ActiPASS CLI ‐ for CLI workflows and quick‐previewing accelerometer files - Ergo-Tools/ActiPASS GitHub Wiki

ActiPASS CLI

A special CLI version of ActiPASS can be integrated into Windows system (or Linux/MacOS existing MATLAB installations with some tweaks) for quick batch processing or previewing all supported thigh worn accelerometer files. This feature is helpful to integrate ActiPASS into an existing CLI workflow, or do a quick quality check of a measurement and to give feedback to a participant. Tool will auto-detect the accelerometer brand. All we have to do is give the accelerometer file as a CLI argument or (right-click on a file and “Send it to” ActiPASS in Windows). However, please be aware that full GUI version of ActiPASS is recommended for generating results for studies** since this tool bypasses some features of ActiPASS GUI version (see Limitations).

Command line interface (for integrating into existing workflows)

See full functionality (e.g. to generate 1s PA/SB classification) available via command line. See: CLI Usage

Using ActiPASS_CLI source in MATLAB

Clone (or download) ActiPASS GitHub source code. ActiPASS CLI can be found at "cli" sub-directory. Add the folders "library", "algorithms" and "utils" to MATLAB path and invoke "actipass_cli.m". See command line arguments CLI Usage (also given in "Usage_CLI.txt").

ActiPASS_CLI source code is released under GPLV3 license and therefore please make sure any derivative work of ActiPASS_CLI be published in a similar license with correct attribution. However the rest of ActiPASS algorithms, library functions and utilities are released under permissive BSD 3-clause license.

Installation and quick start guide (for windows binary executable)

Prerequisite for using this version is that you already have a licensed version of ActiPASS installed in your system. Usage of this tool falls under the same license agreement. (See licensing info below).

  1. Download ActiPASS_CLI version from the link sent separately via Email:

  2. Start the ActiPASS_CLI installation by executing the file "ActiPASS_CLI_####.##_installer.exe"

    image

  3. ActiPASS_CLI will now be available via Windows start menu.

    image

  4. Click “actipass_cli.exe” from Windows Start Menu. You will see a windows terminal window for some time and it will then automatically close. Now ActiPASS is registered as a Windows “Send To” destination.

    image

  5. In order to process any supported accelerometer file, just right click on the accelerometer file and select “Send To” -> “ActiPASS_CLI” as shown in the screenshot.

    image

  6. After the processing is completed, you will see two new files:

    • A daily PA and SB report in XLSX format
    • And PA/SB visualization in PNG format

    image

  7. Most parameters which could be changed via ActiPASS advanced settings are also used by ActiPASS CLI version (if mode is set to "ADVANCED", see CLI Usage). Therefore be careful that the intended processing parameters are set using the normal version of ActiPASS (also see Limitations)

  8. See the "ReadMe_CLI.txt" for additional features, using it via windows command prompt or integration with other tools.

Other ways of using via Windows File Explorer:

  • Drag and drop supported accelerometer raw data file on to "actipass_cli.exe"
  • Associate supported accelerometer files with "actipass_cli.exe" (right click an accelerometer file and select "Open with")

Licensing (for binary executable version)

  1. If you do not yet have a license for ActiPASS GUI, first use the normal GUI version of ActiPASS and send a new license request to developers.

  2. Copy license files you received to ActiPASS configuration/license folder. You can type “%APPDATA%\ActiPASS” in windows file explorer address bar to open ActiPASS config folder where licenses are located.

    image

  3. Then you will see the folder below. Copy new license files as seen in the screenshot below.

    image

CLI Usage

Syntax for usage via command line:

  1. actipass_cli.exe "file_in" out "file_or_folder_out" ID "ID" diary "file_diary" daily "on" vis "on" loc "front" mode "PROPASS"

    • file_in: first argument is always the full file-path to accelerometer raw data file
    • out: optional output file or a folder (only .csv, .xlsx or .mat files accepted)
    • ID: optional participant ID
    • diary: optional ActiPASS formatted diary Excel format
    • daily: optional. Default "on". "off" disables daily output table
    • vis: optional. Default "on". "off" disables activity visualizations
    • loc: optional device location: default: "front": front-of-thigh, "right": right-thigh-side or "left": left-thigh-side.
    • mode: optional operation-mode. default: "PROPASS" or "ADVANCED"

  2. actipass_cli.exe --help

    • display help/readme text in console

  3. actipass_cli.exe --add-to-sendto

    • add actipass_cli.exe to windows SendTo folder as a shortcut

