Metadata-Version: 2.1
Name: itinerum-tripkit
Version: 0.0.2
Summary: A toolkit for inferencing trips and trip metadata from Itinerum GPS data
Home-page: https://github.com/TRIP-Lab/itinerum-tripkit
Author: Kyle Fitzsimmons
Author-email: kfitzsimmons@gmail.com
License: UNKNOWN
Description: # itinerum-tripkit
        
        [![Python Version](https://img.shields.io/badge/Python-3.6%7C3.7-blue.svg?style=flat-square)]()
        
        Documentation for library usage: https://itinerum-tripkit.readthedocs.io/
        
        This library serves as a framework to process data from the Itinerum platform and hardware GPS loggers (e.g., QStarz). It can be used both through Jupyter to explore datasets interactively or imported as a module in standalone scripts and applications.
        
        This repository also serves as the development bed for the Itinerum platform algorithms within the TRIP Lab repositories. 
        
        ## Setup
        
        ### Quickstart
        
        1. Clone this repository and `pip install -r requirements.txt` (using a Python [virtual environment](https://docs.python.org/3/library/venv.html) is recommended)
        2. Place source *.csv* data in the `itinerum-tripkit/input` folder (create if necessary) and edit `./tripkit/config.py` to reflect the correct filepaths.
        
        Then either:
        
         - Start Jupyter in repository directly and get started by `from tripkit import Itinerum`
        
           *or*
        
         - Copy the `tripkit` directory into other projects as a library (more complete packaging to come)
        
        For more complete installation information, see the official [itinerum-tripkit documentation](https://itinerum-tripkit.readthedocs.io/en/stable/usage/installation.html).
        
        
        ### Loading Subway Stations
        
        Subway station data for trip detection can be loaded similarly for all processing modules. Place a *.csv* file of station entrances with the columns of `x` (or `longitude`) and `y` (or `latitude`). Locations are expected as geographic coordinates only. Edit the `SUBWAY_STATIONS_FP` config parameter to reflect the subway stations *.csv* filepath.
        
        #### Example
        
        *View attributes on a User*
        
        ```python
        import tripkit_config
        itinerum = Itinerum(tripkit_config)
        
        # create a new database and read in .csv data
        itinerum.setup()
        
        # load all users from database
        users = itinerum.load_all_users()
        
        test_user = users[0]
        print(test_user.coordinates)
        print(test_user.prompt_responses)
        ```
        
        *Run trip detection on a User*
        
        ```python
        import tripkit_config
        itinerum = Itinerum(tripkit_config)
        
        # load user from database by uuid
        user = itinerum.database.load_user('00000000-0000-0000-0000-000000000000')
        
        # run a provided trip detection algorithm
        parameters = {
            'subway_entrances': itinerum.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 = itinerum.process.trip_detection.triplab.v2.algorithm.run(user.coordinates, parameters)
        ```
        
        ## Processing
        
        #### Trip Detection
        
        | Arguments         |                                                              |
        | ----------------- | ------------------------------------------------------------ |
        | `parameters`      | A dictionary to supply arbitrary kwargs to an algorithm      |
        | `subway_stations` | A list of subway station entrance database objects containing `latitude` and `longitude` attributes |
        | `coordinates`     | A timestamp-ordered list of coordinates as dicts for a specific user. Multiple users should be run in sequence and have their output coordinates concatenated into a single list after if desired. |
        
        #### Trip Outputs
        
        Trips will be output with the following trip codes to indicate the type of trip:
        
        | Trip Code | Description                         |
        | --------- | ----------------------------------- |
        | 1         | Complete trip                       |
        | 2         | Complete trip - subway              |
        | 101       | Missing trip                        |
        | 102       | Missing trip - subway               |
        | 103       | Missing trip - less than 250m       |
        | 201       | Single point                        |
        | 202       | Distance too short - less than 250m |
        
        
        ## Outputs
        The aim of this library is to provide easy visualization of Itinerum data to assist in writing trip processing algorthms. Therefore at a minimum, the library provides exporting processed coordinates and traces as .geojson files (TBA: GeoPackage format). With a PostgreSQL backend for caching, PostGIS can be enabled (unimplemented) and a `geom` column generated for directly connection QGIS to the output data. The library should also easily provide methods for easily plotting GPS within Jupyter notebooks.
        
Platform: UNKNOWN
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Requires-Python: >=3.6
Description-Content-Type: text/markdown
