Input/Output

We primarily support two types of data persistence:

  • From CSV files.

  • From PostGIS databases.

Our primary focus lies on supporting PostGIS databases for persistence, but of course you can use the standard Pandas/Python tools to persist your data to any database with a minimal bit of tweaking. And of course you can also keep all data in memory while you do an analysis, e.g., in a Jupyter notebook.

All the read/write functions are made available in the top-level trackintel module, i.e., you can use them as trackintel.read_positionfixes_csv('data.csv'), etc. Note that these functions are wrappers around the (Geo)Pandas CSV and SQL functions. As such, all *args and **kwargs are forwarded to them.

CSV File Import

trackintel.io.file.read_positionfixes_csv(*args, **kwargs)

Wraps the pandas read_csv function, extracts longitude and latitude and builds a geopandas GeoDataFrame. This also validates that the ingested data conforms to the trackintel understanding of positionfixes (see Model).

Parameters

  • columns (dict) – The columnnames to rename in the format {‘old_name’:’trackintel_standard_name’}.

  • tz (str) – pytz compatible timezone string. If None UTC is assumed.

  • that this function is primarily useful if data is available in a (Note) –

  • format. If your data already contains a WKT column (longitude/latitude) –

  • it –

  • be easier to just use the GeoPandas import functions. (might) –

Returns

A GeoDataFrame containing the positionfixes.

Return type

GeoDataFrame

Examples

>>> trackintel.read_positionfixes_csv('data.csv')
>>> trackintel.read_positionfixes_csv('data.csv', columns={'time':'tracked_at', 'User':'user_id'})
trackintel.io.file.read_triplegs_csv(*args, **kwargs)
Wraps the pandas read_csv function, extracts a WKT for the leg geometry and

builds a geopandas GeoDataFrame. This also validates that the ingested data conforms to the trackintel understanding of triplegs (see Model).

Parameters
columnsdict

The columnnames to rename in the format {‘old_name’:’trackintel_standard_name’}.

tzstr

pytz compatible timezone string. If None UTC is assumed.

GeoDataFrame

A GeoDataFrame containing the triplegs.

>>> trackintel.read_triplegs_csv('data.csv')
>>> trackintel.read_triplegs_csv('data.csv', columns={'start_time':'started_at', 'User':'user_id'})
trackintel.io.file.read_staypoints_csv(*args, **kwargs)

Wraps the pandas read_csv function, extracts a WKT for the staypoint geometry and builds a geopandas GeoDataFrame. This also validates that the ingested data conforms to the trackintel understanding of staypoints (see Model).

Parameters

  • columns (dict) – The columnnames to rename in the format {‘old_name’:’trackintel_standard_name’}.

  • tz (str) – pytz compatible timezone string. If None UTC is assumed.

Returns

A GeoDataFrame containing the staypoints.

Return type

GeoDataFrame

Examples

>>> trackintel.read_staypoints_csv('data.csv')
>>> trackintel.read_staypoints_csv('data.csv', columns={'start_time':'started_at', 'User':'user_id'})
trackintel.io.file.read_locations_csv(*args, **kwargs)

Wraps the pandas read_csv function, extracts a WKT for the location center (and extent) and builds a geopandas GeoDataFrame. This also validates that the ingested data conforms to the trackintel understanding of locations (see Model).

Parameters

columns (dict) – The columnnames to rename in the format {‘old_name’:’trackintel_standard_name’}.

Returns

A GeoDataFrame containing the locations.

Return type

GeoDataFrame

Examples

>>> trackintel.read_locations_csv('data.csv')
>>> trackintel.read_locations_csv('data.csv', columns={'start_time':'started_at', 'User':'user_id'})
trackintel.io.file.read_trips_csv(*args, **kwargs)

Wraps the pandas read_csv function and extraces proper datetimes. This also validates that the ingested data conforms to the trackintel understanding of trips (see Model).

Parameters

  • columns (dict) – The columnnames to rename in the format {‘old_name’:’trackintel_standard_name’}.

  • tz (str) – pytz compatible timezone string. If None UTC is assumed.

Returns

A DataFrame containing the trips.

Return type

DataFrame

Examples

>>> trackintel.read_trips_csv('data.csv')
>>> trackintel.read_trips_csv('data.csv', columns={'start_time':'started_at', 'User':'user_id'})

PostGIS Import

trackintel.io.postgis.read_positionfixes_postgis(conn_string, table_name, geom_col='geom', *args, **kwargs)

Reads positionfixes from a PostGIS database.

Parameters

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The table to read the positionfixes from.

  • geom_col (str, default 'geom') – The geometry column of the table.

  • *args – Further arguments as available in GeoPanda’s GeoDataFrame.from_postgis().

  • **kwargs – Further arguments as available in GeoPanda’s GeoDataFrame.from_postgis().

Returns

A GeoDataFrame containing the positionfixes.

Return type

GeoDataFrame

trackintel.io.postgis.read_triplegs_postgis(conn_string, table_name, geom_col='geom', *args, **kwargs)

Reads triplegs from a PostGIS database.

Parameters

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The table to read the triplegs from.

  • geom_col (str, default 'geom') – The geometry column of the table.

Returns

A GeoDataFrame containing the triplegs.

Return type

GeoDataFrame

trackintel.io.postgis.read_staypoints_postgis(conn_string, table_name, geom_col='geom', *args, **kwargs)

Reads staypoints from a PostGIS database.

Parameters

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The table to read the staypoints from.

  • geom_col (str, default 'geom') – The geometry column of the table.

Returns

A GeoDataFrame containing the staypoints.

Return type

GeoDataFrame

trackintel.io.postgis.read_locations_postgis(conn_string, table_name, geom_col='geom', *args, **kwargs)

