causalcheck 0.1.0__tar.gz

causalcheck-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Taha Bouhoun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

causalcheck-0.1.0/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: causalcheck
+Version: 0.1.0
+Summary: Pre-flight assumption checks for causal discovery: which methods your data can support, and which outputs to trust.
+Author-email: Taha Bouhoun <bouhountaha@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Tahahaha7/causalcheck
+Project-URL: Issues, https://github.com/Tahahaha7/causalcheck/issues
+Keywords: causal discovery,causal inference,assumptions,diagnostics,LiNGAM,PC,FCI
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: full
+Requires-Dist: causal-learn>=0.1.3; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# causalcheck
+
+Pre-flight assumption checks for causal discovery.
+
+Every causal discovery method rests on assumptions about the data: linear relations, non-Gaussian noise, no hidden confounders, no near-deterministic links, comparable scales. Libraries will happily run any method on any data and return a confident graph either way. `causalcheck` looks at the data first and tells you which methods it can support, which outputs to trust, and what to fix before you run anything.
+
+It describes the data, not a graph. It does not do causal discovery itself.
+
+## Install
+
+```bash
+pip install causalcheck
+pip install "causalcheck[full]"   # adds causal-learn for the optional hidden-confounder check
+```
+
+## Usage
+
+Command line:
+
+```bash
+causalcheck data.csv               # text report
+causalcheck data.csv --json        # machine-readable
+causalcheck data.csv --confounding # also run FCI to flag likely hidden common causes (slower)
+```
+
+Python:
+
+```python
+import pandas as pd
+import causalcheck
+
+report = causalcheck.check(pd.read_csv("data.csv"))
+print(report)                 # text report
+report.to_json()              # same content as JSON
+report.worst_status           # "pass" | "info" | "warn" | "fail"
+report.advice.methods         # per-method verdicts
+```
+
+The exit code of the CLI is `1` when any check fails, so it can gate a pipeline.
+
+## What it checks
+
+| Check | Question it answers | Why it matters |
+|---|---|---|
+| data types | Which columns are continuous, discrete, or non-numeric? How many rows have missing values? | Additive-noise direction tests need continuous variables; mixed data needs mixed-data scores |
+| sample size | Is n large enough for the number of variables? | Small n gives weak CI tests and unstable orientations |
+| linearity | Does a spline model beat a straight line out of sample for any pair? | Fisher-z, linear BIC and LiNGAM are mis-specified on nonlinear pairs |
+| noise distribution | Are the residuals non-Gaussian (beyond a trivial amount)? | Non-Gaussian noise is what lets LiNGAM orient edges; Gaussian noise leaves only an equivalence class |
+| near-determinism | Is any variable almost fully explained by the others? Are any pairs effectively duplicates? | Faithfulness breaks: CI-based skeletons (PC, FCI) drop true edges; duplicates confuse every method |
+| scale | Do variances differ by orders of magnitude? | Continuous-optimization methods (NOTEARS, DAGMA) tend to recover the variance ordering instead of the causal one |
+| hidden confounding (optional) | Does FCI consistently see bidirected edges? | Methods that assume no latents will orient those edges wrongly |
+
+Each check returns one of four statuses:
+
+- `pass`: the assumption looks satisfied
+- `warn`: something that will mislead some methods
+- `fail`: a method family should not be used on this data as is
+- `info`: a finding that routes you to a method, with no good/bad meaning
+
+## What it recommends
+
+From the check results, the report gives:
+
+- **Fix first:** data problems to resolve before running anything (duplicates, standardization, unencoded columns, heavy missingness).
+- **Methods:** a verdict of `recommended`, `usable` or `avoid` for each family (PC, FCI/GFCI, GES/BOSS/GRaSP, DirectLiNGAM, ANM/CAM/RESIT, NOTEARS/DAGMA), with a one-line reason.
+- **How to read your results:** what the output of any method can and cannot mean on this data.
+
+## Example
+
+```
+causalcheck 0.1.0  |  1000 rows x 3 variables
+CHECKS
+  [PASS] linearity         all pairwise relations look linear
+  [PASS] noise distribution 3/3 residuals clearly non-Gaussian -> LiNGAM-style direction identification is possible
+  [WARN] scale             variances differ by a factor of 37 -> standardize first
+METHODS
+  recommended  GES / BOSS / GRaSP (score-based): most reliable skeleton
+  recommended  DirectLiNGAM: linear with non-Gaussian noise: full DAG and coefficients are identifiable
+  avoid        NOTEARS / DAGMA (continuous optimization): variance ordering will drive the result
+```
+
+## Limitations
+
+- Some assumptions cannot be tested from observational data: faithfulness (no canceling effects) and the absence of selection bias. The report says so rather than pretending.
+- The noise check uses each variable's residual given all others as a stand-in for its true disturbance, because the graph is unknown.
+- The hidden-confounder check is a signal, not a proof. Passing it does not rule out confounding.
+- Thresholds (linearity gain 0.02, R² 0.98 for near-determinism, variance ratio 10) are sensible defaults, not laws. All are arguments to the check functions.
+
+## Development
+
+```bash
+git clone https://github.com/Tahahaha7/causalcheck && cd causalcheck
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

causalcheck-0.1.0/README.md

@@ -0,0 +1,100 @@
+# causalcheck
+
+Pre-flight assumption checks for causal discovery.
+
+Every causal discovery method rests on assumptions about the data: linear relations, non-Gaussian noise, no hidden confounders, no near-deterministic links, comparable scales. Libraries will happily run any method on any data and return a confident graph either way. `causalcheck` looks at the data first and tells you which methods it can support, which outputs to trust, and what to fix before you run anything.
+
+It describes the data, not a graph. It does not do causal discovery itself.
+
+## Install
+
+```bash
+pip install causalcheck
+pip install "causalcheck[full]"   # adds causal-learn for the optional hidden-confounder check
+```
+
+## Usage
+
+Command line:
+
+```bash
+causalcheck data.csv               # text report
+causalcheck data.csv --json        # machine-readable
+causalcheck data.csv --confounding # also run FCI to flag likely hidden common causes (slower)
+```
+
+Python:
+
+```python
+import pandas as pd
+import causalcheck
+
+report = causalcheck.check(pd.read_csv("data.csv"))
+print(report)                 # text report
+report.to_json()              # same content as JSON
+report.worst_status           # "pass" | "info" | "warn" | "fail"
+report.advice.methods         # per-method verdicts
+```
+
+The exit code of the CLI is `1` when any check fails, so it can gate a pipeline.
+
+## What it checks
+
+| Check | Question it answers | Why it matters |
+|---|---|---|
+| data types | Which columns are continuous, discrete, or non-numeric? How many rows have missing values? | Additive-noise direction tests need continuous variables; mixed data needs mixed-data scores |
+| sample size | Is n large enough for the number of variables? | Small n gives weak CI tests and unstable orientations |
+| linearity | Does a spline model beat a straight line out of sample for any pair? | Fisher-z, linear BIC and LiNGAM are mis-specified on nonlinear pairs |
+| noise distribution | Are the residuals non-Gaussian (beyond a trivial amount)? | Non-Gaussian noise is what lets LiNGAM orient edges; Gaussian noise leaves only an equivalence class |
+| near-determinism | Is any variable almost fully explained by the others? Are any pairs effectively duplicates? | Faithfulness breaks: CI-based skeletons (PC, FCI) drop true edges; duplicates confuse every method |
+| scale | Do variances differ by orders of magnitude? | Continuous-optimization methods (NOTEARS, DAGMA) tend to recover the variance ordering instead of the causal one |
+| hidden confounding (optional) | Does FCI consistently see bidirected edges? | Methods that assume no latents will orient those edges wrongly |
+
+Each check returns one of four statuses:
+
+- `pass`: the assumption looks satisfied
+- `warn`: something that will mislead some methods
+- `fail`: a method family should not be used on this data as is
+- `info`: a finding that routes you to a method, with no good/bad meaning
+
+## What it recommends
+
+From the check results, the report gives:
+
+- **Fix first:** data problems to resolve before running anything (duplicates, standardization, unencoded columns, heavy missingness).
+- **Methods:** a verdict of `recommended`, `usable` or `avoid` for each family (PC, FCI/GFCI, GES/BOSS/GRaSP, DirectLiNGAM, ANM/CAM/RESIT, NOTEARS/DAGMA), with a one-line reason.
+- **How to read your results:** what the output of any method can and cannot mean on this data.
+
+## Example
+
+```
+causalcheck 0.1.0  |  1000 rows x 3 variables
+CHECKS
+  [PASS] linearity         all pairwise relations look linear
+  [PASS] noise distribution 3/3 residuals clearly non-Gaussian -> LiNGAM-style direction identification is possible
+  [WARN] scale             variances differ by a factor of 37 -> standardize first
+METHODS
+  recommended  GES / BOSS / GRaSP (score-based): most reliable skeleton
+  recommended  DirectLiNGAM: linear with non-Gaussian noise: full DAG and coefficients are identifiable
+  avoid        NOTEARS / DAGMA (continuous optimization): variance ordering will drive the result
+```
+
+## Limitations
+
+- Some assumptions cannot be tested from observational data: faithfulness (no canceling effects) and the absence of selection bias. The report says so rather than pretending.
+- The noise check uses each variable's residual given all others as a stand-in for its true disturbance, because the graph is unknown.
+- The hidden-confounder check is a signal, not a proof. Passing it does not rule out confounding.
+- Thresholds (linearity gain 0.02, R² 0.98 for near-determinism, variance ratio 10) are sensible defaults, not laws. All are arguments to the check functions.
+
+## Development
+
+```bash
+git clone https://github.com/Tahahaha7/causalcheck && cd causalcheck
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

