heartandsole: Python library for analysis of running data files

Table of Contents

• Introduction
• Dependencies
• Installation
• Example
• License
• Documentation
• 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 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 .fit files.
• activereader allows data to be read in from .tcx and .gpx files.
• 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.

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

This project is licensed under the MIT License. See 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, 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
• LinkedIn: linkedin.com/in/aarondschroeder
• Twitter: @trailzealot
• Instagram: @trailzealot
• GitHub: github.com/aaron-schroeder