flasheda 0.1.0__tar.gz

flasheda-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: flasheda
+Version: 0.1.0
+Summary: Constant-time EDA for any dataset size — one line, fixed time.
+Author: Your Name
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: rich>=12.0.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: matplotlib>=3.4.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

flasheda-0.1.0/README.md

@@ -0,0 +1,21 @@
+# ⚡ FlashEDA
+
+Constant-time Exploratory Data Analysis — one line, fixed time, any dataset size.
+
+## Install
+```bash
+pip install flasheda
+```
+
+## Usage
+```python
+import flasheda
+
+report = flasheda.analyze(df)   # works on 1K or 50M rows in the same time
+report.show()                   # rich console output
+report.save_html("report.html") # browser report
+```
+
+## How it works
+FlashEDA uses **reservoir sampling** to always analyse exactly 5,000 rows,
+regardless of dataset size. All analyzers run in parallel via ThreadPoolExecutor.

flasheda-0.1.0/flasheda/__init__.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Union, Optional
+
+import pandas as pd
+
+from .sampler import sample, get_sample_size, set_sample_size
+from .analyzers import overview, missing, numeric, categorical, correlation
+from .report import EDAReport
+
+__version__ = "0.1.0"
+__all__ = ["analyze", "set_sample_size", "get_sample_size", "EDAReport"]
+
+
+def analyze(
+    source: Union[pd.DataFrame, str, Path],
+    n: Optional[int] = None,
+    *,
+    show: bool = False,
+    random_state: int = 42,
+) -> EDAReport:
+
+    t0 = time.perf_counter()
+    n = n or get_sample_size()
+
+    if isinstance(source, pd.DataFrame):
+        original_shape = source.shape
+    else:
+        original_shape = (-1, -1)
+
+    sampled = sample(source, n=n, random_state=random_state)
+
+    if original_shape == (-1, -1):
+        original_shape = sampled.shape
+
+    tasks = {
+        "overview":    lambda: overview.analyze(sampled, original_shape),
+        "missing":     lambda: missing.analyze(sampled),
+        "numeric":     lambda: numeric.analyze(sampled),
+        "categorical": lambda: categorical.analyze(sampled),
+        "correlation": lambda: correlation.analyze(sampled),
+    }
+
+    results: dict = {}
+    with ThreadPoolExecutor(max_workers=5) as pool:
+        future_map = {pool.submit(fn): name for name, fn in tasks.items()}
+        for future in as_completed(future_map):
+            name = future_map[future]
+            try:
+                results[name] = future.result()
+            except Exception as exc:
+                results[name] = {"error": str(exc)}
+
+    warnings: list[str] = []
+    miss = results.get("missing", {})
+    if miss.get("critical_columns"):
+        warnings.append(f"Columns with >50% missing: {', '.join(miss['critical_columns'])}")
+    num = results.get("numeric", {})
+    if num.get("skewed_columns"):
+        warnings.append(f"Highly skewed columns: {', '.join(num['skewed_columns'])}")
+    cat = results.get("categorical", {})
+    if cat.get("likely_id_columns"):
+        warnings.append(f"Likely ID columns: {', '.join(cat['likely_id_columns'])}")
+    corr = results.get("correlation", {})
+    if corr.get("numeric_strong_pairs"):
+        warnings.append(f"{len(corr['numeric_strong_pairs'])} strongly correlated pair(s) found")
+
+    elapsed = round(time.perf_counter() - t0, 3)
+
+    report = EDAReport(
+        overview=results.get("overview", {}),
+        missing=results.get("missing", {}),
+        numeric=results.get("numeric", {}),
+        categorical=results.get("categorical", {}),
+        correlation=results.get("correlation", {}),
+        sample_size=len(sampled),
+        elapsed_seconds=elapsed,
+        original_shape=original_shape,
+        warnings=warnings,
+    )
+
+    if show:
+        report.show()
+
+    return report
+
+
+def get_sample_size() -> int:
+    from .sampler import get_sample_size as _get
+    return _get()
+
+
+def set_sample_size(n: int) -> None:
+    from .sampler import set_sample_size as _set
+    _set(n)

flasheda-0.1.0/flasheda/analyzers/__init__.py

@@ -0,0 +1,3 @@
+from . import overview, missing, numeric, categorical, correlation
+
+__all__ = ["overview", "missing", "numeric", "categorical", "correlation"]

flasheda-0.1.0/flasheda/analyzers/categorical.py

