• 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 11 64bit 23H2 or later recommended
2. X64 CPU (also known as x64, x86_64, AMD64, and Intel 64)
3. RAM: 16 GB or higher recommended
4. 15 GiB or more free disk space
5. Full HD (1920 x 1080) or higher screen resolution

Installation of ActiPASS

ActiPASS installation is fairly simple. After you receive a compiled executable version of ActiPASS, execute the file "ActiPASS_####.##_Installer.exe" to start the ActiPASS installation process. ActiPASS depends on "MATLAB Runtime" to function and the installer will download and install the correct version of MATLAB Runtime in your system. ActiPASS by default will be installed in to your roaming "AppData" folder (Ex. C:\Users\JaneDoe\AppData\Roaming\Ergo-Tools\ActiPASS_UI_Beta).

First time use and licensing

First use

1. Execute ActiPASS by clicking "ActiPASS_UI_Beta" in Windows start menu.

   

2. 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" multiple times). Even though ActiPASS itself has a small footprint, loading Matlab Runtime takes some time.

   

3. 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.
5. Copy the two license files "ActiPASS.lic" and "ActiPASS.key" which you received from developers in to the folder opened.

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 conduct a quality check of 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 the project 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 whole project or 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"). By default this table is sorted such that it shows the problematic cases first.
   • The cases highlighted in yellow fall into one of the quality-check or outlier flags or fall 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.
   • Double-clicking on any row of this table will open the corresponding QC-visualization.

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.

Visualizations and changing auto-detected QC_Status

8. Press the "QC Visualization" tab to browse the quality-check visualizations (see below).

   • Auto detected QC flags are shown in the "Flags" field
   • Use the "Previous" and "Next" buttons to browse QC images
   • Use the "Search" box to search a specific ID
   • It is possible to right click on visualization and open the corresponding PNG file in windows File Explorer.

9. Finally if auto detected QC_Status should be changed after manual inspection, it can be done using the "QC_Status" drop-down as seen below.

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 and a long format table where each row represent a 24h day (multiple rows per participant). Please read ActiPASS Variable Definitions for definitions of each variable.

Stat generation steps

Note: Some of these options are non-chngeable under ProPASS mode.

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. This settings is applicable only to wide-format table "ProPASS_WideFormat_MasterFile.csv". The long format table "ActiPASS_Daily_LongFormat_MasterFile.csv" contains data from all days.

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. This settings is applicable only to wide-format table "ProPASS_WideFormat_MasterFile.csv". The long format table "ActiPASS_Daily_LongFormat_MasterFile.csv" contains data from all days.

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.