[GTFS Fares v2] Area Set matching predicates.

[bdferris-v2]

Add support for matching "sets" of areas in fare_leg_rules.txt per this proposal.

[tzujenchanmbd]

For the intermediate stops, it seems they must be stops defined in stop_times rather than "geographical pass-through" stops. Could the current description cause misunderstandings? Would it be clearer to state this explicitly?

[bdferris-v2]

I attempted to add explicit language. Let me know what you think.

[tzujenchanmbd]

Looks good to me!

Just to confirm:

and intermediate stops as referenced by the trip's stop-time entries; belongs to the specified area as defined by [stop_areas.txt]

This means that entries will be included regardless of their pickup_type and drop_off_type values (e.g., value=1 - No pickup/drop_off available). Is this correct?

[bdferris-v2]

Yes, I suppose that's correct.

I think we discussed this briefly in the last meeting, yes? I think it's reasonable to make the default the simple case (passes through a stop).

[tzujenchanmbd]

Yes, got it. Just want to confirm if I correctly understand the semantics here (i.e. regardless of the pickup_type and drop_off_type values).

[halbertram]

Whilst we are far along in this proposal, I recently had the following thought. It may be overly pedantic (and doesn't come with a proposed solution), but it might be worth discussing.

There seems to be a bit of a variation between how eg areas are formed from stops, and how area sets are formed from areas.

Stops and areas / Routes and networks

• <element>s.txt – element data
• <collection>s.txt – collection data such as name
• <element>_<collection>s.txt – insertion into collection

Areas and area sets

area_sets.txt defines the collections and the insertion. It's not clear where any fields that an area set might gain down the line would go.

If we view the collection as 'set', then it does partially follow the above scheme, but that will cause issues once we have network sets, and sets.txt would be ambiguous.

However having area_sets.txt and area_area_sets.txt doesn't seem sensible. We could find a name for an area set (in the way that we call a 'stop set' an area), possibly 'region' – but may be hard to find a word that would be appropriate in all uses of area sets. (Also would eventually have to find one for the corresponding network and trip_group cases). Or further area set level fields could go in area_set_details.txt.

[tzujenchanmbd]

It seems reasonable to separate collections and insertions into collections into two files, which is consistent with the existing three cases (networks.txt + route_networks.txt, areas.txt + stop_areas.txt, location_groups.txt + location_group_stops.txt), and it seems like a normalized relational model.

[bdferris-v2]

Did we talk about this briefly in the Fares v2 meeting last week? Or did I just imagine talking about this? :)

Agreed that the naming is awkward here. A couple options:

1. We just keep area_sets.txt as-is. It's not clear what properties of an area set that we'd actually add (beyond a name?) and if we did need to add something after the fact, then I agree that area_set_properties.txt or area_set_details.txt could possibly work.
2. That said, I do acknowledge that this does deviate slightly from the pattern. If we really wanted to stick to the pattern, then I guess I'd actually suggest area_set_areas.txt for the collection file to map an area to an area set. A little clearer on what it means than area_area_sets.txt I think? But if we went with this option, would we want to then make area_sets.txt the element file now (and require an entry for each area set), even if we don't have meaningful fields to associate with it?

[tzujenchanmbd]

Last week I mentioned that Hal raised this question, but it seems we didn’t dive into the discussion. :)

Currently, all similar files (e.g., areas.txt, networks.txt) only include a unique ID field and a name field. We could probably follow this pattern for now? and if additional properties are needed in the future, they can be added directly to the file.

Regarding naming, area_set_areas.txt does seem clearer than area_area_sets.txt to me.

How does this look?

area_set_areas.txt: The file maps area to area set, with the following fields:

• area_set_id (foreign ID referencing area_sets.area_set_id, required)
• area_id (foreign ID referencing areas.area_id, required)

area_sets.txt: The file defining area sets, with the following fields:

• area_set_id (unique ID, required)
• area_set_name (optional)

[github-actions]

This pull request has been automatically marked as stale because of lack of recent activity. It may be closed manually after one month of inactivity. Thank you for your contributions.

[bdferris-v2]

(Apologies, not many cycles to think about Fares v2 these days)

Reflecting on this proposal and the Trip Groups proposal, I wanted to propose an alternate file naming scheme for sets:

• [entity]_sets.txt - defines sets containing the specified entity type
• [entity]_set_elements.txt - defines the elements of the set of the specified entity type

So then we'd have:

