SemImplied/SemLossFun: drop meanstructure kwarg

- for SemImplied require spec::SemSpec as positional
- for SemLossFunction require implied argument

Author: alyst

src/frontend/specification/Sem.jl

@@ -109,7 +109,15 @@ function get_fields!(kwargs, specification, observed, implied, loss)
 
     # implied
     if !isa(implied, SemImplied)
-        implied = implied(; specification, kwargs...)
+        # FIXME remove this implicit logic
+        # SemWLS only accepts vech-ed implied covariance
+        if isa(loss, Type) && (loss <: SemWLS) && !haskey(kwargs, :vech)
+            implied_kwargs = copy(kwargs)
+            implied_kwargs[:vech] = true
+        else
+            implied_kwargs = kwargs
+        end
+        implied = implied(specification; implied_kwargs...)
     end
 
     kwargs[:implied] = implied

src/implied/RAM/generic.jl

@@ -6,14 +6,10 @@ Model implied covariance and means via RAM notation.
 
 # Constructor
 
-    RAM(;specification,
-        meanstructure = false,
-        gradient = true,
-        kwargs...)
+    RAM(; specification, gradient = true, kwargs...)
 
 # Arguments
 - `specification`: either a `RAMMatrices` or `ParameterTable` object
-- `meanstructure::Bool`: does the model have a meanstructure?
 - `gradient::Bool`: is gradient-based optimization used
 
 # Extended help
@@ -53,9 +49,9 @@ Vector of indices of each parameter in the respective RAM matrix:
 - `ram.M_indices`
 
 Additional interfaces
-- `ram.F⨉I_A⁻¹` -> ``F(I-A)^{-1}``
-- `ram.F⨉I_A⁻¹S` -> ``F(I-A)^{-1}S``
-- `ram.I_A` -> ``I-A``
+- `F⨉I_A⁻¹(::RAM)` -> ``F(I-A)^{-1}``
+- `F⨉I_A⁻¹S(::RAM)` -> ``F(I-A)^{-1}S``
+- `I_A(::RAM)` -> ``I-A``
 
 Only available in gradient! calls:
 - `ram.I_A⁻¹` -> ``(I-A)^{-1}``
@@ -90,15 +86,13 @@ end
 ### Constructors
 ############################################################################################
 
