# GNSS-IR Real-Time Water Level Processing
[](https://opensource.org/licenses/BSD-3-Clause)
A Python-based command line tool for real-time processing of low-cost GNSS-IR (Global Navigation Satellite System Interferometric Reflectometry) water level data.
## About
This software accompanies the research article ["Real-time water levels using GNSS-IR: a potential tool for flood monitoring"](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2023GL105039) by Purnell et al., published in Geophysical Research Letters (2024).
## Installation
### From PyPI (recommended)
```bash
pip install gnssir-rt
```
### From Source
For an editable install:
```bash
git clone https://github.com/purnelldj/gnssir-rt.git
cd gnssir-rt
pip install -e .
```
## Quick Start
Here's a complete example using test data from Saint-Joseph-de-la-Rive:
### Step 1: Download Test Data
```bash
# Download the test dataset
wget https://github.com/purnelldj/gnssir-rt/raw/main/tests/data/sjdlr.zip
# Create data directory and extract to it
mkdir -p gnssir-data
unzip sjdlr.zip -d gnssir-data
```
### Step 2: Process the Data
```bash
gnssir --task arcs2splines --site_dir gnssir-data/sjdlr --config gnssir-data/sjdlr/sjdlr.yaml
```
This will generate a plot showing one day of processed water level data.
## Usage
### General Command Structure
```bash
gnssir --task TASK --site_dir SITE_DIR --config path/to/config.yaml
```
### Configuration Options
You can either change parameters directly in a configuration file or from the command line as shown below.
```bash
gnssir --task arcs2splines --site_dir gnssir-data/sjdlr --config gnssir-data/sjdlr/sjdlr.yaml \
--azilims '[190, 230]'
```
### Help and Documentation
```bash
gnssir --help # Show all available parameters
```
## Data
### Research Dataset
The complete SNR dataset used in the accompanying research paper is available on Zenodo: [10.5281/zenodo.10114719](https://doi.org/10.5281/zenodo.10114719)
To download the dataset:
```bash
pip install zenodo_get
zenodo_get 10.5281/zenodo.10114719
```
**Note:** The download is approximately 1GB.
### SNR Data Format
The software expects SNR data in a specific format similar to the [gnssrefl format](https://gnssrefl.readthedocs.io/en/latest/pages/file_structure.html#the-snr-data-format), with the following modifications:
| Column | Description |
|--------|-------------|
| 1 | Satellite number |
| 2 | Elevation angle (degrees) |
| 3 | Azimuth angle (degrees) |
| 4 | [GPS time](https://docs.astropy.org/en/stable/api/astropy.time.TimeGPS.html) (instead of seconds of day) |
| 5 | L1 SNR values |
## Contributing
We welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing new site configurations, your help is appreciated.
### How to Contribute
1. **Fork the repository** on GitHub
2. **Clone your fork** locally:
```bash
git clone https://github.com/yourusername/gnssir-rt.git
cd gnssir-rt
```
3. **Create a new branch** for your feature:
```bash
git checkout -b feature/your-feature-name
```
4. **Make your changes** and test them thoroughly
5. **Commit your changes** with clear, descriptive messages:
```bash
git commit -m "Add feature: description of your changes"
```
6. **Push to your fork** and submit a pull request
### Development Setup
For development work:
```bash
pip install -e ".[dev]" # Install with development dependencies
python -m pytest # Run tests
```
## License
This project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.
## Citation
If you use this software in your research, please cite:
```
Purnell, D., et al. (2024). Real-time water levels using GNSS-IR: a potential tool
for flood monitoring. Geophysical Research Letters.
https://doi.org/10.1029/2023GL105039
```
## Acknowledgments
- The script [make_gpt.py](./gnssir/make_gpt.py) was adapted from the [gnssrefl](https://github.com/kristinemlarson/gnssrefl) repository
- This work builds upon the broader GNSS-IR research community's contributions
## Support
- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/purnelldj/gnssir-rt/issues)
- **Discussions**: Join community discussions in [GitHub Discussions](https://github.com/purnelldj/gnssir-rt/discussions)
- **Email**: For direct inquiries, contact the maintainers
---
**Keywords:** GNSS-IR, water level monitoring, flood detection, interferometric reflectometry, remote sensing
Raw data
{
"_id": null,
"home_page": null,
"name": "gnssir-rt",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "gnss, gnss-ir, water-level, flood-monitoring, remote-sensing, interferometry",
"author": null,
"author_email": "David Purnell <davejpurnell@gmail.com>",
"download_url": "https://files.pythonhosted.org/packages/54/8a/be11006e70cf118f871e313b74e6998d7b3868081163c5429fe4d4eccd43/gnssir_rt-2.0.0.tar.gz",
"platform": null,
"description": "# GNSS-IR Real-Time Water Level Processing\n\n[](https://opensource.org/licenses/BSD-3-Clause)\n\nA Python-based command line tool for real-time processing of low-cost GNSS-IR (Global Navigation Satellite System Interferometric Reflectometry) water level data.\n\n## About\n\nThis software accompanies the research article [\"Real-time water levels using GNSS-IR: a potential tool for flood monitoring\"](https://agupubs.onlinelibrary.wiley.com/doi/full/10.1029/2023GL105039) by Purnell et al., published in Geophysical Research Letters (2024).\n\n## Installation\n\n### From PyPI (recommended)\n\n```bash\npip install gnssir-rt\n```\n\n### From Source\n\nFor an editable install:\n```bash\ngit clone https://github.com/purnelldj/gnssir-rt.git\ncd gnssir-rt\npip install -e .\n```\n\n## Quick Start\n\nHere's a complete example using test data from Saint-Joseph-de-la-Rive:\n\n### Step 1: Download Test Data\n\n```bash\n# Download the test dataset\nwget https://github.com/purnelldj/gnssir-rt/raw/main/tests/data/sjdlr.zip\n\n# Create data directory and extract to it\nmkdir -p gnssir-data\nunzip sjdlr.zip -d gnssir-data\n```\n\n### Step 2: Process the Data\n\n```bash\ngnssir --task arcs2splines --site_dir gnssir-data/sjdlr --config gnssir-data/sjdlr/sjdlr.yaml\n```\n\nThis will generate a plot showing one day of processed water level data.\n\n## Usage\n\n### General Command Structure\n\n```bash\ngnssir --task TASK --site_dir SITE_DIR --config path/to/config.yaml\n```\n\n### Configuration Options\n\nYou can either change parameters directly in a configuration file or from the command line as shown below.\n\n```bash\ngnssir --task arcs2splines --site_dir gnssir-data/sjdlr --config gnssir-data/sjdlr/sjdlr.yaml \\\n --azilims '[190, 230]'\n```\n\n### Help and Documentation\n\n```bash\ngnssir --help # Show all available parameters\n```\n\n## Data\n\n### Research Dataset\n\nThe complete SNR dataset used in the accompanying research paper is available on Zenodo: [10.5281/zenodo.10114719](https://doi.org/10.5281/zenodo.10114719)\n\nTo download the dataset:\n```bash\npip install zenodo_get\nzenodo_get 10.5281/zenodo.10114719\n```\n\n**Note:** The download is approximately 1GB.\n\n### SNR Data Format\n\nThe software expects SNR data in a specific format similar to the [gnssrefl format](https://gnssrefl.readthedocs.io/en/latest/pages/file_structure.html#the-snr-data-format), with the following modifications:\n\n| Column | Description |\n|--------|-------------|\n| 1 | Satellite number |\n| 2 | Elevation angle (degrees) |\n| 3 | Azimuth angle (degrees) |\n| 4 | [GPS time](https://docs.astropy.org/en/stable/api/astropy.time.TimeGPS.html) (instead of seconds of day) |\n| 5 | L1 SNR values |\n\n## Contributing\n\nWe welcome contributions from the community! Whether you're fixing bugs, adding features, improving documentation, or sharing new site configurations, your help is appreciated.\n\n### How to Contribute\n\n1. **Fork the repository** on GitHub\n2. **Clone your fork** locally:\n ```bash\n git clone https://github.com/yourusername/gnssir-rt.git\n cd gnssir-rt\n ```\n3. **Create a new branch** for your feature:\n ```bash\n git checkout -b feature/your-feature-name\n ```\n4. **Make your changes** and test them thoroughly\n5. **Commit your changes** with clear, descriptive messages:\n ```bash\n git commit -m \"Add feature: description of your changes\"\n ```\n6. **Push to your fork** and submit a pull request\n\n### Development Setup\n\nFor development work:\n```bash\npip install -e \".[dev]\" # Install with development dependencies\npython -m pytest # Run tests\n```\n\n## License\n\nThis project is licensed under the BSD 3-Clause License - see the [LICENSE](LICENSE) file for details.\n\n## Citation\n\nIf you use this software in your research, please cite:\n\n```\nPurnell, D., et al. (2024). Real-time water levels using GNSS-IR: a potential tool\nfor flood monitoring. Geophysical Research Letters.\nhttps://doi.org/10.1029/2023GL105039\n```\n\n## Acknowledgments\n\n- The script [make_gpt.py](./gnssir/make_gpt.py) was adapted from the [gnssrefl](https://github.com/kristinemlarson/gnssrefl) repository\n- This work builds upon the broader GNSS-IR research community's contributions\n\n## Support\n\n- **Issues**: Report bugs or request features via [GitHub Issues](https://github.com/purnelldj/gnssir-rt/issues)\n- **Discussions**: Join community discussions in [GitHub Discussions](https://github.com/purnelldj/gnssir-rt/discussions)\n- **Email**: For direct inquiries, contact the maintainers\n\n---\n\n**Keywords:** GNSS-IR, water level monitoring, flood detection, interferometric reflectometry, remote sensing\n",
"bugtrack_url": null,
"license": "BSD-3-Clause",
"summary": "Real-time processing tools for GNSS-IR water level monitoring and flood detection",
"version": "2.0.0",
"project_urls": {
"Changelog": "https://github.com/purnelldj/gnssir-rt/blob/main/CHANGELOG.md",
"Documentation": "https://github.com/purnelldj/gnssir-rt#readme",
"Homepage": "https://github.com/purnelldj/gnssir-rt",
"Issues": "https://github.com/purnelldj/gnssir-rt/issues",
"Repository": "https://github.com/purnelldj/gnssir-rt.git"
},
"split_keywords": [
"gnss",
" gnss-ir",
" water-level",
" flood-monitoring",
" remote-sensing",
" interferometry"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "87b33d38914b2ab3432a8c964fcad637472d024c2900852e6d79a20be7524093",
"md5": "f19c3308e3335b22a287eb81770e8de7",
"sha256": "c4cf7812fdb24be73c8e80bb4b2234917857370a050404f60857a113b0a07aec"
},
"downloads": -1,
"filename": "gnssir_rt-2.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f19c3308e3335b22a287eb81770e8de7",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 4421831,
"upload_time": "2025-08-24T16:49:12",
"upload_time_iso_8601": "2025-08-24T16:49:12.581949Z",
"url": "https://files.pythonhosted.org/packages/87/b3/3d38914b2ab3432a8c964fcad637472d024c2900852e6d79a20be7524093/gnssir_rt-2.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "548abe11006e70cf118f871e313b74e6998d7b3868081163c5429fe4d4eccd43",
"md5": "ea82812a4d2b4f87945865b65c6d1d1e",
"sha256": "1c83daebb3ae3b97f70e538e47b0dd7c00f3fe4533224125d2fc6c88727892a3"
},
"downloads": -1,
"filename": "gnssir_rt-2.0.0.tar.gz",
"has_sig": false,
"md5_digest": "ea82812a4d2b4f87945865b65c6d1d1e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 4322066,
"upload_time": "2025-08-24T16:49:14",
"upload_time_iso_8601": "2025-08-24T16:49:14.931010Z",
"url": "https://files.pythonhosted.org/packages/54/8a/be11006e70cf118f871e313b74e6998d7b3868081163c5429fe4d4eccd43/gnssir_rt-2.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-24 16:49:14",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "purnelldj",
"github_project": "gnssir-rt",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gnssir-rt"
}
JSON