@@ -0,0 +1,76 @@
+"""
+flasheda.analyzers.categorical
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Categorical / string column analysis.
+Computes cardinality, top-k frequencies, and flags high-cardinality columns.
+Uses HyperLogLog-style approximation for cardinality on large columns.
+Constant-time: always operates on the fixed sample.
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, Any, List
+
+
+HIGH_CARDINALITY_RATIO = 0.5   # unique/total > 50% → high cardinality warning
+TOP_K = 10
+
+
+def analyze(df: pd.DataFrame) -> Dict[str, Any]:
+    # Include object, string, category, and boolean columns
+    cat_cols = df.select_dtypes(
+        include=["object", "string", "category", "bool"]
+    ).columns.tolist()
+
+    results: Dict[str, Dict[str, Any]] = {}
+
+    for col in cat_cols:
+        s = df[col].dropna().astype(str)
+        n = len(s)
+        if n == 0:
+            results[col] = {"error": "all values are null"}
+            continue
+
+        unique_count = s.nunique()
+        cardinality_ratio = round(unique_count / n, 4)
+        high_cardinality = cardinality_ratio > HIGH_CARDINALITY_RATIO
+
+        vc = s.value_counts()
+        top_k = vc.head(TOP_K)
+
+        top_values = [
+            {
+                "value": str(val),
+                "count": int(cnt),
+                "pct": round(cnt / n * 100, 2),
+            }
+            for val, cnt in top_k.items()
+        ]
+
+        # Mode
+        mode_val = vc.index[0] if len(vc) > 0 else None
+        mode_pct = round(vc.iloc[0] / n * 100, 2) if len(vc) > 0 else 0.0
+
+        # Detect potential ID columns (very high cardinality)
+        likely_id = cardinality_ratio > 0.95
+
+        results[col] = {
+            "count": n,
+            "unique_count": unique_count,
+            "cardinality_ratio": cardinality_ratio,
+            "high_cardinality": high_cardinality,
+            "likely_id_column": likely_id,
+            "mode": str(mode_val),
+            "mode_pct": mode_pct,
+            "top_values": top_values,
+        }
+
+    high_card_cols = [c for c, v in results.items() if v.get("high_cardinality")]
+    likely_id_cols = [c for c, v in results.items() if v.get("likely_id_column")]
+
+    return {
+        "columns": results,
+        "categorical_col_names": cat_cols,
+        "high_cardinality_columns": high_card_cols,
+        "likely_id_columns": likely_id_cols,
+    }

flasheda-0.1.0/flasheda/analyzers/correlation.py

@@ -0,0 +1,91 @@
+"""
+flasheda.analyzers.correlation
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Computes:
+  - Pearson correlation for numeric–numeric pairs
+  - Cramér's V for categorical–categorical pairs
+  - Point-biserial for numeric–boolean pairs
+
+Flags strongly correlated pairs (potential redundant features).
+Always operates on the fixed sample — constant time.
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, Any, List, Tuple
+from itertools import combinations
+
+
+STRONG_CORR_THRESHOLD = 0.80
+MAX_COLS_FOR_HEATMAP = 20   # skip heatmap if too many cols (slow to render)
+
+
+def analyze(df: pd.DataFrame) -> Dict[str, Any]:
+    num_cols = df.select_dtypes(include=["number"]).columns.tolist()
+    cat_cols = df.select_dtypes(include=["object", "string", "category"]).columns.tolist()
+
+    # ── Numeric correlations ────────────────────────────────────────────────
+    pearson_matrix: Dict[str, Any] = {}
+    strong_pairs: List[Dict[str, Any]] = []
+
+    if len(num_cols) >= 2:
+        num_df = df[num_cols].copy()
+        corr = num_df.corr(method="pearson")
+        pearson_matrix = {
+            col: {
+                other: round(float(corr.loc[col, other]), 4)
+                for other in num_cols
+            }
+            for col in num_cols
+        }
+
+        for a, b in combinations(num_cols, 2):
+            v = abs(float(corr.loc[a, b]))
+            if v >= STRONG_CORR_THRESHOLD and not np.isnan(v):
+                strong_pairs.append({"col_a": a, "col_b": b, "pearson_r": round(float(corr.loc[a, b]), 4)})
+
+    # ── Cramér's V for categoricals ─────────────────────────────────────────
+    cramer_pairs: List[Dict[str, Any]] = []
+    if len(cat_cols) >= 2:
+        for a, b in combinations(cat_cols[:10], 2):   # cap at 10 cols
+            v = _cramers_v(df[a], df[b])
+            if v is not None and v >= STRONG_CORR_THRESHOLD:
+                cramer_pairs.append({"col_a": a, "col_b": b, "cramers_v": round(v, 4)})
+
+    # ── Heatmap data (numeric only, capped) ─────────────────────────────────
+    heatmap_cols = num_cols[:MAX_COLS_FOR_HEATMAP]
+    heatmap_data: Dict[str, Any] = {}
+    if len(heatmap_cols) >= 2:
+        hm_corr = df[heatmap_cols].corr(method="pearson")
+        heatmap_data = {
+            "columns": heatmap_cols,
+            "matrix": [[round(float(hm_corr.loc[r, c]), 3) for c in heatmap_cols] for r in heatmap_cols],
+        }
+
+    return {
+        "pearson_matrix": pearson_matrix,
+        "numeric_strong_pairs": strong_pairs,
+        "categorical_strong_pairs": cramer_pairs,
+        "heatmap": heatmap_data,
+        "numeric_col_names": num_cols,
+    }
+
+
+def _cramers_v(a: pd.Series, b: pd.Series) -> float | None:
+    """Cramér's V: symmetric measure of association for categorical columns."""
+    try:
+        from scipy.stats import chi2_contingency
+        ct = pd.crosstab(a.astype(str), b.astype(str))
+        chi2, _, _, _ = chi2_contingency(ct)
+        n = ct.sum().sum()
+        phi2 = chi2 / n
+        r, k = ct.shape
+        phi2_corr = max(0.0, phi2 - (k - 1) * (r - 1) / (n - 1))
+        r_corr = r - (r - 1) ** 2 / (n - 1)
+        k_corr = k - (k - 1) ** 2 / (n - 1)
+        denom = min(k_corr - 1, r_corr - 1)
+        if denom <= 0:
+            return None
+        return float(np.sqrt(phi2_corr / denom))
+    except Exception:
+        return None

