ActiPASS User Guide

• ActiPASS GUI
• Installation
  • Prerequisites
    • System requirements
    • Install Matlab Runtime
  • Installation of ActiPASS
• First time use and licensing
  • First use
  • Licensing
• Processing accelerometer files
  • ActiPASS status bar
  • Start new ActiPASS project
  • Start a new batch analysis
    • Adding accelerometer files
    • ActiPASS diary and device calibration
  • Start a subsequent batch analysis (for the same project)
• Quality checking a project
  • Project and batch level quick quality-check
  • Detailed quality checks
• Generating final statistics
  • Stat generation steps

ActiPASS GUI

ActiPASS has a user friendly GUI where processing accelerometer data files, and generating statistics can be done in few simple steps (see the numbers in red corresponding to these steps in the screenshot below). ActiPASS also has a convenient status bar (see screenshot below) and blue (❔) icons which will guide you through these steps.

This user guide walks you through installation, licensing, a typical batch process, quality-check and stats generation steps. For more info it is recommended to consult the ActiPASS user manual (upcoming). This user guide corresponds to ActiPASS versions 1.50 or later unless superseded by a newer version.

Installation

Prerequisites

System requirements

1. Operating system: Windows 10 64bit (version 21H2 or later recommended)
2. RAM: 16 GB or higher recommended
3. 15 GiB or more free disk space
4. Full HD (1920 x 1080) or higher screen resolution

Install Matlab Runtime

Download and install Matlab Runtime for Windows version 2020b 64bit from this link. Even if a full version of Matlab is installed, it is recommended to install the correct version of Matlab Runtime for compatibility reasons.

Installation of ActiPASS

ActiPASS installation is fairly simple. Execute the self extracting archive file "ActiPASS_#.###.exe" to extract ActiPASS executable files to a suitable location in your system. For an example select: "C:/Users/%USERNAME%/ActiPASS"

First time use and licensing

First use

Browse to the folder where ActiPASS executable files are located and double click "ActiPASS_UI_Beta_###.exe" file to start ActiPASS. You will see the following splash window for a short time and then ActiPASS software will be loaded afterwards. ActiPASS startup will take some time and please be patient (and avoid executing "ActiPASS_UI_Beta_###.exe" multiple times). Even though ActiPASS itself has a small footprint, loading Matlab Runtime takes some time.

Then you will see the ActiPASS about dialog as shown below. ActiPASS now runs in unlicensed evaluation mode with limited functionality. Licensing will be discussed next.

Licensing

ActiPASS has a functionality-limited evaluation mode, and two licensed modes of operation. The recommended "ProPASS" mode is where all algorithm options are set to ProPASS defaults. An "Advanced" mode also exists where algorithm options can be altered. It's recommended to run ActiPASS in "ProPASS" mode unless instructed by developers.

1. Click "Help->Activate License" to open-up the licensing dialog box shown below.
2. Read license terms, enter your details and press Accept and Request License if you agree to the license terms.
3. Send the generated "Host-Details.txt" file back to developers. This file contains the unique MAC addresses of network interfaces in your computer and the user details you have specified.
4. You will then receive two license files "ActiPASS.key" and "ActiPASS.lic" back from developers. Click "Help->Activate License" one more time to continue the licensing process.

Processing accelerometer files

ActiPASS status bar

During a typical ActiPASS workflow, The Status bar (see screenshot below) will be updated with current status of the workflow, possible next steps and some hints about what went wrong in case of errors.

Start new ActiPASS project

In order to process accelerometer files by ActiPASS, a new ActiPASS project should be created first. ActiPASS project is simply a folder initialized by ActiPASS (no separate project file). A project folder contains outputs from one or more batch processes. It also contains extra individual quality check information, intermediate files needed for ActiPASS final statistics generation and also final statistics. It's strongly recommended not to modify, delete, rename or move files and folders within this directory. Otherwise ActiPASS will not function properly. Also see ActiPASS project folder structure.

1. Start ActiPASS and make sure it is not running in evaluation mode. ActiPASS status will display "ActiPASS ready. Choose project directory..". You can also click "Reset Application" button to initialize ActiPASS if a project is already initialized.

   

