maxlikmtProfile

Purpose

Computes profile likelihood traces and profile t traces for models estimated using maximum likelihood.

Format

out = MaxlikmtProfile(&logl, par[, ..., c1])
Parameters:
  • &logl (pointer) – Pointer to a procedure that returns the log-likelihood for one observation or a vector of log-likelihoods for a matrix of observations.
  • par (struct) – Instance of a PV structure, constructed using the “pack” functions.
  • .. (various) – Optional input arguments. They can be any set of structures, matrices, arrays, strings required to compute the function. Can include GAUSS data types or a DS structure for dataset manipulation. Specific usage depends on the requirements of the logl.
  • c1 (struct) –

    Optional input. Instance of a maxlikmtControl structure containing the following members:

    c1.bayesAlpha Exponent of the Dirichlet random variates used in the weighted bootstrap. Default = 1.4.
    c1.priorProc Pointer to a procedure for computing the prior. Assumes a uniform prior if not provided.
    c1.numSamples Number of re-samples in the weighted likelihood bootstrap.
    c1.BayesFname Filename for the simulated posterior parameters dataset. Defaults to a unique “BAYESxxxx” pattern.
    c1.maxBootTime Maximum time allowed for resampling.
    c1.Bounds Bounds on parameters, either 1x2 for all parameters or Kx2 for individual parameter bounds. Default = {-1e256, 1e256}.
    c1.algorithm Descent algorithm for optimization, includes BFGS, DFP, Newton, and BHHH.
    c1.switch Controls algorithm switching based on various performance metrics.
    c1.lineSearch Method for line search in optimization, includes augmented trust region method and others. Default varies based on constraints.
    c1.active Kx1 vector to control which parameters are active or fixed at start value.
    c1.numObs Number of observations, required if the log-likelihood function returns a scalar.
    c1.maxIters Maximum number of iterations for the optimization process. Default = 10000.
    c1.tol Convergence tolerance, optimization stops when all elements of the direction vector are below this value. Default = 1e-5.
    c1.weights Vector of weights for the objective function returning a vector. Default = 1.
    c1.covParType Determines the type of covariance matrix computed, QML or ML. Default = 1.
    c1.alpha Probability level for statistical tests. Default = .05.
    c1.feasibleTest If nonzero, parameters are tested for feasibility before computing the function in line search. Default = 1.
    c1.maxTries Maximum number of attempts in random search. Default = 100.
    c1.randRadius Radius of the random search, if attempted. Default = .001.
    c1.gradMethod Method for computing numerical gradient, includes central, forward, and backward difference.
    c1.hessMethod Method for computing numerical Hessian, similar options as gradient computation.
    c1.gradStep Increment size for computing numerical gradient, can be scalar or Kx1 vector.
    c1.hessStep Increment size for computing numerical Hessian, options similar to gradStep.
    c1.gradCheck If nonzero and analytical gradients/Hessian provided, numerical versions are computed for comparison.
    c1.state Seed for random number generator, ensuring reproducibility.
    c1.title Title of the run, for identification in output.
    c1.printIters If nonzero, iteration information is printed. Default = 0.
    c1.disableKey If nonzero, keyboard input is disabled during execution.
Returns:

out (struct) –

An instance of a maxlikmtResults structure. Contains the results of the optimization problem, including parameter estimates, function evaluations, and various statistical measures.

out.bayesLimits Weighted likelihood Bayesian confidence limits, Kx2 matrix.
out.par Instance of a PV structure containing the parameter estimates, placed in the member matrix out.par.
out.fct Scalar, function evaluated at parameters in par.
out.returnDescription String, description of return values.
out.covPar KxK matrix, covariance matrix of parameters.
out.covParDescription String, description of covPar.
out.numObs Scalar, number of observations.
out.hessian KxK matrix, Hessian evaluated at parameters in par.
out.xproduct KxK matrix, cross-product of NxK matrix of first derivatives evaluated at parameters in par. Not available if log-likelihood function returns a scalar.
out.waldLimits Kx2 matrix, Wald confidence limits.
out.inverseWaldLimits Kx2 matrix, confidence limits by inversion of Wald statistics. Available only if maxlikmtInverseWaldLimits`() has been called.
out.profileLimits Kx2 matrix, profile likelihood confidence limits, by inversion of likelihood ratio statistics. Only available if maxlikmtProfileLimits() has been called.
out.bootLimits Kx2 Matrix, bootstrap confidence limits. Available only if maxlikmtBoot() has been called.
out.gradient Kx1 vector, gradient evaluated at the parameters in par.
out.numIterations Scalar, number of iterations.
out.elapsedTime Scalar, elapsed time of iterations.
out.alpha Scalar, probability level of confidence limits. Default = .05.
out.title String, title of run.
out.Lagrangeans Kx2 matrix, Lagrangean coefficients of bounds constraints if any.
out.retcode

Return code indicating the outcome of the computation:

  • 0: Normal convergence
  • 1: Forced exit
  • 2: Maximum number of iterations exceeded
  • 3: Function calculation failed
  • 4: Gradient calculation failed
  • 5: Hessian calculation failed
  • 6: Line search failed
  • 7: Functional evaluation failed
  • 8: Error with initial gradient
  • 9: Error with constraints
  • 10: Second update failed
  • 11: Maximum time exceeded
  • 12: Error with weights
  • 13: Quadratic program failed
  • 14: Equality constraint Jacobian failed
  • 15: Inequality constraint Jacobian failed
  • 20: Hessian failed to invert
  • 34: Data set could not be opened

Example

Biochemical Oxygen Demand (BOD) Analysis

This example demonstrates the application of maxlikmtProfile() to model the Biochemical Oxygen Demand (BOD) data using a log-likelihood function.

library maxlikmt;

// Define the log-likelihood function
proc lnlk(struct PV p, struct DS d, ind);
    local dev, s2, m, r, b0, b;

    struct modelResults mm;

    // Unpack parameters
    b0 = pvUnpack(p, 1);
    b = pvUnpack(p, 2);

    // Calculate model predictions
    r = exp(-b * d[2].dataMatrix);
    m = 1 - r;

    // Calculate deviations
    dev = d[1].dataMatrix - b0 * m;
    s2 = dev'dev/rows(dev);

    // Calculate log-likelihood
    if ind[1];
        mm.function = lnpdfmvn(dev, s2);
    endif;

    // Calculate gradient, if requested
    if ind[2];
        mm.gradient = (dev / s2) .* (m ~ b0 * d[2].dataMatrix .* r);
    endif;

    retp(mm);
endp;

// Data setup
struct DS d0;
d0 = reshape(dsCreate, 2, 1);
d0[1].dataMatrix = {8.3, 10.3, 19.0, 16.0, 15.6, 19.8};
d0[2].dataMatrix = {1, 2, 3, 4, 5, 7};

// Parameter setup
struct PV p0;
p0 = pvPacki(pvCreate, 19.143, "b0", 1);
p0 = pvPacki(p0, .5311, "b", 2);

// Control structure setup
struct maxlikmtControl c0;
c0 = maxlikmtControlCreate;
c0.Bounds = {10 35, 0 2};  // Set parameter bounds

// Perform the profile likelihood analysis
struct maxlikmtResults out;
out = maxlikmtProfile(&lnlk, p0, d0, c0);

Remarks

  • maxlikmtProfile() is utilized to explore the parameter space of maximum likelihood estimates more thoroughly, offering insights into the confidence intervals and sensitivity of the estimates.
  • This function is especially useful in complex models where the standard error may not provide a complete picture of parameter uncertainty.
  • The control structure allows extensive customization of the profiling process, making it adaptable to a wide range of models and research questions.