Examples:

  1. actipass_cli.exe "testdata.cwa"

    • daily output is saved as "testdata_actipass_dailyact.csv" in the same folder as testdata.cwa
    • quality-check visualization is saved as "testdata_QC-1.png" in the same folder as testdata.cwa

  2. actipass_cli.exe "testdata.csv"

    • daily output is saved "testdata_actipass_dailyact.csv" in the same folder as testdata.csv
    • quality-check visualization is saved as "testdata_QC-1.png" in the same folder as testdata.cwa

  3. actipass_cli.exe "C:\Users\UNAME\Desktop\testdata.csv" out "C:\Users\UNAME\Downloads"

    • 1s output is saved to "C:\Users\UNAME\Downloads\testdata_actipass_1s.mat"
    • daily output is saved to "C:\Users\UNAME\Downloads\testdata_actipass_dailyact.xlsx"
    • quality-check visualization is saved as "C:\Users\UNAME\Downloads\testdata_QC-1.png"

  4. actipass_cli.exe "C:\Users\UNAME\Desktop\testdata.csv" out "C:\Users\UNAME\Downloads\test_out.csv"

    • 1s output is saved to matlab binary file "C:\Users\UNAME\Downloads\test_out.csv"
    • daily output is saved to "C:\Users\UNAME\Downloads\test_out_dailyact.xlsx"
    • quality-check visualization is saved as "C:\Users\UNAME\Downloads\test_out_QC-1.png"

  5. actipass_cli.exe "C:\Users\UNAME\Desktop\testdata.csv" out "C:\Users\UNAME\Downloads" ID "S0001"

    • 1s output is saved to "C:\Users\UNAME\Deownloads\S0001_actipass_1s.mat"
    • daily is saved to "C:\Users\UNAME\Deownloads\S0001_actipass_daily.xlsx"
    • quality-check visualization is saved as "C:\Users\UNAME\Downloads\S0001_QC-1.png"

  6. actipass_cli.exe "C:\Users\UNAME\Desktop\testdata.csv" out "C:\Users\UNAME\Downloads" ID "S0001" diary "C:\Users\UNAME\Desktop\diary.xlsx"

    • diary is used to trim data, define manual lying, bed, sleep or non-wear periods or divide data into intervals
    • 1s output is saved to "C:\Users\UNAME\Deownloads\S0001_actipass_1s.mat"
    • daily output is saved to "C:\Users\UNAME\Deownloads\S0001_actipass_daily.xlsx"
    • quality-check visualization is saved as "C:\Users\UNAME\Downloads\S0001_QC-1.png"

  7. actipass_cli.exe "C:\Users\UNAME\Desktop\testdata.csv" out "C:\Users\UNAME\Downloads" daily "off" vis "off"

    • only 1s outputs is saved. (to "C:\Users\UNAME\Deownloads\testdata_actipass_1s.mat")

Return codes:

  • 0 = everything went well. However it's still necessary to check for outliers

Other errors are categorized by their decimal digit position:

  • 1s indicates an unhandled exception
  • 10s indicates a license related error
  • 100s indicate file loading error
  • 1000s indicate automatic device calibration error
  • 10000s indicate automatic orientation and trimming correction error
  • 100000s indicate reference position errors
  • 1000000s times-in-bed and sleep detection error
  • 10000000s diary related error
  • 100000000s possible misclassifications

example error code:

300100000: possible misclassifications combined with reference position errors

Limitations and differences compared to ActiPASS GUI version

  1. CLI mode ignores following settings

    • ID-format, ID-length
    • Thigh reference-position setting (CLI always use auto1 method and cannot fall-back to auto2. Also diary reference positions are not available)
    • Any trunk accelerometer related setting
    • device calibration related settings (CLI always try to auto-calibrate, but cannot fall-back to manual)
    • All visualization related settings
    • All stats generation settings

  2. Other limitations

    • Handling cases with poor sensor-placement will not be as good as the GUI version.
    • CLI trims raw-data based on diary start/stop only after loading data in full. GUI tries to trim data while loading if possible.
    • Not all quality-checks and outlier detections are available for CLI mode.

Copyright notice:

ActiPASS CLI version is developed by: © Pasan Hettiarachchi at Occupational and Environmental Medicine, Department of Medical Sciences, Uppsala University

See full license agreement:

https://github.com/Ergo-Tools/ActiPASS/wiki/License-agreement#license-and-usage-agreement