antecedent.validation

Discovery stability validators.

Thin wrappers over antecedent-validate stability checks (PCMCI block bootstrap, false-positive surrogates, parameter grids, orientation, null calibration, environment holdout, regime stability).

View Source

  1"""Discovery stability validators.
  2
  3Thin wrappers over ``antecedent-validate`` stability checks (PCMCI block bootstrap,
  4false-positive surrogates, parameter grids, orientation, null calibration,
  5environment holdout, regime stability).
  6"""
  7
  8from __future__ import annotations
  9
 10from typing import Any, Mapping, Sequence
 11
 12from ._data import as_columns, as_multi_env_columns
 13from ._native import (
 14    validate_environment_holdout as _validate_environment_holdout,
 15    validate_pcmci_alpha_sensitivity as _validate_pcmci_alpha_sensitivity,
 16    validate_pcmci_block_bootstrap as _validate_pcmci_block_bootstrap,
 17    validate_pcmci_ci_sensitivity as _validate_pcmci_ci_sensitivity,
 18    validate_pcmci_false_positive as _validate_pcmci_false_positive,
 19    validate_pcmci_lag_sensitivity as _validate_pcmci_lag_sensitivity,
 20    validate_pcmci_plus_orientation as _validate_pcmci_plus_orientation,
 21    validate_regime_stability as _validate_regime_stability,
 22    validate_synthetic_null_calibration as _validate_synthetic_null_calibration,
 23)
 24
 25
 26def validate_pcmci_block_bootstrap(
 27    data: Mapping[str, Any] | Any,
 28    *,
 29    max_lag: int = 1,
 30    alpha: float = 0.05,
 31    fdr: bool = False,
 32    ci: str = "parcorr",
 33    replicates: int = 20,
 34    block_size: int = 20,
 35    seed: int = 1,
 36    threads: int = 1,
 37) -> dict[str, Any]:
 38    names, columns = as_columns(data)
 39    return _validate_pcmci_block_bootstrap(
 40        names,
 41        columns,
 42        max_lag=max_lag,
 43        alpha=alpha,
 44        fdr=fdr,
 45        ci=ci,
 46        replicates=replicates,
 47        block_size=block_size,
 48        seed=seed,
 49        threads=threads,
 50    )
 51
 52
 53def validate_pcmci_false_positive(
 54    data: Mapping[str, Any] | Any,
 55    *,
 56    max_lag: int = 1,
 57    alpha: float = 0.05,
 58    fdr: bool = False,
 59    ci: str = "parcorr",
 60    transform: str = "permute",
 61    replicates: int = 20,
 62    seed: int = 1,
 63    threads: int = 1,
 64) -> dict[str, Any]:
 65    names, columns = as_columns(data)
 66    return _validate_pcmci_false_positive(
 67        names,
 68        columns,
 69        max_lag=max_lag,
 70        alpha=alpha,
 71        fdr=fdr,
 72        ci=ci,
 73        transform=transform,
 74        replicates=replicates,
 75        seed=seed,
 76        threads=threads,
 77    )
 78
 79
 80def validate_pcmci_alpha_sensitivity(
 81    data: Mapping[str, Any] | Any,
 82    alphas: Sequence[float],
 83    *,
 84    max_lag: int = 1,
 85    fdr: bool = False,
 86    ci: str = "parcorr",
 87    seed: int = 1,
 88    threads: int = 1,
 89) -> dict[str, Any]:
 90    names, columns = as_columns(data)
 91    return _validate_pcmci_alpha_sensitivity(
 92        names,
 93        columns,
 94        list(alphas),
 95        max_lag=max_lag,
 96        fdr=fdr,
 97        ci=ci,
 98        seed=seed,
 99        threads=threads,
100    )
101
102
103def validate_pcmci_lag_sensitivity(
104    data: Mapping[str, Any] | Any,
105    max_lags: Sequence[int],
106    *,
107    alpha: float = 0.05,
108    fdr: bool = False,
109    ci: str = "parcorr",
110    seed: int = 1,
111    threads: int = 1,
112) -> dict[str, Any]:
113    names, columns = as_columns(data)
114    return _validate_pcmci_lag_sensitivity(
115        names,
116        columns,
117        [int(m) for m in max_lags],
118        alpha=alpha,
119        fdr=fdr,
120        ci=ci,
121        seed=seed,
122        threads=threads,
123    )
124
125
126def validate_pcmci_ci_sensitivity(
127    data: Mapping[str, Any] | Any,
128    ci_names: Sequence[str],
129    *,
130    max_lag: int = 1,
131    alpha: float = 0.05,
132    fdr: bool = False,
133    seed: int = 1,
134    threads: int = 1,
135) -> dict[str, Any]:
136    names, columns = as_columns(data)
137    return _validate_pcmci_ci_sensitivity(
138        names,
139        columns,
140        list(ci_names),
141        max_lag=max_lag,
142        alpha=alpha,
143        fdr=fdr,
144        seed=seed,
145        threads=threads,
146    )
147
148
149def validate_pcmci_plus_orientation(
150    data: Mapping[str, Any] | Any,
151    *,
152    max_lag: int = 1,
153    alpha: float = 0.05,
154    fdr: bool = False,
155    ci: str = "parcorr",
156    replicates: int = 20,
157    block_size: int = 20,
158    seed: int = 1,
159    threads: int = 1,
160) -> dict[str, Any]:
161    names, columns = as_columns(data)
162    return _validate_pcmci_plus_orientation(
163        names,
164        columns,
165        max_lag=max_lag,
166        alpha=alpha,
167        fdr=fdr,
168        ci=ci,
169        replicates=replicates,
170        block_size=block_size,
171        seed=seed,
172        threads=threads,
173    )
174
175
176def validate_synthetic_null_calibration(
177    *,
178    max_lag: int = 1,
179    alpha: float = 0.05,
180    fdr: bool = False,
181    ci: str = "parcorr",
182    n_sim: int = 20,
183    n_obs: int = 100,
184    n_vars: int = 3,
185    seed: int = 1,
186    threads: int = 1,
187) -> dict[str, Any]:
188    return _validate_synthetic_null_calibration(
189        max_lag=max_lag,
190        alpha=alpha,
191        fdr=fdr,
192        ci=ci,
193        n_sim=n_sim,
194        n_obs=n_obs,
195        n_vars=n_vars,
196        seed=seed,
197        threads=threads,
198    )
199
200
201def validate_environment_holdout(
202    data: Sequence[Mapping[str, Any] | Any],
203    *,
204    max_lag: int = 1,
205    alpha: float = 0.05,
206    fdr: bool = False,
207    ci: str = "parcorr",
208    n_discovery: int = 1,
209    seed: int = 1,
210    threads: int = 1,
211) -> dict[str, Any]:
212    names, env_columns = as_multi_env_columns(data)
213    return _validate_environment_holdout(
214        names,
215        env_columns,
216        max_lag=max_lag,
217        alpha=alpha,
218        fdr=fdr,
219        ci=ci,
220        n_discovery=n_discovery,
221        seed=seed,
222        threads=threads,
223    )
224
225
226def validate_regime_stability(
227    data: Mapping[str, Any] | Any,
228    regimes: Sequence[int],
229    *,
230    max_lag: int = 1,
231    alpha: float = 0.05,
232    fdr: bool = False,
233    ci: str = "parcorr",
234    replicates: int = 10,
235    block_size: int = 20,
236    seed: int = 1,
237    threads: int = 1,
238) -> dict[str, Any]:
239    names, columns = as_columns(data)
240    return _validate_regime_stability(
241        names,
242        columns,
243        [int(r) for r in regimes],
244        max_lag=max_lag,
245        alpha=alpha,
246        fdr=fdr,
247        ci=ci,
248        replicates=replicates,
249        block_size=block_size,
250        seed=seed,
251        threads=threads,
252    )
253
254
255__all__ = [
256    "validate_environment_holdout",
257    "validate_pcmci_alpha_sensitivity",
258    "validate_pcmci_block_bootstrap",
259    "validate_pcmci_ci_sensitivity",
260    "validate_pcmci_false_positive",
261    "validate_pcmci_lag_sensitivity",
262    "validate_pcmci_plus_orientation",
263    "validate_regime_stability",
264    "validate_synthetic_null_calibration",
265]