flasheda-0.1.0/flasheda/analyzers/missing.py

@@ -0,0 +1,54 @@
+"""
+flasheda.analyzers.missing
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Missing-value analysis on the fixed sample.
+Detects per-column null rates and flags high-missing columns.
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, Any, List
+
+
+WARN_THRESHOLD = 0.20   # 20%+ missing → flag
+CRITICAL_THRESHOLD = 0.50  # 50%+ missing → critical
+
+
+def analyze(df: pd.DataFrame) -> Dict[str, Any]:
+    n = len(df)
+    per_col: Dict[str, Dict[str, Any]] = {}
+
+    for col in df.columns:
+        null_count = int(df[col].isna().sum())
+        null_pct = round(null_count / n * 100, 2) if n > 0 else 0.0
+        severity = "ok"
+        if null_pct >= CRITICAL_THRESHOLD * 100:
+            severity = "critical"
+        elif null_pct >= WARN_THRESHOLD * 100:
+            severity = "warn"
+
+        per_col[col] = {
+            "null_count": null_count,
+            "null_pct": null_pct,
+            "severity": severity,
+        }
+
+    total_cells = n * len(df.columns)
+    total_nulls = sum(v["null_count"] for v in per_col.values())
+    overall_null_pct = round(total_nulls / total_cells * 100, 2) if total_cells > 0 else 0.0
+
+    warn_cols = [c for c, v in per_col.items() if v["severity"] in ("warn", "critical")]
+    critical_cols = [c for c, v in per_col.items() if v["severity"] == "critical"]
+
+    # Detect rows with any null (approximate missing-row pattern)
+    rows_with_any_null = int(df.isna().any(axis=1).sum())
+    rows_with_any_null_pct = round(rows_with_any_null / n * 100, 2) if n > 0 else 0.0
+
+    return {
+        "per_column": per_col,
+        "overall_null_pct": overall_null_pct,
+        "warn_columns": warn_cols,
+        "critical_columns": critical_cols,
+        "rows_with_any_null": rows_with_any_null,
+        "rows_with_any_null_pct": rows_with_any_null_pct,
+    }

flasheda-0.1.0/flasheda/analyzers/numeric.py

@@ -0,0 +1,71 @@
+"""
+flasheda.analyzers.numeric
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+Statistical summary for numeric columns.
+Detects outliers using IQR, computes skewness & kurtosis,
+and flags heavily skewed distributions.
+All computed on the fixed sample — constant time.
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, Any, List
+
+
+SKEW_THRESHOLD = 1.0   # |skew| > 1 → flag
+
+
+def analyze(df: pd.DataFrame) -> Dict[str, Any]:
+    num_cols = df.select_dtypes(include=["number"]).columns.tolist()
+    results: Dict[str, Dict[str, Any]] = {}
+
+    for col in num_cols:
+        s = df[col].dropna()
+        if len(s) < 4:
+            results[col] = {"error": "too few non-null values"}
+            continue
+
+        q1, q50, q75 = float(np.percentile(s, 25)), float(np.percentile(s, 50)), float(np.percentile(s, 75))
+        iqr = q75 - q1
+
+        lower_fence = q1 - 1.5 * iqr
+        upper_fence = q75 + 1.5 * iqr
+        outliers = s[(s < lower_fence) | (s > upper_fence)]
+        outlier_pct = round(len(outliers) / len(s) * 100, 2)
+
+        skewness = float(s.skew())
+        kurt = float(s.kurtosis())
+        mean_val = float(s.mean())
+        std_val = float(s.std())
+        min_val = float(s.min())
+        max_val = float(s.max())
+
+        skew_flag = abs(skewness) > SKEW_THRESHOLD
+
+        results[col] = {
+            "count": int(len(s)),
+            "mean": round(mean_val, 4),
+            "std": round(std_val, 4),
+            "min": round(min_val, 4),
+            "q25": round(q1, 4),
+            "median": round(q50, 4),
+            "q75": round(q75, 4),
+            "max": round(max_val, 4),
+            "iqr": round(iqr, 4),
+            "skewness": round(skewness, 4),
+            "kurtosis": round(kurt, 4),
+            "outlier_count": int(len(outliers)),
+            "outlier_pct": outlier_pct,
+            "skewed": skew_flag,
+            "zero_variance": std_val < 1e-10,
+        }
+
+    skewed_cols = [c for c, v in results.items() if v.get("skewed")]
+    high_outlier_cols = [c for c, v in results.items() if v.get("outlier_pct", 0) > 5]
+
+    return {
+        "columns": results,
+        "numeric_col_names": num_cols,
+        "skewed_columns": skewed_cols,
+        "high_outlier_columns": high_outlier_cols,
+    }