2. Choose an empty directory to create a new ActiPASS project by clicking "Choose Project Dir" button. This ActiPASS Project directory/folder will be populated with analysis results, quality check information and final output tables. Please note that you should not select a directory with accelerometer files as the Project folder.

   

3. The checkbox "ProPASS Mode" indicate whether ActiPASS runs in ProPASS mode or not.

4. The level of visualizations (for quality-checks, participant feedback and group level overview) can be selected with "Visualizations" combo-box. The option "QC", which creates a single quality-check figure, is recommended for batch processing large amount of files. The option "full" creates more individual level figures and also group level distributions and histograms which can be used for participant feedback or to gain quick overview of the results.

Start a new batch analysis

Once a new ActiPASS project folder is initialized, the next step is to start a batch analysis. ActiPASS supports Axivity AX3/AX6 CWA or WAV files, ActivPAL3 datx files, ActivPAL3 or ActivPAL4 CSV files, ActiGraph CSV files, SENS Motion hex and bin files and CSV files formatted according to ActiPASS generic format.

Adding accelerometer files

1. Before adding accelerometer files for a batch analysis, we can help ActiPASS by indicating if accelerometer placement orientation is different from default ActiPASS orientation by setting "Flipped" and "Rotated" check-boxes. Even though ActiPASS has in-built orientation detection, setting those check-boxes helps ActiPASS in cases where orientation detection is difficult (ex. too short measurements).

2. The next step is to indicate how participant IDs can be found from accelerometer filenames. The "ID format" combo-box sets whether IDs can be found at the start or end of the filename or in unique ActivPAL format. The "ID Length" indicates how many digits or characters are in IDs.

3. Then add accelerometer files to the batch process by pressing the "Choose Acc Files:" button. The type of accelerometer files can be selected in the windows file opening dialog box as shown below.

   

   Instead of choosing accelerometer files directly it is also possible to open a list of accelerometer files. This method is recommended if accelerometer files are in different locations or when participant IDs are not embedded in accelerometer filenames. See ActiPASS accelerometer file lists for more info.

   

ActiPASS diary and device calibration

4. Before starting the batch process we can first specify the optional diary which separates measurement periods into several domains/intervals (like work, leisure etc). Please see ActiPASS diary file format for more information.

   • If no diary exists, you should still press the button "Load Diary" and then press cancel in file opening dialog box.

   • It's a good idea to quality check an the diary via built-in tool "Quality check ActiPASS formatted diary" located under "Project -> Tools"

5. The other optional file is the device specific calibration file. Even though this file is also optional, it's strongly recommended that a device specific calibration file is specified. If the file does not exist ActiPASS will create the file and add device specific calibration data (found using auto-calibration algorithm by Vincent van Hees). It's also recommended to use the same device specific calibration file for all batch-processes.

6. Finally press "Process Start" to start the new batch process. ActiPASS will then process accelerometer files and display a progress-bar. You can cancel the batch process anytime by pressing the cancel button in the progress-bar. ActiPASS will populate the chosen project folder with results of the batch process. See ActiPASS project folder structure for more info.

Start a subsequent batch analysis (for the same project)

1. Press "Reset Application" button if ActiPASS is already open. Otherwise start ActiPASS

2. Click "Choose Project Dir" button and choose existing project directory. ActiPASS status bar will look like below.

3. Do all steps specified in previous topic "Start a new batch analysis". ActiPASS will then merge the output of the new batch-process with previous batches. If chosen accelerometer files for a subsequent batch overlap with previous batches, then ActiPASS will always give priority to subsequent batches and overwrite results from previous batches.

Quality checking a project

After one or several batch processes are completed, it's time to do a quality check of the analysis. ActiPASS supports this quality check procedure by providing an automated quality-check summary indicating possible outliers and other problematic cases. Then cases flagged for manual quality check can be investigated using ActiPASS quality-check visualizations.

Figure: ActiPASS quality-check visualization showing weekly activity

Project and batch level quick quality-check

1. After one or several batch-processes are completed, ActiPASS displays a project summary as shown in above screenshot (left). It shows the automatically detected problematic cases ("Manual QC suggested") and also number of cases fall into most common outlier categories. For more info about outlier cut-offs see "Edit->Advanced Settings".

2. The batch-level summary can be seen by selecting a batch from the combo-box (right in above screenshot).

3. To do a more thorough quality check, press the "Show QC Info" button.

