[Policy API] support vehicle distribution by %

[jean-populus]

Is your feature request related to a problem? Please describe.

Many cities have policies where the vehicle distribution is based on a % of the total vehicles. This is a policy found in cities like Chicago, Portland, and Oakland among others. However, I don't see a way to clearly convey this concept using the Policy API where the my options for rule_type are: count, type, speed, rate, user.

Describe the solution you'd like

Is this a breaking change

• I'm not sure

Impacted Spec

• policy

Describe alternatives you've considered

Additional context

[jean-populus]

Example Meg Young (Baltimore) presented during the working group meeting today -

in writing - in the morning hours we check for 5-25% of vehicles in each zone. We retrospectively check for compliance to this twice a month. We also check for overconcentration throughout the day, if there are more than 35% of vehicles we try to send an immediate message to rebalance.

[marie-x]

This is an example of where you could use value_url. We'd need to add a new count-rule unit pct. You would write one rule per zone, specifying the geography of the zone, or a single rule to get the max across all zones and another to get the min across all zones. Each rule would include a value_url that would return whatever measurement you want. You'd have to host the service that performs that calculation of course.

Would you like a concrete example of a count rule with a value_url?

How many zones are in Baltimore?

Using value_url raises some auditability issues if you're going to get into fees or fines or other punishments, but I believe we can work through those.

[schnuerle]

Notes from the working group meeting discussions.

• Many cities don't have exact number requirements, but a percentage of total fleet. This is difficult because the number of vehicles fluctuates day to day.
• Cities approach this in different ways such as total number from previous day, mean deployment
• Options
  • Define a way to calculate metric and percentage
  • Leave room for free form text and don't aim for exact precision
  • Focus on what can be directly measured with MDS, but not necessarily the entire universe of a city's policy
  • Is there value in a freeform text field to at least describe/add context to a policy? Metric description.
• Meg Baltimore uses % metric - measure in morning 6-9am, up to 35% then redistribute in afternoon before rush hour
• How to define a metric so it’s readable in policy
• Sometimes the details are unclear based on permit language
• Maybe pick a time window, any time in there if the provider meets it
• Could this be tied to direct measurements and metrics - create a definition/description/formula in Metrics and reference in Policy?

@Karcass Can you create a concrete example of how you could do this with Policy now?

[schnuerle]

@Karcass @avatarneil Could you all add an example of how it may be possible to do this with Policy now? And if it's not possible, an idea of what it would take to support this?

The Metrics methodology may also benefit from a standard way to calculate this.

[jean-populus]

Posting an update from presentation MDS Policy Extensions 15 July 2021

• Another example of where a Metric-based Rule would provide a huge amount of flexibility and shift defining “distribution” out of Policy
• Proposal: 1.2 or later

[jean-populus]

So how we adapted MDS at Populus for this use case is that we have:

• rule_name=Distribution
• rule_type=count
• rule_units=percent_of_deployed_devices

The rule_name is selected from a predefined list of policy types. We assume that everyone who uses our platform knows what Distribution means and how Populus is calculating those numbers. So we don't define "Distribution" or ask for clarification on a count method. FYI we've never received requests to calculate distribution in a different way.

Note: Having a predefined list of rule types where there was shared understanding of concepts was a key requirement for the cities we work with. They needed the policies to be categorizable and human-readable. Some of these policy types are more narrowly defined than others. For example, we have a "Vehicle Cap" rule type but cities still need to specify the count_method using the SAE definitions. But for "Distribution" rule type the count_method is inherent to the rule.

Upon further consideration, just expanding rule_units to include "percentage" is not enough as it's unclear the way Policy API is currently written what the % is of. Looks like the solution could include a combination of Metric-based rule plus more fields around count method.

We're okay with keeping this as-is at Populus while the larger MDS community figures out how to move forward.

[jrheard]

We use an extremely similar approach at RR, re: a count rule with a new rule unit enum value - I went with percentage_of_deployed_vehicles, but it's basically the exact same thing :)