Stochastic Student API

StochasticStudentCopula

A multivariate Student copula with dynamic degrees of freedom and either fixed or jointly estimated static correlation. The dynamic scalar parameter is

\[\operatorname{df}_t = 2 + 10^{-6} + \mathrm{softplus}(g_t),\]

and the row density is the standard Student copula density

\[c(u_t;R,\nu_t)= \frac{t_d(T_{\nu_t}^{-1}(u_t);0,R,\nu_t)} {\prod_j t_1(T_{\nu_t}^{-1}(u_{tj});\nu_t)}.\]

method='mle' estimates a constant \(\nu\), method='gas' estimates a score-driven recursion for \(g_t\), and method='scar-tm-ou' treats \(g_t\) as a latent OU process integrated by transfer matrix.

SCAR-TM-OU accepts and returns the physical OU parameters (kappa, mu, nu). For this model only, optimization is performed internally in (log(kappa), mu, log(sigma_x)), where sigma_x = nu / sqrt(2 * kappa). The representation used by the optimizer is reported in result.diagnostics['optimizer_parameterization']; it does not change alpha0 or the fitted parameter values exposed by the API.

Stochastic Student copula with estimated static correlation

Static correlation modes are selected with corr_mode:

StochasticStudentCopula(d=5, R=R, corr_mode="fixed")
StochasticStudentCopula(d=5, corr_mode="shrinkage")
StochasticStudentCopula(d=5, corr_mode="cholesky")
StochasticStudentCopula(
    d=100_000, corr_mode="factor", factor_rank=8)

shrinkage estimates one additional static parameter. cholesky estimates d(d-1)/2 static parameters and is intended for low-dimensional problems. For estimated modes, the initialization/base matrix is selected in this order: an explicit corr_base, then R, then a Kendall estimate from the fit data. Both estimated-correlation modes are available for MLE and SCAR-TM-OU. GAS supports fixed correlation and the one-parameter shrinkage mode; GAS with corr_mode="cholesky" is rejected before fitting. Setting analytical_grad=False retains a fully numerical optimizer gradient. See the multivariate guide for fitting details and diagnostic fields.

factor stores O(d*k + k^2) state and supports explicit initialize_factor, static row likelihood, tiled latent-grid evaluation, MLE, GAS, SCAR-TM-OU, bounded batch sampling, and exact conditional sampling. It forbids R and corr_base, and its R property never silently allocates a dense matrix. Factor sampling and conditioning retain the compact representation.

Dynamic emission densities normally use an interpolated, precomputed Student quantile (PPF) table of shape (n_df_nodes, T, d), covering the model boundary through df = 1000. Its size is capped at DEFAULT_MAX_TABLE_BYTES (256 MiB). If the values table is skipped, native evaluation keeps the node range metadata, uses exact quantiles through the final node, and switches to a controlled third-order normal-quantile asymptotic above it. Quantile derivatives with respect to df are analytical both in the exact and large-df paths, so an out-of-cache gradient does not repeat the expensive quantile inversion through finite differences. See the performance guide for accuracy and memory details.

Pass NumericalConfig(n_threads=N) to fit to parallelize eligible native emission, row-likelihood, and Monte Carlo work. Methods with a direct n_threads parameter, including conditional sampling and row/grid evaluation, can opt in per call. Omitting it always selects one native thread.

pyscarcopula.copula.multivariate.stochastic_student.StochasticStudentCopula

Bases: MultivariateCopula

d-dimensional Student-t copula with stochastic degrees of freedom.

The static correlation matrix R is fixed or estimated jointly. The df parameter is driven by a latent OU process: df(t) = Psi(x(t)) = 2 + 1e-6 + softplus(x(t))

Compatible with SCAR-TM-OU: one latent OU process drives df(t). Also supports MLE (constant df) and GAS methods.

Parameters:

Name	Type	Description	Default
d	int	Dimension (number of variables). Must be >= 2.	required
R	(d, d) ndarray or None	Fixed correlation matrix or initialization matrix for an estimated correlation mode.	None
corr_mode	('fixed', 'shrinkage', 'cholesky', 'factor')	Static correlation parameterization.	'fixed'
corr_base	(d, d) ndarray or None	Explicit initialization/base matrix for an estimated correlation mode. Initialization priority is corr_base, then R, then a Kendall estimate from the fit data.	None
factor_rank	int or None	Required rank k for corr_mode='factor'.	None
factor_loadings	(d, k) ndarray or None	Optional fixed loadings. If omitted, call :meth:initialize_factor for deterministic two-stage initialization.	None
factor_estimation	('two-stage', 'joint')	Factor estimation policy. joint estimates identifiable loadings together with constant df in static MLE; dynamic GAS/SCAR joint estimation is not yet supported.	'two-stage'
factor_tile_size	int	Dimension tile used by initialization and exact Student grid kernels.	16384
factor_joint_penalty	float	L2 loading penalty used only by joint static MLE.	1e-06
factor_joint_condition_max	float	Maximum accepted Woodbury core condition estimate in joint static MLE.	1000000000000.0

