Multiple refactorings reformatted

Project.toml

@@ -13,8 +13,10 @@ LineSearches = "d3d80556-e9d4-5f37-9878-2ab0fcc64255"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
 NLSolversBase = "d41bc354-129a-5804-8e4c-c37616107c6c"
 Optim = "429524aa-4258-5aef-a3af-852621145aeb"
+PackageExtensionCompat = "65ce6f38-6b18-4e1d-a461-8949797d7930"
 Pkg = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"
 PrettyTables = "08abe8d2-0d0c-5749-adfa-8a2ac140af0d"
+Printf = "de0858da-6303-5e67-8744-51eddeeeb8d7"
 Random = "9a3f8284-a2c9-5f02-9a11-845980a1fd5c"
 SparseArrays = "2f01184e-e22b-5df5-ae63-d93ebab69eaf"
 Statistics = "10745b16-79ce-11e8-11f9-7d13ad32a3b2"
@@ -46,11 +48,14 @@ Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 test = ["Test"]
 
 [weakdeps]
+BlackBoxOptim = "a134a8b2-14d6-55f6-9291-3336d3ab0209"
 NLopt = "76087f3c-5699-56af-9a33-bf431cd00edd"
+Optimisers = "3bd65402-5787-11e9-1adc-39752487f4e2"
 ProximalAlgorithms = "140ffc9f-1907-541a-a177-7475e0a401e9"
 ProximalCore = "dc4f5ac2-75d1-4f31-931e-60435d74994b"
 ProximalOperators = "a725b495-10eb-56fe-b38b-717eba820537"
 
 [extensions]
 SEMNLOptExt = "NLopt"
 SEMProximalOptExt = ["ProximalCore", "ProximalAlgorithms", "ProximalOperators"]
+SEMBlackBoxOptimExt = ["BlackBoxOptim", "Optimisers"]

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/developer/imply.md → docs/src/developer/implied.md

@@ -1,11 +1,11 @@
-# Custom imply types
+# 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.
 
-Imply types are of subtype `SemImply`. To implement your own imply type, you should define a struct
+Implied types are of subtype `SemImplied`. To implement your own implied type, you should define a struct
 
 ```julia
-struct MyImply <: SemImply
+struct MyImplied <: SemImplied
     ...
 end
 ```
@@ -15,37 +15,37 @@ and at least a method to compute the objective
 ```julia
 import StructuralEquationModels: objective!
 
-function objective!(imply::MyImply, par, model::AbstractSemSingle)
+function objective!(implied::MyImplied, par, model::AbstractSemSingle)
     ...
     return nothing
 end
 ```
 
-This method should compute and store things you want to make available to the loss functions, and returns `nothing`. For example, as we have seen in [Second example - maximum likelihood](@ref), the `RAM` imply type computes the model-implied covariance matrix and makes it available via `Σ(imply)`.
-To make stored computations available to loss functions, simply write a function - for example, for the `RAM` imply type we defined
+This method should compute and store things you want to make available to the loss functions, and returns `nothing`. 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)`.
+To make stored computations available to loss functions, simply write a function - for example, for the `RAM` implied type we defined
 
 ```julia
-Σ(imply::RAM) = imply.Σ
+Σ(implied::RAM) = implied.Σ
 ```
 
 Additionally, you can specify methods for `gradient` and `hessian` as well as the combinations described in [Custom loss functions](@ref).
 
-The last thing nedded to make it work is a method for `nparams` that takes your imply type and returns the number of parameters of the model:
+The last thing nedded to make it work is a method for `nparams` that takes your implied type and returns the number of parameters of the model:
 
 ```julia
-nparams(imply::MyImply) = ...
+nparams(implied::MyImplied) = ...
 ```
 
 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 `ImplyEmpty` type in our package that does nothing but serving as an imply field in case you are using a loss function that does not need any imply type at all. You may use it as a template for defining your own imply type, as it also shows how to handle the specification objects:
+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
 ############################################################################
 
-struct ImplyEmpty{V, V2} <: SemImply
+struct ImpliedEmpty{V, V2} <: SemImplied
     identifier::V2
     n_par::V
 end
@@ -54,7 +54,7 @@ end
 ### Constructors
 ############################################################################
 
-function ImplyEmpty(;
+function ImpliedEmpty(;
         specification,
         kwargs...)
 
@@ -63,25 +63,25 @@ function ImplyEmpty(;
 
         n_par = length(ram_matrices.parameters)
 
-        return ImplyEmpty(identifier, n_par)
+        return ImpliedEmpty(identifier, n_par)
 end
 
 ############################################################################
 ### methods
 ############################################################################
 
-objective!(imply::ImplyEmpty, par, model) = nothing
-gradient!(imply::ImplyEmpty, par, model) = nothing
-hessian!(imply::ImplyEmpty, par, model) = nothing
+objective!(implied::ImpliedEmpty, par, model) = nothing
+gradient!(implied::ImpliedEmpty, par, model) = nothing
+hessian!(implied::ImpliedEmpty, par, model) = nothing
 
 ############################################################################
 ### Recommended methods
 ############################################################################
 
-identifier(imply::ImplyEmpty) = imply.identifier
-n_par(imply::ImplyEmpty) = imply.n_par
+identifier(implied::ImpliedEmpty) = implied.identifier
+n_par(implied::ImpliedEmpty) = implied.n_par
 
-update_observed(imply::ImplyEmpty, observed::SemObserved; kwargs...) = imply
+update_observed(implied::ImpliedEmpty, observed::SemObserved; kwargs...) = implied
 ```
 
 As you see, similar to [Custom loss functions](@ref) we implement a method for `update_observed`. Additionally, you should store the `identifier` from the specification object and write a method for `identifier`, as this will make it possible to access parameter indices by label.

