🐛📄 – Clarify event_count usage in passenger_events

[chrisyamas]

Problem Description

The TIDES spec does not formally document whether event_count in the passenger_events table is only expected for certain event types (e.g., "Passenger boarded" or "Passenger alighted"). This ambiguity creates implementation challenges and potential inconsistencies across agencies.

Current Specification

The passenger_events table includes an event_count field, but there is no clear documentation about:

1. Which event types should have associated count values
2. Whether event types should be interpreted as singular or plural when counts > 1
3. How to handle aggregated boarding/alighting data

WMATA's Implementation Experience

In WMATA's implementation:

• WMATA uses "Vehicle arrived at stop" as the event type while aggregating passenger loads in the event_count field
• This approach differs from what might be expected in TIDES, where separate events for boardings and alightings might be recorded
• The implementation choice was driven by the structure of WMATA's source data, which combines AVL and APC information

During implementation discussions, questions arose about whether this approach aligns with the intended use of the event_count field, particularly when applied to event types other than passenger boardings/alightings.

Possible Solutions

We propose the following clarifications to the TIDES specification:

Option 1: Specify Applicable Event Types

Explicitly document which event types should have associated event_count values. For example:

The event_count field should only be populated for the following event types:
- "Passenger boarded"
- "Passenger alighted"
- "Individual bike boarded"
- "Individual bike alighted"

Option 2: Rename Event Types to Reflect Plurality

Modify event type names to clearly indicate they can represent multiple events:

- "Passengers boarded" (instead of "Passenger boarded")
- "Passengers alighted" (instead of "Passenger alighted")

Option 3: Add Documentation for Aggregation Approaches

Provide guidance on how to handle aggregated data:

When source data provides aggregated boarding/alighting counts rather than individual events, 
implementers should create a single event record with the appropriate event_type and set 
event_count to the total number of boardings/alightings.

Impact

Clarifying the usage of event_count would:

1. Improve consistency across TIDES implementations
2. Provide clearer guidance for agencies implementing TIDES
3. Reduce ambiguity in data interpretation
4. Better accommodate common agency data structures

Questions for Consideration

1. Should event_count only apply to certain event types? If so, which ones?
2. Should event type names be renamed to possibly be plural?
3. How should aggregated boarding/alighting data be represented in TIDES?
4. Are there other event types where counts would be meaningful?

Additional Context

This issue is related to the broader discussion about passenger events granularity and how agencies typically collect and process boarding/alighting data. Many agencies, including WMATA, work with aggregated data at the stop level rather than individual boarding/alighting events.

[botanize]

I interpret this table to be instantaneous events. So if two things happen at the same time, you should have an event count of 2. But most instantaneous events are probably singletons, which is why event_count defaults to 1.

[botanize]

I'll add that the discussion we had around generalizing this table is very appealing. I think there's a possibility for both vehicle events and device events tables. Or you could use a single device events table, and associate your APC device(s) to vehicles with the devices table, or use the vehicle_id as the device_id.