Merge pull request #249 from StructuralEquationModels/devel

Devel

Author: Maximilian-Stefan-Ernst

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.3.0"
 
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"
@@ -12,7 +12,6 @@ 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"
@@ -25,8 +24,8 @@ Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 SymbolicUtils = "d1185830-fcd6-423d-90d6-eec64667417b"
 
 [compat]
-julia = "1.9, 1.10"
-StenoGraphs = "0.2, 0.3"
+julia = "1.9, 1.10, 1.11"
+StenoGraphs = "0.2 - 0.3, 0.4.1 - 0.5"
 DataFrames = "1"
 Distributions = "0.25"
 FiniteDiff = "2"
@@ -35,12 +34,21 @@ NLSolversBase = "7"
 NLopt = "0.6, 1"
 Optim = "1"
 PrettyTables = "2"
+ProximalAlgorithms = "0.7"
 StatsBase = "0.33, 0.34"
-Symbolics = "4, 5"
-SymbolicUtils = "1.4 - 1.5"
+Symbolics = "4, 5, 6"
+SymbolicUtils = "1.4 - 1.5, 1.7, 2, 3"
 
 [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"

README.md

@@ -11,7 +11,7 @@ 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).
 
@@ -35,6 +35,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:

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"

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",

docs/src/assets/concept.svg

@@ -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)
 

docs/src/assets/concept_typed.svg

@@ -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`.