Additions and refactor

Frankie Robertson · Frankie Robertson · commit cf02e1146ad4 · 2025-06-21T10:46:11.000+03:00
* Add in CatRecorder
 * CatLoopConfig =&gt; CatLoop
 * Move CatLoop into Sim
diff --git a/Project.toml b/Project.toml
@@ -11,6 +11,7 @@ DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
 EffectSizes = "e248de7e-9197-5860-972e-353a2af44d75"
+ElasticArrays = "fdbdab4c-e67f-52f5-8c3f-e7b388dad3d4"
 FillArrays = "1a297f60-69ca-5386-bcde-b61e274b549b"
 FittedItemBanks = "3f797b09-34e4-41d7-acf6-3302ae3248a5"
 ForwardDiff = "f6369f11-7733-5829-9624-2563aa707210"
@@ -47,6 +48,7 @@ DataFrames = "1.6.1"
 Distributions = "^0.25.88"
 DocStringExtensions = " ^0.9"
 EffectSizes = "^1.0.1"
+ElasticArrays = "1.2.12"
 FillArrays = "0.13, 1.5.0"
 FittedItemBanks = "^0.7.2"
 ForwardDiff = "1"
diff --git a/docs/examples/examples/ability_convergence_3pl.jl b/docs/examples/examples/ability_convergence_3pl.jl
@@ -57,7 +57,7 @@ xs = range(-2.5, 2.5, length = points)
 raw_estimator = LikelihoodAbilityEstimator()
 recorder = CatRecorder(xs, responses, integrator, raw_estimator, ability_estimator)
 for testee_idx in axes(responses, 2)
