gbfs-toolkit 1.0.0__py3-none-any.whl

gbfs_toolkit/__init__.py

@@ -0,0 +1,223 @@
+"""gbfs-toolkit — research-grade ingestion + semantic quality audit for GBFS feeds.
+
+The community's :mod:`gbfs-validator` checks that a feed is *syntactically* valid;
+this package checks whether it is *semantically* trustworthy and analysis-ready —
+the A1–A7 taxonomy of Fossé & Pallares — and normalises feeds into a stable,
+version-independent data model you can reuse across studies.
+
+Quick start
+-----------
+
+    >>> import json, gbfs_toolkit as gb
+    >>> raw = json.load(open("station_information.json"))
+    >>> stations = gb.to_canonical_station_info(raw, system_id="velib")
+    >>> verdict = gb.audit_static(stations)
+    >>> clean = stations[~verdict["flagged"].to_numpy()]
+"""
+
+from gbfs_toolkit import (
+    accessor,  # noqa: F401 — registers the `.gbfs` DataFrame accessor
+    models,
+)
+from gbfs_toolkit.analysis import (
+    cyclical_time_features,
+    ebikes,
+    filter_vehicles,
+    join_availability,
+    join_pricing,
+    join_vehicle_types,
+    network_changes,
+    occupancy,
+    station_state,
+)
+from gbfs_toolkit.audit import audit_dynamic, audit_frames, audit_static, drop_flagged
+from gbfs_toolkit.catalog import filter_catalog, normalize_operator, resolve, systems_catalog
+from gbfs_toolkit.cluster import (
+    cluster_diurnal_profiles,
+    cluster_spatial,
+    cluster_spectral,
+    diurnal_profiles,
+    label_diurnal_typology,
+)
+from gbfs_toolkit.datasets import load_example
+from gbfs_toolkit.diagnostics import show_versions
+from gbfs_toolkit.errors import (
+    GBFSDiscoveryError,
+    GBFSError,
+    GBFSFetchError,
+    GBFSNotModified,
+    GBFSValidationError,
+)
+from gbfs_toolkit.fetch import (
+    FeedResponse,
+    GBFSFeed,
+    audit_feed,
+    availability,
+    build_session,
+    fetch_feed_json,
+    fetch_multiple,
+    parse_discovery,
+)
+from gbfs_toolkit.fleet import detect_ghost_vehicles, reconcile_fleet_state
+from gbfs_toolkit.geo import (
+    GeoKDTree,
+    features_within,
+    find_nearest_stations,
+    haversine_m,
+    stations_near,
+    to_gdf,
+    to_geojson,
+)
+from gbfs_toolkit.geofencing import (
+    to_canonical_geofencing,
+    zone_area_km2,
+    zones_for_points,
+)
+from gbfs_toolkit.models import (
+    AUDIT_FLAGS,
+    RULES,
+    SCHEMAS,
+    SchemaError,
+    coerce_schema,
+    validate_schema,
+)
+from gbfs_toolkit.multimodal import link_transit_stops
+from gbfs_toolkit.normalize import (
+    to_canonical_alerts,
+    to_canonical_pricing_plans,
+    to_canonical_station_info,
+    to_canonical_station_status,
+    to_canonical_station_vehicle_counts,
+    to_canonical_system_information,
+    to_canonical_system_regions,
+    to_canonical_vehicle_types,
+    to_canonical_vehicles,
+)
+from gbfs_toolkit.osm import enrich_with_osm, station_surroundings
+from gbfs_toolkit.stats import (
+    availability_stats,
+    compare_systems,
+    concentration_metrics,
+    coverage_stats,
+    lorenz_curve,
+    morans_i,
+    ripley_k,
+    system_profile,
+)
+from gbfs_toolkit.timeseries import (
+    append_to_parquet,
+    build_availability_panel,
+    calculate_net_flow,
+    coverage_report,
+    detect_frozen_stations,
+    flow_balance,
+    generate_manifest,
+    stockout_episodes,
+    turnover,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    # audit (the flagship)
+    "audit_static",
+    "audit_dynamic",
+    "audit_frames",
+    "audit_feed",
+    "drop_flagged",
+    # fetch / scrape (daily drivers)
+    "GBFSFeed",
+    "availability",
+    "join_availability",
+    "fetch_multiple",
+    "fetch_feed_json",
+    "build_session",
+    "FeedResponse",
+    "parse_discovery",
+    # normalise
+    "to_canonical_station_info",
+    "to_canonical_station_status",
+    "to_canonical_station_vehicle_counts",
+    "to_canonical_vehicles",
+    "to_canonical_vehicle_types",
+    "to_canonical_pricing_plans",
+    "to_canonical_system_information",
+    "to_canonical_system_regions",
+    "to_canonical_alerts",
+    # catalogue
+    "systems_catalog",
+    "filter_catalog",
+    "resolve",
+    "normalize_operator",
+    # longitudinal (data lake)
+    "append_to_parquet",
+    "build_availability_panel",
+    "calculate_net_flow",
+    "coverage_report",
+    "generate_manifest",
+    "stockout_episodes",
+    "turnover",
+    "flow_balance",
+    "detect_frozen_stations",
+    # clustering ([cluster])
+    "cluster_spatial",
+    "cluster_spectral",
+    "cluster_diurnal_profiles",
+    "diurnal_profiles",
+    "label_diurnal_typology",
+    # multimodal & surroundings
+    "link_transit_stops",
+    "station_surroundings",
+    "enrich_with_osm",
+    # geofencing / service areas ([geo])
+    "to_canonical_geofencing",
+    "zones_for_points",
+    "zone_area_km2",
+    # fleet reconciliation
+    "reconcile_fleet_state",
+    "detect_ghost_vehicles",
+    # network evolution & joins
+    "network_changes",
+    "join_vehicle_types",
+    "join_pricing",
+    "filter_vehicles",
+    "ebikes",
+    # descriptive stats
+    "system_profile",
+    "compare_systems",
+    "concentration_metrics",
+    "lorenz_curve",
+    "coverage_stats",
+    "availability_stats",
+    "morans_i",
+    "ripley_k",
+    # analysis & geo
+    "station_state",
+    "occupancy",
+    "cyclical_time_features",
+    "find_nearest_stations",
+    "features_within",
+    "stations_near",
+    "haversine_m",
+    "GeoKDTree",
+    "to_gdf",
+    "to_geojson",
+    # errors
+    "GBFSError",
+    "GBFSFetchError",
+    "GBFSDiscoveryError",
+    "GBFSValidationError",
+    "GBFSNotModified",
+    # schema / library ergonomics
+    "validate_schema",
+    "coerce_schema",
+    "SCHEMAS",
+    "load_example",
+    "show_versions",
+    # meta
+    "models",
+    "RULES",
+    "AUDIT_FLAGS",
+    "SchemaError",
+    "__version__",
+]

