Appendix B. Cruise Detector User Guide
This manual describes how to use the GPS cruising identification model developed by FHWA. Any user with a working knowledge of GIS and simple database skills should be able to implement the system with the aid of information presented here. This tool uses GPS data to estimate the proportion of trips that are cruising for parking.
The following Python® packages must also be installed: numpy 1.11.3+ scipy 0.19.0+ pandas 0.19.2+ gpxpy 1.1.2+ psycopg2 2.5.2+ sqlalchemy 1.1.6+ docopt 0.6.1+
Create a base directory, and download the cruising and pgMapMatch repositories to that directory, and download the sample location data to the cruising folder. Add a folder titled “output” to store logs, and unzip the sampleLocationData folder if using. Download osm2po to a directory with no spaces in its path.
Data Requirements and Format
The street network should be in pbf format. An extract for specific geographic areas can be obtained from geofabrik.de. The extract should be saved to the osm2po base path, if that is different from the project base bath.
Census tract or block group boundaries are used to aggregate results for analysis purposes after pgMapMatch has been run on the GPS trace data. Census geographies can be obtained in shapefile format from the U.S. Census Bureau’s TIGERweb database.
Global Positioning System Data
Data formats may vary by vendor, but the raw GPS location data must be a table containing a minimum of: device ID, timestamp, latitude and longitude, and horizontal accuracy. The cruising_importLocationData.py script is based on one specific vendor’s data and may require alteration to match the format and data structure of the location data obtained.
The following is an incomplete list of possible location data vendors*:
Trip data that have been pre-processed into traces by the vendor can also be used. The imported PostgreSQL table must contain:
The following is an incomplete list of possible vendors for trip data*:
As with the location data, the list is not comprehensive, not an endorsement and not a guarantee the vendor will make usable data available. A collaboration with these firms may be necessary to access their data and information.
Config File Changes
User will need to change the configuration settings for Postgres, pgMapMatch, osm2po, and the cruising tool itself.
Postgres. After setting up the postgres database, removing the password requirement allows the tool to run smoother. This can be done by changing authentication requirements in the pg_hba.conf file to trust.
Clone the cruising and pgMapMatch repositories, and add a folder titled “output” to store logs.
cruising. Configuration parameters are located in the cruising.py file. Open cruising.py and set the parameters for host, file paths, regions, spatial reference systems, and number of CPU cores used for processing. The config file also contains multiple parameters to calibrate trace generation from GPS data and identify cruising.
pgMapMatch. Open config_template.py and make changes to the pgInfo parameter for the postgres database connection. If password has been removed, make sure requirePassword is set to False. Save the file as config.py.
postp.0.class = de.cm.osm2po.plugins.postp.PgRoutingWriter
Load the Data
To get started, create extensions for Postgis and Pgrouting by running the following query in the project's PostgreSQL database:
CREATE EXTENSION postgis;
Next, run the following in Python IDE:
Import Street Network
Run loadTables(region='[yourRegion]') with the respective region as specified in cruising.py, which will import the osm street network and turn restriction table into the database. The field names for the streets table should match those in the pgMapMatch/config.py. Make sure the SRS of the streets table matches the SRS to be used for the location or trip data, and create indexes and spatial indexes have been created. Depending on the imported network, it may improve performance to clip the street network to a convex hull around the study area.
To run the sample data, user will need to download the Washington State osm.pbf file to the osm2po path and run loadTables(region='wa'). The sample data are comprised of GPS point data, which will be used to generate traces, that can then be analyzed for cruising.
Import Census Boundaries
Use PostGIS to import the census boundary files to database, and reproject the data to the SRS being used. Use a spatial join to add the tract or block group ID to the streets table.
Import Global Positioning System Data
The cruising_importLocationData.py script is based on a specific data vendor and may require alteration to match the format and data structure of the location data obtained.
To import the sample data, set the sample data directory and name for the imported location data table points_table and output trace table output_table.
Run the following code to import the table:
points_table = 'samplepoints'
To generate traces from the sample data, run the following code:
pts = pointData(points_table, trace_table, schema = 'public', region = 'wa', forceUpdate=True)
Map-Matching from User-Generated Traces
Once the trace table is created, from either the sample data set or the user’s data, it can be mapmatched by running the following code:
trace_table = "[yourTraceTable]" ##same as the trace_table in the previous section
This may take several hours, even with the sample data.
Results and Interpretation
Once the trips have been processed the data output can be analyzed with a spreadsheet, python, or any statistical package and GIS. See the data dictionary here: https://github.com/amillb/cruising/blob/master/data_dictionary.csv.
Glossary for the Cruise Detector User Guide
A trail or path made up of a collection of chronologically arranged GPS locations.
A process to match a series of pings or traces to a street network or map.
Both a converter and a routing engine.
Displays information about processor groups hierarchy, its contents, and its characteristics.
A map-matching algorithm.
An extension that adds routing and other network analysis functionality to PostGIS/PostgreSQL databases.
A spatial database extender for PostgreSQL object-relational database.
Also known as Postgres, a free and open-source relational database management system emphasizing extensibility and SQL compliance.
To change the projection (coordinate system) of spatial data with another projection.
Involves matching rows from the Join Features to the Target Features based on their relative spatial locations.
A related or connected group of pings.
* The names of vendors in this list are included for informational purposes only and are not intended to reflect a preference, approval, or endorsement of any one product or entity. [ Return to Note * ]
United States Department of Transportation - Federal Highway Administration