def validate_environment_holdout( data: Sequence[Union[Mapping[str, Any], Any]], *, max_lag: int = 1, alpha: float = 0.05, fdr: bool = False, ci: str = 'parcorr', n_discovery: int = 1, seed: int = 1, threads: int = 1) -> dict[str, typing.Any]: View Source

202def validate_environment_holdout(
203    data: Sequence[Mapping[str, Any] | Any],
204    *,
205    max_lag: int = 1,
206    alpha: float = 0.05,
207    fdr: bool = False,
208    ci: str = "parcorr",
209    n_discovery: int = 1,
210    seed: int = 1,
211    threads: int = 1,
212) -> dict[str, Any]:
213    names, env_columns = as_multi_env_columns(data)
214    return _validate_environment_holdout(
215        names,
216        env_columns,
217        max_lag=max_lag,
218        alpha=alpha,
219        fdr=fdr,
220        ci=ci,
221        n_discovery=n_discovery,
222        seed=seed,
223        threads=threads,
224    )

def validate_pcmci_alpha_sensitivity( data: Union[Mapping[str, Any], Any], alphas: Sequence[float], *, max_lag: int = 1, fdr: bool = False, ci: str = 'parcorr', seed: int = 1, threads: int = 1) -> dict[str, typing.Any]: View Source

 81def validate_pcmci_alpha_sensitivity(
 82    data: Mapping[str, Any] | Any,
 83    alphas: Sequence[float],
 84    *,
 85    max_lag: int = 1,
 86    fdr: bool = False,
 87    ci: str = "parcorr",
 88    seed: int = 1,
 89    threads: int = 1,
 90) -> dict[str, Any]:
 91    names, columns = as_columns(data)
 92    return _validate_pcmci_alpha_sensitivity(
 93        names,
 94        columns,
 95        list(alphas),
 96        max_lag=max_lag,
 97        fdr=fdr,
 98        ci=ci,
 99        seed=seed,
100        threads=threads,
101    )

