update docs

Author: itsdfish

Examples/Delay_Discounting/Run_Delay_Discounting.jl

@@ -12,7 +12,7 @@ include("Delay_Discounting.jl")
 #######################################################################################
 #                                  Define Model
 #######################################################################################
-Random.seed!(1204)
+Random.seed!(12034)
 prior = [Uniform(-5, 5), Uniform(-5, 50)]
 
 model = Model(;prior, loglike)

Examples/Monetary_Gambles/Run_Monetary_Gamble.jl

@@ -9,10 +9,10 @@ using Pkg
 Pkg.activate("../../")
 using AdaptiveDesignOptimization, Random, UtilityModels, Distributions
 include("TAX_Model.jl")
+Random.seed!(25974)
 #######################################################################################
-#                                  Define Model
+#                                  Define Parameters
 #######################################################################################
-Random.seed!(25974)
 
 # model with default uniform prior
 model = Model(;loglike)
@@ -34,7 +34,7 @@ design_list = (design_names,design_vals[1:100])
 
 data_list = (choice=[true, false],)
 #######################################################################################
-#                              Simulate Experiment
+#                              Optimize Experiment
 #######################################################################################
 using DataFrames
 true_parms = (δ=-1.0, β=1.0, γ=.7, θ=1.5)

Examples/Monetary_Gambles/TAX_Model.jl

@@ -1,10 +1,26 @@
+"""
+*loglike*
+
+Computes the log likelihood for the TAX model.
+* `δ`: transfer of attention parameter 
+* `γ`: probability weighting parameter
+* `β`: utility curvature parameter 
+* `θ`: decision consistency parameter 
+* `pa`: outcome probabilities for gamble a
+* `va`: outcome values for gamble a
+* `pb`: outcome probabilities for gamble b
+* `vb`: outcome values for gamble b
+
+Function Signature 
+```julia
+loglike(δ, β, γ, θ, pa, va, pb, vb, data)
+```
+"""
 function loglike(δ, β, γ, θ, pa, va, pb, vb, data)
     eua,eub = expected_utilities(δ, β, γ, θ, pa, va, pb, vb)
     p = choice_prob(eua, eub, θ)
-    p = p == 1 ? 1 - eps() : p
-    p = p == 0 ? eps() : p
-    LL = data ? log(p) : log(1 - p)
-    return LL
+    p = max(p, eps())
+    return logpdf(Bernoulli(p), data)
 end
 
 function choice_prob(eua, eub, θ)

README.md

@@ -1 +1,84 @@
 # AdaptiveDesignOptimization
+
+This package is a grid-based approach for performing Bayesian adaptive design optimization. After each observation, the optimizer chooses an experimental design that maximizes mutual information between model parameters and design parameters. In so doing, the optimizer selects designs that minimize the variance in the posterior distribution of model parameters.
+# Example
+
+In this example, we will optimize a decision making experiment for the model called Transfer of Attention Exchange (TAX; Birnbaum, 2008). Additional examples can be found in the folder titled Examples. sds
+
+```julia 
+using AdaptiveDesignOptimization, Random, UtilityModels, Distributions
+include("TAX_Model.jl")
+Random.seed!(25974)
+```
+
+## Define Model
+
+The model object contains a log likelihood function and optional prior distributions. Unless an array of distribution objects is passed as `prior`, uniform distributions will be used by default. Arguments in the log likelihood function must be ordered as follows:
+
+- loglike(model_parameters..., design_parameters..., data..., args...; kwargs...)
+
+`args...` and `kwargs...` are optional arguments that may be preloaded through the `Model` constructor. Enter 
+
+```julia 
+? Model
+``` 
+for additional details. The likelihood function for the TAX model (see `TAX_Model.jl`) is defined as:
+
+```julia
+function loglike(δ, β, γ, θ, pa, va, pb, vb, data)
+    eua,eub = expected_utilities(δ, β, γ, θ, pa, va, pb, vb)
+    p = choice_prob(eua, eub, θ)
+    p = max(p, eps())
+    return logpdf(Bernoulli(p), data)
+end
+```
+
+The model object is contructed with default uniform prior distributions. 
+
+```julia 
+# model with default uniform prior
+model = Model(;loglike)
+```
+## Define Parameters
+
+Define a `NamedTuple` of parameter value ranges. Note that the parameters listed in the same order that they appear in `loglike`.
+
+```julia
+parm_list = (
+    δ = range(-2, 2, length=10),
+    β = range(.5, 1.5, length=10),
+    γ = range(.5, 1.2, length=10),
+    θ = range(.5, 3, length=10)
+)
+```
+
+The experiment will consist of two gambles with three outcomes each. The number of dimensions in the design space is large (2X2X3X3 = 36). In this case, we will sample random gambles and select a subset of 100 with high distributional overlap. In this case, the `design_list` will be a `Tuple` of design names and design values. 
+
+```julia
+# outcome distribution
+dist = Normal(0,10)
+n_vals = 3
+n_choices = 2
+design_vals = map(x->random_design(dist, n_vals, n_choices), 1:1000)
+# select gambles with overlapping distributions
+filter!(x->abs_zscore(x) ≤ .4, design_vals)
+design_names = (:p1,:v1,:p2,:v2)
+design_list = (design_names,design_vals[1:100])
+```
+
+Lastly, we will define a list for the data. The value true indicates gamble A was choosen and false indicates gamble B was chosen.
+
+```julia 
+data_list = (choice=[true, false],)
+```
+## Optimize Exeriment
+
+
+# References
+
+* Birnbaum, M. H., & Chavez, A. (1997). Tests of theories of decision making: Violations of branch independence and distribution   independence. Organizational Behavior and human decision Processes, 71(2), 161-194. Birnbaum, M. H. (2008). New paradoxes of risky decision making. Psychological review, 115(2), 463.
+
+* Myung, J. I., Cavagnaro, D. R., and Pitt, M. A. (2013). A tutorial on adaptive design optimization. Journal of Mathematical Psychology, 57, 53–67.
+
+* Yang, J., Pitt, M. A., Ahn, W., & Myung, J. I. (2020). ADOpy: A Python Package for Adaptive Design Optimization. Behavior Research Methods, 1--24. https://doi.org/10.3758/s13428-020-01386-4
+

