Overview

If your school district uses Here Comes the Bus and your notification rules include email, then you can use this code to analyze the data from Stop Radius Entry and Bus Substitution notification events.

Usage

Pipe your mbox formatted email box to main.js to run the analysis. The example below enables you to test with a trivially small sample mail box.

$ cat sample/sample.mbox | node main.js

Results stored in ./2021-10-29-statistics.json
In person school days: 52
Total expected bus radius notification: 104
Total bus radius notifications received: 3
Total bus substitution notifications received: 1
Total notifications received: 4
Efficacy of radius notifications: 2.88 %

Example Chart.js based charts are included in sample/index.html to visualize the data.

Please review the configuration options as manual configuration will be required to match your specific scenario.

Configuration Options

There are several configuration files in the config/ directory. Updates are required as the default configuration will not match your situation.

Here Comes The Bus App

Email notifications must be enabled in the app to provide the data for analysis. Follow these steps to ensure your notifications are properly configured.

1. Open the application
2. Select Notifications
3. Select Edit Notification Radius
4. Select the desired bus rider's name.
5. Select the desired AM stop.
6. Drag the slider to set the desired notification radius.
7. Select Save to save the notification radius.
8. Select the desired PM stop.
9. Drag the slider to set the desired notification radius.
10. Select Save to save the notification radius.
11. Select Edit Notification Rules.
12. Select the desired bus rider's name.
13. Select the Notification settings for Stop Radius Entry.
14. Select Email.
15. Ensure that your desired email address has a check box next to it.

Note that notifications are sent when the bus enters the circle- not when the bus arrives at the bus stop. A smaller radius will result in notifications being sent closer to bus stop arrival time than a larger radius.

Bus Rider

Specifics for your bus rider are specified in config/rider.json.

You must configure the morning and afternoon scheduled arrival times by setting amScheduledArrivalTime and pmScheduledArrivalTime to your schedule following a 'HH:mm:ss EDT' format.

If you receive notifications for more than one bus rider you may want to filter on the rider's first or last name, which can be accomplished by configuring filterFirstName and filterLastName. By default these are set to false and filtering is disabled. Note that if names are specified all letters must be capitalized to match the notification.

Calendar

The config/calendar.js file is currently configured for the Atlanta Public Schools 2021-2022 school year. If your data is from a school with a different calendar, then update this file and export the list of in person school days as inPersonSchoolDayList.

Regular Expressions

Regular expressions specified in config/regex.js are used to match and extract notification data from your email.

• The regexRadius variable captures a Stop Radius Entry notification event.
• The regexSubstitute variable captures a Bus Substitution notification event.
• At this time Stop Radius Exit notification events are not supported.

These regular expressions should not need to be modified.

The regexRadius capture groups are as follows:

• Group 0 - Original Line
• Group 1 - Bus Number
• Group 2 - First Name
• Group 3 - Last Name
• Group 4 - DateTime

The regexSubstitute capture groups are as follows:

• Group 0 - Original Line
• Group 1 - Normal Bus Number
• Group 2 - Replacement Bus Number

Mailbox Data

Refer to RFC 4155 for more information on the mbox file format. Here are a few hints to get you started.

• Gmail users can use Google Takeout to export emails with a specific tag in the mbox file format.
• Mail on Mac users can export mbox format directly.
• Outlook users can manually convert a .pst to .mbox file.

For maximum performance, create a filter to ensure that only Here Comes The Bus notification emails are in your mbox.

Analytics

This code is designed to help assess the overall efficacy of the Here Comes The Bus application. Efficacy is impacted many factors including how the local school district operates the system.

This analysis uses the Stop Radius Entry event as a proxy for bus stop arrival time and is far from exact.

Results Summary

The tool prints a summary of results to the command line.

In person school days: 52
Total expected bus radius notification: 104
Total bus radius notifications received: 49
Total bus substitution notifications received: 2
Total notifications received: 51
Efficacy of radius notifications: 47.1 %

The tool saves the extracted notification events in ./YYYY-MM-DD-statistics.json if deeper analysis is desired.

Results Visualization

Sample data is included in sample/statistics.json and is used as the basis for the visualizations in sample/index.html.

Time Series Chart

The included visualizations show a time series chart with time on the X axis and differences from scheduled arrival on the Y axis.

Colors are used to differentiate between AM and PM Stop Radius Entry notifications and the delta between scheduled arrival and the time of the Stop Radius Entry sent is also displayed if you click on one of the circles.

Early arrival is indicated by negative numbers. Late arrival is indicated by positive numbers.

Bus Substitution notifications are plotted with a value of '0' on the Y axis.

This chart also depicts when a notification was not received as 'No Notification Sent'. When no notification is sent for the AM route, the Y value is set to -15. When no notification is sent for the PM route, the Y value is set to +15. These Y value settings were chosen to make it easier to see missing notifications.

Notional Findings

This time series visualization leads to additional lines of inquiry.

Slow Start

This time series visualization illustrates that it took the local school system two and half weeks before the initial notification events were sent. In the future, I would hope the system could be configured to work on the first day of school.

Very Unreliable

The time series visualization shows a large number of school days where no notification was sent. The pie chart confirms that 50% fewer notifications were sent than expected. This indicates that the overall system is unreliable more often than not.

Possible explanations for bad reliability include:

• Problems with the Here Comes The Bus platform
• When replacement buses are used, the local school system does not update the Here Comes The Bus platform
  • The local school system is not properly trained to use the system
  • The local school system is trained to use the system, but purposely do not use it in order to mask poor on time performance
• Any number of other reasons including solar flares

Efficacy Pie Chart

This simple pie chart is used to show how often Stop Radius Entry events are sent compared with how many were expected.

The sample/statistics.json data shows only 47% of the expected notifications were received.

Note that sample/sample.mbox was not used to generate sample/statistics.json and that these represent different datasets.