Simplify Imputor API

docs/make.jl

@@ -6,7 +6,6 @@ makedocs(
     pages=[
         "Home" => "index.md",
         "Impute" => "api/impute.md",
-        "Context" => "api/context.md",
         "Imputors" => "api/imputors.md",
         "Utilities" => "api/utils.md",
     ],

src/Impute.jl

@@ -16,6 +16,20 @@ using LinearAlgebra: Diagonal
 
 import Base.Iterators: drop
 
+#=
+TODO List:
+- [X] Drop Context
+- [X] Introduce a separate Threshold type and `assert` function
+- [X] Update old tests cases to use new type
+- [ ] Add deprecations for old `context` calls
+- [ ] Generalize the dimensionality behaviour using a `dims` keyword similar to the stats functions
+  https://github.com/JuliaLang/Statistics.jl/blob/master/src/Statistics.jl#L164
+- [ ] Drop in-place calls
+- [ ] Base imputors should dispatch on `impute(AbstractArray{Union{T, Missing}}, imp)`
+- [ ] Replace `dropobs` and `dropvars` with `Impute.drop` and a `dims` keyword
+- [ ] Make `Chain` not an imputor and have it work on `Assertions` and `Imputors`
+- [ ] Add function for checking if a methods support some input data?
+=#
 """
     ImputeError{T} <: Exception
 
@@ -30,14 +44,15 @@ end
 
 Base.showerror(io::IO, err::ImputeError) = println(io, "ImputeError: $(err.msg)")
 
-include("context.jl")
+include("utils.jl")
+include("assertions.jl")
 include("imputors.jl")
 
 #=
 These default methods are required because @auto_hash_equals doesn't
 play nice with Base.@kwdef
 =#
-function Base.hash(imp::T, h::UInt) where T <: Union{Imputor, AbstractContext}
+function Base.hash(imp::T, h::UInt) where T <: Imputor
     h = hash(Symbol(T), h)
 
     for f in fieldnames(T)
@@ -47,7 +62,7 @@ function Base.hash(imp::T, h::UInt) where T <: Union{Imputor, AbstractContext}
     return h
 end
 
-function Base.:(==)(a::T, b::T) where T <: Union{Imputor, AbstractContext}
+function Base.:(==)(a::T, b::T) where T <: Imputor
     result = true
 
     for f in fieldnames(T)
@@ -89,14 +104,14 @@ for (f, v) in pairs(imputation_methods)
 end
 
 @doc """
-    Impute.dropobs(data; dims=1, context=Context())
+    Impute.dropobs(data; dims=1)
 
 Removes missing observations from the `AbstractArray` or `Tables.table` provided.
 See [DropObs](@ref) for details.
 
 # Example
 ```
-julia> using DataFrames; using Impute: Impute, Context
+julia> using DataFrames; using Impute: Impute
 
 julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2, 3.3, missing, 5.5])
 5×2 DataFrames.DataFrame
@@ -109,7 +124,7 @@ julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2,
 │ 4   │ missing  │ missing  │
 │ 5   │ 5.0      │ 5.5      │
 
-julia> Impute.dropobs(df; dims=2, context=Context(; limit=1.0))
+julia> Impute.dropobs(df; dims=2)
 3×2 DataFrames.DataFrame
 │ Row │ a       │ b       │
 │     │ Float64 │ Float64 │
@@ -121,14 +136,14 @@ julia> Impute.dropobs(df; dims=2, context=Context(; limit=1.0))
 """ dropobs
 
 @doc """
-    Impute.dropvars(data; dims=1, context=Context())
+    Impute.dropvars(data; dims=1)
 
 Finds variables with too many missing values in a `AbstractMatrix` or `Tables.table` and
 removes them from the input data. See [DropVars](@ref) for details.
 
 # Example
 ```jldoctest
-julia> using DataFrames; using Impute: Impute, Context
+julia> using DataFrames; using Impute: Impute
 
 julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2, 3.3, missing, 5.5])
 5×2 DataFrames.DataFrame
@@ -141,7 +156,7 @@ julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2,
 │ 4   │ missing  │ missing  │
 │ 5   │ 5.0      │ 5.5      │
 
