StructuralEquationModels · Maximilian-Stefan-Ernst · Apr 14, 2025 · Nov 18, 2024 · Nov 19, 2024 · Feb 4, 2025
diff --git a/.github/workflows/CI.yml b/.github/workflows/CI.yml
@@ -33,6 +33,6 @@ jobs:
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         with:
           file: lcov.info
diff --git a/.github/workflows/CI_ecosystem.yml b/.github/workflows/CI_ecosystem.yml
@@ -36,6 +36,6 @@ jobs:
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         with:
           file: lcov.info
diff --git a/.github/workflows/CI_extended.yml b/.github/workflows/CI_extended.yml
@@ -35,6 +35,6 @@ jobs:
       - uses: julia-actions/julia-buildpkg@v1
       - uses: julia-actions/julia-runtest@v1
       - uses: julia-actions/julia-processcoverage@v1
-      - uses: codecov/codecov-action@v4
+      - uses: codecov/codecov-action@v5
         with:
           file: lcov.info
diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "StructuralEquationModels"
 uuid = "383ca8c5-e4ff-4104-b0a9-f7b279deed53"
 authors = ["Maximilian Ernst", "Aaron Peikert"]
-version = "0.2.4"
+version = "0.4.0"
 
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
@@ -12,20 +12,21 @@ LazyArtifacts = "4af54fe1-eca0-43a8-85a7-787d91b784e3"
 LineSearches = "d3d80556-e9d4-5f37-9878-2ab0fcc64255"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 NLSolversBase = "d41bc354-129a-5804-8e4c-c37616107c6c"
-NLopt = "76087f3c-5699-56af-9a33-bf431cd00edd"
 Optim = "429524aa-4258-5aef-a3af-852621145aeb"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
+StatsAPI = "82ae8749-77ed-4fe6-ae5f-f523153014b0"
 StatsBase = "2913bbd2-ae8a-5f71-8c99-4fb6c76f3a91"
 StenoGraphs = "78862bba-adae-4a83-bb4d-33c106177f81"
 Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
+SymbolicUtils = "d1185830-fcd6-423d-90d6-eec64667417b"
 
 [compat]
-julia = "1.9, 1.10"
-StenoGraphs = "0.2"
+julia = "1.9, 1.10, 1.11"
+StenoGraphs = "0.2 - 0.3, 0.4.1 - 0.5"
 DataFrames = "1"
 Distributions = "0.25"
 FiniteDiff = "2"
@@ -34,11 +35,22 @@ NLSolversBase = "7"
 NLopt = "0.6, 1"
 Optim = "1"
 PrettyTables = "2"
+ProximalAlgorithms = "0.7"
 StatsBase = "0.33, 0.34"
-Symbolics = "4, 5"
+Symbolics = "4, 5, 6"
+SymbolicUtils = "1.4 - 1.5, 1.7, 2, 3"
+StatsAPI = "1"
 
 [extras]
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 
 [targets]
 test = ["Test"]
