Configuration and Fit Results¶

Use NumericalConfig for fitting and PredictConfig for prediction defaults. LBFGSBConfig supplies optimizer overrides; None fields inherit the library defaults. Per-call fit keywords override the corresponding configured values. See Optimizer Controls for examples and Estimation Methods for model compatibility.

from pyscarcopula import LBFGSBConfig, NumericalConfig, PredictConfig

config = NumericalConfig(mle_optimizer=LBFGSBConfig(gtol=1e-6))
prediction = PredictConfig()

Fitting configuration¶

NumericalConfig `dataclass` ¶

NumericalConfig(
    fail_value=10000000000.0,
    n_threads=1,
    default_K=300,
    default_grid_range=5.0,
    default_pts_per_sigma=4,
    default_grid_method="auto",
    default_adaptive=True,
    mle_optimizer=(lambda: DEFAULT_MLE_OPTIMIZER)(),
    gas_optimizer=(lambda: DEFAULT_GAS_OPTIMIZER)(),
    scar_optimizer=(lambda: DEFAULT_SCAR_OPTIMIZER)(),
    bivariate_scar_optimizer=None,
    bivariate_log_scar_optimizer=(
        lambda: DEFAULT_BIVARIATE_LOG_SCAR_OPTIMIZER
    )(),
    equicorr_optimizer=(
        lambda: DEFAULT_EQUICORR_OPTIMIZER
    )(),
    stochastic_student_optimizer=(
        lambda: DEFAULT_STOCHASTIC_STUDENT_OPTIMIZER
    )(),
    static_student_optimizer=(
        lambda: DEFAULT_STATIC_STUDENT_OPTIMIZER
    )(),
    stochastic_student_gas_optimizer=(
        lambda: DEFAULT_STOCHASTIC_STUDENT_GAS_OPTIMIZER
    )(),
    stochastic_student_scar_optimizer=(
        lambda: DEFAULT_STOCHASTIC_STUDENT_SCAR_OPTIMIZER
    )(),
    bisection_tol=1e-10,
    bisection_maxiter=60,
    gas_score_eps=0.0001,
    gas_gamma_bound=20.0,
    gas_beta_bound=0.999,
)

Shared optimizer and algorithm configuration.

This immutable object centralizes numerical tolerances, grid sizes, Monte Carlo defaults, and optimizer options. Unspecified optimizer fields are filled from the method-specific defaults during initialization.

Examples:

>>> config = NumericalConfig(default_K=500, bisection_tol=1e-12)

Optimizer options¶

LBFGSBConfig `dataclass` ¶

LBFGSBConfig(
    gtol=None,
    ftol=None,
    maxfun=None,
    maxiter=None,
    maxls=None,
    eps=None,
    maxcor=None,
    finite_diff_rel_step=None,
)

Options for SciPy's L-BFGS-B optimizer.

None means "inherit the library default" when the configuration is merged into NumericalConfig. All supplied values must be finite, real, and strictly positive.

merged ¶

merged(override)

Return a copy with non-None values from override.

options ¶

options(**overrides)

Return validated options suitable for scipy.optimize.minimize.

Keyword arguments override fields on this object. Unknown option names raise TypeError instead of being silently ignored.

Prediction configuration¶

PredictConfig `dataclass` ¶

PredictConfig(
    given=None,
    horizon="next",
    predictive_r_mode=None,
    dynamic_conditioning="ignore",
    return_diagnostics=False,
    mcmc_steps=None,
    mcmc_burnin=None,
)

Prediction-time options shared by copulas, vines, and strategies.

Parameters:

Name	Type	Description	Default
`given`	`dict[int, float] or None`	Coordinates fixed during conditional sampling, expressed in pseudo-observation space.	`None`
`horizon`	`str`	Use "current" for the filtered state or "next" to advance one step.	`"next"`
`predictive_r_mode`	`str or None`	Sampling representation for a predictive scalar parameter: "grid" or "histogram". None selects the strategy-specific default.	`None`
`dynamic_conditioning`	`str`	Policy for updating dynamic vine edges from conditioned values: "ignore" or "given_only".	`"ignore"`
`return_diagnostics`	`bool`	Request prediction diagnostics from models that support them.	`False`
`mcmc_steps`	`int or None`	Optional non-negative counts of single-coordinate updates for conditional MCMC sampling. A full sweep updates every free variable.	`None`
`mcmc_burnin`	`int or None`	Optional non-negative counts of single-coordinate updates for conditional MCMC sampling. A full sweep updates every free variable.	`None`