causalcheck-0.1.0/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "causalcheck"
+version = "0.1.0"
+description = "Pre-flight assumption checks for causal discovery: which methods your data can support, and which outputs to trust."
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.9"
+authors = [{ name = "Taha Bouhoun", email = "bouhountaha@gmail.com" }]
+keywords = ["causal discovery", "causal inference", "assumptions", "diagnostics", "LiNGAM", "PC", "FCI"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering",
+]
+dependencies = ["numpy>=1.23", "pandas>=1.5", "scipy>=1.9", "scikit-learn>=1.2"]
+
+[project.optional-dependencies]
+full = ["causal-learn>=0.1.3"]
+dev = ["pytest>=7", "build", "twine"]
+
+[project.urls]
+Homepage = "https://github.com/Tahahaha7/causalcheck"
+Issues = "https://github.com/Tahahaha7/causalcheck/issues"
+
+[project.scripts]
+causalcheck = "causalcheck.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

causalcheck-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

causalcheck-0.1.0/src/causalcheck/__init__.py

@@ -0,0 +1,13 @@
+"""causalcheck: pre-flight assumption checks for causal discovery.
+
+    import causalcheck
+    report = causalcheck.check(df)        # df: pandas DataFrame
+    print(report)                         # text report
+    report.to_json()                      # machine-readable
+"""
+from .checks import CheckResult, run_checks
+from .recommend import Advice, Recommendation, recommend
+from .report import Report, check
+
+__version__ = "0.1.0"
+__all__ = ["check", "Report", "CheckResult", "run_checks", "recommend", "Advice", "Recommendation"]

causalcheck-0.1.0/src/causalcheck/checks.py

