Skip to content

filter_vehicles

filter_vehicles

filter_vehicles(vehicles: DataFrame, vehicle_types: DataFrame, *, form_factor: str | None = None, propulsion: str | None = None) -> 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).

See Also

ebikes : The electric-only shorthand. join_vehicle_types : Resolve the type attributes this filters on.

Examples:

>>> import pandas as pd
>>> vehicles = pd.DataFrame({"bike_id": ["v1", "v2"], "vehicle_type_id": ["t1", "t2"]})
>>> types = pd.DataFrame({
...     "vehicle_type_id": ["t1", "t2"], "form_factor": ["bicycle", "scooter"],
...     "propulsion_type": ["human", "electric"]})
>>> filter_vehicles(vehicles, types, form_factor="scooter")["bike_id"].tolist()
['v2']
Source code in src/gbfs_toolkit/analytics/frames.py
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``).

    See Also
    --------
    [`ebikes`][gbfs_toolkit.ebikes] : The electric-only shorthand.
    [`join_vehicle_types`][gbfs_toolkit.join_vehicle_types] : Resolve the type attributes this filters on.

    Examples
    --------
    >>> import pandas as pd
    >>> vehicles = pd.DataFrame({"bike_id": ["v1", "v2"], "vehicle_type_id": ["t1", "t2"]})
    >>> types = pd.DataFrame({
    ...     "vehicle_type_id": ["t1", "t2"], "form_factor": ["bicycle", "scooter"],
    ...     "propulsion_type": ["human", "electric"]})
    >>> filter_vehicles(vehicles, types, form_factor="scooter")["bike_id"].tolist()
    ['v2']
    """
    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)