robustkit 0.0.1__py3-none-any.whl

robustkit/__init__.py

@@ -0,0 +1,54 @@
+"""
+robustkit
+=========
+
+Practical tools for robust analysis of a single continuous relationship
+(y as a function of one continuous x), designed around one core idea:
+a conclusion that survives multiple fitting methods is more trustworthy
+than one that only holds under a single model.
+
+Modules:
+    robustkit.core          -- trend fitting, stability, diagnostics, uncertainty
+    robustkit.segmentation   -- hierarchical grouping, per-segment analysis
+    robustkit.information    -- mutual-information-based feature ranking
+"""
+
+from .core.trend import fit_huber_trend, fit_tukey_trend, fit_ols_trend, predict_trend
+from .core.stability import model_stability_pct
+from .core.diagnostics import cooks_diagnostic, cook_impact
+from .core.uncertainty import bootstrap_band, bca_bootstrap_ci
+from .core.consistency import check_row_integrity, compare_row_sets
+from .segmentation.hierarchy import hierarchical_segment, segment_sizes
+from .segmentation.apply import apply_by_segment
+from .information.entropy import entropy
+from .information.mutual_info import rank_features, information_efficiency
+from .information.quadrants import quadrant_report
+from .information.visualization import plot_feature_space, feature_map
+from .information.profile import profile, print_profile
+
+__all__ = [
+    "fit_huber_trend",
+    "fit_tukey_trend",
+    "fit_ols_trend",
+    "predict_trend",
+    "model_stability_pct",
+    "cooks_diagnostic",
+    "cook_impact",
+    "bootstrap_band",
+    "bca_bootstrap_ci",
+    "check_row_integrity",
+    "compare_row_sets",
+    "hierarchical_segment",
+    "segment_sizes",
+    "apply_by_segment",
+    "entropy",
+    "rank_features",
+    "information_efficiency",
+    "quadrant_report",
+    "plot_feature_space",
+    "feature_map",
+    "profile",
+    "print_profile",
+]
+
+__version__ = "0.0.1"

robustkit/core/consistency.py

@@ -0,0 +1,33 @@
+"""
+Generic integrity checks, independent of any specific fitting method.
+"""
+
+
+def check_row_integrity(df, group_col):
+    total_rows = len(df)
+    n_missing_group = int(df[group_col].isna().sum())
+    grouped_rows = int(df.groupby(group_col, observed=True).size().sum())
+
+    return {
+        "total_rows": total_rows,
+        "rows_accounted_for": grouped_rows,
+        "rows_missing_group_label": n_missing_group,
+        "consistent": total_rows == grouped_rows + 0,
+    }
+
+
+def compare_row_sets(before_df, after_df, key_col):
+    before_keys = set(before_df[key_col])
+    after_keys = set(after_df[key_col])
+
+    dropped = before_keys - after_keys
+    added = after_keys - before_keys
+
+    return {
+        "n_before": len(before_keys),
+        "n_after": len(after_keys),
+        "n_dropped": len(dropped),
+        "n_added": len(added),
+        "dropped_keys": dropped,
+        "added_keys": added,
+    }

robustkit/core/diagnostics.py