-function RAM(;
-    specification::SemSpecification,
+function RAM(
+    spec::SemSpecification;
+    #vech = false,
     gradient_required = true,
-    meanstructure = false,
     kwargs...,
 )
-    ram_matrices = convert(RAMMatrices, specification)
-
-    check_meanstructure_specification(meanstructure, ram_matrices)
+    ram_matrices = convert(RAMMatrices, spec)
 
     # get dimensions of the model
     n_par = nparams(ram_matrices)
@@ -126,7 +120,7 @@ function RAM(;
     end
 
     # μ
-    if meanstructure
+    if !isnothing(ram_matrices.M)
         MS = HasMeanStruct
         M_pre = materialize(ram_matrices.M, rand_params)
         ∇M = gradient_required ? sparse_gradient(ram_matrices.M) : nothing

src/implied/RAM/symbolic.jl

@@ -12,12 +12,10 @@ Subtype of `SemImplied` that implements the RAM notation with symbolic precomput
         gradient = true,
         hessian = false,
         approximate_hessian = false,
-        meanstructure = false,
         kwargs...)
 
 # Arguments
 - `specification`: either a `RAMMatrices` or `ParameterTable` object
-- `meanstructure::Bool`: does the model have a meanstructure?
 - `gradient::Bool`: is gradient-based optimization used
 - `hessian::Bool`: is hessian-based optimization used
 - `approximate_hessian::Bool`: for hessian based optimization: should the hessian be approximated
@@ -79,20 +77,16 @@ end
 ### Constructors
 ############################################################################################
 
-function RAMSymbolic(;
-    specification::SemSpecification,
-    loss_types = nothing,
-    vech = false,
-    simplify_symbolics = false,
-    gradient = true,
-    hessian = false,
-    meanstructure = false,
-    approximate_hessian = false,
+function RAMSymbolic(
+    spec::SemSpecification;
+    vech::Bool = false,
+    simplify_symbolics::Bool = false,
+    gradient::Bool = true,
+    hessian::Bool = false,
+    approximate_hessian::Bool = false,
     kwargs...,
 )
-    ram_matrices = convert(RAMMatrices, specification)
-
-    check_meanstructure_specification(meanstructure, ram_matrices)
+    ram_matrices = convert(RAMMatrices, spec)
 
     n_par = nparams(ram_matrices)
     par = (Symbolics.@variables θ[1:n_par])[1]
@@ -102,10 +96,6 @@ function RAMSymbolic(;
     M = !isnothing(ram_matrices.M) ? materialize(Num, ram_matrices.M, par) : nothing
     F = ram_matrices.F
 
-    if !isnothing(loss_types) && any(T -> T <: SemWLS, loss_types)
-        vech = true
-    end
-
     I_A⁻¹ = neumann_series(A)
 
     # Σ
@@ -146,7 +136,7 @@ function RAMSymbolic(;
     end
 
     # μ
-    if meanstructure
+    if !isnothing(ram_matrices.M)
         MS = HasMeanStruct
         μ_sym = eval_μ_symbolic(M, I_A⁻¹, F; simplify = simplify_symbolics)
         μ_eval! = Symbolics.build_function(μ_sym, par, expression = Val{false})[2]
@@ -230,10 +220,10 @@ end
 ############################################################################################
 
 # expected covariations of observed vars
-function eval_Σ_symbolic(S, I_A⁻¹, F; vech = false, simplify = false)
+function eval_Σ_symbolic(S, I_A⁻¹, F; vech::Bool = false, simplify::Bool = false)
     Σ = F * I_A⁻¹ * S * permutedims(I_A⁻¹) * permutedims(F)
     Σ = Array(Σ)
-    vech && (Σ = Σ[tril(trues(size(F, 1), size(F, 1)))])
+    vech && (Σ = SEM.vech(Σ))
     if simplify
         Threads.@threads for i in eachindex(Σ)
             Σ[i] = Symbolics.simplify(Σ[i])

src/implied/abstract.jl

@@ -31,17 +31,3 @@ function check_acyclic(A::AbstractMatrix; verbose::Bool = false)
         return A
     end
 end
-
-# Verify that the `meanstructure` argument aligns with the model specification.
-function check_meanstructure_specification(meanstructure, ram_matrices)
-    if meanstructure & isnothing(ram_matrices.M)
-        throw(ArgumentError(
-            "You set `meanstructure = true`, but your model specification contains no mean parameters."
-        ))
-    end
-    if !meanstructure & !isnothing(ram_matrices.M)
-        throw(ArgumentError(
-            "If your model specification contains mean parameters, you have to set `Sem(..., meanstructure = true)`."
-        ))
-    end
-end

src/loss/ML/FIML.jl

@@ -75,15 +75,16 @@ Can handle observed data with missing values.
 
 # Constructor
 
-    SemFIML(; observed::SemObservedMissing, specification, kwargs...)
+    SemFIML(; observed::SemObservedMissing, implied::SemImplied, kwargs...)
 
 # Arguments
-- `observed`: the observed data with missing values (see [`SemObservedMissing`](@ref))
-- `specification`: [`SemSpecification`](@ref) object
+- `observed::SemObservedMissing`: the observed part of the model
+  (see [`SemObservedMissing`](@ref))
+- `implied::SemImplied`: the implied part of the model
 
 # Examples
 ```julia
-my_fiml = SemFIML(observed = my_observed, specification = my_parameter_table)
+my_fiml = SemFIML(observed = my_observed, implied = my_implied)
 ```
 
 # Interfaces
@@ -118,7 +119,7 @@ function SemFIML(; observed::SemObservedMissing, implied, specification, kwargs.
         ExactHessian(),
         [SemFIMLPattern(pat) for pat in observed.patterns],
         zeros(nobserved_vars(observed), nobserved_vars(observed)),
-        CommutationMatrix(nvars(specification)),
+        CommutationMatrix(nvars(implied)),
         nothing,
     )
 end

src/loss/ML/ML.jl

@@ -8,11 +8,10 @@ Maximum likelihood estimation.
 
 # Constructor
 
-    SemML(;observed, meanstructure = false, approximate_hessian = false, kwargs...)
+    SemML(; observed, approximate_hessian = false, kwargs...)
 
 # Arguments
 - `observed::SemObserved`: the observed part of the model
-- `meanstructure::Bool`: does the model have a meanstructure?
 - `approximate_hessian::Bool`: if hessian-based optimization is used, should the hessian be swapped for an approximation
 
 # Examples

src/loss/WLS/WLS.jl

@@ -10,16 +10,15 @@ At the moment only available with the `RAMSymbolic` implied type.
 # Constructor
 
     SemWLS(;
-        observed,
-        meanstructure = false,
+        observed, implied,
         wls_weight_matrix = nothing,
         wls_weight_matrix_mean = nothing,
         approximate_hessian = false,
         kwargs...)
 
 # Arguments
 - `observed`: the `SemObserved` part of the model
-- `meanstructure::Bool`: does the model have a meanstructure?
+- `implied::SemImplied`: the implied part of the model
 - `approximate_hessian::Bool`: should the hessian be swapped for an approximation
 - `wls_weight_matrix`: the weight matrix for weighted least squares.
     Defaults to GLS estimation (``0.5*(D^T*kron(S,S)*D)`` where D is the duplication matrix
@@ -29,7 +28,7 @@ At the moment only available with the `RAMSymbolic` implied type.
 
 # Examples
 ```julia
-my_wls = SemWLS(observed = my_observed)
+my_wls = SemWLS(observed = my_observed, implied = my_implied)
 ```
 
 # Interfaces
@@ -50,12 +49,11 @@ SemWLS{HE}(args...) where {HE <: HessianEval} =
     SemWLS{HE, map(typeof, args)...}(HE(), args...)
 
 function SemWLS(;
-    observed,
-    implied,
-    wls_weight_matrix = nothing,
-    wls_weight_matrix_mean = nothing,
-    approximate_hessian = false,
-    meanstructure = false,
+    observed::SemObserved,
+    implied::SemImplied,
+    wls_weight_matrix::Union{AbstractMatrix, Nothing} = nothing,
+    wls_weight_matrix_mean::Union{AbstractMatrix, Nothing} = nothing,
+    approximate_hessian::Bool = false,
     kwargs...,
 )
     if observed isa SemObservedMissing
@@ -81,6 +79,10 @@ function SemWLS(;
     nobs_vars = nobserved_vars(observed)
     tril_ind = filter(x -> (x[1] >= x[2]), CartesianIndices(obs_cov(observed)))
     s = obs_cov(observed)[tril_ind]
+    size(s) == size(implied.Σ) ||
+        throw(DimensionMismatch("SemWLS requires implied covariance to be in vech-ed form " *
+                                "(vectorized lower triangular part of Σ matrix): $(size(s)) expected, $(size(implied.Σ)) found.\n" *
+                                "$(nameof(typeof(implied))) must be constructed with vech=true."))
 
     # compute V here
     if isnothing(wls_weight_matrix)
@@ -94,9 +96,12 @@ function SemWLS(;
                 "wls_weight_matrix has to be of size $(length(tril_ind))×$(length(tril_ind))",
             )
     end
+    size(wls_weight_matrix) == (length(s), length(s)) ||
+        DimensionMismatch("wls_weight_matrix has to be of size $(length(s))×$(length(s))")
 
-    if meanstructure
+    if MeanStruct(implied) == HasMeanStruct
         if isnothing(wls_weight_matrix_mean)
+        	@warn "Computing WLS weight matrix for the meanstructure using obs_cov()"
             wls_weight_matrix_mean = inv(obs_cov(observed))
         else
             size(wls_weight_matrix_mean) == (nobs_vars, nobs_vars) || DimensionMismatch(

test/examples/recover_parameters/recover_parameters_twofact.jl

@@ -53,7 +53,7 @@ start = [
     repeat([0.5], 4)
 ]
 
-implied_ml = RAMSymbolic(; specification = ram_matrices, start_val = start)
+implied_ml = RAMSymbolic(ram_matrices; start_val = start)
 
 implied_ml.Σ_eval!(implied_ml.Σ, true_val)
 

test/unit_tests/model.jl

@@ -46,13 +46,16 @@ function test_params_api(semobj, spec::SemSpecification)
     @test @inferred(param_labels(semobj)) == param_labels(spec)
 end
 
-@testset "Sem(implied=$impliedtype, loss=SemML)" for impliedtype in (RAM, RAMSymbolic)
-
+@testset "Sem(implied=$impliedtype, loss=$losstype)" for (impliedtype, losstype) in [
+    (RAM, SemML),
+    (RAMSymbolic, SemML),
+    (RAMSymbolic, SemWLS),
+]
     model = Sem(
         specification = ram_matrices,
         observed = obs,
         implied = impliedtype,
-        loss = SemML,
+        loss = losstype,
     )
 
     @test model isa Sem
@@ -71,29 +74,3 @@ end
 
     @test @inferred(nsamples(model)) == nsamples(obs)
 end
-
-@testset "Sem(implied=RAMSymbolic, loss=SemWLS)" begin
-
-    model = Sem(
-        specification = ram_matrices,
-        observed = obs,
-        implied = RAMSymbolic,
-        loss = SemWLS,
-    )
-
-    @test model isa Sem
-    @test @inferred(implied(model)) isa RAMSymbolic
-    @test @inferred(observed(model)) isa SemObserved
-
-    test_vars_api(model, ram_matrices)
-    test_params_api(model, ram_matrices)
-
-    test_vars_api(implied(model), ram_matrices)
-    test_params_api(implied(model), ram_matrices)
-
-    @test @inferred(loss(model)) isa SemLoss
-    semloss = loss(model).functions[1]
-    @test semloss isa SemWLS
-
-    @test @inferred(nsamples(model)) == nsamples(obs)
-end