For all new code and existing code, we should ensure that type hints are used. Arguments, return values, and instance variables should all include type hints. Below are some examples:

class Trace:
    # Instance variable type hints:
    _frame: GeoDataFrame

    coords: List[Coordinate]
    crs: CRS

    # method with both argument type hints and a return type type hint
    @classmethod
    def build(cls, frame: GeoDataFrame, xy: bool = True) -> Trace:
        if xy:
            frame = frame.to_crs(XY_CRS)
        return Trace(frame)

Match() defines its distance attribute as float and code elsewhere assumes that it is a float.
e.g., from compute_cutting_points()

if abs(m.distance - distance_epsilon) < cutting_thresh:
                        cutting_points.append(CuttingPoint(i))

however, in orsm'.py the function _parse_leg() (inner function of parse_osrm_json()) constructs Match objects with distance=None. this is both a mypy error and can cause an error in functions like compute_cutting_points()

discussed with @nreinicke and decided to change the None to float('infinity')

Have usort in CI. Need to remove. Isort is integrated.

Initially, will implement flake8 and eventually migrate to mypy. Not sure whether implement as precommit or CI

Currently, we have to call utils to plot the objects like trace, geofence, which always calls folium.

However, users might want a plot method just like geopandas.GeoDataframe:

• trace.plot() which is equals to trace._frame.plot()
• geofence.plot() which is equals to geofence.geometry

We removed our direct pygeos dependency from the conda environment file but it still exists in the setup.py file. We'll want to remove it and re-distribute the wheels on PyPi.

Implement try/except for geopy distance calc to nearest point on-link to predicted point.

Add or update docstrings on existing classes/ functions. Function/method docstrings should include:

• function/method description
• arguments and return values

Class docstrings should include:

• class description
• public methods and instance variables

An example function docstring from Trace.from_geo_dataframe:

"""
Builds a trace from a geopandas dataframe
Expects the dataframe to have geometry column

:param frame: geopandas dataframe with _one_ trace
:param xy: should the trace be projected to epsg 3857?
:return: the trace built from the dataframe
"""

Python’s webbrowser module (as of 3.10) cannot correctly launch an HTML file from inside WSL. python/cpython#89752

Nothing much we can do here (short of coming up with a fix for CPython), but something to keep in mind when someone else fails to run an example.

As a workaround, you can always launch the HTML file manually with /mnt/c/Windows/explorer.exe <path/to/html> (replace c with wherever your Windows system drive is).

Right now we have a webhook into read the docs that will build the docs anytime there is any pull request related action. It would be more efficient to add a set into our CI workflow that just re-builds the docs when we have a pull request that gets merged into main.

In matchers/lcss/constructs.py (lines 157 - 160) np.argmax can return array of indices where the highest value is found. If there is only one highest value an int is returned. If an array is returned by argmax, this throws an error. Make a check for if the return value of argmax isn't an int.

Determine which version of pygeos work across platforms

To reproduce the the issue run pytest tests from the root directory.

The error is ' OSError: [WinError 6] The handle is invalid'

The cause is pytest by default runs tests in parallel. In parallel, the omnx logger is not able to get a handle.

Git is finding html's produced by examples.

Currently, origin node id and destination node id are found in the Road.metadata. We should add an origin_id and dest_id attribute to Road and remove these ids from the metadata.

We currently have a CI check to run Flake8 but we need go through the codebase and fix all the errors.

Current plot utils do not support layer overlapping. We may want to implement a method called "add_to_map" which accepts a folium map object and additional arguments for styling...

or we can create a method to return an object (maybe a geojson layer) which can be accepted by folium.

I propose to use GeoJSON as the data format internally.

When installing yamm via pip, there ends up being a mismatch between the shapely GEOS version and the pygeos version (see below). This doesn't seem to happen when installing via conda-forge.

../yamm/lib/python3.8/site-packages/geopandas/_compat.py:111: UserWarning: The Shapely GEOS version (3.10.2-CAPI-1.16.0) is incompatible with the GEOS version PyGEOS was compiled with (3.10.1-CAPI-1.16.0). Conversions between both will be slow.

Create a functional test that can assess the accuracy of a particular map-matcher. This probably has to be done with respect to a particular road network.

An idea for how to do this:

• create / download a set of sample traces that have a variety of frequencies / noise.
• manually identify which points should go with which road network link
• run a matcher over the sample traces
• compare the matcher results to the hand-built results to define how accurate the matcher did (with respect to human classification).

This might break out into separate sub issues but it would be nice to setup some GitHub actions for the following:

• publishing the package on PyPi (see #12)
• building the package over multiple python versions
• automated testing
• building documentation and publish to GitHub pages (see #16)

What else?

Most of the development for this package has been done with python 3.8. Investigate what it would take to support python 3.9 and python 3.10.

We currently have simple visualizations in yamm.utils.plots, but we should improve these visualizations to plot the points with a line connecting to the matching road segment.

it makes it easy for users to toggle layers

No real reason to have the notebooks in their own repository under a different github account.

Going to just fold in https://github.com/nreinicke/yamm-notebooks

Right now the OSM map reader only support the "drive" mode.

Parameterize this such that a user could specify which mode to use for creating a road network to match to.

We could provide this input in a string, or, we could create an Enum for the network types that we support. Looking at the osmnx documentation, it looks like the current supported network types are: "all_private", "all", "bike", "drive", "drive_service", "walk".

Since pygeos is going to be incorporated into shapely 2.0, we can remove all of our direct usages of pygeos and only use shapely for all of our geometry. Once pygeos gets incorporated into shapely we can reap the benefits of the performance at that point.

Currently, Road has optional metadata. However, in nx_map, there is no check to see if the Road has metadata and the code assumes that metadata is present. We should add a check to confirm the existence of metadata if it is optional or change Road.metadata to no longer be optional.

Closing this issue in favor of #60

Add a new @classmethod to the Trace class that can load a trace from a provided GPX file.

This could probably be done with some regex parsing, similar to here.

It would be nice to test this using a small sample / dummy .gpx file.

The yamm package is ready to be installed with pip but still needs to uploaded to PyPI. Once yamm is added to PyPI, users will be able install yamm solely by pip.

A set of tasks that need to be ticked off before we open source this package.

• remove direct references to any internal trolley schemas (I think this is fully contained here)
• update the README with more descriptive language
• add license
• add a set of examples

Read the docs supports versioning (right now we don't have multiple versions so this doesn't matter yet). We'll need to figure out how to configure read the docs to maintain a different set of documents for each version.

for easier debugging. __str__ is also important for jupyter notebook users to print out summaries

Testing the match_one_trace.py example on a remote linux server (NREL HPC), the plots do not seem to render in a Jupyter notebook.

We can integrate jupyter notebooks into our documentation.

Reasons:

1. add a layer of testing for notebooks
2. nice for jupyter notebook users

https://jupyterbook.org/en/stable/start/build.html

In addition to distributing the package via PyPi we could also distribute via conda.

Create developer documentation. Some sections we could include:

• Get started or quick start guide

• a variety of examples/use cases ranging from simple to complex

• API documentation

• matcher documentation

Right now matches are returned as a list of Match objects. It might make sense to encapsulate the result of a matcher as an MatchResult object that could implement methods like to_csv().

Another idea is to add a matches attribute to the Trace construct. Then, the matcher could just return a copy of the input trace with the matches appended to it, allowing the user to write trace and matches to file in the same place.

When checking out the project at the beginning of the sprint, tests were initially failing. This appears to be because the length of sample_trace_1.txt changed without the test being updated.

I also added a basic asserts to test_osm so that test makes sure the correct osm_map is returned.

mypy yamm shows a few errors, but two sets of errors are easily resolvable

Errors in class Trace

yamm/constructs/trace.py:45: error: Name "coords" already defined on line 20
yamm/constructs/trace.py:68: error: Name "crs" already defined on line 21

since coords and crs are defined as properties, the declaration at the top of the class are an unneeded extra definitions

Errors in plot_map()

yamm/utils/plot.py:124: error: "MapInterface" has no attribute "g"
yamm/utils/plot.py:126: error: "MapInterface" has no attribute "_geom_key"
yamm/utils/plot.py:126: error: "MapInterface" has no attribute "crs"

plot_map() is a utility function which is only used in the examples. its type hint is MapInterface but the implementation is specific to NxMap. Given the function's limited usage, this type hint can be changed to the specific type.

After installing the environment via environment.yml and then running tests, it fails like so:

=============================================================================== test session starts ===============================================================================
platform darwin -- Python 3.8.8, pytest-6.2.3, py-1.10.0, pluggy-0.13.1
rootdir: /Users/ryan/code/yamm
plugins: anyio-2.2.0
collected 0 items / 4 errors

===================================================================================== ERRORS ======================================================================================
_____________________________________________________________________ ERROR collecting tests/test_geofence.py _____________________________________________________________________
ImportError while importing test module '/Users/ryan/code/yamm/tests/test_geofence.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
../../anaconda3/lib/python3.8/importlib/__init__.py:127: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/test_geofence.py:4: in <module>
    from yamm.constructs.geofence import Geofence
yamm/constructs/geofence.py:4: in <module>
    from geopandas import read_file
E   ModuleNotFoundError: No module named 'geopandas'
_______________________________________________________________________ ERROR collecting tests/test_osm.py ________________________________________________________________________
ImportError while importing test module '/Users/ryan/code/yamm/tests/test_osm.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
../../anaconda3/lib/python3.8/importlib/__init__.py:127: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/test_osm.py:4: in <module>
    from yamm.constructs.geofence import Geofence
yamm/constructs/geofence.py:4: in <module>
    from geopandas import read_file
E   ModuleNotFoundError: No module named 'geopandas'
__________________________________________________________________ ERROR collecting tests/test_process_trace.py ___________________________________________________________________
ImportError while importing test module '/Users/ryan/code/yamm/tests/test_process_trace.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
../../anaconda3/lib/python3.8/importlib/__init__.py:127: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/test_process_trace.py:4: in <module>
    from yamm.constructs.trace import Trace
yamm/constructs/trace.py:9: in <module>
    from geopandas import GeoDataFrame, points_from_xy, read_file, read_parquet
E   ModuleNotFoundError: No module named 'geopandas'
______________________________________________________________________ ERROR collecting tests/test_trace.py _______________________________________________________________________
ImportError while importing test module '/Users/ryan/code/yamm/tests/test_trace.py'.
Hint: make sure your test modules/packages have valid Python names.
Traceback:
../../anaconda3/lib/python3.8/importlib/__init__.py:127: in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
tests/test_trace.py:6: in <module>
    from yamm.constructs.trace import Trace
yamm/constructs/trace.py:9: in <module>
    from geopandas import GeoDataFrame, points_from_xy, read_file, read_parquet
E   ModuleNotFoundError: No module named 'geopandas'
============================================================================= short test summary info =============================================================================
ERROR tests/test_geofence.py
ERROR tests/test_osm.py
ERROR tests/test_process_trace.py
ERROR tests/test_trace.py

When installing mappymatch from PyPI and importing it into another project I get the mypy error:

Skipping analyzing "mappymatch.constructs.geofence": module is installed, but missing library stubs or py.typed marker

We should update our setup.py file to distribute type information (see here)

The forward_merge and reverse_merge functions share the same core code but just reversed. The reverse_merge function could be done by reversing the inputted list and call the forward_merge function and then reverse the results.

Also there is a small issue in the forward merge see the following:
forward_merge([5, 4, 3, 2, 1], lambda x: x < 3) returns [5, 4, 3, 3]
but if there were merges already done in the list like:
forward_merge([1, 2, 3, 4, 5, 4, 3, 2, 1], lambda x: x < 3) return [6, 4, 5, 4, 3, 2, 1]

This can be fixed by running the _flatten command when there are items to merge.

While following the install documents on Windows, the Fiona package fails to install with a GDAL Exception.

In order to replicate the issue:

1. Create environment conda create -n yammbug python=3.8
2. Activate environment conda activate yammbug
3. Install yamm in editable mode pip install -m .

Exception:

Collecting fiona>=1.8
  Using cached Fiona-1.8.21.tar.gz (1.0 MB)
    ERROR: Command errored out with exit status 1:
     command: 'c:\Users\willc\miniconda3\envs\gdaltest1\python.exe' -c 'import sys, setuptools, tokenize; sys.argv[0] = '"'"'C:\\Users\\willc\\AppData\\Local\\Temp\\pip-install-5zcy45b7\\fiona\\setup.py'"'"'; __
file__='"'"'C:\\Users\\willc\\AppData\\Local\\Temp\\pip-install-5zcy45b7\\fiona\\setup.py'"'"';f=getattr(tokenize, '"'"'open'"'"', open)(__file__);code=f.read().replace('"'"'\r\n'"'"', '"'"'\n'"'"');f.close();ex
ec(compile(code, __file__, '"'"'exec'"'"'))' egg_info --egg-base 'C:\Users\willc\AppData\Local\Temp\pip-pip-egg-info-iigt1ecz'
         cwd: C:\Users\willc\AppData\Local\Temp\pip-install-5zcy45b7\fiona\
    Complete output (1 lines):
    A GDAL API version must be specified. Provide a path to gdal-config using a GDAL_CONFIG environment variable or use a GDAL_VERSION environment variable.
    ----------------------------------------
ERROR: Command errored out with exit status 1: python setup.py egg_info Check the logs for full command output.

Using something like sphinx, build a set of API documentation pages.

This is a larger scope issue that will likely need to be split into smaller sub issues

Add a new Hidden Markov Model matcher class that implements the algorithm originally described in this paper.

Some other resources:

• https://github.com/valhalla/valhalla/blob/master/docs/meili/algorithms.md

Build out a new interface to interact with the Vahalla Map Matching API (similar to the OSRM interface).

Testing this could be done by setting up a local instance of Vahalla or using the demo API server (both documented here)

In #83 we made origin/destination junction ids required for roads. There are some tests that we'll need to update to include dummy values for these attributes. See here for one example.

Implement unit tests for the various functions that compose the LCSSMatcher:

• forward_merge
• reverse_merge
• merge
• compress
• same_trajectory_scheme
• find_stationary_points
• drop_stationary_points
• add_matches_for_stationary_points