gbfs_toolkit/accessor.py

@@ -0,0 +1,105 @@
+"""A ``.gbfs`` pandas DataFrame accessor for fluent method chaining.
+
+The library's functions stay pure (``f(df, ...)``); this registers a thin namespace so the
+same operations also read as ``df.gbfs.audit()``. Single-frame operations map directly;
+operations that need a *second* frame (join info+status, reconcile against vehicles, …) take
+it as an argument — so ``info.gbfs.join_status(status)`` reads left-to-right.
+
+Importing :mod:`gbfs_toolkit` registers the accessor as a side effect.
+"""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from gbfs_toolkit import analysis, audit, geo, models, stats, timeseries
+
+
+@pd.api.extensions.register_dataframe_accessor("gbfs")
+class GBFSAccessor:
+    """Fluent access to gbfs-toolkit operations — e.g. ``df.gbfs.occupancy()``."""
+
+    def __init__(self, pandas_obj: pd.DataFrame) -> None:
+        self._df = pandas_obj
+
+    # -- single-frame operations (map directly) -----------------------------
+    def audit(self) -> pd.DataFrame:
+        return audit.audit_static(self._df)
+
+    def audit_dynamic(self, **kw) -> pd.DataFrame:
+        return audit.audit_dynamic(self._df, **kw)
+
+    def drop_flagged(self) -> pd.DataFrame:
+        return audit.drop_flagged(self._df)
+
+    def occupancy(self) -> pd.Series:
+        return analysis.occupancy(self._df)
+
+    def station_state(self) -> pd.Series:
+        return analysis.station_state(self._df)
+
+    def net_flow(self) -> pd.DataFrame:
+        return timeseries.calculate_net_flow(self._df)
+
+    def turnover(self, **kw) -> pd.DataFrame:
+        return timeseries.turnover(self._df, **kw)
+
+    def flow_balance(self) -> pd.DataFrame:
+        return timeseries.flow_balance(self._df)
+
+    def stockout_episodes(self, **kw) -> pd.DataFrame:
+        return timeseries.stockout_episodes(self._df, **kw)
+
+    def coverage_report(self, **kw) -> pd.DataFrame:
+        return timeseries.coverage_report(self._df, **kw)
+
+    def detect_frozen_stations(self, **kw) -> pd.DataFrame:
+        return timeseries.detect_frozen_stations(self._df, **kw)
+
+    def system_profile(self) -> pd.Series:
+        return stats.system_profile(self._df)
+
+    def concentration_metrics(self, **kw) -> pd.Series:
+        return stats.concentration_metrics(self._df, **kw)
+
+    def coverage_stats(self, **kw) -> pd.Series:
+        return stats.coverage_stats(self._df, **kw)
+
+    def availability_stats(self, **kw) -> pd.DataFrame:
+        return stats.availability_stats(self._df, **kw)
+
+    def morans_i(self, value_col: str, **kw) -> pd.Series:
+        return stats.morans_i(self._df, value_col, **kw)
+
+    def to_gdf(self, **kw):
+        return geo.to_gdf(self._df, **kw)
+
+    def to_geojson(self, **kw):
+        return geo.to_geojson(self._df, **kw)
+
+    def validate(self, schema: str) -> pd.DataFrame:
+        return models.validate_schema(self._df, schema)
+
+    def coerce(self, schema: str) -> pd.DataFrame:
+        return models.coerce_schema(self._df, schema)
+
+    # -- operations needing a second frame (passed as the argument) ---------
+    def join_status(self, status: pd.DataFrame) -> pd.DataFrame:
+        """``info.gbfs.join_status(status)`` → analysis-ready availability frame."""
+        return analysis.join_availability(self._df, status)
+
+    def audit_frames(self, status: pd.DataFrame | None = None, **kw) -> pd.DataFrame:
+        return audit.audit_frames(self._df, status, **kw)
+
+    def join_vehicle_types(self, vehicle_types: pd.DataFrame) -> pd.DataFrame:
+        return analysis.join_vehicle_types(self._df, vehicle_types)
+
+    def join_pricing(self, plans: pd.DataFrame) -> pd.DataFrame:
+        return analysis.join_pricing(self._df, plans)
+
+    def ebikes(self, vehicle_types: pd.DataFrame) -> pd.DataFrame:
+        return analysis.ebikes(self._df, vehicle_types)
+
+    def network_changes(self, new: pd.DataFrame, **kw) -> pd.DataFrame:
+        """``old.gbfs.network_changes(new)`` → added/removed/recapacitated/moved."""
+        return analysis.network_changes(self._df, new, **kw)

