Last time, we worked out how to extract, collate, and print statistics about the data contained in a FIT file. Now we’re going to take the next logical step and plot the time series data.

Start plotting with Gnu

Now that we’ve extracted data from the FIT file, what else can we do with it? Since this is time series data, the most natural next step is to visualise the data values over time. Since I know that Gnuplot handles time series data well,¹ I chose to use Chart::Gnuplot to plot the data.

An additional point in Gnuplot’s favour is that it can plot two datasets on the same graph, each with its own y-axis. Such functionality is handy when searching for correlations between datasets of different y-axis scales and ranges that share the same baseline data series.

Clearly Chart::Gnuplot relies on Gnuplot, so we need to install it first:

$ sudo apt install -y gnuplot

Now we can install Chart::Gnuplot with cpanm:

$ cpanm Chart::Gnuplot

Putting our finger on the pulse

Something I like looking at is how my heart rate evolved throughout a ride; it gives me an idea of how much effort I was putting in. So, we’ll start off by looking at how the heart rate data varied over time. In other words, we want time on the x-axis and heart rate on the y-axis.

One great thing about Gnuplot is that if you give it a format string for the time data, then plotting “just works”. In other words, explicit conversion to datetime data for the x-axis is unnecessary.

Here’s a script to extract the FIT data from our example data file. It displays some statistics about the activity and plots heart rate versus time. I’ve given the script the filename geo-fit-plot-data.pl:

  1use strict;
  2use warnings;
  3
  4use Geo::FIT;
  5use Scalar::Util qw(reftype);
  6use List::Util qw(max sum);
  7use Chart::Gnuplot;
  8
  9
 10sub main {
 11    my @activity_data = extract_activity_data();
 12
 13    show_activity_statistics(@activity_data);
 14    plot_activity_data(@activity_data);
 15}
 16
 17sub extract_activity_data {
 18    my $fit = Geo::FIT->new();
 19    $fit->file( "2025-05-08-07-58-33.fit" );
 20    $fit->open or die $fit->error;
 21
 22    my $record_callback = sub {
 23        my ($self, $descriptor, $values) = @_;
 24        my @all_field_names = $self->fields_list($descriptor);
 25
 26        my %event_data;
 27        for my $field_name (@all_field_names) {
 28            my $field_value = $self->field_value($field_name, $descriptor, $values);
 29            if ($field_value =~ /[a-zA-Z]/) {
 30                $event_data{$field_name} = $field_value;
 31            }
 32        }
 33
 34        return \%event_data;
 35    };
 36
 37    $fit->data_message_callback_by_name('record', $record_callback ) or die $fit->error;
 38
 39    my @header_things = $fit->fetch_header;
 40
 41    my $event_data;
 42    my @activity_data;
 43    do {
 44        $event_data = $fit->fetch;
 45        my $reftype = reftype $event_data;
 46        if (defined $reftype && $reftype eq 'HASH' && defined %$event_data{'timestamp'}) {
 47            push @activity_data, $event_data;
 48        }
 49    } while ( $event_data );
 50
 51    $fit->close;
 52
 53    return @activity_data;
 54}
 55
 56# extract and return the numerical parts of an array of FIT data values
 57sub num_parts {
 58    my $field_name = shift;
 59    my @activity_data = @_;
 60
 61    return map { (split ' ', $_->{$field_name})[0] } @activity_data;
 62}
 63
 64# return the average of an array of numbers
 65sub avg {
 66    my @array = @_;
 67
 68    return (sum @array) / (scalar @array);
 69}
 70
 71sub show_activity_statistics {
 72    my @activity_data = @_;
 73
 74    print "Found ", scalar @activity_data, " entries in FIT file\n";
 75    my $available_fields = join ", ", sort keys %{$activity_data[0]};
 76    print "Available fields: $available_fields\n";
 77
 78    my $total_distance_m = (split ' ', ${$activity_data[-1]}{'distance'})[0];
 79    my $total_distance = $total_distance_m/1000;
 80    print "Total distance: $total_distance km\n";
 81
 82    my @speeds = num_parts('speed', @activity_data);
 83    my $maximum_speed = max @speeds;
 84    my $maximum_speed_km = $maximum_speed*3.6;
 85    print "Maximum speed: $maximum_speed m/s = $maximum_speed_km km/h\n";
 86
 87    my $average_speed = avg(@speeds);
 88    my $average_speed_km = sprintf("%0.2f", $average_speed*3.6);
 89    $average_speed = sprintf("%0.2f", $average_speed);
 90    print "Average speed: $average_speed m/s = $average_speed_km km/h\n";
 91
 92    my @powers = num_parts('power', @activity_data);
 93    my $maximum_power = max @powers;
 94    print "Maximum power: $maximum_power W\n";
 95
 96    my $average_power = avg(@powers);
 97    $average_power = sprintf("%0.2f", $average_power);
 98    print "Average power: $average_power W\n";
 99
100    my @heart_rates = num_parts('heart_rate', @activity_data);
101    my $maximum_heart_rate = max @heart_rates;
102    print "Maximum heart rate: $maximum_heart_rate bpm\n";
103
104    my $average_heart_rate = avg(@heart_rates);
105    $average_heart_rate = sprintf("%0.2f", $average_heart_rate);
106    print "Average heart rate: $average_heart_rate bpm\n";
107}
108
109sub plot_activity_data {
110    my @activity_data = @_;
111
112    my @heart_rates = num_parts('heart_rate', @activity_data);
113    my @times = map { $_->{'timestamp'} } @activity_data;
114
115    my $date = "2025-05-08";
116
117    my $chart = Chart::Gnuplot->new(
118        output => "watopia-figure-8-heart-rate.png",
119        title  => "Figure 8 in Watopia on $date: heart rate over time",
120        xlabel => "Time",
121        ylabel => "Heart rate (bpm)",
122        terminal => "png size 1024, 768",
123        timeaxis => "x",
124        xtics => {
125            labelfmt => '%H:%M',
126        },
127    );
128
129    my $data_set = Chart::Gnuplot::DataSet->new(
130        xdata => \@times,
131        ydata => \@heart_rates,
132        timefmt => "%Y-%m-%dT%H:%M:%SZ",
133        style => "lines",
134    );
135
136    $chart->plot2d($data_set);
137}
138
139main();

A lot has happened between this code and the previous scripts. Let’s review it to see what’s changed.

The biggest changes were structural. I’ve moved the code into separate routines, improving encapsulation and making each more focused on one task.

The FIT file data extraction code I’ve put into its own routine (extract_activity_data(); lines 17-54). This sub returns the array of event data that we’ve been using.

I’ve also created two utility routines num_parts() (lines 57-62) and avg() (lines 65-69). These return the numerical parts of the activity data and average data series value, respectively.

The ride statistics calculation and display code is now located in the show_activity_statistics() routine. Now it’s out of the way, allowing us to concentrate on other things.

The plotting code is new and sits in a sub called plot_activity_data() (lines 109-137). We’ll focus much more on that later.

These routines are called from a main() routine (lines 10-15) giving us a nice bird’s eye view of what the script is trying to achieve. Running all the code is now as simple as calling main() (line 139).

Particulars of pulse plotting

Let’s zoom in on the plotting code in plot_activity_data(). After having imported Chart::Gnuplot at the top of the file (line 7), we need to do a bit of organising before we can set up the chart. We extract the activity data with extract_activity_data() (line 11) and pass this as an argument to plot_activity_data() (line 14). At the top of plot_activity_data() we fetch an array of the numerical heart rate data (line 112) and an array of all the timestamps (line 113).

