Running Hills Factor

How much should a runner factor in the hills for a particular route to alter an expected finish time? Running Hills Factor calculates how much time could be expected to be gained or lost while running due to hills.

Methodology

For every percent grade value in a running route, there is a corresponding difference in expected pace per percent grade. For instance, if the route has a 3% incline, then it can be expected that a runner's pace would slow down ~15 seconds per mile per percent grade (45 seconds per mile slower). Similarly, if there is a 2% decline in the route, then it can be expected that a runner's pace would speed up ~8 seconds per mile per percent grade (16 seconds per mile faster).

• Uphill: every % grade incline slows down pace 15 seconds per mile by default (pacing done in minutes per mile)
• Downhill: every % grade decline increases pace 8 seconds per mile by default (pacing done in minutes per mile)

Running Hills Factor uses the percent grade to calculate the time gained or lost from each segment of the route provided and sums over the whole distance of the route.

Getting Started

To install Running Hills Factor, use the command:

npm install running-hills-factor

Example usage using ES modules:

import RunningHillsFactor from 'running-hills-factor';

const runningHillsFactor = new RunningHillsFactor();

runningHillsFactor.calculateHillsFactor('./example.gpx')
  .then(timeDifference => console.log('Total gained or lost time:', timeDifference))
  .catch(err => console.error('Error calculating hills factor:', err));

If you're using CommonJS modules, then you can bring in the class with:

const RunningHillsFactor = require('running-hills-factor');

const runningHillsFactor = new RunningHillsFactor();

Note: Currently, this package runs with NodeJS versions 14 or greater.

API Documentation

Running Hills Factor is designed with a class to be able to create multiple instances of the calculator with different configuration options.

For example, one instance can be configured for a runner where for every % grade incline, they slow down 12 seconds per mile. Where another instance can represent another runner where for every % grade incline, they slow down 20 seconds per mile.

class: RunningHillsFactor(options)

• options <Object>
  • inclineFactor <Number> the number of seconds per mile each % grade incline slows down. This number should be positive. Defaults to 15 (seconds).
  • declineFactor <Number> the number of seconds per mile each % grade decline speeds up. This number should be positive. Defaults to 8 (seconds).

Example options usage:

const runningHillsFactor = new RunningHillsFactor({inclineFactor: 13, declineFactor: 7});

RunningHillsFactor.calculateHillsFactor(filepath)

• filepath<String> Filepath to the running course route. Current support is for the GPX file format from https://onthegomap.com/.
• returns: <Promise> where the resolved value is the total time gained or lost in seconds, and the rejected value is an error. Time is gained if the resolved value is positive. Time is lost if the resolved value is negative.