tlf-correlation-engine 0.1.0__py3-none-any.whl

tlf_correlation_engine/__init__.py

@@ -0,0 +1,28 @@
+"""
+tlf-correlation-engine
+-----------------------
+Country-agnostic correlation analysis (Pearson, Spearman, Kendall) over
+any pandas DataFrame's numeric columns — coefficient matrices, p-values,
+and a sortable/filterable long-form report of relationship strength.
+Part of the TLF-Data-Analysis repo, part of the TLF ("The Living Facts")
+initiative.
+"""
+
+from .engine import CorrelationEngine, SUPPORTED_METHODS
+from .methods import pairwise_correlation
+from .loader import TabularLoader, UnsupportedFileError
+from .errors import CorrelationEngineError, InvalidMethodError, InsufficientDataError
+
+__all__ = [
+    "__version__",
+    "CorrelationEngine",
+    "SUPPORTED_METHODS",
+    "pairwise_correlation",
+    "TabularLoader",
+    "UnsupportedFileError",
+    "CorrelationEngineError",
+    "InvalidMethodError",
+    "InsufficientDataError",
+]
+
+__version__ = "0.1.0"

tlf_correlation_engine/engine.py

@@ -0,0 +1,155 @@
+"""
+Core CorrelationEngine — country-agnostic correlation analysis over any
+pandas DataFrame's numeric columns.
+
+Unlike a bare ``df.corr()`` call, this engine also reports statistical
+significance (p-values) and the number of paired observations behind
+each coefficient, and can produce a sorted, filterable long-form report
+of the strongest / most significant relationships in a dataset.
+
+matrix(), pvalue_matrix(), pairwise(), and report() are all backed by
+the same MIN_OBSERVATIONS-aware pairwise_correlation() calls (see
+methods.py), so they always agree with each other: a pair with too few
+paired observations to be meaningful comes back as NaN everywhere, not
+just in the p-value output.
+"""
+
+import pandas as pd
+
+from .errors import InvalidMethodError, InsufficientDataError
+from .methods import METHODS, pairwise_correlation
+
+SUPPORTED_METHODS = tuple(METHODS)
+
+
+class CorrelationEngine:
+    """Compute correlations across a DataFrame's numeric columns.
+
+    Parameters
+    ----------
+    df : pandas.DataFrame
+        Any DataFrame. Only numeric columns are used; non-numeric
+        columns are ignored automatically.
+    method : str
+        One of "pearson" (default), "spearman", or "kendall".
+    """
+
+    def __init__(self, df: pd.DataFrame, method: str = "pearson"):
+        if method not in SUPPORTED_METHODS:
+            raise InvalidMethodError(
+                f"Unsupported method '{method}'. Choose from: {', '.join(SUPPORTED_METHODS)}."
+            )
+
+        self.method = method
+        self.df = df
+        self._numeric_df = df.select_dtypes(include="number")
+        self._grid_cache = None  # set on first matrix()/pvalue_matrix() call
+
+        if self._numeric_df.shape[1] < 2:
+            raise InsufficientDataError(
+                "Need at least 2 numeric columns to compute correlations; "
+                f"found {self._numeric_df.shape[1]}."
+            )
+
+    @property
+    def columns(self):
+        """Numeric columns considered by this engine."""
+        return list(self._numeric_df.columns)
+
+    def _pairwise_grid(self):
+        """Computes the coefficient and p-value matrices in one pass, both
+        going through the same MIN_OBSERVATIONS-aware pairwise_correlation()
+        used by pairwise()/report() — so a pair with too few paired
+        observations is NaN everywhere, not just in the p-value matrix.
+        Cached per-instance since method/data don't change after __init__.
+        """
+        if self._grid_cache is not None:
+            return self._grid_cache
+
+        cols = self.columns
+        coef = pd.DataFrame(index=cols, columns=cols, dtype=float)
+        pval = pd.DataFrame(index=cols, columns=cols, dtype=float)
+
+        for i, col_a in enumerate(cols):
+            # A column is perfectly, trivially correlated with itself,
+            # regardless of n — this is a definitional identity, not a
+            # statistical claim, so MIN_OBSERVATIONS doesn't apply here.
+            coef.loc[col_a, col_a] = 1.0
+            pval.loc[col_a, col_a] = 0.0
+            for col_b in cols[i + 1:]:
+                result = pairwise_correlation(
+                    self._numeric_df[col_a], self._numeric_df[col_b], method=self.method
+                )
+                coef.loc[col_a, col_b] = result["coefficient"]
+                coef.loc[col_b, col_a] = result["coefficient"]
+                pval.loc[col_a, col_b] = result["p_value"]
+                pval.loc[col_b, col_a] = result["p_value"]
+
+        self._grid_cache = (coef, pval)
+        return self._grid_cache
+
+    def matrix(self) -> pd.DataFrame:
+        """Correlation coefficient matrix. A pair with fewer than
+        MIN_OBSERVATIONS paired observations (see methods.py) is NaN,
+        matching pairwise()/report() — this is NOT the same as a bare
+        ``df.corr()`` call, which would compute a (statistically
+        meaningless) coefficient from as few as 2 points."""
+        coef, _ = self._pairwise_grid()
+        return coef
+
+    def pvalue_matrix(self) -> pd.DataFrame:
+        """P-value matrix aligned with ``matrix()``. Diagonal is 0.0 (a
+        column is perfectly, trivially correlated with itself)."""
+        _, pval = self._pairwise_grid()
+        return pval
+
+    def pairwise(self, col_a: str, col_b: str) -> dict:
+        """Correlation between two specific columns, with n and p-value."""
+        return pairwise_correlation(
+            self._numeric_df[col_a], self._numeric_df[col_b], method=self.method
+        )
+
+    def report(self, threshold: float = None, significant_only: bool = False, alpha: float = 0.05) -> pd.DataFrame:
+        """Long-form report: one row per unique column pair, sorted by
+        the strength of the relationship (descending |coefficient|).
+
+        Parameters
+        ----------
+        threshold : float, optional
+            Only include pairs where |coefficient| >= threshold.
+        significant_only : bool
+            Only include pairs where p_value < alpha.
+        alpha : float
+            Significance threshold used when significant_only=True.
+        """
+        cols = self.columns
+        rows = []
+
+        for i, col_a in enumerate(cols):
+            for col_b in cols[i + 1:]:
+                result = self.pairwise(col_a, col_b)
+                rows.append({
+                    "variable_1": col_a,
+                    "variable_2": col_b,
+                    "method": result["method"],
+                    "coefficient": result["coefficient"],
+                    "p_value": result["p_value"],
+                    "n": result["n"],
+                })
+
+        report_df = pd.DataFrame(rows)
+
+        if report_df.empty:
+            return report_df
+
+        if threshold is not None:
+            report_df = report_df[report_df["coefficient"].abs() >= threshold]
+
+        if significant_only:
+            report_df = report_df[report_df["p_value"] < alpha]
+
+        report_df = report_df.reindex(
+            report_df["coefficient"].abs().sort_values(ascending=False).index
+        ).reset_index(drop=True)
+
+        return report_df

