Merge pull request #22 from JuliaAI/dev

For a 0.1.2 release

Author: EssamWisam

.github/workflows/CI.yml

@@ -19,7 +19,7 @@ jobs:
       fail-fast: false
       matrix:
         version:
-          - '1.7'
+          - '1.6'
           - '1'
 
         os: [ubuntu-latest, windows-latest, macOS-latest]

Project.toml

@@ -17,7 +17,7 @@ OrderedCollections = "1.6"
 MLJModelInterface = "1.9"
 MLUtils = "0.4"
 StatsBase = "0.34"
-julia = "1.7"
+julia = "1.6"
 
 [extras]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"

src/MLJBalancing.jl

@@ -5,7 +5,7 @@ using MLJModelInterface
 using MLUtils
 using OrderedCollections
 using Random
-using Random: AbstractRNG, Xoshiro, rand
+using Random: AbstractRNG, rand
 using StatsBase: sample
 
 MMI = MLJModelInterface

src/balanced_bagging.jl

@@ -79,20 +79,34 @@ mutable struct BalancedBaggingClassifier{RI<:Union{AbstractRNG, Integer},I<:Inte
     rng::RI
 end
 
-rng_handler(rng::Integer) = Random.Xoshiro(rng)
+# To support Julia 1.6 which does not have Xoshiro
+XoshiroOrMT(rng::Integer) = (VERSION < v"1.7") ? Random.MersenneTwister(rng) : Random.Xoshiro(rng)
+rng_handler(rng::Integer) = XoshiroOrMT(rng)
 rng_handler(rng::AbstractRNG) = rng
+
 const ERR_MISSING_CLF = "No model specified. Please specify a probabilistic classifier using the `model` keyword argument."
 const ERR_BAD_T = "The number of ensemble models `T` cannot be negative."
 const INFO_DEF_T(T_def) = "The number of ensemble models was not given and was thus, automatically set to $T_def"*
                           " which is the ratio of the frequency of the majority class to that of the minority class"
-function BalancedBaggingClassifier(;
+const ERR_NUM_ARGS_BB = "`BalancedBaggingClassifier` can at most have one non-keyword argument where the model is passed."                
+const WRN_MODEL_GIVEN = "Ignoring keyword argument `model=...` as model already given as positional argument. "
+
+function BalancedBaggingClassifier(args...;
     model = nothing,
     T = 0,
     rng = Random.default_rng(),
 )
-    model === nothing && error(ERR_MISSING_CLF)
-    T < 0 && error(ERR_BAD_T)
-    rng = rng_handler(rng)
+    length(args) <= 1 || throw(ERR_NUM_ARGS_BB)
+    if length(args) === 1
+        atom = first(args)
+        model === nothing ||
+            @warn WRN_MODEL_GIVEN
+        model = atom
+    else
+        model === nothing && throw(ERR_MISSING_CLF)
+    end
+    T < 0 && error(ERR_BAD_T)      
+    rng = rng_handler(rng)    
     return BalancedBaggingClassifier(model, T, rng)
 end
 
@@ -208,8 +222,8 @@ Train the machine with `fit!(mach, rows=...)`.
 - `T::Integer=0`: The number of bags to be used in the ensemble. If not given, will be set as
     the ratio between the frequency of the majority and minority classes. Can be later found in `report(mach)`.
 
-- `rng::Union{AbstractRNG, Integer}=default_rng()`: Either an `AbstractRNG` object or an `Integer`
-seed to be used with `Xoshiro`
+- `rng::Union{AbstractRNG, Integer}=default_rng()`: Either an `AbstractRNG` object or an `Integer` 
+    seed to be used with `Xoshiro` if Julia `VERSION>=1.7`. Otherwise, uses MersenneTwister`.
 
 # Operations
 

src/balanced_model.jl

@@ -55,33 +55,78 @@ const UNION_MODEL_TYPES = Union{keys(MODELTYPE_TO_COMPOSITETYPE_EVAL)...}
 
 
 # Possible Errors (for the constructor as well)
-const ERR_MODEL_UNSPECIFIED = ArgumentError("Expected an atomic model as argument. None specified. ")
+const ERR_MODEL_UNSPECIFIED = ErrorException("Expected an atomic model as argument. None specified. ")
 
 const WRN_BALANCER_UNSPECIFIED = "No balancer was provided. Data will be directly passed to the model. "
 
 const PRETTY_SUPPORTED_MODEL_TYPES = join([string("`", opt, "`") for opt in SUPPORTED_MODEL_TYPES], ", ",", and ")
 
-const ERR_UNSUPPORTED_MODEL(model) = ArgumentError(
+const ERR_UNSUPPORTED_MODEL(model) = ErrorException(
     "Only these model supertypes support wrapping: "*
     "$PRETTY_SUPPORTED_MODEL_TYPES.\n"*
     "Model provided has type `$(typeof(model))`. "
 )
+const ERR_NUM_ARGS_BM = "`BalancedModel` can at most have one non-keyword argument where the model is passed."                
 
 
 """
-    BalancedModel(; balancers=[], model=nothing)
+    BalancedModel(; model=nothing, balancer1=balancer_model1, balancer2=balancer_model2, ...)
+    BalancedModel(model;  balancer1=balancer_model1, balancer2=balancer_model2, ...)
 
-Wraps a classification model with balancers that resample the data before passing it to the model.
+Given a classification model, and one or more balancer models that all implement the `MLJModelInterface`,
+    `BalancedModel` allows constructing a sequential pipeline that wraps an arbitrary number of balancing models 
+    and a classifier together in a sequential pipeline.
 
-# Arguments
-- `balancers::AbstractVector=[]`: A vector of balancers (i.e., resampling models). 
-    Data passed to the model will be first passed to the balancers sequentially.
-- `model=nothing`: The classification model which must be provided.
+# Operation
+- During training, data is first passed to `balancer1` and the result is passed to `balancer2` and so on, the result from the final balancer
+    is then passed to the classifier for training.
+- During prediction, the balancers have no effect.
 
+# Arguments
+- `model::Supervised`: A classification model that implements the `MLJModelInterface`. 
+- `balancer1::Static=...`: The first balancer model to pass the data to. This keyword argument can have any name.
+- `balancer2::Static=...`: The second balancer model to pass the data to. This keyword argument can have any name.
+- and so on for an arbitrary number of balancers.
+
+# Returns
+- An instance of type ProbabilisticBalancedModel or DeterministicBalancedModel, depending on the prediction type of model.
+
+# Example
+```julia
+using MLJ
+using Imbalance
+
+# generate data
+X, y = Imbalance.generate_imbalanced_data(1000, 5; class_probs=[0.2, 0.3, 0.5])
+
+# prepare classification and balancing models
+SMOTENC = @load SMOTENC pkg=Imbalance verbosity=0
+TomekUndersampler = @load TomekUndersampler pkg=Imbalance verbosity=0
+LogisticClassifier = @load LogisticClassifier pkg=MLJLinearModels verbosity=0
+
+oversampler = SMOTENC(k=5, ratios=1.0, rng=42)
+undersampler = TomekUndersampler(min_ratios=0.5, rng=42)
+logistic_model = LogisticClassifier()
+
+# wrap them in a BalancedModel
+balanced_model = BalancedModel(model=logistic_model, balancer1=oversampler, balancer2=undersampler)
+
+# now this behaves as a unified model that can be trained, validated, fine-tuned, etc.
+mach = machine(balanced_model, X, y)
+fit!(mach)
+```
 """
-function BalancedModel(; model=nothing, named_balancers...)
+function BalancedModel(args...; model=nothing, named_balancers...)
     # check model and balancer are given
-    model === nothing && throw(ERR_MODEL_UNSPECIFIED)
+    length(args) <= 1 || throw(ERR_NUM_ARGS_BM)
+    if length(args) === 1
+        atom = first(args)
+        model === nothing ||
+            @warn WRN_MODEL_GIVEN
+        model = atom
+    else
+        model === nothing && throw(ERR_MODEL_UNSPECIFIED)
+    end
     # check model is supported
     model isa UNION_MODEL_TYPES  || throw(ERR_UNSUPPORTED_MODEL(model))
 
@@ -116,6 +161,7 @@ for model_type in SUPPORTED_MODEL_TYPES
     eval(ex)
 end
 
+
 const ERR_NO_PROP = ArgumentError("trying to access property $name which does not exist")
 # overload set property to set the property from the vector in the struct
 for model_type in SUPPORTED_MODEL_TYPES

test/balanced_bagging.jl

@@ -1,7 +1,7 @@
 
 @testset "group_inds and get_majority_minority_inds_counts" begin
     y = [0, 0, 0, 0, 1, 1, 1, 0]
-    @test MLJBalancing.group_inds(y) == Dict(0 => [1, 2, 3, 4, 8], 1 => [5, 6, 7])
+    @test MLJBalancing.group_inds(y) == Dict(0 => [1, 2, 3, 4, 8], 1 => [5, 6,  7])
     @test MLJBalancing.get_majority_minority_inds_counts(y) ==
           ([1, 2, 3, 4, 8], [5, 6, 7], 5, 3)
     y = [0, 0, 0, 0, 1, 1, 1, 0, 2, 2, 2]
@@ -18,7 +18,7 @@ end
         num_vals_per_category = [3, 2, 1, 2],
         class_probs = [0.9, 0.1],
         type = "ColTable",
-        rng = 42,
+        rng = Random.MersenneTwister(42),
     )
     majority_inds, minority_inds, majority_count, minority_count =
         MLJBalancing.get_majority_minority_inds_counts(y)
@@ -30,7 +30,7 @@ end
         minority_inds,
         majority_count,
         minority_count,
-        Random.Xoshiro(42)
+        Random.MersenneTwister(42)
     )
     X_sub, y_sub = X_sub(rows = 1:100), y_sub(rows = 1:100)
     majority_inds_sub, minority_inds_sub, _, _ =
@@ -51,7 +51,7 @@ end
 
 @testset "End-to-end Test" begin
     ## setup parameters
-    R = Random.Xoshiro(42)
+    R = Random.MersenneTwister(42)
     T = 2
     LogisticClassifier = @load LogisticClassifier pkg = MLJLinearModels verbosity = 0
     model = LogisticClassifier()
@@ -64,7 +64,7 @@ end
         num_vals_per_category = [3, 2, 1, 2],
         class_probs = [0.9, 0.1],
         type = "ColTable",
-        rng = 42,
+        rng = Random.MersenneTwister(42),
     )
     # testing
     Xt, yt = generate_imbalanced_data(
@@ -73,7 +73,7 @@ end
         num_vals_per_category = [3, 2, 1, 2],
         class_probs = [0.9, 0.1],
         type = "ColTable",
-        rng = 42,
+        rng = Random.MersenneTwister(42),
     )
 
     ## prepare subsets
@@ -111,14 +111,30 @@ end
     pred_manual = mean([pred1, pred2])
 
     ## using BalancedBagging
-    modelo = BalancedBaggingClassifier(model = model, T = 2, rng = Random.Xoshiro(42))
+    modelo = BalancedBaggingClassifier(model = model, T = 2, rng = Random.MersenneTwister(42))
     mach = machine(modelo, X, y)
     fit!(mach)
     pred_auto = MLJBase.predict(mach, Xt)
     @test sum(pred_manual) ≈ sum(pred_auto)
-    modelo = BalancedBaggingClassifier(model = model, rng = Random.Xoshiro(42))
+    modelo = BalancedBaggingClassifier(model = model, rng = Random.MersenneTwister(42))
     mach = machine(modelo, X, y)
     fit!(mach)
-    @test report(mach) == (chosen_T = 5,)
-
+    @test report(mach) == (chosen_T = 9,)
 end
+
+
+
+
+@testset "Equivalence of Constructions" begin
+    ## setup parameters
+    R = Random.MersenneTwister(42)
+    T = 2
+    LogisticClassifier = @load LogisticClassifier pkg = MLJLinearModels verbosity = 0
+    model = LogisticClassifier()
+    BalancedBaggingClassifier(model=model, T=T, rng=R) == BalancedBaggingClassifier(model; T=T, rng=R)
+
+    @test_throws MLJBalancing.ERR_NUM_ARGS_BB BalancedBaggingClassifier(model, model; T=T, rng=R)
+    @test_logs (:warn, MLJBalancing.WRN_MODEL_GIVEN) begin
+        BalancedBaggingClassifier(model; model=model, T=T, rng=R)
+    end
+end

test/balanced_model.jl

@@ -1,10 +1,10 @@
 @testset "BalancedModel" begin
 	### end-to-end test
 	# Create and split data
-	X, y = generate_imbalanced_data(100, 5; class_probs = [0.2, 0.3, 0.5])
+	X, y = generate_imbalanced_data(100, 5; class_probs = [0.2, 0.3, 0.5], rng=Random.MersenneTwister(42))
 	X = DataFrame(X)
 	train_inds, test_inds =
-		partition(eachindex(y), 0.8, shuffle = true, stratify = y, rng = Random.Xoshiro(42))
+		partition(eachindex(y), 0.8, shuffle = true, stratify = y, rng = Random.MersenneTwister(42))
 	X_train, X_test = X[train_inds, :], X[test_inds, :]
 	y_train, y_test = y[train_inds], y[test_inds]
 
@@ -18,9 +18,9 @@
 	# And here are three resamplers from Imbalance. 
 	# The package should actually work with any `Static` transformer of the form  `(X, y) -> (Xout, yout)`
 	# provided that it implements the MLJ interface. Here, the balancer is the transformer
-	balancer1 = Imbalance.MLJ.RandomOversampler(ratios = 1.0, rng = 42)
-	balancer2 = Imbalance.MLJ.SMOTENC(k = 10, ratios = 1.2, rng = 42)
-	balancer3 = Imbalance.MLJ.ROSE(ratios = 1.3, rng = 42)
+	balancer1 = Imbalance.MLJ.RandomOversampler(ratios = 1.0, rng = Random.MersenneTwister(42))
+	balancer2 = Imbalance.MLJ.SMOTENC(k = 10, ratios = 1.2, rng = Random.MersenneTwister(42))
+	balancer3 = Imbalance.MLJ.ROSE(ratios = 1.3, rng = Random.MersenneTwister(42))
 
 	### 1. Make a pipeline of the three balancers and a probablistic model
 	## ordinary way
@@ -35,8 +35,8 @@
 	fit!(mach)
 	y_pred = MLJBase.predict(mach, X_test)
 
-	# with MLJ balancing
-	@test_throws MLJBalancing.ERR_MODEL_UNSPECIFIED begin
+	# with MLJ balancing 
+	@test_throws  MLJBalancing.ERR_MODEL_UNSPECIFIED begin
 		BalancedModel(b1 = balancer1, b2 = balancer2, b3 = balancer3)
 	end
     @test_throws(
@@ -46,7 +46,6 @@
 	@test_logs (:warn, MLJBalancing.WRN_BALANCER_UNSPECIFIED) begin
 		BalancedModel(model = model_prob)
 	end
-
 	balanced_model =
 		BalancedModel(model = model_prob, b1 = balancer1, b2 = balancer2, b3 = balancer3)
 	mach = machine(balanced_model, X_train, y_train)
@@ -86,3 +85,18 @@
 	Base.setproperty!(balanced_model, :name11, balancer2),
     )
 end
+
+
+@testset "Equivalence of Constructions" begin
+    ## setup parameters
+    R = Random.MersenneTwister(42)
+    LogisticClassifier = @load LogisticClassifier pkg = MLJLinearModels verbosity = 0
+	balancer1 = Imbalance.MLJ.RandomOversampler(ratios = 1.0, rng = Random.MersenneTwister(42))
+    model = LogisticClassifier()
+    BalancedModel(model=model, balancer1=balancer1) == BalancedModel(model; balancer1=balancer1)
+
+    @test_throws MLJBalancing.ERR_NUM_ARGS_BM BalancedModel(model, model; balancer1=balancer1)
+    @test_logs (:warn, MLJBalancing.WRN_MODEL_GIVEN) begin
+        BalancedModel(model; model=model, balancer1=balancer1)
+    end
+end