c2dPyParse - A Command-Line Tool for Cyclus2 Data Processing

This is a Python-based command-line tool that converts Cyclus2 .c2d files into standard data formats (TSV and JSON) that you can easily import into R, or any other analysis software you like.

What this tool does

c2dpyparse extracts measurement data and metadata from compressed Cyclus2 .c2d files (from Wingate anaerobic capacity tests) and converts them into:

• TSV file: Tab-separated measurement data (e.g., readable by R's read.table())
• JSON file: Structured metadata about the test (e.g., readable with R's jsonlite package)

Prerequisites

You need Python installed on your computer. Don't worry - you don't need to write any Python code!

Check if Python is installed

Open your terminal/command prompt and type:

python --version

If you see something like Python 3.8.x or higher, you're good to go. If not, install Python:

• Windows: Download from python.org
• macOS: brew install python3 (if you have Homebrew) or download from python.org
• Linux: sudo apt install python3 python3-pip (Ubuntu/Debian)

Installation

Step 1: Download the package

Clone or download the c2dpyparse package to your computer

git clone FIXME: URL to public repo
cd c2dPyParse

If you don't have git: Download the package as a ZIP file and extract it.

Step 2: Install the package

Open your terminal/command prompt in the package directory and run:

pip install -e .

Common Issues and Solutions:

• "pip not found": Try python -m pip install -e . instead
• Permission errors on macOS/Linux: Try pip install --user -e .
• Multiple Python versions: Try python3 -m pip install -e .

Step 3: Verify Installation

Test that the command works:

c2dpyparse --help

You should see help text describing the available options.

If you get "command not found": Try using the module approach instead:

python -m c2dpyparse.c2d_cli --help

Usage

Basic Command

c2dpyparse path/to/your/file.c2d --output-dir results/

Full Example

c2dpyparse "C:\Users\YourName\Desktop\report_Wingate.c2d" --output-dir "C:\Users\YourName\Desktop\results"

Command options

• <file path> (required): Path to your .c2d file
• --output-dir (required): Directory where output files will be saved
• --task (optional): Task name for file naming (default: "wingate")
• --sections (optional): Which metadata sections to extract (default: Athlete CycleData Protocol)

Advanced usage

Custom task name

c2dpyparse data/test.c2d --output-dir results/ --task baseline

To extract specific metadata sections, use

c2dpyparse data/test.c2d --output-dir results/ --sections Athlete Protocol

To extract multiple sections, use

c2dpyparse data/test.c2d --output-dir results/ --sections Athlete CycleData Protocol Equipment

Output files

For an input file named report_Wingate.c2d, the tool creates:

1. sub-Wingate_task-wingate_physio.tsv, containing the measurement data over time
2. sub-Wingate_task-wingate_physio.json, containing metadata about the participant and settings

Read measurement data

measurement_data <- read.table("sub-Wingate_task-wingate_physio.tsv",
sep = "\t",
header = TRUE,
na.strings = "n/a")

Read metadata

library(jsonlite)

metadata <- fromJSON("sub-Wingate_task-wingate_physio.json")

View the data

head(measurement_data)
str(metadata)

Expected Data Columns

The TSV file typically contains:

• Time [ms]: Timestamp in milliseconds
• Power [W]: Power output in watts
• Heart Rate [1/min]: Heart rate in beats per minute
• Cadence [1/min]: Pedaling cadence in RPM
• Speed [km/h]: Speed in kilometers per hour
• ...and more, depending on your test setup

Troubleshooting

Common Problems and Solutions

Problem: c2dpyparse: command not found

Solution:

1. Make sure you installed the package: pip install -e .
2. Try the module approach: python -m c2dpyparse.cli [your arguments]
3. Check your $PATH environment variable, or restart your terminal

Problem: ModuleNotFoundError: No module named 'c2dpyparse'

Solution:

1. Make sure you're in the correct directory
2. Reinstall: pip uninstall c2dpyparse && pip install -e .
3. Check if you're using the correct Python environment

Problem: FileNotFoundError when processing .c2d files

Solution:

1. Use absolute paths, starting at the top level containing the file: "C:\full\path\to\file.c2d"
2. Check that the file exists and is readable
3. Make sure the file is actually a .c2d file

Problem: Permission denied errors

Solution:

1. Make sure you have write permissions to the output directory
2. Try running as administrator (Windows) or with sudo (macOS/Linux)
3. Choose a different output directory

Problem: Empty or corrupted output files

Solution:

1. Check that your .c2d file is valid and not corrupted
2. Try with a different .c2d file
3. Check the terminal output for error messages

Getting Help

If you encounter issues:

1. Check the help: c2dpyparse --help
2. Use verbose output: Add error checking to see what's happening
3. Try a test file: Start with a known working .c2d file
4. Check file paths: Use absolute paths to avoid confusion

Example workflow

For a single file

1. Navigate to your data directory, e.g.,

   cd "C:\Users\YourName\Desktop\WingateData"

2. Create output directory

   mkdir results

3. Process the file

   c2dpyparse report_Wingate.c2d --output-dir results/

4. Check if the files were created, e.g.,

   ls results/

For multiple files (Windows)

@echo off
for %%f in (*.c2d) do (
c2dpyparse "%%f" --output-dir "results/"
)

Requirements

• Python >= 3.8
• pandas >= 1.5.0
• lxml >= 4.9.0

These are installed automatically when you run pip install -e .

License

This project is licensed under the European Union Public License (EUPL-1.2). See full license text in English in LICENSES/EUPL-1.2.txt; for other languages, see https://interoperable-europe.ec.europa.eu/collection/eupl/eupl-text-eupl-12.