Metadata-Version: 2.4
Name: feature-dash
Version: 0.1.2
Summary: Fast, interactive feature evaluation & web dashboard generator for predictive tabular models
Author: feature-dash contributors
License-Expression: MIT
Keywords: machine-learning,feature-engineering,data-science,eda,feature-selection,information-value
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pandas>=1.5.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: jinja2>=3.0.0
Requires-Dist: click>=8.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Dynamic: license-file

<p align="center">
  <strong>feature-dash ⚡</strong>
</p>

<p align="center">
  <em>High-performance feature evaluation &amp; interactive web dashboards for tabular ML workflows.</em>
</p>

## Why feature-dash?

![feature-dash Example Screenshot - Light](https://raw.githubusercontent.com/Marshalmathew/feature-dash/main/docs/assets/screenshot.png)

![feature-dash Example Screenshot - Dark](https://raw.githubusercontent.com/Marshalmathew/feature-dash/main/docs/assets/screenshot_dark.png)

> **Note**: Want to see it in action? View the [Sample Interactive Dashboard](https://Marshalmathew.github.io/feature-dash/examples/sample_report.html) (HTML) directly in your browser, or check out the [Sample WoE Rules](https://github.com/Marshalmathew/feature-dash/blob/main/examples/sample_rules.json) (JSON).

[![PyPI](https://img.shields.io/pypi/v/feature-dash?color=blue)](https://pypi.org/project/feature-dash/)
[![Python](https://img.shields.io/pypi/pyversions/feature-dash)](https://pypi.org/project/feature-dash/)
[![License](https://img.shields.io/github/license/Marshalmathew/feature-dash)](https://github.com/Marshalmathew/feature-dash/blob/main/LICENSE)

---

## Overview

**`feature-dash`** is a Python library and CLI tool for evaluating tabular features and generating **zero-dependency, interactive web dashboards** — all from a single function call.

Unlike generic EDA tools, `feature-dash` is built specifically for machine learning workflows. It supports both **unsupervised feature EDA** (distributions, percentiles, correlation heatmaps) and **supervised predictive intelligence** (Information Value, Weight of Evidence, Mutual Information, target leakage detection, and Scikit-Learn WoE transformers).

---

## ✨ Key Features

### Feature Analysis
- **Smart Adaptive Binning** — 4-tier strategy handling discrete, zero-inflated, skewed, and continuous distributions automatically.
- **Information Value (IV)** — Quantile-binned predictive power scoring across all features.
- **Mutual Information (MI)** — Non-linear dependency scoring for classification and regression targets.
- **Weight of Evidence (WoE)** — Per-bin WoE values with interactive Chart.js visualizations.
- **Target Leakage Detection** — Automatic flagging of suspected leakage features ($IV \ge 1.0$ or $|r| \ge 0.95$).

### PII Safeguards & Column Exclusion
- **Automatic PII Detection** — Detects and excludes raw PII columns (emails, phone numbers, names, SSNs, addresses, etc.) using broad pattern matching.
- **Explicit `exclude_cols`** — Pass explicit column exclusion lists for fine-grained control.
- **Interactive Badge & Modal** — Displays a `🛡️ Excluded Columns` badge with a detailed modal in the dashboard.

### Bivariate Analysis
- **Spearman Rank Correlation Matrix** — Hierarchically clustered heatmap (Ward distance), excluding nominal noise.
- **Redundant Pair Detection** ($|r| \ge 0.75$) — With recommended retention based on Information Value.
- **2D Quantile Interaction Heatmaps** — 5×5 risk grids supporting binary `pos_rate` and regression `target_mean`.

### Production Integration
- **WoE Scoring Export** — Save binning rules as JSON (`report.export_woe_rules("woe_rules.json")`).
- **Scikit-Learn Transformer** — `WoETransformer` converts DataFrames into WoE-encoded numeric matrices, compatible with pipelines and production inference.
- **DataFrame & CSV Export** — `report.to_dataframe()` and `report.to_csv("summary.csv")`.

### Dashboard & Deployment
- **Self-Contained HTML** — Single-file dashboards with embedded Chart.js visualizations.
- **Dual Theme** — 🌙 Dark Mode / ☀️ Light Mode toggle with dynamic re-rendering.
- **Print & PDF Export** — One-click export unwraps multi-tab UI into a clean linear layout.
- **Inline Jupyter Rendering** — `report.display_in_notebook()` for notebook workflows.
- **Single-File Standalone** — Zero-dependency `standalone_feature_dash.py` for air-gapped and restricted environments where `pip install` is not available.

---

## 📦 Installation

```bash
pip install feature-dash
```

---

## ⚡ Quickstart

### Supervised Feature Analysis

```python
import pandas as pd
from feature_dash import FeatureAnalyzer

df = pd.read_csv("dataset.csv")

analyzer = FeatureAnalyzer(
    df,
    target="SeriousDlqin2yrs",
    n_bins=10,
    exclude_cols=["customer_id", "phone_number"],
)
report = analyzer.fit()

# Generate interactive HTML dashboard
report.to_html(output_path="./reports")

# Export metrics
df_summary = report.to_dataframe()
report.to_csv("feature_summary.csv")
```

### Unsupervised Feature Analysis

```python
analyzer = FeatureAnalyzer(df, target=None, n_bins=15)
report = analyzer.fit()
report.to_html(output_path="./unsupervised_reports")
```

### Inline Jupyter Rendering

```python
report.display_in_notebook(height=850)
```

### WoE Scoring & Scikit-Learn Transformer

```python
# Export WoE binning rules
rules = report.export_woe_rules(filepath="woe_rules.json")

# Convert to scikit-learn transformer
woe_encoder = report.to_transformer()
X_test_woe = woe_encoder.transform(df_test)

# Production: reload from JSON (no FeatureAnalyzer needed)
from feature_dash import WoETransformer

prod_encoder = WoETransformer.from_json("woe_rules.json")
X_prod_woe = prod_encoder.transform(df_prod)
```

---

## 🔒 Air-Gapped & Restricted Environments

For environments where package installation is prohibited (air-gapped clusters, locked-down Jupyter servers, etc.), use the self-contained single-file script:

```python
from standalone_feature_dash import create_feature_dashboard

create_feature_dashboard(
    df,
    target="SeriousDlqin2yrs",
    output_path="feature_dash_report.html",
    display_notebook=True,
)
```

> **Note:** `standalone_feature_dash.py` bundles the full analysis engine, HTML template, and dashboard renderer into a single `.py` file with no external dependencies beyond `pandas` and `numpy`.

---

## 💻 CLI

```bash
# Check version
feature-dash --version

# Supervised analysis
feature-dash analyze dataset.csv --target SeriousDlqin2yrs --output-dir ./reports

# Unsupervised analysis
feature-dash analyze dataset.csv --output-dir ./unsupervised_reports
```

---

## ⚙️ Configuration

```python
analyzer = FeatureAnalyzer(
    df,
    target="target_column",
    n_bins=10,                      # Quantile bins for IV and distributions
    sample_size=100_000,            # Max rows for MI & correlation computation
    n_bivariate_features=6,         # Top features for 2D interaction grids
    max_corr_features=40,           # Max features in correlation matrix
    exclude_cols=["id", "phone"],   # Explicit column exclusions
    force_include=["zipcode_id"],   # Force-include columns that would be auto-dropped
    leakage_iv_threshold=1.0,       # IV threshold for leakage flagging
    leakage_corr_threshold=0.95,    # Correlation threshold for leakage flagging
    drop_high_cardinality=True,     # Auto-drop high-cardinality ID/PII columns
    max_cardinality_ratio=0.7,      # Cardinality ratio cutoff (for n >= 100)
)
```

---

## 📄 License

MIT License — see [LICENSE](LICENSE) for details.