The activity’s date (line 115) is assigned as a string variable because I want this to appear in the chart’s title. Although the date is present in the activity data, I’ve chosen not to calculate its value until later. This way we get the plotting code up and running sooner, as there’s still a lot to discuss.

Now we’re ready to set up the chart, which takes place on lines 117-127. We create a new Chart::Gnuplot object on line 117 and configure the plot with various keyword arguments to the object’s constructor.

The parameters are as follows:

• output specifies the name of the output file as a string. The name I’ve chosen reflects the activity as well as the data being plotted.
• title is a string to use as the plot’s title. To provide context, I mention the name of the route (Figure 8) within Zwift’s main virtual world (Watopia) as well as the date of the activity. To highlight that we’re plotting heart rate over time, I’ve mentioned this in the title also.
• xlabel is a string describing the x-axis data.
• ylabel is a string describing the y-axis data.
• the terminal option tells Gnuplot to use the PNG² “terminal”³ and to set its dimensions to 1024x768.
• timeaxis tells Gnuplot which axis contains time-based data (in this case the x-axis). This enables Gnuplot to space out the data along the axis evenly. Often, the spacing between points in time-based data isn’t regular; for instance, data points can be missing. Hence, naively plotting unevenly-spaced time data can produce a distorted graph. Telling Gnuplot that the x-axis contains time-based data allows it to add appropriate space where necessary.
• xtics is a hash of options to configure the behaviour of the ticks on the x-axis. The setting here displays hour and minute information at each tick mark for our time data. We omit the year, month and day information as this is the same for all data points.

Now that the main chart parameters have been set, we can focus on the data we want to plot. In Chart::Gnuplot parlance, a Chart::Gnuplot::DataSet object represents a set of data to plot. Lines 129-134 instantiate such an object which we later pass to the Chart::Gnuplot object when plotting the data (line 136). One configures Chart::Gnuplot::DataSet objects similarly to how Chart::Gnuplot objects are constructed: by passing various options to its constructor. These options include the data to plot and how this data should be styled on the graph.

The options used here have the following meanings:

• xdata is an array reference to the data to use for the x-axis. If this option is omitted, then Gnuplot uses the array indices of the y-data as the x-axis values.
• ydata is an array reference to the data to use for the y-axis.
• timefmt specifies the format string Gnuplot should use when reading the time data in the xdata array. Timestamps are strings and we need to inform Gnuplot how to parse them into a form useful for x-axis data. Were the x-axis data a numerical data type, this option wouldn’t be necessary.
• style is a string specifying the style to use for plotting the data. In this example, we’re plotting the data points as a set of connected lines. Check out the Chart::Gnuplot documentation for a full list of the available style options.

We finally get to plot the data on line 136. The data set gets passed to the Chart::Gnuplot object as the argument to its plot2d() method. As its name suggests, this plots 2D data, i.e. y versus x. Gnuplot can also display 3D data, in which case we’d call plot3d(). When plotting 3D data we’d have to include a z dimension when setting up the data set.

Running this code

$ perl geo-fit-plot-data.pl

generates this plot:

A couple of things are apparent when looking at this graph. It took me a while to get going (my pulse rose steadily over the first ~15 minutes of the ride) and the time is weird (6 am? Me? Lol, no). We’ll try to explain the heart rate behaviour later.

But first, what’s up with the time data? Did I really start riding at 6 o’clock in the morning? I’m not a morning person, so that’s not right. Also, I’m pretty sure my neighbours wouldn’t appreciate me coughing and wheezing at 6 am while trying to punish myself on Zwift. So what’s going on?

For those following carefully, you might have noticed the trailing Z on the timestamp data. This means that the time zone is UTC. Given that this data is from May and I live in Germany, this implies that the local time would have been 8 am. Still rather early for me, but not too early to disturb the neighbours too much.⁴ In other words, we need to fix the time zone to get the time data right.

Getting into the zone

How do we fix the time zone? I’m glad you asked! We need to parse the timestamp into a DateTime object, set the time zone, and then pass the fixed time data to Gnuplot. It turns out that the standard DateTime library doesn’t parse date/time strings. Instead, we need to use DateTime::Format::Strptime. This module parses date/time strings much like the strptime(3) POSIX function does and returns DateTime objects.

Since the module isn’t part of the core Perl distribution, we need to install it:

$ cpanm DateTime::Format::Strptime

Most of the code changes that follow take place only within the plotting routine (plot_activity_data()). So, I’m going to focus on that from now on and won’t create a new script for the new version of the code.

The first thing to do is to import the DateTime::Format::Strptime module:

 use Scalar::Util qw(reftype);
 use List::Util qw(max sum);
 use Chart::Gnuplot;
+use DateTime::Format::Strptime;

Extending plot_activity_data() to set the correct time zone, we get this code:

 1sub plot_activity_data {
 2    my @activity_data = @_;
 3
 4    # extract data to plot from full activity data
 5    my @heart_rates = num_parts('heart_rate', @activity_data);
 6    my @timestamps = map { $_->{'timestamp'} } @activity_data;
 7
 8    # fix time zone in time data
 9    my $date_parser = DateTime::Format::Strptime->new(
10        pattern => "%Y-%m-%dT%H:%M:%SZ",
11        time_zone => 'UTC',
12    );
13
14    my @times = map {
15        my $dt = $date_parser->parse_datetime($_);
16        $dt->set_time_zone('Europe/Berlin');
17        my $time_string = $dt->strftime("%H:%M:%S");
18        $time_string;
19    } @timestamps;
20
21    # determine date from timestamp data
22    my $dt = $date_parser->parse_datetime($timestamps[0]);
23    my $date = $dt->strftime("%Y-%m-%d");
24
25    # plot data
26    my $chart = Chart::Gnuplot->new(
27        output => "watopia-figure-8-heart-rate.png",
28        title  => "Figure 8 in Watopia on $date: heart rate over time",
29        xlabel => "Time",
30        ylabel => "Heart rate (bpm)",
31        terminal => "png size 1024, 768",
32        timeaxis => "x",
33        xtics => {
34            labelfmt => '%H:%M',
35        },
36    );
37
38    my $data_set = Chart::Gnuplot::DataSet->new(
39        xdata => \@times,
40        ydata => \@heart_rates,
41        timefmt => "%H:%M:%S",
42        style => "lines",
43    );
44
45    $chart->plot2d($data_set);
46}

The timestamp data is no longer read straight into the @times array; it’s stored in the @timestamps temporary array (line 6). This change also makes the variable naming a bit more consistent, which is nice.

To parse a timestamp string into a DateTime object, we need to tell DateTime::Format::Strptime how to format the timestamp (lines 8-12). This is the purpose of the pattern argument in the DateTime::Format::Strptime constructor (line 10). You might have noticed that we used the same pattern when telling Gnuplot what format the time data was in. We also specify the time zone (line 11) to ensure that the date/time data is parsed as UTC.

Next, we fix the time zone in all elements of the @timestamps array (lines 14-19). I’ve chosen to do this within a map here. I could extract this code into a well-named routine, but it does the job for now. The map parses the date/time string into a Date::Time object (line 15) and sets the time zone to Europe/Berlin⁵ (line 16). We only need to plot the time data,⁶ hence we format the DateTime object as a string including only hour, minute and second information (line 17). Even though we only use hours and minutes for the x-axis tick labels later, the time data is resolved down to the second, hence we retain the seconds information in the @times array.