src/functions.jl

@@ -56,7 +56,8 @@ function loglikelihood!(loglike, log_like, design_grid, parm_grid, data_grid, mo
         for (k,design) in enumerate(design_grid)
             for (p,parms) in enumerate(parm_grid)
                 i += 1
-                log_like[p,k,d] = loglike(parms..., design..., data..., model_state[i]) 
+                state = deepcopy(model_state[i])
+                log_like[p,k,d] = loglike(parms..., design..., data..., state) 
             end
         end
     end
@@ -168,6 +169,14 @@ function update!(optimizer::Optimizer{A,MT}, data, args...; kwargs...) where {A,
     return best_design
 end
 
+function update!(optimizer::Optimizer{A,MT}, data, args...; kwargs...) where {A<:Rand,MT<:Dyn}
+    update_posterior!(optimizer, data)
+    update_states!(optimizer, data, args...; kwargs...)
+    loglikelihood!(optimizer)
+    best_design = find_best_design!(optimizer)
+    return best_design
+end
+
 function update!(optimizer::Optimizer{A}, data) where {A<:Rand}
     update_posterior!(optimizer, data)
     best_design = find_best_design!(optimizer)
@@ -176,10 +185,12 @@ end
 
 function update_states!(optimizer, obs_data, args...; kwargs...)
     @unpack model_state, data_grid, design_grid, parm_grid, update_state! = optimizer
-    for (d, data) in enumerate(data_grid)
-        for (k,design) in enumerate(design_grid)
-            for (p,parms) in enumerate(parm_grid)
-                update_state!(model_state, parms, design, data, obs_data, args...; kwargs...)
+    i = 0
+    for data in data_grid
+        for design in design_grid
+            for parms in parm_grid
+                i += 1
+                update_state!(model_state[i], parms, design, data, obs_data, args...; kwargs...)
             end
         end
     end
@@ -238,6 +249,4 @@ end
 
 function create_state(model_type::Stat, T, dims, args...; kwargs...)
     return nothing
-end
-
-
+end

src/structs.jl

@@ -34,6 +34,22 @@ Constructor
 ````julia 
 Model(args...; prior=nothing, loglike, kwargs...)
 ````
+*Examples*
+
+```julia
+# Default uninform prior
+loglike(θ, design, data) = ...
+
+model = Model(;loglike)
+```
+
+```julia
+# Custom priors
+prior = [Beta(5,5),...]
+loglike(θ, design, data) = ...
+
+model = Model(;loglike, prior)
+```
 """
 mutable struct Model{F<:Function,P}
     prior::P
@@ -66,44 +82,6 @@ Constructor
 Optimizer(;task, model, grid_design, grid_parms, grid_response)
 ````
 # """
-# mutable struct Optimizer{A,M<:Model,T1,T2,T3,T4,T5,T6,T7,T8,T9}
-#     approach::A
-#     model::M
-#     design_grid::T1
-#     parm_grid::T2
-#     data_grid::T3
-#     log_like::Array{Float64,3}
-#     marg_log_like::T4
-#     priors::T5
-#     log_post::Vector{Float64}
-#     entropy::T6
-#     marg_entropy::Vector{Float64}
-#     cond_entropy::Vector{Float64}
-#     mutual_info::Vector{Float64}
-#     best_design::T7
-#     parm_names::T8
-#     design_names::T9
-# end
-
-# function Optimizer(; model, design_list, parm_list, data_list, approach=Optimize)
-#     design_names,design_grid = to_grid(design_list)
-#     parm_names,parm_grid = to_grid(parm_list)
-#     _,data_grid = to_grid(data_list)
-#     log_like = loglikelihood(model, design_grid, parm_grid, data_grid)
-#     priors = prior_probs(model, parm_grid)
-#     post = priors[:]
-#     log_post = log.(post)
-#     entropy = compute_entropy(log_like)
-#     marg_log_like = marginal_log_like(log_post, log_like)
-#     marg_entropy = marginal_entropy(marg_log_like)
-#     cond_entropy = conditional_entropy(entropy, post)
-#     mutual_info = mutual_information(marg_entropy, cond_entropy)
-#     best_design = find_best_design(mutual_info, design_grid, design_names)
-#     return Optimizer(approach, model, design_grid, parm_grid, data_grid, log_like,
-#         marg_log_like, priors, log_post, entropy, marg_entropy, cond_entropy, 
-#         mutual_info, best_design, parm_names, design_names)
-# end
-
 mutable struct Optimizer{A,MT,M<:Model,T1,T2,T3,T4,T5,T6,T7,T8,T9,
     T10,T11}
     design_type::A