Skip to content

Copulas

Copula

A dependency structure for correlate.

Elliptical copulas take correlations(dim_row_a, dim_row_b), the target correlation in [-1, 1] between the cells of the rows whose dim rows (tuples of dim cells) are dim_row_a and dim_row_b; it's called once per pair, and the pairs must form a positive-definite matrix. Archimedean copulas take one theta for every pair, and cover positive dependence only.

gaussian staticmethod

gaussian(
    correlations: Callable[[tuple, tuple], float],
) -> Copula

A Gaussian copula.

student_t staticmethod

student_t(
    correlations: Callable[[tuple, tuple], float],
    degrees_of_freedom: float,
) -> Copula

A Student t copula: tail dependence that grows as degrees_of_freedom falls.

clayton staticmethod

clayton(theta: float) -> Copula

Clayton, theta >= 0 (0 is independence): lower-tail dependence. Kendall's tau is theta / (theta + 2).

gumbel staticmethod

gumbel(theta: float) -> Copula

Gumbel, theta >= 1 (1 is independence): upper-tail dependence. Kendall's tau is 1 - 1 / theta.

frank staticmethod

frank(theta: float) -> Copula

Frank, theta >= 0 (0 is independence): no tail dependence.

joe staticmethod

joe(theta: float) -> Copula

Joe, theta >= 1 (1 is independence): upper-tail dependence, stronger than Gumbel's for the same Kendall's tau.

ali_mikhail_haq staticmethod

ali_mikhail_haq(theta: float) -> Copula

Ali-Mikhail-Haq, 0 <= theta < 1 (0 is independence): weak dependence only, Kendall's tau below 1/3.

correlate

correlate(collection, copula, seed=None)

Correlate the cells of a float array collection (a FloatA column) with copula, lazily: the copula joins the lineage, and nothing is evaluated until something depending on it is collected.

Every input tied to each cell - every input the cell depends on, and any input combined with those in an operation such as a + b - will be reordered by the cell's permutation, so values derived from them, before or after this call, are reordered consistently. The permutations are computed from the cells' values as they stand at this call (after any earlier copula), when a value depending on them is first collected. A tied jagged input is reordered entry by entry, each entry keeping its values. Cells that already depend on a common input can't be correlated.

Without a seed, one is derived from the current :class:Context's seed and the cells' lineage, so a model gives the same results however its statements are ordered. Warns with :class:StaleReadWarning if values collected earlier depend on the inputs it will reorder.

Context

Context(*, seed: int | None = None)

Settings for everything built inside a with block.

seed is the root seed: a copula applied without an explicit seed gets one derived from it and from its cells' lineage, so results don't depend on the order a model's statements run in. A setting left as None is inherited from the enclosing context.

StaleReadWarning

Bases: UserWarning

A copula will reorder inputs that values already collected depend on: those Collected values are out of date, and collecting again gives reordered values.

Copula bookkeeping

pending_copulas

pending_copulas() -> int

How many copulas registered by zeki.correlate have yet to be applied, including any nothing can apply any more until free_unreachable_copulas() frees them.

free_unreachable_copulas

free_unreachable_copulas() -> int

Free the values held only by copulas nothing can ever apply - registered, then every value depending on what they reorder dropped before anything was collected - returning how many copulas were freed. Runs after every collect, as zeki.correlate registers copulas, and on a full gc.collect(), so calling it is rarely needed.