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), robustkit.information (mutual-information
feature ranking, quadrant classification, pairwise redundancy/synergy
scoring), robustkit.benchmark (global-trend segment comparison,
Robustness Map), and robustkit.report (analyst vs. publisher views,
dispersion measures) are stable and tested.
Note on information_efficiency: values can exceed 1.0 for
continuous features. mutual_information is estimated on the
full-resolution continuous values, while entropy_bits is computed on
a binned version of the same feature (since entropy() expects
categorical input). Binning discards information, so entropy_bits is
a lower bound on the feature's true entropy -- an efficiency above 1.0
signals that the feature carries more usable information than a coarse
categorical summary of it would capture. This is expected behavior,
not a bug.
Installation
git clone https://github.com/<your-username>/robustkit.git
cd robustkit
pip install -e ".[dev]"
Quickstart
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:
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:
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.
Benchmarking against a global trend
Compare each segment's observed outcome against what a single global robust trend predicts, with bootstrap uncertainty on the difference -- answers "which groups deviate from the overall trend, and by how much?" rather than "how does the trend look overall?":
from robustkit import segment_position_report
report = segment_position_report(
df, segment_col="department", x_col="age", y_col="salary",
)
# segment n observed_median expected_median difference ci_lower ci_upper
# Finance 176 48339.70 47799.82 539.88 202.15 1031.01
# HR 174 45718.84 46647.39 -928.55 -1293.26 -580.36
# IT 250 47226.50 47126.91 99.59 -117.56 510.81
A segment's confidence interval crossing zero means no clear deviation from the benchmark; HR and Finance above don't cross zero, IT does.
Robustness Map
Classify features by how much a conclusion about their relationship with the target depends on (a) fitting method choice and (b) specific influential observations -- two genuinely different failure modes that a single diagnostic can miss:
from robustkit import feature_robustness_report, plot_feature_robustness
report = feature_robustness_report(df, target="value")
# feature stability_pct cook_impact_pct quadrant
# CRIM 8.9 17.1 fragile
# AGE 16.8 15.5 fragile
# RM 4.9 0.1 robust
# TAX 22.2 1.4 structural_sensitivity
plot_feature_robustness(report=report)
Four quadrants: robust (low spread, low impact), structural sensitivity (sensitive to fitting method, not to specific points), data sensitive (a few points drive the conclusion, method choice barely matters), fragile (both -- least trustworthy).
quadrant_report/plot_feature_space (information) and
feature_robustness_report/plot_feature_robustness (benchmark) both
route through the same shared classifier, robustkit.classify_quadrants
-- any future quadrant-based analysis in this package will too.
Analyst view vs. publisher view
Two visualizations that look superficially similar but answer genuinely different questions:
from robustkit import plot_analyst_view, plot_publisher_view, dispersion_ratio, iqr
# "How confident are we in the trend estimate?" -- a bootstrap
# confidence band that SHRINKS as sample size grows.
plot_analyst_view(df["age"], df["salary"])
# "How spread out are actual values in the population?" -- a median +
# IQR band that does NOT shrink with more data, since it reflects
# real dispersion, not estimation uncertainty. show_points defaults to
# False, since this view is meant for publishing potentially sensitive
# data (e.g. individual salaries) without exposing raw points.
plot_publisher_view(df["age"], df["salary"])
This distinction matters in practice: with 20x more data (same underlying distribution), the analyst view's confidence band roughly halves in width, while the publisher view's IQR band stays essentially unchanged -- confirmed by the package's own test suite.
dispersion_ratio(y) -- (Q3-Q1)/median -- and iqr(y) are available
standalone for tabular reporting; dispersion_by_bin(x, y, n_bins=10)
computes both across bins of a continuous x, e.g. to check whether
dispersion (inequality) grows with age.
Feature pairing (information)
Beyond ranking single features, evaluate pairs of features together: how redundant are they with each other, and does knowing one reveal additional predictive value in the other (synergy, e.g. an interaction effect)?
from robustkit import (
conditional_mutual_information, communication_score,
rank_by_communication, pair_redundancy, pair_synergy,
rank_communicative_pairs,
)
# How communicable is a single feature -- not just predictive, but
# suitable for a clear chart/table (adequate group sizes, homogeneous
# groups, few enough categories to show at once)?
comm_ranking = rank_by_communication(df, target="value")
# How much does region's relevance to the target change once
# department is already known?
synergy = pair_synergy(df, feature_1="department", feature_2="region", target="value")
# Rank every candidate pair by combined relevance, penalizing
# redundant pairs and rewarding genuine synergy
pairs = rank_communicative_pairs(df, target="value")
All mutual-information-based quantities in this module (rank_features,
conditional_mutual_information, pair_redundancy, pair_synergy,
communication_score) are expressed in bits, consistent with
entropy() -- internally, scikit-learn's MI estimators return nats
and are converted before being used anywhere in this package.
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_diagnosticflags candidates;cook_impacttells 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.
Metadata
Release files for robustkit 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| robustkit-0.4.0.tar.gz | 37.2 kB | With provenance | Details for robustkit-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| robustkit-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for robustkit-0.4.0-py3-none-any.whl |
Total release size: 72.7 kB
Release files / robustkit-0.4.0.tar.gz
| Download URL | robustkit-0.4.0.tar.gz |
|---|---|
| Size | 37.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
179572e97908d6e3ce1183939a49a2428d61cb6d06bbc5e9557f84c5debb950e
|
|
BLAKE2b-256 checksum How to use checksums |
9e4a063f30d4fccae8edcc84af4370bd17567f54402769c385253e181d7cb70c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency logRelease files / robustkit-0.4.0-py3-none-any.whl
| Download URL | robustkit-0.4.0-py3-none-any.whl |
|---|---|
| Size | 35.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
89f7dea27d8581e220be3bf82a666cf490aa3e651b3d0bd5b85e469249887394
|
|
BLAKE2b-256 checksum How to use checksums |
740f0391e7924e56472fdb18afdaa815162e4a03fbed657a677922a7b54407ed
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency logSecurity for robustkit 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for robustkit-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 5, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.