activity-parser 0.9.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- activity_parser/__init__.py +12 -0
- activity_parser/parse_activity.py +281 -0
- activity_parser/parse_fit_file.py +105 -0
- activity_parser/parse_tcx_gpx.py +201 -0
- activity_parser/py.typed +0 -0
- activity_parser-0.9.0.dist-info/METADATA +97 -0
- activity_parser-0.9.0.dist-info/RECORD +9 -0
- activity_parser-0.9.0.dist-info/WHEEL +4 -0
- activity_parser-0.9.0.dist-info/licenses/LICENSE +20 -0
|
@@ -0,0 +1,12 @@
|
|
|
1
|
+
"""Parser for loading FIT, TCX and GPX files into Pandas DataFrames."""
|
|
2
|
+
|
|
3
|
+
from .parse_activity import ActivityParser
|
|
4
|
+
from .parse_fit_file import parse_fit
|
|
5
|
+
from .parse_tcx_gpx import parse_gpx, parse_tcx
|
|
6
|
+
|
|
7
|
+
__all__ = [
|
|
8
|
+
"ActivityParser",
|
|
9
|
+
"parse_fit",
|
|
10
|
+
"parse_gpx",
|
|
11
|
+
"parse_tcx",
|
|
12
|
+
]
|
|
@@ -0,0 +1,281 @@
|
|
|
1
|
+
"""Class for parsing FIT, TCX and GPX files into Pandas DataFrames."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Mapping, Sequence
|
|
4
|
+
from os import PathLike
|
|
5
|
+
from pathlib import Path
|
|
6
|
+
from typing import IO, Any
|
|
7
|
+
|
|
8
|
+
import pandas as pd
|
|
9
|
+
|
|
10
|
+
from .parse_fit_file import parse_fit
|
|
11
|
+
from .parse_tcx_gpx import parse_gpx, parse_tcx
|
|
12
|
+
|
|
13
|
+
|
|
14
|
+
def select_and_rename_cols(
|
|
15
|
+
df: pd.DataFrame,
|
|
16
|
+
selector: Sequence[str],
|
|
17
|
+
mapper: Mapping[str, str],
|
|
18
|
+
) -> pd.DataFrame:
|
|
19
|
+
"""Select and rename columns from a DataFrame."""
|
|
20
|
+
cols = [col for col in selector if col in df.columns]
|
|
21
|
+
return df.loc[:, cols].rename(columns=mapper)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
def normalize_extension(ext: str) -> str:
|
|
25
|
+
"""Normalize an extension string to one of: fit, tcx, gpx."""
|
|
26
|
+
normalized = ext.lower().lstrip(".")
|
|
27
|
+
if normalized == "gz":
|
|
28
|
+
raise ValueError("Ambiguous extension: .gz without base extension.")
|
|
29
|
+
return normalized
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def infer_extension(file: str | PathLike[str]) -> str:
|
|
33
|
+
"""Infer normalized extension from a path-like input."""
|
|
34
|
+
p = Path(file)
|
|
35
|
+
ext = p.suffix
|
|
36
|
+
if ext.lower() == ".gz":
|
|
37
|
+
ext = Path(p.stem).suffix
|
|
38
|
+
return normalize_extension(ext)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class ActivityParser:
|
|
42
|
+
"""Parser for FIT, GPX and TCX files.
|
|
43
|
+
|
|
44
|
+
Each instance of this class is a parser object that can be used to import FIT, GPX
|
|
45
|
+
and TCX files into DataFrames. During parsing, the column names in the resulting
|
|
46
|
+
DataFrames are normalized to a standard set of names to allow for more
|
|
47
|
+
interchangeable use of DataFrames from the different activity file types.
|
|
48
|
+
"""
|
|
49
|
+
|
|
50
|
+
def __init__(self, strict_xml: bool = False) -> None:
|
|
51
|
+
"""Initialize parser settings, selectors, and mappers.
|
|
52
|
+
|
|
53
|
+
Args:
|
|
54
|
+
strict_xml: If True, TCX/GPX XML parsing fails on malformed input.
|
|
55
|
+
If False, parser recovery is enabled.
|
|
56
|
+
"""
|
|
57
|
+
self.strict_xml = strict_xml
|
|
58
|
+
|
|
59
|
+
# 'Selectors' specify the list and order of columns to be copied from each
|
|
60
|
+
# DataFrame (records and laps for each file type), and 'mappers' translate the
|
|
61
|
+
# imported column names into canonical names
|
|
62
|
+
|
|
63
|
+
self.fit_records_selector = [
|
|
64
|
+
"position_lat",
|
|
65
|
+
"position_long",
|
|
66
|
+
"altitude",
|
|
67
|
+
"distance",
|
|
68
|
+
"speed",
|
|
69
|
+
"cadence",
|
|
70
|
+
"fractional_cadence",
|
|
71
|
+
"heart_rate",
|
|
72
|
+
"power",
|
|
73
|
+
"left_right_balance",
|
|
74
|
+
"accumulated_power",
|
|
75
|
+
"temperature",
|
|
76
|
+
]
|
|
77
|
+
|
|
78
|
+
self.tcx_records_selector = [
|
|
79
|
+
"LatitudeDegrees",
|
|
80
|
+
"LongitudeDegrees",
|
|
81
|
+
"AltitudeMeters",
|
|
82
|
+
"DistanceKm",
|
|
83
|
+
"Speed",
|
|
84
|
+
"Cadence",
|
|
85
|
+
"HeartRateBpm",
|
|
86
|
+
"Watts",
|
|
87
|
+
]
|
|
88
|
+
|
|
89
|
+
self.gpx_records_selector = [
|
|
90
|
+
"lat",
|
|
91
|
+
"lon",
|
|
92
|
+
"ele",
|
|
93
|
+
"speed",
|
|
94
|
+
"cad",
|
|
95
|
+
"hr",
|
|
96
|
+
"power",
|
|
97
|
+
"atemp",
|
|
98
|
+
]
|
|
99
|
+
|
|
100
|
+
self.fit_records_mapper = {
|
|
101
|
+
"position_lat": "latitude",
|
|
102
|
+
"position_long": "longitude",
|
|
103
|
+
"altitude": "altitude",
|
|
104
|
+
"distance": "distance",
|
|
105
|
+
"speed": "speed",
|
|
106
|
+
"cadence": "cadence",
|
|
107
|
+
"fractional_cadence": "fractional_cadence",
|
|
108
|
+
"heart_rate": "heart_rate",
|
|
109
|
+
"power": "power",
|
|
110
|
+
"left_right_balance": "left_right_balance",
|
|
111
|
+
"accumulated_power": "accumulated_power",
|
|
112
|
+
"temperature": "temperature",
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
self.tcx_records_mapper = {
|
|
116
|
+
"LatitudeDegrees": "latitude",
|
|
117
|
+
"LongitudeDegrees": "longitude",
|
|
118
|
+
"AltitudeMeters": "altitude",
|
|
119
|
+
"DistanceKm": "distance",
|
|
120
|
+
"Speed": "speed",
|
|
121
|
+
"Cadence": "cadence",
|
|
122
|
+
"HeartRateBpm": "heart_rate",
|
|
123
|
+
"Watts": "power",
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
self.gpx_records_mapper = {
|
|
127
|
+
"lat": "latitude",
|
|
128
|
+
"lon": "longitude",
|
|
129
|
+
"ele": "altitude",
|
|
130
|
+
"speed": "speed",
|
|
131
|
+
"cad": "cadence",
|
|
132
|
+
"hr": "heart_rate",
|
|
133
|
+
"power": "power",
|
|
134
|
+
"atemp": "temperature",
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
self.fit_laps_selector = [
|
|
138
|
+
"event",
|
|
139
|
+
"event_type",
|
|
140
|
+
"lap_trigger",
|
|
141
|
+
"start_time",
|
|
142
|
+
"total_elapsed_time",
|
|
143
|
+
"total_timer_time",
|
|
144
|
+
"start_position_lat",
|
|
145
|
+
"start_position_long",
|
|
146
|
+
"end_position_lat",
|
|
147
|
+
"end_position_long",
|
|
148
|
+
"total_distance",
|
|
149
|
+
"total_ascent",
|
|
150
|
+
"total_descent",
|
|
151
|
+
"avg_vam",
|
|
152
|
+
"avg_speed",
|
|
153
|
+
"max_speed",
|
|
154
|
+
"avg_cadence",
|
|
155
|
+
"max_cadence",
|
|
156
|
+
"avg_fractional_cadence",
|
|
157
|
+
"max_fractional_cadence",
|
|
158
|
+
"total_strokes",
|
|
159
|
+
"avg_heart_rate",
|
|
160
|
+
"max_heart_rate",
|
|
161
|
+
"time_in_hr_zone",
|
|
162
|
+
"avg_power",
|
|
163
|
+
"max_power",
|
|
164
|
+
"normalized_power",
|
|
165
|
+
"left_right_balance",
|
|
166
|
+
"time_in_power_zone",
|
|
167
|
+
"total_work",
|
|
168
|
+
"avg_temperature",
|
|
169
|
+
"max_temperature",
|
|
170
|
+
"total_calories",
|
|
171
|
+
"total_fat_calories",
|
|
172
|
+
"sport",
|
|
173
|
+
"sub_sport",
|
|
174
|
+
]
|
|
175
|
+
|
|
176
|
+
self.tcx_laps_selector = [
|
|
177
|
+
"TriggerMethod",
|
|
178
|
+
"StartTime",
|
|
179
|
+
"TotalTimeSeconds",
|
|
180
|
+
"DistanceKm",
|
|
181
|
+
"AvgSpeed",
|
|
182
|
+
"MaximumSpeed",
|
|
183
|
+
"Cadence",
|
|
184
|
+
"MaxBikeCadence",
|
|
185
|
+
"AverageHeartRateBpm",
|
|
186
|
+
"MaximumHeartRateBpm",
|
|
187
|
+
"AvgWatts",
|
|
188
|
+
"MaxWatts",
|
|
189
|
+
"Calories",
|
|
190
|
+
]
|
|
191
|
+
|
|
192
|
+
# Just use the FIT names for lap data as canonical
|
|
193
|
+
self.fit_laps_mapper = {}
|
|
194
|
+
|
|
195
|
+
self.tcx_laps_mapper = {
|
|
196
|
+
"TriggerMethod": "lap_trigger",
|
|
197
|
+
"StartTime": "start_time",
|
|
198
|
+
"TotalTimeSeconds": "total_elapsed_time",
|
|
199
|
+
"DistanceKm": "total_distance",
|
|
200
|
+
"AvgSpeed": "avg_speed",
|
|
201
|
+
"MaximumSpeed": "max_speed",
|
|
202
|
+
"Cadence": "avg_cadence",
|
|
203
|
+
"MaxBikeCadence": "max_cadence",
|
|
204
|
+
"AverageHeartRateBpm": "avg_heart_rate",
|
|
205
|
+
"MaximumHeartRateBpm": "max_heart_rate",
|
|
206
|
+
"AvgWatts": "avg_power",
|
|
207
|
+
"MaxWatts": "max_power",
|
|
208
|
+
"Calories": "total_calories",
|
|
209
|
+
}
|
|
210
|
+
|
|
211
|
+
def parse(
|
|
212
|
+
self,
|
|
213
|
+
file: str | PathLike[str] | IO[bytes],
|
|
214
|
+
ext: str | None = None,
|
|
215
|
+
) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
|
|
216
|
+
"""Loads a FIT, TCX or GPX activity into Pandas DataFrames.
|
|
217
|
+
|
|
218
|
+
During import, column names in ``records`` and ``laps`` are normalized into a
|
|
219
|
+
canonical set of names. Note this function does not guarantee that all canonical
|
|
220
|
+
columns appear in the output, it only renames the columns that are present in
|
|
221
|
+
the activity file.
|
|
222
|
+
|
|
223
|
+
Args:
|
|
224
|
+
file: Binary file-like or path-like object. A path-like argument ending in
|
|
225
|
+
``.gz`` will be unzipped before processing.
|
|
226
|
+
ext: File type, case-insensitive: ``fit``, ``tcx``, or ``gpx``. Required for
|
|
227
|
+
a file-like ``file``; optional for a path-like ``file`` (inferred from
|
|
228
|
+
the name).
|
|
229
|
+
|
|
230
|
+
Returns:
|
|
231
|
+
Tuple containing records, laps, and selected extra metadata.
|
|
232
|
+
"""
|
|
233
|
+
if ext is not None:
|
|
234
|
+
ext_normalized = normalize_extension(ext)
|
|
235
|
+
elif isinstance(file, (str, PathLike)):
|
|
236
|
+
ext_normalized = infer_extension(file)
|
|
237
|
+
else:
|
|
238
|
+
raise ValueError("ext must be provided when file is a file-like object.")
|
|
239
|
+
|
|
240
|
+
if ext_normalized == "fit":
|
|
241
|
+
records, laps, extra = parse_fit(file)
|
|
242
|
+
records = select_and_rename_cols(
|
|
243
|
+
records,
|
|
244
|
+
self.fit_records_selector,
|
|
245
|
+
self.fit_records_mapper,
|
|
246
|
+
)
|
|
247
|
+
records.rename_axis("time", inplace=True)
|
|
248
|
+
laps = select_and_rename_cols(
|
|
249
|
+
laps,
|
|
250
|
+
self.fit_laps_selector,
|
|
251
|
+
self.fit_laps_mapper,
|
|
252
|
+
)
|
|
253
|
+
|
|
254
|
+
elif ext_normalized == "tcx":
|
|
255
|
+
records, laps, extra = parse_tcx(file, strict_xml=self.strict_xml)
|
|
256
|
+
records = select_and_rename_cols(
|
|
257
|
+
records,
|
|
258
|
+
self.tcx_records_selector,
|
|
259
|
+
self.tcx_records_mapper,
|
|
260
|
+
)
|
|
261
|
+
records.rename_axis("time", inplace=True)
|
|
262
|
+
laps = select_and_rename_cols(
|
|
263
|
+
laps,
|
|
264
|
+
self.tcx_laps_selector,
|
|
265
|
+
self.tcx_laps_mapper,
|
|
266
|
+
)
|
|
267
|
+
|
|
268
|
+
elif ext_normalized == "gpx":
|
|
269
|
+
records, laps, extra = parse_gpx(file, strict_xml=self.strict_xml)
|
|
270
|
+
records = select_and_rename_cols(
|
|
271
|
+
records,
|
|
272
|
+
self.gpx_records_selector,
|
|
273
|
+
self.gpx_records_mapper,
|
|
274
|
+
)
|
|
275
|
+
records.rename_axis("time", inplace=True)
|
|
276
|
+
# Note GPX files have no lap information
|
|
277
|
+
|
|
278
|
+
else:
|
|
279
|
+
raise ValueError(f"File type not supported: {ext_normalized}")
|
|
280
|
+
|
|
281
|
+
return records, laps, extra
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
"""Functions for parsing FIT files into Pandas DataFrames."""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
|
|
5
|
+
import gzip
|
|
6
|
+
from collections.abc import Iterator
|
|
7
|
+
from os import PathLike
|
|
8
|
+
from pathlib import Path
|
|
9
|
+
from typing import IO, TYPE_CHECKING, Any
|
|
10
|
+
|
|
11
|
+
import fitdecode
|
|
12
|
+
import pandas as pd
|
|
13
|
+
|
|
14
|
+
if TYPE_CHECKING:
|
|
15
|
+
from _typeshed import SupportsRead
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def copy_fit_frames(
|
|
19
|
+
fit_file: SupportsRead[bytes],
|
|
20
|
+
) -> Iterator[fitdecode.FitDataMessage]:
|
|
21
|
+
"""Yields FIT data frames from a file-like object."""
|
|
22
|
+
processor = fitdecode.StandardUnitsDataProcessor()
|
|
23
|
+
for frame in fitdecode.FitReader(fit_file, processor=processor):
|
|
24
|
+
if isinstance(frame, fitdecode.FitDataMessage) and frame.mesg_type is not None:
|
|
25
|
+
yield frame
|
|
26
|
+
|
|
27
|
+
|
|
28
|
+
def frame_to_dict(frame: fitdecode.FitDataMessage) -> dict[str, Any]:
|
|
29
|
+
"""Convert one FIT frame to a dict, dropping unknown fields."""
|
|
30
|
+
return {field.name: field.value for field in frame.fields if field.field is not None}
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
def parse_fit_frames(
|
|
34
|
+
fit_file: SupportsRead[bytes],
|
|
35
|
+
) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
|
|
36
|
+
"""Parse FIT frames from an open file object."""
|
|
37
|
+
records_rows: list[dict[str, Any]] = []
|
|
38
|
+
laps_rows: list[dict[str, Any]] = []
|
|
39
|
+
extra_rows: dict[str, list[dict[str, Any]]] = {}
|
|
40
|
+
|
|
41
|
+
for frame in copy_fit_frames(fit_file):
|
|
42
|
+
row = frame_to_dict(frame)
|
|
43
|
+
if frame.name == "record":
|
|
44
|
+
records_rows.append(row)
|
|
45
|
+
elif frame.name == "lap":
|
|
46
|
+
laps_rows.append(row)
|
|
47
|
+
else:
|
|
48
|
+
extra_rows.setdefault(frame.name, []).append(row)
|
|
49
|
+
|
|
50
|
+
records = pd.DataFrame(records_rows)
|
|
51
|
+
|
|
52
|
+
# None-valued fields cause object dtype; coerce numeric columns to float64.
|
|
53
|
+
for col in records.select_dtypes(include="object").columns:
|
|
54
|
+
coerced = pd.to_numeric(records[col], errors="coerce")
|
|
55
|
+
if coerced.notna().sum() == records[col].notna().sum():
|
|
56
|
+
records[col] = coerced
|
|
57
|
+
|
|
58
|
+
# FIT files occasionally have duplicate timestamps.
|
|
59
|
+
if "timestamp" in records.columns:
|
|
60
|
+
records = records.set_index("timestamp")
|
|
61
|
+
else:
|
|
62
|
+
records.index = pd.Index(records.index, name="timestamp")
|
|
63
|
+
|
|
64
|
+
records = records[records.index.notna()]
|
|
65
|
+
records = records[~records.index.duplicated()]
|
|
66
|
+
|
|
67
|
+
laps = pd.DataFrame(laps_rows)
|
|
68
|
+
|
|
69
|
+
extra: dict[str, Any] = {}
|
|
70
|
+
for name, rows in extra_rows.items():
|
|
71
|
+
if len(rows) == 1:
|
|
72
|
+
extra[name] = rows[0]
|
|
73
|
+
else:
|
|
74
|
+
extra[name] = pd.DataFrame(rows)
|
|
75
|
+
|
|
76
|
+
return records, laps, extra
|
|
77
|
+
|
|
78
|
+
|
|
79
|
+
def parse_fit(
|
|
80
|
+
file: str | PathLike[str] | IO[bytes],
|
|
81
|
+
) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, Any]]:
|
|
82
|
+
"""Loads a FIT activity into Pandas DataFrames.
|
|
83
|
+
|
|
84
|
+
FIT frames and data fields that are marked as 'unknown' by fitdecode are dropped
|
|
85
|
+
during import. Assumes that the FIT file is all one activity, i.e. chained FIT files
|
|
86
|
+
will be merged into one set of return values.
|
|
87
|
+
|
|
88
|
+
Args:
|
|
89
|
+
file: File-like or path-like object. A path-like argument ending in ``.gz`` will
|
|
90
|
+
be unzipped before processing.
|
|
91
|
+
|
|
92
|
+
Returns:
|
|
93
|
+
Tuple containing records, laps, and additional metadata.
|
|
94
|
+
"""
|
|
95
|
+
is_path = isinstance(file, (str, PathLike))
|
|
96
|
+
|
|
97
|
+
if is_path:
|
|
98
|
+
ext = Path(file).suffix
|
|
99
|
+
opener = gzip.open if ext.lower() == ".gz" else open
|
|
100
|
+
with opener(file, "rb") as fit_file:
|
|
101
|
+
records, laps, extra = parse_fit_frames(fit_file)
|
|
102
|
+
else:
|
|
103
|
+
records, laps, extra = parse_fit_frames(file)
|
|
104
|
+
|
|
105
|
+
return records, laps, extra
|
|
@@ -0,0 +1,201 @@
|
|
|
1
|
+
"""Functions for parsing TCX and GPX files into Pandas DataFrames."""
|
|
2
|
+
|
|
3
|
+
from collections.abc import Iterator
|
|
4
|
+
from os import PathLike
|
|
5
|
+
from typing import IO, cast
|
|
6
|
+
|
|
7
|
+
import pandas as pd
|
|
8
|
+
from lxml import etree
|
|
9
|
+
|
|
10
|
+
NUMERIC_EXACT_COLUMNS = {
|
|
11
|
+
"lat",
|
|
12
|
+
"lon",
|
|
13
|
+
"ele",
|
|
14
|
+
"hr",
|
|
15
|
+
"cad",
|
|
16
|
+
"power",
|
|
17
|
+
"atemp",
|
|
18
|
+
"speed",
|
|
19
|
+
"Watts",
|
|
20
|
+
"DistanceMeters",
|
|
21
|
+
"AltitudeMeters",
|
|
22
|
+
"HeartRateBpm",
|
|
23
|
+
"Cadence",
|
|
24
|
+
"LatitudeDegrees",
|
|
25
|
+
"LongitudeDegrees",
|
|
26
|
+
"TotalTimeSeconds",
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
NUMERIC_SUBSTRINGS = (
|
|
30
|
+
"Distance",
|
|
31
|
+
"Speed",
|
|
32
|
+
"Altitude",
|
|
33
|
+
"Cadence",
|
|
34
|
+
"HeartRate",
|
|
35
|
+
"Watts",
|
|
36
|
+
"Power",
|
|
37
|
+
"Calories",
|
|
38
|
+
)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
def should_coerce_numeric(column_name: str) -> bool:
|
|
42
|
+
"""Return True when an XML-derived column should be numeric."""
|
|
43
|
+
if column_name in NUMERIC_EXACT_COLUMNS:
|
|
44
|
+
return True
|
|
45
|
+
return any(token in column_name for token in NUMERIC_SUBSTRINGS)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def remove_elements(root: etree._Element, *tags: str) -> None:
|
|
49
|
+
"""Remove all elements matching ``tags`` from the tree."""
|
|
50
|
+
for element in root.iter(*tags):
|
|
51
|
+
parent = element.getparent()
|
|
52
|
+
if parent is not None:
|
|
53
|
+
parent.remove(element)
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def extract_xml_fields(
|
|
57
|
+
element: etree._Element,
|
|
58
|
+
) -> Iterator[tuple[str, str | None]]:
|
|
59
|
+
"""Yields (name, value) pairs recursively through an XML element."""
|
|
60
|
+
# Iterating with "*" matches only true elements and drops e.g. comments
|
|
61
|
+
for el in element.iter("*"):
|
|
62
|
+
# Some (name, value) pairs are stored as XML attributes
|
|
63
|
+
for key, value in el.attrib.items():
|
|
64
|
+
localname = etree.QName(key).localname
|
|
65
|
+
if localname != "type":
|
|
66
|
+
yield localname, cast(str, value)
|
|
67
|
+
|
|
68
|
+
# In a TCX file, some values are buried in a 'Value' element
|
|
69
|
+
if el.text is None or el.text.isspace():
|
|
70
|
+
try:
|
|
71
|
+
child = next(el.iterchildren("*"))
|
|
72
|
+
parent_localname = etree.QName(el).localname
|
|
73
|
+
child_localname = etree.QName(child).localname
|
|
74
|
+
if child_localname == "Value":
|
|
75
|
+
yield parent_localname, child.text
|
|
76
|
+
except StopIteration:
|
|
77
|
+
pass
|
|
78
|
+
|
|
79
|
+
# But most values are recorded as leaf element text
|
|
80
|
+
else:
|
|
81
|
+
localname = etree.QName(el).localname
|
|
82
|
+
if localname != "Value":
|
|
83
|
+
yield localname, el.text
|
|
84
|
+
|
|
85
|
+
|
|
86
|
+
def cleanup_xml_dataframe(df: pd.DataFrame, time_col: str) -> pd.DataFrame:
|
|
87
|
+
"""Common post-processing for DataFrames extracted from XML elements."""
|
|
88
|
+
for col in df.columns:
|
|
89
|
+
if col == time_col or not should_coerce_numeric(str(col)):
|
|
90
|
+
continue
|
|
91
|
+
|
|
92
|
+
values = df[col]
|
|
93
|
+
non_null = values.notna().sum()
|
|
94
|
+
if non_null == 0:
|
|
95
|
+
continue
|
|
96
|
+
|
|
97
|
+
numeric_values = pd.to_numeric(values, errors="coerce")
|
|
98
|
+
if numeric_values.notna().sum() == non_null:
|
|
99
|
+
df[col] = numeric_values
|
|
100
|
+
|
|
101
|
+
if time_col in df.columns:
|
|
102
|
+
# Without format="ISO8601", timestamps mixing naive and UTC-offset values in
|
|
103
|
+
# the same column silently become NaT instead of parsing.
|
|
104
|
+
df[time_col] = pd.to_datetime(df[time_col], errors="coerce", utc=True, format="ISO8601")
|
|
105
|
+
else:
|
|
106
|
+
df[time_col] = pd.NaT
|
|
107
|
+
|
|
108
|
+
# Conversion from meters and m/s to km and kph is done to align with processing done
|
|
109
|
+
# by fitdecode.StandardUnitsDataProcessor
|
|
110
|
+
for col in df.columns:
|
|
111
|
+
# Columns that failed numeric coercion above are still strings; leave them as-is
|
|
112
|
+
if not pd.api.types.is_numeric_dtype(df[col]):
|
|
113
|
+
continue
|
|
114
|
+
if "distance" in col.lower():
|
|
115
|
+
df[col] = df[col] / 1000.0
|
|
116
|
+
df = df.rename(columns={col: col.replace("Meters", "Km")})
|
|
117
|
+
if "speed" in col.lower():
|
|
118
|
+
df[col] = df[col] * 60.0 * 60.0 / 1000.0
|
|
119
|
+
|
|
120
|
+
return df
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
def parse_tcx(
|
|
124
|
+
file: str | PathLike[str] | IO[str] | IO[bytes],
|
|
125
|
+
strict_xml: bool = False,
|
|
126
|
+
) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, str | None]]:
|
|
127
|
+
"""Loads a TCX activity into Pandas DataFrames.
|
|
128
|
+
|
|
129
|
+
Assumes that the TCX file is all one activity. Files with multiple activities will
|
|
130
|
+
be merged into one set of return values, possibly over-writing some fields.
|
|
131
|
+
|
|
132
|
+
Args:
|
|
133
|
+
file: File-like or path-like object. A path-like argument ending in ``.gz`` will
|
|
134
|
+
be transparently unzipped before processing.
|
|
135
|
+
strict_xml: If True, fail on XML parsing errors instead of recovering.
|
|
136
|
+
|
|
137
|
+
Returns:
|
|
138
|
+
Tuple containing records, laps, and additional metadata.
|
|
139
|
+
"""
|
|
140
|
+
# lxml takes care of identifying and handling a gzipped file
|
|
141
|
+
parser = etree.XMLParser(recover=not strict_xml)
|
|
142
|
+
root = etree.parse(file, parser).getroot()
|
|
143
|
+
|
|
144
|
+
# TCX files occasionally have duplicate timestamps, just drop those
|
|
145
|
+
records = pd.DataFrame(
|
|
146
|
+
dict(extract_xml_fields(element)) for element in root.iter("{*}Trackpoint")
|
|
147
|
+
)
|
|
148
|
+
records = cleanup_xml_dataframe(records, "Time").set_index("Time")
|
|
149
|
+
records = records[records.index.notna()]
|
|
150
|
+
records = records[~records.index.duplicated()]
|
|
151
|
+
|
|
152
|
+
remove_elements(root, "{*}Track")
|
|
153
|
+
|
|
154
|
+
laps = pd.DataFrame(dict(extract_xml_fields(element)) for element in root.iter("{*}Lap"))
|
|
155
|
+
laps = cleanup_xml_dataframe(laps, "StartTime")
|
|
156
|
+
|
|
157
|
+
remove_elements(root, "{*}Lap")
|
|
158
|
+
|
|
159
|
+
extra = dict(extract_xml_fields(root))
|
|
160
|
+
extra.pop("schemaLocation", None)
|
|
161
|
+
|
|
162
|
+
return records, laps, extra
|
|
163
|
+
|
|
164
|
+
|
|
165
|
+
def parse_gpx(
|
|
166
|
+
file: str | PathLike[str] | IO[str] | IO[bytes],
|
|
167
|
+
strict_xml: bool = False,
|
|
168
|
+
) -> tuple[pd.DataFrame, pd.DataFrame, dict[str, str | None]]:
|
|
169
|
+
"""Loads a GPX activity into a Pandas DataFrame.
|
|
170
|
+
|
|
171
|
+
Assumes that the GPX file is all one activity. Files with multiple tracks will be
|
|
172
|
+
merged into one set of return values, possibly over-writing some fields. Waypoints
|
|
173
|
+
and routes in the GPX file are ignored.
|
|
174
|
+
|
|
175
|
+
Args:
|
|
176
|
+
file: File-like or path-like object. A path-like argument ending in ``.gz`` will
|
|
177
|
+
be transparently unzipped before processing.
|
|
178
|
+
strict_xml: If True, fail on XML parsing errors instead of recovering.
|
|
179
|
+
|
|
180
|
+
Returns:
|
|
181
|
+
Tuple containing records, laps, and additional metadata. Note GPX files don't
|
|
182
|
+
have lap information, so the laps DataFrame will be empty.
|
|
183
|
+
"""
|
|
184
|
+
# Note there is a 'gpxpy' library that provides comprehensive handling of GPX files.
|
|
185
|
+
# Parsing the XML directly works for our purposes and keeps this consistent with
|
|
186
|
+
# how we handle TCX files above.
|
|
187
|
+
|
|
188
|
+
parser = etree.XMLParser(recover=not strict_xml)
|
|
189
|
+
root = etree.parse(file, parser).getroot()
|
|
190
|
+
|
|
191
|
+
records = pd.DataFrame(dict(extract_xml_fields(element)) for element in root.iter("{*}trkpt"))
|
|
192
|
+
records = cleanup_xml_dataframe(records, "time").set_index("time")
|
|
193
|
+
records = records[records.index.notna()]
|
|
194
|
+
records = records[~records.index.duplicated()]
|
|
195
|
+
|
|
196
|
+
remove_elements(root, "{*}trkseg", "{*}rte", "{*}wpt")
|
|
197
|
+
|
|
198
|
+
extra = dict(extract_xml_fields(root))
|
|
199
|
+
extra.pop("schemaLocation", None)
|
|
200
|
+
|
|
201
|
+
return records, pd.DataFrame(), extra
|
activity_parser/py.typed
ADDED
|
File without changes
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: activity-parser
|
|
3
|
+
Version: 0.9.0
|
|
4
|
+
Summary: Parser for loading FIT, TCX and GPX files into Pandas DataFrames.
|
|
5
|
+
Project-URL: Repository, https://github.com/tabishm52/activity_parser
|
|
6
|
+
Project-URL: Issues, https://github.com/tabishm52/activity_parser/issues
|
|
7
|
+
Author-email: Tabish Mustufa <tabishm@gmail.com>
|
|
8
|
+
License-Expression: MIT
|
|
9
|
+
License-File: LICENSE
|
|
10
|
+
Keywords: fit,fitness,gps,gpx,pandas,parser,tcx
|
|
11
|
+
Classifier: Development Status :: 4 - Beta
|
|
12
|
+
Classifier: Intended Audience :: Developers
|
|
13
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
14
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
15
|
+
Classifier: Programming Language :: Python :: 3.13
|
|
16
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
17
|
+
Classifier: Topic :: Scientific/Engineering :: GIS
|
|
18
|
+
Requires-Python: >=3.11
|
|
19
|
+
Requires-Dist: fitdecode
|
|
20
|
+
Requires-Dist: lxml
|
|
21
|
+
Requires-Dist: pandas
|
|
22
|
+
Description-Content-Type: text/markdown
|
|
23
|
+
|
|
24
|
+
# activity-parser
|
|
25
|
+
|
|
26
|
+
[](https://github.com/tabishm52/activity_parser/actions/workflows/ci.yml)
|
|
27
|
+
|
|
28
|
+
Parser for loading FIT, TCX and GPX activity files into Pandas DataFrames.
|
|
29
|
+
|
|
30
|
+
Provides a parser object for reading (optionally gzipped) FIT, TCX, and GPX activity files and converting them into Pandas DataFrames.
|
|
31
|
+
During import, column names extracted from activity files are normalized into a canonical set of output column names.
|
|
32
|
+
|
|
33
|
+
## Installation
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
pip install activity-parser
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
## Usage
|
|
40
|
+
|
|
41
|
+
Create a new instance of the `ActivityParser` class to be reused for subsequent parsing of activity files:
|
|
42
|
+
|
|
43
|
+
```python
|
|
44
|
+
import activity_parser
|
|
45
|
+
parser = activity_parser.ActivityParser()
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Parse FIT, TCX and GPX files into normalized DataFrames:
|
|
49
|
+
|
|
50
|
+
```python
|
|
51
|
+
records, laps, extra = parser.parse('path/to/fit_file.fit')
|
|
52
|
+
records, laps, extra = parser.parse('path/to/gpx_file.gpx')
|
|
53
|
+
records, laps, extra = parser.parse('path/to/tcx_file.tcx')
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Regardless of source format, `records` and `laps` use a canonical set of column names (see [Output columns](#output-columns) below), e.g.:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
distance speed cadence heart_rate
|
|
60
|
+
time
|
|
61
|
+
2026-01-05 08:00:00+00:00 0.00 36.0 80 100
|
|
62
|
+
2026-01-05 08:00:01+00:00 0.01 36.0 81 101
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`extra` is not canonicalized like `records` and `laps`: it's a dict of leftover, format-specific metadata passed through with its native field names, and its shape differs by format.
|
|
66
|
+
For FIT, it's keyed by FIT message name (e.g. `session`, `device_info`).
|
|
67
|
+
For TCX/GPX, it's a single dict of the root element's attributes/fields (e.g. `Creator`, `Id`).
|
|
68
|
+
Treat it as raw metadata to inspect per-format rather than something to consume generically.
|
|
69
|
+
|
|
70
|
+
## Output columns
|
|
71
|
+
|
|
72
|
+
Units are aligned to FIT's standard units (via `fitdecode.StandardUnitsDataProcessor`), and columns are renamed/converted where needed so the same name means the same unit regardless of source format:
|
|
73
|
+
|
|
74
|
+
| Column | Unit | FIT | TCX | GPX |
|
|
75
|
+
|---|---|:-:|:-:|:-:|
|
|
76
|
+
| `latitude`, `longitude` | degrees | Yes | Yes | Yes |
|
|
77
|
+
| `altitude` | meters | Yes | Yes | Yes |
|
|
78
|
+
| `distance` | km | Yes | Yes | — |
|
|
79
|
+
| `speed` | km/h | Yes | Yes | (\*) |
|
|
80
|
+
| `cadence` | rpm | Yes | Yes | Yes |
|
|
81
|
+
| `heart_rate` | bpm | Yes | Yes | Yes |
|
|
82
|
+
| `power` | watts | Yes | Yes | Yes |
|
|
83
|
+
| `temperature` | °C | Yes | — | Yes |
|
|
84
|
+
|
|
85
|
+
Not every column appears in every file: `parse()` only includes columns actually present in the source.
|
|
86
|
+
Two of these gaps are structural (GPX has no field for cumulative distance, in the base spec or in Garmin's `TrackPointExtension`, and TCX has no field for temperature, in the base spec or in Garmin's `ActivityExtension`), so those will never appear regardless of exporter.
|
|
87
|
+
GPX files also have no lap data, so `laps` will always be an empty DataFrame.
|
|
88
|
+
|
|
89
|
+
(\*) `speed` for GPX is exporter-dependent, not a format limitation: it's defined in Garmin's `TrackPointExtension/v2` schema.
|
|
90
|
+
Any exporter that emits `v2` (or another extension exposing a `speed`-named field) will have it picked up and normalized.
|
|
91
|
+
|
|
92
|
+
`laps` follows the same convention for shared metrics (`total_distance`, `avg_speed`, `max_speed`, `avg_heart_rate`, `avg_power`, `total_calories`, etc.).
|
|
93
|
+
FIT also exposes FIT-specific fields not available from TCX/GPX (e.g. `fractional_cadence`, `left_right_balance`, `accumulated_power`) under their native FIT names.
|
|
94
|
+
|
|
95
|
+
## License
|
|
96
|
+
|
|
97
|
+
MIT
|
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
activity_parser/__init__.py,sha256=R2vu04z59TPQaLvmV3AmNJfHf5ubsOMca0krvhECfm8,290
|
|
2
|
+
activity_parser/parse_activity.py,sha256=OonQJcEDvHj-mVQH8cbqFyeJMmImCZCo7u6A4YIDho8,9076
|
|
3
|
+
activity_parser/parse_fit_file.py,sha256=aoi9qKRIH0cHRobMk0rIK9ASq53aLoh-vwJVS5zUHuI,3475
|
|
4
|
+
activity_parser/parse_tcx_gpx.py,sha256=59pYLBwBJ3-v-FmjMQd8PJPVUQW8YDUMkaOh2_nc8x0,6965
|
|
5
|
+
activity_parser/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
6
|
+
activity_parser-0.9.0.dist-info/METADATA,sha256=i0E9CSrJXT438b6IBo0F0LtbuMK4n3G-yIJ-xVoy3dI,4374
|
|
7
|
+
activity_parser-0.9.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
|
|
8
|
+
activity_parser-0.9.0.dist-info/licenses/LICENSE,sha256=33omZljNc_oQyuSppalWHYKCj-axXx8R05aPvPWf6Z4,1076
|
|
9
|
+
activity_parser-0.9.0.dist-info/RECORD,,
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023-2026 Tabish Mustufa
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of
|
|
6
|
+
this software and associated documentation files (the "Software"), to deal in
|
|
7
|
+
the Software without restriction, including without limitation the rights to
|
|
8
|
+
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
|
|
9
|
+
the Software, and to permit persons to whom the Software is furnished to do so,
|
|
10
|
+
subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
|
|
17
|
+
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
|
|
18
|
+
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
|
|
19
|
+
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
|
20
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|