Quick Start

The itinerum-tripkit library provides simple interfaces to load .csv data into a local SQLite database and providing Python class objects (such as tripkit.models.User and tripkit.models.Trip) to represent this data for processing and inferring metadata.

Load Data

To initilize the libary, a configuration object is expected (see Generating the Configuration).

First, input .csv data be loaded to the itinerum-tripkit cache database:

from tripkit import TripKit
import tripkit_config

tripkit = TripKit(config=tripkit_config)
tripkit.setup()

After data has been loaded to the database, survey participants or users can be loaded as a list of tripkit.models.User objects:

users = tripkit.load_users()
for user in users:
    print(len(user.coordinates))

Note: On first run, .csv data will be imported if the table user_survey_responses does not exist in the cache database. To delete the cache, the temporary files can be deleted between runs.

Run Trip Detection on a User

Instead of running trip detection on the whole survey, it is possible to focus on a single user in detail. For writing new processing libraries, this is often an essential first step.

user = tripkit.load_users(uuid='00000000-0000-0000-0000-000000000000')
params = {
    'load_subway_entrances': tripkit.database.load_subway_entrances(),
    'break_interval_seconds': tripkit_config.TRIP_DETECTION_BREAK_INTERVAL_SECONDS,
    'subway_buffer_meters': tripkit_config.TRIP_DETECTION_SUBWAY_BUFFER_METERS,
    'cold_start_distance': tripkit_config.TRIP_DETECTION_COLD_START_DISTANCE_METERS,
    'accuracy_cutoff_meters': tripkit_config.TRIP_DETECTION_ACCURACY_CUTOFF_METERS
}
trips = tripkit.process.trip_detection.triplab.algorithm.run(user.coordinates,
                                                              parameters=params)

Run Complete Days Summaries on a User

When trips have been detected for a user, the complete days summary process can be run on individual users. This will check to see if a day is “complete” (contains no missing trips), “incomplete”, or “inactive”. There are additional rules to consider days as “complete” if there is an inactive day between two complete days; it is recommended to review the process source code.

user = tripkit.load_users(uuid='00000000-0000-0000-0000-000000000000')
trip_day_summaries = tripkit.process.complete_days.triplab.counter.run(user.trips,
                                                                        tripkit_config.TIMEZONE)
tripkit.database.save_trip_day_summaries(user, trip_day_summaries, tripkit_config.TIMEZONE)

Run Semantic Location Activity Detection on a User

If common user locations are available within survey responses or supplied separately (such as from the outputs of a clustering process), dwell times from nearby GPS points can be tallied. Note: the Coordinate model is currently created on-the-fly as demonstrated, but this should soon be available as an included library class-object.

Coordinate = namedtuple('Coordinate', ['latitude', 'longitude'])
user = tripkit.load_users(uuid='00000000-0000-0000-0000-000000000000')
locations = {
    'home': Coordinate(latitude=45.5, longitude=-73.5)
}
tripkit.io.write_activity_locations_geojson(tripkit_config, fn_base=user.uuid, locations=locations)
summary = tripkit.process.activities.triplab.detect.run(
    user, locations, proximity_m=tripkit_config.ACTIVITY_LOCATION_PROXIMITY_METERS, timezone=tripkit_config.TIMEZONE)
dwell_time_summaries = [summary]  # usually, multiple users would be summarized for output
tripkit.io.write_user_summaries_csv(tripkit_config, dwell_time_summaries)

Run OSRM Map Matching on a Trip

If an OSRM server is available, map matching queries can be passed to the API and the response saved to a GIS-friendly format (.geojson or .gpkg). The API query is limited by URL length, so map matching should be done for a single trip and especially long trips may have to be supplied in chunks.

user = tripkit.load_users(uuid='00807c5b-7542-4868-8462-14b79a9fcc9f',
                          start=datetime(2017, 11, 29),
                          end=datetime(2017, 11, 30))
map_matcher = tripkit.process.map_match.osrm(tripkit_config)
mapmatched_results = map_matcher.match(coordinates=user.coordinates, matcher='DRIVING')
tripkit.io.write_mapmatched_geojson(cfg=tripkit_config, fn_base=user.uuid, results=mapmatched_results)