Allow `get_gtfs_segments` to accept a specific date

[araichev]

Is your feature request related to a problem? Please describe.

I wish i could get segments for a particular date of analysis. Sometimes i need to analyze a feed on a date other than the busiest one chosen by GTFS Segents, e.g. a Sunday.

Describe the solution you'd like

Add an optional date keyword argument to get_gtfs_segments, which restricts the analysis to that date (a YYYYMMDD date string, say) instead of the default busiest date. Seems like an easy and powerful change.

[praneethd7]

@araichev Thank you for raising this issue. I can see this feature being helpful to others. I will work on this and add it soon.

[araichev]

Hi @praneethd7 , do you think this feature would be available in July?
Would be quite useful.

[araichev]

Here's one potential solution that modifies get_bus_feed, which you can then use in get_gtfs_segments and elsewhere.
I must confess that i haven't tested this, but it looks about right and i offer it as starting point.

from datetime import datetime
from typing import Optional, Union

def get_bus_feed(
    path: str,
    agency_id: Optional[str] = None,
    threshold: Optional[int] = 1,
    parallel: bool = False,
    date: Optional[Union[str, date]] = None
) -> Tuple[date, Feed]:
    """
    Retrieve a GTFS feed optionally filtered to the given agency and date, the latter of which defaults to the busiest date of the feed.

    Args:
      path (str): Path to the GTFS data directory or zip file.
      agency_id (str, optional): Filter by a specific agency_id.
      threshold (int, optional): Minimum total stop-count across days to include a service_id.
      parallel (bool, optional): If True, process the feed in parallel.
      date (str or datetime.date, optional): Specific date (YYYYMMDD or date) to restrict services to.

    Returns:
      The date used and the GTFS feed.
    """
    # Determine target day and service IDs for that day
    all_days_s_ids_df = get_all_days_s_ids(path)

    if date is not None:
        # Parse string date if needed
        if isinstance(date, str):
            b_day = datetime.strptime(date, "%Y%m%d").date()
        else:
            b_day = date
        # Ensure the day exists in the data
        if b_day not in all_days_s_ids_df.index:
            raise ValueError(f"Date {b_day} not found in GTFS service calendar.")
        # Services active on the specified date
        bday_service_ids = all_days_s_ids_df.loc[b_day][all_days_s_ids_df.loc[b_day] > 0].index.tolist()
        print("Using requested date:", b_day)
    else:
        # Fallback to the busiest date
        b_day, bday_service_ids = ptg.read_busiest_date(path)
        print("Using the busiest day:", b_day)

    # Filter service_ids by threshold frequency across all days
    series = all_days_s_ids_df[bday_service_ids].sum(axis=0) > threshold
    service_ids = series[series].index.values.tolist()

    # Report eliminated low-frequency service IDs
    removed = set(bday_service_ids) - set(service_ids)
    if removed:
        print("Service IDs eliminated due to low frequency:", removed)

    # Build view filter
    route_types = [3, 700, 702, 703, 704, 705]
    view = {
        "routes.txt": {"route_type": route_types},
        "trips.txt": {"service_id": service_ids},
    }
    if agency_id:
        view["agency.txt"] = {"agency_id": agency_id}

    # Load the feed
    feed = ptg.load_geo_feed(path, view=view)
    if parallel:
        num_cores = os.cpu_count() or 1
        print(":: Processing Feed in Parallel :: Number of cores:", num_cores)
        parallel_read(feed)

    return b_day, feed

[praneethd7]

Thank you @araichev for giving me this code to get started. I have implemented this here: #17. Could you help me test this out?

Apologies for the delay in adding this feature. Caught up with life :).

[araichev]

Wow, thanks for your speedy work, @praneethd7 !
I know it's not easy maintaining an open source project with users.

I checked out the pull request, ran its tests, and tested it manually on a New Zealand feed, crosschecking the number of routes found by get_gtfs_segments with GTFS Kit's counts.
Seems to be working fine.

My one suggestion is to edit line https://github.com/UTEL-UIUC/gtfs_segments/blob/main/gtfs_segments/geom_utils.py#L513 to print the actual number of trips processed (which is much lower) or to print what is actually being counted or to print nothing at all.
That's not related to this pull request, but i just noticed it today.