update docs and tests

Project.toml

@@ -1,9 +1,10 @@
 name = "ParameterSpacePartitions"
 uuid = "64931d76-8770-46b0-8423-0a5d3a7d2d72"
 authors = ["itsdfish"]
-version = "0.3.5"
+version = "0.3.7"
 
 [deps]
+ComponentArrays = "b0b7db55-cfe3-40fc-9ded-d10e2dbeff66"
 ConcreteStructs = "2569d6c7-a4a2-43d3-a901-331e8e4be471"
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
@@ -17,6 +18,7 @@ SpecialFunctions = "276daf66-3868-5448-9aa4-cd146d93841b"
 ThreadedIterables = "11d239b0-c0b9-11e8-1935-d5cfa53abb03"
 
 [compat]
+ComponentArrays = "0.11.9"
 ConcreteStructs = "v0.2.3"
 DataFrames = "1.3.0"
 Distributions = "0.23.0,0.24.0,v0.25.37"

src/ParameterSpacePartitions.jl

@@ -1,6 +1,6 @@
 module ParameterSpacePartitions
     using Requires, Distributions, ConcreteStructs, LinearAlgebra
-    using ThreadedIterables, SpecialFunctions 
+    using ThreadedIterables, SpecialFunctions, ComponentArrays 
 
     export find_partitions,
         adapt!,

src/volume.jl

@@ -7,19 +7,26 @@ volume_hypersphere(n, r=1) = π^(n / 2) / gamma(1 + n / 2) * r^n
 Computes the log volume of a hypersphere
 
 # Arguments
+
 - `n`: the number of dimensions
+
+# Keywords
+
 - `r=1`: the radius
 """
 log_vol_hypersphere(n; r=1) = (n / 2) * log(π) - loggamma(1 + n / 2) + n * log(r)
 
 """
-    log_vol_ellipsiod(n, r=1)
+    log_vol_ellipsiod(n, cov_mat; r = 1)
 
-Computes the log volume of a hypersphere
+Computes the log volume of a ellipsoid
 
 # Arguments
 - `n`: the number of dimensions
 - `cov_mat`: covariance matrix
+
+# Keywords
+
 - `r=1`: the radius
 """
 function log_vol_ellipsiod(n, cov_mat; r = 1)
@@ -29,13 +36,16 @@ function log_vol_ellipsiod(n, cov_mat; r = 1)
 end
 
 """
-    volume_ellipsoid(n, cov_mat, r=1)   
+    volume_ellipsoid(n, cov_mat; r=1)   
 
 Computes the volume of an ellipsoid
 
 # Arguments
 - `n`: the number of dimensions
 - `cov_mat`: covariance matrix
+
+# Keywords
+
 - `r=1`: the radius
 """
 function volume_ellipsoid(n, cov_mat; r = 1)
@@ -63,7 +73,7 @@ function sample_ellipsoid(μ, n_dims, cov_mat)
 end
 
 """
-    sample_ellipsoid_surface(μ, n_dims, cov_mat)
+    sample_ellipsoid_surface(μ, n_dims, cov_mat; r=1)
 
 Samples a point uniformly from the surface of an ellipsoid 
 
@@ -72,18 +82,44 @@ Samples a point uniformly from the surface of an ellipsoid
 - `μ`: mean of ellipsoid on each dimension  
 - `n_dims`: the number of dimensions 
 - `cov_mat`: covariance matrix
+
+# Keywords
+
 - `r=1`: radius of underlying unit hypersphere 
 """
-function sample_ellipsoid_surface(μ, n_dims, cov_mat, r=1)
+function sample_ellipsoid_surface(μ, n_dims, cov_mat; r=1)
     x = random_position(r, n_dims)
     return μ .+ sqrt((n_dims + 2) * cov_mat) * x
 end
 
 """
-    bias_correction(model, p_fun, points, target, bounds, n_sim, args...; kwargs...)
+    bias_correction(
+        model,
+        p_fun, 
+        points, 
+        target, 
+        bounds, 
+        args...; 
+        parm_names = Symbol.("p", 1:size(points,2)),
+        n_sim=10_000, 
+        kwargs...
+    )
 
 Uses the hit or miss technique to adjust volume estimates based on ellipsoids. 
 
+# Arguments 
+
+- `model`: a model function that returns predictions given a vector of parameters 
+- `p_fun`: a function that that evaluates the qualitative data pattern 
+- `points`: a p x n matrix of sampled points where p is the number of parameters and n is the number of samples
+- `bounds`: a vector of tuples representing (lowerbound, upperbound) for each dimension in 
+- `args...`: arguments passed to `model` and `p_fun`
+
+# Keywords
+
+- `parm_names`: parameter names with default `p1`, `p2,`... `pn`
+- `n_sim=10_000`: number of simulations for hit or miss adjustment 
+- `kwargs...`: optional keyword arguments for `model` and `p_fun`
 """
 function bias_correction(
     model,
@@ -92,11 +128,13 @@ function bias_correction(
     target, 
     bounds, 
     args...; 
+    parm_names = Symbol.("p", 1:size(points,2)),
     n_sim=10_000, 
     kwargs...
     )
 
-    μ = mean(points, dims=1)[:]
+    _μ = mean(points, dims=1)[:]
+    μ = ComponentArray(_μ, make_axis(parm_names))
     cov_mat = cov(points)
     n = length(μ)
 
@@ -155,6 +193,7 @@ function estimate_volume(
     bounds,  
     args...;
     n_sim = 10_000,
+    parm_names = Symbol.("p", 1:size(points,2)),
     kwargs...
     )
 
@@ -166,11 +205,14 @@ function estimate_volume(
         bounds, 
         args...;
         n_sim,
+        parm_names,
         kwargs...
     )
 
     cov_mat = cov(points)
     volume = volume_ellipsoid(cov_mat)
     volume *= cf
     return volume
-end
+end
+
+make_axis(symbols) = Axis(NamedTuple(symbols .=> eachindex(symbols)))

src/volume_df.jl

@@ -1,5 +1,34 @@
 using DataFrames
 
+"""
+    estimate_volume(
+        model, 
+        p_fun, 
+        df::SubDataFrame, 
+        bounds,  
+        args...;
+        n_sim = 10_000,
+        parm_names,
+        kwargs...
+    )
+    
+
+Estimate volume of region with an eillipsoid and hit or miss bias adjustment. 
+
+# Arguments
+- `model`: a model function that returns predictions given a vector of parameters 
+- `p_fun`: a function that that evaluates the qualitative data pattern 
+- `df::SubDataFrame`: a SubDataFrame containing MCMC samples in columns identities by `parm_names`
+    and column containing data patterns named `pattern`
+- `bounds`: a vector of tuples representing (lowerbound, upperbound) for each dimension in 
+- `args...`: arguments passed to `model` and `p_fun`
+
+# Keywords 
+
+- `n_sim=10_000`: the number of samples for hit or miss bias adjustment 
+- `parm_names`: a vector of symbols representing parameter columns in `df`
+- `kwargs...`: additional keyword arguments passed to `model` or `p_fun`
+"""
 function estimate_volume(
     model, 
     p_fun, 
@@ -19,8 +48,9 @@ function estimate_volume(
         p_fun, 
         points, 
         target, 
-        bounds,  
+        bounds, 
         args...;
+        parm_names,
         n_sim,
         kwargs...
     )