tlf_correlation_engine/errors.py

@@ -0,0 +1,14 @@
+"""Exceptions raised by tlf_correlation_engine."""
+
+
+class CorrelationEngineError(Exception):
+    """Base exception for tlf_correlation_engine."""
+
+
+class InvalidMethodError(CorrelationEngineError):
+    """Raised when an unsupported correlation method is requested."""
+
+
+class InsufficientDataError(CorrelationEngineError):
+    """Raised when a DataFrame doesn't have enough numeric columns or rows
+    to compute a meaningful correlation."""

tlf_correlation_engine/interactive.py

@@ -0,0 +1,83 @@
+"""
+interactive.py — prompts
+Terminal prompts for any run configuration the user didn't supply via
+CLI flags. Flags always win; a prompt only fires for whatever's still
+missing after argument parsing. In --yes (non-interactive) mode, none
+of these are called at all — main.py raises a clear error instead if
+something required is still missing.
+
+Uses questionary for arrow-key menus and multi-select checklists.
+"""
+
+import questionary
+
+from .engine import SUPPORTED_METHODS
+
+
+def prompt_for_path() -> str:
+    return questionary.path("Path to your data file (CSV, Excel, or JSON):").ask()
+
+
+def prompt_for_sheet(sheet_names: list):
+    if not sheet_names or len(sheet_names) == 1:
+        return sheet_names[0] if sheet_names else None
+    return questionary.select("Which sheet should be read?", choices=sheet_names).ask()
+
+
+def prompt_for_method() -> str:
+    return questionary.select(
+        "Which correlation method?",
+        choices=[
+            questionary.Choice("Pearson (linear relationships)", value="pearson"),
+            questionary.Choice("Spearman (monotonic, rank-based, robust to outliers)", value="spearman"),
+            questionary.Choice("Kendall (rank concordance, good for small samples)", value="kendall"),
+        ],
+    ).ask()
+
+
+def prompt_for_output() -> str:
+    return questionary.select(
+        "What should be shown?",
+        choices=[
+            questionary.Choice("Long-form report (sorted by relationship strength)", value="report"),
+            questionary.Choice("Correlation coefficient matrix", value="matrix"),
+            questionary.Choice("P-value matrix", value="pvalues"),
+        ],
+    ).ask()
+
+
+def prompt_for_report_filters() -> tuple:
+    """Only asked when output == 'report'. Returns (threshold, significant_only)."""
+    significant_only = questionary.confirm(
+        "Only show statistically significant pairs (p < 0.05)?", default=False
+    ).ask()
+
+    use_threshold = questionary.confirm(
+        "Filter by minimum correlation strength?", default=False
+    ).ask()
+    threshold = None
+    if use_threshold:
+        raw = questionary.text("Minimum |coefficient| (0.0–1.0):", default="0.5").ask()
+        threshold = float(raw)
+
+    return threshold, significant_only
+
+
+def prompt_for_export() -> tuple:
+    # NOTE: questionary.Choice(value=None) is treated as "no value given"
+    # and defaults to the choice's *title* text, not to a real None. So
+    # "no export" needs its own distinct sentinel ("none") rather than
+    # value=None, or selecting it would be silently mistaken for a
+    # (nonsense) export format and still try to prompt for a path.
+    fmt = questionary.select(
+        "Export the result to a file?",
+        choices=[
+            questionary.Choice("No, just print to terminal", value="none"),
+            questionary.Choice("CSV", value="csv"),
+            questionary.Choice("JSON", value="json"),
+        ],
+    ).ask()
+    if fmt in (None, "none"):
+        return None, None
+    path = questionary.text(f"Export path (e.g. output.{fmt}):").ask()
+    return fmt, path

