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})
Data-bound GCM conditional-independence test.
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).
Data-bound HSIC conditional-independence test.
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).
Data-bound KCI conditional-independence test.
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).
Gaussian (RBF) kernel with a fixed length scale.
Raised when the core conditional-independence engine reports an error.
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.
Data-bound ChiSquared conditional-independence test.
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).
Data-bound CressieRead conditional-independence test.
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).
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.
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.
Data-bound FisherZ conditional-independence test.
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).
Data-bound FreemanTukey conditional-independence test.
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).
Linear kernel.
Data-bound LogLikelihood conditional-independence test.
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).
Data-bound ModifiedLikelihood conditional-independence test.
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).
Data-bound PearsonCorrelation conditional-independence test.
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).
Data-bound PearsonEquivalence conditional-independence test.
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).
Data-bound PillaiTrace conditional-independence test.
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).