Merge pull request #167 from Stanford-NavLab/v1.0.3

In line with user requests, we are now updating our GNSS library to support Python 3.12! The library is still compatible with Python 3.9, 3.10, and 3.11 across Linux, MacOS, Windows, and Google Colab (Python 3.10). But, if you wish to continue using Python 3.8, we recommend that you stay with v1.0.2.

Please see the upcoming v1.0.3 release for more information.

.github/workflows/build.yml

@@ -20,18 +20,18 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.8", "3.11"]
+        python-version: ["3.9","3.10","3.11","3.12"]
         os: [ubuntu-latest, macos-latest, windows-latest]
       fail-fast : false
     defaults:
       run:
         shell: bash
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
       id: setup-python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install Poetry
@@ -43,7 +43,7 @@ jobs:
     # Load cached environment, if it exists
     - name: Load cached poetry environment
       id: cached-poetry-dependencies
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: .venv
         key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}
@@ -68,7 +68,7 @@ jobs:
         source $VENV
         poetry run pytest --cov=gnss_lib_py/algorithms --cov=gnss_lib_py/navdata --cov=gnss_lib_py/parsers --cov=gnss_lib_py/utils --cov=gnss_lib_py/visualizations --cov-report=xml
     - name: Upload coverage report to code-cov
-      uses: codecov/codecov-action@v3
+      uses: codecov/codecov-action@v4
       with:
         fail_ci_if_error: true
         token: ${{ secrets.CODECOV_TOKEN }} # not required for public repos
@@ -79,13 +79,13 @@ jobs:
     runs-on: ubuntu-latest
     name: Check if index.rst and README.md weren't changed together
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
       - name: Get changed files since last remote commit
         id: changed-files
-        uses: tj-actions/changed-files@v34
+        uses: tj-actions/changed-files@v44
 
       - name: Check if index.rst changed when README.md file changes
         if: contains(steps.changed-files.outputs.modified_files, 'README.md') && !contains(steps.changed-files.outputs.modified_files, 'docs/source/index.rst')

.github/workflows/pip-install.yml

@@ -14,13 +14,13 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        python-version: ["3.8"]
+        python-version: ["3.9"]
         os: [ubuntu-latest]
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install using pip

.github/workflows/pylint.yml

@@ -13,12 +13,12 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.8"]
+        python-version: ["3.9"]
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python ${{ matrix.python-version }}
       id: setup-python
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install Poetry
@@ -29,7 +29,7 @@ jobs:
         installer-parallel: true # default option selected currently
     - name: Load cached poetry environment
       id: cached-poetry-dependencies
-      uses: actions/cache@v3
+      uses: actions/cache@v4
       with:
         path: .venv
         key: venv-${{ runner.os }}-${{ steps.setup-python.outputs.python-version }}-${{ hashFiles('**/poetry.lock') }}

.github/workflows/pypi-release.yml

@@ -15,9 +15,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-    - uses: actions/checkout@v3
+    - uses: actions/checkout@v4
     - name: Set up Python 3.10
-      uses: actions/setup-python@v4
+      uses: actions/setup-python@v5
       with:
         python-version: "3.10"
 

.gitignore

@@ -151,9 +151,6 @@ target/
 profile_default/
 ipython_config.py
 
-# pyenv
-# .python-version
-
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
 #   However, in case of collaboration, if having platform-specific dependencies or dependencies

.python-version

@@ -1 +1 @@
-3.8.9
+3.9.19

.readthedocs.yaml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-20.04
   tools:
-    python: "3.8"
+    python: "3.9"
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:

README.md

@@ -9,25 +9,31 @@ gnss_lib_py
 `gnss_lib_py` is a modular Python tool for parsing, analyzing, and
 visualizing Global Navigation Satellite Systems (GNSS) data and state
 estimates.
-It also provides an intuitive and modular framework allowing users to
+It also provides an intuitive and modular framework which allows users to
 quickly prototype, implement, and visualize GNSS algorithms.
 `gnss_lib_py` is modular in the sense that multiple types of
-algorithms can be easily exchanged for each other and extendable in
-facilitating user-specific extensions of existing implementations.
+algorithms or datasets can be easily exchanged for each other.
+It is extendable in facilitating user-specific extensions of existing
+implementations.
 
-<img src="https://raw.githubusercontent.com/Stanford-NavLab/gnss_lib_py/main/docs/source/img/skyplot.png" alt="satellite skyplot" width="600"/>
+<img src="https://raw.githubusercontent.com/Stanford-NavLab/gnss_lib_py/main/docs/source/img/glp_architecture.svg" alt="Architecture of gnss-lib-py library" width="800"/>
 
 `gnss_lib_py` contains parsers for common file types used for
 storing GNSS measurements, benchmark algorithms for processing
 measurements into state estimates and visualization tools for measurements
 and state estimates.
 The modularity of `gnss_lib_py` is made possibly by the unifying
