API references

solve(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: If true, re-optimizes the model at the provided initial parameter values optpars before profiling. Defaults to false.
• 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 to 1e4.
• verbose::Bool: Indicates whether to display the progress of the profiling process. Defaults to false.

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)

chi2_quantile(α, df=1)

Computes α quantile for Chi2 distribution with df degrees of freedom

CICOProfiler

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 to 1e-3.

Example

profiler = CICOProfiler(optimizer = :LN_NELDERMEAD, scan_tol = 1e-3)

FixedStep{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.

FunctionTarget{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})

IntegrationProfiler{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 the integrator. Defaults to false.
• optimizer::opType: The optimizer used for the optimization process. Defaults to nothing.
• optimizer_opts::optsType: Options for the optimizer. Defaults to NamedTuple().
• integrator::DEAlg: The differential equation algorithm used for integration.
• integrator_opts::DEOpts: Options for the differential equation solver. Defaults to NamedTuple().
• 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 to 1.0.

Example

using OrdinaryDiffEq
profiler = IntegrationProfiler(integrator = Tsit5(), integrator_opts = (dtmax=0.3,), matrix_type = :hessian)

InterpolationLineSearch

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.

LineSearchStep{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.
  The choice affects how the next step is proposed in parameter space.
• linesearch::L=InterpolationLineSearch(): Line search algorithm (e.g., InterpolationLineSearch()).

OptimizationProfiler{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 the direction keyword argument.
• optimizer::opType: The optimizer used for the optimization process.
• optimizer_opts::optsType: Options for the optimizer. Defaults to NamedTuple().

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,))

ParameterTarget{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})

ProfileLikelihoodProblem{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

1. 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 (see ParameterTarget) or FunctionTarget (see FunctionTarget) defining what to profile and the profile bounds.
• conf_level: Confidence level for the profile likelihood. Defaults to 0.95.
• df: Degrees of freedom for the profile likelihood. Defaults to 1.
• threshold: Profile likelihood threshold. If not provided, computed from conf_level and df. Can be set to Inf if confidence interval endpoint estimation is not required.

1. 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; if nothing, taken from optprob. If scalar bounds are provided, they will be expanded to match the number of parameters being profiled.
• kwargs...: passed to the explicit target constructor.

1. 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.

ProfileLikelihoodSolution{probType,P}

Contains the results of a profile likelihood analysis.

Fields

• prob::probType: The profile likelihood problem ProfileLikelihoodProblem.
• 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 the threshold.
• retcodes(sol[i]): Returns the retcodes of the CI endpoints estimation.
• stats(sol[i]): Returns the statistics of the profile computation.