tlf_correlation_engine/loader.py

@@ -0,0 +1,95 @@
+"""
+loader.py — TabularLoader
+Reads a CSV, Excel, or JSON file into a plain pandas DataFrame with no
+schema assumptions: no required columns, no renaming. Column headers
+are used exactly as given in the source file — CorrelationEngine picks
+out the numeric ones itself.
+
+This mirrors tlf-statistical-summary's TabularLoader (same supported
+formats, same PDF rejection message) since both packages are meant to
+sit downstream of already-cleaned data, not parse raw PDFs themselves.
+"""
+
+import json
+from pathlib import Path
+
+import pandas as pd
+
+from .errors import CorrelationEngineError
+
+
+class UnsupportedFileError(CorrelationEngineError):
+    """Raised when the input file's type can't be read at all (e.g. a
+    raw PDF, or an extension this package doesn't recognize)."""
+
+
+class TabularLoader:
+    """
+    Loads tabular data from a CSV, Excel, or JSON file, as-is.
+
+    Usage:
+        loader = TabularLoader("census_data.csv")
+        df = loader.load()
+
+        loader = TabularLoader("data.xlsx", sheet="District Summary")
+        df = loader.load()
+    """
+
+    SUPPORTED_EXTENSIONS = {".csv", ".xlsx", ".xls", ".json"}
+
+    def __init__(self, filepath: str, sheet=None):
+        self.filepath = Path(filepath)
+        # Excel only: None = first/only sheet; a name or index restricts to one.
+        self.sheet = sheet
+
+    def load(self) -> pd.DataFrame:
+        if not self.filepath.exists():
+            raise FileNotFoundError(f"Data file not found: {self.filepath}")
+        return self._read_file()
+
+    def _read_file(self) -> pd.DataFrame:
+        ext = self.filepath.suffix.lower()
+
+        if ext == ".csv":
+            return pd.read_csv(self.filepath)
+
+        if ext in (".xlsx", ".xls"):
+            sheet = self.sheet if self.sheet is not None else 0
+            return pd.read_excel(self.filepath, sheet_name=sheet)
+
+        if ext == ".json":
+            return self._read_json()
+
+        if ext == ".pdf":
+            raise UnsupportedFileError(
+                f"Cannot read '{self.filepath.name}' directly: this package does not "
+                f"parse PDFs. Convert the PDF's tables into a CSV/Excel/JSON file "
+                f"first (e.g. with tlf-data-cleaning), then load that output here instead."
+            )
+
+        raise UnsupportedFileError(
+            f"Unsupported file type '{ext}' for '{self.filepath.name}'. "
+            f"This package reads: {sorted(self.SUPPORTED_EXTENSIONS)}."
+        )
+
+    def _read_json(self) -> pd.DataFrame:
+        with open(self.filepath, "r", encoding="utf-8") as f:
+            data = json.load(f)
+
+        if isinstance(data, list):
+            return pd.DataFrame(data)
+        if isinstance(data, dict):
+            return pd.DataFrame([data])
+        raise UnsupportedFileError(
+            f"'{self.filepath.name}' is valid JSON but not in a shape this package "
+            f"can read: expected a list of row-objects or a single flat object, "
+            f"got {type(data).__name__}."
+        )
+
+    def list_sheets(self) -> list:
+        """Returns the sheet names in an Excel workbook, for building an
+        interactive sheet-selection prompt. Empty list for non-Excel files."""
+        ext = self.filepath.suffix.lower()
+        if ext not in (".xlsx", ".xls"):
+            return []
+        return pd.ExcelFile(self.filepath).sheet_names

