Documentation/fix docstrings (#260)

Clean code, fix docstrings, fix docs

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.4.0"
+version = "0.4.1"
 
 [deps]
 DataFrames = "a93c6f00-e57d-5684-b7b6-d8193f3e46c0"

README.md

@@ -39,7 +39,7 @@ The package makes use of
 - 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.
+- FiniteDiff.jl and to provide gradient approximations for user-defined loss functions.
 
 # At the moment, we are still working on:
 - optimizing performance for big models (with hundreds of parameters)

docs/make.jl

@@ -52,7 +52,6 @@ makedocs(
             "files" => "internals/files.md",
             "types" => "internals/types.md",
         ],
-        "Complementary material" => ["Mathematical appendix" => "complementary/maths.md"],
     ],
     format = Documenter.HTML(
         prettyurls = get(ENV, "CI", nothing) == "true",

docs/src/developer/implied.md

@@ -62,11 +62,8 @@ model per group and an additional model with `ImpliedEmpty` and `SemRidge` for t
 # Extended help
 
 ## Interfaces
-- `params(::RAMSymbolic) `-> Vector of parameter labels
-- `nparams(::RAMSymbolic)` -> Number of parameters
-
-## Implementation
-Subtype of `SemImplied`.
+- `param_labels(::ImpliedEmpty) `-> Vector of parameter labels
+- `nparams(::ImpliedEmpty)` -> Number of parameters
 """
 struct ImpliedEmpty{A, B, C} <: SemImplied
     hessianeval::A
@@ -78,7 +75,12 @@ end
 ### Constructors
 ############################################################################################
 
-function ImpliedEmpty(;specification, meanstruct = NoMeanStruct(), hessianeval = ExactHessian(), kwargs...)
+function ImpliedEmpty(;
+    specification,
+    meanstruct = NoMeanStruct(),
+    hessianeval = ExactHessian(),
+    kwargs...,
+)
     return ImpliedEmpty(hessianeval, meanstruct, convert(RAMMatrices, specification))
 end
 

docs/src/developer/loss.md

@@ -204,7 +204,7 @@ julia>?
 
 help?> RAM
 
-help?> SemObservedCommon
+help?> SemObservedData
 ```
 
 We see that the model implied covariance matrix can be assessed as `Σ(implied)` and the observed covariance matrix as `obs_cov(observed)`.

docs/src/developer/observed.md

@@ -28,8 +28,8 @@ nsamples(observed::MyObserved) = ...
 nobserved_vars(observed::MyObserved) = ...
 ```
 
-As always, you can add additional methods for properties that implied 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 `SemObservedData` implementation):
 
 ```julia
-obs_cov(observed::SemObservedCommon) = observed.obs_cov
+obs_cov(observed::SemObservedData) = observed.obs_cov
 ```

docs/src/developer/optimizer.md

@@ -37,13 +37,13 @@ options(optimizer::SemOptimizerName) = optimizer.options
 Note that your optimizer is a subtype of `SemOptimizer{:Name}`, where you can choose a `:Name` that can later be used as a keyword argument to `fit(engine = :Name)`.
 Similarly, `SemOptimizer{:Name}(args...; kwargs...) = SemOptimizerName(args...; kwargs...)` should be defined as well as a constructor that uses only keyword arguments:
 
-´´´julia
+```julia
 SemOptimizerName(;
     algorithm = LBFGS(),
     options = Optim.Options(; f_tol = 1e-10, x_tol = 1.5e-8),
     kwargs...,
 ) = SemOptimizerName(algorithm, options)
-´´´
+```
 A method for `update_observed` and additional methods might be usefull, but are not necessary.
 
 Now comes the substantive part: We need to provide a method for `fit`:

docs/src/internals/files.md

@@ -10,7 +10,7 @@ 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"`, `"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).
+- The folders `"observed"`, `"implied"`, and `"loss"` 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 `fit`)
     - `"optim.jl"`: connection to the `Optim.jl` package
 - `"frontend"` contains user-facing functions

docs/src/internals/internals.md

@@ -1,3 +1,3 @@
 # Internals and Design
 
-On the following pages, we document the internals and design of the package. Those informations are no prerequisite for extending the package (as decribed in the developer documentation)!, but they may be useful and hopefully interesting.
+On the following pages, we document some technical information about the package. Those informations are no prerequisite for extending the package (as decribed in the developer documentation)!, but they may be useful.

docs/src/performance/simulation.md

@@ -1,9 +1,5 @@
 # Simulation studies
 
-!!! note "Simulation study interface"
-    We are currently working on an interface for simulation studies.
-    Until we are finished with this, this page is just a collection of tips.
-
 ## Replace observed data
 In simulation studies, a common task is fitting the same model to many different datasets.
 It would be a waste of resources to reconstruct the complete model for each dataset.