Diagnostics API

Diagnostics help explain which numerical method was used for a fit or goodness-of-fit calculation. They are especially useful for dynamic models, where optimizer convergence and numerical approximation accuracy are separate questions.

Goodness-of-fit tests

gof_test evaluates the Rosenblatt transform and a Cramer-von Mises statistic for fitted bivariate and multivariate models. With a supplied fit_result, the calculation follows the fitted strategy:

• MLE uses the fitted constant parameter.
• GAS uses the filtered point state path.
• SCAR-TM integrates conditional h-functions over the predictive latent-state distribution.

An explicit static Gaussian or Student fit_result also supplies correlation state (dense or factor) and Student degrees of freedom, taking precedence over state attached to the model without changing that model. GAS diagnostics keep the fitted scaling and score_eps. Dynamic multivariate SCAR diagnostics require an OU result and preserve its grid settings and auto_small_kdt; K and grid_range on the GoF call override the corresponding grid sizes.

Bootstrap calibration, when requested, simulates from the fitted model and recomputes the statistic on generated samples. For stochastic latent-state models this means resampling both the latent path and the copula observations, not only perturbing the observed pseudo-observations.

bootstrap_fit_kwargs accepts the selected model's normal fit options, including strategy constructor settings such as GAS scaling or OU K. These settings control bootstrap refitting. For bivariate, EquicorrGaussianCopula, and StochasticStudentCopula GAS refits, the fitted score_eps is retained even when a new gamma0 is supplied. For these models, an explicit score_eps takes priority over an explicit config.gas_score_eps, which takes priority over the fitted score step. Passing score_eps=None selects the config or fitted default. GAS Vine refits do not restore fitted score steps from individual edges. Set bootstrap_fit_kwargs={'score_eps': value} to use one chosen step for all refitted GAS edges; otherwise they use an explicit config.gas_score_eps or the library default. Unknown or misplaced keys are rejected before bootstrap random streams or workers are created, including when bootstrap_refit=False. In that mode, valid fit-only options have no effect. Samplers that support native threads receive the resolved config.n_threads, including static Student and Equicorr models; parallel bootstrap uses one native thread per worker. The dictionary cannot override to_pobs: generated bootstrap samples are already pseudo-observations.

Fitted VineCopula models follow the same parametric-bootstrap contract. A replication simulates from the captured fitted R-vine, optionally refits a worker-owned vine with the same structure and requested fitting settings, applies the R-vine Rosenblatt transform, and recomputes the Cramer-von Mises statistic. Supported static and dynamic exact built-in edges use the mandatory native Rosenblatt traversal. Unknown edge types raise NativeUnsupported; there is no Python numerical fallback. Dynamic traversals preserve each edge strategy and its fitted settings, with explicit OU grid overrides applied only to OU edges.

The returned BootstrapGoFResult exposes statistic, the calibrated pvalue, bootstrap_statistics, n_bootstrap, and bootstrap_diagnostics. Parallel execution metadata is available as n_jobs_requested, resolved n_jobs, n_threads, and backend; reproducible execution policy is recorded in rng_policy and worker_model_ownership. An unsuccessful or nonfinite refit is retried once on the same simulated sample, using its finite endpoint as the next initial point when available. The retry retains the requested optimizer budget. If it also fails, calibration raises an error identifying the replication and optimizer message; an unsuccessful fit never contributes a statistic to the calibrated p-value. Successful results retain both attempt records in bootstrap_refit_attempts and expose bootstrap_refit_retries. Retrying does not draw replacement data or consume another simulation seed.

Common fit diagnostics to inspect before interpreting GoF results include:

• optimizer fields such as success, message, objective evaluations, and gradient kind;
• SCAR-TM-OU transition attempts and fallback counters such as fallback_spectral_to_matrix, fallback_matrix_to_local, matrix_failures, and matrix_capped;
• grid resolution fields last_K_requested, last_K_effective, last_grid_was_capped, and grid_capped_evaluations. These distinguish an actual adaptive grid cap from a matrix-to-local fallback; explicit matrix evaluation can use a capped grid without taking any fallback;
• SCAR-TM-JACOBI fields such as transition_method, transition_storage, stationarity_correction, gradient_kind, setup_derivative, filter_derivative, and spectral negative-mass indicators. Sparse numerical and validation diagnostics additionally expose nnz, max_width, retained_bytes, dense_bytes, and stationary_error, together with MH/IPFP-specific correction fields when those experimental corrections are evaluated. Adaptive-order fit diagnostics store the complete initial and fitted-parameter reports as adaptive_quad_order_initial and adaptive_quad_order_final. Options that determine later Jacobi likelihood, sampling, and prediction semantics are stored as typed LatentResult fields rather than only in diagnostics, so they survive stateless dispatch and JSON persistence;
• Stochastic Student correlation preprocessing fields such as corr_initialization_source, corr_projection_applied, corr_min_eigenvalue_before, corr_min_eigenvalue_after, and corr_nonfinite_kendall_pairs.
• optimizer_parameterization, which is log_kappa_mu_log_stationary_sigma for Stochastic Student SCAR-TM-OU fits; the fitted parameters themselves remain in public (kappa, mu, nu) units.
• n_threads, the resolved native thread count used by MLE, GAS, or SCAR. Omission always resolves to 1; environment variables do not override it.