One could write a more compact version of the time zone correction code like this:

my @times = map {
    $date_parser->parse_datetime($_)
        ->set_time_zone('Europe/Berlin')
        ->strftime("%H:%M:%S");
} @timestamps;

yet, in this case, I find giving each step a name (via a variable) helps the code explain itself. YMMV.

The next chunk of code (lines 22-23) isn’t related to the time zone fix. It generalises working out the current date from the activity data. This way I can use a FIT file from a different activity without having to update the $date variable by hand. The process is simple: all elements of the @timestamps array have the same date, so we choose to parse only the first one (line 22)⁷. This gives us a DateTime object which we convert into a formatted date string (via the strftime() method) composed of the year, month and day (line 23). We don’t need to fix the time zone because UTC is sufficient in this case to extract the date information. Of course, if you’re in a time zone close to the international date line you might need to set the time zone to get the correct date.

The last thing to change is the timefmt option to the Chart::Gnuplot::DataSet object on line 41. Because we now only have hour, minute and second information, we need to update the time format string to reflect this.

Now we’re ready to run the script again! Doing so

$ perl geo-fit-plot-data.pl

creates this graph

where we see that the time information is correct. Yay! 🎉

How long can this go on?

Now that I look at the graph again, I realise something: it doesn’t matter when the data was taken (at least, not for this use case). What matters more is the elapsed time from the start of the activity until the end. It looks like we need to munge the time data again. The job now is to convert the timestamp information into seconds elapsed since the ride began. Since we’ve parsed the timestamp data into DateTime objects (in line 15 above), we can convert that value into the number of seconds since the epoch (via the epoch() method). As soon as we know the epoch value for each element in the @timestamps array, we can subtract the first element’s epoch value from each element in the array. This will give us an array containing elapsed seconds since the beginning of the activity. Elapsed seconds are a bit too fine-grained for an activity extending over an hour, so we’ll also convert seconds to minutes.

Making these changes to the plot_activity_data() code, we get:

 1sub plot_activity_data {
 2    my @activity_data = @_;
 3
 4    # extract data to plot from full activity data
 5    my @heart_rates = num_parts('heart_rate', @activity_data);
 6    my @timestamps = map { $_->{'timestamp'} } @activity_data;
 7
 8    # parse timestamp data
 9    my $date_parser = DateTime::Format::Strptime->new(
10        pattern => "%Y-%m-%dT%H:%M:%SZ",
11        time_zone => 'UTC',
12    );
13
14    # get the epoch time for the first point in the time data
15    my $first_epoch_time = $date_parser->parse_datetime($timestamps[0])->epoch;
16
17    # convert timestamp data to elapsed minutes from start of activity
18    my @times = map {
19        my $dt = $date_parser->parse_datetime($_);
20        my $epoch_time = $dt->epoch;
21        my $elapsed_time = ($epoch_time - $first_epoch_time)/60;
22        $elapsed_time;
23    } @timestamps;
24
25    # determine date from timestamp data
26    my $dt = $date_parser->parse_datetime($timestamps[0]);
27    my $date = $dt->strftime("%Y-%m-%d");
28
29    # plot data
30    my $chart = Chart::Gnuplot->new(
31        output => "watopia-figure-8-heart-rate.png",
32        title  => "Figure 8 in Watopia on $date: heart rate over time",
33        xlabel => "Elapsed time (min)",
34        ylabel => "Heart rate (bpm)",
35        terminal => "png size 1024, 768",
36    );
37
38    my $data_set = Chart::Gnuplot::DataSet->new(
39        xdata => \@times,
40        ydata => \@heart_rates,
41        style => "lines",
42    );
43
44    $chart->plot2d($data_set);
45}

The main changes occur in lines 14-23. We parse the date/time information from the first timestamp (line 15), chaining the epoch() method call to find the number of seconds since the epoch. We store this result in a variable for later use; it holds the epoch time at the beginning of the data series. After parsing the timestamps into DateTime objects (line 19), we find the epoch time for each time point (line 20). Line 21 calculates the elapsed time from the time stored in $first_epoch_time and converts seconds to minutes by dividing by 60. The map returns this value (line 22) and hence @times now contains a series of elapsed time values in minutes.

It’s important to note here that we’re no longer plotting a date/time value on the x-axis; the elapsed time is a purely numerical value. Thus, we update the x-axis label string (line 33) to highlight this fact and remove the timeaxis and xtics/labelfmt options from the Chart::Gnuplot constructor. The timefmt option to the Chart::Gnuplot::DataSet constructor is also no longer necessary and it too has been removed.

The script is now ready to go!

Running it

$ perl geo-fit-plot-data.pl

gives

That’s better!

Reaching for the sky

Our statistics output from earlier told us that the maximum heart rate was 165 bpm with an average of 142 bpm. Looking at the graph, an average of 142 bpm seems about right. It also looks like the maximum pulse value occurred at an elapsed time of just short of 50 minutes. We can check that guess more closely later.

What’s intriguing me now is what caused this pattern in the heart rate data. What could have caused the values to go up and down like that? Is there a correlation with other data fields? We know from earlier that there’s an altitude field, so we can try plotting that along with the heart rate data and see how (or if) they’re related.

Careful readers might have noticed something: how can you have a variation in altitude when you’re sitting on an indoor trainer? Well, Zwift simulates going up and downhill by changing the resistance in the smart trainer. The resistance is then correlated to a gradient and, given time and speed data, one can work out a virtual altitude gain or loss. Thus, for the data set we’re analysing here, altitude is a sensible parameter to consider. Even if you had no vertical motion whatsoever!

As I mentioned earlier, one of the things I like about Gnuplot is that one can plot two data sets with different y-axes on the same plot. Plotting heart rate and altitude on the same graph is one such use case.

To plot an extra data set on our graph, we need to set up another Chart::Gnuplot::DataSet object, this time for the altitude data. Before we can do that, we’ll have to extract the altitude data from the full activity data set. Gnuplot also needs to know which data to plot on the primary and secondary y-axes (i.e. on the left- and right-hand sides of the graph). And we must remember to label our axes properly. That’s a fair bit of work, so I’ve done the hard yakka for ya. 😉

Here’s the updated plot_activity_data() code:

 1sub plot_activity_data {
 2    my @activity_data = @_;
 3
 4    # extract data to plot from full activity data
 5    my @heart_rates = num_parts('heart_rate', @activity_data);
 6    my @timestamps = map { $_->{'timestamp'} } @activity_data;
 7    my @altitudes = num_parts('altitude', @activity_data);
 8
 9    # parse timestamp data
10    my $date_parser = DateTime::Format::Strptime->new(
11        pattern => "%Y-%m-%dT%H:%M:%SZ",
12        time_zone => 'UTC',
13    );
14
15    # get the epoch time for the first point in the time data
16    my $first_epoch_time = $date_parser->parse_datetime($timestamps[0])->epoch;
17
18    # convert timestamp data to elapsed minutes from start of activity
19    my @times = map {
20        my $dt = $date_parser->parse_datetime($_);
21        my $epoch_time = $dt->epoch;
22        my $elapsed_time = ($epoch_time - $first_epoch_time)/60;
23        $elapsed_time;
24    } @timestamps;
25
26    # determine date from timestamp data
27    my $dt = $date_parser->parse_datetime($timestamps[0]);
28    my $date = $dt->strftime("%Y-%m-%d");
29
30    # plot data
31    my $chart = Chart::Gnuplot->new(
32        output => "watopia-figure-8-heart-rate-and-altitude.png",
33        title  => "Figure 8 in Watopia on $date: heart rate and altitude over time",
34        xlabel => "Elapsed time (min)",
35        ylabel => "Heart rate (bpm)",
36        terminal => "png size 1024, 768",
37        xtics => {
38            incr => 5,
39        },
40        y2label => 'Altitude (m)',
41        y2range => [-10, 70],
42        y2tics => {
43            incr => 10,
44        },
45    );
46
47    my $heart_rate_ds = Chart::Gnuplot::DataSet->new(
48        xdata => \@times,
49        ydata => \@heart_rates,
50        style => "lines",
51    );
52
53    my $altitude_ds = Chart::Gnuplot::DataSet->new(
54        xdata => \@times,
55        ydata => \@altitudes,
56        style => "boxes",
57        axes => "x1y2",
58    );
59
60    $chart->plot2d($altitude_ds, $heart_rate_ds);
61}