tlf_correlation_engine/main.py

@@ -0,0 +1,135 @@
+"""
+main.py — tlf-correlation-engine CLI
+Country-agnostic Pearson/Spearman/Kendall correlation analysis for any
+tabular file.
+
+Usage:
+    python -m tlf_correlation_engine.main --data census.csv
+    python -m tlf_correlation_engine.main --data census.csv --method spearman --output matrix
+    python -m tlf_correlation_engine.main --data census.csv --yes --output report --export csv --export-path out.csv
+
+Flags are read first; anything not supplied is filled in via
+interactive terminal prompts, UNLESS --yes is passed, in which case
+any required-but-missing value raises a clear error instead of
+prompting (so this can run unattended, e.g. from a script or cron job,
+without hanging on input()).
+"""
+
+import argparse
+import sys
+
+import pandas as pd
+
+from .loader import TabularLoader
+from .engine import CorrelationEngine, SUPPORTED_METHODS
+from .errors import CorrelationEngineError
+from . import interactive
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(description="tlf-correlation-engine: Pearson/Spearman/Kendall correlation analysis")
+    parser.add_argument("--data", default=None, help="Path to a CSV, Excel, or JSON file.")
+    parser.add_argument("--sheet", default=None, help="Excel sheet name to read. Default: first sheet.")
+    parser.add_argument("--method", default=None, choices=SUPPORTED_METHODS, help="Correlation method.")
+    parser.add_argument("--output", default=None, choices=["report", "matrix", "pvalues"],
+                        help="What to show: long-form report, coefficient matrix, or p-value matrix.")
+    parser.add_argument("--threshold", type=float, default=None,
+                        help="Report only: minimum |coefficient| to include.")
+    parser.add_argument("--significant-only", dest="significant_only", action="store_true", default=None,
+                        help="Report only: only include pairs with p < --alpha.")
+    parser.add_argument("--alpha", type=float, default=0.05, help="Significance threshold for --significant-only.")
+    parser.add_argument("--export", default=None, choices=["csv", "json"], help="Export format.")
+    parser.add_argument("--export-path", default=None, help="Export file path.")
+    parser.add_argument("--yes", action="store_true",
+                        help="Non-interactive mode: never prompt, error on missing required values.")
+    return parser.parse_args()
+
+
+def _require(value, flag_name):
+    if value is None:
+        raise SystemExit(f"--yes was given but {flag_name} was not provided and is required.")
+    return value
+
+
+def main():
+    args = parse_args()
+
+    # --- data path ---
+    data_path = args.data
+    if data_path is None:
+        if args.yes:
+            _require(None, "--data")
+        data_path = interactive.prompt_for_path()
+
+    # --- sheet selection (Excel only) ---
+    sheet = args.sheet
+    loader = TabularLoader(data_path)
+    available_sheets = loader.list_sheets()
+    if available_sheets and sheet is None and not args.yes:
+        sheet = interactive.prompt_for_sheet(available_sheets)
+    if sheet is not None:
+        loader = TabularLoader(data_path, sheet=sheet)
+
+    try:
+        df = loader.load()
+    except (CorrelationEngineError, FileNotFoundError) as e:
+        raise SystemExit(f"[tlf-correlation-engine] {e}")
+
+    # --- method ---
+    method = args.method
+    if method is None:
+        if args.yes:
+            method = "pearson"
+        else:
+            method = interactive.prompt_for_method()
+
+    try:
+        engine = CorrelationEngine(df, method=method)
+    except CorrelationEngineError as e:
+        raise SystemExit(f"[tlf-correlation-engine] {e}")
+
+    # --- output type ---
+    output = args.output
+    if output is None:
+        if args.yes:
+            output = "report"
+        else:
+            output = interactive.prompt_for_output()
+
+    # --- report filters (only relevant for output == "report") ---
+    threshold = args.threshold
+    significant_only = args.significant_only
+    if output == "report" and not args.yes and threshold is None and significant_only is None:
+        threshold, significant_only = interactive.prompt_for_report_filters()
+    significant_only = bool(significant_only)
+
+    # --- compute result ---
+    if output == "matrix":
+        result = engine.matrix()
+    elif output == "pvalues":
+        result = engine.pvalue_matrix()
+    else:
+        result = engine.report(threshold=threshold, significant_only=significant_only, alpha=args.alpha)
+
+    print(result.to_string())
+
+    # --- export ---
+    export_fmt, export_path = args.export, args.export_path
+    if export_fmt is None and not args.yes:
+        export_fmt, export_path = interactive.prompt_for_export()
+    if export_fmt:
+        if export_path is None:
+            _require(None, "--export-path")
+        _export(result, export_fmt, export_path)
+        print(f"\nExported to {export_path}")
+
+
+def _export(result: pd.DataFrame, fmt: str, path: str):
+    if fmt == "csv":
+        result.to_csv(path)
+    elif fmt == "json":
+        result.to_json(path, orient="records" if "variable_1" in result.columns else "split", indent=2)
+
+
+if __name__ == "__main__":
+    main()

