fastcit

Data-bound conditional-independence testing.

Build a Dataset once from named, typed columns, then construct any of the twelve tests bound to that data and query run_test / is_independent::

import numpy as np
from fastcit import Dataset, ChiSquared, PearsonEquivalence

data = Dataset({
    "A": ("discrete", np.array([0, 1, 0, 1], dtype=float)),
    "B": ("discrete", np.array([1, 1, 0, 0], dtype=float)),
})
res = ChiSquared(data).run_test("A", "B")
res.statistic, res.p_value, res.dof, res.effect_size

The per-test classes are data-bound: they take the Dataset (or a raw {name: (kind, values)} mapping or a pandas.DataFrame) plus their own configuration in the constructor. x / y accept a column name or integer index; z is a sequence of names/indices.

  1"""Data-bound conditional-independence testing.
  2
  3Build a :class:`Dataset` once from named, typed columns, then construct any of
  4the twelve tests bound to that data and query ``run_test`` / ``is_independent``::
  5
  6    import numpy as np
  7    from fastcit import Dataset, ChiSquared, PearsonEquivalence
  8
  9    data = Dataset({
 10        "A": ("discrete", np.array([0, 1, 0, 1], dtype=float)),
 11        "B": ("discrete", np.array([1, 1, 0, 0], dtype=float)),
 12    })
 13    res = ChiSquared(data).run_test("A", "B")
 14    res.statistic, res.p_value, res.dof, res.effect_size
 15
 16The per-test classes are data-bound: they take the :class:`Dataset` (or a raw
 17``{name: (kind, values)}`` mapping or a :class:`pandas.DataFrame`) plus their
 18own configuration in the constructor. ``x`` / ``y`` accept a column name or
 19integer index; ``z`` is a sequence of names/indices.
 20"""
 21
 22from __future__ import annotations
 23
 24from typing import TYPE_CHECKING, Any
 25
 26import numpy as np
 27
 28from fastcit._fastcit import (
 29    GCM,
 30    HSIC,
 31    KCI,
 32    RBF,
 33    ChiSquared,
 34    CIError,
 35    CIResult,
 36    CressieRead,
 37    FisherZ,
 38    FreemanTukey,
 39    Linear,
 40    LogLikelihood,
 41    ModifiedLikelihood,
 42    PearsonCorrelation,
 43    PearsonEquivalence,
 44    PillaiTrace,
 45)
 46from fastcit._fastcit import (
 47    Dataset as _Dataset,
 48)
 49
 50if TYPE_CHECKING:  # pragma: no cover - typing-only import
 51    import pandas as pd
 52    from numpy.typing import NDArray
 53
 54__all__ = [
 55    "GCM",
 56    "HSIC",
 57    "KCI",
 58    "RBF",
 59    "CIError",
 60    "CIResult",
 61    "ChiSquared",
 62    "CressieRead",
 63    "Dataset",
 64    "FisherZ",
 65    "FreemanTukey",
 66    "Linear",
 67    "LogLikelihood",
 68    "ModifiedLikelihood",
 69    "PearsonCorrelation",
 70    "PearsonEquivalence",
 71    "PillaiTrace",
 72]
 73
 74
 75def _safe_issubdtype(dtype: Any, base: Any) -> bool:  # noqa: ANN401
 76    """Return whether ``dtype`` is a subtype of ``base`` without raising.
 77
 78    Pandas extension dtypes that NumPy cannot interpret return ``False``.
 79    """
 80    try:
 81        return bool(np.issubdtype(dtype, base))
 82    except TypeError:
 83        return False
 84
 85
 86def _column_from_pandas(series: pd.Series[Any]) -> tuple[str, NDArray[np.float64]]:
 87    """Infer a column's kind and encode its values for the native dataset.
 88
 89    Categorical and string/object values become integer codes. Missing values
 90    remain NaN so the core enforces the same strict missing-data policy.
 91    """
 92    import pandas as pd  # noqa: PLC0415 - optional dependency imported lazily
 93
 94    dtype = series.dtype
 95    name = str(getattr(dtype, "name", dtype))
 96    if name == "category":
 97        codes = np.asarray(series.cat.codes, dtype=np.float64)
 98        codes[codes == -1.0] = np.nan
 99        return "discrete", codes
