https://github.com/aaron-schroeder/heartandsole
Python library for analysis of running data files
https://github.com/aaron-schroeder/heartandsole
ant fit fit-sdk fitanalysis garmin govss intensity physiology running strava trainingpeaks
Last synced: 6 months ago
JSON representation
Python library for analysis of running data files
- Host: GitHub
- URL: https://github.com/aaron-schroeder/heartandsole
- Owner: aaron-schroeder
- License: mit
- Created: 2019-08-12T19:07:38.000Z (about 6 years ago)
- Default Branch: master
- Last Pushed: 2023-02-21T16:38:51.000Z (over 2 years ago)
- Last Synced: 2025-05-07T02:02:14.067Z (6 months ago)
- Topics: ant, fit, fit-sdk, fitanalysis, garmin, govss, intensity, physiology, running, strava, trainingpeaks
- Language: Python
- Homepage:
- Size: 3.55 MB
- Stars: 12
- Watchers: 1
- Forks: 3
- Open Issues: 17
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# heartandsole: Python library for analysis of running data files
[](https://pypi.org/project/heartandsole/)
[](https://github.com/aaron-schroeder/heartandsole/blob/master/LICENSE)
[](https://www.python.org/downloads/)
## Table of Contents
- [Introduction](#introduction)
- [Dependencies](#dependencies)
- [Installation](#installation)
- [Example](#example)
- [License](#license)
- [Documentation](#documentation)
- [Contact](#contact)
## Introduction
heartandsole is designed to work with running activity files.
It reads data from `.fit`, `.tcx`, `.gpx`, and `.csv` files, converts it to
pandas data structures, then performs calculations and summarizes the data,
for example:
- elevation gain
- elapsed time
- timer time
- distance from GPS coordinates
## Dependencies
[Pandas](http://pandas.pydata.org/) and [NumPy](http://www.numpy.org/) are required.
A number of optional dependencies enable various features, such as
reading data from specific activity file formats and performing geospatial
calculations:
- [fitparse](https://github.com/dtcooper/python-fitparse) allows data
to be read in from `.fit` files.
- [activereader](https://github.com/aaron-schroeder/activereader) allows data
to be read in from `.tcx` and `.gpx` files.
- [pandas-xyz](https://github.com/aaron-schroeder/pandas-xyz) allows geospatial
calculations, like converting GPS coordinates to distance and determining
elevation gain along a route.
## Installation
`pip install heartandsole` to install.
## Example
heartandsole provides the `Activity` class.
Activities can be constructed manually with a required records DataFrame
and optional summary Series and laps DataFrame, or they can be constructed
directly from various activity file formats using `Activity.from_*` class
methods.
```python
from heartandsole import Activity
# Reading from a fit file requires the fitparse package to be
# installed.
activity = heartandsole.Activity.from_fit('my_activity.fit')
# Various field accessors provide methods related to specific data fields
# commonly found in activity files.
print(activity.time.elapsed(source='records'))
print(activity.time.timer(source='summary'))
# Geospatial calculations require pandas-xyz to be installed.
print(activity.elevation.gain(source='records')) # scalar
print(activity.distance.records_from_position()) # Series
```
## License
[](https://github.com/aaron-schroeder/heartandsole/blob/master/LICENSE)
This project is licensed under the MIT License. See
[LICENSE](https://github.com/aaron-schroeder/heartandsole/blob/master/LICENSE)
file for details.
## Documentation
The official documentation is hosted on readthedocs.io: https://heartandsole.readthedocs.io/en/stable.
## Background
My impetus for this project was to implement a version of Philip Friere Skiba's
GOVSS algorithm (with tweaks to better align with the underlying research).
The end result will be a free, open-source version of proprietary calculations
found in platforms like Strava and Training Peaks (eventually - bear with me).
My hope is that other runners will benefit as I have from taking these secret
algorithms out of their black box, by understanding the science behind these
calculations, and training smarter.
This package was originally forked from Michael Traver's
[fitanalysis package](https://github.com/mtraver/python-fitanalysis), but the two
projects diverged significantly enough for me to move my fork to a separate
repository. I am indebted to Michael for writing such a clean, useful,
easy-to-understand package that served as heartandsole's starting point.
## Contact
You can get in touch with me at the following places:
- Website: [trailzealot.com](https://trailzealot.com)
- LinkedIn: [linkedin.com/in/aarondschroeder](https://www.linkedin.com/in/aarondschroeder/)
- Twitter: [@trailzealot](https://twitter.com/trailzealot)
- Instagram: [@trailzealot](https://instagram.com/trailzealot)
- GitHub: [github.com/aaron-schroeder](https://github.com/aaron-schroeder)