@@ -0,0 +1,262 @@
+"""Pre-flight assumption checks for causal discovery.
+
+Each check inspects the data (not any graph) and returns a CheckResult with a status:
+  pass  - assumption looks satisfied
+  warn  - something that will mislead some methods
+  fail  - a method family should not be used on this data
+  info  - a finding that routes you to a method, with no good/bad meaning
+"""
+from __future__ import annotations
+
+import contextlib
+import warnings
+from dataclasses import dataclass, field
+
+import numpy as np
+import pandas as pd
+from scipy import stats
+from sklearn.linear_model import LinearRegression, RidgeCV
+from sklearn.model_selection import KFold, cross_val_score
+from sklearn.pipeline import make_pipeline
+from sklearn.preprocessing import SplineTransformer
+
+
+
+@contextlib.contextmanager
+def _quiet():
+    """Silence numeric/convergence warnings from numpy and sklearn only while a check runs."""
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", RuntimeWarning)
+        warnings.simplefilter("ignore", UserWarning)
+        yield
+
+
+@dataclass
+class CheckResult:
+    name: str
+    status: str
+    summary: str
+    details: dict = field(default_factory=dict)
+
+
+@dataclass
+class Prepared:
+    X: np.ndarray            # standardized numeric data, rows with missing values dropped
+    raw: np.ndarray          # same rows, original scale
+    names: list[str]
+    discrete: list[str]      # numeric but low-cardinality columns
+    dropped: list[str]       # non-numeric columns
+    n_missing_rows: int
+
+
+def _gam():
+    return make_pipeline(SplineTransformer(n_knots=6, degree=3, extrapolation="linear"),
+                         RidgeCV(alphas=np.logspace(-3, 3, 13)))
+
+
+def _cv_r2(model, D, y, seed):
+    kf = KFold(5, shuffle=True, random_state=seed)
+    return float(cross_val_score(model, D, y, cv=kf, scoring="r2").mean())
+
+
+def prepare(df: pd.DataFrame, min_unique: int = 10) -> Prepared:
+    num = df.select_dtypes(include=[np.number])
+    dropped = [c for c in df.columns if c not in num.columns]
+    n0 = len(num)
+    num = num.dropna()
+    num = num.loc[:, num.std() > 0]
+    names = list(num.columns)
+    discrete = [c for c in names if num[c].nunique() < min_unique]
+    raw = num.to_numpy(float)
+    X = (raw - raw.mean(0)) / raw.std(0)
+    return Prepared(X, raw, names, discrete, dropped, n0 - len(num))
+
+
+# ---------------------------------------------------------------- checks
+
+def check_data_types(prep: Prepared, n_total_rows: int) -> CheckResult:
+    d = dict(numeric=len(prep.names), discrete=prep.discrete, dropped=prep.dropped,
+             rows_used=len(prep.X), rows_dropped_missing=prep.n_missing_rows)
+    if prep.dropped and not prep.names:
+        return CheckResult("data types", "fail", "no numeric columns found", d)
+    if prep.discrete or prep.dropped:
+        what = []
+        if prep.discrete:
+            what.append(f"{len(prep.discrete)} low-cardinality column(s) treated as discrete")
+        if prep.dropped:
+            what.append(f"{len(prep.dropped)} non-numeric column(s) ignored")
+        return CheckResult("data types", "warn", "; ".join(what)
+                           + " -> use mixed-data scores/tests, skip additive-noise tests on them", d)
+    return CheckResult("data types", "pass", f"{len(prep.names)} continuous columns, "
+                       f"{prep.n_missing_rows} of {n_total_rows} rows dropped for missing values", d)
+
+
+def check_sample_size(prep: Prepared) -> CheckResult:
+    n, p = prep.X.shape
+    d = dict(n=n, p=p, n_per_variable=round(n / max(p, 1), 1))
+    if n < 200 or n < 20 * p:
+        return CheckResult("sample size", "warn",
+                           f"n={n} for p={p} variables: expect low power, unstable orientations, "
+                           "and many undirected edges", d)
+    if n < 1000:
+        return CheckResult("sample size", "pass",
+                           f"n={n} for p={p}: fine for skeleton; direction tests may be weak", d)
+    return CheckResult("sample size", "pass", f"n={n} for p={p}", d)
+
+
+def check_linearity(prep: Prepared, tol: float = 0.02, max_rows: int = 2000, seed: int = 0) -> CheckResult:
+    """Pairwise: does a spline GAM beat a straight line out of sample?"""
+    X, names = prep.X, prep.names
+    rng = np.random.default_rng(seed)
+    Xs = X[rng.choice(len(X), min(len(X), max_rows), replace=False)]
+    cont = [k for k, c in enumerate(names) if c not in prep.discrete]
+    nonlinear = []
+    for i in cont:
+        for j in cont:
+            if i == j:
+                continue
+            D, y = Xs[:, [i]], Xs[:, j]
+            gain = _cv_r2(_gam(), D, y, seed) - _cv_r2(LinearRegression(), D, y, seed)
+            if gain > tol:
+                nonlinear.append((names[i], names[j], round(gain, 3)))
+    nonlinear.sort(key=lambda t: -t[2])
+    d = dict(nonlinear_pairs=nonlinear, tol=tol, pairs_tested=len(cont) * (len(cont) - 1))
+    if nonlinear:
+        return CheckResult("linearity", "info",
+                           f"{len(nonlinear)} pair(s) clearly nonlinear (largest R2 gain "
+                           f"{nonlinear[0][2]:.2f}) -> linear methods (LiNGAM, Fisher-z, linear BIC) "
+                           "will mis-specify these", d)
+    return CheckResult("linearity", "pass",
+                       "all pairwise relations look linear -> linear scores and tests are appropriate", d)
+
+
+def check_noise(prep: Prepared, linear: bool, alpha: float = 0.01,
+                min_skew: float = 0.3, min_kurt: float = 0.5) -> CheckResult:
+    """Non-Gaussian disturbances are what let LiNGAM/ANM orient edges.
+
+    Without the graph we use each variable's residual given all other variables as a proxy:
+    if every disturbance is Gaussian, these residuals are Gaussian too.
+    """
+    X, names = prep.X, prep.names
+    cont = [k for k, c in enumerate(names) if c not in prep.discrete]
+    rows = []
+    for v in cont:
+        others = [u for u in cont if u != v]
+        if not others:
+            r = X[:, v]
+        else:
+            m = LinearRegression() if linear else _gam()
+            m.fit(X[:, others], X[:, v])
+            r = X[:, v] - m.predict(X[:, others])
+        r = (r - r.mean()) / (r.std() + 1e-12)
+        p = float(stats.normaltest(r).pvalue) if len(r) >= 20 else 1.0
+        sk, ku = float(stats.skew(r)), float(stats.kurtosis(r))
+        nongauss = p < alpha and (abs(sk) > min_skew or abs(ku) > min_kurt)
+        rows.append(dict(variable=names[v], p=p, skew=round(sk, 2), excess_kurtosis=round(ku, 2),
+                         non_gaussian=bool(nongauss)))
+    k = sum(r["non_gaussian"] for r in rows)
+    d = dict(per_variable=rows, non_gaussian_count=k, tested=len(rows))
+    if not linear:
+        return CheckResult("noise distribution", "info",
+                           f"{k}/{len(rows)} residuals non-Gaussian; with nonlinear relations, additive-noise "
+                           "methods (ANM, CAM, RESIT) can orient edges regardless of noise shape", d)
+    if len(rows) and k >= len(rows) - 1:
+        return CheckResult("noise distribution", "pass",
+                           f"{k}/{len(rows)} residuals clearly non-Gaussian -> LiNGAM-style "
+                           "direction identification is possible", d)
+    if k == 0:
+        return CheckResult("noise distribution", "warn",
+                           "all residuals look Gaussian -> directions beyond colliders are not "
+                           "identifiable; expect an equivalence class, do not trust LiNGAM arrows", d)
+    return CheckResult("noise distribution", "info",
+                       f"{k}/{len(rows)} residuals non-Gaussian -> LiNGAM needs at most one Gaussian "
+                       "disturbance; trust only arrows touching the non-Gaussian variables", d)
+
+
+def check_determinism(prep: Prepared, r2_thresh: float = 0.98, corr_thresh: float = 0.99,
+                      dup_thresh: float = 0.999) -> CheckResult:
+    """Near-deterministic links break faithfulness: CI tests drop true edges."""
+    X, names = prep.X, prep.names
+    flagged = []
+    for v in range(len(names)):
+        others = [u for u in range(len(names)) if u != v]
+        if not others:
+            continue
+        m = LinearRegression().fit(X[:, others], X[:, v])
+        r2 = float(m.score(X[:, others], X[:, v]))
+        if r2 > r2_thresh:
+            flagged.append((names[v], round(r2, 4)))
+    C = np.corrcoef(X.T) if len(names) > 1 else np.eye(1)
+    pairs = [(names[i], names[j], round(float(C[i, j]), 4))
+             for i in range(len(names)) for j in range(i + 1, len(names)) if abs(C[i, j]) > corr_thresh]
+    dups = [t for t in pairs if abs(t[2]) > dup_thresh]
+    d = dict(near_deterministic_variables=flagged, near_deterministic_pairs=pairs, duplicate_pairs=dups)
+    if dups:
+        return CheckResult("near-determinism", "fail",
+                           f"{len(dups)} pair(s) correlated above {dup_thresh} -> effectively the same "
+                           "variable; merge or drop one of each pair before running anything", d)
+    if flagged or pairs:
+        return CheckResult("near-determinism", "warn",
+                           f"{len(flagged)} variable(s) almost fully explained by the others and "
+                           f"{len(pairs)} pair(s) correlated above {corr_thresh} -> faithfulness at risk: "
+                           "CI-based skeletons (PC, FCI) will drop true edges; prefer score-based search "
+                           "(BOSS, GES)", d)
+    return CheckResult("near-determinism", "pass", "no near-deterministic relations", d)
+
+
+def check_scale(prep: Prepared, ratio_thresh: float = 10.0) -> CheckResult:
+    """Large variance differences let continuous-optimization methods sort by variance (varsortability)."""
+    var = prep.raw.var(0)
+    ratio = float(var.max() / max(var.min(), 1e-12))
+    d = dict(variance_ratio=round(ratio, 1), variances={n: float(v) for n, v in zip(prep.names, var)})
+    if ratio > ratio_thresh:
+        return CheckResult("scale", "warn",
+                           f"variances differ by a factor of {ratio:.0f} -> NOTEARS/DAGMA-style methods "
+                           "may just recover the variance ordering; standardize first and distrust "
+                           "directions that follow variance", d)
+    return CheckResult("scale", "pass", "variables are on comparable scales", d)
+
+
+def check_confounding(prep: Prepared, linear: bool, n_boot: int = 5, frac: float = 0.8,
+                      alpha: float = 0.05, seed: int = 0) -> CheckResult:
+    """Optional: signs of hidden common causes, via bidirected edges in FCI (needs causal-learn)."""
+    try:
+        from causallearn.search.ConstraintBased.FCI import fci
+    except ImportError:
+        return CheckResult("hidden confounding", "info",
+                           "skipped: install causal-learn (pip install causalcheck[full]) to run FCI", {})
+    X = prep.X
+    n = len(X)
+    ci = "fisherz" if linear else "kci"
+    m = min(int(frac * n), n if linear else 500)
+    rng = np.random.default_rng(seed)
+    p = X.shape[1]
+    bi = np.zeros((p, p))
+    for _ in range(n_boot):
+        G, _ = fci(X[rng.choice(n, m, replace=False)], independence_test_method=ci, alpha=alpha,
+                   verbose=False, show_progress=False)
+        g = G.graph
+        bi += (g == 1) & (g.T == 1)
+    pairs = [(prep.names[i], prep.names[j], round(bi[i, j] / n_boot, 2))
+             for i in range(p) for j in range(i + 1, p) if bi[i, j] / n_boot >= 0.6]
+    d = dict(bidirected_pairs=pairs, ci_test=ci, subsamples=n_boot)
+    if pairs:
+        return CheckResult("hidden confounding", "warn",
+                           f"{len(pairs)} pair(s) consistently bidirected in FCI -> likely hidden common "
+                           "causes; methods that assume no latents (PC, GES, BOSS, LiNGAM) will orient "
+                           "these wrongly", d)
+    return CheckResult("hidden confounding", "pass",
+                       "no consistent signs of hidden common causes (not a guarantee)", d)
+
+
+def run_checks(df: pd.DataFrame, confounding: bool = False, seed: int = 0) -> tuple[Prepared, list[CheckResult]]:
+    with _quiet():
+        prep = prepare(df)
+        results = [check_data_types(prep, len(df)), check_sample_size(prep)]
+        if len(prep.names) >= 2:
+            lin = check_linearity(prep, seed=seed)
+            linear = lin.status == "pass"
+            results += [lin, check_noise(prep, linear), check_determinism(prep), check_scale(prep)]
+            if confounding:
+                results.append(check_confounding(prep, linear, seed=seed))
+    return prep, results

