Release 0.5.0

Project.toml

@@ -1,20 +1,22 @@
 name = "StructuralEquationModels"
 uuid = "383ca8c5-e4ff-4104-b0a9-f7b279deed53"
 authors = ["Maximilian Ernst", "Aaron Peikert"]
-version = "0.4.2"
+version = "0.5.0"
 
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 DelimitedFiles = "8bb1440f-4735-579b-a4ab-409b98df4dab"
 Distributions = "31c24e10-a181-5473-b8eb-7969acd0382f"
 FiniteDiff = "6a86dc24-6348-571c-b903-95158fe2bd41"
+InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 LazyArtifacts = "4af54fe1-eca0-43a8-85a7-787d91b784e3"
 LineSearches = "d3d80556-e9d4-5f37-9878-2ab0fcc64255"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 NLSolversBase = "d41bc354-129a-5804-8e4c-c37616107c6c"
 Optim = "429524aa-4258-5aef-a3af-852621145aeb"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
+ProgressMeter = "92933f4c-e287-5a05-a399-4b506db050ca"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
@@ -25,21 +27,23 @@ Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 SymbolicUtils = "d1185830-fcd6-423d-90d6-eec64667417b"
 
 [compat]
-julia = "1.9, 1.10, 1.11"
-StenoGraphs = "0.2 - 0.3, 0.4.1 - 0.5"
+julia = "1.10, 1.11, 1.12"
+StenoGraphs = "0.5"
 DataFrames = "1"
 Distributions = "0.25"
 FiniteDiff = "2"
 LineSearches = "7"
-NLSolversBase = "7"
+NLSolversBase = "8"
 NLopt = "0.6, 1"
-Optim = "1"
-PrettyTables = "2"
+Optim = "2"
+PrettyTables = "3"
 ProximalAlgorithms = "0.7"
 StatsBase = "0.33, 0.34"
-Symbolics = "4, 5, 6"
-SymbolicUtils = "1.4 - 1.5, 1.7, 2, 3"
+Symbolics = "4, 5, 6, 7"
+SymbolicUtils = "1.4 - 1.5, 1.7, 2, 3, 4"
 StatsAPI = "1"
+DelimitedFiles = "1"
+Statistics = "1"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"

docs/make.jl