Line 7 extracts the altitude data from the full activity data. This code also strips the unit information from the altitude data so that we only have the numerical part, which is what Gnuplot needs. We store the altitude data in the @altitudes array. This we use later to create a Chart::Gnuplot::DataSet object on lines 53-58. An important line to note here is the axes setting on line 57; it tells Gnuplot to use the secondary y-axis on the right-hand side for this data set. I’ve chosen to use the boxes style for the altitude data (line 56) so that the output looks a bit like the hills and valleys that it represents.

To make the time data a bit easier to read and analyse, I’ve set the increment for the ticks on the x-axis to 5 (lines 37-39). This way it’ll be easier to refer to specific changes in altitude and heart rate data.

The settings for the secondary y-axis use the same names as for the primary y-axis, with the exception that the string y2 replaces y. For instance, to set the axis label for the secondary y-axis, we specify the y2label value, as in line 40 above.

I’ve set the range on the secondary y-axis explicitly (line 41) because the output looks better than what the automatic range was able to make in this case. Similarly, I’ve set the increment on the secondary y-axis ticks (lines 42-44) because the automatic output wasn’t as good as what I wanted.

I’ve also renamed the variable for the heart rate data set on line 47 to be more descriptive; the name $data_set was much too generic.

We specify the altitude data set first in the call to plot2d() (line 60) because we want the heart rate data plotted “on top” of the altitude data. Had we used $heart_rate_ds first in this call, the altitude data would have obscured part of the heart rate data.

Running our script in the now familiar way

$ perl geo-fit-plot-data.pl

gives this plot

Cool! Now it’s a bit clearer why the heart rate evolved the way it did.

At the beginning of the graph (in the first ~10 minutes) it looks like I was getting warmed up and my pulse was finding a kind of base level (~130 bpm). Then things started going uphill at about the 10-minute mark and my pulse also kept going upwards. This makes sense because I was working harder. Between about 13 minutes and 19 minutes came the first hill climb on the route and here I was riding even harder. The effort is reflected in the heart rate data which rose to around 160 bpm at the top of the hill. That explains why the heart rate went up from the beginning to roughly the 18-minute mark.

Looking back over the Zwift data for that particular ride, it seems that I took the KOM⁸ for that climb at that time, so no wonder my pulse was high!⁹ Note that this wasn’t a special record or anything like that; it was a short-term live result¹⁰ and someone else took the jersey with a faster time not long after I’d done my best time up that climb.

It was all downhill shortly after the hill climb, which also explains why the heart rate went down straight afterwards. We also see similar behaviour on the second hill climb (from about 37 minutes to 42 minutes). Although my pulse rose throughout the hill climb, it didn’t rise as high this time. This indicates that I was getting tired and wasn’t able to put as much effort in.

Just in case you’re wondering how the altitude can go negative,¹¹ part of the route goes through “underwater tunnels”. This highlights the flexibility of the virtual worlds within Zwift: the designers have enormous room to let their imaginations run wild. There are all kinds of fun things to discover along the various routes and many that don’t exist in the Real World™. Along with the underwater tunnels (where it’s like riding through a giant aquarium, with sunken shipwrecks, fish, and whales), there is a wild west style town complete with a steam train from that era chugging past. There are also Mayan ruins with llamas (or maybe alpacas?) wandering around and even a section with dinosaurs grazing at the side of the road.

Here’s what it looks like riding through an underwater tunnel:

I think that’s pretty cool.

At the end of the ride (at ~53 minutes) my pulse dropped sharply. Since this was the warm-down phase of the ride, this also makes sense.

Power to the people!

There are two peaks in the heart rate data that don’t correlate with altitude (one at ~25 minutes and another at ~48 minutes). The altitude change at these locations would suggest that things are fairly flat. What’s going on there?

One other parameter that we could consider for correlations is power output. Going uphill requires more power than riding on the flat, so we’d expect to see higher power values (and therefore higher heart rates) when climbing. If flat roads require less power, what’s causing the peaks in the pulse? Maybe there’s another puzzle hiding in the data.

Let’s combine the heart rate data with power output and see what other relationships we can discover. To do this we need to extract power output data instead of altitude data. Then we need to change the secondary y-axis data set and configuration to produce a nice plot of power output. Making these changes gives this code:

 1sub plot_activity_data {
 2    my @activity_data = @_;
 3
 4    # extract data to plot from full activity data
 5    my @heart_rates = num_parts('heart_rate', @activity_data);
 6    my @timestamps = map { $_->{'timestamp'} } @activity_data;
 7    my @powers = num_parts('power', @activity_data);
 8
 9    # parse timestamp data
10    my $date_parser = DateTime::Format::Strptime->new(
11        pattern => "%Y-%m-%dT%H:%M:%SZ",
12        time_zone => 'UTC',
13    );
14
15    # get the epoch time for the first point in the time data
16    my $first_epoch_time = $date_parser->parse_datetime($timestamps[0])->epoch;
17
18    # convert timestamp data to elapsed minutes from start of activity
19    my @times = map {
20        my $dt = $date_parser->parse_datetime($_);
21        my $epoch_time = $dt->epoch;
22        my $elapsed_time = ($epoch_time - $first_epoch_time)/60;
23        $elapsed_time;
24    } @timestamps;
25
26    # determine date from timestamp data
27    my $dt = $date_parser->parse_datetime($timestamps[0]);
28    my $date = $dt->strftime("%Y-%m-%d");
29
30    # plot data
31    my $chart = Chart::Gnuplot->new(
32        output => "watopia-figure-8-heart-rate-and-power.png",
33        title  => "Figure 8 in Watopia on $date: heart rate and power over time",
34        xlabel => "Elapsed time (min)",
35        ylabel => "Heart rate (bpm)",
36        terminal => "png size 1024, 768",
37        xtics => {
38            incr => 5,
39        },
40        ytics => {
41            mirror => "off",
42        },
43        y2label => 'Power (W)',
44        y2range => [0, 1100],
45        y2tics => {
46            incr => 100,
47        },
48    );
49
50    my $heart_rate_ds = Chart::Gnuplot::DataSet->new(
51        xdata => \@times,
52        ydata => \@heart_rates,
53        style => "lines",
54    );
55
56    my $power_ds = Chart::Gnuplot::DataSet->new(
57        xdata => \@times,
58        ydata => \@powers,
59        style => "lines",
60        axes => "x1y2",
61    );
62
63    $chart->plot2d($power_ds, $heart_rate_ds);
64}