tlf_correlation_engine/methods.py

@@ -0,0 +1,74 @@
+"""
+Pairwise correlation statistics.
+
+Each function takes two 1-D numeric sequences (typically pandas Series),
+drops rows where either value is missing, and returns a dict with the
+correlation coefficient, its p-value, and the number of paired
+observations actually used (``n``).
+
+Three methods are supported, matching the TLF-Data-Analysis roadmap:
+
+- ``pearson``  — linear correlation (scipy.stats.pearsonr)
+- ``spearman`` — rank/monotonic correlation (scipy.stats.spearmanr)
+- ``kendall``  — rank concordance correlation (scipy.stats.kendalltau)
+"""
+
+import pandas as pd
+from scipy import stats
+
+from .errors import InvalidMethodError, InsufficientDataError
+
+# Below this many paired observations, a correlation coefficient is not
+# considered statistically meaningful.
+MIN_OBSERVATIONS = 3
+
+
+def _paired_dropna(a, b):
+    """Align two series on a shared index and drop rows where either is null."""
+    a = pd.Series(a)
+    b = pd.Series(b)
+    paired = pd.concat([a, b], axis=1).dropna()
+    return paired.iloc[:, 0], paired.iloc[:, 1]
+
+
+def pearson(a, b):
+    a, b = _paired_dropna(a, b)
+    if len(a) < MIN_OBSERVATIONS:
+        return {"method": "pearson", "coefficient": float("nan"), "p_value": float("nan"), "n": len(a)}
+    stat, p = stats.pearsonr(a, b)
+    return {"method": "pearson", "coefficient": stat, "p_value": p, "n": len(a)}
+
+
+def spearman(a, b):
+    a, b = _paired_dropna(a, b)
+    if len(a) < MIN_OBSERVATIONS:
+        return {"method": "spearman", "coefficient": float("nan"), "p_value": float("nan"), "n": len(a)}
+    stat, p = stats.spearmanr(a, b)
+    return {"method": "spearman", "coefficient": stat, "p_value": p, "n": len(a)}
+
+
+def kendall(a, b):
+    a, b = _paired_dropna(a, b)
+    if len(a) < MIN_OBSERVATIONS:
+        return {"method": "kendall", "coefficient": float("nan"), "p_value": float("nan"), "n": len(a)}
+    stat, p = stats.kendalltau(a, b)
+    return {"method": "kendall", "coefficient": stat, "p_value": p, "n": len(a)}
+
+
+METHODS = {
+    "pearson": pearson,
+    "spearman": spearman,
+    "kendall": kendall,
+}
+
+
+def pairwise_correlation(a, b, method="pearson"):
+    """Compute a single pairwise correlation between two series.
+
+    Returns a dict: {"method", "coefficient", "p_value", "n"}.
+    """
+    if method not in METHODS:
+        raise InvalidMethodError(
+            f"Unsupported method '{method}'. Choose from: {', '.join(METHODS)}."
+        )
+    return METHODS[method](a, b)