Notes

Call validated after direct construction, or use replace, to normalize string values and validate integer controls.

validated ¶

validated()

Return a normalized, validated copy of this configuration.

replace ¶

replace(**kwargs)

Return a validated copy with selected fields replaced.

Fit results¶

Scalar model fit calls return a typed result. Inspect success, message, and log_likelihood before using an optimizer candidate. n_params includes estimated static parameters where applicable; it need not equal the length of the dynamic process vector. Configuration and MultivariateMLEResult are exported at package level. The other result classes below are defined in pyscarcopula._types; their fields are described here because fitted models return them.

Fit	Result type	Parameter fields
Scalar MLE	`MLEResult`	`copula_param`, `n_params`, `diagnostics`
Multivariate static MLE	`MultivariateMLEResult`	`model_parameters`, `correlation_matrix`, `aic`, `bic`; `copula_param` is `None` for Gaussian
GAS	`GASResult`	`params.omega`, `params.gamma`, `params.beta`, `scaling`, `score_eps`, `r_last`
SCAR-TM-OU	`LatentResult`	`params.kappa`, `params.mu`, `params.nu`, solver metadata
SCAR-TM-JACOBI	`LatentResult`	`params.kappa`, `params.m`, `params.xi`, solver and sampling metadata
Independence	`IndependentResult`	`copula_param == 0`, `n_params == 0`, zero log likelihood

GAS is observation-driven and has its own result type. It is not a LatentResult. LatentProcessParams.names, .values, and .to_dict() allow generic inspection without assuming OU parameter names. GASResult.r_last contains the one-step-ahead copula parameter.

VineCopula.fit returns the fitted vine itself. Its fit_result is a scipy.optimize.OptimizeResult summary; individual edges carry the typed results above. See Vine API.

Common fields¶

Field	Meaning
`log_likelihood`	Fitted log likelihood
`method`	Estimation method label
`copula_name`	Model name
`success`	Optimizer/candidate acceptance status
`nfev`	Reported objective evaluation count
`message`	Fit status or termination explanation

FitResultBase `dataclass` ¶

FitResultBase(
    log_likelihood,
    method,
    copula_name,
    success,
    nfev=0,
    message="",
)

Common fields for all fit results.

Scalar MLE result¶

MLEResult `dataclass` ¶

MLEResult(
    log_likelihood,
    method,
    copula_name,
    success,
    nfev=0,
    message="",
    copula_param=0.0,
    parameter_count=1,
    diagnostics=dict(),
)

Bases: FitResultBase

Result of an MLE fit with optional additional static parameters.

n_params `property` ¶

n_params

Multivariate MLE result¶

Factor results store compact loadings in model_parameters; their correlation_matrix is None. A supplied fixed Gaussian correlation has zero fitted parameters. Other correlation counts follow Mathematical Contracts.

MultivariateMLEResult `dataclass` ¶

MultivariateMLEResult(
    log_likelihood,
    method,
    copula_name,
    success,
    nfev=0,
    message="",
    copula_param=None,
    parameter_count=1,
    diagnostics=dict(),
    n_observations=1,
    model_parameters=dict(),
    correlation_matrix=None,
)

Bases: MLEResult

MLE result with explicit multivariate parameters and correlation.

n_params `property` ¶

n_params

aic `property` ¶

aic

Akaike information criterion.

bic `property` ¶

bic

Bayesian information criterion.

GAS result¶

GASResult `dataclass` ¶

GASResult(
    log_likelihood,
    method,
    copula_name,
    success,
    nfev=0,
    message="",
    params=(lambda: gas_params(0.0, 0.0, 0.0))(),
    scaling="unit",
    score_eps=DEFAULT_CONFIG.gas_score_eps,
    r_last=0.0,
    diagnostics=dict(),
    parameter_count=None,
)

Bases: FitResultBase

Result of GAS fit.

omega `property` ¶

omega

gamma `property` ¶

gamma

beta `property` ¶

beta

n_params `property` ¶