Independent fit batches and rolling risk results additionally expose:

• n_jobs_requested and resolved n_jobs;
• n_threads_requested and resolved n_threads;
• multiprocessing_start_method;
• nested_parallelism;
• worker_model_ownership='per_task' and prepared_evaluator_sharing=False.

For VineCopula, vine.fit_diagnostics["edge_fits"] additionally separates the requested vine method from the methods retained on individual edges. It contains actual method and family counts, dynamic attempt/success counts, fallback edges, selection and attempted-dynamic nfev, discarded fallback work, failure messages, and edge-level timings. Unsuccessful dynamic edge fits are replaced by their successful MLE selection results, so performance and model audits should check actual_methods and fallback_count rather than the vine-level method label alone.

For the formulas behind the dynamic Rosenblatt transform and the distinction between optimizer and approximation convergence, see Mathematical Contracts.

pyscarcopula.stattests.gof_test(model, data, to_pobs=True, K=300, grid_range=5.0, fit_result=None, bootstrap=False, n_bootstrap=199, bootstrap_refit=True, bootstrap_fit_kwargs=None, rng=None, n_jobs=1)

Unified goodness-of-fit test for any copula model.

Dispatches based on model type: - BivariateCopula -> bivariate Rosenblatt (MLE or SCAR mixture) - VineCopula -> generic regular-vine Rosenblatt - GaussianCopula -> Cholesky-based Rosenblatt - StudentCopula -> conditional t-distribution Rosenblatt

Parameters:

Name	Type	Description	Default
model	BivariateCopula, VineCopula, GaussianCopula, or StudentCopula		required
data	(T, d) array		required
to_pobs	bool		True
K	int — grid size (SCAR-TM-OU only)		300
grid_range	float (SCAR-TM-OU only)		5.0
fit_result	FitResult or None	If provided, use this instead of model.fit_result. Enables the stateless API: gof_test(copula, u, fit_result=result)	None
bootstrap	bool	If True, calibrate a supported bivariate, regular-vine, static multivariate, or dynamic multivariate CvM statistic by parametric bootstrap instead of using the one-sample asymptotic p-value.	False
n_bootstrap	int	Number of bootstrap replications.	199
bootstrap_refit	bool	If True, re-estimate the model on each bootstrap sample. An unsuccessful refit is retried once on the same sample, starting from its finite endpoint when available. If the retry fails, calibration raises instead of including an invalid statistic.	True
bootstrap_fit_kwargs	dict or None	Extra keyword arguments for each bootstrap fit.	None
rng	int, Generator, SeedSequence, or None	Random seed/source for bootstrap simulation.	None
n_jobs	int	Bootstrap worker processes. 1 executes sequentially; -1 uses all available CPUs. Ignored when bootstrap=False.	1

Returns:

Type	Description
CramérVonMisesResult or BootstrapGoFResult	The bootstrap result additionally contains calibration samples, per-replication diagnostics, and resolved parallelism metadata.

pyscarcopula.stattests.rvine_gof_test(vine, data, to_pobs=True, K=500, grid_range=7.0, *, vine_type=None)

Goodness-of-fit test for a fitted R-vine copula.

Parameters:

Name	Type	Description	Default
vine	VineCopula(fitted)		required
data	(T, d)		required
to_pobs	bool		True
K	int		500
grid_range	float		7.0
vine_type	(cvine, dvine, rvine)	Structural mode forwarded by :func:gof_test. None derives it from the fitted model.	'cvine'

Returns:

Type	Description
CramérVonMisesResult

pyscarcopula.stattests.rvine_rosenblatt_transform(vine, u, K=300, grid_range=5.0, *, vine_type=None)

Apply the mandatory native R-vine Rosenblatt traversal.