docs/src/developer/loss.md

@@ -171,7 +171,7 @@ function MyLoss(;arg1 = ..., arg2, kwargs...)
 end
 ```
 
-All keyword arguments that a user passes to the Sem constructor are passed to your loss function. In addition, all previously constructed parts of the model (imply and observed part) are passed as keyword arguments as well as the number of parameters `n_par = ...`, so your constructor may depend on those. For example, the constructor for `SemML` in our package depends on the additional argument `meanstructure` as well as the observed part of the model to pre-allocate arrays of the same size as the observed covariance matrix and the observed mean vector: 
+All keyword arguments that a user passes to the Sem constructor are passed to your loss function. In addition, all previously constructed parts of the model (implied and observed part) are passed as keyword arguments as well as the number of parameters `n_par = ...`, so your constructor may depend on those. For example, the constructor for `SemML` in our package depends on the additional argument `meanstructure` as well as the observed part of the model to pre-allocate arrays of the same size as the observed covariance matrix and the observed mean vector:
 
 ```julia
 function SemML(;observed, meanstructure = false, approx_H = false, kwargs...)
@@ -221,9 +221,9 @@ To keep it simple, we only cover models without a meanstructure. The maximum lik
 F_{ML} = \log \det \Sigma_i + \mathrm{tr}\left(\Sigma_{i}^{-1} \Sigma_o \right)
 ```
 
-where ``\Sigma_i`` is the model implied covariance matrix and ``\Sigma_o`` is the observed covariance matrix. We can query the model implied covariance matrix from the `imply` par of our model, and the observed covariance matrix from the `observed` path of our model.
+where ``\Sigma_i`` is the model implied covariance matrix and ``\Sigma_o`` is the observed covariance matrix. We can query the model implied covariance matrix from the `implied` par of our model, and the observed covariance matrix from the `observed` path of our model.
 
-To get information on what we can access from a certain `imply` or `observed` type, we can check it`s documentation an the pages [API - model parts](@ref) or via the help mode of the REPL:
+To get information on what we can access from a certain `implied` or `observed` type, we can check it`s documentation an the pages [API - model parts](@ref) or via the help mode of the REPL:
 
 ```julia
 julia>?
@@ -233,7 +233,7 @@ help?> RAM
 help?> SemObservedCommon
 ```
 
-We see that the model implied covariance matrix can be assessed as `Σ(imply)` and the observed covariance matrix as `obs_cov(observed)`.
+We see that the model implied covariance matrix can be assessed as `Σ(implied)` and the observed covariance matrix as `obs_cov(observed)`.
 
 With this information, we write can implement maximum likelihood optimization as
 
@@ -245,7 +245,7 @@ import StructuralEquationModels: Σ, obs_cov, objective!
 
 function objective!(semml::MaximumLikelihood, parameters, model::AbstractSem)
     # access the model implied and observed covariance matrices
-    Σᵢ = Σ(imply(model))
+    Σᵢ = Σ(implied(model))
     Σₒ = obs_cov(observed(model))
     # compute the objective
     if isposdef(Symmetric(Σᵢ)) # is the model implied covariance matrix positive definite?

docs/src/developer/observed.md

@@ -28,7 +28,7 @@ nsamples(observed::MyObserved) = ...
 nobserved_vars(observed::MyObserved) = ...
 ```
 