@@ -1,7 +1,12 @@
-using Documenter, StructuralEquationModels
+using Documenter, StructuralEquationModels, NLopt, ProximalAlgorithms, ProximalOperators
+
+SEM = StructuralEquationModels
+SEMNLOptExt = Base.get_extension(StructuralEquationModels, :SEMNLOptExt)
+SEMProximalOptExt = Base.get_extension(StructuralEquationModels, :SEMProximalOptExt)
 
 makedocs(
     sitename = "StructuralEquationModels.jl",
+    modules = [SEM, SEMNLOptExt, SEMProximalOptExt],
     pages = [
         "index.md",
         "Tutorials" => [
@@ -47,11 +52,6 @@ makedocs(
             "Starting values" => "performance/starting_values.md",
             "Parametric Types" => "performance/parametric.md",
         ],
-        "Internals and design" => [
-            "Internals and design" => "internals/internals.md",
-            "files" => "internals/files.md",
-            "types" => "internals/types.md",
-        ],
     ],
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",
@@ -60,6 +60,7 @@ makedocs(
         collapselevel = 1,
     ),
     doctest = false,
+    checkdocs = :none,
 )
 
 # doctest(StructuralEquationModels, fix=true)

docs/src/developer/extending.md

@@ -1,10 +1,12 @@
 # Extending the package
 
-As discussed in the section on [Model Construction](@ref), every Structural Equation Model (`Sem`) consists of three (four with the optimizer) parts:
+As discussed in [Our Concept of a Structural Equation Model](@ref), a `Sem` is built from one or more loss
+terms, and each SEM loss function bundles an *observed* and an *implied* part:
 
 ![SEM concept typed](../assets/concept_typed.svg)
 
-On the following pages, we will explain how you can define your own custom parts and "plug them in". There are certain things you **have to do** to define custom parts and some things you **can do** to have a more pleasent experience. In general, these requirements fall into the categories
+On the following pages, we will explain how you can define your own custom parts (a loss function, an observed
+type, an implied type, or an optimizer) and "plug them in". There are certain things you **have to do** to define custom parts and some things you **can do** to have a more pleasent experience. In general, these requirements fall into the categories
 - minimal (to use your custom part and fit a `Sem` with it)
 - use the outer constructor to build a model in a more convenient way
 - use additional functionality like standard errors, fit measures, etc.

docs/src/developer/implied.md

@@ -13,9 +13,9 @@ end
 and a method to update!:
 
 ```julia
-import StructuralEquationModels: objective!
+import StructuralEquationModels: update!
 
-function update!(targets::EvaluationTargets, implied::MyImplied, model::AbstractSemSingle, params)
+function update!(targets::EvaluationTargets, implied::MyImplied, params)
 
     if is_objective_required(targets)
         ...
@@ -31,12 +31,10 @@ function update!(targets::EvaluationTargets, implied::MyImplied, model::Abstract
 end
 ```
 
-As you can see, `update` gets passed as a first argument `targets`, which is telling us whether the objective value, gradient, and/or hessian are needed.
+As you can see, `update!` gets passed as a first argument `targets`, which is telling us whether the objective value, gradient, and/or hessian are needed.
 We can then use the functions `is_..._required` and conditional on what the optimizer needs, we can compute and store things we want to make available to the loss functions. For example, as we have seen in [Second example - maximum likelihood](@ref), the `RAM` implied type computes the model-implied covariance matrix and makes it available via `implied.Σ`.
 
-
-
-Just as described in [Custom loss functions](@ref), you may define a constructor. Typically, this will depend on the `specification = ...` argument that can be a `ParameterTable` or a `RAMMatrices` object.
+Just as described in [Custom loss functions](@ref), you may define a constructor. It should take the model specification (a `ParameterTable` or a `RAMMatrices` object) as the first positional argument, like the built-in [`RAM`](@ref) — this is how the outer `Sem` constructor builds the implied part when you select it by type (e.g. `implied = MyImplied`).
 
 We implement an `ImpliedEmpty` type in our package that does nothing but serving as an `implied` field in case you are using a loss function that does not need any implied type at all. You may use it as a template for defining your own implied type, as it also shows how to handle the specification objects:
 
@@ -45,19 +43,18 @@ We implement an `ImpliedEmpty` type in our package that does nothing but serving
 ### Types
 ############################################################################################
 """
-Empty placeholder for models that don't need an implied part.
-(For example, models that only regularize parameters.)
+Empty placeholder for loss functions that don't need an implied part.
 
 # Constructor
 
-    ImpliedEmpty(;specification, kwargs...)
+    ImpliedEmpty(specification; kwargs...)
 
 # Arguments
 - `specification`: either a `RAMMatrices` or `ParameterTable` object
 
 # Examples
-A multigroup model with ridge regularization could be specified as a `SemEnsemble` with one
-model per group and an additional model with `ImpliedEmpty` and `SemRidge` for the regularization part.
+A multigroup model with ridge regularization could be specified as a `Sem` with one
+SEM term (`SemLoss`) per group and an additional `SemRidge` regularization term.
 
 # Extended help
 
@@ -75,8 +72,8 @@ end
 ### Constructors
 ############################################################################################
 
-function ImpliedEmpty(;
-    specification,
+function ImpliedEmpty(
+    specification::SemSpecification;
     meanstruct = NoMeanStruct(),
     hessianeval = ExactHessian(),
     kwargs...,
@@ -88,13 +85,7 @@ end
 ### methods
 ############################################################################################
 
-update!(targets::EvaluationTargets, implied::ImpliedEmpty, par, model) = nothing
-
-############################################################################################
-### Recommended methods
-############################################################################################
-
-update_observed(implied::ImpliedEmpty, observed::SemObserved; kwargs...) = implied
+update!(targets::EvaluationTargets, implied::ImpliedEmpty, par) = nothing
 ```
 
-As you see, similar to [Custom loss functions](@ref) we implement a method for `update_observed`.
+As you see, similar to [Custom loss functions](@ref) we implement a constructor.