Factor Operators API

Factor correlation operator

FactorCorrelation stores a correlation matrix as \(R=D+BB^\top\) and prepares a matrix-free Woodbury operator. FactorStudentEvaluator combines that operator with Student copula likelihoods. StochasticStudentCopula(corr_mode="factor") exposes the same representation through the model API.

Prepared operators and evaluators require real-valued observations, loadings, parameters, and draws; complex arrays are rejected before conversion. Dimensions, ranks, row indices, and factor-initialization integer options require Python or NumPy integers, excluding booleans. Conditional samplers validate the supplied correlation, Student degrees of freedom, and thread count even when every coordinate is fixed by given.

import numpy as np
from pyscarcopula import FactorCorrelation, FactorStudentEvaluator

rng = np.random.default_rng(2026)
B = rng.normal(scale=0.05, size=(20, 3))
u = rng.uniform(0.01, 0.99, size=(50, 20))
factor = FactorCorrelation(B, uniqueness_min=1e-8)
operator = factor.prepare()
evaluation = FactorStudentEvaluator(operator, u).evaluate(
    df=7.0,
    n_threads=4,
)

For construction, fitting, batching, conditional sampling, persistence, complexity, and memory limits, see Factor Models. The generated reference below is the canonical source for method signatures and defaults.

API

pyscarcopula.copula.multivariate.factor_correlation.FactorCorrelation dataclass

Immutable factor correlation R = D + B B.T.

D is derived from the row norms of loadings so every diagonal entry of R equals one. This value object does not depend on a copula family. Call :meth:prepare to construct the reusable native Woodbury operator.

dimension property

Number of correlated variables.

rank property

Number of latent factors.

storage_bytes property

Bytes occupied by the compact loading and uniqueness arrays.

uniqueness property

Read-only diagonal uniqueness vector diag(D).

from_unconstrained(values, *, uniqueness_min=1e-08) classmethod

Map arbitrary finite rows into the valid factor-correlation set.

load_mmap(directory) classmethod

Open an mmap-backed factor representation without copying it.

load_npz(path) classmethod

Load a compact factor representation created by :meth:save_npz.

prepare()

Build the immutable native Woodbury workspace.

save_mmap(directory)

Write an mmap-friendly directory without overwriting it.

save_npz(path)

Write the compact factor representation.

to_dense(*, max_dimension=2048, memory_budget_bytes=None)

Explicitly materialize R for small diagnostic problems.

pyscarcopula.copula.multivariate.factor_correlation.PreparedFactorCorrelation dataclass

Thread-safe native Woodbury workspace for a factor correlation.

dimension property

Number of correlated variables.

loadings property

Read-only factor loading matrix.

logdet property

Log determinant of the represented correlation matrix.

rank property

Number of latent factors.

uniqueness property

Read-only diagonal uniqueness vector.

matvec(values, *, n_threads=1)

Multiply one or more row vectors by the correlation matrix.

quadratic_form(value, *, n_threads=1)

Evaluate x.T @ R**-1 @ x for one vector.

quadratic_forms(values, *, n_threads=1)

Evaluate x.T @ R**-1 @ x for one or more row vectors.

sample_normal(n, *, rng=None, n_threads=1, memory_budget_bytes=None)

Draw factor-normal rows using bounded, deterministic native work.

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

Yield bounded batches of factor-normal rows.

solve(values, *, n_threads=1)

Solve against the correlation matrix for one or more row vectors.

to_dense(*, max_dimension=2048, memory_budget_bytes=None)

Explicitly materialize the correlation matrix.

transform_normal_draws(factor_draws, residual_draws, *, n_threads=1)

Transform fixed independent draws into factor-normal rows.

The returned array is a copy of residual_draws. Keeping random number generation outside the native operator makes results exactly reproducible across thread counts and also supports conditional factor distributions whose factor draws have a non-identity small covariance.

pyscarcopula.copula.multivariate.factor_student.FactorStudentEvaluator

Static Student likelihood composed with a factor correlation.

The evaluator owns an immutable observation copy and shares the immutable :class:PreparedFactorCorrelation. It contains no optimizer or copula model state and is safe for concurrent read-only evaluations.

correlation property

Prepared factor-correlation operator shared by this evaluator.

dimension property

Number of variables per observation.

n_observations property

Number of observation rows.

observations property

Immutable pseudo-observations owned by this evaluator.

rank property

Rank of the factor correlation.

dlog_pdf_ddf_rows(df, *, n_threads=1)

Return analytical row derivatives with respect to df.

evaluate(df, *, n_threads=1)

Evaluate row log densities and analytical df derivatives.

evaluate_grid(df_grid, *, dimension_tile=16384, n_threads=1, memory_budget_bytes=None)

Evaluate a tiled (observations, df_grid) log-density grid.

evaluate_grid_batches(df_grid, *, batch_rows=128, dimension_tile=16384, n_threads=1, memory_budget_bytes=None)

Yield bounded row batches of the tiled Student grid.

joint_likelihood_and_gradient(df, *, n_threads=1)

Return aggregate analytical gradients for scalar df and B.

log_likelihood_and_gradient(df, *, n_threads=1)

Return likelihood and derivative for one common scalar df.

log_pdf_and_dlog_ddf_grid(df_grid, *, dimension_tile=16384, n_threads=1, memory_budget_bytes=None)

Return tiled row/grid log densities and df derivatives.

log_pdf_and_dlog_ddf_rows(df, *, n_threads=1)

Return row log densities and their analytical df derivatives.

log_pdf_rows(df, *, n_threads=1)

Return row log densities.

objective_and_gradient(df, *, n_threads=1)

Return negative likelihood and a one-element optimizer gradient.

pdf_and_grad_on_grid(df_grid, *, dimension_tile=16384, n_threads=1, memory_budget_bytes=None)

Return tiled row/grid densities and df derivatives.

pdf_and_grad_on_grid_batches(df_grid, *, batch_rows=128, dimension_tile=16384, n_threads=1, memory_budget_bytes=None)

Yield bounded density/gradient grid batches.

penalized_parameterized_objective_and_gradient(df, parameters, parameterization, *, penalty, condition_max, n_threads=1)

Evaluate the joint factor objective entirely in native code.

stochastic_pdf_and_gradient_grid(raw_grid, *, offset, dimension_tile=16384, n_threads=1, memory_budget_bytes=None)

Return density and d/dx for df=offset+softplus(x) natively.

pyscarcopula.copula.multivariate.factor_student.FactorStudentEvaluation dataclass

Immutable row likelihood and degrees-of-freedom derivative result.

dlog_likelihood_ddf property

Sum df derivatives when the evaluation used one common df.

dnegative_log_likelihood_ddf property

Return its native derivative for one common df.

log_likelihood property

Sum the row log densities.

negative_log_likelihood property

Return the native negative aggregate likelihood.

pyscarcopula.copula.multivariate.factor_student.FactorStudentGridEvaluation dataclass

Immutable tiled Student log-density grid result.

pdf_and_gradient()

Convert stable log values into density and d pdf / d df.

pyscarcopula.copula.multivariate.factor_student.FactorStudentJointEvaluation dataclass

Aggregate likelihood and analytical df/loading gradients.