On line 7, I swapped out the altitude data extraction code with power output. Then, I updated the output filename (line 32) and plot title (line 33) to highlight that we’re now plotting heart rate and power data.

The mirror option to the ytics setting (lines 40-42) isn’t an obvious change. Its purpose is to stop the ticks from the primary y-axis from being mirrored to the secondary y-axis (on the right-hand side). We want to stop these mirrored ticks from appearing because they’ll clash with the secondary y-axis tick marks. The reason we didn’t need this before is that all the y-axis ticks happened to line up and the issue wasn’t obvious until now.

I’ve updated the secondary axis label setting to mention power (line 43). Also, I’ve set the range to match the data we’re plotting (line 44) and to space out the data nicely via the incr option to the y2tics setting (lines 45-47). It seemed more appropriate to use lines to plot power output as opposed to the bars we used for the altitude data, hence the change to the style option on line 59.

As we did when plotting altitude, we pass the power data set ($power_ds) to the plot2d() call before $heart_rate_ds (line 63).

Running the script again

$ perl geo-fit-plot-data.pl

produces this plot:

This plot shows the correlation between heart rate and power output that we expected for the first hill climb. The power output increases steadily from the 3-minute mark up to about the 18-minute mark. After that, it dropped suddenly once I’d reached the top of the climb. This makes sense: I’d just done a personal best up that climb and needed a bit of respite!

However, now we can see clearly what caused the spikes in heart rate at 25 minutes and 48 minutes: there are two large spikes in power output. The first spike maxes out at 1023 W;¹² what value the other peak has, it’s hard to tell. We’ll try to work out what that value is later. These spikes in power result from sprints. In Zwift, not only can one try to go up hills as fast as possible, but flatter sections have sprints where one also tries to go as fast as possible, albeit for shorter distances (say 200m or 500m).

Great! We’ve worked out another puzzle in the data!

A quick comparison

Zwift produces what they call timelines of a given ride, which is much the same as what we’ve been plotting here. For instance, for the FIT file we’ve been looking at, this is the timeline graph:

Zwift plots several datasets on this graph that have very different value ranges. The plot above shows power output, cadence, heart rate, and altitude data all on one graph! A lot is going on here and because of the different data values and ranges, Zwift doesn’t display values on the y-axes. Their solution is to show all four values at a given time point when the user hovers their mouse over the graph. This solution only works within a web browser and needs lots of JavaScript to work, hence this is something I like to avoid. That (and familiarity) is largely the reason why I prefer PNG output for my graphs.

If you take a close look at the timeline graph, you’ll notice that the maximum power is given as 937 W and not 1023 W, which we worked out from the FIT file data. I don’t know what’s going on here, as the same graph in the Zwift Companion App shows the 1023 W that we got. The graph above is a screenshot from the web application in a browser on my laptop and, at least theoretically, it’s supposed to display the same data. I’ve noticed a few inconsistencies between the web browser view and that from the Zwift Companion App, so maybe this discrepancy is one bug that still needs shaking out.

A dialogue with data

Y’know what’d also be cool beyond plotting this data? Playing around with it interactively.

That’s also possible with Perl, but it’s another story.

FIT files record the activities of people using devices such as sports watches and bike head units. Platforms such as Strava and Zwift understand this now quasi-standard format. So does Perl! Here I discuss how to parse FIT files and calculate some basic statistics from the extracted data.

Gotta love that data

I love data. Geographical data, time series data, simulation data, whatever. Whenever I get my hands on a new dataset, I like to have a look at it and visualise it. This way I can get a feel for what’s available and to see what kind of information I can extract from the long lists of numbers. I guess this comes with having worked in science for so long: there’s always some interesting dataset to look at and analyse and try to understand.

I began collecting lots of data recently when I started riding my bike more. Bike head units can save all sorts of information about one’s ride. There are standard parameters such as time, position, altitude, temperature, and speed. If you have extra sensors then you can also measure power output, heart rate, and cadence. This is a wealth of information just waiting to be played with!

I’ve also recently started using Zwift¹ and there I can get even more data than on my road bike. Now I can get power and cadence data along with the rest of the various aspects of a normal training ride.

My head unit is from Garmin² and thus saves ride data in their standard FIT format. Zwift also allows you to save ride data in FIT format, so you don’t have to deal with multiple formats when reading and analysing ride data. FIT files can also be uploaded to Strava³ where you can track all the riding you’re doing in one location.

But what if you don’t want to use an online service to look at your ride data? What if you want to do this yourself, using your own tools? That’s what I’m going to talk about here: reading ride data from FIT files and analysing the resulting information.

Because I like Perl, I wondered if there are any modules available to read FIT files. It turns out that there are two: Geo::FIT and Parser::FIT. I chose to use Geo::FIT because Parser::FIT is still in alpha status. Also, Geo::FIT is quite mature with its last release in 2024, so it is still up-to-date.

The FIT format

The Garmin developer site explains all the gory details of the FIT format. The developer docs give a good high-level overview of what the format is for:

The Flexible and Interoperable Data Transfer (FIT) protocol is a format designed specifically for the storing and sharing of data that originates from sport, fitness and health devices. It is specifically designed to be compact, interoperable and extensible.

A FIT file has a well-defined structure and contains a series of records of different types. There are definition messages which describe the data appearing in the file. There are also data messages which contain the data fields storing a ride’s various parameters. Header fields contain such things as CRC information which one can use to check a file’s integrity.

Getting the prerequisites ready

As noted above, to extract the data, I’m going to use the Geo::FIT module. It’s based on the Garmin::Fit module originally by Kiyokazu Suto and later expanded upon by Matjaz Rihtar. Unfortunately, neither was ever released to CPAN. The latest releases of the Garmin::FIT code (either version) were in 2017. In contrast, Geo::FIT’s most recent release is from 2024-07-13 and it’s available on CPAN, making it easy to install. It’s great to see that someone has taken on the mantle of maintaining this codebase!

To install Geo::FIT, we’ll use cpanm:

$ cpanm Geo::FIT

Now we’re ready to start parsing FIT files and extracting their data.

Extracting data: a simple example

As mentioned earlier, FIT files store event data in data messages. Each event has various fields, depending upon the kind of device (e.g. watch or head unit) used to record the activity. More fields are possible if other peripherals are attached to the main device (e.g. power meter or heart rate monitor). We wish to extract all available event data.

To extract (and if we want to, process) the event data, Geo::FIT requires that we define a callback function and register it. Geo::FIT calls this function each time it detects a data message, allowing us to process the file in small bites as a stream of data rather than one giant blob.

Simple beginnings

A simple example should explain the process. I’m going to adapt the example mentioned in the module’s synopsis. Here’s the code (which I’ve put into a file called geo-fit-basic-data-extraction.pl):

 1use strict;
 2use warnings;
 3
 4use Geo::FIT;
 5
 6my $fit = Geo::FIT->new();
 7$fit->file( "2025-05-08-07-58-33.fit" );
 8$fit->open or die $fit->error;
 9
10my $record_callback = sub {
11    my ($self, $descriptor, $values) = @_;
12    my $time= $self->field_value( 'timestamp',     $descriptor, $values );
13    my $lat = $self->field_value( 'position_lat',  $descriptor, $values );
14    my $lon = $self->field_value( 'position_long', $descriptor, $values );
15    print "Time was: ", join("\t", $time, $lat, $lon), "\n"
16};
17
18$fit->data_message_callback_by_name('record', $record_callback ) or die $fit->error;
19
20my @header_things = $fit->fetch_header;
21
221 while ( $fit->fetch );
23
24$fit->close;