tlf_correlation_engine-0.1.0.dist-info/METADATA

@@ -0,0 +1,138 @@
+Metadata-Version: 2.4
+Name: tlf-correlation-engine
+Version: 0.1.0
+Summary: Country-agnostic Pearson/Spearman/Kendall correlation analysis over pandas DataFrames — part of The Living Facts (TLF).
+Author-email: Sanchita Karki <karkisanchu06@gmail.com>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/ctpl-git/TLF-Data-Analysis
+Project-URL: Repository, https://github.com/ctpl-git/TLF-Data-Analysis
+Project-URL: Issues, https://github.com/ctpl-git/TLF-Data-Analysis/issues
+Classifier: Development Status :: 3 - Alpha
+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 :: Information Analysis
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pandas>=1.5
+Requires-Dist: scipy>=1.9
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: questionary>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# tlf-correlation-engine
+
+Country-agnostic correlation analysis — part of **TLF** ("The Living Facts").
+
+Computes Pearson, Spearman, or Kendall correlations across any pandas
+DataFrame's numeric columns, along with p-values and observation counts,
+and produces a sorted, filterable long-form report of the strongest and
+most statistically significant relationships in a dataset.
+
+Unlike `tlf-census-stats`, this package has no dependency on a specific
+country schema — it works on any DataFrame with 2+ numeric columns.
+
+---
+
+## Install
+
+```bash
+pip install tlf-correlation-engine
+```
+
+Or from source, inside the `TLF-Data-Analysis` monorepo:
+
+```bash
+cd tlf-correlation-engine
+pip install -e ".[dev]"
+```
+
+---
+
+## Usage
+
+```python
+import pandas as pd
+from tlf_correlation_engine import CorrelationEngine
+
+df = pd.read_csv("census_data.csv")
+
+engine = CorrelationEngine(df, method="pearson")  # or "spearman" / "kendall"
+
+# Coefficient matrix (like df.corr(), but validated numeric-only)
+engine.matrix()
+
+# P-value matrix, aligned with matrix()
+engine.pvalue_matrix()
+
+# One specific pair, with n and p-value
+engine.pairwise("literacy_rate", "urban_population")
+
+# Long-form report of all pairs, strongest relationship first
+engine.report()
+
+# Only strong (|r| >= 0.5) and statistically significant (p < 0.05) pairs
+engine.report(threshold=0.5, significant_only=True)
+```
+
+### Methods
+
+| Method | Use for |
+|---|---|
+| `pearson` | Linear relationships between continuous variables |
+| `spearman` | Monotonic (rank-based) relationships, robust to outliers/non-linearity |
+| `kendall` | Rank concordance, more robust on small samples or many tied ranks |
+
+---
+
+## CLI
+
+```bash
+tlf-correlation-engine --data census.csv --method spearman --output report --export csv --export-path out.csv
+```
+
+Run with no flags at all for a fully interactive walkthrough (file path → sheet selection → method → output type → report filters → export format):
+
+```bash
+tlf-correlation-engine
+```
+
+For unattended/scripted runs, `--yes` disables all prompting and fails loudly (rather than silently guessing) if something required — like `--data` — is missing:
+
+```bash
+tlf-correlation-engine --data census.csv --yes --method pearson --output matrix
+```
+
+### CLI flags
+
+| Flag | Description |
+|---|---|
+| `--data` | Path to a CSV, Excel, or JSON file |
+| `--sheet` | Excel sheet name (default: first sheet) |
+| `--method` | `pearson` \| `spearman` \| `kendall` |
+| `--output` | `report` \| `matrix` \| `pvalues` |
+| `--threshold` | Report only: minimum \|coefficient\| to include |
+| `--significant-only` | Report only: only include pairs with p < `--alpha` |
+| `--alpha` | Significance threshold for `--significant-only` (default 0.05) |
+| `--export` | `csv` \| `json` |
+| `--export-path` | Export file path |
+| `--yes` | Non-interactive mode: never prompt, error on missing required values |
+
+---
+
+## Errors
+
+- `InvalidMethodError` — unsupported `method` value
+- `InsufficientDataError` — fewer than 2 numeric columns in the DataFrame
+
+---
+
+## License
+
+MIT — see `LICENSE`.

