Quick preview accelerometer files using ActiPASS CLI version - Ergo-Tools/ActiPASS GitHub Wiki

ActiPASS CLI

A special CLI version of ActiPASS can be integrated into Windows system for quick previewing all supported thigh worn accelerometer files. This feature is helpful to 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 right-click on a file and “Send it to” ActiPASS. However, please be aware that this version is not recommended for generating results for studies since it bypasses some features of ActiPASS GUI version (see Limitations).

Command line interface

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

Installation and quick start guide

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. The same license you received for ActiPASS GUI works with this tool. (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. 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

  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"

    • 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.

  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