def validate_pcmci_block_bootstrap( data: Union[Mapping[str, Any], Any], *, max_lag: int = 1, alpha: float = 0.05, fdr: bool = False, ci: str = 'parcorr', replicates: int = 20, block_size: int = 20, seed: int = 1, threads: int = 1) -> dict[str, typing.Any]: View Source

27def validate_pcmci_block_bootstrap(
28    data: Mapping[str, Any] | Any,
29    *,
30    max_lag: int = 1,
31    alpha: float = 0.05,
32    fdr: bool = False,
33    ci: str = "parcorr",
34    replicates: int = 20,
35    block_size: int = 20,
36    seed: int = 1,
37    threads: int = 1,
38) -> dict[str, Any]:
39    names, columns = as_columns(data)
40    return _validate_pcmci_block_bootstrap(
41        names,
42        columns,
43        max_lag=max_lag,
44        alpha=alpha,
45        fdr=fdr,
46        ci=ci,
47        replicates=replicates,
48        block_size=block_size,
49        seed=seed,
50        threads=threads,
51    )

def validate_pcmci_ci_sensitivity( data: Union[Mapping[str, Any], Any], ci_names: Sequence[str], *, max_lag: int = 1, alpha: float = 0.05, fdr: bool = False, seed: int = 1, threads: int = 1) -> dict[str, typing.Any]: View Source

127def validate_pcmci_ci_sensitivity(
128    data: Mapping[str, Any] | Any,
129    ci_names: Sequence[str],
130    *,
131    max_lag: int = 1,
132    alpha: float = 0.05,
133    fdr: bool = False,
134    seed: int = 1,
135    threads: int = 1,
136) -> dict[str, Any]:
137    names, columns = as_columns(data)
138    return _validate_pcmci_ci_sensitivity(
139        names,
140        columns,
141        list(ci_names),
142        max_lag=max_lag,
143        alpha=alpha,
144        fdr=fdr,
145        seed=seed,
146        threads=threads,
147    )

def validate_pcmci_false_positive( data: Union[Mapping[str, Any], Any], *, max_lag: int = 1, alpha: float = 0.05, fdr: bool = False, ci: str = 'parcorr', transform: str = 'permute', replicates: int = 20, seed: int = 1, threads: int = 1) -> dict[str, typing.Any]: View Source

54def validate_pcmci_false_positive(
55    data: Mapping[str, Any] | Any,
56    *,
57    max_lag: int = 1,
58    alpha: float = 0.05,
59    fdr: bool = False,
60    ci: str = "parcorr",
61    transform: str = "permute",
62    replicates: int = 20,
63    seed: int = 1,
64    threads: int = 1,
65) -> dict[str, Any]:
66    names, columns = as_columns(data)
67    return _validate_pcmci_false_positive(
68        names,
69        columns,
70        max_lag=max_lag,
71        alpha=alpha,
72        fdr=fdr,
73        ci=ci,
74        transform=transform,
75        replicates=replicates,
76        seed=seed,
77        threads=threads,
78    )