tlf_correlation_engine-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+tlf_correlation_engine/__init__.py,sha256=JGh4txQGh0aoouzHbFsToWgf31JB-r3lHMWIIkQ3Yso,867
+tlf_correlation_engine/engine.py,sha256=35dgbl_TbwIcUGjQO79A4v15oamm_iPIQTX9a98JZKU,6052
+tlf_correlation_engine/errors.py,sha256=B-jjSDhLZPBuqDqgOdGbMjf-OEAtfRc22GLpHOViA8E,443
+tlf_correlation_engine/interactive.py,sha256=u4SR6svEF0LIyHA6CIHpuJz6UtP-tbigMu0vdtHXHEY,3068
+tlf_correlation_engine/loader.py,sha256=VPB8xyO60k-raSuCec-UXeW0bh_aaapUS9NzktHCWX0,3337
+tlf_correlation_engine/main.py,sha256=reRuTzob5Fjxu-UU_y_3M4yYXK1RGRQu-X-wQTIF8dE,5136
+tlf_correlation_engine/methods.py,sha256=sOi22k5-gYUc4-QOYH4OTsTVF_H7Wj8dK0kf8axoJ80,2441
+tlf_correlation_engine-0.1.0.dist-info/licenses/LICENSE,sha256=Oi5Nz1L9eFpL3SUampJQJMvTKHVvGdPF-bEaHxFeqlk,1070
+tlf_correlation_engine-0.1.0.dist-info/METADATA,sha256=HOdRIUAayptUhQTZ6Th8VcAuPuyB6nyzAZ5p32WJODA,4402
+tlf_correlation_engine-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+tlf_correlation_engine-0.1.0.dist-info/entry_points.txt,sha256=ROELEpgkAf7EWXy0zw21t-IAu9VglpmvlPb_oBmXkMM,76
+tlf_correlation_engine-0.1.0.dist-info/top_level.txt,sha256=e_PNyTDcSFJqfdAfgcquHUpClglpZpKM246AHqPsyeo,23
+tlf_correlation_engine-0.1.0.dist-info/RECORD,,

tlf_correlation_engine-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

tlf_correlation_engine-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+tlf-correlation-engine = tlf_correlation_engine.main:main

tlf_correlation_engine-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2026 Sanchita Karki
+
+Permission is hereby granted, free of charge, to any person obtaining a copyof 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.

tlf_correlation_engine-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+tlf_correlation_engine