-    tracked_responses, θ = run_cat(CatLoopConfig(rules = rules,
+    tracked_responses, θ = run_cat(CatLoop(rules = rules,
             get_response = auto_responder(@view responses[:, testee_idx]),
             new_response_callback = (tracked_responses, terminating) -> recorder(tracked_responses,
                 testee_idx,
diff --git a/docs/examples/examples/ability_convergence_mirt.jl b/docs/examples/examples/ability_convergence_mirt.jl
@@ -67,7 +67,7 @@ recorder = CatRecorder(xs,
     abilities)
 for testee_idx in axes(responses, 2)
     @debug "Running for testee" testee_idx
-    tracked_responses, θ = run_cat(CatLoopConfig(rules = rules,
+    tracked_responses, θ = run_cat(CatLoop(rules = rules,
             get_response = auto_responder(@view responses[:, testee_idx]),
             new_response_callback = (tracked_responses, terminating) -> recorder(tracked_responses,
                 testee_idx,
diff --git a/docs/examples/examples/vocab_iq.jl b/docs/examples/examples/vocab_iq.jl
@@ -63,7 +63,7 @@ function run_vocab_iq_cat()
         println("Got ability estimate: $ability ± $var")
         println("")
     end
-    loop_config = CatLoopConfig(rules = rules,
+    loop_config = CatLoop(rules = rules,
         get_response = get_response,
         new_response_callback = new_response_callback)
     run_cat(loop_config, item_bank)
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -8,5 +8,5 @@ CurrentModule = ComputerAdaptiveTesting
 ```
 
 ```@autodocs
-Modules = [ComputerAdaptiveTesting, ComputerAdaptiveTesting.Aggregators, ComputerAdaptiveTesting.Responses, ComputerAdaptiveTesting.Sim, ComputerAdaptiveTesting.TerminationConditions, ComputerAdaptiveTesting.NextItemRules, ComputerAdaptiveTesting.CatConfig]
+Modules = [ComputerAdaptiveTesting, ComputerAdaptiveTesting.Aggregators, ComputerAdaptiveTesting.Responses, ComputerAdaptiveTesting.Sim, ComputerAdaptiveTesting.TerminationConditions, ComputerAdaptiveTesting.NextItemRules, ComputerAdaptiveTesting.Rules]
 ```
diff --git a/docs/src/creating_a_cat.md b/docs/src/creating_a_cat.md
@@ -13,7 +13,7 @@ The configuration of a CAT is built up as a tree of configuration structs.
 These structs are all subtypes of `CatConfigBase`.
 
 ```@docs; canonical=false
-ComputerAdaptiveTesting.CatConfig.CatConfigBase
+ComputerAdaptiveTesting.ConfigBase.CatConfigBase
 ```
 
 The constructors for the configuration structs in this package tend to have
@@ -59,7 +59,7 @@ next item selection rule, and the stopping rule. `CatRules` has explicit and
 implicit constructors.
 
 ```@docs; canonical=false
-ComputerAdaptiveTesting.CatConfig.CatRules
+ComputerAdaptiveTesting.CatRules
 ```
 
 ### Next item selection with `NextItemRule`
diff --git a/docs/src/stateful.md b/docs/src/stateful.md
@@ -33,4 +33,4 @@ Stateful.StatefulCatConfig
 
 ## Usage
 
-Just as [CatLoopConfig](@ref) can wrap [CatRules](@ref), you can also use it with any implementor of [Stateful.StatefulCat](@ref), and run using [Sim.run_cat](@ref).
+Just as [CatLoop](@ref) can wrap [CatRules](@ref), you can also use it with any implementor of [Stateful.StatefulCat](@ref), and run using [Sim.run_cat](@ref).
diff --git a/docs/src/using_your_cat.md b/docs/src/using_your_cat.md
@@ -9,10 +9,10 @@ a number of ways you can use it.
 This section covers a few.
 See also the [Examples](@ref demo-page).
 
-When you've set up your CAT using [CatRules](@ref), you can wrap it in a [CatLoopConfig](@ref) and run it with [run_cat](@ref).
+When you've set up your CAT using [CatRules](@ref), you can wrap it in a [CatLoop](@ref) and run it with [run_cat](@ref).
 
 ```@docs; canonical=false
-CatLoopConfig
+CatLoop
 run_cat
 ```
 
diff --git a/src/Compat/CatR.jl b/src/Compat/CatR.jl
@@ -7,7 +7,7 @@ using ComputerAdaptiveTesting.Aggregators: AbilityIntegrator,
                                            MeanAbilityEstimator,
                                            PriorAbilityEstimator
 using ComputerAdaptiveTesting.TerminationConditions: RunForeverTerminationCondition
-using ComputerAdaptiveTesting.CatConfig: CatRules
+using ComputerAdaptiveTesting.Rules: CatRules
 using ComputerAdaptiveTesting.NextItemRules
 using PsychometricsBazaarBase: Integrators, Optimizers
 
diff --git a/src/Compat/MirtCAT.jl b/src/Compat/MirtCAT.jl
@@ -9,8 +9,8 @@ using ComputerAdaptiveTesting.Aggregators: SafeLikelihoodAbilityEstimator,
                                            AbilityEstimator,
                                            distribution_estimator
 using ComputerAdaptiveTesting.TerminationConditions: RunForeverTerminationCondition
-using ComputerAdaptiveTesting.CatConfig: CatRules
 using ComputerAdaptiveTesting.NextItemRules
+using ComputerAdaptiveTesting: CatRules
 using PsychometricsBazaarBase: Integrators, Optimizers
 
 public next_item_aliases, ability_estimator_aliases, assemble_rules
diff --git a/src/ComputerAdaptiveTesting.jl b/src/ComputerAdaptiveTesting.jl
@@ -5,9 +5,9 @@ include("./hacks.jl")
 using Reexport: Reexport, @reexport
 
 # Modules
-export ConfigBase, Responses, Aggregators
+export Responses, Aggregators
 export NextItemRules, TerminationConditions
-export CatConfig, Sim, DecisionTree
+export Sim, DecisionTree
 export Stateful, Comparison
 
 # Extension modules
@@ -33,7 +33,7 @@ include("./next_item_rules/NextItemRules.jl")
 include("./TerminationConditions.jl")
 
 # Combining / running
-include("./CatConfig.jl")
+include("./Rules.jl")
 include("./sim/Sim.jl")
 include("./decision_tree/DecisionTree.jl")
 
@@ -42,8 +42,8 @@ include("./Stateful.jl")
 include("./Compat/Compat.jl")
 include("./Comparison/Comparison.jl")
 
-@reexport using .CatConfig: CatLoopConfig, CatRules
-@reexport using .Sim: run_cat
+@reexport using .Rules: CatRules
+@reexport using .Sim: CatLoop, run_cat
 @reexport using .NextItemRules: preallocate
 
 include("./precompiles.jl")
diff --git a/src/Rules.jl b/src/Rules.jl
@@ -1,15 +1,17 @@
-module CatConfig
+module Rules
 
-export CatRules, CatLoopConfig
+export CatRules
 
 using DocStringExtensions
 using PsychometricsBazaarBase.Parameters
+using PsychometricsBazaarBase.IndentWrappers: indent
 
 using ..Aggregators: AbilityEstimator, AbilityTracker, ConsAbilityTracker,
                      NullAbilityTracker
 using ..NextItemRules: NextItemRule
 using ..TerminationConditions: TerminationCondition
 using ..ConfigBase
+import Base: show
 
 """
 $(TYPEDEF)
@@ -19,7 +21,7 @@ Configuration of the rules for a CAT. This all includes all the basic rules for
 the CAT's operation, but not the item bank, nor any of the interactivity hooks
 needed to actually run the CAT.
 
-This may be more a more convenient layer to integrate than CatLoopConfig if you
+This may be more a more convenient layer to integrate than CatLoop if you
 want to write your own CAT loop rather than using hooks.
 
     $(FUNCTIONNAME)(; next_item=..., termination_condition=..., ability_estimator=..., ability_tracker=...)
@@ -79,6 +81,16 @@ function CatRules(bits...)
         ability_tracker = collect_trackers(next_item, ability_tracker))
 end
 
+function show(io::IO, ::MIME"text/plain", rules::CatRules)
+    indent_io = indent(io, 2)
+    println(io, "Next item rule:")
+    show(indent_io, MIME"text/plain"(), rules.next_item)
+    println(io, "Termination condition:")
+    show(indent_io, MIME"text/plain"(), rules.termination_condition)
+    println(io, "Ability estimator:")
+    show(indent_io, MIME"text/plain"(), rules.ability_estimator)
+end
+
 function _find_ability_estimator_and_tracker(bits...)
     ability_estimator = AbilityEstimator(bits...)
     ability_tracker = AbilityTracker(bits...; ability_estimator = ability_estimator)
@@ -113,33 +125,4 @@ function collect_trackers(next_item_rule::NextItemRule, ability_tracker::Ability
     end
 end
 
-"""
-```julia
-struct $(FUNCTIONNAME)
-$(FUNCTIONNAME)(; rules=..., get_response=..., new_response_callback=...)
-```
-$(TYPEDFIELDS)
-
-Configuration for a simulatable CAT.
-"""
-@with_kw struct CatLoopConfig{CatEngineT} <: CatConfigBase
-    """
-    An object which implements the CAT engine.
-    Implementations exist for:
-      * [CatRules](@ref)
-      * [Stateful.StatefulCat](@ref ComputerAdaptiveTesting.Stateful.StatefulCat)
-    """
-    rules::CatEngineT # e.g. CatRules
-    """
-    The function `(index, label) -> Int8`` which obtains the testee's response for
-    a given question, e.g. by prompting or simulation from data.
-    """
-    get_response::Any
-    """
-    A callback called each time there is a new responses.
-    If provided, it is passed `(responses::TrackedResponses, terminating)`.
-    """
-    new_response_callback = nothing
-end
-
 end
diff --git a/src/Stateful.jl b/src/Stateful.jl
@@ -9,10 +9,10 @@ using DocStringExtensions
 
 using FittedItemBanks: AbstractItemBank, ResponseType, ItemResponse, resp_vec
 using ..Aggregators: TrackedResponses, Aggregators, pdf, distribution_estimator
-using ..CatConfig: CatLoopConfig, CatRules
+using ..Rules: CatRules
 using ..Responses: BareResponses, Response, Responses
 using ..NextItemRules: compute_criteria, best_item
-using ..Sim: Sim, item_label
+using ..Sim: CatLoop, Sim, item_label
 
 export StatefulCat, StatefulCatConfig
 public next_item, ranked_items, item_criteria
@@ -156,7 +156,7 @@ model backing the CAT.
 function item_response_functions end
 
 ## Running the CAT
-function Sim.run_cat(cat_config::CatLoopConfig{RulesT},
+function Sim.run_cat(cat_config::CatLoop{RulesT},
         ib_labels = nothing) where {RulesT <: StatefulCat}
     (; stateful_cat, get_response, new_response_callback) = cat_config
     while true
diff --git a/src/TerminationConditions.jl b/src/TerminationConditions.jl
@@ -8,7 +8,7 @@ using PsychometricsBazaarBase.ConfigTools: @returnsome, find1_instance
 using FittedItemBanks
 
 export TerminationCondition,
-       FixedItemsTerminationCondition, SimpleFunctionTerminationCondition
+       LengthTerminationCondition, SimpleFunctionTerminationCondition
 export RunForeverTerminationCondition
 
 """
@@ -24,14 +24,17 @@ end
 $(TYPEDEF)
 $(TYPEDFIELDS)
 """
-struct FixedItemsTerminationCondition{} <: TerminationCondition
+struct LengthTerminationCondition{} <: TerminationCondition
     num_items::Int64
 end
-function (condition::FixedItemsTerminationCondition)(responses::TrackedResponses,
+function (condition::LengthTerminationCondition)(responses::TrackedResponses,
         items::AbstractItemBank)
     length(responses) >= condition.num_items
 end
 
+# Alias for old name
+const FixedItemsTerminationCondition = LengthTerminationCondition
+
 struct SimpleFunctionTerminationCondition{F} <: TerminationCondition
     func::F
 end
diff --git a/src/decision_tree/sim.jl b/src/decision_tree/sim.jl
@@ -1,9 +1,9 @@
 import ComputerAdaptiveTesting: Sim
 
 """
-Run a given CatLoopConfig with a MaterializedDecisionTree
+Run a given CatLoop with a MaterializedDecisionTree
 """
-function Sim.run_cat(cat_config::Sim.CatLoopConfig{RulesT},
+function Sim.run_cat(cat_config::Sim.CatLoop{RulesT},
         item_bank::AbstractItemBank;
         ib_labels = nothing) where {RulesT <: MaterializedDecisionTree}
     (; rules, get_response, new_response_callback) = cat_config
diff --git a/src/precompiles.jl b/src/precompiles.jl
@@ -10,6 +10,7 @@ using PrecompileTools: @compile_workload, @setup_workload
     using .NextItemRules: preallocate, ExhaustiveSearch, ItemStrategyNextItemRule,
                           ExpectationBasedItemCriterion, AbilityVarianceStateCriterion
     using .Stateful: Stateful
+    using .ComputerAdaptiveTesting: CatRules
 
     rng = default_rng(42)
     spec = SimpleItemBankSpec(StdModel2PL(), OneDimContinuousDomain(), BooleanResponse())
@@ -24,7 +25,7 @@ using PrecompileTools: @compile_workload, @setup_workload
             ExhaustiveSearch(),
             ExpectationBasedItemCriterion(ability_estimator,
                 AbilityVarianceStateCriterion(ability_estimator)))
-        cat = Stateful.StatefulCatConfig(CatConfig.CatRules(;
+        cat = Stateful.StatefulCatConfig(CatRules(;
             next_item=next_item_rule,
             termination_condition=TerminationConditions.RunForeverTerminationCondition(),
             ability_estimator=ability_estimator
diff --git a/src/sim/Sim.jl b/src/sim/Sim.jl
diff --git a/src/sim/loop.jl b/src/sim/loop.jl
diff --git a/src/sim/recorder.jl b/src/sim/recorder.jl
diff --git a/src/sim/run.jl b/src/sim/run.jl
diff --git a/test/dt.jl b/test/dt.jl
diff --git a/test/runtests.jl b/test/runtests.jl
diff --git a/test/smoke.jl b/test/smoke.jl

Original file line number	Diff line number	Diff line change
`@@ -33,4 +33,4 @@ Stateful.StatefulCatConfig`
`33`	`33`
`34`	`34`	`## Usage`
`35`	`35`
`36`		`-Just as [CatLoopConfig](@ref) can wrap [CatRules](@ref), you can also use it with any implementor of [Stateful.StatefulCat](@ref), and run using [Sim.run_cat](@ref).`
	`36`	`+Just as [CatLoop](@ref) can wrap [CatRules](@ref), you can also use it with any implementor of [Stateful.StatefulCat](@ref), and run using [Sim.run_cat](@ref).`