gbfs_toolkit/analysis.py

@@ -0,0 +1,274 @@
+"""Derived, ready-to-use metrics on canonical availability frames.
+
+Small, safe, broadly-applicable transforms that every analysis re-implements —
+deliberately *not* trip/OD inference (left to dedicated research code).
+"""
+
+from __future__ import annotations
+
+import numpy as np
+import pandas as pd
+
+from gbfs_toolkit.geo import haversine_m
+from gbfs_toolkit.models import require_columns
+
+#: Ordered categories returned by :func:`station_state`.
+STATION_STATES = ("disabled", "virtual", "empty", "full", "normal")
+
+#: Ordered categories of the ``presence`` indicator from :func:`join_availability`.
+PRESENCE_STATES = ("both", "info_only", "status_only")
+
+
+def join_availability(info: pd.DataFrame, status: pd.DataFrame) -> pd.DataFrame:
+    """Join a status snapshot onto the station inventory — the analysis-ready availability frame.
+
+    A pure function on canonical frames (no feed object needed), so it works equally on live
+    data and on frames read back from a Parquet lake. Uses an **outer** join — operators
+    routinely add/drop a station from one endpoint mid-sync — with a ``presence`` indicator
+    (Categorical ``both`` / ``info_only`` / ``status_only``) so orphaned rows stay visible
+    instead of being silently dropped.
+
+    Parameters
+    ----------
+    info : pandas.DataFrame
+        Canonical station information (:data:`~gbfs_toolkit.models.STATION_INFO_COLUMNS`).
+    status : pandas.DataFrame
+        Canonical station status (:data:`~gbfs_toolkit.models.STATION_STATUS_COLUMNS`).
+    """
+    require_columns(info, ["station_id"], what="join_availability(info)")
+    require_columns(status, ["station_id"], what="join_availability(status)")
+    info_cols = info.drop(columns=["system_id"]) if "system_id" in info.columns else info
+    merged = status.merge(
+        info_cols, on="station_id", how="outer", suffixes=("", "_info"), indicator="presence"
+    )
+    mapped = merged["presence"].map(
+        {"both": "both", "left_only": "status_only", "right_only": "info_only"}
+    )
+    merged["presence"] = pd.Categorical(mapped, categories=list(PRESENCE_STATES))
+    return merged
+
+
+#: Period of each cyclic calendar field, for sin/cos encoding.
+_CYCLE_PERIODS = {
+    "minute": 60,
+    "hour": 24,
+    "dayofweek": 7,
+    "day": 31,
+    "month": 12,
+    "dayofyear": 366,
+}
+
+
+def cyclical_time_features(
+    timestamps: object, *, fields: tuple[str, ...] = ("hour", "dayofweek", "month")
+) -> pd.DataFrame:
+    """Encode calendar fields as (sin, cos) pairs — the one everyone re-implements.
+
+    Periodic time variables (hour-of-day, day-of-week, month) are discontinuous as raw integers
+    (23:00 is adjacent to 00:00 but ``23`` is far from ``0``); sin/cos on the circle fixes that.
+    Pass any datetime-like (Series / Index / array); returns two columns per field.
+
+    Parameters
+    ----------
+    fields : tuple of str
+        Any of ``minute, hour, dayofweek, day, month, dayofyear``.
+
+    Returns
+    -------
+    pandas.DataFrame
+        ``{field}_sin`` / ``{field}_cos`` per requested field, aligned to the input order.
+    """
+    ts = pd.to_datetime(
+        pd.Series(list(timestamps) if not hasattr(timestamps, "dt") else timestamps)
+    )
+    ts = ts.reset_index(drop=True)
+    out: dict[str, np.ndarray] = {}
+    for f in fields:
+        if f not in _CYCLE_PERIODS:
+            raise ValueError(f"unknown field {f!r}; choose from {sorted(_CYCLE_PERIODS)}")
+        angle = 2 * np.pi * getattr(ts.dt, f).to_numpy() / _CYCLE_PERIODS[f]
+        out[f"{f}_sin"] = np.sin(angle)
+        out[f"{f}_cos"] = np.cos(angle)
+    return pd.DataFrame(out)
+
+
+def occupancy(availability: pd.DataFrame) -> pd.Series:
+    """Occupancy ratio — bikes / (bikes + docks) per station.
+
+    The quantity everyone recomputes by hand. Returns ``NaN`` where there are no bikes *and*
+    no docks (a virtual/dead station), so the divide-by-zero is handled once, consistently.
+    """
+    require_columns(availability, ["num_bikes_available", "num_docks_available"], what="occupancy")
+    bikes = pd.to_numeric(availability["num_bikes_available"], errors="coerce")
+    docks = pd.to_numeric(availability["num_docks_available"], errors="coerce")
+    denom = bikes + docks
+    return (bikes / denom).where(denom > 0).rename("occupancy")
+
+
+def filter_vehicles(
+    vehicles: pd.DataFrame,
+    vehicle_types: pd.DataFrame,
+    *,
+    form_factor: str | None = None,
+    propulsion: str | None = None,
+) -> pd.DataFrame:
+    """Resolve vehicle types then keep only matching vehicles — "where are the X?" in one call.
+
+    ``form_factor`` matches exactly (e.g. ``"bicycle"``, ``"scooter"``); ``propulsion`` matches
+    as a substring (so ``"electric"`` catches both ``electric`` and ``electric_assist``).
+    """
+    out = join_vehicle_types(vehicles, vehicle_types)
+    mask = pd.Series(True, index=out.index)
+    if form_factor is not None:
+        mask &= out["form_factor"].astype("string").str.lower() == form_factor.lower()
+    if propulsion is not None:
+        mask &= (
+            out["propulsion_type"].astype("string").str.contains(propulsion, case=False, na=False)
+        )
+    return out[mask].reset_index(drop=True)
+
+
+def ebikes(vehicles: pd.DataFrame, vehicle_types: pd.DataFrame) -> pd.DataFrame:
+    """Electric vehicles only (any ``electric*`` propulsion), with their type attributes joined."""
+    return filter_vehicles(vehicles, vehicle_types, propulsion="electric")
+
+
+def station_state(availability: pd.DataFrame) -> pd.Series:
+    """Classify each station as ``disabled`` / ``virtual`` / ``empty`` / ``full`` / ``normal``.
+
+    Resolves two edge cases researchers re-derive constantly:
+    an ``is_renting=False`` (and not returning) station is *disabled*, not merely empty;
+    a *virtual* station (painted box, capacity 0/NA) must not be read as "full" just
+    because it reports zero docks.
+
+    Parameters
+    ----------
+    availability : pandas.DataFrame
+        Needs ``num_bikes_available`` and ``num_docks_available``; uses
+        ``is_renting`` / ``is_returning`` / ``is_virtual_station`` / ``capacity`` when present.
+
+    Returns
+    -------
+    pandas.Series
+        Categorical (categories = :data:`STATION_STATES`), aligned to the input index.
+    """
+    n = len(availability)
+    bikes = (
+        pd.to_numeric(availability["num_bikes_available"], errors="coerce").fillna(-1).to_numpy()
+    )
+    docks = (
+        pd.to_numeric(availability["num_docks_available"], errors="coerce").fillna(-1).to_numpy()
+    )
+
+    def _bool(col: str, default: bool) -> np.ndarray:
+        if col in availability:
+            return availability[col].astype("boolean").fillna(default).to_numpy()
+        return np.full(n, default, dtype=bool)
+
+    renting = _bool("is_renting", True)
+    returning = _bool("is_returning", True)
+    is_virtual = _bool("is_virtual_station", False)
+    if "capacity" in availability:
+        cap = pd.to_numeric(availability["capacity"], errors="coerce").to_numpy()
+        is_virtual = is_virtual | ~(cap > 0)  # no physical docks ⇒ treat as virtual
+
+    state = np.where(
+        ~renting & ~returning,
+        "disabled",
+        np.where(
+            is_virtual,
+            "virtual",
+            np.where(bikes <= 0, "empty", np.where(docks <= 0, "full", "normal")),
+        ),
+    )
+    return pd.Series(
+        pd.Categorical(state, categories=list(STATION_STATES)),
+        index=availability.index,
+        name="station_state",
+    )
+
+
+_CHANGE_COLUMNS = ["system_id", "station_id", "change", "old_value", "new_value", "distance_m"]
+
+
+def network_changes(
+    old: pd.DataFrame, new: pd.DataFrame, *, move_threshold_m: float = 50.0
+) -> pd.DataFrame:
+    """Diff two station inventories — how the network itself changed between two dates.
+
+    A multi-month study spans network growth, not a fixed graph. This compares two canonical
+    ``station_information`` frames and reports stations **added**, **removed**,
+    **recapacitated** (capacity changed) and **moved** (relocated beyond ``move_threshold_m``).
+    A station can appear twice (e.g. recapacitated *and* moved).
+
+    Returns
+    -------
+    pandas.DataFrame
+        ``system_id, station_id, change, old_value, new_value, distance_m`` — ``old/new_value``
+        carry the capacity for recapacitations; ``distance_m`` the move distance for moves.
+    """
+    require_columns(old, ["station_id"], what="network_changes(old)")
+    require_columns(new, ["station_id"], what="network_changes(new)")
+    o = old.drop_duplicates("station_id").set_index("station_id")
+    n = new.drop_duplicates("station_id").set_index("station_id")
+    sys_new = new["system_id"].iloc[0] if "system_id" in new.columns and len(new) else None
+
+    rows = []
+
+    def _row(sid, change, **kw):
+        src = n if sid in n.index else o
+        system = src.loc[sid, "system_id"] if "system_id" in src.columns else sys_new
+        rows.append({"system_id": system, "station_id": sid, "change": change, **kw})
+
+    for sid in n.index.difference(o.index):
+        _row(sid, "added")
+    for sid in o.index.difference(n.index):
+        _row(sid, "removed")
+
+    common = o.index.intersection(n.index)
+    if len(common):
+        oc, nc = o.loc[common], n.loc[common]
+        if "capacity" in oc.columns and "capacity" in nc.columns:
+            changed = oc["capacity"].ne(nc["capacity"]) & ~(
+                oc["capacity"].isna() & nc["capacity"].isna()
+            )
+            for sid in common[changed.to_numpy()]:
+                _row(
+                    sid,
+                    "recapacitated",
+                    old_value=oc.at[sid, "capacity"],
+                    new_value=nc.at[sid, "capacity"],
+                )
+        if {"lat", "lon"} <= set(oc.columns) & set(nc.columns):
+            dist = pd.Series(haversine_m(oc["lat"], oc["lon"], nc["lat"], nc["lon"]), index=common)
+            for sid in common[(dist > move_threshold_m).to_numpy()]:
+                _row(sid, "moved", distance_m=round(float(dist[sid]), 1))
+
+    return pd.DataFrame(rows, columns=_CHANGE_COLUMNS).reset_index(drop=True)
+
+
+def join_vehicle_types(vehicles: pd.DataFrame, vehicle_types: pd.DataFrame) -> pd.DataFrame:
+    """Resolve ``vehicle_type_id`` → form factor / propulsion / range onto a vehicles frame.
+
+    Turns "where are the e-bikes?" into a filter: ``out[out.form_factor == "bicycle"]`` etc.
+    Left join on ``vehicle_type_id``; the catalogue's ``system_id`` is dropped to avoid a clash.
+    """
+    cat = vehicle_types.drop(columns=["system_id"], errors="ignore")
+    return vehicles.merge(cat, on="vehicle_type_id", how="left")
+
+
+def join_pricing(vehicles: pd.DataFrame, plans: pd.DataFrame) -> pd.DataFrame:
+    """Resolve ``pricing_plan_id`` → plan name / price / currency onto a vehicles frame.
+
+    Left join of :func:`~gbfs_toolkit.to_canonical_pricing_plans` (its ``plan_id`` matches the
+    vehicle's ``pricing_plan_id``); plan ``name``/``description`` are prefixed ``plan_`` to
+    avoid clashes.
+    """
+    p = plans.drop(columns=["system_id"], errors="ignore").rename(
+        columns={
+            "plan_id": "pricing_plan_id",
+            "name": "plan_name",
+            "description": "plan_description",
+        }
+    )
+    return vehicles.merge(p, on="pricing_plan_id", how="left")