• area_sets.txt and area_set_elements.txt
• network_sets.txt and network_set_elements.txt
• trip_sets.txt and trip_set_elements.txt` - (I know the proposal was trip groups, but maybe this would be better?)
• ... and so on for future types

@halbertram thoughts?

[halbertram]

I think that makes sense given the various options.

[felixguendling]

I've implemented support for this feature in MOTIS (released in v2.0.71).
motis-project/nigiri@d32d816

Maybe it's obvious for others but it could help to explicitly state how to deal with stops that are assigned to more than one area (stop_areas.txt has primary key * which means a stop can be part of several areas).

I implemented it like this:

• check if all areas from an area set are visited: go through all areas and search for at least one stop that is assigned to this area (including all areas a stop is assigned to)
• check if no extra areas are covered: go through each stop of the effective fare leg and check that all areas the stop is assigned to are part of the area set

[github-actions]

This pull request has been automatically marked as stale because of lack of recent activity. It may be closed manually after one month of inactivity. Thank you for your contributions.

[tzujenchanmbd]

not stale

[tzujenchanmbd]

Suggestions to add area_set_elements.txt, to align with the conclusions from comments above and previous working group discussions.

[tzujenchanmbd]

Suggested change

| `area_id` | Foreign ID referencing `areas.area_id` | **Required** | Identifies an area to be included in the set. The same `area_id` may be defined in multiple area sets. |

[skalexch]

The name also needs to be added.
| `area_set_name` | Text | **Required** | The name of the area set. |

[tzujenchanmbd]

Suggested change

	Primary key (`*`)
	Primary key (`area_set_id`)

[tzujenchanmbd]

Suggested change

	### area_set_elements.txt
	File: **Optional**
	Primary key (`*`)
	Groups collections of areas into sets.
	| Field Name | Type | Presence | Description |
	| ------ | ------ | ------ | ------ |
	| `area_set_id` | Foreign ID referencing `area_sets.area_set_id` | **Required** | Identifies an area set to which one or multiple `area_id`s belong. |
	| `area_id` | Foreign ID referencing `areas.area_id` | **Required** | Identifies an area to be included in the set. The same `area_id` may be defined in multiple area sets. |

[tzujenchanmbd]

Suggested change

	Groups collections of areas into sets.
	Defines area set identifiers that apply for fare leg rules.

[tzujenchanmbd]

Suggested change

	| [area_sets.txt](#area_setstxt) | Optional | Collections of areas. |
	| [area_sets.txt](#area_setstxt) | Optional | Collections of areas. |
	| [area_set_elements.txt](#area_set_elementstxt) | Optional | Rules to assign areas to area sets. |

[tzujenchanmbd]

Suggested change

	- [area_sets.txt](#area_setstxt)
	- [area_sets.txt](#area_setstxt)
	- [area_set_elements.txt](#area_set_elementstxt)

[skalexch]

@tzujenchanmbd should there also be rules of how contains_exactly_area_set_id and contains_area_set_id interact with from_area_id and to_area_id?
We resolved this in the Network Sets PR by forbidding the network_id predicate when the set predicates exist. We can do the same here.

Also, if contains_area_set_id and contains_exactly_area_set_id both exist, contains_area_set_id would have to be included in contains_exactly_area_set_id, causing a redundancy. If not, the leg rule will never be matched. Should we do the same thing we did for network sets and make them mutually exclusive as well?

[tzujenchanmbd]

should there also be rules of how contains_exactly_area_set_id and contains_area_set_id interact with from_area_id and to_area_id?

@skalexch I think the from_area_id / to_area_id case is different from network_id?
The network_id predicate matches a single network, which is logically at odds with a network_set that represents multiple networks within the same leg rule. In contrast, from_area_id and to_area_id describe the origin and destination areas of a leg. Producers may want to define different fares for different origin–destination pairs within the same area_set (e.g., A→D vs. A→C within area set ABCD), especially when fare_leg_join_rule is used. Allowing them to be used together should provide more flexibility?

Also, if contains_area_set_id and contains_exactly_area_set_id both exist,

Agree that the interaction between contains_area_set_id and contains_exactly_area_set_id is similar to the network set case and that they should be mutually exclusive. I’ll update the suggestions accordingly.

[skalexch]

@tzujenchanmbd 100% agree. Let's keep the intersection with from_area_id / to_area_id but enforce mutual exclusivity between contains_area_set_id and contains_exactly_area_set_id.

[isabelle-dr]

Should these be added as a primary key to this file?