Package 'tcxr'

Title: Parse and Analyze TCX Files
Description: Framework provides functions to parse 'Training Center XML (TCX)' files and extract key activity metrics such as total distance, total time, calories burned, maximum altitude, and power values (watts). This package is useful for analyzing workout and training data from devices that export 'TCX' format.
Authors: Iztok Jr. Fister [aut, cre, cph] (ORCID: <https://orcid.org/0000-0002-6418-1272>)
Maintainer: Iztok Jr. Fister <[email protected]>
License: MIT + file LICENSE
Version: 0.1.0
Built: 2026-05-18 09:41:55 UTC
Source: https://github.com/firefly-cpp/tcxr

Help Index

Parse a Lap from a TCX File

Description

Extracts summary data from a lap and also returns raw trackpoint data.

Usage

parse_lap(lap, activity_id = NA_integer_, lap_id = NA_integer_)

Arguments

lap

An XML node representing a lap in a TCX file.
activity_id

Integer activity index.
lap_id

Integer lap index within activity.

Value

A list with: - summary: dataframe containing lap summary - raw: dataframe of lap trackpoints

Parse a Trackpoint from a TCX File

Description

Extracts raw trackpoint fields into one dataframe row.

Usage

parse_trackpoint(
  trackpoint,
  activity_id = NA_integer_,
  lap_id = NA_integer_,
  trackpoint_id = NA_integer_
)

Arguments

trackpoint

An XML node representing a trackpoint.
activity_id

Integer activity index.
lap_id

Integer lap index.
trackpoint_id

Integer trackpoint index.

Value

A one-row dataframe of parsed trackpoint metrics.

Read and Parse a TCX File

Description

Parses a TCX file and returns both: 1. aggregated activity metrics 2. raw trackpoint data as a dataframe

Usage

TCXRead(file_path)

Arguments

file_path

A character string specifying the path to the TCX file.

Value

A list with: - summary: named list of aggregated metrics - raw_data: dataframe of raw TCX trackpoints

Examples

# Example usage
temp_tcx_file <- tempfile(fileext = ".tcx")
cat('<?xml version="1.0" encoding="UTF-8"?>
<TrainingCenterDatabase xmlns="http://www.garmin.com/xmlschemas/TrainingCenterDatabase/v2">
  <Activities>
    <Activity Sport="Running">
      <Lap StartTime="2024-01-01T10:00:00Z">
        <TotalTimeSeconds>1800</TotalTimeSeconds>
        <DistanceMeters>5000</DistanceMeters>
        <Calories>400</Calories>
        <Track>
          <Trackpoint>
            <Time>2024-01-01T10:00:00Z</Time>
            <DistanceMeters>0</DistanceMeters>
            <AltitudeMeters>50</AltitudeMeters>
            <Extensions>
              <TPX>
                <Speed>2.78</Speed>
                <Watts>200</Watts>
              </TPX>
            </Extensions>
            <Cadence>90</Cadence>
            <HeartRateBpm>
              <Value>150</Value>
            </HeartRateBpm>
          </Trackpoint>
        </Track>
      </Lap>
    </Activity>
  </Activities>
</TrainingCenterDatabase>', file = temp_tcx_file)

tcx_data <- TCXRead(temp_tcx_file)
tcx_data$summary
head(tcx_data$raw_data)

unlink(temp_tcx_file)