API references

solve(plprob::ProfileLikelihoodProblem, method::AbstractProfilerMethod; 
        idxs::AbstractVector{<:Int} = eachindex(get_optpars(plprob)),
        parallel_type::Symbol=:none, kwargs...)

Profiles the likelihood function for the given problem plprob using the specified profiling method.

Arguments

• plprob::ProfileLikelihoodProblem{ParameterProfile}: The profiling problem instance containing the parameters and likelihood function to be profiled.
• method::AbstractProfilerMethod: The method to be used for profiling.
• idxs::AbstractVector{<:Int}: Indices of the parameters to be profiled. Defaults to all parameters. (note!) Ensure that each parameter index in idxs has a finite (lower, upper) range in the ProfileLikelihoodProblem’s profile_range – the profile procedure will validate this.
• 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, [(-10.,10.), (-5.,5.)])
method = OptimizationProfiler(optimizer = Optimization.LBFGS(), stepper = FixedStep())
sol = solve(plprob, method; idxs=[1])

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.

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

ProfileLikelihoodProblem{T,probType,P,PF,PR}

Defines a profile likelihood problem.

Mathematical Specification of a Profile Likelihood Problem:

A profile likelihood problem is defined by

• an objective function (usually negative log-likelihood function) wrapped within an optprob::OptimizationProblem. Consult Optimization.jl docs for details.
• a set of optimal values of the parameters optpars that minimize the objective function.

Constructors

ProfileLikelihoodProblem(optprob::OptimizationProblem, optpars::AbstractVector{<:Real},
  profile_range::Union{AbstractVector, Tuple} = tuple.(optprob.lb, optprob.ub); 
  conf_level::Float64 = 0.95, df::Int = 1, threshold::Real = chi2_quantile(conf_level, df))

Arguments

• optprob::OptimizationProblem: The OptimizationProblem to be solved.
• optpars::AbstractVector{<:Real}: Initial (optimal) values of the parameters.
• profile_range::Union{AbstractVector, Tuple}: The range over which the profile likelihood is computed. A tuple (lower, upper) specifying a common profiling interval for all parameters, or an array of such tuples (one per parameter). By default, it uses the OptimizationProblem bounds for each parameter (i.e., tuple.(optprob.lb, optprob.ub)). (note!) If a parameter is not meant to be profiled, you may use nothing or infinite bounds.

Keyword arguments

• conf_level::Float64: The confidence level for the profile likelihood. Defaults to 0.95.
• df::Int: The degrees of freedom for the profile likelihood. Defaults to 1.
• threshold::Real: The threshold for the profile likelihood. Can be set to Inf if confidence interval endpoint estimation is not required. Defaults to chi2_quantile(conf_level, df).

ProfileLikelihoodSolution{probType,P}

Contains the results of a profile likelihood analysis.

Fields

• prob::probType: The profile likelihood problem ProfileLikelihoodProblem.
• profiles::P: The computed profiles.
• 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]:

• get_endpoints(sol[i]): Returns the confidence interval (CI) endpoints, marking the intersection of the profile with the threshold.
• get_retcodes(sol[i]): Returns the retcodes of the CI endpoints estimation.
• get_stats(sol[i]): Returns the statistics of the profile computation.