def validate_pcmci_lag_sensitivity( data: Union[Mapping[str, Any], Any], max_lags: Sequence[int], *, alpha: float = 0.05, fdr: bool = False, ci: str = 'parcorr', seed: int = 1, threads: int = 1) -> dict[str, typing.Any]: View Source

104def validate_pcmci_lag_sensitivity(
105    data: Mapping[str, Any] | Any,
106    max_lags: Sequence[int],
107    *,
108    alpha: float = 0.05,
109    fdr: bool = False,
110    ci: str = "parcorr",
111    seed: int = 1,
112    threads: int = 1,
113) -> dict[str, Any]:
114    names, columns = as_columns(data)
115    return _validate_pcmci_lag_sensitivity(
116        names,
117        columns,
118        [int(m) for m in max_lags],
119        alpha=alpha,
120        fdr=fdr,
121        ci=ci,
122        seed=seed,
123        threads=threads,
124    )

def validate_pcmci_plus_orientation( data: Union[Mapping[str, Any], Any], *, max_lag: int = 1, alpha: float = 0.05, fdr: bool = False, ci: str = 'parcorr', replicates: int = 20, block_size: int = 20, seed: int = 1, threads: int = 1) -> dict[str, typing.Any]: View Source

150def validate_pcmci_plus_orientation(
151    data: Mapping[str, Any] | Any,
152    *,
153    max_lag: int = 1,
154    alpha: float = 0.05,
155    fdr: bool = False,
156    ci: str = "parcorr",
157    replicates: int = 20,
158    block_size: int = 20,
159    seed: int = 1,
160    threads: int = 1,
161) -> dict[str, Any]:
162    names, columns = as_columns(data)
163    return _validate_pcmci_plus_orientation(
164        names,
165        columns,
166        max_lag=max_lag,
167        alpha=alpha,
168        fdr=fdr,
169        ci=ci,
170        replicates=replicates,
171        block_size=block_size,
172        seed=seed,
173        threads=threads,
174    )

def validate_regime_stability( data: Union[Mapping[str, Any], Any], regimes: Sequence[int], *, max_lag: int = 1, alpha: float = 0.05, fdr: bool = False, ci: str = 'parcorr', replicates: int = 10, block_size: int = 20, seed: int = 1, threads: int = 1) -> dict[str, typing.Any]: View Source

227def validate_regime_stability(
228    data: Mapping[str, Any] | Any,
229    regimes: Sequence[int],
230    *,
231    max_lag: int = 1,
232    alpha: float = 0.05,
233    fdr: bool = False,
234    ci: str = "parcorr",
235    replicates: int = 10,
236    block_size: int = 20,
237    seed: int = 1,
238    threads: int = 1,
239) -> dict[str, Any]:
240    names, columns = as_columns(data)
241    return _validate_regime_stability(
242        names,
243        columns,
244        [int(r) for r in regimes],
245        max_lag=max_lag,
246        alpha=alpha,
247        fdr=fdr,
248        ci=ci,
249        replicates=replicates,
250        block_size=block_size,
251        seed=seed,
252        threads=threads,
253    )

def validate_synthetic_null_calibration( *, max_lag: int = 1, alpha: float = 0.05, fdr: bool = False, ci: str = 'parcorr', n_sim: int = 20, n_obs: int = 100, n_vars: int = 3, seed: int = 1, threads: int = 1) -> dict[str, typing.Any]: View Source

177def validate_synthetic_null_calibration(
178    *,
179    max_lag: int = 1,
180    alpha: float = 0.05,
181    fdr: bool = False,
182    ci: str = "parcorr",
183    n_sim: int = 20,
184    n_obs: int = 100,
185    n_vars: int = 3,
186    seed: int = 1,
187    threads: int = 1,
188) -> dict[str, Any]:
189    return _validate_synthetic_null_calibration(
190        max_lag=max_lag,
191        alpha=alpha,
192        fdr=fdr,
193        ci=ci,
194        n_sim=n_sim,
195        n_obs=n_obs,
196        n_vars=n_vars,
197        seed=seed,
198        threads=threads,
199    )