causalcheck-0.1.0/src/causalcheck/cli.py

@@ -0,0 +1,51 @@
+"""Command line: `causalcheck data.csv [--json] [--confounding]`."""
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+import pandas as pd
+
+from .report import check
+
+
+def _load(path: str, sep: str | None) -> pd.DataFrame:
+    p = Path(path)
+    if not p.exists():
+        sys.exit(f"causalcheck: file not found: {path}")
+    suffix = p.suffix.lower()
+    if suffix in (".parquet", ".pq"):
+        return pd.read_parquet(p)
+    if suffix in (".xlsx", ".xls"):
+        return pd.read_excel(p)
+    if suffix in (".tsv", ".tab"):
+        return pd.read_csv(p, sep="\t")
+    return pd.read_csv(p, sep=sep) if sep else pd.read_csv(p, sep=None, engine="python")
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(
+        prog="causalcheck",
+        description="Pre-flight assumption checks for causal discovery: which methods your data "
+                    "can support, and which outputs to trust.")
+    ap.add_argument("file", help="CSV, TSV, Parquet, or Excel file with one column per variable")
+    ap.add_argument("--json", action="store_true", help="print a JSON report instead of text")
+    ap.add_argument("--confounding", action="store_true",
+                    help="also run the hidden-confounder check (needs causal-learn, slower)")
+    ap.add_argument("--sep", default=None, help="CSV delimiter (auto-detected if omitted)")
+    ap.add_argument("--seed", type=int, default=0, help="random seed for subsampling")
+    ap.add_argument("--width", type=int, default=100, help="text report width")
+    args = ap.parse_args(argv)
+
+    df = _load(args.file, args.sep)
+    report = check(df, confounding=args.confounding, seed=args.seed)
+    try:
+        print(report.to_json() if args.json else report.to_text(width=args.width))
+    except BrokenPipeError:  # e.g. piped into `head`
+        pass
+    return 1 if report.worst_status == "fail" else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