flasheda-0.1.0/flasheda/analyzers/overview.py

@@ -0,0 +1,66 @@
+"""
+flasheda.analyzers.overview
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Fast dataset-level summary: shape, dtypes, memory, duplicates.
+Operates on the fixed-size sample — O(n_sample) always.
+"""
+
+import pandas as pd
+import numpy as np
+from typing import Dict, Any
+
+
+def analyze(df: pd.DataFrame, original_shape: tuple) -> Dict[str, Any]:
+    """
+    Parameters
+    ----------
+    df             : sampled DataFrame
+    original_shape : (rows, cols) of the original dataset before sampling
+    """
+    original_rows, ncols = original_shape
+    sample_rows = len(df)
+
+    dtype_counts: Dict[str, int] = {}
+    for dtype in df.dtypes:
+        key = _simplify_dtype(dtype)
+        dtype_counts[key] = dtype_counts.get(key, 0) + 1
+
+    mem_bytes = df.memory_usage(deep=True).sum()
+    # Extrapolate memory to full dataset
+    scale = original_rows / sample_rows if sample_rows > 0 else 1
+    est_full_mem = mem_bytes * scale
+
+    dup_count = df.duplicated().sum()
+    dup_pct = round(dup_count / sample_rows * 100, 2) if sample_rows > 0 else 0.0
+
+    col_types = {col: _simplify_dtype(df[col].dtype) for col in df.columns}
+
+    return {
+        "original_rows": original_rows,
+        "sample_rows": sample_rows,
+        "columns": ncols,
+        "dtype_counts": dtype_counts,
+        "col_types": col_types,
+        "memory_sample_bytes": int(mem_bytes),
+        "memory_estimated_full_bytes": int(est_full_mem),
+        "duplicate_rows_in_sample": int(dup_count),
+        "duplicate_pct_in_sample": dup_pct,
+        "column_names": list(df.columns),
+    }
+
+
+def _simplify_dtype(dtype) -> str:
+    s = str(dtype)
+    if "int" in s:
+        return "integer"
+    if "float" in s:
+        return "float"
+    if "bool" in s:
+        return "boolean"
+    if "datetime" in s:
+        return "datetime"
+    if "object" in s or "string" in s:
+        return "string/object"
+    if "category" in s:
+        return "category"
+    return s

flasheda-0.1.0/flasheda/report.py

