Command Line Tutorial¶
Default Pipeline¶
Running a single file.¶
The simplest way to run wristpy is to open up an instance of your command line terminal of choice, and entering a valid file path for the first positional argument, and an output path (-o) that ends in the name you want to give your save file. Valid save formats are .csv and .parquet.
!wristpy tutorial_data/three_nights.bin -o ../build/three_nights_single_file_cli.csv
2026-11-18 14:51:35,376 - wristpy - INFO - writers.py:79 - save_results - Results saved in: ../build/three_nights_single_file_cli.csv
2026-11-18 14:51:35,380 - wristpy - INFO - orchestrator.py:494 - _run_file - Processing for three_nights completed successfully.
Running a Directory¶
To run an entire directory, use the path to the directory as the input. For the output, specify a path to dump the files in. Unlike in the first example, when running a directory, the output file names will be determined by the input file names. The user can use the -O flag to specify the output file type (default: .csv)
!wristpy tutorial_data/ -o ../build/ -O .csv
Customizing your pipeline¶
Wristpy allows for a number of arguments allowing you to customize your pipeline.
Specify a calibrator¶
The default calibrator (‘gradient’) is a modified version of the original GGIR implementation. The GGIR implementation can be specified using the ‘ggir’ argument.
See the following links for information on each calibration method: gradient and ggir
!wristpy tutorial_data/three_nights.bin -o ../build/three_nights_single_file_cli.csv -c gradient
2026-11-18 14:51:51,056 - wristpy - INFO - writers.py:79 - save_results - Results saved in: ../build/three_nights_single_file_cli.csv
2026-11-18 14:51:51,060 - wristpy - INFO - orchestrator.py:494 - _run_file - Processing for three_nights completed successfully.
Epoch Length¶
By default, epochs are set to 5 seconds, but the -e flag can be used to specify the desired epoch in seconds.
!wristpy tutorial_data/three_nights.bin -o ../build/three_nights_single_file_cli.csv -c gradient -e 10
2026-11-18 14:51:59,427 - wristpy - INFO - writers.py:79 - save_results - Results saved in: ../build/three_nights_single_file_cli.csv
2026-11-18 14:51:59,432 - wristpy - INFO - orchestrator.py:494 - _run_file - Processing for three_nights completed successfully.
Choose an activity metric.¶
There are four different measures of physical activity that wristpy can generate from accelerometer data. The user can specify some or all of the available metrics to be generated in the report. If no option is given, the Euclidean Norm Minus One is used by default. The available metrics are enmo, mims, mad, and ag_count. See here for details on each metric.
!wristpy tutorial_data/three_nights.bin -o ../build/three_nights_single_file_cli.csv -c gradient -e 10 -a enmo -a mad
2026-11-18 14:52:08,230 - wristpy - INFO - writers.py:79 - save_results - Results saved in: ../build/three_nights_single_file_cli.csv
2026-11-18 14:52:08,234 - wristpy - INFO - orchestrator.py:494 - _run_file - Processing for three_nights completed successfully.
Physical activity levels¶
To specify your own activity thresholds, enter them in the same order as the corresponding metric. Make sure the values are triplets, contained within strings and separated with a space. In the following example, the threshold values for enmo would be 1, 2, 3 and the threshold values for mad would be 1.5, 2.5, 3.5.
!wristpy tutorial_data/three_nights.bin -o ../build/three_nights_single_file_cli.csv -a enmo -a mad -t "1 2 3" -t "1.5 2.5 3.5"
2026-11-18 14:52:15,937 - wristpy - INFO - writers.py:79 - save_results - Results saved in: ../build/three_nights_single_file_cli.csv
2026-11-18 14:52:15,941 - wristpy - INFO - orchestrator.py:494 - _run_file - Processing for three_nights completed successfully.
To see all available options run:
!wristpy --help
Usage: wristpy [OPTIONS] {input}
Run wristpy orchestrator with command line arguments.
╭─ Arguments ──────────────────────────────────────────────────────────────────╮
│ * input <path> Path to the input data. [required] │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --output -o <path> Path where data │
│ will be saved. │
│ Supports .csv and │
│ .parquet formats. │
│ --output-filety… -O <.csv|.parquet> Format for save │
│ files when │
│ processing │
│ directories. │
│ [default: .csv] │
│ --calibrator -c <none|ggir|grad Pick which │
│ ient> calibrator to │
│ use. Must choose │
│ one of 'none', │
│ 'ggir', or │
│ 'gradient'. │
│ [default: none] │
│ --activity-metr… -a <list[enmo|mad| Metric(s) used │
│ ag_count|mims]> for physical │
│ activity │
│ categorization. │
│ Choose from │
│ 'enmo', 'mad', │
│ 'ag_count', or │
│ 'mims'. Use │
│ multiple times │
│ for multiple │
│ metrics: '-a enmo │
│ -a mad' etc. │
│ [default: enmo] │
│ --thresholds -t <list[str]> Provide three │
│ thresholds for │
│ light, moderate, │
│ and vigorous │
│ activity. One │
│ threshold set per │
│ activity metric, │
│ in the same order │
│ as metrics. │
│ Format: three │
│ space-separated │
│ values >= 0 in │
│ ascending order. │
│ Example: -t '0.1 │
│ 1.0 1.5' or -a │
│ enmo -a mad -t │
│ '0.1 1.0 1.5' -t │
│ '0.2 2.0 3.0' │
│ --nonwear-algor… -n <list[ggir|cta| Specify the │
│ detach]> non-wear │
│ detection │
│ algorithm(s) to │
│ use. Specify one │
│ or more of │
│ 'ggir', 'cta', │
│ 'detach'. (e.g. │
│ '-n ggir -n │
│ cta'). When │
│ multiple │
│ algorithms are │
│ specified, │
│ majority voting │
│ will be applied. │
│ [default: ggir] │
│ --epoch-length -e <int range> Specify the │
│ [x>=1] sampling rate in │
│ seconds for all │
│ metrics. Must be │
│ greater than or │
│ equal to 1. │
│ [default: 5] │
│ --allow-duplica… -d <bool> Whether to allow │
│ duplicate │
│ timestamps in the │
│ sensor data. If │
│ this flag is set, │
│ no error will be │
│ raised during │
│ Measurement │
│ validation and │
│ processing can │
│ continue. Only │
│ unique timestamps │
│ and their │
│ corresponding │
│ sensor values │
│ will be kept. The │
│ first occurrence │
│ of each timestamp │
│ is retained. │
│ Defaults to │
│ False. Note that │
│ the presence of │
│ duplicate │
│ timestamps may │
│ indicate sensor │
│ malfunction. │
│ Modifying this │
│ parameter should │
│ be done with │
│ caution. │
│ --adaptive-nonw… --no-adaptive-n… <bool> Absorb nonwear │
│ immediately │
│ preceding │
│ detected sleep. │
│ Enabled by │
│ default. │
│ [default: │
│ adaptive-nonwear] │
│ --verbosity -v <bool> Determines the │
│ level of │
│ verbosity. Use -v │
│ for DEBUG. │
│ Defaults to INFO │
│ if not included. │
│ --version -V <bool> Print the current │
│ version of │
│ wristpy and exit. │
│ --install-compl… <bool> Install │
│ completion for │
│ the current │
│ shell. │
│ --show-completi… <bool> Show completion │
│ for the current │
│ shell, to copy it │
│ or customize the │
│ installation. │
│ --help <bool> Show this message │
│ and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