docs upd

README.md

@@ -7,12 +7,12 @@
 [![GitHub license](https://img.shields.io/github/license/insysbio/LikelihoodProfiler.jl.svg)](https://github.com/insysbio/LikelihoodProfiler.jl/blob/master/LICENSE)
 [![DOI:10.1371/journal.pcbi.1008495](https://zenodo.org/badge/DOI/10.1371/journal.pcbi.1008495.svg)](https://doi.org/10.1371/journal.pcbi.1008495)
 
-**LikelihoodProfiler** is a [Julia language](https://julialang.org/downloads/) package for [identifiability analysis](https://en.wikipedia.org/wiki/Identifiability_analysis) and confidence intervals evaluation.
+**LikelihoodProfiler** is a [Julia language](https://julialang.org/downloads/) package for [identifiability analysis](https://en.wikipedia.org/wiki/Identifiability_analysis) and confidence intervals estimation.
 
 See [documentation](https://insysbio.github.io/LikelihoodProfiler.jl/latest/).
 
-## Cases
-Cases notebooks have been removed to separate repository: <https://github.com/insysbio/likelihoodprofiler-cases>
+## Use cases
+Notebooks with use cases can be found in a separate repository: <https://github.com/insysbio/likelihoodprofiler-cases>
 
  Case | Ref
  ----|----
@@ -29,7 +29,7 @@ Cases notebooks have been removed to separate repository: <https://github.com/in
 ```julia
 julia> ]
 
-(v1.2) pkg> add LikelihoodProfiler
+(v1.5) pkg> add LikelihoodProfiler
 ```
 
 ## Quick start
@@ -62,7 +62,7 @@ plot(res_1)
 
 [MIT](./LICENSE) Public license
 
-## How to site
+## How to cite
 
 **Borisov I, Metelkin E** (2020) *Confidence intervals by constrained optimization—An algorithm and software package for practical identifiability analysis in systems biology.* PLoS Comput Biol 16(12): e1008495.
 

docs/make.jl

@@ -1,13 +1,15 @@
 
-using Documenter, LikelihoodProfiler
+using LikelihoodProfiler
+using Documenter
 
 makedocs(
     modules = [LikelihoodProfiler],
-    sitename = "LikelihoodProfiler.jl",
+    sitename = "LikelihoodProfiler Documentation",
     pages = [
         "Home" => "index.md",
         "Methods" => "methods.md",
         "Visualization" => "visualization.md",
+        "Optimizers" => "optimizers.md",
         "API" => "api.md",
     ],
 )

docs/mkdocs.yml

@@ -1,6 +1,6 @@
 site_name:        LikelihoodProfiler.jl
 repo_url:         https://github.com/insysbio/LikelihoodProfiler.jl
-site_description: A Julia package for identifiability analysis and confidence intervals evaluation.
+site_description: A Julia package for identifiability analysis and confidence intervals estimation.
 site_author:      InSysBio
 
 theme: readthedocs

docs/src/index.md

@@ -2,8 +2,8 @@
 
 **LikelihoodProfiler** is a [Julia](https://julialang.org/downloads/) package for **identifiability analysis** and **confidence intervals** evaluation.
 
-## Cases
-Cases notebooks have been removed to separate repository: <https://github.com/insysbio/likelihoodprofiler-cases>
+## Use cases
+Notebooks with use cases can be found in a separate repository: <https://github.com/insysbio/likelihoodprofiler-cases>
 
  Case | Ref
  ----|----
@@ -33,10 +33,10 @@ f(x) = 5.0 + (x[1]-3.0)^2 + (x[1]-x[2]-1.0)^2 + 0*x[3]^2
 # Calculate parameters intervals for first parameter component, x[1]
 res_1 = get_interval(
   [3., 2., 2.1], # starting point
-  1,             # parameter component
+  1,             # index of parameter
   f,             # profile function
   :LIN_EXTRAPOL; # method
-  loss_crit = 9. # critical level
+  loss_crit = 9. # likelihood confidence level
   )
 #
 
@@ -50,24 +50,24 @@ plot(res_1)
 
 ## Intro
 
-The reliability and predictability of a **kinetic systems biology (SB) and systems pharmacology (SP) model** depends on the calibration of model parameters. Taking into account the lacking of data and the experimental variability the value of any parameter determined unambiguously. This results in characterization of parameter by "confidence intervals" or even "non-identifiable" parameters when the confidence interval is open. The package includes algorithms to perform practical identifiability analysis and evaluation confidence intervals using Profile Likelihood [2] which can be applied to complex SB/SP models. Results of the identifiability analysis can be used to qualify and calibrate parameters or to reduce the model.
+The reliability and predictability of a **kinetic systems biology (SB) and systems pharmacology (SP) model** depends on the calibration of model parameters. Experimental data can be insufficient to determine all the parameters unambiguously. This results in "non-identifiable" parameters and parameters identifiable within confidence intervals (CIs). The algorithms included in **LikelihoodProfiler** implement Profile Likelihood (PL) [2] method for parameters identification and can be applied to complex SB models. The results of the algorithms can be used to qualify and calibrate parameters or to reduce the model.
 
 ## Objective
 
-The package introduces several original algorithms taking into account the following points:
+The package introduces several original algorithms. The default algorithm `:CICO_ONE_PASS` has been developed in accordance with the following principles:
 
-- This algorithm does not assume that the likelihood function is differentiable at any point. This allows using derivation free and global methods of optimization which do not require the calculation of gradients.
-- The calculation of likelihood function is the most computationally expensive operation within the others. It becomes critical for large dynamic model used nowadays in systems biology.
-- The algorithm should calculate the confidence endpoint with the selected tolerance and must be optimal regarding likelihood function calls. The intermediate (non-endpoint) profile points is not important.
-- The algorithm should be stable for calculation both finite and infinite intervals. They should stop immediately (with the corresponding status) if parameter is not identifiable.
+- The algorithms don't require the likelihood function to be differentiable. Hence, derivative-free or global optimization methods can be used to estimate CI endpoints.
+- The algorithms are designed to obtain CI endpoints and avoid the calculation of profiles as the most computationally expensive part of the analysis. 
+- CI endpoints are estimates with some preset tolerance. Reasonable tolerance setup can also reduce the number of likelihood function calls and speed up the computations. 
+- The algorithm are applicable for both finite and infinite CI.
 
 ## Methods overview
 
 This algorithms can be applied to complex kinetic models where function differentiability is not guaranteed and each likelihood estimation is computationally expensive.  
 
 The package introduces original "one-pass" algorithm: **Confidence Intervals evaluation by Constrained Optimization** [6]  `:CICO_ONE_PASS` developed by the authors of this package. `:CICO_ONE_PASS` utilizes the **Inequality-based Constrained Optimization** [3-4] for efficient determination of confidence intervals and detection of “non-identifiable” parameters.  
 
-The "multi-pass" methods use extrapolation/interpolation of likelihood points to the critical level: linear (`:LIN_EXTRAPOL`) and quadratic (`:QUADR_EXTRAPOL`) approaches. They are also effective for both identifiable and non-identifiable parameters.
+The "multi-pass" methods use extrapolation/interpolation of profile likelihood points: linear (`:LIN_EXTRAPOL`) and quadratic (`:QUADR_EXTRAPOL`) approaches. They are also efficient for both identifiable and non-identifiable parameters.
 
 ## References
 

docs/src/methods.md

@@ -4,22 +4,21 @@
  `:LIN_EXTRAPOL`,
  `:QUADR_EXTRAPOL`.
 
-All the methods are wrapped by `get_endpoint` interface where the argument `method` should be initiated by one of the possible values. `get_endpoint` provides also the additional mechanism for better optimization by transforming the parameters to log/logit scales.
+The main function for CI endpoints estimation is `get_interval` (see API section). Estimation method is defined by the keyword argument `method`. It supports one of the above values. Default is `:CICO_ONE_PASS`.
 
 ## :CICO\_ONE\_PASS
 
-The method uses the one-pass calculation of confidence interval endpoint, i.e. one
-optimization is required for single endpoint. It utilizes the **Inequality-based Constrained Optimization**
+The method uses the one-pass calculation of confidence interval endpoint and  utilizes **Inequality-based Constrained Optimization**
 for efficient determination of confidence intervals and detection of “non-identifiable” parameters.
 
- The method internally calls [`NLopt`](https://nlopt.readthedocs.io/en/latest/) algorithm to build an **objective function** with [`LN_AUGLAG`](https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/#augmented-lagrangian-algorithm) algorithm.
+ The method internally calls [`NLopt`](https://nlopt.readthedocs.io/en/latest/) algorithm to build an **augmented objective function** with [`LN_AUGLAG`](https://nlopt.readthedocs.io/en/latest/NLopt_Algorithms/#augmented-lagrangian-algorithm) algorithm. Optimization algorithm choice is described in Optimizers section.
 
 ## :LIN_EXTRAPOL
 
-The method uses multi-pass approach creating profile likelihood function and evaluating
-next step as linear extrapolation: `y = a*x + b`.
+The method examines profile likelihood function by making steps in both directions from the optima. 
+Each step is derived as a linear extrapolation: `y = a*x + b`.
 
 ## :QUADR_EXTRAPOL
 
-The method uses multi-pass approach creating profile likelihood function and evaluating
-next step as quadratic extrapolation: `y = x^2*a + x*b + c`.
+The method examines profile likelihood function by making steps in both directions from the optima. 
+Each step is derived as a quadratic extrapolation: `y = x^2*a + x*b + c`.

docs/src/optimizers.md

@@ -0,0 +1,5 @@
+# Note on optimizers
+
+Currently **LikelihoodProfiler** relies on [`NLopt`](https://nlopt.readthedocs.io/en/latest/). 
+
+Internally **LikelihoodProfiler** utilizes `:LN_AUGLAG` algorithm from **NLopt** to construct an augmented objective function. Then the augmented objective function with no constraints is passed to an optimization algorithm, which is defined by the keyword argument `local_alg` (see [`LikelihoodProfiler.get_interval`](@ref)). Default is `:LN_NELDERMEAD`, which is the most reliable for the current problem among the derivative-free algorithms. The following gradien based algorithms have also shown good relsults on test problems (see /test/test_grad_algs.jl): `:LD_MMA`, `:LD_SLSQP`, `:LD_CCSAQ`.

docs/src/visualization.md

@@ -1,11 +1,11 @@
 # Visualization
 
-[`LikelihoodProfiler.get_interval`](@ref) function outputs estimated
+[`LikelihoodProfiler.get_interval`](@ref) function returns estimated
 confidence interval along with other data as
 [`LikelihoodProfiler.ParamInterval`](@ref) structure.
 
 **LikelihoodProfiler** provides a `@recipe` for **Plots.jl** to visualize
-confidence interval estimation and plot parameter profile based on
+confidence interval estimation and plot parameter's profile based on
 [`LikelihoodProfiler.ParamInterval`](@ref).
 
 ```
@@ -32,7 +32,7 @@ plot(res[2])
 
 ![](https://github.com/insysbio/LikelihoodProfiler.jl/blob/master/img/plot_cico.png?raw=true)
 
-To make a smooth plot compute more profile points using [`LikelihoodProfiler.update_profile_points!`](@ref) which internally uses [`PlotUtils.adapted_grid`](https://github.com/JuliaPlots/PlotUtils.jl/blob/master/src/adapted_grid.jl)
+To make a smooth plot one can compute more profile points with [`LikelihoodProfiler.update_profile_points!`](@ref) which internally uses [`PlotUtils.adapted_grid`](https://github.com/JuliaPlots/PlotUtils.jl/blob/master/src/adapted_grid.jl)
 
 ```
 update_profile_points!(res[2])