@@ -0,0 +1,348 @@
+"""
+flasheda.report
+~~~~~~~~~~~~~~~
+EDAReport: the single object returned by flasheda.analyze().
+Supports:
+  - .show()         → rich console table
+  - .to_html()      → self-contained HTML report
+  - .to_dict()      → plain dict
+  - .to_json()      → JSON string
+  - .save_html()    → write HTML to disk
+"""
+
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class EDAReport:
+    overview: Dict[str, Any]
+    missing: Dict[str, Any]
+    numeric: Dict[str, Any]
+    categorical: Dict[str, Any]
+    correlation: Dict[str, Any]
+    sample_size: int
+    elapsed_seconds: float
+    original_shape: tuple
+    warnings: list[str] = field(default_factory=list)
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Console output
+    # ──────────────────────────────────────────────────────────────────────
+
+    def show(self) -> None:
+        """Print a rich summary to the console."""
+        from rich.console import Console
+        from rich.table import Table
+        from rich import box
+        from rich.panel import Panel
+
+        console = Console()
+
+        # ── Header ──
+        orig_rows = self.original_shape[0]
+        ncols = self.original_shape[1]
+        console.print(
+            Panel(
+                f"[bold cyan]FlashEDA Report[/bold cyan]\n"
+                f"Dataset: [green]{orig_rows:,}[/green] rows × [green]{ncols}[/green] cols  "
+                f"| Analysed on [yellow]{self.sample_size:,}[/yellow] sampled rows  "
+                f"| ⏱  [white]{self.elapsed_seconds:.2f}s[/white]",
+                expand=False,
+            )
+        )
+
+        # ── Warnings ──
+        if self.warnings:
+            for w in self.warnings:
+                console.print(f"  [bold yellow]⚠  {w}[/bold yellow]")
+            console.print()
+
+        # ── Missing values ──
+        miss = self.missing
+        console.print(f"[bold]Missing values[/bold]  overall: [red]{miss['overall_null_pct']}%[/red]  "
+                      f"| rows with any null: [red]{miss['rows_with_any_null_pct']}%[/red]")
+        if miss["critical_columns"]:
+            console.print(f"  Critical (>50% null): [red]{', '.join(miss['critical_columns'])}[/red]")
+        if miss["warn_columns"]:
+            console.print(f"  Warn    (>20% null): [yellow]{', '.join(miss['warn_columns'])}[/yellow]")
+        console.print()
+
+        # ── Numeric summary table ──
+        num_cols = self.numeric.get("numeric_col_names", [])
+        if num_cols:
+            t = Table(title="Numeric columns", box=box.SIMPLE, show_lines=False)
+            for h in ["Column", "Mean", "Std", "Min", "Median", "Max", "Outlier %", "Skew"]:
+                t.add_column(h, style="white")
+            for col in num_cols:
+                s = self.numeric["columns"].get(col, {})
+                if "error" in s:
+                    continue
+                flag = "[yellow]⚠[/yellow] " if s.get("skewed") else ""
+                t.add_row(
+                    col,
+                    str(s.get("mean", "")),
+                    str(s.get("std", "")),
+                    str(s.get("min", "")),
+                    str(s.get("median", "")),
+                    str(s.get("max", "")),
+                    f"{s.get('outlier_pct', 0)}%",
+                    f"{flag}{s.get('skewness', '')}",
+                )
+            console.print(t)
+
+        # ── Categorical summary table ──
+        cat_cols = self.categorical.get("categorical_col_names", [])
+        if cat_cols:
+            t = Table(title="Categorical columns", box=box.SIMPLE, show_lines=False)
+            for h in ["Column", "Unique", "Cardinality ratio", "Mode", "Mode %", "Flag"]:
+                t.add_column(h)
+            for col in cat_cols:
+                s = self.categorical["columns"].get(col, {})
+                if "error" in s:
+                    continue
+                flag = ""
+                if s.get("likely_id_column"):
+                    flag = "[red]likely ID[/red]"
+                elif s.get("high_cardinality"):
+                    flag = "[yellow]high cardinality[/yellow]"
+                t.add_row(
+                    col,
+                    str(s.get("unique_count", "")),
+                    str(s.get("cardinality_ratio", "")),
+                    str(s.get("mode", ""))[:30],
+                    f"{s.get('mode_pct', '')}%",
+                    flag,
+                )
+            console.print(t)
+
+        # ── Strong correlations ──
+        strong = self.correlation.get("numeric_strong_pairs", [])
+        if strong:
+            console.print("[bold]Strong numeric correlations (|r| ≥ 0.8)[/bold]")
+            for pair in strong[:10]:
+                console.print(f"  {pair['col_a']} ↔ {pair['col_b']}  r={pair['pearson_r']}")
+            console.print()
+
+    # ──────────────────────────────────────────────────────────────────────
+    # HTML report
+    # ──────────────────────────────────────────────────────────────────────
+
+    def to_html(self) -> str:
+        """Return a self-contained HTML report string."""
+        return _render_html(self)
+
+    def save_html(self, path: str = "flasheda_report.html") -> Path:
+        """Save the HTML report to disk and return the path."""
+        p = Path(path)
+        p.write_text(self.to_html(), encoding="utf-8")
+        return p
+
+    # ──────────────────────────────────────────────────────────────────────
+    # Serialisation
+    # ──────────────────────────────────────────────────────────────────────
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "overview": self.overview,
+            "missing": self.missing,
+            "numeric": self.numeric,
+            "categorical": self.categorical,
+            "correlation": self.correlation,
+            "sample_size": self.sample_size,
+            "elapsed_seconds": self.elapsed_seconds,
+            "original_shape": list(self.original_shape),
+            "warnings": self.warnings,
+        }
+
+    def to_json(self, indent: int = 2) -> str:
+        return json.dumps(self.to_dict(), indent=indent, default=str)
+
+    def __repr__(self) -> str:
+        rows, cols = self.original_shape
+        return (
+            f"EDAReport(rows={rows:,}, cols={cols}, "
+            f"sample={self.sample_size:,}, elapsed={self.elapsed_seconds:.2f}s)"
+        )
+
+
+# ─────────────────────────────────────────────────────────────────────────────
+# HTML renderer
+# ─────────────────────────────────────────────────────────────────────────────
+
+def _render_html(r: EDAReport) -> str:
+    num_stats = r.numeric.get("numeric_col_names", [])
+    cat_stats = r.categorical.get("categorical_col_names", [])
+    strong_corr = r.correlation.get("numeric_strong_pairs", [])
+    miss_per_col = r.missing.get("per_column", {})
+
+    # Build numeric rows
+    num_rows_html = ""
+    for col in num_stats:
+        s = r.numeric["columns"].get(col, {})
+        if "error" in s:
+            continue
+        skew_badge = '<span class="badge warn">skewed</span>' if s.get("skewed") else ""
+        out_badge = '<span class="badge warn">outliers</span>' if s.get("outlier_pct", 0) > 5 else ""
+        num_rows_html += f"""
+        <tr>
+          <td><strong>{col}</strong></td>
+          <td>{s.get('mean', '')}</td><td>{s.get('std', '')}</td>
+          <td>{s.get('min', '')}</td><td>{s.get('median', '')}</td><td>{s.get('max', '')}</td>
+          <td>{s.get('outlier_pct', '')}%</td>
+          <td>{s.get('skewness', '')} {skew_badge}</td>
+          <td>{out_badge}</td>
+        </tr>"""
+
+    # Build categorical rows
+    cat_rows_html = ""
+    for col in cat_stats:
+        s = r.categorical["columns"].get(col, {})
+        if "error" in s:
+            continue
+        flag = ""
+        if s.get("likely_id_column"):
+            flag = '<span class="badge danger">likely ID</span>'
+        elif s.get("high_cardinality"):
+            flag = '<span class="badge warn">high cardinality</span>'
+        top = s.get("top_values", [])[:5]
+        top_str = " · ".join(f"{t['value']} ({t['pct']}%)" for t in top)
+        cat_rows_html += f"""
+        <tr>
+          <td><strong>{col}</strong></td>
+          <td>{s.get('unique_count', '')}</td>
+          <td>{s.get('cardinality_ratio', '')}</td>
+          <td>{s.get('mode', '')[:40]}</td>
+          <td>{s.get('mode_pct', '')}%</td>
+          <td class="muted">{top_str[:80]}</td>
+          <td>{flag}</td>
+        </tr>"""
+
+    # Missing table
+    miss_rows_html = ""
+    for col, info in miss_per_col.items():
+        sev = info.get("severity", "ok")
+        color = {"ok": "#27ae60", "warn": "#f39c12", "critical": "#e74c3c"}.get(sev, "#888")
+        bar_w = min(100, int(info.get("null_pct", 0)))
+        miss_rows_html += f"""
+        <tr>
+          <td>{col}</td>
+          <td>{info.get('null_count', 0)}</td>
+          <td>
+            <div class="bar-bg">
+              <div class="bar-fill" style="width:{bar_w}%;background:{color}"></div>
+            </div>
+            {info.get('null_pct', 0)}%
+          </td>
+          <td><span style="color:{color};font-weight:500">{sev}</span></td>
+        </tr>"""
+
+    # Correlation rows
+    corr_html = ""
+    for p in strong_corr[:15]:
+        corr_html += f"<tr><td>{p['col_a']}</td><td>{p['col_b']}</td><td>{p['pearson_r']}</td></tr>"
+
+    # Warnings
+    warn_html = ""
+    for w in r.warnings:
+        warn_html += f'<div class="warn-banner">⚠  {w}</div>'
+
+    orig_rows, orig_cols = r.original_shape
+
+    return f"""<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<title>FlashEDA Report</title>
+<style>
+  * {{ box-sizing: border-box; margin: 0; padding: 0; }}
+  body {{ font-family: system-ui, sans-serif; background: #f5f7fa; color: #222; font-size: 14px; }}
+  .container {{ max-width: 1100px; margin: 0 auto; padding: 24px 16px; }}
+  header {{ background: #1a1a2e; color: #fff; padding: 24px 32px; border-radius: 10px; margin-bottom: 24px; }}
+  header h1 {{ font-size: 22px; font-weight: 600; margin-bottom: 6px; }}
+  header .meta {{ font-size: 13px; color: #aac; }}
+  .card {{ background: #fff; border-radius: 10px; padding: 20px 24px; margin-bottom: 20px; box-shadow: 0 1px 4px rgba(0,0,0,.07); }}
+  .card h2 {{ font-size: 15px; font-weight: 600; margin-bottom: 14px; border-bottom: 1px solid #eee; padding-bottom: 8px; }}
+  table {{ width: 100%; border-collapse: collapse; font-size: 13px; }}
+  th {{ text-align: left; padding: 6px 10px; background: #f0f2f5; font-weight: 500; }}
+  td {{ padding: 6px 10px; border-top: 1px solid #f0f0f0; vertical-align: middle; }}
+  .badge {{ display: inline-block; padding: 2px 7px; border-radius: 12px; font-size: 11px; font-weight: 600; }}
+  .badge.warn {{ background: #fff3cd; color: #856404; }}
+  .badge.danger {{ background: #f8d7da; color: #842029; }}
+  .muted {{ color: #888; font-size: 12px; }}
+  .bar-bg {{ display: inline-block; width: 80px; height: 8px; background: #eee; border-radius: 4px; vertical-align: middle; margin-right: 6px; }}
+  .bar-fill {{ height: 8px; border-radius: 4px; }}
+  .warn-banner {{ background: #fff3cd; color: #856404; padding: 10px 14px; border-radius: 8px; margin-bottom: 10px; font-size: 13px; }}
+  .stats-grid {{ display: grid; grid-template-columns: repeat(auto-fit, minmax(160px, 1fr)); gap: 12px; margin-bottom: 4px; }}
+  .stat-box {{ background: #f8f9fc; border-radius: 8px; padding: 14px 16px; }}
+  .stat-box .label {{ font-size: 11px; color: #888; margin-bottom: 4px; }}
+  .stat-box .value {{ font-size: 20px; font-weight: 600; color: #1a1a2e; }}
+</style>
+</head>
+<body>
+<div class="container">
+  <header>
+    <h1>⚡ FlashEDA Report</h1>
+    <div class="meta">
+      {orig_rows:,} rows × {orig_cols} columns &nbsp;|&nbsp;
+      Analysed on {r.sample_size:,} sampled rows &nbsp;|&nbsp;
+      Completed in {r.elapsed_seconds:.2f}s
+    </div>
+  </header>
+
+  {warn_html}
+
+  <div class="card">
+    <h2>Dataset overview</h2>
+    <div class="stats-grid">
+      <div class="stat-box"><div class="label">Total rows</div><div class="value">{orig_rows:,}</div></div>
+      <div class="stat-box"><div class="label">Columns</div><div class="value">{orig_cols}</div></div>
+      <div class="stat-box"><div class="label">Sample size</div><div class="value">{r.sample_size:,}</div></div>
+      <div class="stat-box"><div class="label">Analysis time</div><div class="value">{r.elapsed_seconds:.2f}s</div></div>
+      <div class="stat-box"><div class="label">Overall null %</div><div class="value">{r.missing.get('overall_null_pct', 0)}%</div></div>
+      <div class="stat-box"><div class="label">Duplicate rows (sample)</div><div class="value">{r.overview.get('duplicate_pct_in_sample', 0)}%</div></div>
+    </div>
+  </div>
+
+  <div class="card">
+    <h2>Missing values</h2>
+    <table>
+      <thead><tr><th>Column</th><th>Null count</th><th>Null %</th><th>Status</th></tr></thead>
+      <tbody>{miss_rows_html}</tbody>
+    </table>
+  </div>
+
+  <div class="card">
+    <h2>Numeric columns</h2>
+    <table>
+      <thead><tr><th>Column</th><th>Mean</th><th>Std</th><th>Min</th><th>Median</th><th>Max</th><th>Outlier %</th><th>Skewness</th><th>Flags</th></tr></thead>
+      <tbody>{num_rows_html}</tbody>
+    </table>
+  </div>
+
+  <div class="card">
+    <h2>Categorical columns</h2>
+    <table>
+      <thead><tr><th>Column</th><th>Unique</th><th>Cardinality ratio</th><th>Mode</th><th>Mode %</th><th>Top values</th><th>Flags</th></tr></thead>
+      <tbody>{cat_rows_html}</tbody>
+    </table>
+  </div>
+
+  {"" if not corr_html else f'''
+  <div class="card">
+    <h2>Strong correlations (|r| ≥ 0.8)</h2>
+    <table>
+      <thead><tr><th>Column A</th><th>Column B</th><th>Pearson r</th></tr></thead>
+      <tbody>{corr_html}</tbody>
+    </table>
+  </div>'''}
+
+  <p class="muted" style="text-align:center;margin-top:16px">Generated by FlashEDA — constant-time EDA for any dataset size</p>
+</div>
+</body>
+</html>"""