-As always, you can add additional methods for properties that imply types and loss function want to access, for example (from the `SemObservedCommon` implementation):
+As always, you can add additional methods for properties that implied types and loss function want to access, for example (from the `SemObservedCommon` implementation):
 
 ```julia
 obs_cov(observed::SemObservedCommon) = observed.obs_cov

docs/src/developer/sem.md

@@ -1,15 +1,15 @@
 # Custom model types
 
-The abstract supertype for all models is `AbstractSem`, which has two subtypes, `AbstractSemSingle{O, I, L, D}` and `AbstractSemCollection`. Currently, there are 2 subtypes of `AbstractSemSingle`: `Sem`, `SemFiniteDiff`. All subtypes of `AbstractSemSingle` should have at least observed, imply, loss and optimizer fields, and share their types (`{O, I, L, D}`) with the parametric abstract supertype. For example, the `SemFiniteDiff` type is implemented as
+The abstract supertype for all models is `AbstractSem`, which has two subtypes, `AbstractSemSingle{O, I, L, D}` and `AbstractSemCollection`. Currently, there are 2 subtypes of `AbstractSemSingle`: `Sem`, `SemFiniteDiff`. All subtypes of `AbstractSemSingle` should have at least observed, implied, loss and optimizer fields, and share their types (`{O, I, L, D}`) with the parametric abstract supertype. For example, the `SemFiniteDiff` type is implemented as
 
 ```julia
 struct SemFiniteDiff{
-        O <: SemObserved, 
-        I <: SemImply, 
-        L <: SemLoss, 
+        O <: SemObserved,
+        I <: SemImplied,
+        L <: SemLoss,
         D <: SemOptimizer} <: AbstractSemSingle{O, I, L, D}
     observed::O
-    imply::I
+    implied::I
     loss::L
     optimizer::D
 end
@@ -19,13 +19,13 @@ Additionally, we need to define a method to compute at least the objective value
 
 ```julia
 function objective!(model::AbstractSemSingle, parameters)
-    objective!(imply(model), parameters, model)
+    objective!(implied(model), parameters, model)
     return objective!(loss(model), parameters, model)
 end
 
 function gradient!(gradient, model::AbstractSemSingle, parameters)
     fill!(gradient, zero(eltype(gradient)))
-    gradient!(imply(model), parameters, model)
+    gradient!(implied(model), parameters, model)
     gradient!(gradient, loss(model), parameters, model)
 end
 ```

docs/src/internals/files.md

@@ -10,7 +10,7 @@ All source code is in the `"src"` folder:
 - `"StructuralEquationModels.jl"` defines the module and the exported objects
 - `"types.jl"` defines all abstract types and the basic type hierarchy
 - `"objective_gradient_hessian.jl"` contains methods for computing objective, gradient and hessian values for different model types as well as generic fallback methods
-- The four folders `"observed"`, `"imply"`, `"loss"` and `"diff"` contain implementations of specific subtypes (for example, the `"loss"` folder contains a file `"ML.jl"` that implements the `SemML` loss function).
+- The four folders `"observed"`, `"implied"`, `"loss"` and `"diff"` contain implementations of specific subtypes (for example, the `"loss"` folder contains a file `"ML.jl"` that implements the `SemML` loss function).
 - `"optimizer"` contains connections to different optimization backends (aka methods for `sem_fit`)
     - `"optim.jl"`: connection to the `Optim.jl` package
     - `"NLopt.jl"`: connection to the `NLopt.jl` package

docs/src/internals/types.md

@@ -8,6 +8,6 @@ The type hierarchy is implemented in `"src/types.jl"`.
     - `SemFiniteDiff`: models whose gradients and/or hessians should be computed via finite difference approximation
 - `AbstractSemCollection <: AbstractSem` is an abstract supertype of all models that contain multiple `AbstractSem` submodels
 
-Every `AbstractSemSingle` has to have `SemObserved`, `SemImply`, `SemLoss` and `SemOptimizer` fields (and can have additional fields).
+Every `AbstractSemSingle` has to have `SemObserved`, `SemImplied`, `SemLoss` and `SemOptimizer` fields (and can have additional fields).
 
 `SemLoss` is a container for multiple `SemLossFunctions`.

docs/src/performance/symbolic.md

@@ -13,6 +13,6 @@ If the model is acyclic, we can compute
 ```
 
 for some ``n < \infty``.
-Typically, the ``S`` and ``A`` matrices are sparse. In our package, we offer symbolic precomputation of ``\Sigma``, ``\nabla\Sigma`` and even ``\nabla^2\Sigma`` for acyclic models to optimally exploit this sparsity. To use this feature, simply use the `RAMSymbolic` imply type for your model.
+Typically, the ``S`` and ``A`` matrices are sparse. In our package, we offer symbolic precomputation of ``\Sigma``, ``\nabla\Sigma`` and even ``\nabla^2\Sigma`` for acyclic models to optimally exploit this sparsity. To use this feature, simply use the `RAMSymbolic` implied type for your model.
 
 This can decrase model fitting time, but will also increase model building time (as we have to carry out the symbolic computations and compile specialised functions). As a result, this is probably not beneficial to use if you only fit a single model, but can lead to great improvements if you fit the same modle to multiple datasets (e.g. to compute bootstrap standard errors).