causalcheck-0.1.0/src/causalcheck/recommend.py

@@ -0,0 +1,153 @@
+"""Turn check results into advice: what to fix first, which methods fit, what to trust."""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from .checks import CheckResult
+
+RECOMMENDED, USABLE, AVOID = "recommended", "usable", "avoid"
+
+
+@dataclass
+class Recommendation:
+    method: str
+    verdict: str
+    reason: str
+
+
+@dataclass
+class Advice:
+    fix_first: list[str] = field(default_factory=list)
+    methods: list[Recommendation] = field(default_factory=list)
+    trust: list[str] = field(default_factory=list)
+
+
+def _by_name(results: list[CheckResult]) -> dict[str, CheckResult]:
+    return {r.name: r for r in results}
+
+
+def recommend(results: list[CheckResult]) -> Advice:
+    r = _by_name(results)
+    adv = Advice()
+
+    types = r.get("data types")
+    size = r.get("sample size")
+    lin = r.get("linearity")
+    noise = r.get("noise distribution")
+    det = r.get("near-determinism")
+    scale = r.get("scale")
+    conf = r.get("hidden confounding")
+
+    linear = lin is not None and lin.status == "pass"
+    nongauss = noise is not None and noise.status == "pass"
+    gaussian = noise is not None and noise.status == "warn"
+    mixed = types is not None and bool(types.details.get("discrete"))
+    small = size is not None and size.status == "warn"
+    near_det = det is not None and det.status in ("warn", "fail")
+    latents = conf is not None and conf.status == "warn"
+    latents_untested = conf is None or conf.status == "info"
+
+    # ---- fix first
+    if det is not None and det.status == "fail":
+        adv.fix_first.append("Drop or merge the near-duplicate columns listed under near-determinism; "
+                             "every method treats them as a confusing extra edge.")
+    if scale is not None and scale.status == "warn":
+        adv.fix_first.append("Standardize all variables before running anything, or any continuous-"
+                             "optimization method will mostly recover the variance ordering.")
+    if types is not None and types.details.get("dropped"):
+        adv.fix_first.append(f"Encode or drop the non-numeric columns {types.details['dropped']} explicitly, "
+                             "rather than letting them be silently ignored.")
+    if types is not None and types.details.get("rows_dropped_missing", 0) > 0.2 * types.details.get("rows_used", 1):
+        adv.fix_first.append("More than 20% of rows were dropped for missing values; impute or check "
+                             "whether missingness itself depends on the variables.")
+
+    # ---- method verdicts
+    def add(method, verdict, reason):
+        adv.methods.append(Recommendation(method, verdict, reason))
+
+    # constraint-based, no latents
+    if near_det:
+        add("PC (constraint-based)", AVOID, "near-deterministic links make CI tests drop true edges")
+    elif latents:
+        add("PC (constraint-based)", AVOID, "assumes no hidden confounders, but FCI found signs of them")
+    else:
+        add("PC (constraint-based)", USABLE, "use fisherz if linear, kci if nonlinear; expect an equivalence class")
+
+    # latent-tolerant constraint-based
+    if near_det:
+        add("FCI / GFCI (latent-tolerant)", USABLE if latents else AVOID,
+            "CI tests are unreliable here; if you need latent handling, use GFCI or BOSS-FCI, "
+            "which take the skeleton from a score")
+    else:
+        add("FCI / GFCI (latent-tolerant)", RECOMMENDED if (latents or latents_untested) else USABLE,
+            "honest about hidden confounding; output is a PAG with circle endpoints")
+
+    # score-based
+    if latents:
+        add("GES / BOSS / GRaSP (score-based)", USABLE,
+            "best skeleton recovery, but orientations assume no latents; check them against FCI")
+    else:
+        add("GES / BOSS / GRaSP (score-based)", RECOMMENDED,
+            "most reliable skeleton" + ("; the right choice under near-determinism" if near_det else "")
+            + ("; use a mixed-data score (conditional Gaussian / BDeu)" if mixed else "")
+            + ("; use a nonparametric score (basis-function BIC)" if not linear else ""))
+
+    # LiNGAM
+    if not linear:
+        add("DirectLiNGAM", AVOID, "relations are nonlinear; LiNGAM's linear model is mis-specified")
+    elif gaussian:
+        add("DirectLiNGAM", AVOID, "noise looks Gaussian: LiNGAM will output confident but arbitrary directions")
+    elif latents:
+        add("DirectLiNGAM", AVOID, "signs of hidden confounding; use RCD or LiNGAM-with-latents instead")
+    elif nongauss:
+        add("DirectLiNGAM", RECOMMENDED, "linear with non-Gaussian noise: full DAG and coefficients are identifiable"
+            + ("; verify directions with bootstrap at this sample size" if small else ""))
+    else:
+        add("DirectLiNGAM", USABLE, "only some disturbances are non-Gaussian; trust arrows touching those variables")
+
+    # nonlinear additive-noise
+    if not linear and not mixed:
+        add("ANM / CAM / RESIT (nonlinear additive noise)", RECOMMENDED if not latents else USABLE,
+            "nonlinearity itself identifies directions" + ("; confounding may bias them" if latents else ""))
+    elif mixed:
+        add("ANM / CAM / RESIT (nonlinear additive noise)", AVOID, "needs continuous variables; discrete columns present")
+    else:
+        add("ANM / CAM / RESIT (nonlinear additive noise)", USABLE,
+            "works, but with linear relations the direction signal comes only from non-Gaussian noise")
+
+    # continuous optimization
+    if scale is not None and scale.status == "warn":
+        add("NOTEARS / DAGMA (continuous optimization)", AVOID,
+            "variance ordering will drive the result (varsortability); standardize first and still distrust directions")
+    elif gaussian:
+        add("NOTEARS / DAGMA (continuous optimization)", AVOID,
+            "with Gaussian noise its directions are not identifiable; it will still output a DAG")
+    else:
+        add("NOTEARS / DAGMA (continuous optimization)", USABLE,
+            "fine for a skeleton; validate directions against a method with identifiability guarantees")
+
+    # ---- trust notes
+    if gaussian:
+        adv.trust.append("Expect an equivalence class: only collider patterns can be oriented from this data. "
+                         "Treat any fully directed output as a guess beyond those.")
+    if nongauss and linear:
+        adv.trust.append("Directions and coefficients from LiNGAM are trustworthy here, provided there are "
+                         "no hidden confounders.")
+    if not linear:
+        adv.trust.append("Linear-only outputs (Fisher-z tests, linear BIC, LiNGAM) are mis-specified for the "
+                         "nonlinear pairs listed in the linearity check.")
+    if near_det:
+        adv.trust.append("Missing edges from PC/FCI are suspect: near-deterministic links hide real "
+                         "dependencies from CI tests.")
+    if small:
+        adv.trust.append("Bootstrap every result; keep only edges and directions that appear in most resamples.")
+    if latents:
+        adv.trust.append("Pairs flagged as bidirected may be driven by a hidden common cause; "
+                         "do not read their arrows as cause and effect.")
+    elif latents_untested:
+        adv.trust.append("Hidden confounding was not tested; no method here can rule it out from "
+                         "observational data alone.")
+    if mixed:
+        adv.trust.append("Additive-noise direction tests are meaningless on the discrete columns; "
+                         "their edges will stay undirected unless a collider orients them.")
+    return adv