100    if name in ("string", "str") or dtype == np.object_ or _safe_issubdtype(dtype, np.str_):
101        raw, _ = pd.factorize(series)
102        codes = raw.astype(np.float64)
103        codes[codes == -1.0] = np.nan
104        return "discrete", codes
105    # Temporal dtypes are neither categorical nor plain-numeric; reject them
106    # explicitly (timedelta64 would otherwise pass the integer check below).
107    if _safe_issubdtype(dtype, np.datetime64) or _safe_issubdtype(dtype, np.timedelta64):
108        msg = f"cannot infer column kind for temporal dtype {dtype!r}; convert it explicitly first"
109        raise TypeError(msg)
110    if _safe_issubdtype(dtype, np.floating):
111        return "continuous", np.asarray(series, dtype=np.float64)
112    if _safe_issubdtype(dtype, np.integer) or _safe_issubdtype(dtype, np.bool_):
113        return "discrete", np.asarray(series, dtype=np.float64)
114    msg = f"cannot infer column kind for dtype {dtype!r}; pass an explicit mapping"
115    raise TypeError(msg)
116
117
118class Dataset(_Dataset):
119    """A named, typed, immutable table shared by the test classes.
120
121    See the native :class:`fastcit._fastcit.Dataset` for the primary
122    constructor (a ``{name: (kind, values)}`` mapping). This subclass adds the
123    pure-Python :meth:`from_pandas` convenience.
124    """
125
126    __slots__ = ()
127
128    @classmethod
129    def from_pandas(cls, df: pd.DataFrame) -> Dataset:
130        """Build a :class:`Dataset` from a :class:`pandas.DataFrame`.
131
132        Column kinds are inferred from dtypes: integer / boolean / categorical
133        / object / string columns become ``"discrete"`` and floating columns
134        become ``"continuous"``. Categorical and object/string columns are
135        factorized to integer codes; **missing values are mapped to NaN and
136        rejected by the core** (strict missing-data policy — drop or impute
137        first). ``pandas`` is imported lazily, so it is not a hard dependency
138        of this package.
139
140        .. note::
141            Passing a :class:`pandas.DataFrame` directly to any test
142            constructor (e.g. ``ChiSquared(df)``) is equivalent to
143            ``ChiSquared(Dataset.from_pandas(df))`` — a fresh :class:`Dataset`
144            is built per constructor call; to share data across tests, build
145            a :class:`Dataset` explicitly.
146        """
147        return cls({str(name): _column_from_pandas(df[name]) for name in df.columns})
class GCM:

Data-bound GCM conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class HSIC:

Data-bound HSIC conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class KCI:

Data-bound KCI conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class RBF:

Gaussian (RBF) kernel with a fixed length scale.

length_scale
class CIError(builtins.Exception):

Raised when the core conditional-independence engine reports an error.

class CIResult:

The numeric outcome of a conditional-independence test.

Mirrors [fastcit_core::strategy::CIResult]: statistic, dof, and effect_size are None when the test does not define them.

dof
statistic
effect_size
p_value
class ChiSquared:

Data-bound ChiSquared conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class CressieRead:

Data-bound CressieRead conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class Dataset(fastcit._fastcit.Dataset):
119class Dataset(_Dataset):
120    """A named, typed, immutable table shared by the test classes.
121
122    See the native :class:`fastcit._fastcit.Dataset` for the primary
123    constructor (a ``{name: (kind, values)}`` mapping). This subclass adds the
124    pure-Python :meth:`from_pandas` convenience.
125    """
126
127    __slots__ = ()
128
129    @classmethod
130    def from_pandas(cls, df: pd.DataFrame) -> Dataset:
131        """Build a :class:`Dataset` from a :class:`pandas.DataFrame`.
132
133        Column kinds are inferred from dtypes: integer / boolean / categorical
134        / object / string columns become ``"discrete"`` and floating columns
135        become ``"continuous"``. Categorical and object/string columns are
136        factorized to integer codes; **missing values are mapped to NaN and
137        rejected by the core** (strict missing-data policy — drop or impute
138        first). ``pandas`` is imported lazily, so it is not a hard dependency
139        of this package.
140
141        .. note::
142            Passing a :class:`pandas.DataFrame` directly to any test
143            constructor (e.g. ``ChiSquared(df)``) is equivalent to
144            ``ChiSquared(Dataset.from_pandas(df))`` — a fresh :class:`Dataset`
145            is built per constructor call; to share data across tests, build
146            a :class:`Dataset` explicitly.
147        """
148        return cls({str(name): _column_from_pandas(df[name]) for name in df.columns})

A named, typed, immutable table shared by the test classes.

See the native fastcit._fastcit.Dataset for the primary constructor (a {name: (kind, values)} mapping). This subclass adds the pure-Python from_pandas() convenience.

@classmethod
def from_pandas(cls, df: 'pd.DataFrame') -> Dataset:
129    @classmethod
130    def from_pandas(cls, df: pd.DataFrame) -> Dataset:
131        """Build a :class:`Dataset` from a :class:`pandas.DataFrame`.
132
133        Column kinds are inferred from dtypes: integer / boolean / categorical
134        / object / string columns become ``"discrete"`` and floating columns
135        become ``"continuous"``. Categorical and object/string columns are
136        factorized to integer codes; **missing values are mapped to NaN and
137        rejected by the core** (strict missing-data policy — drop or impute
138        first). ``pandas`` is imported lazily, so it is not a hard dependency
139        of this package.
140
141        .. note::
142            Passing a :class:`pandas.DataFrame` directly to any test
143            constructor (e.g. ``ChiSquared(df)``) is equivalent to
144            ``ChiSquared(Dataset.from_pandas(df))`` — a fresh :class:`Dataset`
145            is built per constructor call; to share data across tests, build
146            a :class:`Dataset` explicitly.
147        """
148        return cls({str(name): _column_from_pandas(df[name]) for name in df.columns})

Build a Dataset from a pandas.DataFrame.

Column kinds are inferred from dtypes: integer / boolean / categorical / object / string columns become "discrete" and floating columns become "continuous". Categorical and object/string columns are factorized to integer codes; missing values are mapped to NaN and rejected by the core (strict missing-data policy — drop or impute first). pandas is imported lazily, so it is not a hard dependency of this package.

Passing a pandas.DataFrame directly to any test constructor (e.g. ChiSquared(df)) is equivalent to ChiSquared(Dataset.from_pandas(df)) — a fresh Dataset is built per constructor call; to share data across tests, build a Dataset explicitly.

class FisherZ:

Data-bound FisherZ conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class FreemanTukey:

Data-bound FreemanTukey conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class Linear:

Linear kernel.

class LogLikelihood:

Data-bound LogLikelihood conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class ModifiedLikelihood:

Data-bound ModifiedLikelihood conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class PearsonCorrelation:

Data-bound PearsonCorrelation conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class PearsonEquivalence:

Data-bound PearsonEquivalence conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.

class PillaiTrace:

Data-bound PillaiTrace conditional-independence test.

def run_test(self, /, x, y, z=None):

Run the test for x ⟂ y | z, returning a [CIResult].

x and y are column names or indices; z is a sequence of names/indices (default: empty conditioning set).

def is_independent(self, /, x, y, z=None, significance_level=0.05):

Decide independence at significance_level using the test's rule.

def meta(self, /):

Static metadata: {name, data_types, symmetric, rule}.