One AI Commute Time Augmentation Guide with Video

The commute time augmentation "augments" your data in One Model with commute times and distances between home and office locations. This data is obtained by sending zip code pairs (employee home and office locations) to the mapquest API and returning time and distance for both the AM and PM commute. As your data (zip code pairs) will be shared outside of the One Model platform, please consult your internal stakeholders before proceeding.

Jump to the Video - Commute Time Augmentation Guide

Pre-work

The first step in creating a commute time augmentation is preparing the necessary data.

A data destination of type "One AI" that generates a single file must be created. 

  1. From the Data menu on the top navigation bar, select Destinations
  2. Click Add Data Destination and select One AI from the dropdown
  3. Assign a Display Name such as "Commute Time" and Save
  4. Select the + icon on the row for the destination you just created and select Query Source
  5. Assign a file name and click Save and Explore Query 
  6. Create an Explore query that follows these guidelines:
    1. Must contain a headcount metric and time selection
      1. Headcount (EOP) is the most commonly selected headcount metric
      2. Today is the most commonly selected time selection
      3. You can apply whatever filters you desire
    2. a unique person identifier - person_id in the image above
    3. a date formatted as a date - we recommend you use one.timeperiods.date column as shown in the image
    4. a home zip code - home_zip_code in the image above
    5. an office zip code - work_zip_code in the image above
  7. Click the Run query button if you have not
  8. Hover over the pin icon above the table and select Update Data Destination Query
  9. From the Data menu on the top navigation bar, select Destinations again
  10. Run the data destination by clicking the Run Data Destination icon (Play symbol) on the row for the destination you just created
  11. Validate that the destination ran successfully by clicking the View Data Destination History icon on the row for the destination you just created

Configuration

Select One AI from the top navigation bar.

NavBar.png
Click the “Add Data Augmentation” button to prompt a new augmentation.

Enter a name into the Display Name field and then select “Commute Time” from the dropdown menu under “Augmentation Type.”

Select the appropriate data destination from the “Select Data Destination” dropdown menu. This should be the destination you created in your pre-work step.

Once you have selected the appropriate data destination, click “Refresh data from selected data destination” to ensure that the data destination is up to date.

Once these steps are completed, the following configuration options should be displayed:

The following selections should be associated with the corresponding column from the data destination:

  • Person ID

  • Employee Zip Code

  • Office Zip Code

  • Sample Date

Country, Arrive By, Leave At, and Distance Units are optional. If nothing is selected for these options, the following defaults will be used:

  • Country: United States of America (US)

  • Arrive By: 09:00

  • Leave at: 17:00

  • Distance Units: Miles

Although there is not a control for it, a custom date can also be passed by selecting "Show YAML Template" and entering the following, replacing the MM/DD/YYYY with a valid date. By default, today's date is used.

traffic_date: "MM/DD/YYYY"

Once you have filled in your configurations, click the “Create” button at the bottom of the Add Augmentation screen.

Run and Review

Now that the augmentation has been created, find it in the Augmentations list and click “Run” to kick off a run that will return the commute data.

Click “Runs” to see the status of the run. Depending on the volume of data, it can take some time to run. When it is complete, you will see an orange “Pending” bar. Select the Pending bar to inspect the results.

Select the “Results Explorer” tab to review the results.

 

The columns returned are as follows:

  • person_id - the employee identifier you configured

  • arrive_by_commute_time_seconds - the AM commute time in seconds

  • leave_at_commute_time_seconds - the PM commute time in seconds

  • arrive_by_commute_time_formatted - the AM commute time formatted as time

  • leave_at_commute_time_formatted - the AM commute time formatted as time

  • arrive_by_distance - the AM distance of the route in miles

  • leave_at_distance - the PM distance of the route in miles

  • sample_date - the sample date you configured

  • aug_name - the name of the augmentation

  • aug_id - the ID of the augmentation run

Note that there is a row in the screen shot that displays "API call" errors. If invalid zip code combinations are passed or if zip codes are incorrectly formatted, you will receive these errors.

Deploy and Model

If the data in the Results Explorer looks sensible and you would like to leverage it in One Model, the results should be deployed from the "Results Explorer" tab by selecting the blue “Deploy” button in the bottom right corner. 

Doing so loads the data into a data source where it can be accessed by your processing script. Next, please reach out to your Customer Success Lead to arrange for a One Model Data Engineer to model it for use in Explore and Storyboards. Once they have built the appropriate tables and dimensions, you can build metrics and present this data on Storyboards. Remember, your One Model data must reprocess before deployed results will be available for use in Explore or Storyboards. Please plan accordingly.

Rerun and Deploy an Existing Augmentation

In order to rerun and deploy an existing commute time augmentation, follow these steps:

  1. Find the commute time augmentation in the Augmentations list and click Edit.
  2. If you want to use refreshed data, click the "Refresh data from selected data destination" button. You can see how long it’s been since the selected data destination was last run here as well. You can also run the data destination from Data > Destinations if you prefer.

  1. Once the refresh is complete (should only take a few minutes), check that the configuration still looks correct. If so, scroll to the bottom of the screen and click Save
  2. Click Run and Agree and Confirm after reading the warning if you are comfortable. 
  3. Click Runs. Once the augmentation has finished running, it will have a yellow 'Pending’ label. Click it. 
  4. View the results in the "Results Explorer" tab. If everything looks good, click Deploy in the bottom right corner. 
  5. Once your One Model site refreshes, this data will be available for use in Explore and Storyboards.

Technical Notes

The commute time augmentation leverages the Mapquest Directions API. Documentation about this API can be found at the following links:

The commute time augmentation pulls “time” and “distance” at both the “arrive by” and “leave at” times.

Note: Data is sent and received at a zip code to zip code level, not a per employee level. Person identifier is not sent to Mapquest. The mapping from person to zip codes is performed on the One Model end.

Values passed to the API are as follows:

 

Mapquest Parameter

Value

dateType

0 (Specific Date & Time)

useTraffic

True

timeType

Arrive By is 3 and Leave At is 2

to

Office Zip Code

from

Employee Zip Code

country

Country or defaults to US if not specified

date

defaults to today unless overridden in YAML

 

Video - Commute Time Augmentation Guide

This video walks you through the steps to create a One AI Commute Time Augmentation on your One Model site. 

You will learn:

  • How to configure and run the necessary data destination 
  • How to configure and run the Commute Time Augmentation step by step
  • Where and how to review your Commute Time Augmentation results
  • How to deploy this data and model onto a storyboard or use in Explore

Run time: >17 minutes

Was this article helpful?

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.