causalcheck-0.1.0/src/causalcheck/report.py

@@ -0,0 +1,96 @@
+"""Report: the result of running all checks, printable as text or JSON."""
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+
+import pandas as pd
+
+from .checks import CheckResult, run_checks
+from .recommend import Advice, recommend
+
+_TAG = {"pass": "PASS", "warn": "WARN", "fail": "FAIL", "info": "INFO"}
+
+
+@dataclass
+class Report:
+    n_rows: int
+    variables: list[str]
+    discrete: list[str]
+    checks: list[CheckResult]
+    advice: Advice
+    version: str = "0.1.0"
+
+    @property
+    def worst_status(self) -> str:
+        order = {"fail": 3, "warn": 2, "info": 1, "pass": 0}
+        return max((c.status for c in self.checks), key=lambda s: order[s], default="pass")
+
+    def to_dict(self) -> dict:
+        return dict(causalcheck=self.version, n_rows=self.n_rows, variables=self.variables,
+                    discrete=self.discrete, worst_status=self.worst_status,
+                    checks=[asdict(c) for c in self.checks], advice=asdict(self.advice))
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, default=_jsonable)
+
+    def to_text(self, width: int = 100) -> str:
+        lines = [f"causalcheck {self.version}  |  {self.n_rows} rows x {len(self.variables)} variables"
+                 + (f"  ({len(self.discrete)} discrete)" if self.discrete else ""),
+                 "=" * width, "CHECKS"]
+        for c in self.checks:
+            lines.append(f"  [{_TAG[c.status]}] {c.name}")
+            lines += _wrap(c.summary, width, indent=9)
+        if self.advice.fix_first:
+            lines += ["", "FIX FIRST"]
+            for f in self.advice.fix_first:
+                lines += _wrap("- " + f, width, indent=2, hang=4)
+        lines += ["", "METHODS"]
+        for m in self.advice.methods:
+            lines += _wrap(f"{m.verdict:<12} {m.method}: {m.reason}", width, indent=2, hang=15)
+        if self.advice.trust:
+            lines += ["", "HOW TO READ YOUR RESULTS"]
+            for t in self.advice.trust:
+                lines += _wrap("- " + t, width, indent=2, hang=4)
+        lines += ["=" * width,
+                  "Checks describe the data, not any graph. They cannot detect every violation "
+                  "(faithfulness and selection bias are untestable)."]
+        return "\n".join(lines)
+
+    def __str__(self) -> str:
+        return self.to_text()
+
+
+def _wrap(text: str, width: int, indent: int, hang: int | None = None) -> list[str]:
+    import textwrap
+    hang = indent if hang is None else hang
+    return textwrap.wrap(text, width=width, initial_indent=" " * indent, subsequent_indent=" " * hang) or [""]
+
+
+def _jsonable(o):
+    try:
+        import numpy as np
+        if isinstance(o, (np.integer,)):
+            return int(o)
+        if isinstance(o, (np.floating,)):
+            return float(o)
+        if isinstance(o, (np.bool_,)):
+            return bool(o)
+        if isinstance(o, np.ndarray):
+            return o.tolist()
+    except ImportError:
+        pass
+    return str(o)
+
+
+def check(data, confounding: bool = False, seed: int = 0) -> Report:
+    """Run every check on a DataFrame (or anything DataFrame() accepts) and return a Report.
+
+    >>> import causalcheck
+    >>> report = causalcheck.check(df)
+    >>> print(report)
+    """
+    df = data if isinstance(data, pd.DataFrame) else pd.DataFrame(data)
+    prep, results = run_checks(df, confounding=confounding, seed=seed)
+    return Report(n_rows=len(prep.X), variables=prep.names, discrete=prep.discrete,
+                  checks=results, advice=recommend(results))

