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
¶
A Gaussian copula.
student_t
staticmethod
¶
A Student t copula: tail dependence that grows as
degrees_of_freedom falls.
clayton
staticmethod
¶
Clayton, theta >= 0 (0 is independence): lower-tail
dependence. Kendall's tau is theta / (theta + 2).
gumbel
staticmethod
¶
Gumbel, theta >= 1 (1 is independence): upper-tail
dependence. Kendall's tau is 1 - 1 / theta.
frank
staticmethod
¶
Frank, theta >= 0 (0 is independence): no tail dependence.
joe
staticmethod
¶
Joe, theta >= 1 (1 is independence): upper-tail dependence,
stronger than Gumbel's for the same Kendall's tau.
correlate ¶
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.