Add CrowdLevel to VehiclePosition

[sccmcca]

Hi everyone,

This pull request contains a proposal for CrowdLevel continuing from #212 and is based off of stakeholder interest in #223 for a description of occupancy levels in GTFS Realtime that are expressed as enum values on a simple ordinal scale (i.e., NOT_CROWDED, SOME_CROWDING, CROWDED).

This is in contrast to OccupancyStatus which has been clarified in #259 to describe occupancies by states (i.e., MANY_SEATS_AVAILABLE, STANDING_ROOM_ONLY, etc.) that cannot necessarily be attributed to a unversal linear scale (as seen in a few practices), as well as occupancy_percentage which describes occupancy ratio at a fine-grained level.

Note that this pull request is for the experimental adoption of CrowdLevel. Feedback is welcomed!

[barbeau]

Thanks @scmcca! Mostly LGTM, some comments in-line

[bbafford]

Clever Devices would like to understand if the intention is to expand GTFS-RT to include OccupancyStatus, OccupancyPercentage, and CrowdLevel. It is not clear how these three should co-exist, why such similar fields are being proposed, and the differences between OccupancyStatus and CrowdLevel. If CrowdLevel is intended to fully replace OccupancyStatus, than we believe the proposal in #261 is satisfactory.

Our contributions to #223 advocating a clear, coherent, and not overly-precise measure of real-time occupancy were not meant as a request for yet another field. This was our perspective on the best way for GTFS-RT to communicate crowding to riders. We believe that an additional field complicates this. We are unlikely to become produces of CrowdLevel as we already extended support of OccupancyStatus to satisfy the pressing need to communicate passenger crowding. We map crowding levels to three enumerations allowed by OccupancyStatus that have a clear hierarchy (Empty, Few Seats Available, Full).

[stevenmwhite]

We map crowding levels to three enumerations allowed by OccupancyStatus that have a clear hierarchy (Empty, Few Seats Available, Full).

@bbafford We do something similar, but the fact that we only use three and that we believe them to have a clear scale isn't actually clear from the spec, which specifically addresses the type of passenger spaces available (standing and seated).

My understanding is that CrowdLevel is being proposed as a way to communicate a clear scale and hierarchy of passenger load -- and that essentially the way you (and we) currently map crowding data from vehicles should be transitioned to use the new scale defined here.

Then, the documentation for the existing OccupancyStatus will be clarified to ensure that producers and consumers understand it to mean something qualitative about the types of passenger space available (seats vs standing). I expect most producers don't actually have this specific information and over time would switch to using the CrowdLevel instead -- but theoretically for those who do have access to seat-level data, there is still valuable information that can be communicated by saying whether seats are available or not.

[RTL-Gilles-Ferland]

Hello,

We also think that 2 enums is not necessary. The CrowdLevel one is more interesting and we do find this proposal satisfactory.