-julia> Impute.dropvars(df; context=Context(; limit=0.2))
+julia> Impute.dropvars(df)
 5×1 DataFrames.DataFrame
 │ Row │ b        │
 │     │ Float64  │
@@ -155,14 +170,14 @@ julia> Impute.dropvars(df; context=Context(; limit=0.2))
 """ dropvars
 
 @doc """
-    Impute.interp(data; dims=1, context=Context())
+    Impute.interp(data; dims=1)
 
 Performs linear interpolation between the nearest values in an vector.
 See [Interpolate](@ref) for details.
 
 # Example
 ```jldoctest
-julia> using DataFrames; using Impute: Impute, Context
+julia> using DataFrames; using Impute: Impute
 
 julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2, 3.3, missing, 5.5])
 5×2 DataFrames.DataFrame
@@ -175,7 +190,7 @@ julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2,
 │ 4   │ missing  │ missing  │
 │ 5   │ 5.0      │ 5.5      │
 
-julia> Impute.interp(df; context=Context(; limit=1.0))
+julia> Impute.interp(df)
 5×2 DataFrames.DataFrame
 │ Row │ a        │ b        │
 │     │ Float64  │ Float64  │
@@ -189,13 +204,13 @@ julia> Impute.interp(df; context=Context(; limit=1.0))
 """ interp
 
 @doc """
-    Impute.fill(data; value=mean, dims=1, context=Context())
+    Impute.fill(data; value=mean, dims=1)
 
 Fills in the missing data with a specific value. See [Fill](@ref) for details.
 
 # Example
 ```jldoctest
-julia> using DataFrames; using Impute: Impute, Context
+julia> using DataFrames; using Impute: Impute
 
 julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2, 3.3, missing, 5.5])
 5×2 DataFrames.DataFrame
@@ -208,7 +223,7 @@ julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2,
 │ 4   │ missing  │ missing  │
 │ 5   │ 5.0      │ 5.5      │
 
-julia> Impute.fill(df; value=-1.0, context=Context(; limit=1.0))
+julia> Impute.fill(df; value=-1.0)
 5×2 DataFrames.DataFrame
 │ Row │ a        │ b        │
 │     │ Float64  │ Float64  │
@@ -222,14 +237,14 @@ julia> Impute.fill(df; value=-1.0, context=Context(; limit=1.0))
 """ fill
 
 @doc """
-    Impute.locf(data; dims=1, context=Context())
+    Impute.locf(data; dims=1)
 
 Iterates forwards through the `data` and fills missing data with the last existing
 observation. See [LOCF](@ref) for details.
 
 # Example
 ```jldoctest
-julia> using DataFrames; using Impute: Impute, Context
+julia> using DataFrames; using Impute: Impute
 
 julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2, 3.3, missing, 5.5])
 5×2 DataFrames.DataFrame
@@ -242,7 +257,7 @@ julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2,
 │ 4   │ missing  │ missing  │
 │ 5   │ 5.0      │ 5.5      │
 
-julia> Impute.locf(df; context=Context(; limit=1.0))
+julia> Impute.locf(df)
 5×2 DataFrames.DataFrame
 │ Row │ a        │ b        │
 │     │ Float64  │ Float64  │
@@ -256,14 +271,14 @@ julia> Impute.locf(df; context=Context(; limit=1.0))
 """ locf
 
 @doc """
-    Impute.nocb(data; dims=1, context=Context())
+    Impute.nocb(data; dims=1)
 
 Iterates backwards through the `data` and fills missing data with the next existing
 observation. See [LOCF](@ref) for details.
 
 # Example
 ```jldoctest
-julia> using DataFrames; using Impute: Impute, Context
+julia> using DataFrames; using Impute: Impute
 
 julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2, 3.3, missing, 5.5])
 5×2 DataFrames.DataFrame
@@ -276,7 +291,7 @@ julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2,
 │ 4   │ missing  │ missing  │
 │ 5   │ 5.0      │ 5.5      │
 
-julia> Impute.nocb(df; context=Context(; limit=1.0))
+julia> Impute.nocb(df)
 5×2 DataFrames.DataFrame
 │ Row │ a        │ b        │
 │     │ Float64  │ Float64  │