n_params

SCAR result¶

LatentResult `dataclass` ¶

LatentResult(
    log_likelihood,
    method,
    copula_name,
    success,
    nfev=0,
    message="",
    params=(lambda: ou_params(1.0, 0.0, 1.0))(),
    K=None,
    grid_range=None,
    pts_per_sigma=None,
    transition_method=None,
    max_K=None,
    r_gh=None,
    gh_order=None,
    auto_small_kdt=None,
    spectral_basis_order=None,
    spectral_quad_order=None,
    diagnostics=dict(),
    parameter_count=None,
    tau_eps=1e-06,
    theta_cap=None,
    clip_negative=False,
    negative_mass_tol=1e-05,
    stationary_shape_max=500.0,
    sampling_method="tm_grid",
    lamperti_substeps=8,
    lamperti_boundary="reflect",
    lamperti_eps=1e-10,
    lamperti_engine="native",
    lamperti_chunk_observations=4096,
    memory_budget_bytes=None,
    transition_storage="dense",
    stationarity_correction="none",
    grid_method=None,
    adaptive=None,
)

Bases: FitResultBase

Result of any latent-process fit.

The process parameters live in params (LatentProcessParams), which is generic over the number and names of parameters. This keeps the result type independent of the parameter count.

n_params `property` ¶

n_params

Independence result¶

IndependentResult `dataclass` ¶

IndependentResult(
    log_likelihood,
    method,
    copula_name,
    success,
    nfev=0,
    message="",
    copula_param=0.0,
)

Bases: FitResultBase

Result for IndependentCopula: 0 params, logL=0.

copula_param is always 0.0; present for interface uniformity. so that code like edge.fit_result.copula_param works without isinstance checks.

n_params `property` ¶

n_params

Named process parameters¶

LatentProcessParams `dataclass` ¶

LatentProcessParams(
    process_type,
    names,
    values,
    bounds_lower=None,
    bounds_upper=None,
)

Parameters of a latent stochastic process.

This is intentionally generic: different processes have different parameter sets and different numbers of parameters.

For OU process: names=('kappa', 'mu', 'nu'), values=(49.97, 2.42, 10.65) For fBm-style models: names=('H', 'mu', 'sigma'), values=(0.7, 0, 1)

The named access (params.kappa) goes through getattr, the positional access (params.values[0]) is always available. Values and optional bounds must be real; infinite bounds are allowed.

n_params `property` ¶

n_params

Number of named process parameters.

to_dict ¶

to_dict()

Return process parameters keyed by their names.

replace ¶

replace(**kwargs)

Return a new LatentProcessParams with some values changed.

Configuration and Fit Results¶

Fitting configuration¶

NumericalConfig dataclass ¶

Optimizer options¶

LBFGSBConfig dataclass ¶

merged ¶

options ¶

Prediction configuration¶

PredictConfig dataclass ¶

validated ¶

replace ¶

Fit results¶

Common fields¶

FitResultBase dataclass ¶

Scalar MLE result¶

MLEResult dataclass ¶

n_params property ¶

Multivariate MLE result¶

MultivariateMLEResult dataclass ¶

n_params property ¶

aic property ¶

bic property ¶

GAS result¶

GASResult dataclass ¶

omega property ¶

gamma property ¶

beta property ¶

n_params property ¶

SCAR result¶

LatentResult dataclass ¶

n_params property ¶

Independence result¶

IndependentResult dataclass ¶

n_params property ¶

Named process parameters¶

LatentProcessParams dataclass ¶

n_params property ¶

to_dict ¶

replace ¶

NumericalConfig `dataclass` ¶

LBFGSBConfig `dataclass` ¶

PredictConfig `dataclass` ¶

FitResultBase `dataclass` ¶

MLEResult `dataclass` ¶

n_params `property` ¶

MultivariateMLEResult `dataclass` ¶

n_params `property` ¶

aic `property` ¶

bic `property` ¶

GASResult `dataclass` ¶

omega `property` ¶

gamma `property` ¶

beta `property` ¶

n_params `property` ¶

LatentResult `dataclass` ¶

n_params `property` ¶

IndependentResult `dataclass` ¶

n_params `property` ¶

LatentProcessParams `dataclass` ¶

n_params `property` ¶