Will this new CrowdLevel be integrated to the Occupancy.txt (#240) file with the objective of replacing the OccupancyStatus as well?

As a producer we will probably have to include both enum values for some time until all consumers have migrated from OccupancyStatus to CrowdLevel.

Thanks

[sccmcca]

@bbafford I'd like to second @stevenmwhite's comment. You can find a complete account of the discussions that led to this proposal at #223 and #212.

To summarize, this proposal was initially made in #212 as a replacement of OccupancyStatus. However, it became clear that some stakeholders were still using the current enum values of OccupancyStatus to communicate qualitative vehicle occupancy states such as "seating available" or "standing only". So forcing a breaking change by deprecating some enum values, and changing the mappings of OccupancyStatus enum values onto an ordinal scale was not likely to be a successful strategy if put to a vote. Moreover, the description of OccupancyStatus has been recently clarified in #259 to discourage interpretive mappings of qualitative OccupancyStatus values onto a linear scale.

If CrowdLevel is intended to fully replace OccupancyStatus, than we believe the proposal in #261 is satisfactory.

If the community migrates from OccupancyStatus to CrowdLevel (there is some momentum for that), then deprecating OccupancyStatus would be a serious consideration for the mid- to long-term, but not likely in the short-term as tried with #212.

@RTL-Gilles-Ferland The occupancy description that will be integrated into occupancies.txt (#240) will be the one that the community votes in as official. In fact, the reality that there is no official way to describe occupancies in GTFS is what is blocking #240 to move forward. I've made this proposal for CrowdLevel experimental for now to ease adoption for the mid-term.

As a producer we will probably have to include both enum values for some time until all consumers have migrated from OccupancyStatus to CrowdLevel.

Depending on the producers who intake your feeds, this may be a good strategy in the interim.

@bbafford @RTL-Gilles-Ferland The three occupancy descriptions co-exist by each indicating respectively true conditions. I left a note for the interaction of OccupancyStatus and CrowdLevel in the proposal:

Both OccupancyStatus and CrowdLevel may be used side-by-side, but must respectively indicate true conditions. For example, a vehicle may have FEW_SEATS_AVAILABLE and SOME_CROWDING, have STANDING_ROOM_ONLY and be CROWDED, or is NOT_ACCEPTING_PASSENGERS and is CROWDED.

The idea is that since are each distinct in describing occupancies (qualitative states, ordinal level, fine-grained ratio), and results may differ by vehicle type or context, that all can be provided but must ultimately hold up to their own statements. At the same time, all occupancy descriptions are optional. Producers can provide whichever one(s) they want.

[RTL-Gilles-Ferland]

The idea is that since are each distinct in describing occupancies (qualitative states, ordinal level, fine-grained ratio), and results may differ by vehicle type or context, that all can be provided but must ultimately hold up to their own statements. At the same time, all occupancy descriptions are optional. Producers can provide whichever one(s) they want.

Understood, but are we making things more complicated than they need to be? What's the initial business requirement? The requirement is to inform the client on the potential crowding of the next departure. It seems to us that one simple ordinal enum successfully answers that requirement.

We feel that by having 3 different optional values and giving freedom to producers we are complicating things for consumers. Consumers (like mobile app providers) will end up having to support multiple combinations of these 3 optional values to get the same end result for our clients. It seems like we are failing at having a "standard" by doing this.

[jamespfennell]

Yes unfortunately proposals like this are always biased to the benefit of producers. Producers have the luxury of picking and choosing which of the N (in this case 3) methods they want to use to transmit data; meanwhile, consumers are forced to implement each of the N methods.

Of course we need to advance the spec, but perhaps somewhat redundant additions should be tied to deprecations of other fields?

Also, the GTFS spec (both static and realtime) does support extensions. Should high specialized features like this, which will likely see little use, just be implemented as extensions?

[paulswartz]

@mbta is interested in implementing this. We would add this to our existing implementations of the larger OccupancyStatus and occupancy_percentage fields.

[stale]

This pull request has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[stale]

This pull request has been closed due to inactivity. Pull requests can always be reopened after they have been closed. See the Specification Amendment Process.

[harshverma2000]

We need to add a file for Occupancy Levels in the static feed for GTFS which defines the levels to be used by the Real-time Occupancy populating approach or technology - to be used for historic data (static) as well as 3 minutes (GTFS-RT) before riders board a train or transit vehicle.

The text file could be something like below:

occupancy_range,google_transit_occupancy_level,occupancy_level_defined_by_agency
0-25,EMPTY,NEARLY EMPTY
26-50,MANY_SEATS_AVAILABLE,NOT CROWDED
51-84,FEW_SEATS_AVAILABLE,FAIRLY CROWDED
85-100,STANDING_ROOM_ONLY,NEARLY FULL OR FULL

I believe such a file currently does not exist in static feeds. Am I correct in assuming so?

[sccmcca]

@harshverma2000 There is currently a proposal for occupancies in static at #290.

However an approach to define multiple indicators of occupancy at once as you're suggesting above has not been proposed. IMHO I think something like that would a be a bit too complicated, and contributes to the scattered conversation on a unified way to describe occupancies in GTFS (see #212, #213, #222, #223, #233, #290/#240).

I think the way forward is to build consensus for an official method of describing occupancies. The available options are:

1. OccupancyStatus
2. occupancy_percentage
3. CrowdLevel

[harshverma2000]

Thanks @scmcca - we need a way for the operator to change their occupancy indicators if they desire some time and to maintain flexibility for the designer, imho, the static text files could be the best place and simplest way to keep that info.

[barbeau]

This proposal was closed due to inactivity, but I wanted to add this comment in case it resumes.

It appears that VDV (Germany) is standardizing on a 3-level ordered occupancy enumeration - "low", "moderate", "high":
VDVde/TRIAS#14

This is similar to what is proposed in this PR.