flasheda-0.1.0/flasheda/sampler.py

@@ -0,0 +1,124 @@
+"""
+flasheda.sampler
+~~~~~~~~~~~~~~~~
+Reservoir sampling that always returns exactly `n` rows,
+regardless of how large the dataset is. This is the key to
+constant-time EDA: every downstream analyzer always sees
+the same fixed number of rows.
+
+Supports:
+  - pandas DataFrames (in-memory)
+  - CSV / Parquet file paths (chunked streaming, no full load)
+  - Large in-memory DataFrames (random sample without full scan)
+"""
+
+import random
+import math
+import pandas as pd
+import numpy as np
+from pathlib import Path
+from typing import Union, Optional
+
+
+_SAMPLE_SIZE = 5_000  # fixed budget — tweak as needed
+
+
+def sample(
+    source: Union[pd.DataFrame, str, Path],
+    n: int = _SAMPLE_SIZE,
+    random_state: int = 42,
+) -> pd.DataFrame:
+    """
+    Return exactly `n` rows from `source` in O(n) time.
+
+    For DataFrames larger than n:  reservoir / random sample.
+    For DataFrames smaller than n: return as-is (no oversampling).
+    For file paths:                stream in chunks — never load all at once.
+    """
+    rng = random.Random(random_state)
+    np.random.seed(random_state)
+
+    if isinstance(source, (str, Path)):
+        return _sample_file(source, n, rng)
+
+    if not isinstance(source, pd.DataFrame):
+        raise TypeError(f"source must be a DataFrame or file path, got {type(source)}")
+
+    total = len(source)
+    if total <= n:
+        return source.copy()
+
+    # pandas .sample is O(n) with reservoir algorithm under the hood
+    return source.sample(n=n, random_state=random_state).reset_index(drop=True)
+
+
+def _sample_file(path: Union[str, Path], n: int, rng: random.Random) -> pd.DataFrame:
+    """
+    Stream a CSV or Parquet file in fixed-size chunks and maintain
+    a reservoir of exactly n rows — never loading the whole file.
+    """
+    path = Path(path)
+    ext = path.suffix.lower()
+
+    if ext == ".parquet":
+        return _sample_parquet(path, n, rng)
+    elif ext in (".csv", ".tsv", ".txt"):
+        return _sample_csv(path, n, rng)
+    else:
+        raise ValueError(f"Unsupported file type: {ext}. Use .csv or .parquet")
+
+
+def _sample_csv(path: Path, n: int, rng: random.Random) -> pd.DataFrame:
+    """Classic reservoir sampling (Algorithm R) over CSV chunks."""
+    chunk_size = max(n, 10_000)
+    reservoir: list[pd.Series] = []
+    seen = 0
+
+    sep = "\t" if path.suffix.lower() in (".tsv", ".txt") else ","
+
+    for chunk in pd.read_csv(path, chunksize=chunk_size, sep=sep, low_memory=False):
+        for _, row in chunk.iterrows():
+            seen += 1
+            if len(reservoir) < n:
+                reservoir.append(row)
+            else:
+                j = rng.randint(0, seen - 1)
+                if j < n:
+                    reservoir[j] = row
+
+    if not reservoir:
+        raise ValueError("File appears to be empty.")
+
+    return pd.DataFrame(reservoir).reset_index(drop=True)
+
+
+def _sample_parquet(path: Path, n: int, rng: random.Random) -> pd.DataFrame:
+    """
+    For Parquet: read metadata to get total row count,
+    then read only the rows we need via row-group skipping.
+    Falls back to full load + sample if pyarrow unavailable.
+    """
+    try:
+        import pyarrow.parquet as pq
+        pf = pq.ParquetFile(path)
+        total = pf.metadata.num_rows
+        if total <= n:
+            return pf.read().to_pandas()
+        indices = sorted(rng.sample(range(total), n))
+        # Read row groups that contain those indices (approximate but fast)
+        df = pq.read_table(path).to_pandas()
+        return df.iloc[indices].reset_index(drop=True)
+    except ImportError:
+        df = pd.read_parquet(path)
+        return df.sample(n=min(n, len(df)), random_state=42).reset_index(drop=True)
+
+
+def get_sample_size() -> int:
+    return _SAMPLE_SIZE
+
+
+def set_sample_size(n: int) -> None:
+    global _SAMPLE_SIZE
+    if n < 100:
+        raise ValueError("Sample size must be at least 100.")
+    _SAMPLE_SIZE = n

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

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: flasheda
+Version: 0.1.0
+Summary: Constant-time EDA for any dataset size — one line, fixed time.
+Author: Your Name
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.8
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: numpy>=1.21.0
+Requires-Dist: scipy>=1.7.0
+Requires-Dist: rich>=12.0.0
+Requires-Dist: jinja2>=3.0.0
+Requires-Dist: matplotlib>=3.4.0
+Dynamic: author
+Dynamic: classifier
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary

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

