mclovin 1.0.0__py3-none-any.whl

mclovin/__init__.py

@@ -0,0 +1,118 @@
+"""
+mclovin
+=======
+
+Trustworthy features from messy tabular data.
+
+This package started life as basketball code. What survived the move to a
+general-purpose library is the part that was never really about basketball:
+resolving whatever a dataset calls its columns, saying honestly how reliable
+each derived number is, correcting rates computed on small samples, and
+building panel features that do not leak the future into the past.
+
+Design principles
+-----------------
+1. **Schema-flexible.** Functions resolve canonical names against whatever
+   your DataFrame actually calls them, via :class:`SchemaResolver` pointed at
+   a :class:`~mclovin.vocab.Vocabulary`. Point it at a new dataset, extend the
+   vocabulary, and everything downstream works unchanged.
+
+2. **Honest about provenance.** Many derived quantities need context columns
+   (team totals, station baselines, cohort aggregates) that a given dataset
+   may not carry. Rather than quietly approximating, every metric declares
+   what it needed and reports a reliability tier -- EXACT, APPROXIMATED,
+   PASSTHROUGH, DERIVED or UNAVAILABLE -- so you know which numbers can bear
+   weight.
+
+3. **Leakage-resistant by default.** Rolling windows require a full window,
+   horizon joins match on the key rather than on position, and splits are
+   chronological. The defaults are the careful choice, not the convenient one.
+
+Modules
+-------
+`schema`       Canonical-name resolution and dataset coverage auditing
+`vocab`        Domain vocabularies: aliases, context markers, rate ceilings
+`core`         Shared helpers; the provenance and reliability-tier system
+`panel`        Lags, deltas, rolling windows, horizon joins, temporal splits
+`quality`      Rate validation, artifact detection, robust standardisation
+`shrinkage`    Empirical-Bayes and James-Stein small-sample correction
+`similarity`   PCA decomposition, GMM soft archetypes, Mahalanobis neighbours
+`survival`     Kaplan-Meier, Cox, and censoring-aware label construction
+`units`        Detect and harmonise mixed per-period / cumulative columns
+`evaluation`   Shared regression and classification scoring helpers
+`basketball`   The original domain pack: Four Factors, BPM/PER, draft features
+
+Quick start
+-----------
+    import pandas as pd
+    from mclovin import SchemaResolver, ComputationReport
+    from mclovin.vocab import Vocabulary
+
+    WEATHER = Vocabulary(
+        name="weather",
+        aliases={"TEMP_MAX": ["temperature_2m_max", "tmax"]},
+    )
+
+    df = pd.read_csv("daily.csv")
+    resolver = SchemaResolver(df.columns, vocabulary=WEATHER)
+    print(resolver.coverage().query("available"))
+
+The basketball metrics that were moneyBBall live on in `mclovin.basketball`
+and are unchanged:
+
+    import mclovin.basketball as bb
+
+    resolver = bb.resolver(df.columns)
+    df = bb.draft.add_prospect_features(df, resolver=resolver)
+
+A caution on interpretation
+---------------------------
+A composite that summarises what already happened is not the same thing as a
+predictor of what happens next, and the two are easy to confuse because they
+are computed from the same columns. Check the reliability tier, check what
+the metric needed, and do not mistake a good description for a good forecast.
+"""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("mclovin")
+except PackageNotFoundError:  # pragma: no cover - local/dev install
+    __version__ = "0.0.0-dev"
+
+from . import (
+    core,
+    evaluation,
+    panel,
+    quality,
+    schema,
+    shrinkage,
+    similarity,
+    survival,
+    units,
+    vocab,
+)
+from .core import ComputationReport, MetricSpec, Reliability
+from .schema import SchemaResolver
+from .vocab import Vocabulary
+
+__all__ = [
+    # modules
+    "schema",
+    "vocab",
+    "core",
+    "panel",
+    "quality",
+    "shrinkage",
+    "similarity",
+    "survival",
+    "units",
+    "evaluation",
+    # most-used names
+    "SchemaResolver",
+    "Vocabulary",
+    "ComputationReport",
+    "MetricSpec",
+    "Reliability",
+    "__version__",
+]

mclovin/basketball/__init__.py

@@ -0,0 +1,65 @@
+"""Basketball metrics -- the domain pack.
+
+Everything here is basketball and only basketball: Oliver's Four Factors,
+possession estimation, the box-score composites (BPM, PER, Game Score, PIE,
+VORP), the NCAA-to-NBA draft features, and reconstruction of counting stats
+from rate-only college exports.
+
+It sits on top of the generic machinery in :mod:`mclovin` rather than being
+mixed into it. Nothing in the core imports this subpackage, which is the
+property that lets the core be used on data that has nothing to do with sport.
+
+Provenance and formula citations are unchanged from moneyBBall 0.6.2:
+Oliver's *Basketball on Paper*, Kubatko et al. (2007) in *JQAS*, Myers' BPM
+2.0, Hollinger's PER, Sill's RAPM regularisation, Pelton's age adjustment.
+
+    import pandas as pd
+    import mclovin.basketball as bb
+
+    df = pd.read_csv("train.csv", encoding="latin1")
+    resolver = bb.resolver(df.columns)      # basketball vocabulary supplied
+    df = bb.draft.add_prospect_features(df, resolver=resolver)
+"""
+
+from __future__ import annotations
+
+from typing import Iterable
+
+from ..schema import SchemaResolver
+from ..vocab import register
+from ..vocab.basketball import BASKETBALL
+from . import box_metrics, draft, four_factors, possessions, reconstruct
+from .identities import verify_scoring_identity
+from .coefficients import (
+    FTA_POSSESSION_COEFFICIENT_NBA,
+    FTA_POSSESSION_COEFFICIENT_NCAA,
+    fta_coefficient,
+)
+
+register(BASKETBALL)
+
+
+def resolver(columns: Iterable[str], **kwargs) -> SchemaResolver:
+    """A :class:`~mclovin.schema.SchemaResolver` loaded with the basketball
+    vocabulary.
+
+    Shorthand for ``SchemaResolver(columns, vocabulary=BASKETBALL)``. Pass
+    ``extra_aliases=`` to handle a dataset-specific quirk, exactly as before.
+    """
+    kwargs.setdefault("vocabulary", BASKETBALL)
+    return SchemaResolver(columns, **kwargs)
+
+
+__all__ = [
+    "box_metrics",
+    "draft",
+    "four_factors",
+    "possessions",
+    "reconstruct",
+    "verify_scoring_identity",
+    "resolver",
+    "BASKETBALL",
+    "fta_coefficient",
+    "FTA_POSSESSION_COEFFICIENT_NBA",
+    "FTA_POSSESSION_COEFFICIENT_NCAA",
+]