Methodology to calculate raw Metrics numbers

[schnuerle]

In order to get to Metrics, we need to define and specify the limits of measuring curb activity and usage for differing data sources and scenarios.

After events come in from the Events API and are stored, how do those then get reconciled into curb activity like event counts, counts over times, dwell time, duration, and usage percents?

Events can be from on/off sensors, or camera devices, in person recording, fleet data feeds, etc, each collecting different data or not knowing other data (eg, vehicle type, vehicle length, unused curb linear feet). How do you count events, aggregate events, and overlapping events from different sensors or sources?

Is it ok to caveat the Metrics as sampling, off model, or representative data, vs being a 100% accurate view of the curb at all times?

After defining use cases we can ensure this methodology helps meet them.

Current Metrics could include (see draft document):

1. Total Events
2. Turnover
3. Average Dwell Time
4. Occupancy Percent
5. Curb Productivity Index

[jacobmalleau]

Curious to know how others have typically calculated turnover. I have often seen it divided by the number of spaces for the zone being looked at. See here:
https://www.civil.iitb.ac.in/tvm/1100_LnTse/535_lnTse/plain/plain.html

[schnuerle]

Regarding turnover, from the link above:

It is the ratio of number of vehicles parked in a duration to the number of parking bays available.
    parking turnover= parking volume/No. of bays available
This can be expressed as number of vehicles per bay per time duration.

Which is saying vehicles per space/time

In our draft we have a more simple

    count[events]/hour 
Used together with Average Dwell Time by cities to understand how long vehicles are parked at the curb. 
When evaluated alongside a vehicle type breakdown, cities can see if the curb space is being used as intended 
and design better rules for compliance.

For CDS we have events, which could be a space for one vehicle, or the use of a curb area that is unmarked. So I feel these two boil down to the same thing. Though we are specifying the time unit of hour.

[bhamlinSDOT]

I think we are leaning towards caveating that Metrics (and Events for that matter) are a sampling of data and that they are not a 100% inclusive depiction of all the curbside events. Parking studies, enforcement records, sensor data, cameras, etc. will all exist in separate "event" silos and I think as long as the required information is provided, then the Metrics can be calculated using our methodology. For example, if you want to calculate Metrics using enforcement data, you won't be able to produce all of the proposed Metrics because you won't have all of the required information. (maybe you could do total events for a particular time period but enforcement and parking studies are often just a snap shot in time and not check in/check out) Using your sensor data though, you will be able to calculate all of the Metrics. but it will be challenging to combine the two together.

That said, if we have common units of measurements, an end user could pull metrics from the 2 different "silo's" and do further analysis beyond the scope of V1 of CDS.

[schnuerle]

Added a new "Representative Sample Data" section in Metrics to start putting guardrails on how the methodology can be calculated across sources.

https://github.com/openmobilityfoundation/curb-data-specification/blob/feature-release-work-1/metrics/README.md#representative-sample-data

[schnuerle]

We still need some work on now to take Events from the different source types and get them into some of the metrics, like Average Dwell Time and therefore Occupancy Percent.

https://github.com/openmobilityfoundation/curb-data-specification/tree/feature-release-work-1/metrics#methodology

[schnuerle]

This is now sussed out with the reworking of /activity to /session. All of these can be calculated now using /session data.

Added a sentence to point this out here:
https://github.com/openmobilityfoundation/curb-data-specification/blob/feature-release-work-1/metrics/README.md#methodology

[schnuerle]

We may want to consider a third endpoint (or maybe as a replacement for /metrics/activities) called /metrics/sessions (or possibly /metrics/transactions, though there is likely no monetary transaction taking place) that is a conceptual level between /activities and /aggregates, that uses /events/event data to calculate a vehicle's "session" at the curb, i.e. its curb usage. Would include only start and end times of a defined session of a curb user.

We need something like this to determine occupancy in curb places for our Metrics.

[schnuerle]

If we think about how Events will be used, we want them to come in as they happen in CDS. So when a vehicle pulls up and stops to occupy a curb space, a park_start Event would be sent. Then later when it leaves a park_end Event is sent.

This allows cities to track real-time occupancy (if the can and want to). We wouldn't want data to come through only when a session is over.

But as long as a session_id is created at the start, and the same ID is used later at the end, then that would be ok.

But we wouldn't want to require session_id of course, and I image most data sources might not be able to provide a session_id at the start and end of a session? So there would still have to be manual work done like you mention when there is no session_id.

Having said all that, I'm inclined to add it as optional with some guidance about ensuring it is provided and consistent with park_start and park_end events.

[jacobmalleau]

Agree with having it optional and ensuring it is consistent with park_start and park_end events!
My one counter point to the instance you gave above is that if you are dealing with transaction/app payment data, you actually don't know when the user has left a curb space. They may pay for an hour (and in turn you would get the park_start time, duration, and associated park_end time at the start of the session) but you wouldn't know if they stayed the full hour, or left before or after their time is up.

[schnuerle]

I would say in that case you would 1) not use session_id and only record a park_start or 2) use session_id and set the park_end to the maximum time and if you can set park_end to when a new vehicle is using the space and they begin a park_start.

I think session_id should only be used when you know or can guess at the park start and end values, otherwise don't use session_id.

It makes me wonder though about adding a field like 'event_expected_duration' so that on park_start events a company can specify the expected duration of a stay, eg 1 hour for a meter or a fleet can estimate a 15 min stay and send that. It seems like useful info to know, where you could look at historically, or when you don't get a park end event, or if you are supporting realtime availability you could publish expected leaving info.

[schnuerle]

I'll try and add session_id by tomorrow's meeting so we can discuss at WG. Any other thoughts on this or the duration field?

[schnuerle]

I've added event_session_id to the Curbs Event and Metrics Session where applicable, with guidance. Please review and let me know if you have suggested changes.

For the event_expected_duration we may not add this based on the responses so far from the Working Group - it doesn't seem to be too valuable at this time.

[schnuerle]

Added an optional session_id that can be provided connect multiple event records into a cohesive session later for Metrics API endpoints.

https://github.com/openmobilityfoundation/curb-data-specification/blob/feature-release-work-1/events/README.md#curb-event

[schnuerle]

Ok removed this in favor of calculating it later in the Metrics /session area.

[schnuerle]

I wonder if in the 'events' as defined in the Metrics Methodology really means 'session' and the wording is borrowed from the source of these metrics, and not aligning to the CDS language used.

Eg,
Total Events
count[events] for a specific time period
Name: total_events

should really be:

Total Sessions
count[sessions] for a specific time period
Name: total_sessions

Eliot Mueting may be able to answer this.

[jean-populus]

Yes, so by event we mean parking session.

[schnuerle]

Thank you @jean-populus.

I've renamed total_events to total_sessions across Metrics and added a quick definition of what a session is:
https://github.com/openmobilityfoundation/curb-data-specification/blob/feature-release-work-1/metrics/README.md#total-sessions