causalcheck-0.1.0/src/causalcheck.egg-info/PKG-INFO

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: causalcheck
+Version: 0.1.0
+Summary: Pre-flight assumption checks for causal discovery: which methods your data can support, and which outputs to trust.
+Author-email: Taha Bouhoun <bouhountaha@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Tahahaha7/causalcheck
+Project-URL: Issues, https://github.com/Tahahaha7/causalcheck/issues
+Keywords: causal discovery,causal inference,assumptions,diagnostics,LiNGAM,PC,FCI
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: scikit-learn>=1.2
+Provides-Extra: full
+Requires-Dist: causal-learn>=0.1.3; extra == "full"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Dynamic: license-file
+
+# causalcheck
+
+Pre-flight assumption checks for causal discovery.
+
+Every causal discovery method rests on assumptions about the data: linear relations, non-Gaussian noise, no hidden confounders, no near-deterministic links, comparable scales. Libraries will happily run any method on any data and return a confident graph either way. `causalcheck` looks at the data first and tells you which methods it can support, which outputs to trust, and what to fix before you run anything.
+
+It describes the data, not a graph. It does not do causal discovery itself.
+
+## Install
+
+```bash
+pip install causalcheck
+pip install "causalcheck[full]"   # adds causal-learn for the optional hidden-confounder check
+```
+
+## Usage
+
+Command line:
+
+```bash
+causalcheck data.csv               # text report
+causalcheck data.csv --json        # machine-readable
+causalcheck data.csv --confounding # also run FCI to flag likely hidden common causes (slower)
+```
+
+Python:
+
+```python
+import pandas as pd
+import causalcheck
+
+report = causalcheck.check(pd.read_csv("data.csv"))
+print(report)                 # text report
+report.to_json()              # same content as JSON
+report.worst_status           # "pass" | "info" | "warn" | "fail"
+report.advice.methods         # per-method verdicts
+```
+
+The exit code of the CLI is `1` when any check fails, so it can gate a pipeline.
+
+## What it checks
+
+| Check | Question it answers | Why it matters |
+|---|---|---|
+| data types | Which columns are continuous, discrete, or non-numeric? How many rows have missing values? | Additive-noise direction tests need continuous variables; mixed data needs mixed-data scores |
+| sample size | Is n large enough for the number of variables? | Small n gives weak CI tests and unstable orientations |
+| linearity | Does a spline model beat a straight line out of sample for any pair? | Fisher-z, linear BIC and LiNGAM are mis-specified on nonlinear pairs |
+| noise distribution | Are the residuals non-Gaussian (beyond a trivial amount)? | Non-Gaussian noise is what lets LiNGAM orient edges; Gaussian noise leaves only an equivalence class |
+| near-determinism | Is any variable almost fully explained by the others? Are any pairs effectively duplicates? | Faithfulness breaks: CI-based skeletons (PC, FCI) drop true edges; duplicates confuse every method |
+| scale | Do variances differ by orders of magnitude? | Continuous-optimization methods (NOTEARS, DAGMA) tend to recover the variance ordering instead of the causal one |
+| hidden confounding (optional) | Does FCI consistently see bidirected edges? | Methods that assume no latents will orient those edges wrongly |
+
+Each check returns one of four statuses:
+
+- `pass`: the assumption looks satisfied
+- `warn`: something that will mislead some methods
+- `fail`: a method family should not be used on this data as is
+- `info`: a finding that routes you to a method, with no good/bad meaning
+
+## What it recommends
+
+From the check results, the report gives:
+
+- **Fix first:** data problems to resolve before running anything (duplicates, standardization, unencoded columns, heavy missingness).
+- **Methods:** a verdict of `recommended`, `usable` or `avoid` for each family (PC, FCI/GFCI, GES/BOSS/GRaSP, DirectLiNGAM, ANM/CAM/RESIT, NOTEARS/DAGMA), with a one-line reason.
+- **How to read your results:** what the output of any method can and cannot mean on this data.
+
+## Example
+
+```
+causalcheck 0.1.0  |  1000 rows x 3 variables
+CHECKS
+  [PASS] linearity         all pairwise relations look linear
+  [PASS] noise distribution 3/3 residuals clearly non-Gaussian -> LiNGAM-style direction identification is possible
+  [WARN] scale             variances differ by a factor of 37 -> standardize first
+METHODS
+  recommended  GES / BOSS / GRaSP (score-based): most reliable skeleton
+  recommended  DirectLiNGAM: linear with non-Gaussian noise: full DAG and coefficients are identifiable
+  avoid        NOTEARS / DAGMA (continuous optimization): variance ordering will drive the result
+```
+
+## Limitations
+
+- Some assumptions cannot be tested from observational data: faithfulness (no canceling effects) and the absence of selection bias. The report says so rather than pretending.
+- The noise check uses each variable's residual given all others as a stand-in for its true disturbance, because the graph is unknown.
+- The hidden-confounder check is a signal, not a proof. Passing it does not rule out confounding.
+- Thresholds (linearity gain 0.02, R² 0.98 for near-determinism, variance ratio 10) are sensible defaults, not laws. All are arguments to the check functions.
+
+## Development
+
+```bash
+git clone https://github.com/Tahahaha7/causalcheck && cd causalcheck
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

causalcheck-0.1.0/src/causalcheck.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+LICENSE
+README.md
+pyproject.toml
+src/causalcheck/__init__.py
+src/causalcheck/checks.py
+src/causalcheck/cli.py
+src/causalcheck/recommend.py
+src/causalcheck/report.py
+src/causalcheck.egg-info/PKG-INFO
+src/causalcheck.egg-info/SOURCES.txt
+src/causalcheck.egg-info/dependency_links.txt
+src/causalcheck.egg-info/entry_points.txt
+src/causalcheck.egg-info/requires.txt
+src/causalcheck.egg-info/top_level.txt
+tests/test_checks.py

causalcheck-0.1.0/src/causalcheck.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

causalcheck-0.1.0/src/causalcheck.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+causalcheck = causalcheck.cli:main

causalcheck-0.1.0/src/causalcheck.egg-info/requires.txt

@@ -0,0 +1,12 @@
+numpy>=1.23
+pandas>=1.5
+scipy>=1.9
+scikit-learn>=1.2
+
+[dev]
+pytest>=7
+build
+twine
+
+[full]
+causal-learn>=0.1.3

causalcheck-0.1.0/src/causalcheck.egg-info/top_level.txt

@@ -0,0 +1 @@
+causalcheck

causalcheck-0.1.0/tests/test_checks.py

@@ -0,0 +1,160 @@
+"""Known-answer tests: synthetic data whose assumption profile we know in advance."""
+import json
+
+import numpy as np
+import pandas as pd
+import pytest
+
+import causalcheck
+from causalcheck.cli import main
+
+N = 1000
+
+
+@pytest.fixture
+def rng():
+    return np.random.default_rng(0)
+
+
+def status(report, name):
+    return {c.name: c.status for c in report.checks}[name]
+
+
+def verdict(report, prefix):
+    return next(m.verdict for m in report.advice.methods if m.method.startswith(prefix))
+
+
+# ----------------------------------------------------------------- datasets
+
+def linear_gaussian(rng):
+    a = rng.normal(size=N)
+    b = 0.8 * a + rng.normal(size=N)
+    c = 0.5 * a + 0.5 * b + rng.normal(size=N)
+    return pd.DataFrame(dict(a=a, b=b, c=c))
+
+
+def linear_nongaussian(rng):
+    a = rng.uniform(-1, 1, N)
+    b = 0.8 * a + 0.5 * rng.uniform(-1, 1, N)
+    c = 0.6 * a - 0.6 * b + 0.5 * rng.uniform(-1, 1, N)
+    return pd.DataFrame(dict(a=a, b=b, c=c))
+
+
+def nonlinear(rng):
+    g = rng.normal(size=N)
+    h = np.tanh(2 * g) + 0.3 * rng.normal(size=N)
+    k = np.sin(h) + 0.3 * rng.normal(size=N)
+    return pd.DataFrame(dict(g=g, h=h, k=k))
+
+
+def near_deterministic(rng):
+    x3 = rng.uniform(size=N)
+    x0 = 3 * x3 + rng.uniform(size=N)
+    x2 = 6 * x3 + rng.uniform(size=N)
+    x4 = 8 * x0 - x2 + rng.uniform(size=N)
+    return pd.DataFrame(dict(x0=x0, x2=x2, x3=x3, x4=x4))
+
+
+# -------------------------------------------------------------------- tests
+
+def test_linear_gaussian_refuses_direction_methods(rng):
+    r = causalcheck.check(linear_gaussian(rng))
+    assert status(r, "linearity") == "pass"
+    assert status(r, "noise distribution") == "warn"
+    assert verdict(r, "DirectLiNGAM") == "avoid"
+    assert verdict(r, "NOTEARS") == "avoid"
+    assert any("equivalence class" in t for t in r.advice.trust)
+
+
+def test_linear_nongaussian_recommends_lingam(rng):
+    r = causalcheck.check(linear_nongaussian(rng))
+    assert status(r, "linearity") == "pass"
+    assert status(r, "noise distribution") == "pass"
+    assert verdict(r, "DirectLiNGAM") == "recommended"
+    assert verdict(r, "GES / BOSS") == "recommended"
+
+
+def test_nonlinear_routes_to_anm(rng):
+    r = causalcheck.check(nonlinear(rng))
+    assert status(r, "linearity") == "info"
+    assert verdict(r, "DirectLiNGAM") == "avoid"
+    assert verdict(r, "ANM") == "recommended"
+    pairs = {c.name: c for c in r.checks}["linearity"].details["nonlinear_pairs"]
+    assert any({p[0], p[1]} == {"g", "h"} for p in pairs)
+
+
+def test_near_determinism_flags_faithfulness_risk(rng):
+    r = causalcheck.check(near_deterministic(rng))
+    assert status(r, "near-determinism") == "warn"
+    assert verdict(r, "PC") == "avoid"
+    assert verdict(r, "GES / BOSS") == "recommended"
+
+
+def test_duplicate_column_fails(rng):
+    df = linear_gaussian(rng)
+    df["a_inches"] = df["a"] * 2.54
+    r = causalcheck.check(df)
+    assert status(r, "near-determinism") == "fail"
+    assert r.worst_status == "fail"
+    assert any("duplicate" in f.lower() for f in r.advice.fix_first)
+
+
+def test_discrete_missing_and_text_columns(rng):
+    df = linear_gaussian(rng)
+    df["level"] = rng.integers(0, 3, N)
+    df["label"] = np.where(df["level"] == 0, "x", "y")
+    df.loc[:49, "b"] = np.nan
+    r = causalcheck.check(df)
+    assert status(r, "data types") == "warn"
+    assert r.discrete == ["level"]
+    assert r.n_rows == N - 50
+    assert "label" not in r.variables
+    assert verdict(r, "ANM") == "avoid"
+
+
+def test_small_sample_warns(rng):
+    r = causalcheck.check(linear_gaussian(rng).head(80))
+    assert status(r, "sample size") == "warn"
+    assert any("bootstrap" in t.lower() for t in r.advice.trust)
+
+
+def test_scale_warns_and_asks_to_standardize(rng):
+    df = linear_gaussian(rng)
+    df["c"] *= 100
+    r = causalcheck.check(df)
+    assert status(r, "scale") == "warn"
+    assert any("standardize" in f.lower() for f in r.advice.fix_first)
+
+
+def test_report_text_and_json(rng):
+    r = causalcheck.check(linear_gaussian(rng))
+    text = str(r)
+    assert "CHECKS" in text and "METHODS" in text and "HOW TO READ" in text
+    d = json.loads(r.to_json())
+    assert d["worst_status"] == r.worst_status
+    assert len(d["checks"]) == len(r.checks)
+    assert d["causalcheck"] == causalcheck.__version__
+
+
+def test_confounding_check_skips_without_causal_learn(rng):
+    pytest.importorskip("numpy")
+    try:
+        import causallearn  # noqa: F401
+        pytest.skip("causal-learn installed; skip-path not exercised")
+    except ImportError:
+        pass
+    r = causalcheck.check(linear_gaussian(rng), confounding=True)
+    assert status(r, "hidden confounding") == "info"
+
+
+def test_cli_exit_codes(rng, tmp_path, capsys):
+    ok = tmp_path / "ok.csv"
+    linear_gaussian(rng).to_csv(ok, index=False)
+    assert main([str(ok)]) == 0
+    assert "CHECKS" in capsys.readouterr().out
+    bad = tmp_path / "bad.csv"
+    df = linear_gaussian(rng)
+    df["a2"] = df["a"]
+    df.to_csv(bad, index=False)
+    assert main([str(bad), "--json"]) == 1
+    assert json.loads(capsys.readouterr().out)["worst_status"] == "fail"