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.

Author: danineamati

.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'