Reads locations from a PostGIS database.

Parameters

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The table to read the locations from.

  • geom_col (str, default 'geom') – The geometry column of the table.

Returns

A GeoDataFrame containing the locations.

Return type

GeoDataFrame

trackintel.io.postgis.read_trips_postgis(conn_string, table_name, *args, **kwargs)

Reads trips from a PostGIS database.

Parameters

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The table to read the trips from.

Returns

A DataFrame containing the trips.

Return type

DataFrame

CSV File Export

trackintel.io.file.write_positionfixes_csv(positionfixes, filename, *args, **kwargs)

Wraps the pandas to_csv function, but strips the geometry column (‘geom’) and stores the longitude and latitude in respective columns.

Parameters

  • positionfixes (GeoDataFrame) – The positionfixes to store to the CSV file.

  • filename (str) – The file to write to.

trackintel.io.file.write_triplegs_csv(triplegs, filename, *args, **kwargs)

Wraps the pandas to_csv function, but transforms the geom into WKT before writing.

Parameters

  • triplegs (GeoDataFrame) – The triplegs to store to the CSV file.

  • filename (str) – The file to write to.

trackintel.io.file.write_staypoints_csv(staypoints, filename, *args, **kwargs)

Wraps the pandas to_csv function, but transforms the geom into WKT before writing.

Parameters

  • staypoints (GeoDataFrame) – The staypoints to store to the CSV file.

  • filename (str) – The file to write to.

trackintel.io.file.write_locations_csv(locations, filename, *args, **kwargs)

Wraps the pandas to_csv function, but transforms the center (and extent) into WKT before writing.

Parameters

  • locations (GeoDataFrame) – The locations to store to the CSV file.

  • filename (str) – The file to write to.

trackintel.io.file.write_trips_csv(trips, filename, *args, **kwargs)

Wraps the pandas to_csv function.

Parameters

  • trips (DataFrame) – The trips to store to the CSV file.

  • filename (str) – The file to write to.

PostGIS Export

trackintel.io.postgis.write_positionfixes_postgis(positionfixes, conn_string, table_name, schema=None, sql_chunksize=None, if_exists='replace')

Stores positionfixes to PostGIS. Usually, this is directly called on a positionfixes DataFrame (see example below).

Attention! This replaces the table if it already exists!

Parameters

  • positionfixes (GeoDataFrame) – The positionfixes to store to the database.

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The name of the table to write to.

  • schema (str, optional) – The schema (if the database supports this) where the table resides.

  • sql_chunksize (int, optional) – How many entries should be written at the same time.

  • if_exists (str, {'fail', 'replace', 'append'}, default 'replace') – What should happen if the table already exists.

Examples

>>> df.as_positionfixes.to_postgis(conn_string, table_name)
trackintel.io.postgis.write_triplegs_postgis(triplegs, conn_string, table_name, schema=None, sql_chunksize=None, if_exists='replace')

Stores triplegs to PostGIS. Usually, this is directly called on a triplegs DataFrame (see example below).

Attention! This replaces the table if it already exists!

Parameters

  • triplegs (GeoDataFrame) – The triplegs to store to the database.

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The name of the table to write to.

  • schema (str, optional) – The schema (if the database supports this) where the table resides.

  • sql_chunksize (int, optional) – How many entries should be written at the same time.

  • if_exists (str, {'fail', 'replace', 'append'}, default 'replace') – What should happen if the table already exists.

Examples

>>> df.as_triplegs.to_postgis(conn_string, table_name)
trackintel.io.postgis.write_staypoints_postgis(staypoints, conn_string, table_name, schema=None, sql_chunksize=None, if_exists='replace')

Stores staypoints to PostGIS. Usually, this is directly called on a staypoints DataFrame (see example below).

Attention! This replaces the table if it already exists!

Parameters

  • staypoints (GeoDataFrame) – The staypoints to store to the database.

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The name of the table to write to.

  • schema (str, optional) – The schema (if the database supports this) where the table resides.

  • sql_chunksize (int, optional) – How many entries should be written at the same time.

  • if_exists (str, {'fail', 'replace', 'append'}, default 'replace') – What should happen if the table already exists.

Examples

>>> df.as_staypoints.to_postgis(conn_string, table_name)
trackintel.io.postgis.write_locations_postgis(locations, conn_string, table_name, schema=None, sql_chunksize=None, if_exists='replace')

Stores locations to PostGIS. Usually, this is directly called on a locations GeoDataFrame (see example below).

Attention! This replaces the table if it already exists!

Parameters

  • locations (GeoDataFrame) – The locations to store to the database.

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The name of the table to write to.

  • schema (str, optional) – The schema (if the database supports this) where the table resides.

  • sql_chunksize (int, optional) – How many entries should be written at the same time.

  • if_exists (str, {'fail', 'replace', 'append'}, default 'replace') – What should happen if the table already exists.

Examples

>>> df.as_locations.to_postgis(conn_string, table_name)
trackintel.io.postgis.write_trips_postgis(trips, conn_string, table_name, schema=None, sql_chunksize=None, if_exists='replace')

Stores trips to PostGIS. Usually, this is directly called on a trips DataFrame (see example below).

Attention! This replaces the table if it already exists!

Parameters

  • trips (DataFrame) – The trips to store to the database.

  • conn_string (str) – A connection string to connect to a database, e.g., postgresql://username:password@host:socket/database.

  • table_name (str) – The name of the table to write to.

  • schema (str, optional) – The schema (if the database supports this) where the table resides.

  • sql_chunksize (int, optional) – How many entries should be written at the same time.

  • if_exists (str, {'fail', 'replace', 'append'}, default 'replace') – What should happen if the table already exists.

Examples

>>> df.as_trips.to_postgis(conn_string, table_name)