Notes

SCAR-TM-OU accepts and returns physical (kappa, mu, nu) parameters, but this model is optimized internally in (log(kappa), mu, log(sigma_x)), where sigma_x = nu / sqrt(2 * kappa). The internal representation is reported in the fit diagnostics.

Factor emission methods evaluate only the supplied observation block. They do not accept a dense PPF cache; t_index must be None or 0.

fit(data, method='scar-tm-ou', to_pobs=False, config=None, **kwargs)

Fit the stochastic Student-t copula.

Step 1: Initialize dense R or compact factor loadings if needed. Step 2: Estimate OU params for df(t) via the chosen method.

Parameters:

Name	Type	Description	Default
data	(T, d) array		required
method	str — 'mle', 'scar-tm-ou', 'gas', etc.		'scar-tm-ou'
to_pobs	bool		False
**kwargs	forwarded to strategy		{}

Returns:

Type	Description
FitResult

sample_at_parameter(n, r, rng=None, *, n_threads=1, memory_budget_bytes=None)

Sample from d-dimensional Student-t copula.

Parameters:

Name	Type	Description	Default
n	int — number of observations		required
r	float, (n,) array, or None — degrees of freedom.	If scalar: all samples use same df. If array of length n: each sample uses its own df(t).	required
rng	Generator or None		None

Returns:

Type	Description
(n, d) pseudo-observations in [0, 1]^d

sample_at_parameter_batches(n, r, *, batch_rows=128, rng=None, n_threads=1, memory_budget_bytes=None)

Yield Student samples in bounded row blocks.

sample(n, u=None, rng=None, *, n_threads=1, memory_budget_bytes=None)

Generate observations reproducing the fitted model.

sample_batches(n, u=None, rng=None, *, batch_rows=128, given=None, n_threads=1, memory_budget_bytes=None)

Yield fitted Student-model samples in bounded row blocks.

sample_conditional(n, r=None, given=None, rng=None, *, n_threads=1, memory_budget_bytes=None)

Sample conditionally with given={var_index: u_value}.

predict(n, u=None, rng=None, given=None, horizon='next', predictive_r_mode=None, predict_config=None, *, n_threads=1, memory_budget_bytes=None)

Sample n observations for next-step prediction.

For MLE, use the fitted constant degrees of freedom. Dynamic strategies delegate predictive parameter generation to their common strategy implementation, including current/next timing.

Parameters:

Name	Type	Description	Default
n	int		required
u	(T, d) or None — conditioning data.		None
rng	Generator or None		None

predict_batches(n, u=None, rng=None, *, batch_rows=128, given=None, horizon='next', predictive_r_mode=None, predict_config=None, n_threads=1, memory_budget_bytes=None)

Yield fitted predictive samples from one frozen state.

predictive_mean(u=None)

Return the predictive df path for the fitted strategy.

xT_distribution(u, K=None, grid_range=None)

Return x_T's OU grid distribution, inheriting omitted fit settings.

Explicit K/grid_range override the saved grid. Requires an OU fit; GAS and MLE parameters cannot be used as OU process parameters.

log_likelihood(u, r=None, *, n_threads=1)

Log-likelihood for d-dimensional data.

u : (T, d) pseudo-observations r : float (df) or None — if None, evaluates the fitted strategy

log_pdf_rows(u, r, t_index=None, cache=None, *, n_threads=1)

Return one log-density per row for scalar/row-wise df values.

log_pdf_and_dlog_dr_rows(u, r, t_index=None, cache=None, *, n_threads=1)

Return per-row log-density and d log c(u_t; df_t) / d df_t.

pdf_on_grid(u_row, z_grid, *, n_threads=1)

Copula density on latent grid for one observation.

u_row : (d,) single observation z_grid : (K,) latent grid values

Returns: (K,) copula densities c(u_row; R, Psi(z_j))

pdf_and_grad_on_grid(u_row, z_grid, *, n_threads=1)

Compute fi(z) and dfi/dz on the grid analytically.

fi(z) = c(u_row; R, Psi(z)) dfi/dz = fi * d(log c)/d(df) * d(Psi)/dz

u_row : (d,), z_grid : (K,) Returns: (fi, dfi_dz) each of shape (K,)

transform(x)

Map latent values to degrees of freedom above the finite-variance bound.

inv_transform(df)

Map degrees of freedom above the model offset to latent values.

dtransform(x)

d(Psi)/dx = sigmoid(x).