@@ -290,15 +305,15 @@ julia> Impute.nocb(df; context=Context(; limit=1.0))
 """ nocb
 
 @doc """
-    Impute.srs(data; rng=Random.GLOBAL_RNG, context=Context())
+    Impute.srs(data; rng=Random.GLOBAL_RNG)
 
 Simple Random Sampling (SRS) imputation is a method for imputing both continuous and
 categorical variables. Furthermore, it completes imputation while preserving the
 distributional properties of the variables (e.g., mean, standard deviation).
 
 # Example
 ```jldoctest
-julia> using DataFrames; using Random; using Impute: Impute, Context
+julia> using DataFrames; using Random; using Impute: Impute
 
 julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2, 3.3, missing, 5.5])
 5×2 DataFrames.DataFrame
@@ -311,7 +326,7 @@ julia> df = DataFrame(:a => [1.0, 2.0, missing, missing, 5.0], :b => [1.1, 2.2,
 │ 4   │ missing  │ missing  │
 │ 5   │ 5.0      │ 5.5      │
 
-julia> Impute.srs(df; rng=MersenneTwister(1234), context=Context(; limit=1.0))
+julia> Impute.srs(df; rng=MersenneTwister(1234))
 5×2 DataFrame
 │ Row │ a        │ b        │
 │     │ Float64  │ Float64  │

src/assertions.jl

@@ -0,0 +1,41 @@
+"""
+    Assertion
+
+An Assertion stores settings for checking the validity of a `AbstractArray` or `Tables.table` containing missing values.
+New assertions are expected to subtype `Impute.Assertion` and, at minimum,
+implement the `assert(data::AbstractVector{Union{T, Missing}}, ::<MyAssertion>)` method.
+"""
+abstract type Assertion end
+
+
+"""
+    assert(data, a::Assertion; kwargs...)
+
+If the assertion `a` fails then an `AssertionError` is thrown, otherwise the `data`
+provided is returned without mutation.
+
+# Keywords
+* `dims`: The dimension to apply the assertion along (e.g., observations dim)
+"""
+assert
+
+# A couple fallbacks for matrices and tables
+function assert(data::AbstractMatrix, a::Assertion; dims=1)
+    for var in varwise(data; dims=dims)
+        assert(var, a)
+    end
+    return data
+end
+
+function assert(table, a::Assertion)
+    istable(table) || throw(MethodError(a, (table, a)))
+    columntable = Tables.columns(table)
+
+    for cname in propertynames(columntable)
+        assert(getproperty(columntable, cname), a)
+    end
+
+    return table
+end
+
+include("assertions/threshold.jl")

src/assertions/threshold.jl

@@ -0,0 +1,38 @@
+"""
+    Threshold(ratio; weights=nothing)
+
+Assert that the ratio of missing values in the provided dataset does not exceed to specified ratio.
+If a weights array is provided then the ratio will be calculated as the
+`sum(weights[ismissing.(data)]) / sum(weights)`
+"""
+struct Threshold <: Assertion
+    ratio::Float64
+    weights::Union{AbstractVector, Nothing}
+end
+
+Threshold(ratio::Float64; weights=nothing) = Threshold(ratio, weights)
+
+function assert(data::AbstractVector{Union{T, Missing}}, t::Threshold) where T
+    if t.weights === nothing
+        mratio = count(ismissing, data) / length(data)
+        if mratio > t.ratio
+            throw(AssertionError("Ratio of missing values exceeded $(t.ratio) ($mratio)."))
+        end
+    else
+        if size(data) != size(t.weights)
+            throw(DimensionMismatch(string(
+                "Input has dimensions $(size(data)), but thresholds weights ",
+                "has dimensions $(size(t.weights))"
+            )))
+        end
+
+        mratio = sum(t.weights[ismissing.(data)]) / sum(t.weights)
+        if mratio > t.ratio
+            throw(AssertionError(
+                "Weighted ratio of missing values exceeded $(t.ratio) ($mratio)."
+            ))
+        end
+    end
+
+    return data
+end