Detailed quality checks

When you press the "Show QC Info" button, a separate window is opened containing a batch-level quality-check table and shortcuts for several aspects of individual and group-level quality checks.

1. The table shown in the screenshot above shows individual level quality check summary for the selected batch.

   • The cases highlighted in dark-orange indicate cases with file loading/processing errors or cases where all days have not enough wear time (indicated by "QC_Status" = "NotOK").
   • The cases highlighted in yellow falls into either one of the outlier criteria or falls into other technical issues (indicated by "QC_Status" = "Check").
   • In addition to columns corresponding to outliers and other problems, there are columns corresponding to auto-detected orientation, non-wear, device-specific-calibration and other aspect of the batch-processing in this table.

2. Use the "Batch" dropdown combo-box to choose another batch. Selecting "Master-QC-table" from the combo-box loads the quality check data for the whole project.

3. Press "Open Batch QC-Dir" to open a directory containing visualizations (see example) and tables for thorough individual quality checks. When feasible it's recommended to do an individual quality check for cases highlighted yellow or orange ("QC_Status" set to "Check" or "NotOK"). For more information about this folder and files contained, see: BatchOut

4. Press "Open Batch QC Table" to open the same table above in Excel (or default CSV viewer in your system). See see: BatchOut for more info.

5. "Open Project Dir" opens up the ActiPASS project directory in Windows File Explorer. See see: ActiPASS project folder structure for more info.

6. "Show Master Distributions" button opens up a directory containing group level histograms and distributions for the whole project (all batches). These should not be used for final results and should only be used to get a sneak-peak into the study. The histograms and distributions are generated for all cases including outliers and problematic cases. See QC_Distributions for more info.

7. The "Open Master QC-Table" buttons opens up the master QC-Table (which is the merge of all batch-level QC tables) as a Microsoft Excel file. If needed make changes to "QC_Status" column of this master QC-Table (after going through quality-check visualizations). This column will be considered for the final stats generation discussed next. See ActiPASS_QC_MasterFile for more info.

Generating final statistics

During processing of each batch, ActiPASS saves an intermediate file containing epoch-level (for each second) information for each individual. These epoch-level data is saved within "IndividualOut" folder inside an ActiPASS project (see ActiPASS project folder structure). The last step is to read these 1s-epoch data and generate final variables. By default (in ProPASS mode) ActiPASS generates a wide-format table where each row represent a participant. Please read ActiPASS Variable Definitions for definitions of each variable.

Stat generation steps

1. Set a valid day criteria. The default is the "ProPASS" option which excludes days less than 20hrs of wear time and also auto-detected problematic days. The "only-wear-time" option considers only a wear-time threshold which can be set in ActiPASS settings.

2. Select for how many valid-days statistics are generated. For participants whose measurements contain lower number of valid days than this value, the variables for remaining days will be filled with NaN or NA values.

3. Select how the valid days are selected when participants have more valid days than the specified value. It's possible to select the first valid days or when an the additional diary containing "Work" and "Leisure" information is present, we can select days to achieve the optimal number of work:leisure days ratio.

4. When the additional diary containing times of different domains/intervals such as work or leisure exists, write the domains for which variables are generated by specifying each domain separated by a space in "Stat Domains" edit-box. Default value is "Work Leisure"

5. When "Stat Domains" are defined, choose how those domains are matched against diary in the "Diary matching mode" combo-box. For an example the stat-domain "Work" will match the diary domain "WorkFromHome" when "Diary matching mode" is set to "Inclusive".

6. Set the participant exclusion criteria based on "QC_Status". See "Detailed quality checks" section above). The default "NotOK" options only excludes cases with file loading/processing errors or cases where all days do not have enough wear time. The option "NotOK+Check" additionally excludes cases where a manual quality check is suggested. The option "None" will try to process all files regardless of "QC_Status".

7. If statistics should only be generated for the selected batch (see "Project and batch level quick quality-check" above), then check "Selected batch only" checkbox.

8. Finally press "Generate Stats" button to generate the ActiPASS wide-format master results table. Results will be saved into a CSV files named "ProPASS_Daily_WideFormat_MasterFile.csv" and "ActiPASS_Daily_LongFormat_MasterFile.csv" inside ActiPASS project folder. For variable definitions see: ActiPASS Variable Definitions.