-`NavData` class, which contains methods to add, remove and modify
-numeric and string data consistently.
-We provide standard row names for `NavData` elements on the
+`NavData` class, with accompanying standard nomenclature, which can be
+found in the
 [reference page](https://gnss-lib-py.readthedocs.io/en/latest/reference/reference.html).
-These names ensure cross compatibility between different datasets and
-algorithms.
+The standard nomenclature ensures cross compatibility between different
+datasets and algorithms.
+
+`NavData` combines the readability of `pandas.DataFrame` with `numpy.ndarray`
+allowing for easy and fast access of numbers or strings.
+We also provide functionality to add, remove and modify numeric and
+string data consistently along with commonly needed supporting
+functionality.
 
 Documentation
 -------------
@@ -51,7 +57,7 @@ Code Organization
         ├── parsers/                  # Data parsers
         ├── utils/                    # GNSS and common utilities
         ├── visualizations/           # plotting functions
-        └── __init__.py
+        └── __init__.py               # Initialize gnss_lib_py
    ├── notebooks/                     # Interactive Jupyter notebooks
         ├── tutorials/                # Notebooks with tutorial code
    ├── results/                       # Location for result images/files
@@ -61,7 +67,7 @@ Code Organization
       ├── parsers/                    # Tests for files in parsers
       ├── utils/                      # Tests for files in utils
       ├── visualizations/             # Tests for files in visualizations
-      └── test_gnss_lib_py.py         # High level checks for repository
+      └── conftest.py                 # Common methods for tests
    ├── CONTRIBUTORS.md                # List of contributors
    ├── build_docs.sh                  # Bash script to build docs
    ├── poetry.lock                    # Poetry specific Lock file
@@ -70,14 +76,19 @@ Code Organization
 ```
 In the directory organization above:
 
-  * The `algorithms` directory contains localization algorithms that
+  * The `algorithms` directory contains algorithms that
     work by passing in a `NavData` class. Currently, the following
     algorithms are implemented in the `algorithms`:
 
       * Weighted Least Squares
       * Extended Kalman Filter
       * Calculating pseudorange residuals
       * Fault detection and exclusion
+
+  * The `navdata` directory defines the `NavData` class, its methods, and
+    functions that operate on `NavData` instances, like `sort`, `concat`,
+    and others.
+
   * The data parsers in the `parsers` directory allow for either loading
     GNSS data into `gnss_lib_py`'s unifying `NavData` class or parsing
     precise ephemerides data.
@@ -96,6 +107,10 @@ In the directory organization above:
     visualizations, calculating multi-GNSS satellite PVT information,
     satellite simulation, file operations, etc.
 
+  * The `visualizations` directory contains methods for plotting quantities
+    in `NavData`. It includes methods to plot metrics, positions on maps,
+    and skyplots of satellites visible from the receiver position.
+
 Installation
 ------------
 

build_docs.sh

@@ -1,5 +1,6 @@
 #!/bin/bash
 # export requirements.txt for buildings docs
+poetry config warnings.export false
 poetry export -f requirements.txt --output ./docs/source/requirements.txt --with dev --without-hashes
 # export requirements.txt for Conda environment setup
 poetry export -f requirements.txt --output ./requirements.txt --without-hashes

docs/source/conf.py

@@ -37,7 +37,7 @@
 # -- Project information -----------------------------------------------------
 
 project = 'gnss_lib_py'
-copyright = '2022, Stanford NAV Lab'
+copyright = '2024, Stanford NAV Lab'
 author = 'Ashwin Kanhere, Derek Knowles'
 
 

docs/source/contributing/contributing.rst

@@ -16,12 +16,15 @@ In your issue, please include:
     * Your operating system name and version.
     * Any details about your local setup that might be helpful in
       troubleshooting.
-    * A minimal working example to reproduce the bug.
+    * A minimal working example (MWE) to reproduce the bug. An MWE
+      helps us reproduce the bug and troubleshoot the problem.
+      For more details on how to create an MWE, see
+      `this Stack Overflow guide <https://stackoverflow.com/help/minimal-reproducible-example>`.
 
 Feature requests and feedback
 -----------------------------
 
-The best way to   send feedback is to file an issue on
+The best way to any send feedback is to file an issue on
 `GitHub <https://github.com/Stanford-NavLab/gnss_lib_py/issues>`__.
 
 If you are proposing a feature:
@@ -31,8 +34,9 @@ If you are proposing a feature:
     * Keep the scope as narrow as possible, which will make it easier to
       implement.
     * This is a volunteer driven project and most contributions are a
-      result of other research projects. If you implement your requested
-      feature and submit a pull request, we will incorporate it.
+      result of other research projects. We welcome outside implementations
+      of additional features. If you implement your requested feature
+      and submit a pull request, we will incorporate it.
 
 Additional Contributing Pages
 -----------------------------

docs/source/contributing/development.rst

@@ -22,8 +22,12 @@ Standard GitHub Workflow
 
 2. If using poetry, follow the :ref:`developer install instructions<developer install>`
    to install pyenv, poetry, and the python dependencies. If using
-   :code:`pip` or :code:`conda` for package management instead, use
-   :code:`pip install -r requirements.txt` to install dependencies.
+   :code:`pip` or :code:`conda` for package management instead, install
+   dependencies using
+
+   .. code-block:: bash
+
+      pip install -r requirements.txt
 
 3. Create a local branch:
 
@@ -36,16 +40,21 @@ Standard GitHub Workflow
 
    If the feature branch includes new functionality, you must also:
 
-   * update the "Code Organization" section of the :code:`README.md`
-   * update the "Code Organization" section of
-     :code:`docs/source/index.rst` to match the :code:`README.md`
    * add a section in the appropriate tutorial notebook located in
      :code:`notebooks/tutorials/*`
    * if the feature is in a new file, import the file in the
      `module's import block <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/gnss_lib_py/__init__.py>`__.
 
+   If directory level changes were made, you must also:
+
+   * update the "Code Organization" section of the :code:`README.md`
+   * update the "Code Organization" section of
+     :code:`docs/source/index.rst` to match the :code:`README.md`
+
+
 5. Add tests for the newly added code and ensure the new code is covered.
-   See the :ref:`Testing<testing>` section for more details.
+   See the :ref:`Testing<testing>` and :ref:`Coverage<coverage>` pages
+   for more details.
 
 6. When you're done making changes run all the tests with:
 
@@ -93,9 +102,10 @@ Standard GitHub Workflow
     in the pull request, select the latest version release branch :code:`vX.Y.Z`
     (with the highest number of all such branches). *Do not target the*
     :code:`main` *branch in your pull request.* In the pull request,
-    add a code review request for a current maintainer of the repository.
-    The reviewers might add comments to ensure compliance with the rest
-    of the code.
+    add a code review request for a current maintainer of the repository
+    and provide a brief description of the implemented features.
+    The reviewers might add comments or suggest changes to ensure
+    compliance with the rest of the code.
 
 .. _navlab_dev:
 
@@ -119,14 +129,18 @@ NAVLab GitHub Workflow
 
    If the feature branch includes new functionality, you must also:
 
-   * update the "Code Organization" section of the :code:`README.md`
-   * update the "Code Organization" section of
-     :code:`docs/source/index.rst` to match the :code:`README.md`
    * add a section in the appropriate tutorial notebook located in
      :code:`notebooks/tutorials/*`
    * if the feature is in a new file, import the file in the
      `module's import block <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/gnss_lib_py/__init__.py>`__.
 
+   If directory level changes were made, you must also:
+
+   * update the "Code Organization" section of the :code:`README.md`
+   * update the "Code Organization" section of
+     :code:`docs/source/index.rst` to match the :code:`README.md`
+
+
 5. Add tests for the newly added code and ensure the new code is covered.
    See the :ref:`Testing<testing>` section for more details.
 
@@ -214,19 +228,22 @@ Pull Request Review Workflow
 3. Verify that documentation is complete and updated if necessary. See
    the :ref:`Documentation<documentation>` section for more details on
    what is expected.
-
    If the feature branch included new functionality, the following
    should have also been updated:
 
-   * the "Code Organization" section of the :code:`README.md`
-   * the "Code Organization" section of
-     :code:`docs/source/index.rst` to match the :code:`README.md`
    * the appropriate tutorial notebook located in
      :code:`notebooks/tutorials/*` with a simple example of the new
      functionality
    * if a new file was created, it should likely be imported in the
      `module's import block <https://github.com/Stanford-NavLab/gnss_lib_py/blob/main/gnss_lib_py/__init__.py>`__.
 
+   If the directory structure was modified, the following should also have
+   been updated:
+
+   * the "Code Organization" section of the :code:`README.md`
+   * the "Code Organization" section of
+     :code:`docs/source/index.rst` to match the :code:`README.md`
+
 4. Verify that all tests run on your system:
 
    .. code-block:: bash
@@ -243,7 +260,7 @@ Pull Request Review Workflow
 
    .. code-block:: bash
 
-      poetry run pytest --cov=gnss_lib_py/algorithms --cov=gnss_lib_py/parsers --cov=gnss_lib_py/utils --cov-report=xml
+      poetry run pytest --cov=gnss_lib_py/algorithms --cov=gnss_lib_py/parsers --cov=gnss_lib_py/utils --cov-report=html
       poetry run coverage report
 
    See the :ref:`Coverage Report<coverage>` section for more details.