API references
The package exports the following functions for parameters and functions identifiability analysis, confidence intervals evaluation and results visualization.
CommonSolve.solve
— Methodsolve(plprob::ProfileLikelihoodProblem, method::AbstractProfilerMethod;
parallel_type::Symbol=:none, maxiters::Int=1e4, verbose::Bool=false)
Profiles the likelihood function for the given problem plprob
using the specified profiling method
.
Arguments
plprob::ProfileLikelihoodProblem
: The profiling problem instance containing the parameters and likelihood function to be profiled.method::AbstractProfilerMethod
: The method to be used for profiling.reoptimize_init::Bool=false
: Iftrue
, re-optimizes the model at the provided initial parameter valuesoptpars
before profiling. Defaults tofalse
.parallel_type::Symbol
: Specifies the type of parallelism to be used. Supported values::none, :threads, :distributed
. Defaults to:none
.maxiters::Int
: Maximum number of iterations for one branch (left and right) of the profiling process. Defaults to1e4
.verbose::Bool
: Indicates whether to display the progress of the profiling process. Defaults tofalse
.
Returns
- Returns the profiling results
ProfileLikelihoodSolution
.
Example
plprob = ProfileLikelihoodProblem(optprob, optpars; idxs=1, profile_lower=-10., profile_upper=10.)
method = OptimizationProfiler(optimizer = Optimization.LBFGS(), stepper = FixedStep())
sol = solve(plprob, method)
LikelihoodProfiler.chi2_quantile
— Functionchi2_quantile(α, df=1)
Computes α quantile for Chi2 distribution with df degrees of freedom
LikelihoodProfiler.CICOProfiler
— TypeCICOProfiler
Confidence Intervals by Constrained Optimization (CICO) method to find the intersections of the likelihood function with the threshold. See CICOBase docs for more details. Requires using CICOBase
.
Fields
optimizer::Symbol
: The optimizer used for the optimization process. Defaults to NLopt:LN_NELDERMEAD
.scan_tol::Float64
: The tolerance for the endpoints scan. Defaults to1e-3
.
Example
profiler = CICOProfiler(optimizer = :LN_NELDERMEAD, scan_tol = 1e-3)
LikelihoodProfiler.FixedStep
— TypeFixedStep{S}
Profiler stepper that always proposes a fixed step size in the profiling direction.
Constructors
FixedStep(;initial_step=DEFAULT_INIT_STEP)
Keyword arguments
initial_step=DEFAULT_INIT_STEP
: The initial (and constant) step size to use for each profile step. This can be a number (for a constant step size) or a function(pars, idx) -> step
for custom logic depending on the current parameters and index. If a number is provided, it is automatically wrapped as a function.
LikelihoodProfiler.FunctionTarget
— TypeFunctionTarget{F,B}
Profile target representing profiling of functions of model parameters.
Fields
fs::AbstractVector{<:OptimizationFunction}
: Functions of the parameters being profiled.profile_lower::AbstractVector{<:Real}
: Lower bounds for the profile likelihood.profile_upper::AbstractVector{<:Real}
: Upper bounds for the profile likelihood.
Profile bounds profile_lower
and profile_upper
should be vectors of finite numerical values.
Constructors
Create a target with explicit lower and upper bounds for each function of parameters.
FunctionTarget(; fs::AbstractVector{<:OptimizationFunction}, profile_lower::AbstractVector{<:Real}, profile_upper::AbstractVector{<:Real})
LikelihoodProfiler.IntegrationProfiler
— TypeIntegrationProfiler{opType, optsType, DEAlg, DEOpts}
A profiler method that uses integration of differential equations system to profile the likelihood function.
Fields
reoptimize::Bool
: Indicates whether to re-optimization after each step of theintegrator
. Defaults tofalse
.optimizer::opType
: The optimizer used for the optimization process. Defaults tonothing
.optimizer_opts::optsType
: Options for the optimizer. Defaults toNamedTuple()
.integrator::DEAlg
: The differential equation algorithm used for integration.integrator_opts::DEOpts
: Options for the differential equation solver. Defaults toNamedTuple()
.matrix_type::Symbol
: The type of matrix to be used for the Hessian approximation. Possible options are::hessian
,:identity
. Defaults to:hessian
.gamma::Float64
: Correction factor used in integration if full hessian is not computed (e.g.matrix_type = :identity
). Defaults to1.0
.
Example
using OrdinaryDiffEq
profiler = IntegrationProfiler(integrator = Tsit5(), integrator_opts = (dtmax=0.3,), matrix_type = :hessian)
LikelihoodProfiler.InterpolationLineSearch
— TypeInterpolationLineSearch
Interpolation-based line search algorithm used in profile stepping.
Constructors
InterpolationLineSearch(; objective_factor=1.25, step_size_factor=2.0, maxiters=10)
Keyword arguments
objective_factor::Float64 = 1.25
: Factor by which the change in the objective function from the last step is increased/decreased to set the target for the next step.step_size_factor::Float64 = 2.0
: Multiplicative factor for increasing or decreasing the step size during the search.maxiters::Int = 10
: Maximum number of line search iterations allowed.
LikelihoodProfiler.LineSearchStep
— TypeLineSearchStep{S, L}
Profiler stepper that uses a line search to adaptively determine the step size in the direction which is chosen by the direction
keyword argument.
Constructors
LineSearchStep(;initial_step=DEFAULT_INIT_STEP, direction=:Secant, linesearch=InterpolationLineSearch())
Keyword arguments
initial_step=DEFAULT_INIT_STEP
: Initial guess for the step size. Can be a number (for a constant guess) or a function(pars, idx) -> step
for custom logic depending on the current parameters and index. If a number is provided, it is automatically wrapped as a function.direction::Symbol=:Secant
: Strategy for choosing the direction of the next step. Options::SingleAxis
: Move along the current profiling parameter only.:Secant
: Use the secant direction, i.e., the line connecting the last two points in parameter space (Default).:Gradient
: Use the gradient of the objective function as the direction.
linesearch::L=InterpolationLineSearch()
: Line search algorithm (e.g.,InterpolationLineSearch()
).
LikelihoodProfiler.OptimizationProfiler
— TypeOptimizationProfiler{S, opType, optsType}
A profiler method that uses stepwise re-optimization to profile the likelihood function.
Fields
stepper::S
: The algorithm used to compute the next profile point. Supported steppers include:FixedStep
: Proposes a constant step size in the profiling direction (Default).LineSearchStep
: Uses a line search to adaptively determine the step size in the direction which is chosen by thedirection
keyword argument.
optimizer::opType
: The optimizer used for the optimization process.optimizer_opts::optsType
: Options for the optimizer. Defaults toNamedTuple()
.
Stepping Options
The stepper
argument controls how the next profile point is chosen. For example:
stepper = FixedStep(initial_step=0.1)
: Use a constant step size of 0.1.stepper = LineSearchStep(direction=:Secant, linesearch=InterpolationLineSearch())
: Use a line search with secant direction.
See the documentation for each stepper type (e.g., ?FixedStep
, ?LineSearchStep
) for more details and customization options.
Example
using Optimization
profiler = OptimizationProfiler(; optimizer = Optimization.LBFGS(), optimizer_opts = (reltol=1e-4,))
LikelihoodProfiler.ParameterTarget
— TypeParameterTarget{I,B}
Profile target representing profiling of model parameters.
Fields
idxs::AbstractVector{<:Integer}
: Indices of the parameters being profiled.profile_lower::AbstractVector{<:Real}
: Lower bounds for the profile likelihood.profile_upper::AbstractVector{<:Real}
: Upper bounds for the profile likelihood.
Profile bounds profile_lower
and profile_upper
should be vectors of finite numerical values.
Constructors
Create a target with explicit lower and upper bounds for each index.
ParameterTarget(; idxs::AbstractVector{<:Integer}, profile_lower::AbstractVector{<:Real}, profile_upper::AbstractVector{<:Real})
LikelihoodProfiler.ProfileLikelihoodProblem
— TypeProfileLikelihoodProblem{T,probType,P}
Defines a profile likelihood problem.
Mathematical Specification of a Profile Likelihood Problem:
A problem is specified by:
optprob::OptimizationProblem
— wraps your objective (e.g. negative log-likelihood)optpars::AbstractVector{<:Real}
— parameter values to start profiling from (typically the optimum)target::AbstractProfileTarget
— what to profile (parameters or functions)
Constructors
- Explicit target interface (advanced)
ProfileLikelihoodProblem(optprob::OptimizationProblem, optpars::AbstractVector{<:Real}, target::AbstractProfileTarget;
conf_level::Float64 = 0.95, df::Int = 1, threshold::Union{Nothing,Real} = nothing)
target
:ParameterTarget
(seeParameterTarget
) orFunctionTarget
(seeFunctionTarget
) defining what to profile and the profile bounds.conf_level
: Confidence level for the profile likelihood. Defaults to0.95
.df
: Degrees of freedom for the profile likelihood. Defaults to1
.threshold
: Profile likelihood threshold. If not provided, computed fromconf_level
anddf
. Can be set toInf
if confidence interval endpoint estimation is not required.
- Parameter profiling sugar
ProfileLikelihoodProblem(optprob::OptimizationProblem, optpars::AbstractVector{<:Real};
idxs = nothing, profile_lower = nothing, profile_upper = nothing, kwargs...)
idxs
: Indices of parameters to profile; Integer or vector of integers; if nothing, profile all parameters.profile_lower
,profile_upper
: Bounds for profiling. Accept scalars or vectors of finite numbers; ifnothing
, taken fromoptprob
. If scalar bounds are provided, they will be expanded to match the number of parameters being profiled.kwargs...
: passed to the explicit target constructor.
- Function profiling sugar
ProfileLikelihoodProblem(optprob::OptimizationProblem, optpars::AbstractVector{<:Real};
fs = nothing, profile_lower = nothing, profile_upper = nothing, kwargs...)
fs
: OptimizationFunction
or vector of OptimizationFunction
- functions of parameters to be profiled.
profile_lower
,profile_upper
: Bounds for profiling. Accept scalars or vectors of finite numbers. If scalar bounds are provided, they will be expanded to match the number of functions being profiled.kwargs...
: passed to the explicit target constructor.
LikelihoodProfiler.ProfileLikelihoodSolution
— TypeProfileLikelihoodSolution{probType,P}
Contains the results of a profile likelihood analysis.
Fields
prob::probType
: The profile likelihood problemProfileLikelihoodProblem
.profiles::P
: The computed profile curves.elapsed_time::Float64
: The time elapsed during the computation.
Selectors
A number of selectors are available to extract information from the sol::ProfileLikelihoodSolution
object. These can be applied to each computed profile sol[i]
:
endpoints(sol[i])
: Returns the confidence interval (CI) endpoints, marking the intersection of the profile with thethreshold
.retcodes(sol[i])
: Returns the retcodes of the CI endpoints estimation.stats(sol[i])
: Returns the statistics of the profile computation.