@@ -0,0 +1,94 @@
+"""
+Identify individually influential observations, and quantify how much
+they actually change the fitted trend if removed.
+
+cooks_diagnostic() answers "which points stand out?"
+cook_impact() answers "how much does it matter if we remove them?" --
+these are deliberately separate steps, since a flagged point is not
+automatically a point worth acting on.
+
+Cook's distance is computed here via plain OLS and the hat matrix
+(pure numpy/scikit-learn), so this module has no statsmodels
+dependency.
+"""
+
+import numpy as np
+
+from .trend import _design_matrix, fit_huber_trend, predict_trend
+
+
+def cooks_diagnostic(x, y, degree=2):
+    """
+    Compute Cook's distance for each observation, based on an OLS fit
+    of y ~ poly(x, degree). Flags points above the conventional 4/n
+    threshold.
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    n = len(y)
+
+    X, _ = _design_matrix(x, degree)
+    X_design = np.column_stack([np.ones(n), X])
+    p = X_design.shape[1]
+
+    beta, *_ = np.linalg.lstsq(X_design, y, rcond=None)
+    y_hat = X_design @ beta
+    residuals = y - y_hat
+
+    mse = np.sum(residuals ** 2) / (n - p)
+
+    Q, R = np.linalg.qr(X_design)
+    leverage = np.sum(Q ** 2, axis=1)
+    leverage = np.clip(leverage, 1e-12, 1 - 1e-12)
+
+    cooks_d = (residuals ** 2 / (p * mse)) * (leverage / (1 - leverage) ** 2)
+
+    threshold = 4 / n
+    flagged_indices = np.where(cooks_d > threshold)[0]
+
+    return {
+        "cooks_distance": cooks_d,
+        "leverage": leverage,
+        "threshold": threshold,
+        "flagged_indices": flagged_indices,
+    }
+
+
+def cook_impact(x, y, flagged_indices, degree=2, n_points=50):
+    """
+    Compare the Huber-fitted trend curve with and without the given
+    flagged observations, to quantify how much they actually pull the
+    curve.
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    grid = np.linspace(x.min(), x.max(), n_points)
+
+    full_fit = fit_huber_trend(x, y, degree=degree)
+    full_pred = predict_trend(full_fit, grid)
+
+    mask = np.ones(len(x), dtype=bool)
+    mask[np.asarray(flagged_indices, dtype=int)] = False
+
+    if mask.sum() < degree + 2:
+        raise ValueError(
+            "Too few remaining observations to fit a comparison curve "
+            "after excluding flagged points."
+        )
+
+    reduced_fit = fit_huber_trend(x[mask], y[mask], degree=degree)
+    reduced_pred = predict_trend(reduced_fit, grid)
+
+    denom = np.abs(full_pred)
+    denom[denom == 0] = np.nan
+    pct_change = np.abs(full_pred - reduced_pred) / denom * 100
+
+    return {
+        "grid": grid,
+        "with_flagged": full_pred,
+        "without_flagged": reduced_pred,
+        "pct_change": pct_change,
+        "median_pct_change": float(np.nanmedian(pct_change)),
+        "max_pct_change": float(np.nanmax(pct_change)),
+        "n_excluded": int((~mask).sum()),
+    }

robustkit/core/stability.py

