Skip to main content

Python library for analysis of running activity data

Project description

heartandsole: Python library for analysis of running data files

PyPI Latest Release License Supported Python versions

Table of Contents


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 .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.


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('')

# Various field accessors provide methods related to specific data fields
# commonly found in activity files.

# Geospatial calculations require pandas-xyz to be installed.
print(activity.elevation.gain(source='records'))  # scalar
print(activity.distance.records_from_position())  # Series



This project is licensed under the MIT License. See LICENSE file for details.


The official documentation is hosted on


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:

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

heartandsole-0.0.24.tar.gz (28.4 kB view hashes)

Uploaded source

Built Distribution

heartandsole-0.0.24-py3-none-any.whl (33.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page