The only changes I’ve made from the original example code have been to include the strict and warnings strictures on lines 1 and 2, and to replace the $fname variable with the name of a FIT file exported from one of my recent Zwift rides (line 7).

After having imported the module (line 4), we instantiate a Geo::FIT object (line 6). We then tell Geo::FIT the name of the file to process by calling the file() method on line 7. This method returns the name of the file if it’s called without an argument. We open the file on line 8 and barf with an error if anything went wrong.

Lines 10-16 define the callback function, which must accept the given argument list. Within the callback, the field_value() method extracts the value with the given field name from the FIT data message (lines 12-14). I’ll talk about how to find out what field names are available later. In this example, we extract the timestamp as well as the latitude and longitude of where the event happened. Considering that Garmin is a company that has focused on GPS sensors, it makes sense that such data is the minimum we would expect to find in a FIT file.

On line 18 we register the callback with the Geo::FIT object. We tell it that the callback should be run whenever Geo::FIT sees a data message with the name record⁴. Again, the code barfs with an error if anything goes wrong.

The next line (line 20) looks innocuous but is actually necessary. The fetch_header() method must be called before we can fetch any data from the FIT file. Calling this method also returns header information, part of which we can use to check the file integrity. This is something we might want to use in a robust application as opposed to a simple script such as that here.

The main action takes place on line 22. We read each data message from the FIT file and–if it’s a data message with the name record–process it with our callback.

At the end (line 24), we’re good little developers and close the file.

Running this code, you’ll see lots of output whiz past. It’ll look something like this:

$ perl geo-fit-basic-data-extraction.pl
<snip>
Time was: 2025-05-08T06:53:10Z  -11.6379448 deg 166.9560685 deg
Time was: 2025-05-08T06:53:11Z  -11.6379450 deg 166.9560904 deg
Time was: 2025-05-08T06:53:12Z  -11.6379451 deg 166.9561073 deg
Time was: 2025-05-08T06:53:13Z  -11.6379452 deg 166.9561185 deg
Time was: 2025-05-08T06:53:14Z  -11.6379452 deg 166.9561232 deg
Time was: 2025-05-08T06:53:15Z  -11.6379452 deg 166.9561233 deg
Time was: 2025-05-08T06:53:16Z  -11.6379452 deg 166.9561233 deg
Time was: 2025-05-08T06:53:17Z  -11.6379452 deg 166.9561233 deg

This tells us that, at the end of my ride on Zwift, I was at a position of roughly 11°S, 167°E shortly before 07:00 UTC on the 8th of May 2025.⁵ Because Zwift has virtual worlds, this position tells little of my actual physical location at the time. Hint: my spare room (where I was riding my indoor trainer) isn’t located at this position. 😉

Getting a feel for the fields

We want to get serious, though, and not only extract position and timestamp data. There’s more in there to discover! So how do we find out what fields are available? For this task, we need to use the fields_list() method.

To extract the list of available field names, I wrote the following script, which I called geo-fit-find-field-names.pl:

 1use strict;
 2use warnings;
 3
 4use Geo::FIT;
 5use Scalar::Util qw(reftype);
 6
 7my $fit = Geo::FIT->new();
 8$fit->file( "2025-05-08-07-58-33.fit" );
 9$fit->open or die $fit->error;
10
11my $record_callback = sub {
12    my ($self, $descriptor, $values) = @_;
13    my @all_field_names = $self->fields_list($descriptor);
14
15    return \@all_field_names;
16};
17
18$fit->data_message_callback_by_name('record', $record_callback ) or die $fit->error;
19
20my @header_things = $fit->fetch_header;
21
22my $found_field_names = 0;
23do {
24    my $field_names = $fit->fetch;
25    my $reftype = reftype $field_names;
26    if (defined $reftype && $reftype eq 'ARRAY') {
27        print "Number of field names found: ", scalar @{$field_names}, "\n";
28
29        while (my @next_field_names = splice @{$field_names}, 0, 5) {
30            my $joined_field_names = join ", ", @next_field_names;
31            print $joined_field_names, "\n";
32        }
33        $found_field_names = 1;
34    }
35} while ( !$found_field_names );
36
37$fit->close;

This script extracts and prints the field names from the first data message it finds. Here, I’ve changed the callback (lines 11-16) to only return the list of all available field names by calling the fields_list() method. We return the list of field names as an array reference (line 15). While this particular change to the callback (in comparison to geo-fit-basic-data-extraction.pl, above) will do the job, it’s not very user-friendly. It will print the field names for all data messages in the FIT file, which is a lot. The list of all available field names would be repeated thousands of times! So, I changed the while loop to a do-while loop (lines 23-35), exiting as soon as the callback finds a data message containing field names.

To actually grab the field name data, I had to get a bit tricky. This is because fetch() returns different values depending upon whether the callback was called. For instance, when the callback isn’t called, the return value is 1 on success or undef. If the callback function is called, fetch() returns the callback’s return value, which in our case is the array reference to the list of field names. Hence, I’ve assigned the return value to a variable, $field_names (line 24). To ensure that we’re only processing data returned when the callback is run, we check that $field_names is defined and has a reference type of ARRAY (line 26). This we do with the help of the reftype function from Scalar::Util (line 25).

It turns out that there are 49 field names available (line 27). To format the output more nicely I spliced the array, extracting five elements at a time (line 29) and printing them as a comma-separated string (lines 30 and 31). I adapted the while (splice) pattern from the example in the Perl documentation for splice. Note that I could have printed the field names from within the callback. It doesn’t make much of a difference if we return data from the callback first before processing it or doing the processing within the callback. In this case, I chose to do the former.

Running the script gives the following output:

$ perl geo-fit-find-field-names.pl
Use of uninitialized value $emsg in string ne at /home/vagrant/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Geo/FIT.pm line 7934.
Use of uninitialized value $emsg in string ne at /home/vagrant/perl5/perlbrew/perls/perl-5.38.3/lib/site_perl/5.38.3/Geo/FIT.pm line 7992.
Number of field names found: 49
timestamp, position_lat, position_long, distance, time_from_course
total_cycles, accumulated_power, enhanced_speed, enhanced_altitude, altitude
speed, power, grade, compressed_accumulated_power, vertical_speed
calories, vertical_oscillation, stance_time_percent, stance_time, ball_speed
cadence256, total_hemoglobin_conc, total_hemoglobin_conc_min, total_hemoglobin_conc_max, saturated_hemoglobin_percent
saturated_hemoglobin_percent_min, saturated_hemoglobin_percent_max, heart_rate, cadence, compressed_speed_distance
resistance, cycle_length, temperature, speed_1s, cycles
left_right_balance, gps_accuracy, activity_type, left_torque_effectiveness, right_torque_effectiveness
left_pedal_smoothness, right_pedal_smoothness, combined_pedal_smoothness, time128, stroke_type
zone, fractional_cadence, device_index, 1_6_target_power

Note that the uninitialized value warnings are from Geo::FIT. Unfortunately, I don’t know what’s causing them. They appear whenever we fetch data from the FIT file. From now on, I’ll omit these warnings from program output in this article.