+
+[weakdeps]
+NLopt = "76087f3c-5699-56af-9a33-bf431cd00edd"
+ProximalAlgorithms = "140ffc9f-1907-541a-a177-7475e0a401e9"
+
+[extensions]
+SEMNLOptExt = "NLopt"
+SEMProximalOptExt = "ProximalAlgorithms"
diff --git a/README.md b/README.md
@@ -4,18 +4,21 @@
 |:-------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------:|:-----------------------------------------------------------------------------------------------:|
 | [![Stable](https://img.shields.io/badge/docs-stable-blue.svg)](https://structuralequationmodels.github.io/StructuralEquationModels.jl/) [![Dev](https://img.shields.io/badge/docs-dev-blue.svg)](https://structuralequationmodels.github.io/StructuralEquationModels.jl/dev/) | [![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active) [![Github Action CI](https://github.com/StructuralEquationModels/StructuralEquationModels.jl/workflows/CI_extended/badge.svg)](https://github.com/StructuralEquationModels/StructuralEquationModels.jl/actions/) [![codecov](https://codecov.io/gh/StructuralEquationModels/StructuralEquationModels.jl/branch/main/graph/badge.svg?token=P2kjzpvM4V)](https://codecov.io/gh/StructuralEquationModels/StructuralEquationModels.jl) | [![DOI](https://zenodo.org/badge/228649704.svg)](https://zenodo.org/badge/latestdoi/228649704) |
 
+> [!NOTE]  
+> Check out our [preprint](https://formal-methods-mpi.github.io/pkgmanuscript/manuscript.pdf) on the package!
+
 # What is this Package for?
 
 This is a package for Structural Equation Modeling.
 It is still *in development*.
 Models you can fit include
 - Linear SEM that can be specified in RAM (or LISREL) notation
 - ML, GLS and FIML estimation
-- Regularization
+- Regularized SEM (Ridge, Lasso, L0, ...)
 - Multigroup SEM
 - Sums of arbitrary loss functions (everything the optimizer can handle).
 
-# What are the merrits?
+# What are the merits?
 
 We provide fast objective functions, gradients, and for some cases hessians as well as approximations thereof.
 As a user, you can easily define custom loss functions.
@@ -35,6 +38,7 @@ The package makes use of
 - Symbolics.jl for symbolically precomputing parts of the objective and gradients to generate fast, specialized functions.
 - SparseArrays.jl to speed up symbolic computations.
 - Optim.jl and NLopt.jl to provide a range of different Optimizers/Linesearches.
+- ProximalAlgorithms.jl for regularization.
 - FiniteDiff.jl and ForwardDiff.jl to provide gradients for user-defined loss functions.
 
 # At the moment, we are still working on:

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,4 +1,6 @@
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+NLopt = "76087f3c-5699-56af-9a33-bf431cd00edd"
+ProximalAlgorithms = "140ffc9f-1907-541a-a177-7475e0a401e9"
 ProximalOperators = "a725b495-10eb-56fe-b38b-717eba820537"
diff --git a/docs/make.jl b/docs/make.jl
@@ -32,7 +32,7 @@ makedocs(
         "Developer documentation" => [
             "Extending the package" => "developer/extending.md",
             "Custom loss functions" => "developer/loss.md",
-            "Custom imply types" => "developer/imply.md",
+            "Custom implied types" => "developer/implied.md",
             "Custom optimizer types" => "developer/optimizer.md",
             "Custom observed types" => "developer/observed.md",
             "Custom model types" => "developer/sem.md",

diff --git a/docs/src/assets/concept.svg b/docs/src/assets/concept.svg
diff --git a/docs/src/assets/concept_typed.svg b/docs/src/assets/concept_typed.svg
diff --git a/docs/src/developer/extending.md b/docs/src/developer/extending.md
@@ -1,6 +1,6 @@
 # Extending the package
 
-As discussed in the section on [Model Construction](@ref), every Structural Equation Model (`Sem`) consists of four parts:
+As discussed in the section on [Model Construction](@ref), every Structural Equation Model (`Sem`) consists of three (four with the optimizer) parts:
 
 ![SEM concept typed](../assets/concept_typed.svg)
 

diff --git a/docs/src/developer/implied.md b/docs/src/developer/implied.md
@@ -0,0 +1,98 @@
+# Custom implied types
+
+We recommend to first read the part [Custom loss functions](@ref), as the overall implementation is the same and we will describe it here more briefly.
+
+Implied types are of subtype `SemImplied`. To implement your own implied type, you should define a struct
+
+```julia
+struct MyImplied <: SemImplied
+    ...
+end
+```
+
+and a method to update!:
+
+```julia
+import StructuralEquationModels: objective!
+
+function update!(targets::EvaluationTargets, implied::MyImplied, model::AbstractSemSingle, params)
+
+    if is_objective_required(targets)
+        ...
+    end
+
+    if is_gradient_required(targets)
+        ...
+    end
+    if is_hessian_required(targets)
+        ...
+    end
+
+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.
+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.
+
+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:
+
+```julia
+############################################################################################
+### Types
+############################################################################################
+"""
+Empty placeholder for models that don't need an implied part.
+(For example, models that only regularize parameters.)
+
+# Constructor
+
+    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.
+
+# Extended help
+
+## Interfaces
+- `params(::RAMSymbolic) `-> Vector of parameter labels
+- `nparams(::RAMSymbolic)` -> Number of parameters
+
+## Implementation
+Subtype of `SemImplied`.
+"""
+struct ImpliedEmpty{A, B, C} <: SemImplied
+    hessianeval::A
+    meanstruct::B
+    ram_matrices::C
+end
+
+############################################################################################
+### Constructors
+############################################################################################
+
+function ImpliedEmpty(;specification, meanstruct = NoMeanStruct(), hessianeval = ExactHessian(), kwargs...)
+    return ImpliedEmpty(hessianeval, meanstruct, convert(RAMMatrices, specification))
+end
+
+############################################################################################
+### methods
+############################################################################################
+
+update!(targets::EvaluationTargets, implied::ImpliedEmpty, par, model) = nothing
+
+############################################################################################
+### Recommended methods
+############################################################################################
+
+update_observed(implied::ImpliedEmpty, observed::SemObserved; kwargs...) = implied
+```
+
+As you see, similar to [Custom loss functions](@ref) we implement a method for `update_observed`.