gbfs_toolkit/audit/__init__.py

@@ -0,0 +1,50 @@
+"""Semantic audit of GBFS feeds (the toolkit's flagship)."""
+
+from __future__ import annotations
+
+import pandas as pd
+
+from gbfs_toolkit.audit.dynamic import audit_dynamic
+from gbfs_toolkit.audit.static import audit_static
+
+#: Stacked-audit columns shared by static and dynamic verdicts.
+AUDIT_RESULT_COLUMNS = ["system_id", "station_id", "audit_type", "flagged", "reason"]
+
+
+def audit_frames(
+    info: pd.DataFrame,
+    status: pd.DataFrame | None = None,
+    *,
+    ttl_seconds: int | None = None,
+    system_id: str = "system",
+) -> pd.DataFrame:
+    """Unified semantic audit on canonical frames — static (A1–A7) and, if given, dynamic (D1–D3).
+
+    A pure function (no feed object), so it audits feeds you fetched yourself *or* frames read
+    back from a Parquet lake. Results are stacked with an ``audit_type`` column. Use
+    :func:`audit_static` / :func:`audit_dynamic` directly for the per-rule boolean columns.
+    """
+    static = audit_static(info).assign(audit_type="static")
+    parts = [static[AUDIT_RESULT_COLUMNS]]
+    if status is not None and len(status):
+        from gbfs_toolkit.analysis import join_availability
+
+        availability = join_availability(info, status)
+        dynamic = audit_dynamic(availability, ttl_seconds=ttl_seconds).assign(
+            audit_type="dynamic", system_id=system_id
+        )
+        parts.append(dynamic[AUDIT_RESULT_COLUMNS])
+    return pd.concat(parts, ignore_index=True)
+
+
+def drop_flagged(stations: pd.DataFrame) -> pd.DataFrame:
+    """The analysis-ready subset: stations that pass the static A1–A7 audit, in one call.
+
+    Shorthand for running :func:`audit_static` and keeping the unflagged rows — the first thing
+    most studies do before anything else.
+    """
+    verdict = audit_static(stations)
+    return stations[~verdict["flagged"].to_numpy()].reset_index(drop=True)
+
+
+__all__ = ["audit_static", "audit_dynamic", "audit_frames", "drop_flagged", "AUDIT_RESULT_COLUMNS"]