As you can see, there’s potentially a lot of information one can obtain from FIT files. I say “potentially” here because not all these fields contain valid data, as we’ll see soon. I was quite surprised at the level of detail. For instance, there are various pedal smoothness values, stroke type, and torque effectiveness parameters. Also, there’s haemoglobin information,⁶ which I guess is something one can collect given the appropriate peripheral device. What things like enhanced speed and compressed accumulated power mean, I’ve got no idea. For me, the interesting parameters are: timestamp, position_lat, position_long, distance, altitude, speed, power, calories, heart_rate, and cadence. We’ll get around to extracting and looking at these values soon.

Event data: a first impression

Let’s see what values are present in each of the fields. To do this, we’ll change the callback to collect the values in a hash with the field names as the hash keys. Then we’ll return the hash from the callback. Here’s the script I came up with (I called it geo-fit-show-single-values.pl):

 1use strict;
 2use warnings;
 3
 4use Geo::FIT;
 5use Scalar::Util qw(reftype);
 6
 7my $fit = Geo::FIT->new();
 8$fit->file( "2025-05-08-07-58-33.fit" );
 9$fit->open or die $fit->error;
10
11my $record_callback = sub {
12    my ($self, $descriptor, $values) = @_;
13    my @all_field_names = $self->fields_list($descriptor);
14
15    my %event_data;
16    for my $field_name (@all_field_names) {
17        my $field_value = $self->field_value($field_name, $descriptor, $values);
18        $event_data{$field_name} = $field_value;
19    }
20
21    return \%event_data;
22};
23
24$fit->data_message_callback_by_name('record', $record_callback ) or die $fit->error;
25
26my @header_things = $fit->fetch_header;
27
28my $found_event_data = 0;
29do {
30    my $event_data = $fit->fetch;
31    my $reftype = reftype $event_data;
32    if (defined $reftype && $reftype eq 'HASH' && defined %$event_data{'timestamp'}) {
33        for my $key ( sort keys %$event_data ) {
34            print "$key = ", $event_data->{$key}, "\n";
35        }
36        $found_event_data = 1;
37    }
38} while ( !$found_event_data );
39
40$fit->close;

The main changes here (in comparison to the previous script) involve collecting the data into a hash (lines 15-19) and later, after fetching the event data, printing it (lines 32-35).

To collect data from an individual event, we first find out what the available fields are (line 13). Then we loop over each field name (line 16), extracting the values via the field_value() method (line 17). To pass the data outside the callback, we store the value in the %event_data hash using the field name as a key (line 18). Finally, we return the event data as a hash ref (line 21).

When printing the key and value information, we again only want to print the first event that we come across. Hence we use a do-while loop and exit as soon as we’ve found appropriate event data (line 38).

Making sure that we’re only printing relevant event data is again a bit tricky. Not only do we need to make sure that the callback has returned a reference type, but we also need to check that it’s a hash. Plus, we have an extra check to make sure that we’re getting time series data by looking for the presence of the timestamp key (line 32). Without the timestamp key check, we receive data messages unrelated to the ride activity, which we obviously don’t want.

Running this new script gives this output:

$ perl geo-fit-show-single-values.pl
1_6_target_power = 0
accumulated_power = 4294967295
activity_type = 255
altitude = 4.6 m
ball_speed = 65535
cadence = 84 rpm
cadence256 = 65535
calories = 65535
combined_pedal_smoothness = 255
compressed_accumulated_power = 65535
compressed_speed_distance = 255
cycle_length = 255
cycles = 255
device_index = 255
distance = 0.56 m
enhanced_altitude = 4294967295
enhanced_speed = 4294967295
fractional_cadence = 255
gps_accuracy = 255
grade = 32767
heart_rate = 115 bpm
left_pedal_smoothness = 255
left_right_balance = 255
left_torque_effectiveness = 255
position_lat = -11.6387709 deg
position_long = 166.9487493 deg
power = 188 watts
resistance = 255
right_pedal_smoothness = 255
right_torque_effectiveness = 255
saturated_hemoglobin_percent = 65535
saturated_hemoglobin_percent_max = 65535
saturated_hemoglobin_percent_min = 65535
speed = 1.339 m/s
speed_1s = 255
stance_time = 65535
stance_time_percent = 65535
stroke_type = 255
temperature = 127
time128 = 255
time_from_course = 2147483647
timestamp = 2025-05-08T05:58:45Z
total_cycles = 4294967295
total_hemoglobin_conc = 65535
total_hemoglobin_conc_max = 65535
total_hemoglobin_conc_min = 65535
vertical_oscillation = 65535
vertical_speed = 32767
zone = 255

That’s quite a list!

What’s immediately obvious (at least, to me) is that many of the values look like maximum integer range values. For instance, activity_type = 255 suggests that this value ranges from 0 to 255, implying that it’s an 8-bit integer. Also, the numbers 65535 and 4294967295 are the maximum values of 16-bit and 32-bit integers, respectively. This “smells” of dummy values being used to fill the available keys with something other than 0. Thus, I get the feeling that we can ignore such values.

Further, most of the values that aren’t only an integer have units attached. For instance, the speed is given as 1.339 m/s and the latitude coordinate as -11.6387709 deg. Note the units associated with these values. The only value without a unit–yet is still a sensible value–is timestamp. This makes sense, as a timestamp doesn’t have a unit.

This is the next part of the puzzle to solve: we need to work out how to extract relevant event data and filter out anything containing a dummy value.

Focusing on what’s relevant

To filter out the dummy values and hence focus only on real event data, we use the fact that real event data contains a string of letters denoting the value’s unit. Thus, the event data we’re interested in has a value containing numbers and letters. Fortunately, this is also the case for the timestamp because it contains timezone information, denoted by the letter Z, meaning UTC. In other words, we can solve our problem with a regex.⁷

Another way of looking at the problem would be to realise that all the irrelevant data contains only numbers. Thus, if a data value contains a letter, we should select it. Either way, the easiest approach is to look for a letter by using a regex.

I’ve modified the script above to filter out the dummy event data and to collect valid event data into an array for the entire activity.⁸ Here’s what the code looks like now (I’ve called the file geo-fit-full-data-extraction.pl):

 1use strict;
 2use warnings;
 3
 4use Geo::FIT;
 5use Scalar::Util qw(reftype);
 6
 7my $fit = Geo::FIT->new();
 8$fit->file( "2025-05-08-07-58-33.fit" );
 9$fit->open or die $fit->error;
10
11my $record_callback = sub {
12    my ($self, $descriptor, $values) = @_;
13    my @all_field_names = $self->fields_list($descriptor);
14
15    my %event_data;
16    for my $field_name (@all_field_names) {
17        my $field_value = $self->field_value($field_name, $descriptor, $values);
18        if ($field_value =~ /[a-zA-Z]/) {
19            $event_data{$field_name} = $field_value;
20        }
21    }
22
23    return \%event_data;
24};
25
26$fit->data_message_callback_by_name('record', $record_callback ) or die $fit->error;
27
28my @header_things = $fit->fetch_header;
29
30my $event_data;
31my @activity_data;
32do {
33    $event_data = $fit->fetch;
34    my $reftype = reftype $event_data;
35    if (defined $reftype && $reftype eq 'HASH' && defined %$event_data{'timestamp'}) {
36        push @activity_data, $event_data;
37    }
38} while ( $event_data );
39
40$fit->close;
41
42print "Found ", scalar @activity_data, " entries in FIT file\n";
43my $available_fields = join ", ", sort keys %{$activity_data[0]};
44print "Available fields: $available_fields\n";