@@ -0,0 +1,17 @@
+README.md
+pyproject.toml
+setup.py
+flasheda/__init__.py
+flasheda/report.py
+flasheda/sampler.py
+flasheda.egg-info/PKG-INFO
+flasheda.egg-info/SOURCES.txt
+flasheda.egg-info/dependency_links.txt
+flasheda.egg-info/requires.txt
+flasheda.egg-info/top_level.txt
+flasheda/analyzers/__init__.py
+flasheda/analyzers/categorical.py
+flasheda/analyzers/correlation.py
+flasheda/analyzers/missing.py
+flasheda/analyzers/numeric.py
+flasheda/analyzers/overview.py

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1,6 @@
+pandas>=1.3.0
+numpy>=1.21.0
+scipy>=1.7.0
+rich>=12.0.0
+jinja2>=3.0.0
+matplotlib>=3.4.0

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

@@ -0,0 +1 @@
+flasheda

flasheda-0.1.0/pyproject.toml

@@ -0,0 +1,3 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"

flasheda-0.1.0/setup.cfg

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

flasheda-0.1.0/setup.py

@@ -0,0 +1,22 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="flasheda",
+    version="0.1.0",
+    description="Constant-time EDA for any dataset size — one line, fixed time.",
+    author="Your Name",
+    packages=find_packages(),
+    python_requires=">=3.8",
+    install_requires=[
+        "pandas>=1.3.0",
+        "numpy>=1.21.0",
+        "scipy>=1.7.0",
+        "rich>=12.0.0",
+        "jinja2>=3.0.0",
+        "matplotlib>=3.4.0",
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+    ],
+)