# GradeIT
Road Grade Inference Tool (GradeIT) - a python package, developed by the National Renewable Energy Laboratory,
to append elevation and road grade to a sequence of GPS points.
## Overview
GradeIT looks up and filters elevation and derives road grade from the
[USGS Digital Elevation Model](https://www.usgs.gov/core-science-systems/ngp/3dep) to append to GPS points, typically
for vehicles traveling on paved roads. The python package offers options to use either the the freely accessible USGS
[Elevation Point Query Service](https://nationalmap.gov/epqs/) or a locally available raster database of the elevation
model, which provides much faster results.
## Setup
Clone or download the git repository.
```git clone https://github.com/NREL/gradeit.git```
gradeit depends on python 3.8 and up. One way to satisfy this is to use conda:
```bash
conda create -n gradeit python=3.8
conda activate gradeit
```
This will create a new conda environment that uses python 3.8.
Then, you can install the gradeit library
```pip install gradeit```
or if you're already in the gradeit root directory then:
```pip install .```
## Getting Started
In this repository, `docs/demo.py` will demonstrate the most basic application of the gradeit package. Additionally, the [gradeit-notebooks](https://github.com/NREL/gradeit-notebooks) repo contains various Jupyter notebooks that demonstrate gradeit applications and explore potential improvements.
## USGS Elevation Data
The United States Geological Survey offers a variety of products as a part of the [National Map](https://www.usgs.gov/core-science-systems/national-geospatial-program/national-map) project, including bare-earth elevation datasets. The 1/3 arc-second elevation dataset is continuous for the coterminous United States and is therefore used in GradeIT. As shown in ```docs/demo.ipynb``` appending elevation and grade to 1000+ points benefits significantly from having a local or network copy of the required USGS elevation data.
NREL has the 1/3 arc-second raster data downloaded to on-site compute resources for large scale needs. Individual users can access the same raster data [here](https://prd-tnm.s3.amazonaws.com/index.html?prefix=StagedProducts/Elevation/13/TIFF/current/).
### Download Script
This repository comes with a script you can use to download all of the tiles. You can use the script like this:
```bash
export OUTPUT_DIR=path/to/output/
python scripts/get_usgs_tiles.py
```
The script will then proceed to download all tiles into `path/to/output/` which can be used when running gradeit:
```python
results = gradeit(
df=df,
source="usgs-local",
usgs_db_path="path/to/output/",
)
```
## Filters
Given the spatial noise that can be present in GPS data and the 1/3 arc-second resolution of the digital elevation
model being employed, outliers and unrealistic topographical features can be present in the raw elevation profiles.
Therefore, a series of filtering procedures can be applied to the elevation data, if desired by the user. The primary
filter procedure is summarized in the figure below from Wood et al in 2014.
<img src="docs/imgs/grade_filters.png">
<sub>Wood, Eric, E. Burton, A. Duran, and J. Gonder. Appending High-Resolution Elevation Data to GPS Speed Traces for
Vehicle Energy Modeling and Simulation. No. NREL/TP-5400-61109. National Renewable Energy Lab.(NREL), Golden, CO
(United States), 2014.<sub>
Additionally, since the USGS Digital Elevation Model is a "bare earth" model, road infrastructure features (i.e.
bridges and overpasses) are often not represented in the data. Rather, the "bare earth" model represents the valley or
body of water that is being spanned. GradeIT has optional filtering routines to explicitly handle this by
"building" a bridge to span the river, valley, etc where necessary.
Raw data
{
"_id": null,
"home_page": "",
"name": "gradeit",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": "",
"keywords": "gps,elevation,road grade",
"author": "National Renewable Energy Laboratory",
"author_email": "",
"download_url": "https://files.pythonhosted.org/packages/22/ba/7fad0a01cbdfe2dfa4622bfbdd917e516547bd947751b26664a60d1f44c1/gradeit-0.1.2.tar.gz",
"platform": null,
"description": "# GradeIT\n\nRoad Grade Inference Tool (GradeIT) - a python package, developed by the National Renewable Energy Laboratory,\nto append elevation and road grade to a sequence of GPS points.\n\n## Overview\n\nGradeIT looks up and filters elevation and derives road grade from the\n[USGS Digital Elevation Model](https://www.usgs.gov/core-science-systems/ngp/3dep) to append to GPS points, typically\nfor vehicles traveling on paved roads. The python package offers options to use either the the freely accessible USGS\n[Elevation Point Query Service](https://nationalmap.gov/epqs/) or a locally available raster database of the elevation\nmodel, which provides much faster results.\n\n## Setup\n\nClone or download the git repository.\n\n```git clone https://github.com/NREL/gradeit.git```\n\ngradeit depends on python 3.8 and up. One way to satisfy this is to use conda:\n\n```bash\nconda create -n gradeit python=3.8\nconda activate gradeit\n```\n\nThis will create a new conda environment that uses python 3.8.\n\nThen, you can install the gradeit library\n\n```pip install gradeit```\n\nor if you're already in the gradeit root directory then:\n\n```pip install .```\n\n## Getting Started\n\nIn this repository, `docs/demo.py` will demonstrate the most basic application of the gradeit package. Additionally, the [gradeit-notebooks](https://github.com/NREL/gradeit-notebooks) repo contains various Jupyter notebooks that demonstrate gradeit applications and explore potential improvements.\n\n## USGS Elevation Data\n\nThe United States Geological Survey offers a variety of products as a part of the [National Map](https://www.usgs.gov/core-science-systems/national-geospatial-program/national-map) project, including bare-earth elevation datasets. The 1/3 arc-second elevation dataset is continuous for the coterminous United States and is therefore used in GradeIT. As shown in ```docs/demo.ipynb``` appending elevation and grade to 1000+ points benefits significantly from having a local or network copy of the required USGS elevation data.\n\nNREL has the 1/3 arc-second raster data downloaded to on-site compute resources for large scale needs. Individual users can access the same raster data [here](https://prd-tnm.s3.amazonaws.com/index.html?prefix=StagedProducts/Elevation/13/TIFF/current/).\n\n### Download Script\n\nThis repository comes with a script you can use to download all of the tiles. You can use the script like this:\n\n```bash\nexport OUTPUT_DIR=path/to/output/\npython scripts/get_usgs_tiles.py\n```\n\nThe script will then proceed to download all tiles into `path/to/output/` which can be used when running gradeit:\n\n```python\nresults = gradeit(\n df=df,\n source=\"usgs-local\",\n usgs_db_path=\"path/to/output/\",\n)\n```\n\n## Filters\n\nGiven the spatial noise that can be present in GPS data and the 1/3 arc-second resolution of the digital elevation\nmodel being employed, outliers and unrealistic topographical features can be present in the raw elevation profiles.\nTherefore, a series of filtering procedures can be applied to the elevation data, if desired by the user. The primary\nfilter procedure is summarized in the figure below from Wood et al in 2014.\n\n<img src=\"docs/imgs/grade_filters.png\">\n\n<sub>Wood, Eric, E. Burton, A. Duran, and J. Gonder. Appending High-Resolution Elevation Data to GPS Speed Traces for\nVehicle Energy Modeling and Simulation. No. NREL/TP-5400-61109. National Renewable Energy Lab.(NREL), Golden, CO\n(United States), 2014.<sub>\n\nAdditionally, since the USGS Digital Elevation Model is a \"bare earth\" model, road infrastructure features (i.e.\nbridges and overpasses) are often not represented in the data. Rather, the \"bare earth\" model represents the valley or\nbody of water that is being spanned. GradeIT has optional filtering routines to explicitly handle this by\n\"building\" a bridge to span the river, valley, etc where necessary.\n",
"bugtrack_url": null,
"license": "BSD 3-Clause License Copyright (c) 2020, Alliance for Sustainable Energy, LLC",
"summary": "Road Grade Inference Tool (GradeIT) appends elevation and road grade to a sequence of GPS points.",
"version": "0.1.2",
"project_urls": {
"Homepage": "https://github.com/NREL/gradeit"
},
"split_keywords": [
"gps",
"elevation",
"road grade"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "665cf93267248add86012f7d345896a7da61674e27ccdcfb2472960c32a042d4",
"md5": "5ef237c53192bb7c5986a3b1aeb51dda",
"sha256": "d5e9ea8233ef5d39d6d23c7450b90adb8c2635e38a6f86d544bcdaaa031b66cb"
},
"downloads": -1,
"filename": "gradeit-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5ef237c53192bb7c5986a3b1aeb51dda",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 13002,
"upload_time": "2023-11-11T00:12:05",
"upload_time_iso_8601": "2023-11-11T00:12:05.016773Z",
"url": "https://files.pythonhosted.org/packages/66/5c/f93267248add86012f7d345896a7da61674e27ccdcfb2472960c32a042d4/gradeit-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "22ba7fad0a01cbdfe2dfa4622bfbdd917e516547bd947751b26664a60d1f44c1",
"md5": "1ed8ab927a50b63dcfba89ffa49daa42",
"sha256": "76a2c70db5fcd3a9903b94bfdea3c88d46f5c7a22b0d61415c3ad4d78e087243"
},
"downloads": -1,
"filename": "gradeit-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "1ed8ab927a50b63dcfba89ffa49daa42",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 14171,
"upload_time": "2023-11-11T00:12:06",
"upload_time_iso_8601": "2023-11-11T00:12:06.560905Z",
"url": "https://files.pythonhosted.org/packages/22/ba/7fad0a01cbdfe2dfa4622bfbdd917e516547bd947751b26664a60d1f44c1/gradeit-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-11 00:12:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NREL",
"github_project": "gradeit",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "gradeit"
}
JSON
