fixup SemEns: docs

Author: Alexey Stukalov

src/implied/empty.jl

@@ -13,8 +13,8 @@ Empty placeholder for models that don't need an implied part.
 - `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
 

src/objective_gradient_hessian.jl

@@ -24,26 +24,33 @@ is_hessian_required(::EvaluationTargets{<:Any, <:Any, H}) where {H} = H
 (targets::EvaluationTargets)(arg_tuple::Tuple) = targets(arg_tuple...)
 
 """
-    evaluate!(objective, gradient, hessian [, lossfun], model, params)
+    evaluate!(objective, gradient, hessian, loss::AbstractLoss, params)
+    evaluate!(objective, gradient, hessian, model::AbstractSem, params)
 
 Evaluates the objective, gradient, and/or Hessian at the given parameter vector.
-If a loss function is passed, only this specific loss function is evaluated, otherwise,
-the sum of all loss functions in the model is evaluated.
+
+If a single loss term (`loss`) is passed, only this specific term is evaluated,
+otherwise, if the entire SEM `model` is passed, the weighted sum of all loss terms
+in the model is evaluated.
 
 If objective, gradient or hessian are `nothing`, they are not evaluated.
 For example, since many numerical optimization algorithms don't require a Hessian,
-the computation will be turned off by setting `hessian` to `nothing`.
+its computation will be turned off by setting `hessian` to `nothing`.
+
+During the evaluation, the internal state of the loss term or of the model
+could be modified.
 
 # Arguments
 - `objective`: a Number if the objective should be evaluated, otherwise `nothing`
 - `gradient`: a pre-allocated vector the gradient should be written to, otherwise `nothing`
 - `hessian`: a pre-allocated matrix the Hessian should be written to, otherwise `nothing`
-- `lossfun::SemLossFunction`: loss function to evaluate
+- `loss::AbstractLoss`: loss function to evaluate
 - `model::AbstractSem`: model to evaluate
 - `params`: vector of parameters
 
 # Implementing a new loss function
-To implement a new loss function, a new method for `evaluate!` has to be defined.
+To implement a new loss (subtype of `SemLoss` for SEM terms, or of `AbstractLoss` for
+regularization terms), a new method for `evaluate!` has to be defined.
 This is explained in the online documentation on [Custom loss functions](@ref).
 """
 function evaluate! end
@@ -191,43 +198,33 @@ hessian!(model::AbstractSemOrLoss, par, model) =
 """
     objective!(model::AbstractSem, params)
 
-Returns the objective value at `params`.
-The model object can be modified.
+Calculates the objective value at `params`.
 
-# Implementation
-To implement a new `SemImplied` or `SemLossFunction` subtype, you need to add a method for
-    objective!(newtype::MyNewType, params, model::AbstractSemSingle)
+The model object can be modified during calculation.
 
-To implement a new `AbstractSem` subtype, you need to add a method for
-    objective!(model::MyNewType, params)
+See also [`evaluate!`](@ref).
 """
 function objective! end
 
 """
     gradient!(gradient, model::AbstractSem, params)
 
-Writes the gradient value at `params` to `gradient`.
+Calculates the model's gradient at `params` and writes it to `gradient`.
 
-# Implementation
-To implement a new `SemImplied` or `SemLossFunction` type, you can add a method for
-    gradient!(newtype::MyNewType, params, model::AbstractSemSingle)
+The model object can be modified during calculation.
 
-To implement a new `AbstractSem` subtype, you can add a method for
-    gradient!(gradient, model::MyNewType, params)
+See also [`evaluate!`](@ref).
 """
 function gradient! end
 
 """
     hessian!(hessian, model::AbstractSem, params)
 
-Writes the hessian value at `params` to `hessian`.
+Calculates the model's hessian at `params` and writes it to `hessian`.
 
-# Implementation
-To implement a new `SemImplied` or `SemLossFunction` type, you can add a method for
-    hessian!(newtype::MyNewType, params, model::AbstractSemSingle)
+The model object can be modified during calculation.
 
-To implement a new `AbstractSem` subtype, you can add a method for
-    hessian!(hessian, model::MyNewType, params)
+See also [`evaluate!`](@ref).
 """
 function hessian! end
 

src/types.jl

@@ -37,6 +37,8 @@ abstract type SemOptimizer{E} end
 abstract type SemOptimizerResult{O <: SemOptimizer} end
 
 """
+    abstract type SemObserved
+
 Supertype of all objects that can serve as the observed field of a SEM.
 Pre-processes data and computes sufficient statistics for example.
 If you have a special kind of data, e.g. ordinal data, you should implement a subtype of SemObserved.
@@ -55,7 +57,7 @@ abstract type SemImplied end
 abstract type SemImpliedSymbolic <: SemImplied end
 
 """
-    Sem(;observed = SemObservedData, implied = RAM, loss = SemML, kwargs...)
+    abstract type SemLoss{O <: SemObserved, I <: SemImplied} <: AbstractLoss
 
 The base type for calculating the loss of the implied SEM model when explaining the observed data.
 
@@ -65,7 +67,11 @@ All subtypes of `SemLoss` should have the following fields:
 """
 abstract type SemLoss{O <: SemObserved, I <: SemImplied} <: AbstractLoss end
 
-"Most abstract supertype for all SEMs"
+"""
+    abstract type AbstractSem
+
+The base type for all SEMs.
+"""
 abstract type AbstractSem end
 
 """
@@ -83,9 +89,12 @@ end
 """
     Sem(loss_terms...; [params], kwargs...)
 
-SEM model (including model ensembles) that combines all the data, implied SEM structure
-and regularization terms and implements the calculation of their weighted sum, as well as its
-gradient and (optionally) Hessian.
+SEM model (including multi-group SEMs) that combines all the data, implied SEM structure
+and regularization terms.
+
+All terms of the `Sem` object share the same set of parameters.
+`Sem` implements the calculation of the weighted sum of its terms (the *objective*
+function), as well as the gradient and Hessian of this sum.
 
 # Arguments
 - `loss_terms...`: [`AbstractLoss`](@ref) objects, including SEM losses ([`SemLoss`](@ref)),
@@ -107,8 +116,12 @@ end
 """
     SemFiniteDiff(model::AbstractSem)
 
-A wrapper around [`Sem`](@ref) that substitutes dedicated evaluation of gradient and hessian with
-finite difference approximation.
+A wrapper around [`AbstractSem`](@ref) that substitutes dedicated evaluation of gradient and
+hessian with finite difference approximation.
+
+`SemFiniteDiff` could be used to enable gradient-based optimization of the SEM models
+when the dedicated calculation of gradient and hessian are not available.
+For approximation, it uses the *FiniteDiff.jl* package.
 
 # Arguments
 - `model::Sem`: the SEM model to wrap
@@ -126,6 +139,8 @@ struct SemLossFiniteDiff{O, I, L <: SemLoss{O, I}} <: SemLoss{O, I}
 end
 
 """
+    abstract type SemSpecification end
+
 Base type for all SEM specifications.
 """
 abstract type SemSpecification end