Geography-Driven Events

[quicklywilliam]

No description provided.

[CLAassistant]

All committers have signed the CLA.

[quicklywilliam]

This is an initial attempt at implementing #480. Note that because #271 has not landed yet I had to be a bit interpretive in how to work things into the current event structure. Happy to clean things up as that issue moves to implementation.

[jfh01]

How do folks feel about trying to get this in for 1.1.0? @quicklywilliam @schnuerle @billdirks

[schnuerle]

Feel good about it for 1.1. Milestone marked.

[marie-x]

Probably want to spell out some use cases for trip_enter_geography and trip_leave_geography. E.g. if you have, say, council districts, would transitioning from one to another generate two simultaneous events (leave, enter)? Would leaving the municipal boundary potentially generate two events (trip_leave, trip_leave_geography)?

Also off the top of my head I'm not coming up with a use case for Policy enforcement where the enter/leave geography events are needed. Do you have some examples of a Policy whose enforcement requires these events once you drop the telemetry requirement?

[quicklywilliam]

@Karcass these are interesting questions. I'm wondering if there might be a way that we could unify the events, so that there's just a single trip_leave event issued (with both the jurisdiction and policy geos in event_geographies) instead of a trip_leave_jurisdiction and a trip_leave_geography.

As for uses cases, one that has came up when we started talking to cities about this was for assessing fees. For example, suppose a city wants to assess a 25 cent fee for trips entering or starting downtown during rush hour.

[marie-x]

Added some suggestions about not conflating telemetry (movement of vehicle in same state) with events (change of vehicle state).

Also we will need to be super clear on how Geographies are communicated, such that the Providers' notions of currently relevant Geographies is in sync with the regulating Agency. Geographies themselves do not have start-dates or end-dates; applicability is for Policies or Jurisdictions or Metrics to specify. Solving that problem cleanly blocks this proposal IMHO.

[schnuerle]

We reviewed this PR as part of the second OMF Working Group Steering Committee release Checkpoint. Both WGSCs had some feedback and I'm documenting it here for discussion.

Note: we definitely want to flag this as a 'beta' feature in the release, so leaving a reminder here.

We were trying to think how geographies can best be aligned to this, how do you know which geography is used for an event?

And how can this idea be addressed in the simplest way initially, with minimal changes or dependencies on other things like Jurisdictions.

Idea 1) Maybe just use all geographies and return data for all of them by default, then the city can decide which geographies are of value. As part of it being beta, recommend cities talking to providers first to provide a list of geographies it applies to.

Idea 2) There could be a new rule type in policy. One that is 'event' and you would define the geography and details there. This may be a bit duplicative, since you would also use that geography in another rule type.

Idea 3) Events could be an optional flag in policy that says that this policy needs to be treated as an event.

What do you all think of these ideas? I like Idea 3, but I'm not sure it meets all of your use cases @quicklywilliam.

[quicklywilliam]

All set! Have also updated the agenda with details of what needs to be covered.

[schnuerle]

From the Working Group call last week, here is a summary of the discussions and action items that should be done in the next week or two to make this release:

https://github.com/openmobilityfoundation/mobility-data-specification/wiki/Web-conference-notes,-2020.10.22-(Joint-Working-Group-Provider-Services)#minutes

• Rename the proposal to ‘Geography Driven Events’ (GDE) to reflect that for now the actions are triggered when vehicles enter or leave a geometry, and geometry IDs are returned.
• If you use GDEs, then cities are required to make policy and geography public and communicate the URLs to provide public transparency in the policy and geographic areas, and reduce authentication burden on providers. Add that language.
• Ensure this is structured to be a non-breaking change for 1.1.0, and so it can be tested with minimal disruptions.
• Agreed that 2 fields (enter and leave) are better than one (cross), so leave as is.
• Added note that new policies can’t be expected to be implemented until 20 minutes after publishing to prevent frequent or real time changes. 20 min delay is good for some more emergency policy situations, but most policy will be communicated days or weeks ahead of time. Ensure this is clear.
• Add the beta label and link in the appropriate place to allow cities and providers to try it out and give feedback.
• Beta designation will also also providers to see what their technical burden is to implement and run in production
• Language needed to clarify that policy driven events only apply when you opt into this and discuss with provider and city.
• Can be run in parallel with all existing MDS if desired by cities. So you can turn on GDEs and other telemetry, or turn on GDEs and turn off telemetry, or just use telemetry as it is in 1.0.0. Ensure this is clear.
• Could be issues with GPS in precision float and boundary riding, returning too many events. May need smoothing of data. Could be worth adding some language to spec to account for this.

[schnuerle]

There's about a week left to get these changes into the PR for this release @quicklywilliam. If you can do that we can save some time on the last WG call Nov 12, though that day is filling up with some other items now like Metrics and k-values, so Nov 5 may be better (though it's of course much sooner!).

[quicklywilliam]

@schnuerle I'll post an update on this shortly so that we can discuss and resolve most, if not all, of the remaining points.

[quicklywilliam]

We've now resolved the remaining issues discussed at the WG:

• mark as beta
• clarify which geometries are communicated in in the case of an enter/leave. event_geographies
• add language clarifying that event_location is required if geometries not present
• add language around events being only required for beta users
• change title to "geography driven events"
• add some overall language somewhere describing intent/purpose of "geography driven events"

[quicklywilliam]

One thing I want to call attention to is that in resolving the issues above I decided to eliminate the trip_leave_geography event in favor of a single crossed_geography_boundary. This was something we discussed at the last work group. We saw benefits to both approaches, and no strong preference emerged.

However, I came to a new conclusion in considering how to best clarify the question of which geometries are communicated with these events. The inclusion of the leave event was adding hidden complexity here. For every event type besides leave, the location given is of the vehicle in its new state – not the one it has just transitioned from. However, for a leave event it is unclear – it would seem that event_geographies should contain the geographies the vehicle just left. Removing this event resolves this ambiguity and makes the behavior of event_geographies consistent. If needed, the list of geographies left can be inferred.

As an added bonus, this change allows for greater flexibility in implementations around when a crossed_geography_boundary event occurs. This is likely to be of use during the beta period as we seek to make stronger recommendations to account for GPS inaccuracy, drift, etc.

[marie-x]

Name seems a little wordy. :)
How about changed_geographies?

[schnuerle]

William this looks great, thanks for incorporating all the feedback!

Will you be available to present on your changes at tomorrow's WG meeting? No need to do an overview of the whole GDE proposal, but just what's been updated, and the decision to merge the leave/enter geographies.

Also I noticed a few things in the PR that could be update before tomorrow. If you give me edit access (#2 here) I can make them, otherwise here they are:

• 1. 'geometry' driven events is written in a number of places. Surely just a typo, one I've made before too!
• 2. can you add DS Store back to the .gitignore for the repo?
• 3. a new request: could you add an example of GDEs in the /examples folder readme?

[schnuerle]

Looks good thanks for the changes based on community and city feedback. Will make other minor changes during release candidate preparation (eg like typos with 'telemtry' spelling).