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
Pandas and NumPy are required.
A number of optional dependencies enable various features, such as reading data from specific activity file formats and performing geospatial calculations:
- fitparse allows data
to be read in from
.fitfiles. - activereader allows data
to be read in from
.tcxand.gpxfiles. - pandas-xyz allows geospatial calculations, like converting GPS coordinates to distance and determining elevation gain along a route.
pip install heartandsole to install.
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.
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()) # SeriesThis project is licensed under the MIT License. See LICENSE file for details.
The official documentation is hosted on readthedocs.io: https://heartandsole.readthedocs.io/en/stable.
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, 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.
You can get in touch with me at the following places:
- Website: trailzealot.com
- LinkedIn: linkedin.com/in/aarondschroeder
- Twitter: @trailzealot
- Instagram: @trailzealot
- GitHub: github.com/aaron-schroeder