[Data] Annotated Data: Create a Shuttle class

[0-Rick]

This is the third issue of a series. #41 is the corresponding frontend change; #59 is the old JSON format.

In the future, to make some of this code clearer, we're gonna want to create a data/shuttle.py file that creates a Shuttle class, similar to the Shuttle in testing.
Then we'll want to refactor this code to instantiate the Shuttle class and store a list of Shuttle instances for the day. It can still iterate through the location data, but rather than manually modifying the schema, each shuttle should have the following methods:

• add_break_location(timestamp)
• add_loop_location(timestamp)
• change_state(new_state)
• is_stopped()
• ...
  Then, we can replace the manual modification using the schema's format with calls to methods, which should clean up the code significantly.
  Lastly, before returning the response, we'll need to serialize the Shuttle instances (convert them into JSON). For this, define a to_json() method, that converts the instance to the JSON schema we use.

Originally posted by @jmccand in #255 (comment)

The Shuttle Class will be used in the data_today() function in server/routes.py . The outputted JSON Format of this function is as follows:

{
    "shuttleID1": {
        "locations": {
            "16:25:53": {
                "at_stop": null,
                "closest_polyline": 1,
                "closest_route": "NORTH",
                "closest_route_location": [42.7379143365656, -73.6675641148277],
                "distance": 0.0100496703554305,
                "latitude": 42.7380042100651,
                "longitude": -73.6675511200586,
                "status": "loop"
            },
            "16:26:01": { ... },
            "16:26:08": { ... }
            // ...
        },
        "breaks": [
            {
                "locations": [
                    "16:28:08",     /* break start time */
                    "16:28:16",
                    "16:28:23",
                    "16:28:30",
                    "16:28:37"      /* break end time */
                ]
            },
            {
                "locations": [ ... ]
            }
        ],
        "loops": [
            {
                "locations": [
                    "16:25:53",     /* loop start time */
                    "16:26:01",
                    "16:26:08",
                    "16:26:15",
                    "16:26:22"      /* loop end time */
                ]
            },
            {
                "locations": [ ... ]
            }
        ]
    },
    "shuttleID2": { ... },
    "shuttleID3": { ... }
    // ...
}

[0-Rick]

Detailed Explaination:

There are three main nests in the JSON format: locations, breaks, and loops:

• In locations, the shuttle's location is used to determine different information (e.g: at_stop, closest_route). This is fairly straightforward, and is performed using calls to server\stops.py.
• In breaks and loops, the shuttle is determined to be in either of those states at any given location. To determine this, shuttle are given a range of statuses which is displayed as a tag under locations.

The Statuses are added under the locations, with the following types:

• break is for the shuttle waiting in the Union.
• loop is for the shuttle carrying students along the West or North routes. Loops start and end at the Student Union.
• entry is the initial case of the shuttle entering campus. It has to arrive at the Student Union first before picking up students.
• idle is for shuttles that have stopped moving for five minutes.
• off route are for shuttles that are quite far off-route.

We may want to rename the break and loop statuses due to ambiguity (e.g: pickup and on route instead). The following mapping is from the status --> JSON's breaks and loops nests:

• break, entry, idle, and off route --> breaks
• loop --> loops

Additionally, the statuss should use an Enum, as written below:

I like the strings! What would make the code even cleaner would be to create an enum, which is an object that can take a fixed set of values.
i.e.

class ShuttleState(Enum):
    ENTRY = 1
    BREAK = 2
    LOOP = 3

and reference: state = ShuttleState.ENTRY if state is ShuttleState.ENTRY:

Originally posted by @jmccand in #255 (comment)

Shuttle Class

On top of what Joel mentioned (in the quote above), the Shuttle Class would be the most ideal as we can reduce overhead. Here are some quirks about implementing this class:

• We will need a Shuttle Class Manager, to hold all of the Shuttle instances. The thresholds/constants and helper data will be stored in this Class Manager.
• Previously, we would filter all the data of the current day. Instead, we can filter using vehicle_id and its most recent timestamp to fetch only the most recent data.
  • Databases are not perfect -- due to maintenance or other problems, we may lose the data saved in the Shuttle Class. To solve this, check the previous location/timestamp for a shuttle as usual, and if its missing, then recompute the nests by filtering for the entire day.

Future Work

There is also potential in implementing a cache or derived cache in some way, but the frontend change should come first.