The primary difference here with respect to the previous script is the check within the callback for a letter in the field value (line 18). If that’s true, we store the field value in the %event_data hash under a key corresponding to the field name (line 19).

Later, if we have a hash and it has a timestamp key, we push the $event_data hash reference onto an array. This way we store all events related to our activity (line 36). Also, instead of checking that we got only one instance of event data, we’re now looping over all event data in the FIT file, exiting the do-while loop if $event_data is a falsey value.⁹ Note that $event_data has to be declared outside the do block. Otherwise, it won’t be in scope for the while statement and Perl will barf with a compile-time error. We also declare the @activity_data array outside the do-while loop because we want to use it later.

After processing all records in the FIT file, we display the number of data entries found (line 42) and show a list of the available (valid) fields (lines 43-44).

Running this script gives this output:¹⁰

$ perl geo-fit-full-data-extraction.pl
Found 3273 entries in FIT file
Available fields: altitude, cadence, distance, heart_rate, position_lat, position_long, power, speed, timestamp

Right now, things are fairly average

We now have the full dataset to play with! So what can we do with it? One thing that springs to mind is to calculate the maximum and average values of each data series.

Given the list of available fields, my instincts tell me that it’d be nice to know what the following parameters are:

• total distance
• max speed
• average speed
• max power
• average power
• max heart rate
• average heart rate

Let’s calculate them now.

Going the distance

Finding the total distance is very easy. Since this is a cumulative quantity, we only need to select the value in the final data point. Then we convert it to kilometres by dividing by 1000, because the distance data is in units of metres. I.e.:

my $total_distance_m = (split ' ', ${$activity_data[-1]}{'distance'})[0];
my $total_distance = $total_distance_m/1000;
print "Total distance: $total_distance km\n";

Note that since the distance field value also contains its unit, we have to split on spaces and take the first element to extract the numerical part.

Maxing out

To get maximum values (e.g. for maximum speed), we use the max function from List::Util:

1my @speeds = map { (split ' ', $_->{'speed'})[0] } @activity_data;
2my $maximum_speed = max @speeds;
3my $maximum_speed_km = $maximum_speed*3.6;
4print "Maximum speed: $maximum_speed m/s = $maximum_speed_km km/h\n";

Here, I’ve extracted all speed values from the activity data, selecting only the numerical part (line 1). I then found the maximum speed on line 2 (which is in m/s) and converted this into km/h (line 3), displaying both at the end.

An average amount of work

Getting average values is a bit more work because List::Util doesn’t provide an arithmetic mean function, commonly known as an “average”. Thus, we have to calculate this ourselves. It’s not much work, though. Here’s the code for the average speed:

1my $average_speed = (sum @speeds) / (scalar @speeds);
2my $average_speed_km = sprintf("%0.2f", $average_speed*3.6);
3$average_speed = sprintf("%0.2f", $average_speed);
4print "Average speed: $average_speed m/s = $average_speed_km km/h\n";

In this code, I’ve used the sum function from List::Util to find the sum of all speed values in the entry data (line 1). Dividing this value by the length of the array (i.e. scalar @speeds) gives the average value. Because this value will have lots of decimal places, I’ve used sprintf to show only two decimal places (this is what the "%0.2f" format statement does on line 3). Again, I’ve calculate the value in km/h (line 2) and show the average speed in both m/s and km/h.

Calculating a ride’s statistics

Extending the code to calculate and display all parameters I mentioned above, we get this:

my $total_distance_m = (split ' ', ${$activity_data[-1]}{'distance'})[0];
my $total_distance = $total_distance_m/1000;
print "Total distance: $total_distance km\n";

my @speeds = map { (split ' ', $_->{'speed'})[0] } @activity_data;
my $maximum_speed = max @speeds;
my $maximum_speed_km = $maximum_speed*3.6;
print "Maximum speed: $maximum_speed m/s = $maximum_speed_km km/h\n";

my $average_speed = (sum @speeds) / (scalar @speeds);
my $average_speed_km = sprintf("%0.2f", $average_speed*3.6);
$average_speed = sprintf("%0.2f", $average_speed);
print "Average speed: $average_speed m/s = $average_speed_km km/h\n";

my @powers = map { (split ' ', $_->{'power'})[0] } @activity_data;
my $maximum_power = max @powers;
print "Maximum power: $maximum_power W\n";

my $average_power = (sum @powers) / (scalar @powers);
$average_power = sprintf("%0.2f", $average_power);
print "Average power: $average_power W\n";

my @heart_rates = map { (split ' ', $_->{'heart_rate'})[0] } @activity_data;
my $maximum_heart_rate = max @heart_rates;
print "Maximum heart rate: $maximum_heart_rate bpm\n";

my $average_heart_rate = (sum @heart_rates) / (scalar @heart_rates);
$average_heart_rate = sprintf("%0.2f", $average_heart_rate);
print "Average heart rate: $average_heart_rate bpm\n";

If you’re following along at home–and assuming that you’ve added this code to the end of geo-fit-full-data-extraction.pl–when you run the file, you should see output like this:

$ perl geo-fit-full-data-extraction.pl
Found 3273 entries in FIT file
Available fields: altitude, cadence, distance, heart_rate, position_lat,
position_long, power, speed, timestamp
Total distance: 31.10591 km
Maximum speed: 18.802 m/s = 67.6872 km/h
Average speed: 9.51 m/s = 34.23 km/h
Maximum power: 1023 W
Average power: 274.55 W
Maximum heart rate: 165 bpm
Average heart rate: 142.20 bpm

Nice! That gives us more of a feel for the data and what we can learn from it. We can also see that I was working fairly hard on this bike ride as seen from the average power and average heart rate data.

Not so fast!

One thing to highlight about these numbers, from my experience riding both indoors and outdoors, is that the average speed on Zwift is too high. Were I riding my bike outside on the road, I’d be more likely to have an average speed of ~25 km/h, not the 34 km/h shown here. I think this discrepancy comes from Zwift not accurately converting power output into speed within the game.¹¹ I’m not sure where the discrepancy comes from. Perhaps I don’t go as hard when out on the road? Dunno.

From experience, I know that it’s easier to put in more effort over shorter periods. Thus, I’d expect the average speed to be a bit higher indoors when doing shorter sessions. Another factor is that when riding outside one has to contend with stopping at intersections and traffic lights etc. Stopping and starting brings down the average speed on outdoor rides. These considerations might explain part of the discrepancy, but I don’t think it explains it all.

Refactoring possibilities

There’s some duplication in the above code that I could remove. For instance, the code for extracting the numerical part of a data entry’s value should really be in its own function. I don’t need to map over a split each time; those are just implementation details that should hide behind a nicer interface. Also, the average value calculation would be better in its own function.

A possible refactoring to reduce this duplication could look like this:

# extract and return the numerical parts of an array of FIT data values
sub num_parts {
    my $field_name = shift;
    my @activity_data = @_;

    return map { (split ' ', $_->{$field_name})[0] } @activity_data;
}

# return the average of an array of numbers
sub avg {
    my @array = @_;

    return (sum @array) / (scalar @array);
}

which one would use like so:

my @speeds = num_parts('speed', @activity_data);
my $average_speed = avg(@speeds);

Looking into the future

Seeing numerical values of ride statistics is all well and good, but it’s much nicer to see a picture of the data. To do this, we need to plot it.

But that’s a story for another time.