honest-eda 0.1.0__tar.gz

honest_eda-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 honest-eda contributors
+
+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.

honest_eda-0.1.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: honest-eda
+Version: 0.1.0
+Summary: EDA that admits when there's no signal — wraps nullbic ΔBIC falsification
+Author: honest-eda contributors
+License: MIT
+Project-URL: Homepage, https://github.com/glogwa68/honest-eda
+Project-URL: Issues, https://github.com/glogwa68/honest-eda/issues
+Project-URL: Related, https://github.com/glogwa68/nullbic
+Keywords: eda,exploratory-data-analysis,symbolic-regression,nullbic,falsification,data-leakage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nullbic
+Requires-Dist: pandas>=2.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: plotly>=5.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# honest-eda
+
+**EDA that admits when there's no signal.**
+
+[![PyPI](https://img.shields.io/pypi/v/honest-eda)](https://pypi.org/project/honest-eda/)
+[![Python](https://img.shields.io/pypi/pyversions/honest-eda)](https://pypi.org/project/honest-eda/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/glogwa68/honest-eda/actions/workflows/ci.yml/badge.svg)](https://github.com/glogwa68/honest-eda/actions)
+
+> ydata-profiling shows you 200 correlations. 195 are noise. honest-eda shows you the 5 that survive shuffling.
+
+---
+
+## The Problem
+
+pandas-profiling, ydata-profiling, and sweetviz report everything. Every correlation, every association, every distribution shift. The result: 200 "insights" in your report, of which 195 are pure chance — artifacts of finite sample size, collinearity, or subtle target leakage.
+
+You end up fitting models on noise, wasting compute on AutoML pipelines that have nothing real to learn, and shipping features that degrade on new data.
+
+## The Solution
+
+`honest-eda` runs a falsification test on every feature-target pair using [nullbic](https://github.com/glogwa68/nullbic) — a symbolic regression library with built-in self-falsification via ΔBIC.
+
+For each relation, the verdict is computed against three null hypotheses:
+
+- vs. constant model
+- vs. linear model
+- vs. target-shuffled distribution
+
+Only relations that survive all three appear in the report. Everything else is hidden.
+
+---
+
+## Install
+
+```bash
+pip install honest-eda
+```
+
+---
+
+## Usage
+
+### Python
+
+```python
+from honest_eda import profile, check
+
+# Generate HTML report — only real signals shown
+result = profile("data.csv", target="y", output="report.html")
+print(f"Real signal patterns: {len(result.strong)}")
+print(f"Fake correlations rejected: {result.noise_count}")
+print(f"Leakage suspects: {len(result.leakage_suspects)}")
+
+# CI mode — exit 1 if no real signal
+if not check("data.csv", target="y", min_strong=1):
+    raise ValueError("No real signal in this dataset!")
+```
+
+### CLI
+
+```bash
+honest-eda profile data.csv --target=y --output=report.html
+honest-eda check data.csv --target=y --min-strong=2   # exit 1 if fails
+```
+
+---
+
+## What You Get
+
+```
+HONEST EDA REPORT
+─────────────────
+Columns scanned: 47
+Relations tested: 1081
+
+REAL signal (STRONG): 6
+  • age × tenure → churn
+  • monthly_charges → churn
+
+WEAK signal: 12
+NOISE rejected: 1063 (hidden)
+
+Linear-baseline-only features: 23
+Leakage suspects: 2  ⚠
+```
+
+No noise, no false confidence. Only findings that hold up under falsification.
+
+---
+
+## Killer Features
+
+**Leakage detector** — When a feature's z-score vs. shuffled target drops below −15, honest-eda flags it as a probable data leak. Catches target-encoded columns, future-information leaks, and accidental label copies before they corrupt your model evaluation.
+
+**Linear vs. symbolic dichotomy** — honest-eda tells you explicitly when a linear model would suffice. If symbolic regression finds no improvement over OLS, the feature is labeled "linear-baseline-only". No need to run a neural net to discover this.
+
+**CI mode** — `honest-eda check` exits with code 1 if the minimum number of strong signals is not met. Drop it in your CI pipeline to block training runs on datasets with no real predictive content.
+
+**Pre-modeling triage** — Know whether there is exploitable signal before you launch XGBoost or AutoML. Saves hours of compute and avoids the "model trained fine but generalizes to nothing" postmortem.
+
+---
+
+## How It Works
+
+For each numeric feature paired with the target:
+
+1. `nullbic.discover` fits a symbolic expression and records the BIC improvement over the null model.
+2. The verdict is assigned:
+   - **STRONG** — beats constant + linear baseline + all shuffled-target permutations.
+   - **WEAK** — beats constant baseline only.
+   - **NOISE** — fails to beat the constant. Excluded from the report.
+3. Leakage is flagged when `z_vs_shuffled < −15`, indicating the feature carries near-perfect information about the target.
+
+The HTML report contains only STRONG and WEAK relations. NOISE is counted and disclosed in the summary, but not displayed.
+
+---
+
+## Comparison
+
+|                               | honest-eda | ydata-profiling | sweetviz |
+|-------------------------------|:----------:|:---------------:|:--------:|
+| Tests vs shuffled target      | ✅         | ❌              | ❌       |
+| Reports only real signal      | ✅         | ❌              | ❌       |
+| Symbolic formula extraction   | ✅         | ❌              | ❌       |
+| Leakage detection             | ✅         | ❌              | ❌       |
+| CI mode (exit code)           | ✅         | ❌              | ❌       |
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+## Citation / Related
+
+honest-eda is built on top of **nullbic**, a library for symbolic regression with automatic ΔBIC falsification:
+
+- Repository: https://github.com/glogwa68/nullbic
+
+If you use honest-eda in published work, please also cite nullbic.

honest_eda-0.1.0/README.md

@@ -0,0 +1,143 @@
+# honest-eda
+
+**EDA that admits when there's no signal.**
+
+[![PyPI](https://img.shields.io/pypi/v/honest-eda)](https://pypi.org/project/honest-eda/)
+[![Python](https://img.shields.io/pypi/pyversions/honest-eda)](https://pypi.org/project/honest-eda/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/glogwa68/honest-eda/actions/workflows/ci.yml/badge.svg)](https://github.com/glogwa68/honest-eda/actions)
+
+> ydata-profiling shows you 200 correlations. 195 are noise. honest-eda shows you the 5 that survive shuffling.
+
+---
+
+## The Problem
+
+pandas-profiling, ydata-profiling, and sweetviz report everything. Every correlation, every association, every distribution shift. The result: 200 "insights" in your report, of which 195 are pure chance — artifacts of finite sample size, collinearity, or subtle target leakage.
+
+You end up fitting models on noise, wasting compute on AutoML pipelines that have nothing real to learn, and shipping features that degrade on new data.
+
+## The Solution
+
+`honest-eda` runs a falsification test on every feature-target pair using [nullbic](https://github.com/glogwa68/nullbic) — a symbolic regression library with built-in self-falsification via ΔBIC.
+
+For each relation, the verdict is computed against three null hypotheses:
+
+- vs. constant model
+- vs. linear model
+- vs. target-shuffled distribution
+
+Only relations that survive all three appear in the report. Everything else is hidden.
+
+---
+
+## Install
+
+```bash
+pip install honest-eda
+```
+
+---
+
+## Usage
+
+### Python
+
+```python
+from honest_eda import profile, check
+
+# Generate HTML report — only real signals shown
+result = profile("data.csv", target="y", output="report.html")
+print(f"Real signal patterns: {len(result.strong)}")
+print(f"Fake correlations rejected: {result.noise_count}")
+print(f"Leakage suspects: {len(result.leakage_suspects)}")
+
+# CI mode — exit 1 if no real signal
+if not check("data.csv", target="y", min_strong=1):
+    raise ValueError("No real signal in this dataset!")
+```
+
+### CLI
+
+```bash
+honest-eda profile data.csv --target=y --output=report.html
+honest-eda check data.csv --target=y --min-strong=2   # exit 1 if fails
+```
+
+---
+
+## What You Get
+
+```
+HONEST EDA REPORT
+─────────────────
+Columns scanned: 47
+Relations tested: 1081
+
+REAL signal (STRONG): 6
+  • age × tenure → churn
+  • monthly_charges → churn
+
+WEAK signal: 12
+NOISE rejected: 1063 (hidden)
+
+Linear-baseline-only features: 23
+Leakage suspects: 2  ⚠
+```
+
+No noise, no false confidence. Only findings that hold up under falsification.
+
+---
+
+## Killer Features
+
+**Leakage detector** — When a feature's z-score vs. shuffled target drops below −15, honest-eda flags it as a probable data leak. Catches target-encoded columns, future-information leaks, and accidental label copies before they corrupt your model evaluation.
+
+**Linear vs. symbolic dichotomy** — honest-eda tells you explicitly when a linear model would suffice. If symbolic regression finds no improvement over OLS, the feature is labeled "linear-baseline-only". No need to run a neural net to discover this.
+
+**CI mode** — `honest-eda check` exits with code 1 if the minimum number of strong signals is not met. Drop it in your CI pipeline to block training runs on datasets with no real predictive content.
+
+**Pre-modeling triage** — Know whether there is exploitable signal before you launch XGBoost or AutoML. Saves hours of compute and avoids the "model trained fine but generalizes to nothing" postmortem.
+
+---
+
+## How It Works
+
+For each numeric feature paired with the target:
+
+1. `nullbic.discover` fits a symbolic expression and records the BIC improvement over the null model.
+2. The verdict is assigned:
+   - **STRONG** — beats constant + linear baseline + all shuffled-target permutations.
+   - **WEAK** — beats constant baseline only.
+   - **NOISE** — fails to beat the constant. Excluded from the report.
+3. Leakage is flagged when `z_vs_shuffled < −15`, indicating the feature carries near-perfect information about the target.
+
+The HTML report contains only STRONG and WEAK relations. NOISE is counted and disclosed in the summary, but not displayed.
+
+---
+
+## Comparison
+
+|                               | honest-eda | ydata-profiling | sweetviz |
+|-------------------------------|:----------:|:---------------:|:--------:|
+| Tests vs shuffled target      | ✅         | ❌              | ❌       |
+| Reports only real signal      | ✅         | ❌              | ❌       |
+| Symbolic formula extraction   | ✅         | ❌              | ❌       |
+| Leakage detection             | ✅         | ❌              | ❌       |
+| CI mode (exit code)           | ✅         | ❌              | ❌       |
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+## Citation / Related
+
+honest-eda is built on top of **nullbic**, a library for symbolic regression with automatic ΔBIC falsification:
+
+- Repository: https://github.com/glogwa68/nullbic
+
+If you use honest-eda in published work, please also cite nullbic.

honest_eda-0.1.0/honest_eda/__init__.py

@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from honest_eda.profile import check, profile
+from honest_eda.runner import ProfileResult, RelationResult
+
+__version__ = "0.1.0"
+
+__all__ = ["profile", "check", "ProfileResult", "RelationResult", "__version__"]

honest_eda-0.1.0/honest_eda/cli.py

@@ -0,0 +1,60 @@
+from __future__ import annotations
+
+import sys
+
+import typer
+
+from honest_eda.profile import check as _check
+from honest_eda.profile import profile as _profile
+from honest_eda.report import render_text_summary
+
+app = typer.Typer(no_args_is_help=True, help="EDA that admits when there's no signal.")
+
+
+@app.command("profile")
+def profile_cmd(
+    data: str = typer.Argument(..., help="CSV path"),
+    target: str = typer.Option(..., "--target", "-t", help="Target column name"),
+    output: str = typer.Option("report.html", "--output", "-o", help="HTML output path"),
+    gens: int = typer.Option(40, "--gens", help="nullbic n_generations"),
+    pop: int = typer.Option(200, "--pop", help="nullbic pop_size"),
+    depth: int = typer.Option(4, "--depth", help="nullbic max_depth"),
+    seed: int = typer.Option(0, "--seed", help="Random seed"),
+    show_noise: bool = typer.Option(False, "--show-noise", help="Include noise in HTML"),
+    quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress stdout"),
+) -> None:
+    "Run EDA profile and write HTML report."
+    result = _profile(
+        data,
+        target,
+        output,
+        n_generations=gens,
+        pop_size=pop,
+        max_depth=depth,
+        seed=seed,
+        hide_noise=not show_noise,
+    )
+    if not quiet:
+        typer.echo(render_text_summary(result))
+        typer.echo(f"Report written to: {output}")
+
+
+@app.command("check")
+def check_cmd(
+    data: str = typer.Argument(..., help="CSV path"),
+    target: str = typer.Option(..., "--target", "-t", help="Target column name"),
+    min_strong: int = typer.Option(1, "--min-strong", help="Minimum STRONG relations required"),
+    gens: int = typer.Option(40, "--gens"),
+    pop: int = typer.Option(200, "--pop"),
+    depth: int = typer.Option(4, "--depth"),
+    seed: int = typer.Option(0, "--seed"),
+    quiet: bool = typer.Option(False, "--quiet", "-q"),
+) -> None:
+    "Exit 0 if enough STRONG signals found, exit 1 otherwise."
+    ok = _check(data, target, min_strong=min_strong, n_generations=gens, pop_size=pop, max_depth=depth, seed=seed)
+    if not quiet:
+        if ok:
+            typer.echo(f"PASS: found >= {min_strong} STRONG relation(s) for '{target}'.")
+        else:
+            typer.echo(f"FAIL: fewer than {min_strong} STRONG relation(s) for '{target}'.", err=True)
+    sys.exit(0 if ok else 1)

honest_eda-0.1.0/honest_eda/leakage.py

@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+from honest_eda.runner import RelationResult
+
+LEAKAGE_Z_THRESHOLD = -15.0
+
+
+def is_leakage_suspect(rel: RelationResult) -> bool:
+    return rel.z_vs_shuffled < LEAKAGE_Z_THRESHOLD
+
+
+def flag_leakage(results: list[RelationResult]) -> list[RelationResult]:
+    return [r for r in results if is_leakage_suspect(r)]
+
+
+def explain_leakage(rel: RelationResult) -> str:
+    features = ", ".join(rel.features)
+    return (
+        f"Leakage suspect: feature(s) [{features}] achieve z={rel.z_vs_shuffled:.2f} "
+        f"vs shuffled baseline (threshold: {LEAKAGE_Z_THRESHOLD}). "
+        f"Verify [{features}] is not derived from '{rel.target}'."
+    )

honest_eda-0.1.0/honest_eda/profile.py

@@ -0,0 +1,46 @@
+from __future__ import annotations
+
+import pandas as pd
+
+from honest_eda import report as _report_mod
+from honest_eda.runner import ProfileResult, run_against_target
+
+
+def profile(
+    data: str | pd.DataFrame,
+    target: str,
+    output: str = "report.html",
+    *,
+    n_generations: int = 40,
+    pop_size: int = 200,
+    max_depth: int = 4,
+    seed: int = 0,
+    hide_noise: bool = True,
+) -> ProfileResult:
+    "Run nullbic-backed EDA and render an HTML report."
+    if isinstance(data, str):
+        data = pd.read_csv(data)
+    result = run_against_target(
+        data,
+        target,
+        n_generations=n_generations,
+        pop_size=pop_size,
+        max_depth=max_depth,
+        seed=seed,
+    )
+    _report_mod.render_html(result, output, hide_noise=hide_noise)
+    return result
+
+
+def check(
+    data: str | pd.DataFrame,
+    target: str,
+    *,
+    min_strong: int = 1,
+    **kwargs,
+) -> bool:
+    "CI gate: True if the profile finds at least min_strong STRONG relations."
+    if isinstance(data, str):
+        data = pd.read_csv(data)
+    result = run_against_target(data, target, **kwargs)
+    return len(result.strong) >= min_strong

honest_eda-0.1.0/honest_eda/report/__init__.py

@@ -0,0 +1,5 @@
+from __future__ import annotations
+
+from .report import render_html, render_text_summary
+
+__all__ = ["render_html", "render_text_summary"]

honest_eda-0.1.0/honest_eda/report/report.py

@@ -0,0 +1,146 @@
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+
+from jinja2 import Environment, BaseLoader
+
+from honest_eda.leakage import LEAKAGE_Z_THRESHOLD
+from honest_eda.runner import ProfileResult
+
+_TEMPLATE = """\
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<title>honest-eda — {{ result.target }}</title>
+<style>
+body{font-family:system-ui,sans-serif;margin:2rem;background:#fafafa;color:#111}
+h1,h2{color:#1a1a2e}
+table{border-collapse:collapse;width:100%;margin-bottom:1.5rem}
+th,td{border:1px solid #ccc;padding:.4rem .8rem;text-align:left;font-size:.9em}
+th{background:#1a1a2e;color:#fff}
+tr.strong{background:#d4edda}tr.weak{background:#fff3cd}
+.badge{border-radius:4px;padding:2px 6px;font-size:.8em;font-weight:700}
+.b-STRONG{background:#198754;color:#fff}.b-WEAK{background:#ffc107;color:#000}
+.b-NOISE{background:#dc3545;color:#fff}
+.warn{color:#856404;background:#fff3cd;border:1px solid #ffc107;padding:.5rem;border-radius:4px}
+</style>
+</head>
+<body>
+<h1>honest-eda &mdash; target: <code>{{ result.target }}</code></h1>
+<p>
+  Generated: {{ generated_at }} &nbsp;|&nbsp;
+  Columns: {{ result.n_columns }} &nbsp;|&nbsp;
+  Relations tested: {{ result.n_relations }} &nbsp;|&nbsp;
+  <strong>Strong: {{ result.strong | length }}</strong> &nbsp;|&nbsp;
+  Weak: {{ result.weak | length }} &nbsp;|&nbsp;
+  Noise: {{ result.noise_count }}
+</p>
+
+{% if result.leakage_suspects %}
+<div class="warn">
+  <strong>Leakage suspects</strong> (z &lt; {{ leakage_threshold }}):<br>
+  {% for r in result.leakage_suspects %}
+    &bull; {{ r.features | join(", ") }} &mdash; z={{ "%.2f" | format(r.z_vs_shuffled) }}<br>
+  {% endfor %}
+</div>
+{% endif %}
+
+{% if result.linear_only %}
+<h2>Linear-only features</h2>
+<p>{{ result.linear_only | join(", ") }}</p>
+{% endif %}
+
+<h2>Strong relations</h2>
+{% if result.strong %}
+<table>
+<tr><th>Features</th><th>Formula</th><th>Verdict</th><th>&#916;BIC const</th><th>&#916;BIC linear</th><th>z vs shuffled</th></tr>
+{% for r in result.strong %}
+<tr class="strong">
+  <td>{{ r.features | join(", ") }}</td>
+  <td><code>{{ r.formula }}</code></td>
+  <td><span class="badge b-{{ r.verdict }}">{{ r.verdict }}</span></td>
+  <td>{{ "%.3f" | format(r.delta_bic_const) }}</td>
+  <td>{{ "%.3f" | format(r.delta_bic_linear) }}</td>
+  <td>{{ "%.3f" | format(r.z_vs_shuffled) }}</td>
+</tr>
+{% endfor %}
+</table>
+{% else %}<p><em>None found.</em></p>{% endif %}
+
+<h2>Weak relations</h2>
+{% if result.weak %}
+<table>
+<tr><th>Features</th><th>Formula</th><th>Verdict</th><th>&#916;BIC const</th><th>&#916;BIC linear</th><th>z vs shuffled</th></tr>
+{% for r in result.weak %}
+<tr class="weak">
+  <td>{{ r.features | join(", ") }}</td>
+  <td><code>{{ r.formula }}</code></td>
+  <td><span class="badge b-{{ r.verdict }}">{{ r.verdict }}</span></td>
+  <td>{{ "%.3f" | format(r.delta_bic_const) }}</td>
+  <td>{{ "%.3f" | format(r.delta_bic_linear) }}</td>
+  <td>{{ "%.3f" | format(r.z_vs_shuffled) }}</td>
+</tr>
+{% endfor %}
+</table>
+{% else %}<p><em>None found.</em></p>{% endif %}
+
+{% if not hide_noise %}
+<h2>Noise ({{ result.noise_count }} relation(s) rejected)</h2>
+{% endif %}
+
+</body>
+</html>
+"""
+
+
+def render_html(
+    result: ProfileResult,
+    output_path: str | Path,
+    *,
+    hide_noise: bool = True,
+) -> Path:
+    "Render ProfileResult as a self-contained HTML file."
+    output_path = Path(output_path).resolve()
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    env = Environment(loader=BaseLoader(), autoescape=False)
+    tmpl = env.from_string(_TEMPLATE)
+    generated_at = datetime.now(timezone.utc).isoformat(timespec="seconds")
+    html = tmpl.render(
+        result=result,
+        hide_noise=hide_noise,
+        generated_at=generated_at,
+        leakage_threshold=LEAKAGE_Z_THRESHOLD,
+    )
+    output_path.write_text(html, encoding="utf-8")
+    return output_path
+
+
+def render_text_summary(result: ProfileResult) -> str:
+    "Return a plain-text summary of a ProfileResult."
+    lines: list[str] = [
+        "HONEST EDA REPORT",
+        "─" * 17,
+        f"Target: {result.target}",
+        f"Columns scanned: {result.n_columns}",
+        f"Relations tested: {result.n_relations}",
+        "",
+        f"REAL signal (STRONG): {len(result.strong)}",
+    ]
+    for r in result.strong:
+        lines.append(f"  * {', '.join(r.features)} -> {result.target}  formula: {r.formula}")
+    lines += ["", f"WEAK signal: {len(result.weak)}"]
+    for r in result.weak:
+        lines.append(f"  * {', '.join(r.features)} -> {result.target}  formula: {r.formula}")
+    lines += [
+        "",
+        f"NOISE rejected: {result.noise_count}",
+        "",
+        f"Linear-only features: {', '.join(result.linear_only) or 'none'}",
+        "",
+        f"Leakage suspects: {len(result.leakage_suspects)}",
+    ]
+    for r in result.leakage_suspects:
+        lines.append(f"  ! {', '.join(r.features)}  z={r.z_vs_shuffled:.2f}")
+    return "\n".join(lines)

honest_eda-0.1.0/honest_eda/runner.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+import logging
+import random
+from dataclasses import dataclass, field
+
+import pandas as pd
+from nullbic import Dataset, discover
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class RelationResult:
+    target: str
+    features: list[str]
+    formula: str
+    verdict: str
+    delta_bic_const: float
+    delta_bic_linear: float
+    z_vs_shuffled: float
+
+
+@dataclass
+class ProfileResult:
+    n_columns: int
+    n_relations: int
+    target: str
+    strong: list[RelationResult]
+    weak: list[RelationResult]
+    noise_count: int
+    linear_only: list[str]
+    leakage_suspects: list[RelationResult]
+
+
+def _select_numeric(df: pd.DataFrame) -> list[str]:
+    return df.select_dtypes(include="number").columns.tolist()
+
+
+def _verdict_str(report) -> str:
+    try:
+        return report.verdict.name
+    except AttributeError:
+        if not report.is_real_signal():
+            return "NOISE"
+        # distinguish STRONG vs WEAK via delta_bic_linear threshold
+        return "STRONG" if report.delta_bic_linear < -10 else "WEAK"
+
+
+def _run_one(
+    df: pd.DataFrame,
+    features: list[str],
+    target: str,
+    n_generations: int,
+    pop_size: int,
+    max_depth: int,
+    seed: int,
+) -> RelationResult | None:
+    random.seed(seed)
+    try:
+        ds = Dataset.from_pandas(df[features + [target]], target=target)
+        rep = discover(ds, n_generations=n_generations, pop_size=pop_size, max_depth=max_depth)
+        return RelationResult(
+            target=target,
+            features=features,
+            formula=rep.formula,
+            verdict=_verdict_str(rep),
+            delta_bic_const=float(rep.delta_bic_const),
+            delta_bic_linear=float(rep.delta_bic_linear),
+            z_vs_shuffled=float(rep.z_vs_shuffled),
+        )
+    except Exception as exc:
+        logger.warning("nullbic failed for features=%s target=%s: %s", features, target, exc)
+        return None
+
+
+def run_against_target(
+    df: pd.DataFrame,
+    target: str,
+    *,
+    n_generations: int = 40,
+    pop_size: int = 200,
+    max_depth: int = 4,
+    max_features_per_run: int | None = None,
+    seed: int = 0,
+) -> ProfileResult:
+    numeric_cols = [c for c in _select_numeric(df) if c != target]
+
+    if max_features_per_run is not None:
+        numeric_cols = numeric_cols[:max_features_per_run]
+
+    results: list[RelationResult] = []
+
+    for col in numeric_cols:
+        res = _run_one(df, [col], target, n_generations, pop_size, max_depth, seed)
+        if res is not None:
+            results.append(res)
+
+    if len(numeric_cols) > 1:
+        all_res = _run_one(df, numeric_cols, target, n_generations, pop_size, max_depth, seed)
+        if all_res is not None:
+            results.append(all_res)
+
+    strong = [r for r in results if r.verdict == "STRONG"]
+    weak = [r for r in results if r.verdict == "WEAK"]
+    noise_count = sum(1 for r in results if r.verdict == "NOISE")
+
+    leakage_suspects = [r for r in results if r.z_vs_shuffled < -15]
+
+    linear_only: list[str] = []
+    for r in results:
+        if len(r.features) == 1 and abs(r.delta_bic_linear) < 5 and r.delta_bic_const < -10:
+            linear_only.append(r.features[0])
+
+    return ProfileResult(
+        n_columns=len(df.columns),
+        n_relations=len(results),
+        target=target,
+        strong=strong,
+        weak=weak,
+        noise_count=noise_count,
+        linear_only=linear_only,
+        leakage_suspects=leakage_suspects,
+    )

honest_eda-0.1.0/honest_eda.egg-info/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.4
+Name: honest-eda
+Version: 0.1.0
+Summary: EDA that admits when there's no signal — wraps nullbic ΔBIC falsification
+Author: honest-eda contributors
+License: MIT
+Project-URL: Homepage, https://github.com/glogwa68/honest-eda
+Project-URL: Issues, https://github.com/glogwa68/honest-eda/issues
+Project-URL: Related, https://github.com/glogwa68/nullbic
+Keywords: eda,exploratory-data-analysis,symbolic-regression,nullbic,falsification,data-leakage
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: nullbic
+Requires-Dist: pandas>=2.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: plotly>=5.0
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Dynamic: license-file
+
+# honest-eda
+
+**EDA that admits when there's no signal.**
+
+[![PyPI](https://img.shields.io/pypi/v/honest-eda)](https://pypi.org/project/honest-eda/)
+[![Python](https://img.shields.io/pypi/pyversions/honest-eda)](https://pypi.org/project/honest-eda/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![CI](https://github.com/glogwa68/honest-eda/actions/workflows/ci.yml/badge.svg)](https://github.com/glogwa68/honest-eda/actions)
+
+> ydata-profiling shows you 200 correlations. 195 are noise. honest-eda shows you the 5 that survive shuffling.
+
+---
+
+## The Problem
+
+pandas-profiling, ydata-profiling, and sweetviz report everything. Every correlation, every association, every distribution shift. The result: 200 "insights" in your report, of which 195 are pure chance — artifacts of finite sample size, collinearity, or subtle target leakage.
+
+You end up fitting models on noise, wasting compute on AutoML pipelines that have nothing real to learn, and shipping features that degrade on new data.
+
+## The Solution
+
+`honest-eda` runs a falsification test on every feature-target pair using [nullbic](https://github.com/glogwa68/nullbic) — a symbolic regression library with built-in self-falsification via ΔBIC.
+
+For each relation, the verdict is computed against three null hypotheses:
+
+- vs. constant model
+- vs. linear model
+- vs. target-shuffled distribution
+
+Only relations that survive all three appear in the report. Everything else is hidden.
+
+---
+
+## Install
+
+```bash
+pip install honest-eda
+```
+
+---
+
+## Usage
+
+### Python
+
+```python
+from honest_eda import profile, check
+
+# Generate HTML report — only real signals shown
+result = profile("data.csv", target="y", output="report.html")
+print(f"Real signal patterns: {len(result.strong)}")
+print(f"Fake correlations rejected: {result.noise_count}")
+print(f"Leakage suspects: {len(result.leakage_suspects)}")
+
+# CI mode — exit 1 if no real signal
+if not check("data.csv", target="y", min_strong=1):
+    raise ValueError("No real signal in this dataset!")
+```
+
+### CLI
+
+```bash
+honest-eda profile data.csv --target=y --output=report.html
+honest-eda check data.csv --target=y --min-strong=2   # exit 1 if fails
+```
+
+---
+
+## What You Get
+
+```
+HONEST EDA REPORT
+─────────────────
+Columns scanned: 47
+Relations tested: 1081
+
+REAL signal (STRONG): 6
+  • age × tenure → churn
+  • monthly_charges → churn
+
+WEAK signal: 12
+NOISE rejected: 1063 (hidden)
+
+Linear-baseline-only features: 23
+Leakage suspects: 2  ⚠
+```
+
+No noise, no false confidence. Only findings that hold up under falsification.
+
+---
+
+## Killer Features
+
+**Leakage detector** — When a feature's z-score vs. shuffled target drops below −15, honest-eda flags it as a probable data leak. Catches target-encoded columns, future-information leaks, and accidental label copies before they corrupt your model evaluation.
+
+**Linear vs. symbolic dichotomy** — honest-eda tells you explicitly when a linear model would suffice. If symbolic regression finds no improvement over OLS, the feature is labeled "linear-baseline-only". No need to run a neural net to discover this.
+
+**CI mode** — `honest-eda check` exits with code 1 if the minimum number of strong signals is not met. Drop it in your CI pipeline to block training runs on datasets with no real predictive content.
+
+**Pre-modeling triage** — Know whether there is exploitable signal before you launch XGBoost or AutoML. Saves hours of compute and avoids the "model trained fine but generalizes to nothing" postmortem.
+
+---
+
+## How It Works
+
+For each numeric feature paired with the target:
+
+1. `nullbic.discover` fits a symbolic expression and records the BIC improvement over the null model.
+2. The verdict is assigned:
+   - **STRONG** — beats constant + linear baseline + all shuffled-target permutations.
+   - **WEAK** — beats constant baseline only.
+   - **NOISE** — fails to beat the constant. Excluded from the report.
+3. Leakage is flagged when `z_vs_shuffled < −15`, indicating the feature carries near-perfect information about the target.
+
+The HTML report contains only STRONG and WEAK relations. NOISE is counted and disclosed in the summary, but not displayed.
+
+---
+
+## Comparison
+
+|                               | honest-eda | ydata-profiling | sweetviz |
+|-------------------------------|:----------:|:---------------:|:--------:|
+| Tests vs shuffled target      | ✅         | ❌              | ❌       |
+| Reports only real signal      | ✅         | ❌              | ❌       |
+| Symbolic formula extraction   | ✅         | ❌              | ❌       |
+| Leakage detection             | ✅         | ❌              | ❌       |
+| CI mode (exit code)           | ✅         | ❌              | ❌       |
+
+---
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+---
+
+## Citation / Related
+
+honest-eda is built on top of **nullbic**, a library for symbolic regression with automatic ΔBIC falsification:
+
+- Repository: https://github.com/glogwa68/nullbic
+
+If you use honest-eda in published work, please also cite nullbic.

honest_eda-0.1.0/honest_eda.egg-info/SOURCES.txt

@@ -0,0 +1,21 @@
+LICENSE
+README.md
+pyproject.toml
+honest_eda/__init__.py
+honest_eda/cli.py
+honest_eda/leakage.py
+honest_eda/profile.py
+honest_eda/runner.py
+honest_eda.egg-info/PKG-INFO
+honest_eda.egg-info/SOURCES.txt
+honest_eda.egg-info/dependency_links.txt
+honest_eda.egg-info/entry_points.txt
+honest_eda.egg-info/requires.txt
+honest_eda.egg-info/top_level.txt
+honest_eda/report/__init__.py
+honest_eda/report/report.py
+tests/test_cli.py
+tests/test_leakage.py
+tests/test_profile.py
+tests/test_report.py
+tests/test_runner.py

honest_eda-0.1.0/honest_eda.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

honest_eda-0.1.0/honest_eda.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+honest-eda = honest_eda.cli:app

honest_eda-0.1.0/honest_eda.egg-info/requires.txt

@@ -0,0 +1,9 @@
+nullbic
+pandas>=2.0
+jinja2>=3.0
+plotly>=5.0
+typer>=0.12
+
+[dev]
+pytest>=7.0
+pytest-cov

honest_eda-0.1.0/honest_eda.egg-info/top_level.txt

@@ -0,0 +1 @@
+honest_eda

honest_eda-0.1.0/pyproject.toml

@@ -0,0 +1,49 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "honest-eda"
+version = "0.1.0"
+description = "EDA that admits when there's no signal — wraps nullbic ΔBIC falsification"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "honest-eda contributors" }]
+keywords = ["eda", "exploratory-data-analysis", "symbolic-regression", "nullbic", "falsification", "data-leakage"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+]
+dependencies = [
+    "nullbic",
+    "pandas>=2.0",
+    "jinja2>=3.0",
+    "plotly>=5.0",
+    "typer>=0.12",
+]
+
+[project.optional-dependencies]
+dev = ["pytest>=7.0", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://github.com/glogwa68/honest-eda"
+Issues = "https://github.com/glogwa68/honest-eda/issues"
+Related = "https://github.com/glogwa68/nullbic"
+
+[project.scripts]
+honest-eda = "honest_eda.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["honest_eda*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"

honest_eda-0.1.0/setup.cfg

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

honest_eda-0.1.0/tests/test_cli.py

@@ -0,0 +1,56 @@
+from __future__ import annotations
+
+import pytest
+from typer.testing import CliRunner
+
+from honest_eda.cli import app
+
+runner = CliRunner()
+
+
+def test_help():
+    result = runner.invoke(app, ["--help"])
+    assert result.exit_code == 0
+    assert "profile" in result.output or "check" in result.output
+
+
+def test_profile_command_exit_0(real_signal_df, tmp_path, mock_nullbic, monkeypatch):
+    csv_path = str(tmp_path / "data.csv")
+    real_signal_df.to_csv(csv_path, index=False)
+    out_path = str(tmp_path / "report.html")
+
+    monkeypatch.setattr(
+        "honest_eda.profile._report_mod.render_html",
+        lambda result, path, **kw: open(path, "w").write("<html/>"),
+    )
+
+    result = runner.invoke(
+        app,
+        ["profile", csv_path, "--target", "y", "--output", out_path, "--gens", "5"],
+    )
+    assert result.exit_code == 0
+    assert "Report written to:" in result.output
+
+
+def test_check_exit_0_with_signal(real_signal_df, tmp_path, mock_nullbic):
+    csv_path = str(tmp_path / "data.csv")
+    real_signal_df.to_csv(csv_path, index=False)
+
+    result = runner.invoke(
+        app,
+        ["check", csv_path, "--target", "y", "--gens", "5"],
+    )
+    assert result.exit_code == 0
+    assert "PASS" in result.output
+
+
+def test_check_exit_1_with_noise(noise_df, tmp_path, mock_nullbic):
+    csv_path = str(tmp_path / "data.csv")
+    noise_df.to_csv(csv_path, index=False)
+
+    result = runner.invoke(
+        app,
+        ["check", csv_path, "--target", "y", "--gens", "5"],
+    )
+    assert result.exit_code == 1
+    assert "FAIL" in result.output or "FAIL" in (result.stderr or "")

honest_eda-0.1.0/tests/test_leakage.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import pytest
+
+from honest_eda.leakage import (
+    LEAKAGE_Z_THRESHOLD,
+    explain_leakage,
+    flag_leakage,
+    is_leakage_suspect,
+)
+from honest_eda.runner import RelationResult
+
+
+def _make_rel(z: float, verdict: str = "STRONG") -> RelationResult:
+    return RelationResult(
+        target="y",
+        features=["x"],
+        formula="y ~ x",
+        verdict=verdict,
+        delta_bic_const=-10.0,
+        delta_bic_linear=-8.0,
+        z_vs_shuffled=z,
+    )
+
+
+def test_is_leakage_suspect_extreme_z():
+    assert is_leakage_suspect(_make_rel(-20.0)) is True
+
+
+def test_is_leakage_suspect_mild_z():
+    assert is_leakage_suspect(_make_rel(-5.0)) is False
+
+
+def test_flag_leakage_filters_correctly():
+    rels = [_make_rel(-20.0), _make_rel(-5.0), _make_rel(-1.0), _make_rel(-16.0)]
+    flagged = flag_leakage(rels)
+    assert len(flagged) == 2
+    assert all(r.z_vs_shuffled < LEAKAGE_Z_THRESHOLD for r in flagged)
+
+
+def test_explain_leakage_nonempty():
+    rel = _make_rel(-20.0)
+    explanation = explain_leakage(rel)
+    assert isinstance(explanation, str)
+    assert len(explanation) > 0
+    assert "x" in explanation
+    assert "y" in explanation

honest_eda-0.1.0/tests/test_profile.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import pandas as pd
+import pytest
+
+import honest_eda
+from honest_eda.runner import ProfileResult
+
+
+def test_profile_accepts_dataframe(real_signal_df, tmp_path, mock_nullbic, monkeypatch):
+    out = str(tmp_path / "report.html")
+    monkeypatch.setattr("honest_eda.report.render_html", lambda result, path, **kw: None)
+    monkeypatch.setattr("honest_eda.profile._report_mod.render_html", lambda result, path, **kw: None)
+    result = honest_eda.profile(real_signal_df, "y", out)
+    assert isinstance(result, ProfileResult)
+
+
+def test_profile_accepts_csv_path(real_signal_df, tmp_path, mock_nullbic, monkeypatch):
+    csv_path = str(tmp_path / "data.csv")
+    real_signal_df.to_csv(csv_path, index=False)
+    out = str(tmp_path / "report.html")
+    monkeypatch.setattr("honest_eda.profile._report_mod.render_html", lambda result, path, **kw: None)
+    result = honest_eda.profile(csv_path, "y", out)
+    assert isinstance(result, ProfileResult)
+
+
+def test_profile_writes_html(real_signal_df, tmp_path, mock_nullbic, monkeypatch):
+    out = str(tmp_path / "report.html")
+    written = {}
+
+    def fake_render(result, path, **kw):
+        written["path"] = path
+        with open(path, "w") as f:
+            f.write("<html>stub</html>")
+
+    monkeypatch.setattr("honest_eda.profile._report_mod.render_html", fake_render)
+    honest_eda.profile(real_signal_df, "y", out)
+    assert "path" in written
+    assert written["path"] == out
+    assert (tmp_path / "report.html").exists()
+
+
+def test_check_true_when_signal(real_signal_df, mock_nullbic):
+    result = honest_eda.check(real_signal_df, "y", min_strong=1)
+    assert result is True
+
+
+def test_check_false_when_noise(noise_df, mock_nullbic):
+    result = honest_eda.check(noise_df, "y", min_strong=1)
+    assert result is False

honest_eda-0.1.0/tests/test_report.py

@@ -0,0 +1,99 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from honest_eda.report import render_html, render_text_summary
+from honest_eda.runner import ProfileResult, RelationResult
+
+
+def _make_profile(target: str = "y", *, with_strong=True, with_leakage=False) -> ProfileResult:
+    strong_rel = RelationResult(
+        target=target,
+        features=["x"],
+        formula=f"{target} ~ x",
+        verdict="STRONG",
+        delta_bic_const=-15.0,
+        delta_bic_linear=-12.0,
+        z_vs_shuffled=-5.0,
+    )
+    leakage_rel = RelationResult(
+        target=target,
+        features=["leak"],
+        formula=f"{target} ~ leak",
+        verdict="STRONG",
+        delta_bic_const=-50.0,
+        delta_bic_linear=-30.0,
+        z_vs_shuffled=-20.0,
+    )
+    weak_rel = RelationResult(
+        target=target,
+        features=["w"],
+        formula=f"{target} ~ w",
+        verdict="WEAK",
+        delta_bic_const=-3.0,
+        delta_bic_linear=-2.0,
+        z_vs_shuffled=-2.5,
+    )
+
+    strong = [strong_rel] if with_strong else []
+    leakage = [leakage_rel] if with_leakage else []
+    all_rels = strong + leakage + [weak_rel]
+
+    return ProfileResult(
+        n_columns=4,
+        n_relations=len(all_rels),
+        target=target,
+        strong=strong + leakage,
+        weak=[weak_rel],
+        noise_count=1,
+        linear_only=[],
+        leakage_suspects=leakage,
+    )
+
+
+def test_render_html_creates_file(tmp_path):
+    result = _make_profile()
+    out = tmp_path / "report.html"
+    render_html(result, str(out))
+    assert out.exists()
+    assert out.stat().st_size > 0
+
+
+def test_render_html_contains_target_name(tmp_path):
+    result = _make_profile(target="price")
+    out = tmp_path / "report.html"
+    render_html(result, str(out))
+    content = out.read_text(encoding="utf-8")
+    assert "price" in content
+
+
+def test_render_html_strong_section_present(tmp_path):
+    result = _make_profile(with_strong=True)
+    out = tmp_path / "report.html"
+    render_html(result, str(out))
+    content = out.read_text(encoding="utf-8")
+    assert "STRONG" in content or "strong" in content.lower()
+
+
+def test_render_html_leakage_section_present(tmp_path):
+    result = _make_profile(with_leakage=True)
+    out = tmp_path / "report.html"
+    render_html(result, str(out))
+    content = out.read_text(encoding="utf-8")
+    assert "leak" in content.lower() or "-20" in content
+
+
+def test_render_text_summary_counters():
+    result = _make_profile(target="y", with_strong=True)
+    summary = render_text_summary(result)
+    assert "STRONG" in summary
+    assert "1" in summary
+    assert "y" in summary
+
+
+def test_render_text_summary_noise_count():
+    result = _make_profile()
+    summary = render_text_summary(result)
+    assert "NOISE" in summary or "noise" in summary.lower()

honest_eda-0.1.0/tests/test_runner.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+import pytest
+
+from honest_eda.runner import ProfileResult, RelationResult, run_against_target
+
+
+def test_real_signal_has_strong(real_signal_df, mock_nullbic):
+    result = run_against_target(real_signal_df, "y")
+    assert isinstance(result, ProfileResult)
+    assert len(result.strong) >= 1
+
+
+def test_noise_df_no_strong(noise_df, mock_nullbic):
+    result = run_against_target(noise_df, "y")
+    assert result.strong == []
+    assert result.noise_count > 0
+
+
+def test_leakage_df_suspects(leakage_df, mock_nullbic):
+    result = run_against_target(leakage_df, "y")
+    assert len(result.leakage_suspects) >= 1
+
+
+def test_nullbic_crash_skipped(real_signal_df, monkeypatch, mock_nullbic):
+    import honest_eda.runner as runner_mod
+
+    call_count = 0
+    original_run_one = runner_mod._run_one
+
+    def failing_run_one(df, features, target, *args, **kwargs):
+        nonlocal call_count
+        call_count += 1
+        if call_count == 1:
+            return None
+        return original_run_one(df, features, target, *args, **kwargs)
+
+    monkeypatch.setattr(runner_mod, "_run_one", failing_run_one)
+    result = run_against_target(real_signal_df, "y")
+    assert isinstance(result, ProfileResult)
+
+
+def test_n_columns_and_n_relations(real_signal_df, mock_nullbic):
+    result = run_against_target(real_signal_df, "y")
+    assert result.n_columns == len(real_signal_df.columns)
+    assert result.n_relations >= 0
+    total = len(result.strong) + len(result.weak) + result.noise_count
+    assert total == result.n_relations