{"id":17700462,"url":"https://github.com/aaron-schroeder/py-elevation","last_synced_at":"2026-05-05T21:36:24.781Z","repository":{"id":118331065,"uuid":"332019542","full_name":"aaron-schroeder/py-elevation","owner":"aaron-schroeder","description":"Python library for working with elevation and grade time series.","archived":false,"fork":false,"pushed_at":"2021-02-12T19:12:26.000Z","size":1383,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-02-06T07:30:09.937Z","etag":null,"topics":["elevation","gis","pandas","scipy"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/aaron-schroeder.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-01-22T17:42:04.000Z","updated_at":"2021-02-12T19:48:23.000Z","dependencies_parsed_at":null,"dependency_job_id":"1319e62c-272c-4800-afb7-33611ede04f4","html_url":"https://github.com/aaron-schroeder/py-elevation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaron-schroeder%2Fpy-elevation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaron-schroeder%2Fpy-elevation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaron-schroeder%2Fpy-elevation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aaron-schroeder%2Fpy-elevation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aaron-schroeder","download_url":"https://codeload.github.com/aaron-schroeder/py-elevation/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246405740,"owners_count":20771806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elevation","gis","pandas","scipy"],"created_at":"2024-10-24T17:42:16.520Z","updated_at":"2026-05-05T21:36:19.739Z","avatar_url":"https://github.com/aaron-schroeder.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# py-elevation\n\n\u003e Python library for working with elevation and grade time series.\n\n\u003c!--[![Python 3.6](https://img.shields.io/badge/python-3.6-blue.svg)](https://www.python.org/downloads/release/python-360/)--\u003e\n[![License](http://img.shields.io/:license-mit-blue.svg)](http://badges.mit-license.org)\n\n---\n\n## Table of Contents           \n- [Table of Contents](#table-of-contents)\n- [Background](#background)\n- [Introduction](#introduction)\n- [The Elevation Smoothing Algorithm](#the-elevation-smoothing-algorithm)\n- [Dependencies and Installation](#dependencies-and-installation)\n- [Example](#example)\n- [Project Status](#project-status)\n- [Contact](#contact)\n- [License](#license)\n\n---\n\n## Background\n\nThis project originated as the part of my \n[spatialfriend package](https://github.com/aaron-schroeder/spatialfriend) that\nhandled elevation smoothing and statistics like gain and loss. Lately, I've \nbeen interested in keeping my work in more self-contained modules with lighter\ndependencies, so I split it out.\n\n---\n\n## Introduction\n\nDetermining one's elevation on Earth's surface has become a lot easier thanks\nto high-accuracy consumer GPS products and digital elevation models (DEMs) of\nEarth's topography. Still, there are errors in GPS location and in every Earth\nsurface model. When working with elevation and position time series, for example\ncalculating instantaneous slopes during a trail running workout, stricter \nrequirements are placed on the data. Even with a perfectly accurate DEM,\ninaccurate GPS data can yield totally unreasonable elevation profiles and path\nslopes, documenting work or elevation gain that the runner did not actually do.\nThe same can be said for a perfectly accurate GPS trace on an inaccurate DEM.\n\n\u003c!--The goal of this project is to take GPS data of all resolutions, and return\ngeospatial data and calculations that actually match the athlete's experience.--\u003e\nThe goal of this project is to wrangle messy or unreasonable elevation data, and\nreturn stats and time series that actually match the athlete's experience.\nNo more unreasonably steep slopes or noisy data in your elevation profile \nmaking running power calculations meaningless (if you are into that kind of \nthing). No more wondering if those elevation measurements you read on GPS device\nor barometric altimeter are accurate. No more apples to oranges data comparisons\nbecause of differences between devices or datasets.\n\n\u003c!-- This applies to py-distance, not this one: --\u003e\n\u003c!-- No more adding to your workout's distance because your GPS was drifting around while you were \nwaiting at a stoplight. --\u003e\n\n\u003c!-- This package is all about being able to hit record on that device, head\nout for your run/hike/bike ride, and forget about it. Bring that messy\nactivity file and we will process the data once it is all done. --\u003e\n\n---\n\n## The Elevation Smoothing Algorithm\n\nThe algorithm I apply to filter elevation time series is based on a paper produced by\nthe National Renewable Energy Laboratory. Their algorithm is meant to smooth the elevation\ntime series of a moving vehicle for more reasonable estimates of road grades for energy consumption\nmodels. This actually isn't that different from my end goal of smoothing elevation series for\nmore reasonable estimates of elevation gain and energy consumption by ambulating humans!\nThe paper is included in the [`resources` folder]()\n\n---\n\n## Dependencies and Installation\n\n[Pandas](http://pandas.pydata.org/) and [SciPy](https://www.scipy.org/) are required.\n\nTo install (since I am not on pypi yet), first clone this repo.\n```\ngit clone https://github.com/aaron-schroeder/py-elevation.git\n```\nNow you have a local version of this package that you can install with `pip`\n(the `setup.py` file is configured to make this work).\n\nActivate whatever virtual environment where you wish to install `elevation`,\nand then:\n```\npip install ${local_path_to_py-elevation_dir}\n```\n\n---\n\n## Example\n\n`py-elevation` provides the `elevation` package.\n\nADAPT THIS\n```python\nimport numpy as np\nimport pandas as pd\n\nimport elevation\n\n# Generate some distance coordinates that would result from moving\n# at a variable speed.\nnum_samples = 600\ndistance_series = pd.Series(\n  [2.0 * i + math.cos(0.01 * i) for i in range(num_samples)]\n)\n\n# Generate some noisy elevation coordinates with a lower-frequency\n# (genuine) signal.\nnoise_mean = 0.0\nstd = 0.5\nnoise = np.random.normal(noise_mean, std, size=num_samples)\nsignal = pd.Series(\n  [1600.0 + 100.0 * math.sin(0.01 * i) for i in range(num_samples)]\n)\nelevation_series = signal + noise\n\n# Smooth with either algorithm\nelev_dist_smooth = elevation.dist_smooth(distance_series, elevation_series)\nelev_time_smooth = elevation.time_smooth(elevation_series)\n```\n\u003c!-- # Calculate elevation gain and loss on any of the series, using your\n# choice of algorithm. --\u003e\n\n---\n\n## Project Status\n\n### Complete\n\n- Implement an algorithm to smooth noisy elevation time series.\n- Implement a smoothing algorithm for elevation series as a function of\n  distance (similar to how the completed time-smoother works.)\n\n### Current Activities\n\n- Develop and document a variety of elevation gain/loss algorithms. \n  \n- Describe the algorithms in more detail. Maybe in a wiki?\n- Provide references to papers and other resources where I got inspiration\n  for each algorithm.\n\n### Future Work\n\n- Benchmark algorithm performance (speed, accuracy, and consistency):\n   - Generate dummy time series of (distance, elevation) data to check\n     smoothing algorithm.\n   - Generate series of GPS points to obtain elevation coordinates from\n     various DEMs (using upcoming `elevation-query` package) to compare elevation\n     datasets with and without smoothing.\n- Create gain/loss algorithms to emulate those employed by \n  Strava / TrainingPeaks / Garmin.\n\n---\n\n## Contact\n\nYou can get in touch with me at the following places:\n\n\u003c!-- - Website: \u003ca href=\"https://trailzealot.com\" target=\"_blank\"\u003etrailzealot.com\u003c/a\u003e--\u003e\n- GitHub: \u003ca href=\"https://github.com/aaron-schroeder\" target=\"_blank\"\u003egithub.com/aaron-schroeder\u003c/a\u003e\n- LinkedIn: \u003ca href=\"https://www.linkedin.com/in/aarondschroeder/\" target=\"_blank\"\u003elinkedin.com/in/aarondschroeder\u003c/a\u003e\n- Twitter: \u003ca href=\"https://twitter.com/trailzealot\" target=\"_blank\"\u003e@trailzealot\u003c/a\u003e\n- Instagram: \u003ca href=\"https://instagram.com/trailzealot\" target=\"_blank\"\u003e@trailzealot\u003c/a\u003e\n\n---\n\n## License\n\n[![License](http://img.shields.io/:license-mit-blue.svg)](http://badges.mit-license.org)\n\nThis project is licensed under the MIT License. See\n[LICENSE](https://github.com/aaron-schroeder/py-activityreaders/blob/master/LICENSE)\nfile for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaron-schroeder%2Fpy-elevation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faaron-schroeder%2Fpy-elevation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faaron-schroeder%2Fpy-elevation/lists"}