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 = LBFGSB(), stepper = FixedStep())
sol = solve(plprob, method)

__solve(plprob::ProfileLikelihoodProblem, method::AbstractProfilerMethod; 
        parallel_type::Symbol=:none, kwargs...)

Internal solve dispatcher used by solve after input validation and optional re-optimization. By default, it constructs parameter profile branches (idx, dir) and forwards them to __solve_parallel. Profilers with a different execution model (e.g. non-branch methods) can overload this function.

chi2_quantile(α, df=1)

Computes α quantile for Chi2 distribution with df degrees of freedom

evaluate_FIM(plprob::ProfileLikelihoodProblem, θ=plprob.optpars)

Evaluates the Fisher Information Matrix (FIM) at the given parameter values θ (default: plprob.optpars). This is the local curvature used by QuadraticApproxProfiler to build the quadratic approximation near the optimum.

AdaptiveInitialStep(; rel_step=0.005, abs_step=1e-4, min_step=1e-5, max_step=Inf)

Initial profile step rule that adapts to the current profiled parameter value.

The proposed step is max(rel_step * abs(x), abs_step), where x is the current profiled parameter value. The result is finally clamped to [min_step, max_step].

This is useful when parameters have different numerical scales and a single fixed absolute step would be inefficient.

AdaptiveStep(; initial_step=AdaptiveInitialStep(),
               predictor=LinearPredictor(),
               controller=ObjectiveStepControl())

Profiler stepper that adapts the profile step length based on the observed objective increase from trial points.

The first profile step uses initial_step. Later steps use predictor to choose the direction in parameter space and controller to keep the next objective increase in a useful range.

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 proposes each profile point from the configured initial_step rule without adapting to trial objective values.

Constructors

FixedStep(;initial_step=AdaptiveInitialStep())

Keyword arguments

• initial_step=AdaptiveInitialStep(): The step rule to use for each profile step. This can be a number (for a constant absolute step size), an AdaptiveInitialStep, or a function ctx -> step for custom logic depending on the current profiler cache. 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.
• labels::Union{Nothing,AbstractVector{<:Symbol}}: Optional labels for profiled functions (same length/order as fs).

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}, labels=nothing)

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)

LinearPredictor()

Extrapolates all parameters using linear extrapolation based on the last two successful profile points.

ObjectiveStepControl(; threshold_fraction=0.1,
           target_factor=1.25,
                       lower_factor=0.25,
                       min_obj_step=1e-3,
                       max_obj_step=Inf,
                       min_x_step=1e-4,
                       max_x_step=Inf,
                       step_factor=1.5,
                       max_x_step_growth=5.0,
                       maxiters=15)

Controls adaptive profile stepping by defining acceptable objective and profile-axis step ranges.

For finite likelihood thresholds, the target objective increase is based on threshold_fraction * threshold. For infinite thresholds, the target increase is based on target_factor * abs(obj_cur - obj_prev).

The previous optimized profile objective change is used to nudge the first trial step up or down. Trial points below the upper objective target are then treated as safe to grow until the upper target, profile bound, or iteration limit is reached. The next profile-axis step is additionally capped by max_x_step_growth * previous_step to avoid abrupt jumps in flat profile regions.

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 steps from the configured step rule in the profiling direction (Default).
  • AdaptiveStep: Adapts the step size based on trial objective increases.
• 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 = AdaptiveStep(predictor=LinearPredictor()): Use adaptive stepping with a secant-like linear predictor.

See the documentation for each stepper type (e.g., ?FixedStep, ?AdaptiveStep) for more details and customization options.

Example

using OptimizationLBFGSB
profiler = OptimizationProfiler(; optimizer = LBFGSB(), 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.
• labels::Union{Nothing,AbstractVector{<:Symbol}}: Optional labels for profiled quantities (same length/order as idxs).

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}, labels=nothing)

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, vector of Integers, Symbol, or vector of Symbols; if nothing, profile all parameters. Symbolic indices are resolved against inferred labels of optpars (e.g. named ComponentArray).
• 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;
  profile_lower = nothing, profile_upper = nothing, kwargs...)

fs: OptimizationFunction, vector of OptimizationFunction, or named container of OptimizationFunctions. Named containers propagate keys to profile labels.

• 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.
• profile_labels(sol): Returns labels of profiled quantities, if available.

Indexing

• sol[i::Int]: Access profile by position.
• sol[s::Symbol]: Access profile by symbolic label (requires labels).

QuadraticApproxProfiler

Quadratic-approximation confidence intervals (Wald approximation) based on local curvature at the optimum. The curvature is approximated by the Fisher Information Matrix/Hessian, so the resulting confidence intervals reflect the local quadratic approximation of the likelihood around optpars. By default this method reuses Hessian logic from OptimizationProblem (user-supplied Hessian or AD backend). The confidence interval is computed as θ̂ ± z * sqrt(Σ[idx, idx]), where - θ̂ is the optpars[idx], - z is the quantile of the chi-squared distribution corresponding to the conf_level and df parameters of the ProfileLikelihoodProblem, - Σ is the covariance matrix obtained by inverting the FIM.

cov_factor controls Hessian/objective scaling conventions. Common choices are:

• 1.0 when Hessian is for -logL.
• 2.0 when Hessian is for -2logL and you want covariance on the -logL scale.

Any strictly positive value is allowed (not only 1 or 2), which can be useful for calibrated or robust variance scaling.

Fields

• inversion::Symbol: Matrix inversion strategy (:cholesky, :pinv).
• clamp_to_bounds::Bool: Clip estimated interval endpoints to profile bounds.
• cov_factor::Real: Multiplicative factor applied to inv(H) to obtain covariance (Σ = cov_factor * inv(H)).
• resolution::Int: Number of points per branch (left/right) used to sample the quadratic approximation.

SingleAxisPredictor()

Extrapolates only the profiled parameter using linear extrapolation based on the last two successful profile points.