@@ -0,0 +1,48 @@
+"""
+Quantify how much a fitted trend curve changes depending on which
+fitting method (Huber, Tukey, or OLS) is used.
+
+The central idea: a curve shape that is nearly identical across all
+three methods is a more trustworthy conclusion than one that only
+appears under a single method.
+"""
+
+import numpy as np
+
+from .trend import fit_huber_trend, fit_tukey_trend, fit_ols_trend, predict_trend
+
+
+def model_stability_pct(x, y, degree=2, n_points=50):
+    """
+    Fit Huber, Tukey, and OLS trends to the same (x, y) data, evaluate
+    all three on a common grid, and report how far apart they are as a
+    percentage of the average predicted value at each grid point.
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    grid = np.linspace(x.min(), x.max(), n_points)
+
+    huber_fit = fit_huber_trend(x, y, degree=degree)
+    tukey_fit = fit_tukey_trend(x, y, degree=degree)
+    ols_fit = fit_ols_trend(x, y, degree=degree)
+
+    huber_pred = predict_trend(huber_fit, grid)
+    tukey_pred = predict_trend(tukey_fit, grid)
+    ols_pred = predict_trend(ols_fit, grid)
+
+    curves = np.vstack([huber_pred, tukey_pred, ols_pred])
+    spread = curves.max(axis=0) - curves.min(axis=0)
+    avg = np.abs(curves.mean(axis=0))
+    avg[avg == 0] = np.nan
+    pct_spread = spread / avg * 100
+
+    return {
+        "grid": grid,
+        "huber": huber_pred,
+        "tukey": tukey_pred,
+        "ols": ols_pred,
+        "pct_spread": pct_spread,
+        "median_pct_diff": float(np.nanmedian(pct_spread)),
+        "p95_pct_diff": float(np.nanpercentile(pct_spread, 95)),
+        "max_pct_diff": float(np.nanmax(pct_spread)),
+    }

robustkit/core/trend.py

@@ -0,0 +1,86 @@
+"""
+Fit a trend curve -- y as a function of a single continuous x -- using
+three different loss functions: Huber, Tukey biweight, and ordinary
+least squares (OLS).
+
+All three share the same polynomial design matrix, so their fitted
+curves are directly comparable. OLS is included deliberately: if a
+robust method and OLS agree closely, that agreement is itself useful
+evidence that the conclusion is not driven by a handful of extreme
+points (see robustkit.core.stability).
+
+Note: statsmodels is only imported lazily, inside fit_tukey_trend and
+the statsmodels branch of predict_trend. Huber and OLS fitting (via
+scikit-learn) work without statsmodels installed at all.
+"""
+
+import numpy as np
+from sklearn.linear_model import HuberRegressor, LinearRegression
+from sklearn.preprocessing import PolynomialFeatures
+
+
+def _design_matrix(x, degree):
+    x = np.asarray(x, dtype=float).reshape(-1, 1)
+    poly = PolynomialFeatures(degree=degree, include_bias=False)
+    return poly.fit_transform(x), poly
+
+
+def fit_huber_trend(x, y, degree=2, epsilon=1.35, alpha=0.0001):
+    """
+    Fit y ~ poly(x, degree) using Huber loss.
+
+    epsilon controls the point at which the loss switches from
+    quadratic to linear (smaller = more aggressive downweighting of
+    outliers; 1.35 is the common default, tuned for ~95% efficiency
+    under normal errors).
+    """
+    X, poly = _design_matrix(x, degree)
+    model = HuberRegressor(epsilon=epsilon, alpha=alpha)
+    model.fit(X, y)
+    return {"model": model, "poly": poly, "kind": "sklearn"}
+
+
+def fit_tukey_trend(x, y, degree=2, c=4.685):
+    """
+    Fit y ~ poly(x, degree) using Tukey's biweight (redescending) loss
+    via statsmodels' robust linear model (RLM).
+
+    Unlike Huber, Tukey's loss fully suppresses the influence of very
+    extreme points rather than merely capping it -- useful when Huber
+    still seems pulled by a handful of severe outliers.
+
+    Requires statsmodels (imported lazily here).
+    """
+    import statsmodels.api as sm
+
+    X, poly = _design_matrix(x, degree)
+    X_sm = sm.add_constant(X)
+    model = sm.RLM(np.asarray(y, dtype=float), X_sm, M=sm.robust.norms.TukeyBiweight(c=c)).fit()
+    return {"model": model, "poly": poly, "kind": "statsmodels"}
+
+
+def fit_ols_trend(x, y, degree=2):
+    """
+    Fit y ~ poly(x, degree) using ordinary least squares. Serves as a
+    non-robust reference point, not a method to be discarded.
+    """
+    X, poly = _design_matrix(x, degree)
+    model = LinearRegression()
+    model.fit(X, y)
+    return {"model": model, "poly": poly, "kind": "sklearn"}
+
+
+def predict_trend(fit, x_new):
+    """
+    Predict y for new x values from a fit dict returned by
+    fit_huber_trend / fit_tukey_trend / fit_ols_trend.
+    """
+    x_new = np.asarray(x_new, dtype=float).reshape(-1, 1)
+    X_new = fit["poly"].transform(x_new)
+
+    if fit["kind"] == "statsmodels":
+        import statsmodels.api as sm
+        X_new = sm.add_constant(X_new, has_constant="add")
+        return np.asarray(fit["model"].predict(X_new))
+
+    return np.asarray(fit["model"].predict(X_new))

robustkit/core/uncertainty.py

@@ -0,0 +1,83 @@
+"""
+Quantify uncertainty in a fitted trend curve (or any statistic derived
+from (x, y)) via bootstrap resampling.
+"""
+
+import numpy as np
+from scipy import stats
+
+from .trend import fit_huber_trend, predict_trend
+
+
+def bootstrap_band(x, y, degree=2, n_boot=500, ci=95, n_points=50, seed=0):
+    rng = np.random.default_rng(seed)
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    n = len(x)
+    grid = np.linspace(x.min(), x.max(), n_points)
+
+    preds = np.empty((n_boot, n_points))
+    for b in range(n_boot):
+        idx = rng.integers(0, n, n)
+        fit = fit_huber_trend(x[idx], y[idx], degree=degree)
+        preds[b] = predict_trend(fit, grid)
+
+    lower_pct = (100 - ci) / 2
+    upper_pct = 100 - lower_pct
+
+    return {
+        "grid": grid,
+        "lower": np.percentile(preds, lower_pct, axis=0),
+        "median": np.percentile(preds, 50, axis=0),
+        "upper": np.percentile(preds, upper_pct, axis=0),
+    }
+
+
+def bca_bootstrap_ci(x, y, statistic_fn, n_boot=1000, ci=95, seed=0):
+    rng = np.random.default_rng(seed)
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    n = len(x)
+
+    theta_hat = statistic_fn(x, y)
+
+    boot_thetas = np.empty(n_boot)
+    for b in range(n_boot):
+        idx = rng.integers(0, n, n)
+        boot_thetas[b] = statistic_fn(x[idx], y[idx])
+
+    prop_less = np.mean(boot_thetas < theta_hat)
+    prop_less = np.clip(prop_less, 1e-6, 1 - 1e-6)
+    z0 = stats.norm.ppf(prop_less)
+
+    jack_thetas = np.empty(n)
+    for i in range(n):
+        mask = np.ones(n, dtype=bool)
+        mask[i] = False
+        jack_thetas[i] = statistic_fn(x[mask], y[mask])
+
+    jack_mean = jack_thetas.mean()
+    num = np.sum((jack_mean - jack_thetas) ** 3)
+    den = 6.0 * (np.sum((jack_mean - jack_thetas) ** 2) ** 1.5)
+    a = num / den if den != 0 else 0.0
+
+    alpha = (100 - ci) / 100 / 2
+    z_lo = stats.norm.ppf(alpha)
+    z_hi = stats.norm.ppf(1 - alpha)
+
+    def _adjust(z):
+        denom = 1 - a * (z0 + z)
+        adjusted_z = z0 + (z0 + z) / denom if denom != 0 else z0
+        return stats.norm.cdf(adjusted_z)
+
+    lo_pct = np.clip(_adjust(z_lo) * 100, 0, 100)
+    hi_pct = np.clip(_adjust(z_hi) * 100, 0, 100)
+
+    return {
+        "estimate": theta_hat,
+        "lower": float(np.percentile(boot_thetas, lo_pct)),
+        "upper": float(np.percentile(boot_thetas, hi_pct)),
+        "z0": float(z0),
+        "a": float(a),
+        "boot_distribution": boot_thetas,
+    }

robustkit/information/entropy.py

@@ -0,0 +1,19 @@
+"""
+Shannon entropy for categorical (or already-discretized) variables.
+"""
+
+import numpy as np
+import pandas as pd
+
+
+def entropy(series):
+    """
+    Shannon entropy in bits of a pandas Series, treating its values as
+    categorical. For continuous data, discretize (bin) it before
+    calling this -- entropy on raw continuous values is not meaningful
+    here.
+    """
+    counts = pd.Series(series).value_counts(normalize=True)
+    probs = counts.to_numpy()
+    probs = probs[probs > 0]
+    return float(-np.sum(probs * np.log2(probs)))

robustkit/information/mutual_info.py

@@ -0,0 +1,87 @@
+"""
+Rank features by mutual information with a target, normalized by each
+feature's own entropy ("information efficiency" -- how much of a
+feature's information content is actually being used to predict the
+target).
+"""
+
+import pandas as pd
+from sklearn.feature_selection import mutual_info_classif, mutual_info_regression
+
+from .entropy import entropy
+
+
+def prepare_features(X):
+    """
+    Minimal default preprocessing: median-impute numeric columns,
+    fill missing categoricals with an explicit "Missing" category,
+    then integer-encode all categoricals. Intended as a reasonable
+    default for mutual information estimation, not a general-purpose
+    preprocessing pipeline.
+    """
+    X = X.copy()
+    for col in X.columns:
+        if pd.api.types.is_numeric_dtype(X[col]):
+            X[col] = X[col].fillna(X[col].median())
+        else:
+            X[col] = X[col].fillna("Missing").astype("category").cat.codes
+    return X
+
+
+def information_efficiency(mutual_information, entropy_bits):
+    """
+    Mutual information per bit of the feature's own entropy. Answers:
+    "of everything this feature could tell us, how much is actually
+    being used to predict the target?" A high-cardinality feature can
+    have high raw mutual information while still being inefficient --
+    most of its information content goes unused.
+    """
+    if entropy_bits <= 0:
+        return 0.0
+    return float(mutual_information / entropy_bits)
+
+
+def _target_is_continuous(y, max_categories=20):
+    """
+    Heuristic: numeric dtype with more than `max_categories` distinct
+    values is treated as continuous; everything else (non-numeric, or
+    numeric with few distinct values -- e.g. an integer-coded class
+    label) is treated as categorical.
+    """
+    return pd.api.types.is_numeric_dtype(y) and y.nunique() > max_categories
+
+
+def rank_features(df, target, seed=0):
+    """
+    Rank every column in df (except target) by mutual information with
+    target and by information efficiency.
+
+    Automatically detects whether target should be treated as
+    continuous (mutual_info_regression) or categorical
+    (mutual_info_classif) via _target_is_continuous.
+    """
+    X = df.drop(columns=[target])
+    y = df[target]
+    X_enc = prepare_features(X)
+
+    if _target_is_continuous(y):
+        mi = mutual_info_regression(X_enc, y, random_state=seed)
+    else:
+        y_enc = y.astype("category").cat.codes
+        mi = mutual_info_classif(X_enc, y_enc, random_state=seed)
+
+    rows = []
+    for col, mi_value in zip(X.columns, mi):
+        bits = entropy(X[col])
+        rows.append({
+            "feature": col,
+            "mutual_information": float(mi_value),
+            "entropy_bits": bits,
+            "information_efficiency": information_efficiency(mi_value, bits),
+        })
+
+    return (
+        pd.DataFrame(rows)
+        .sort_values("information_efficiency", ascending=False)
+        .reset_index(drop=True)
+    )

robustkit/information/profile.py

@@ -0,0 +1,32 @@
+"""
+Basic dataset profiling: a quick orientation before running any
+information-theoretic analysis.
+"""
+
+
+def profile(df, target=None):
+    info = {
+        "n_rows": len(df),
+        "n_columns": df.shape[1],
+        "columns": list(df.columns),
+        "missing_per_column": {k: int(v) for k, v in df.isna().sum().to_dict().items()},
+    }
+    if target is not None:
+        info["target"] = target
+        info["target_dtype"] = str(df[target].dtype)
+        info["target_n_unique"] = int(df[target].nunique())
+    return info
+
+
+def print_profile(df, target=None):
+    p = profile(df, target=target)
+    print(f"Rows: {p['n_rows']}, Columns: {p['n_columns']}")
+    if target is not None:
+        print(f"Target: {p['target']} (dtype={p['target_dtype']}, unique={p['target_n_unique']})")
+    missing = {k: v for k, v in p["missing_per_column"].items() if v > 0}
+    if missing:
+        print("Missing values:")
+        for col, n in missing.items():
+            print(f"  {col}: {n}")
+    else:
+        print("No missing values.")

robustkit/information/quadrants.py

@@ -0,0 +1,67 @@
+"""
+Classify features into four quadrants based on mutual information and
+information efficiency.
+
+Both quadrant_report() and visualization.plot_feature_space() route
+through this module's thresholding logic, so a feature can never be
+labeled differently by the table and the plot -- a bug present in an
+earlier version of this code, where the plot used a fixed 75th
+percentile cutoff while the report used the median.
+"""
+
+from .mutual_info import rank_features
+
+QUADRANT_LABELS = {
+    "star": "Star",            # high MI, high efficiency
+    "power": "Predictive",     # high MI, low efficiency: informative but "expensive"
+    "efficient": "Efficient",  # low MI, high efficiency: cheap but limited ceiling
+    "weak": "Weak",            # low MI, low efficiency
+}
+
+
+def quadrant_report(df=None, target=None, ranking=None, mi_threshold="median", eff_threshold="median"):
+    """
+    Classify features into four quadrants of (mutual information,
+    information efficiency) space.
+
+    Provide either a precomputed `ranking` (output of rank_features)
+    or a `df`/`target` pair to compute it internally.
+
+    mi_threshold / eff_threshold: "median" (default) or a quantile in
+    (0, 1) used as the cutoff for "high" on each axis. Both quadrant
+    thresholds are stored in the returned DataFrame's `.attrs` for
+    inspection or reuse (e.g. by plot_feature_space).
+    """
+    if ranking is None:
+        if df is None or target is None:
+            raise ValueError("Provide either `ranking` or both `df` and `target`.")
+        ranking = rank_features(df, target=target)
+    else:
+        ranking = ranking.copy()
+
+    mi_cut = (
+        ranking["mutual_information"].median()
+        if mi_threshold == "median"
+        else ranking["mutual_information"].quantile(mi_threshold)
+    )
+    eff_cut = (
+        ranking["information_efficiency"].median()
+        if eff_threshold == "median"
+        else ranking["information_efficiency"].quantile(eff_threshold)
+    )
+
+    def _label(row):
+        high_mi = row["mutual_information"] >= mi_cut
+        high_eff = row["information_efficiency"] >= eff_cut
+        if high_mi and high_eff:
+            return "star"
+        if high_mi:
+            return "power"
+        if high_eff:
+            return "efficient"
+        return "weak"
+
+    ranking["quadrant"] = ranking.apply(_label, axis=1)
+    ranking.attrs["mi_threshold"] = mi_cut
+    ranking.attrs["eff_threshold"] = eff_cut
+    return ranking

robustkit/information/visualization.py

@@ -0,0 +1,79 @@
+"""
+Visualize features in information space (efficiency vs. mutual
+information).
+
+plot_feature_space always computes (or accepts) a quadrant-labeled
+ranking via quadrants.quadrant_report -- it never applies its own,
+separate threshold. This guarantees the plot and quadrant_report() can
+never disagree about which quadrant a feature falls into.
+"""
+
+from .quadrants import quadrant_report, QUADRANT_LABELS
+
+_QUADRANT_COLORS = {
+    "star": "green",
+    "power": "steelblue",
+    "efficient": "darkorange",
+    "weak": "gray",
+}
+
+
+def plot_feature_space(df=None, target=None, ranking=None, annotate=True, figsize=(10, 7), ax=None):
+    """
+    Scatter plot of features in information space: x = information
+    efficiency, y = mutual information, bubble size = entropy (bits),
+    color = quadrant.
+
+    Provide either a precomputed `ranking` (ideally the output of
+    quadrant_report, so quadrant labels are already attached) or a
+    `df`/`target` pair to compute everything internally.
+
+    Returns the quadrant-labeled ranking DataFrame (so you can inspect
+    or reuse it), regardless of whether a plot was drawn.
+    """
+    import matplotlib.pyplot as plt
+    from matplotlib.lines import Line2D
+
+    if ranking is None or "quadrant" not in ranking.columns:
+        ranking = quadrant_report(df=df, target=target, ranking=ranking)
+
+    colors = ranking["quadrant"].map(_QUADRANT_COLORS)
+    sizes = ranking["entropy_bits"] * 60 + 20
+
+    created_fig = ax is None
+    if created_fig:
+        fig, ax = plt.subplots(figsize=figsize)
+
+    ax.scatter(
+        ranking["information_efficiency"], ranking["mutual_information"],
+        s=sizes, c=colors, alpha=0.7, edgecolors="black", linewidths=0.5,
+    )
+
+    if annotate:
+        for _, row in ranking.iterrows():
+            ax.annotate(
+                row["feature"],
+                (row["information_efficiency"], row["mutual_information"]),
+                fontsize=8, xytext=(4, 4), textcoords="offset points",
+            )
+
+    legend_elements = [
+        Line2D([0], [0], marker="o", color="w", label=label,
+               markerfacecolor=_QUADRANT_COLORS[quadrant], markersize=10)
+        for quadrant, label in QUADRANT_LABELS.items()
+    ]
+    ax.legend(handles=legend_elements, loc="best")
+    ax.set_xlabel("Information Efficiency (MI per bit of feature entropy)")
+    ax.set_ylabel("Mutual Information")
+    ax.set_title("Feature Information Space")
+    ax.grid(True, alpha=0.3)
+
+    if created_fig:
+        fig.tight_layout()
+
+    return ranking
+
+
+def feature_map(df, target, **kwargs):
+    """Convenience wrapper: rank features and plot them in one call."""
+    return plot_feature_space(df=df, target=target, **kwargs)

robustkit/segmentation/apply.py

@@ -0,0 +1,49 @@
+"""
+Run any robustkit.core analysis function independently within each
+segment of a dataset, and collect the scalar summary results into a
+single report table.
+"""
+
+import numpy as np
+import pandas as pd
+
+
+def _is_reportable_scalar(value):
+    if value is None:
+        return True
+    if isinstance(value, (dict, list, tuple, set, np.ndarray)):
+        return False
+    return isinstance(value, (int, float, str, bool, np.integer, np.floating, np.bool_))
+
+
+def apply_by_segment(df, segment_col, x_col, y_col, analysis_fn, min_points=5, **kwargs):
+    rows = []
+
+    for segment_value, group in df.groupby(segment_col, observed=True):
+        row = {"segment": segment_value, "n": len(group)}
+
+        if len(group) < min_points:
+            row["skipped"] = True
+            row["reason"] = f"fewer than {min_points} points"
+            rows.append(row)
+            continue
+
+        row["skipped"] = False
+
+        x = group[x_col].to_numpy(dtype=float)
+        y = group[y_col].to_numpy(dtype=float)
+
+        try:
+            result = analysis_fn(x, y, **kwargs)
+        except Exception as exc:  # noqa: BLE001
+            row["error"] = str(exc)
+            rows.append(row)
+            continue
+
+        for key, value in result.items():
+            if _is_reportable_scalar(value):
+                row[key] = value
+
+        rows.append(row)
+
+    return pd.DataFrame(rows)

robustkit/segmentation/hierarchy.py

@@ -0,0 +1,49 @@
+"""
+Hierarchical segmentation with a minimum-size fallback.
+"""
+
+import pandas as pd
+
+
+def hierarchical_segment(df, hierarchy, min_size=20):
+    df = df.copy()
+    df["segment_id"] = pd.NA
+    df["segment_level"] = pd.NA
+
+    remaining_idx = df.index
+
+    for level_idx, cols in enumerate(hierarchy):
+        if len(remaining_idx) == 0:
+            break
+
+        subset = df.loc[remaining_idx]
+        sizes = subset.groupby(cols, observed=True).size()
+        valid_groups = sizes[sizes >= min_size].index
+
+        if len(valid_groups) == 0:
+            continue
+
+        group_keys = subset[cols].apply(tuple, axis=1)
+
+        for group_key in valid_groups:
+            if not isinstance(group_key, tuple):
+                group_key = (group_key,)
+            mask = group_keys == group_key
+            idx = subset.index[mask]
+
+            label = "_".join(str(v) for v in group_key)
+            df.loc[idx, "segment_id"] = label
+            df.loc[idx, "segment_level"] = level_idx
+
+        still_unassigned = df.loc[remaining_idx, "segment_id"].isna()
+        remaining_idx = still_unassigned[still_unassigned].index
+
+    if len(remaining_idx) > 0:
+        df.loc[remaining_idx, "segment_id"] = "ALL"
+        df.loc[remaining_idx, "segment_level"] = len(hierarchy)
+
+    return df
+
+
+def segment_sizes(df, segment_col="segment_id"):
+    return df.groupby(segment_col, observed=True).size().sort_values(ascending=False)

robustkit-0.0.1.dist-info/METADATA

@@ -0,0 +1,169 @@
+Metadata-Version: 2.4
+Name: robustkit
+Version: 0.0.1
+Summary: Practical tools for robust analysis of a single continuous relationship: trend fitting, stability checks, influence diagnostics, and bootstrap uncertainty.
+Author: Mikael Lundqvist
+License: MIT License
+        
+        Copyright (c) 2026 Mikael Lundqvist
+        
+        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.
+        
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.24
+Requires-Dist: pandas>=2.0
+Requires-Dist: scikit-learn>=1.3
+Requires-Dist: statsmodels>=0.14
+Requires-Dist: scipy>=1.10
+Requires-Dist: matplotlib>=3.7
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# robustkit
+
+> ⚠️ **Under active development.** This is an early placeholder release
+> to claim the package name on PyPI. The API is incomplete and may
+> change without notice. Not yet recommended for production use.
+
+Practical tools for robust analysis of a single continuous relationship:
+y as a function of one continuous x.
+
+The guiding idea: **a conclusion that survives multiple fitting methods
+is more trustworthy than one that only holds under a single model.**
+`robustkit` makes it easy to compare Huber, Tukey biweight, and OLS
+fits side by side, identify and quantify the influence of individual
+observations, and get honest, bias-corrected uncertainty estimates.
+
+## Status
+
+`robustkit.core` (trend fitting, stability, diagnostics, uncertainty,
+consistency checks), `robustkit.segmentation` (hierarchical grouping,
+per-segment analysis), and `robustkit.information` (mutual-information
+feature ranking) are stable and tested. A more advanced
+information-theoretic pairing layer (conditional MI for a second
+variable, synergy/redundancy scoring) is planned but not yet included.
+
+## Installation
+
+```bash
+git clone https://github.com/<your-username>/robustkit.git
+cd robustkit
+pip install -e ".[dev]"
+```
+
+## Quickstart
+
+```python
+import numpy as np
+from robustkit import (
+    fit_huber_trend, fit_tukey_trend, predict_trend,
+    model_stability_pct, cooks_diagnostic, cook_impact,
+    bootstrap_band, bca_bootstrap_ci,
+)
+
+# x: a single continuous predictor, y: a single continuous outcome
+x = np.random.default_rng(0).uniform(20, 60, 200)
+y = 1000 + 50 * x - 0.4 * x**2 + np.random.default_rng(1).normal(0, 500, 200)
+
+fit = fit_huber_trend(x, y, degree=2)
+y_pred = predict_trend(fit, x_new=[30, 40, 50])
+
+stability = model_stability_pct(x, y)
+print("Median % spread between Huber/Tukey/OLS:", stability["median_pct_diff"])
+
+diag = cooks_diagnostic(x, y)
+impact = cook_impact(x, y, diag["flagged_indices"])
+print("Median % change in curve if flagged points removed:", impact["median_pct_change"])
+
+band = bootstrap_band(x, y)
+ci = bca_bootstrap_ci(x, y, statistic_fn=lambda x_, y_: np.median(y_))
+```
+
+See `examples/quickstart_tutorial.py` for a complete, runnable walkthrough.
+
+## Segmentation
+
+Run any `robustkit.core` analysis independently across subgroups of a
+larger dataset, with automatic fallback to coarser groupings when a
+finer one is too small to analyze reliably:
+
+```python
+from robustkit import hierarchical_segment, apply_by_segment, model_stability_pct
+
+hierarchy = [["department", "level", "status"], ["level", "status"], ["status"]]
+segmented = hierarchical_segment(df, hierarchy, min_size=20)
+
+report = apply_by_segment(
+    segmented, segment_col="segment_id", x_col="age", y_col="value",
+    analysis_fn=model_stability_pct,
+)
+```
+
+`apply_by_segment` works with any function shaped like
+`analysis_fn(x, y, **kwargs) -> dict` -- built-in ones
+(`model_stability_pct`, `cook_impact`, `bca_bootstrap_ci`, ...) or your
+own. Only scalar values in the returned dict end up in the report
+table; segments below `min_points` are skipped rather than causing an
+error.
+
+## Feature ranking (information)
+
+Rank features by mutual information with a target, normalized by each
+feature's own entropy, and classify them into four quadrants:
+
+```python
+from robustkit import rank_features, quadrant_report, plot_feature_space
+
+ranking = rank_features(df, target="value")
+report = quadrant_report(df, target="value")   # adds a `quadrant` column
+plot_feature_space(df, target="value")          # same quadrants, visualized
+```
+
+`quadrant_report` and `plot_feature_space` always agree on quadrant
+assignment -- both route through the same thresholding logic.
+
+**Caveat:** default thresholds are the *median* mutual information /
+efficiency across the ranked features. With only a handful of
+features, this can put a genuinely weak feature in the same "high"
+half as a strong one, since roughly half of any list sits above its
+own median regardless of how large the actual gap is. Median
+thresholding becomes meaningful with a reasonably large feature set;
+for a handful of candidates, read the raw `mutual_information` /
+`information_efficiency` values directly rather than relying on the
+quadrant label alone.
+
+See `examples/information_tutorial.py` for a complete walkthrough.
+
+## Design principles
+
+- **One continuous x, one continuous y** at the core. This keeps every
+  function's output visually and numerically interpretable (a curve
+  you can plot, a band you can read).
+- **Diagnosis and action are separate steps.** `cooks_diagnostic`
+  flags candidates; `cook_impact` tells you whether removing them
+  actually changes anything.
+- **OLS is a reference point, not the enemy.** Comparing robust fits
+  against OLS is how you know whether robustness mattered at all.
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

robustkit-0.0.1.dist-info/RECORD

@@ -0,0 +1,21 @@
+robustkit/__init__.py,sha256=fdEzGgsnzzOm75nHouJV-iao8WlJ_V9gMMeaQ2WEWXM,1809
+robustkit/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+robustkit/core/consistency.py,sha256=AoOrntyBUUbUXJ8u9cVXScT2q0rjac-FVfBvFdCyRs0,913
+robustkit/core/diagnostics.py,sha256=AbpNRmQKZeacQPXnUI4YakBpryf_HlqsBTVhT2atKH0,2881
+robustkit/core/stability.py,sha256=z7jb4G0Fr193etZxZuMSSasBNdxQY-7RY3Tt2WL_Y0U,1640
+robustkit/core/trend.py,sha256=KajZVanRlxz1hXyBVglqe5MXLweKusfqM7nZ3zjzbf4,3069
+robustkit/core/uncertainty.py,sha256=U4VJd1vq68wVZtfqRTs28KMMxqyt52XXnJNNJzGbI4c,2458
+robustkit/information/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+robustkit/information/entropy.py,sha256=hPgrDylHqNTu5lFKccqU8ek2f2WwArP3WCiSmF1OlSM,541
+robustkit/information/mutual_info.py,sha256=VvhtXHxjcBoWvodBMK-BMXtfQZGlL2Np8OmCUPW2i5Q,2940
+robustkit/information/profile.py,sha256=y0iMTdV7yypiAL8HRBJ1FfeDMzLaVKAaIlFx-D_Fz4A,1033
+robustkit/information/quadrants.py,sha256=gNuG2uPhg5-wteKKzIujGcvT7un17nNHePYADTts6fc,2453
+robustkit/information/visualization.py,sha256=9LvP9CvQxz9R5xGj0qWdG1bm5dHDVy4Jc_ceVl_01i8,2693
+robustkit/segmentation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+robustkit/segmentation/apply.py,sha256=HaIz7HUlYMUegpvtJ7eCuQ8SPGh9UCZHG8vA2Ec_7aA,1379
+robustkit/segmentation/hierarchy.py,sha256=9ID64UeBvxdj8QdzbZ-zVl5BhqeJExUpVa3mX7n_Hgs,1423
+robustkit-0.0.1.dist-info/licenses/LICENSE,sha256=OWkkHKeAsP8EtJihCUcc2EzJo2SCq6w8OVsWrkdX9qA,1073
+robustkit-0.0.1.dist-info/METADATA,sha256=aDAdVLVynAKXr7BnBFe-qtgn2zMDVEHa9fLJh89ntzs,6682
+robustkit-0.0.1.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+robustkit-0.0.1.dist-info/top_level.txt,sha256=4p1ktr2dT_27qBBADwfjoR0wdzuajfLB9RkQJEqF_TA,10
+robustkit-0.0.1.dist-info/RECORD,,

robustkit-0.0.1.dist-info/WHEEL

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

robustkit-0.0.1.dist-info/licenses/LICENSE

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

robustkit-0.0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+robustkit