# ISR Matcher
A package for map matching GNSS measurements onto German rail network. Supports route visualization and creation of route profiles (velocity, acceleration, incline and height profiles).
## Description
This package enables map matching onto German rail network. The data of the rail infrastructure is requested from [ISR](https://geovdbn.deutschebahn.com/isr), a service of Deutsche Bahn.
GNSS measurements can only be input in form of CSV files. They must contain at least three columns (latitude, longitude and time). Further columns can be used by the tool (altitude, speed, acceleration), but they are not necessary.
The tool matches the GNSS trajectory to the German rail network and performs certain analysis tasks. Results are written to file(s). For a more detailed description of the functionality, see the section [Methodology](#methodolgy)
Please note that this is still an unstable release. In the current form, it is a prototype of a map matching tool that was created during a 4-month period for my master's thesis. The implementation may suffer from unexpected errors, bugs or performance issues.
## Methodology
The main functionality of the tool is divided into three steps:
- **Preprocessing**
- Aquisition of rail infrastructure data from ISR based on GNSS input.
- Preprocessing of raw infrastructure data into internal object structure.
- **Map Matching**
- Map matching algorithm is based on the Hidden-Markov-Model (HMM) of Newson & Krumm [[1]](https://www.ismll.uni-hildesheim.de/lehre/semSpatial-10s/script/6.pdf).
- Inference of optimal route is performed with the Viterbi algorithm.
- **Postprocessing**
- Route construction: Concatenation of rails and spline interpolation to yield a smooth route.
- Coordinate tranformation: Mapping absoulte GNSS coordinates to track coordinates.
- Route information: Provides infrastructural and operational information about the traveled route.
- Incline profile: The incline profile for the traveled route, in permil.
- Height profile: The height profile for the traveled route, in meter above sea level.
- Velocity profile: The velocity profile for the traveled route, in kilometer per hour.
- Acceleration profile: The acceleration profile for the traveled rotue, in meter per square second.
The following image provides an overview of the structure of the map matching functionality.
Structure of the map matching tool.
## Results
The map matching results are output to files. Namely, the following result files are created:
- **route/**
- 000_<first_track_segment>.txt
- 001_<second_track_segment>.txt
- ...
The directory containes the sequence of track segments the train traveled on. Each text file contains the ISR attributes for the respective track segment in JSON format.
- **map.html**
An HTML-map created with ``folium`` that visualizes the GNSS measurements and map matched route.
Example of map matching result and visualization. Background map from [OpenStreetMap](https://www.openstreetmap.org/copyright).
- **results.csv**
A CSV-file that contains the main results. The following columns are included:
- time: Time stamps.
- time_from_start_s: Passed time, in seconds.
- lat_measured: Latitude as measured by GNSS (cs: WGS84).
- lon_measured: Longitude as measured by GNSS (cs: WGS84).
- lat_wgs84: Latitude of the map matched coordinate (cs: WGS84).
- lon_wgs84: Longitude of the map matched coordinate (cs: WGS84).
- x_epsg31467: Easting of the map matched coordinates (cs: EPSG:31467, as used by ISR).
- y_epsg31467: Northing of the map matched coordinates (cs: EPSG:31467, as used by ISR).
- track_number: The four digit DB track number.
- km: The kilometrage value as float, in kilometer.
- km_db: The kilometrage value in DB format, [km,hm + m,cm].
- km_running: The running distance along the traveld route, in kilometer. *This is notably different from the kilometrage. Distance calculations should always use running distances.*
- move_direction: Direction of ride in respect to kilometrage (1: direction of increasing kilometrage, 2: direction of decreasing kilometrage).
- rail_type: 'Richtungsgleis' (Direction Track), 'Gegengleis' (Opposite Track) or 'eingleisig' (monorail).
- gnss_error_m: Lateral GNSS error, in meter.
- inclines_promille: Track incline, in permil.
- altitude_measured_m: Measured altitude, in meter. NaN, if no measurements are available.
- altitude_computed_m: Computed altitude, in meter.
- velocity_measured_ms: Measured velocity, in meter per second. NaN, if no measurments are available.
- velocity_computed_ms: Computed velocity, in meter per second.
- acceleration_measured_ms2: Measured acceleration, in meter per square second. Nan, if no measurements are available.
- acceleration_computed_ms2: Computed acceleration, in meter per square second.
- **path.csv**
Provides the coordinates of the traveled route in the desired resolution. With the default resolution the path is provided with a spacing of 5 m between coordinates.
- **incline_and_height_profile.csv**
Contains the exact incline profile as given by ISR, and the computed height profile. This provides the actual running kilometers, where track incline changes. Therefore, it is a more accurate representation than the instantaneous values contained in results.csv
- **(optional) inclines_permil.png**
- **(optional) altitude_m.png**
- **(optional) velocity_ms.png**
- **(optional) acceleration_ms2.png**
The profiles can be optionally be plotted with ``matplotlib`` and saved as .png files, as shown below.
Examples for computed route profiles
## Getting Started
This section gives a short overview of package dependencies and installation.
### Dependencies
The package is supported and tested for python version 3.11.
The package has the following dependencies, which will be installed along the package:
* folium>=0.15.1,
* matplotlib>=3.8.2,
* numpy>=1.26.4,
* pandas>=2.2.1,
* pyproj>=3.6.0,
* pytest>=7.4.3,
* requests>=2.31.0,
* scipy>=1.12.0,
* shapely>=2.0.3,
### Installing
Install the package using pip:
```bash
pip install isr_matcher
```
## Usage
This section details the intended usage of the package. First, it shows how to set up the GNSS input file. Then, the obligatory and optional parameters of the tool are explained. Lastly, examples for the usage of the map matching tool are presented.
### Pre usage: Input
The tool currently only supports inputting GNSS data as CSV files. In order to make the CSV data compatible with the tool, two options are available.
#### Option 1: Use standardized column names
The first option is to rename the columns in you CSV file to standardized names used by the tool. The following lists these standardized column names with a short description of the respective data contained in each column.
- **latitude**: column with latitudes (in WGS84 coordinate system)
- **longitude**: column with longitudes (in WGS84 coordinate system)
- **time_utc**: column with timestamps
- **time_s**: column with passed time in seconds
- **altitude_m**: column with measured altitudes, in meter
- **velocity_ms**: column with measured velocity, in meter per second
- **acceleartion_ms**: column with measured acceleration, in meter per second
The columns **latitude**, **longitude** and *one* time column (either **time_utc** *or* **time_s**) are *at least* required. Altitudes, velocities and accelerations can be included optionally, if they are available. The CSV file can contain further columns, but they are ignored by the tool.
#### Option 2: Use a dictionary mapping column names
The second option is to use a dictionary that maps the column names in your CSV file to the standardized column names. This dictionary can then be passed as a parameter to the map matching function, which avoids manually renaming columns in your input file. An example for how to set up this dictionary is given in the following snippet:
```python
column_name_dict = {
"latitude": 'column_name_in_csv_file_with_latitudes', # obligatory
"longitude": 'column_name_in_csv_file_with_longitudes', # ogligatory
"time_utc": 'column_name_in_csv_file_with_utc_time_stamps', # can be None (if time_s is given)
"time_s": 'column_name_in_csv_file_with_time_in_seconds', # can be None (if time_utc is given)
"altitude_m": 'column_name_in_csv_file_with_measured_altitude', # can be None (if not available)
"velocity_ms": 'column_name_in_csv_file_with_measured_velocity', # can be None (if not available)
"acceleration_ms2": 'column_name_in_csv_file_with_measured_acceleration', # can be None (if not available)
}
```
### Pre usage: Parameter settings
The tool allows to control the map matching and analysis task to a certain extent with parameter settings.
#### Obligatory parameters
- **``export_path``**: ``str`` | ``Path``
The path to the output directory where results will be written to.
- **``csv_path``**: ``str`` | ``Path``
The path to the input CSV file with GNSS measurements.
- **``column_name_dict``**: ``dict`` | ``None``
A dictionary mapping column names of the input CSV file to standardized names used by the tool. For further description see section **Pre usage: Input** above. If standardized column names are used (option 1), this parameter should be set to ``None``.
#### Optional parameters
- **``r``**: ``float`` = 1500.0
Determines the boundary around GNSS trajectory for querying infrastructure elements from ISR, in meter.
Larger values ensure all necessary elements are queried, but increase processing time of the tool and the map matching process. Smaller values speed up this processing, but too small values may lead to missing elements in the query.
- **``sigma``**: ``float`` | ``None`` = None
The standard deviation of the GNSS error, in meter. If set to ``None``, the standard deviation will be estimated with ``sigma_method``.
This parameter mainly influences the map matching. For smaller values, the solution will tend to pick rails close to the GNSS measurements, while for larger values the picked rails can be more distant to the measurements.
- **``prune``**: ``Literal['auto']`` | ``float`` | ``None`` = 'auto'
Controls pruning of GNSS measurments:
- ``'auto'``: Removes measurements within 2 * ``sigma`` of each other.
- ``float``: Removes measurements within 2 * ``<float_value>`` of each other.
- ``None``: No pruning.
The idea of pruning is taken from [[1]](https://www.ismll.uni-hildesheim.de/lehre/semSpatial-10s/script/6.pdf) and based on the assumption, that for measurements within two times the standard deviation of each other, the confidence is low that the movement originates from an actual movement of the vehicle, and not from noise. Furthermore, it reduces the computational overhead of the map matching algorithm by reducing the number of timesteps.
- **``path_resolution_m``**: ``float`` = 5.0
Path resolution, in meter. Controls the resolution of the interpolated traveled path, that is the spacing between adjacent path coordinates.
- **``average_low_velocity``**: ``bool`` = True
If True, averages consecutive measurements with velocity smaller than ``threshold_velocity``. If false, no averaging is performed.
When the vehicle stands still or moves very slowly, the position can still jump due to GNSS positioning error. Therefore, setting this to True can be useful to mitigate this effect. However, note that this option is only possible if velocity measurements are provided.
- **``threshold_velocity``**: ``float`` = 3.0
The upper threshold for low velocities that is used when ``average_low_velocity`` is set to True, in meter per second.
- **``sigma_method``**: ``Literal['mad', 'std']`` = 'mad'
The method for estimating ``sigma``, if ``sigma`` is set to None.
- ``'mad'``: Conservative estimate using distance of GNSS measurements to nearest rails and the median absolute deviation (mad) estimator.
- ``std``: Bold estimate which uses standard deviation instead and includes experimental methods for estimating longitudinal GNSS error besides lateral GNSS error. Can be beneficial if the GNSS error is believed to be very large (e.g. due to tunnel sections.)
- **``create_plots``**: ``bool`` = False
If True, creates plots of the computed route profiles with ``matplotlib`` and saves them as .png files. If False, no plots are created.
- **``skiprows``**: ``int`` = 0
Determines if rows should be skipped in the input CSV file.
- **``correct_velocity``**: ``bool`` = True.
Determines if the computed velocity should be corrected for track incline. If your velocity measurements are directly from GNSS, it is better to set this to True. For accurate velocity measurements from other sensors, this should be set to False.
- **``cache_processed_segments``**: ``bool`` = True.
Determines if preprocessed track segments should be written to cache. Setting this to True significantly speeds up preprocessing the next time the specific track segment is required. Cached track segments can be deleted from cache with the method ``clear_cache`` (see [Example usage](#example-usage)).
### Example usage
#### Minimal working example
The following script demonstrates the basic usage of the tool. The script can be downloaded from [github](https://github.com/mgillwald/isr_matcher/tree/main/examples) along with the (simulated) test data. As the CSV file containing the test data already has correct column names, we set ``column_name_dict = None``.
```python
from isr_matcher import matching
from pathlib import Path
# required parameters
root = Path(__file__).parent.parent
export_path = root / 'examples/results/' # change this as needed
csv_path = root / 'examples/test_data.csv' # change this as needed
column_name_dict = None # test data has correct column names
# map matching
matching(
export_path=export_path,
csv_path=csv_path,
column_name_dict=column_name_dict,
)
```
#### Extended example with all parameters
An extended example with all parameters explicitly set.
```python
from isr_matcher import matching, clear_cache
from pathlib import Path
# required parameters
root = Path(__file__).parent.parent
export_path = root / 'examples/results/' # change this as needed
csv_path = root / 'examples/test_data.csv' # change this as needed
column_name_dict = None # test data has correct column names
# optional parameters (default values)
r = 1500
sigma = None
prune = 'auto'
path_resolution_m: float = 5.0
average_low_velocity = True
threshold_velocity = 3.0
sigma_method = 'mad'
create_plots = False
skiprows = 0
correct_velocity = True
cache_preprocessed_segments = True
# cache
clear_cache() # optional, removes all preprocessed track files from cache
# map matching
matching(
export_path=export_path,
csv_path=csv_path,
column_name_dict=column_name_dict,
r=r,
sigma=sigma,
path_resolution_m=path_resolution_m,
average_low_velocity=average_low_velocity,
threshold_velocity=threshold_velocity,
sigma_method=sigma_method,
create_plots=create_plots,
skiprows=skiprows,
correct_velocity=correct_velocity,
cache_preprocessed_segments=cache_preprocessed_segments,
)
```
## Help
If you encounter problems or are looking for help, please open an [issue](https://github.com/mgillwald/isr_matcher/issues) or send me a [mail](marco.gillwald@gmx.de).
## Authors
Marco Gillwald ([marco.gillwald@gmx.de](marco.gillwald@gmx.de) / [mgillwald](https://github.com/mgillwald))
## Version History
<details>
<summary>Show</summary>
* 0.0.6
* Fix images
* Refine readme
* 0.0.5
* Fix images
* 0.0.4
* Readme updated
* Minor bug fixes
* 0.0.3
* Readme updated
* Example added
* Updated doc strings
* 0.0.2
* Readme added
* 0.0.1
* Initial Release
</details>
## Road Map
The main goals that need to be addressed are:
* Release full Documentation
* Bug fixes and code optimization
* Expand testing
Reaching those goals will culminate in the first stable release. Additionally, a small GUI is intended for simple usage and control of features. However, this all depends on how much time I will put into further development in the future.
## License
This project is licensed under the Apache Software License 2.0 - see the LICENSE file for details
## Acknowledgments
[1] P. Newson und J. Krumm, „Hidden Markov Map Matching Through Noise and Sparseness,“
in 17th ACM SIGSPATIAL International Conference on Advances in Geographic
Information Systems, November 4-6, Seattle, WA, Nov. 2009, S. 336–343. URL: [https://www.microsoft.com/en-us/research/publication/hidden-markov-map-matching-noise-sparseness/](https://www.microsoft.com/en-us/research/publication/hidden-markov-map-matching-noise-sparseness/).
This package does not include, but allows to query data from infrastructure registry ([Infrastrukturregister](https://geovdbn.deutschebahn.com/isr)) of Deutsche Bahn.
This package uses kilometrage information from the dataset [Geo-Streckennetz](https://data.deutschebahn.com/dataset/geo-strecke.html) of Deutsche Bahn.
Raw data
{
"_id": null,
"home_page": null,
"name": "isr-matcher",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.11",
"maintainer_email": null,
"keywords": "map matching, rail, ISR",
"author": null,
"author_email": "Marco Gillwald <marco.gillwald@gmx.de>",
"download_url": "https://files.pythonhosted.org/packages/51/a7/038cab233ff71d9cf3cc56b0a3b1d5039333fec7ab62d98db8213bb633a2/isr_matcher-0.0.7.tar.gz",
"platform": null,
"description": "# ISR Matcher\r\n\r\nA package for map matching GNSS measurements onto German rail network. Supports route visualization and creation of route profiles (velocity, acceleration, incline and height profiles).\r\n\r\n## Description\r\n\r\nThis package enables map matching onto German rail network. The data of the rail infrastructure is requested from [ISR](https://geovdbn.deutschebahn.com/isr), a service of Deutsche Bahn. \r\n\r\nGNSS measurements can only be input in form of CSV files. They must contain at least three columns (latitude, longitude and time). Further columns can be used by the tool (altitude, speed, acceleration), but they are not necessary. \r\n\r\nThe tool matches the GNSS trajectory to the German rail network and performs certain analysis tasks. Results are written to file(s). For a more detailed description of the functionality, see the section [Methodology](#methodolgy)\r\n\r\nPlease note that this is still an unstable release. In the current form, it is a prototype of a map matching tool that was created during a 4-month period for my master's thesis. The implementation may suffer from unexpected errors, bugs or performance issues.\r\n\r\n## Methodology\r\n\r\nThe main functionality of the tool is divided into three steps:\r\n\r\n- **Preprocessing**\r\n - Aquisition of rail infrastructure data from ISR based on GNSS input.\r\n - Preprocessing of raw infrastructure data into internal object structure.\r\n\r\n- **Map Matching**\r\n - Map matching algorithm is based on the Hidden-Markov-Model (HMM) of Newson & Krumm [[1]](https://www.ismll.uni-hildesheim.de/lehre/semSpatial-10s/script/6.pdf).\r\n - Inference of optimal route is performed with the Viterbi algorithm.\r\n\r\n- **Postprocessing**\r\n - Route construction: Concatenation of rails and spline interpolation to yield a smooth route.\r\n - Coordinate tranformation: Mapping absoulte GNSS coordinates to track coordinates.\r\n - Route information: Provides infrastructural and operational information about the traveled route.\r\n - Incline profile: The incline profile for the traveled route, in permil.\r\n - Height profile: The height profile for the traveled route, in meter above sea level.\r\n - Velocity profile: The velocity profile for the traveled route, in kilometer per hour.\r\n - Acceleration profile: The acceleration profile for the traveled rotue, in meter per square second.\r\n\r\nThe following image provides an overview of the structure of the map matching functionality.\r\n\r\n\r\nStructure of the map matching tool.\r\n\r\n## Results\r\n\r\nThe map matching results are output to files. Namely, the following result files are created:\r\n\r\n- **route/**\r\n - 000_<first_track_segment>.txt\r\n - 001_<second_track_segment>.txt\r\n - ...\r\n\r\n The directory containes the sequence of track segments the train traveled on. Each text file contains the ISR attributes for the respective track segment in JSON format.\r\n- **map.html**\r\n\r\n An HTML-map created with ``folium`` that visualizes the GNSS measurements and map matched route. \r\n \r\nExample of map matching result and visualization. Background map from [OpenStreetMap](https://www.openstreetmap.org/copyright).\r\n- **results.csv**\r\n \r\n A CSV-file that contains the main results. The following columns are included: \r\n - time: Time stamps.\r\n - time_from_start_s: Passed time, in seconds.\r\n - lat_measured: Latitude as measured by GNSS (cs: WGS84).\r\n - lon_measured: Longitude as measured by GNSS (cs: WGS84).\r\n - lat_wgs84: Latitude of the map matched coordinate (cs: WGS84).\r\n - lon_wgs84: Longitude of the map matched coordinate (cs: WGS84).\r\n - x_epsg31467: Easting of the map matched coordinates (cs: EPSG:31467, as used by ISR).\r\n - y_epsg31467: Northing of the map matched coordinates (cs: EPSG:31467, as used by ISR).\r\n - track_number: The four digit DB track number.\r\n - km: The kilometrage value as float, in kilometer.\r\n - km_db: The kilometrage value in DB format, [km,hm + m,cm].\r\n - km_running: The running distance along the traveld route, in kilometer. *This is notably different from the kilometrage. Distance calculations should always use running distances.* \r\n - move_direction: Direction of ride in respect to kilometrage (1: direction of increasing kilometrage, 2: direction of decreasing kilometrage).\r\n - rail_type: 'Richtungsgleis' (Direction Track), 'Gegengleis' (Opposite Track) or 'eingleisig' (monorail).\r\n - gnss_error_m: Lateral GNSS error, in meter.\r\n - inclines_promille: Track incline, in permil.\r\n - altitude_measured_m: Measured altitude, in meter. NaN, if no measurements are available.\r\n - altitude_computed_m: Computed altitude, in meter.\r\n - velocity_measured_ms: Measured velocity, in meter per second. NaN, if no measurments are available.\r\n - velocity_computed_ms: Computed velocity, in meter per second.\r\n - acceleration_measured_ms2: Measured acceleration, in meter per square second. Nan, if no measurements are available. \r\n - acceleration_computed_ms2: Computed acceleration, in meter per square second.\r\n\r\n- **path.csv**\r\n\r\n Provides the coordinates of the traveled route in the desired resolution. With the default resolution the path is provided with a spacing of 5 m between coordinates. \r\n- **incline_and_height_profile.csv**\r\n\r\n Contains the exact incline profile as given by ISR, and the computed height profile. This provides the actual running kilometers, where track incline changes. Therefore, it is a more accurate representation than the instantaneous values contained in results.csv\r\n- **(optional) inclines_permil.png**\r\n- **(optional) altitude_m.png**\r\n- **(optional) velocity_ms.png**\r\n- **(optional) acceleration_ms2.png**\r\n\r\n The profiles can be optionally be plotted with ``matplotlib`` and saved as .png files, as shown below.\r\n\r\n\r\n\r\n \r\nExamples for computed route profiles \r\n\r\n## Getting Started\r\n\r\nThis section gives a short overview of package dependencies and installation.\r\n\r\n### Dependencies\r\n\r\nThe package is supported and tested for python version 3.11.\r\n\r\nThe package has the following dependencies, which will be installed along the package:\r\n\r\n * folium>=0.15.1,\r\n * matplotlib>=3.8.2,\r\n * numpy>=1.26.4,\r\n * pandas>=2.2.1,\r\n * pyproj>=3.6.0,\r\n * pytest>=7.4.3,\r\n * requests>=2.31.0,\r\n * scipy>=1.12.0,\r\n * shapely>=2.0.3,\r\n\r\n\r\n### Installing\r\n\r\nInstall the package using pip:\r\n\r\n```bash\r\npip install isr_matcher\r\n```\r\n\r\n## Usage\r\n\r\nThis section details the intended usage of the package. First, it shows how to set up the GNSS input file. Then, the obligatory and optional parameters of the tool are explained. Lastly, examples for the usage of the map matching tool are presented.\r\n\r\n### Pre usage: Input\r\n\r\nThe tool currently only supports inputting GNSS data as CSV files. In order to make the CSV data compatible with the tool, two options are available.\r\n\r\n#### Option 1: Use standardized column names\r\n\r\nThe first option is to rename the columns in you CSV file to standardized names used by the tool. The following lists these standardized column names with a short description of the respective data contained in each column. \r\n\r\n- **latitude**: column with latitudes (in WGS84 coordinate system)\r\n- **longitude**: column with longitudes (in WGS84 coordinate system)\r\n- **time_utc**: column with timestamps \r\n- **time_s**: column with passed time in seconds\r\n- **altitude_m**: column with measured altitudes, in meter\r\n- **velocity_ms**: column with measured velocity, in meter per second\r\n- **acceleartion_ms**: column with measured acceleration, in meter per second\r\n\r\nThe columns **latitude**, **longitude** and *one* time column (either **time_utc** *or* **time_s**) are *at least* required. Altitudes, velocities and accelerations can be included optionally, if they are available. The CSV file can contain further columns, but they are ignored by the tool.\r\n\r\n#### Option 2: Use a dictionary mapping column names\r\n\r\nThe second option is to use a dictionary that maps the column names in your CSV file to the standardized column names. This dictionary can then be passed as a parameter to the map matching function, which avoids manually renaming columns in your input file. An example for how to set up this dictionary is given in the following snippet:\r\n\r\n```python\r\ncolumn_name_dict = {\r\n \"latitude\": 'column_name_in_csv_file_with_latitudes', # obligatory\r\n \"longitude\": 'column_name_in_csv_file_with_longitudes', # ogligatory\r\n \"time_utc\": 'column_name_in_csv_file_with_utc_time_stamps', # can be None (if time_s is given)\r\n \"time_s\": 'column_name_in_csv_file_with_time_in_seconds', # can be None (if time_utc is given)\r\n \"altitude_m\": 'column_name_in_csv_file_with_measured_altitude', # can be None (if not available)\r\n \"velocity_ms\": 'column_name_in_csv_file_with_measured_velocity', # can be None (if not available)\r\n \"acceleration_ms2\": 'column_name_in_csv_file_with_measured_acceleration', # can be None (if not available)\r\n}\r\n```\r\n\r\n\r\n### Pre usage: Parameter settings\r\n\r\nThe tool allows to control the map matching and analysis task to a certain extent with parameter settings. \r\n\r\n#### Obligatory parameters\r\n\r\n- **``export_path``**: ``str`` | ``Path``\r\n\r\n The path to the output directory where results will be written to. \r\n\r\n- **``csv_path``**: ``str`` | ``Path``\r\n\r\n The path to the input CSV file with GNSS measurements.\r\n\r\n- **``column_name_dict``**: ``dict`` | ``None``\r\n\r\n A dictionary mapping column names of the input CSV file to standardized names used by the tool. For further description see section **Pre usage: Input** above. If standardized column names are used (option 1), this parameter should be set to ``None``.\r\n\r\n\r\n#### Optional parameters\r\n\r\n- **``r``**: ``float`` = 1500.0\r\n\r\n Determines the boundary around GNSS trajectory for querying infrastructure elements from ISR, in meter.\r\n Larger values ensure all necessary elements are queried, but increase processing time of the tool and the map matching process. Smaller values speed up this processing, but too small values may lead to missing elements in the query.\r\n\r\n- **``sigma``**: ``float`` | ``None`` = None\r\n\r\n The standard deviation of the GNSS error, in meter. If set to ``None``, the standard deviation will be estimated with ``sigma_method``.\r\n\r\n This parameter mainly influences the map matching. For smaller values, the solution will tend to pick rails close to the GNSS measurements, while for larger values the picked rails can be more distant to the measurements.\r\n\r\n- **``prune``**: ``Literal['auto']`` | ``float`` | ``None`` = 'auto'\r\n\r\n Controls pruning of GNSS measurments:\r\n\r\n - ``'auto'``: Removes measurements within 2 * ``sigma`` of each other.\r\n - ``float``: Removes measurements within 2 * ``<float_value>`` of each other.\r\n - ``None``: No pruning.\r\n\r\n The idea of pruning is taken from [[1]](https://www.ismll.uni-hildesheim.de/lehre/semSpatial-10s/script/6.pdf) and based on the assumption, that for measurements within two times the standard deviation of each other, the confidence is low that the movement originates from an actual movement of the vehicle, and not from noise. Furthermore, it reduces the computational overhead of the map matching algorithm by reducing the number of timesteps.\r\n\r\n- **``path_resolution_m``**: ``float`` = 5.0\r\n\r\n Path resolution, in meter. Controls the resolution of the interpolated traveled path, that is the spacing between adjacent path coordinates.\r\n\r\n- **``average_low_velocity``**: ``bool`` = True\r\n\r\n If True, averages consecutive measurements with velocity smaller than ``threshold_velocity``. If false, no averaging is performed.\r\n\r\n When the vehicle stands still or moves very slowly, the position can still jump due to GNSS positioning error. Therefore, setting this to True can be useful to mitigate this effect. However, note that this option is only possible if velocity measurements are provided.\r\n\r\n- **``threshold_velocity``**: ``float`` = 3.0\r\n\r\n The upper threshold for low velocities that is used when ``average_low_velocity`` is set to True, in meter per second. \r\n\r\n- **``sigma_method``**: ``Literal['mad', 'std']`` = 'mad'\r\n\r\n The method for estimating ``sigma``, if ``sigma`` is set to None. \r\n \r\n - ``'mad'``: Conservative estimate using distance of GNSS measurements to nearest rails and the median absolute deviation (mad) estimator.\r\n - ``std``: Bold estimate which uses standard deviation instead and includes experimental methods for estimating longitudinal GNSS error besides lateral GNSS error. Can be beneficial if the GNSS error is believed to be very large (e.g. due to tunnel sections.)\r\n\r\n- **``create_plots``**: ``bool`` = False\r\n\r\n If True, creates plots of the computed route profiles with ``matplotlib`` and saves them as .png files. If False, no plots are created.\r\n\r\n- **``skiprows``**: ``int`` = 0\r\n\r\n Determines if rows should be skipped in the input CSV file. \r\n\r\n- **``correct_velocity``**: ``bool`` = True.\r\n\r\n Determines if the computed velocity should be corrected for track incline. If your velocity measurements are directly from GNSS, it is better to set this to True. For accurate velocity measurements from other sensors, this should be set to False. \r\n\r\n- **``cache_processed_segments``**: ``bool`` = True.\r\n\r\n Determines if preprocessed track segments should be written to cache. Setting this to True significantly speeds up preprocessing the next time the specific track segment is required. Cached track segments can be deleted from cache with the method ``clear_cache`` (see [Example usage](#example-usage)).\r\n\r\n### Example usage\r\n\r\n#### Minimal working example\r\n\r\nThe following script demonstrates the basic usage of the tool. The script can be downloaded from [github](https://github.com/mgillwald/isr_matcher/tree/main/examples) along with the (simulated) test data. As the CSV file containing the test data already has correct column names, we set ``column_name_dict = None``.\r\n\r\n```python\r\nfrom isr_matcher import matching\r\nfrom pathlib import Path\r\n\r\n# required parameters\r\nroot = Path(__file__).parent.parent \r\nexport_path = root / 'examples/results/' # change this as needed\r\ncsv_path = root / 'examples/test_data.csv' # change this as needed\r\ncolumn_name_dict = None # test data has correct column names\r\n\r\n# map matching\r\nmatching(\r\n export_path=export_path, \r\n csv_path=csv_path, \r\n column_name_dict=column_name_dict, \r\n)\r\n```\r\n\r\n#### Extended example with all parameters\r\n\r\nAn extended example with all parameters explicitly set.\r\n\r\n```python\r\nfrom isr_matcher import matching, clear_cache\r\nfrom pathlib import Path\r\n\r\n# required parameters\r\nroot = Path(__file__).parent.parent \r\nexport_path = root / 'examples/results/' # change this as needed\r\ncsv_path = root / 'examples/test_data.csv' # change this as needed\r\ncolumn_name_dict = None # test data has correct column names\r\n\r\n# optional parameters (default values)\r\nr = 1500 \r\nsigma = None \r\nprune = 'auto' \r\npath_resolution_m: float = 5.0 \r\naverage_low_velocity = True \r\nthreshold_velocity = 3.0 \r\nsigma_method = 'mad' \r\ncreate_plots = False \r\nskiprows = 0 \r\ncorrect_velocity = True \r\ncache_preprocessed_segments = True \r\n\r\n# cache\r\nclear_cache() # optional, removes all preprocessed track files from cache\r\n\r\n# map matching\r\nmatching(\r\n export_path=export_path, \r\n csv_path=csv_path, \r\n column_name_dict=column_name_dict,\r\n r=r,\r\n sigma=sigma,\r\n path_resolution_m=path_resolution_m,\r\n average_low_velocity=average_low_velocity,\r\n threshold_velocity=threshold_velocity,\r\n sigma_method=sigma_method,\r\n create_plots=create_plots,\r\n skiprows=skiprows,\r\n correct_velocity=correct_velocity,\r\n cache_preprocessed_segments=cache_preprocessed_segments, \r\n)\r\n```\r\n\r\n## Help\r\n\r\nIf you encounter problems or are looking for help, please open an [issue](https://github.com/mgillwald/isr_matcher/issues) or send me a [mail](marco.gillwald@gmx.de).\r\n\r\n## Authors\r\n\r\nMarco Gillwald ([marco.gillwald@gmx.de](marco.gillwald@gmx.de) / [mgillwald](https://github.com/mgillwald))\r\n\r\n## Version History\r\n\r\n\r\n<details>\r\n <summary>Show</summary>\r\n\r\n* 0.0.6\r\n * Fix images\r\n * Refine readme\r\n* 0.0.5\r\n * Fix images\r\n* 0.0.4\r\n * Readme updated\r\n * Minor bug fixes\r\n* 0.0.3\r\n * Readme updated\r\n * Example added\r\n * Updated doc strings\r\n* 0.0.2\r\n * Readme added\r\n* 0.0.1\r\n * Initial Release\r\n\r\n</details>\r\n\r\n## Road Map\r\n\r\nThe main goals that need to be addressed are:\r\n\r\n * Release full Documentation\r\n * Bug fixes and code optimization\r\n * Expand testing\r\n\r\nReaching those goals will culminate in the first stable release. Additionally, a small GUI is intended for simple usage and control of features. However, this all depends on how much time I will put into further development in the future.\r\n\r\n\r\n## License\r\n\r\nThis project is licensed under the Apache Software License 2.0 - see the LICENSE file for details\r\n\r\n## Acknowledgments\r\n\r\n[1] P. Newson und J. Krumm, \u201eHidden Markov Map Matching Through Noise and Sparseness,\u201c\r\nin 17th ACM SIGSPATIAL International Conference on Advances in Geographic\r\nInformation Systems, November 4-6, Seattle, WA, Nov. 2009, S. 336\u2013343. URL: [https://www.microsoft.com/en-us/research/publication/hidden-markov-map-matching-noise-sparseness/](https://www.microsoft.com/en-us/research/publication/hidden-markov-map-matching-noise-sparseness/).\r\n\r\nThis package does not include, but allows to query data from infrastructure registry ([Infrastrukturregister](https://geovdbn.deutschebahn.com/isr)) of Deutsche Bahn.\r\nThis package uses kilometrage information from the dataset [Geo-Streckennetz](https://data.deutschebahn.com/dataset/geo-strecke.html) of Deutsche Bahn.\r\n",
"bugtrack_url": null,
"license": "Copyright 2024 Marco Gillwald Licensed under the Apache License, Version 2.0 (the \"License\"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an \"AS IS\" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.",
"summary": "A package for map matching to german rail network",
"version": "0.0.7",
"project_urls": {
"Homepage": "https://github.com/mgillwald/isr_matcher",
"Issues": "https://github.com/mgillwald/isr_matcher/issues"
},
"split_keywords": [
"map matching",
" rail",
" isr"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0def8304346ba18e6e651da94595e4697406134d4c861ed88291ec7f89d140e9",
"md5": "e3b3b6b2f38e55394090692e14fc9cf3",
"sha256": "566091f7e5313e5ad9c546ed54cd4ecb4457bcb1dda563a547ca8e9f86dac13b"
},
"downloads": -1,
"filename": "isr_matcher-0.0.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e3b3b6b2f38e55394090692e14fc9cf3",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.11",
"size": 836736,
"upload_time": "2024-07-31T12:19:36",
"upload_time_iso_8601": "2024-07-31T12:19:36.113682Z",
"url": "https://files.pythonhosted.org/packages/0d/ef/8304346ba18e6e651da94595e4697406134d4c861ed88291ec7f89d140e9/isr_matcher-0.0.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "51a7038cab233ff71d9cf3cc56b0a3b1d5039333fec7ab62d98db8213bb633a2",
"md5": "6325dfd000750c23dbdbe2661bb35475",
"sha256": "42c2aeccc9f7f48fbb9806c43e3826b2c208ca0ebe64d0dfbdd17d3ddb8bd6ef"
},
"downloads": -1,
"filename": "isr_matcher-0.0.7.tar.gz",
"has_sig": false,
"md5_digest": "6325dfd000750c23dbdbe2661bb35475",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.11",
"size": 2072326,
"upload_time": "2024-07-31T12:19:46",
"upload_time_iso_8601": "2024-07-31T12:19:46.095676Z",
"url": "https://files.pythonhosted.org/packages/51/a7/038cab233ff71d9cf3cc56b0a3b1d5039333fec7ab62d98db8213bb633a2/isr_matcher-0.0.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-07-31 12:19:46",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mgillwald",
"github_project": "isr_matcher",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "folium",
"specs": [
[
"==",
"0.15.1"
]
]
},
{
"name": "matplotlib",
"specs": [
[
"==",
"3.8.2"
]
]
},
{
"name": "numpy",
"specs": [
[
"==",
"1.26.4"
]
]
},
{
"name": "pandas",
"specs": [
[
"==",
"2.2.1"
]
]
},
{
"name": "pyproj",
"specs": [
[
"==",
"3.6.0"
]
]
},
{
"name": "pytest",
"specs": [
[
"==",
"7.4.3"
]
]
},
{
"name": "Requests",
"specs": [
[
"==",
"2.31.0"
]
]
},
{
"name": "scipy",
"specs": [
[
"==",
"1.12.0"
]
]
},
{
"name": "Shapely",
"specs": [
[
"==",
"2.0.3"
]
]
}
],
"lcname": "isr-matcher"
}
JSON
