CLI and API reference

CLI reference


usage: accProcess [-h] [--timeZone e.g. Europe/London]
                  [--timeShift e.g. 10 mins]
                  [--startTime e.g. 1991-01-01T23:59]
                  [--endTime e.g 1991-01-01T23:59]
                  [--timeSeriesDateColumn True/False]
                  [--processInputFile True/False] [--epochPeriod length]
                  [--sampleRate Hz, or samples/second]
                  [--resampleMethod linear/nearest] [--useFilter True/False]
                  [--csvStartTime e.g. 2020-01-01T00:01]
                  [--csvSampleRate Hz, or samples/second]
                  [--csvTimeFormat time format] [--csvStartRow start row]
                  [--csvTimeXYZTempColsIndex time,x,y,z,temperature]
                  [--rawOutput True/False] [--npyOutput True/False]
                  [--skipCalibration True/False] [--calOffset x y z]
                  [--calSlope x y z] [--calTemp x y z] [--meanTemp temp]
                  [--stationaryStd mg] [--calibrationSphereCriteria mg]
                  [--mgCpLPA mg] [--mgCpMPA mg] [--mgCpVPA mg]
                  [--intensityDistribution True/False]
                  [--extractFeatures True/False]
                  [--activityClassification True/False]
                  [--activityModel ACTIVITYMODEL] [--psd True/False]
                  [--fourierFrequency True/False]
                  [--fourierWithAcc True/False] [--m10l5 True/False]
                  [--outputFolder filename] [--verbose True/False]
                  [--deleteIntermediateFiles True/False]
                  [--rawDataParser rawDataParser]
                  [--javaHeapSpace amount in MB]
                  input file

A tool to extract physical activity information from raw accelerometer files.

positional arguments:
  input file            the <.cwa/.cwa.gz> file to process (e.g.
                        sample.cwa.gz). If the file path contains spaces,it
                        must be enclosed in quote marks (e.g. "../My

optional arguments:
  -h, --help            show this help message and exit
  --timeZone e.g. Europe/London
                        timezone in country/city format to be used for
                        daylight savings crossover check (default :
  --timeShift e.g. 10 (mins)
                        time shift to be applied, e.g. -15 will shift the
                        device internal time by -15 minutes. Not to be
                        confused with timezone offsets. (default : 0
  --startTime e.g. 1991-01-01T23:59
                        removes data before this time (local) in the final
                        analysis (default : None)
  --endTime e.g 1991-01-01T23:59
                        removes data after this time (local) in the final
                        analysis (default : None)
  --timeSeriesDateColumn True/False
                        adds a date/time column to the timeSeries file, so
                        acceleration and imputation values can be compared
                        easily. This increases output filesize (default :
  --processInputFile True/False
                        False will skip processing of the .cwa file (the
                        epoch.csv file must already exist for this to work)
                        (default : True)
  --epochPeriod length  length in seconds of a single epoch (default : 30s,
                        must be an integer)
  --sampleRate Hz, or samples/second
                        resample data to n Hz (default : 100s, must be an
  --resampleMethod linear/nearest
                        Method to use for resampling (default : linear)
  --useFilter True/False
                        Filter ENMOtrunc values? (default : True)
  --csvStartTime e.g. 2020-01-01T00:01
                        start time for csv file when time column is not
                        available (default : None)
  --csvSampleRate Hz, or samples/second
                        sample rate for csv file when time column is not
                        available (default : None)
  --csvTimeFormat time format
                        time format for csv file when time column is available
                        (default : yyyy-MM-dd HH:mm:ss.SSSxxxx '['VV']')
  --csvStartRow start row
                        start row for accelerometer data in csv file (default
                        : 1, must be an integer)
  --csvTimeXYZTempColsIndex time,x,y,z,temperature
                        index of column positions for time and
                        x/y/z/temperature columns, e.g. "0,1,2,3,4" (default :
  --rawOutput True/False
                        output calibrated and resampled raw data to a .csv.gz
                        file? NOTE: requires ~50MB per day. (default : False)
  --npyOutput True/False
                        output calibrated and resampled raw data to .npy file?
                        NOTE: requires ~60MB per day. (default : False)
  --skipCalibration True/False
                        skip calibration? (default : False)
  --calOffset x y z     accelerometer calibration offset in g (default : [0.0,
                        0.0, 0.0])
  --calSlope x y z      accelerometer slopes for calibration (default : [1.0,
                        1.0, 1.0])
  --calTemp x y z       temperature slopes for calibration (default : [0.0,
                        0.0, 0.0])
  --meanTemp temp       (DEPRECATED) mean calibration temperature in degrees
                        Celsius (default : None)
  --stationaryStd mg    stationary mg threshold (default : 13 mg))
  --calibrationSphereCriteria mg
                        calibration sphere threshold (default : 0.3 mg))
  --mgCpLPA mg          LPA threshold for cut point based activity definition
                        (default : 45)
  --mgCpMPA mg          MPA threshold for cut point based activity definition
                        (default : 100)
  --mgCpVPA mg          VPA threshold for cut point based activity definition
                        (default : 400)
  --intensityDistribution True/False
                        Save intensity distribution (default : False)
  --extractFeatures True/False
                        Whether to extract signal features. Needed for
                        activity classification (default : True)
  --activityClassification True/False
                        Use pre-trained random forest to predict activity type
                        (default : True)
  --activityModel ACTIVITYMODEL
                        trained activity model .tar file
  --psd True/False      Calculate power spectral density for 24 hour circadian
                        period (default : False)
  --fourierFrequency True/False
                        Calculate dominant frequency of sleep for circadian
                        rhythm analysis (default : False)
  --fourierWithAcc True/False
                        True will do the Fourier analysis of circadian rhythms
                        (for PSD and Fourier Frequency) with acceleration data
                        instead of sleep signal (default : False)
  --m10l5 True/False    Calculate relative amplitude of most and least active
                        acceleration periods for circadian rhythm analysis
                        (default : False)
  --outputFolder filename, -o filename
                        folder for all of the output files (default : None)
  --verbose True/False  enable verbose logging? (default : False)
  --deleteIntermediateFiles True/False
                        True will remove extra "helper" files created by the
                        program (default : True)
  --rawDataParser rawDataParser
                        file containing a java program to process raw .cwa
                        binary file, must end with .class (omitted) (default :
  --javaHeapSpace amount in MB
                        amount of heap space allocated to the java
                        subprocesses,useful for limiting RAM usage (default :


Matplotlib is building the font cache; this may take a moment.
usage: accPlot [-h] [--plotFile output file] [--showFileName True/False]
               [--showFirstNDays days]
               input file

A script to plot acc time series data.

positional arguments:
  input file            input .csv.gz time series file to plot

optional arguments:
  -h, --help            show this help message and exit
  --plotFile output file
                        output .png file to plot to
  --showFileName True/False
                        Toggle showing filename as title in output image
                        (default : False)
  --showFirstNDays days
                        Show just first n days


usage: accWriteCmds [-h] --outDir OUTDIR [--cmdsFile CMDSFILE]
                    [--accExt ACCEXT] [--cmdOptions CMDOPTIONS]

positional arguments:

optional arguments:
  -h, --help            show this help message and exit
  --outDir OUTDIR, -d OUTDIR
  --cmdsFile CMDSFILE, -f CMDSFILE
  --accExt ACCEXT, -a ACCEXT
                        Acc file type e.g. cwa, CWA, bin, BIN, gt3x...
                        String of processing options e.g. --epochPeriod 10


usage: accCollateSummary [-h] [--outputCsvFile OUTPUTCSVFILE] resultsDir

positional arguments:

optional arguments:
  -h, --help            show this help message and exit

API reference

accelerometer.classification.trainClassificationModel(trainingFile, labelCol='label', participantCol='participant', annotationCol='annotation', metCol='MET', featuresTxt='activityModels/features.txt', nTrees=1000, maxDepth=None, minSamplesLeaf=1, cv=None, testParticipants=None, outDir='model/', nJobs=1)

Train model to classify activity states from epoch feature data

Based on a balanced random forest with a Hidden Markov Model containing transitions between predicted activity states and emissions trained using the input training file to identify pre-defined classes of behaviour from accelerometer data.

  • trainingFile (str) – Input csv file of training data, pre-sorted by time

  • labelCol (str) – Input label column

  • participantCol (str) – Input participant column

  • annotationCol (str) – Input text annotation e.g. ‘walking with dog’ vs. ‘walking’

  • metCol (str) – Input MET column

  • featuresTxt (str) – Input txt file listing feature column names

  • cv (int) – Number of CV folds. If None, CV is skipped.

  • testParticipants (str) – Input comma separated list of participant IDs to test on.

  • nTrees (int) – Random forest n_estimators param.

  • maxDepth (int) – Random forest max_depth param.

  • minSamplesLeaf (int) – Random forest min_samples_leaf param.

  • nJobs (int) – Number of jobs to run in parallel.

  • outDir (str) – Output directory


Output files (trained model, predictions, etc.) written to <outDir>

Return type


accelerometer.classification.perParticipantSummaryHTML(dfParam, yTrueCol, yPredCol, pidCol, outHTML)

Provide HTML summary of how well activity classification model works at the per-participant level

  • dfParam (dataframe) – Input pandas dataframe

  • yTrueCol (str) – Input for y_true column label

  • yPregCol (str) – Input for y_pred column label

  • pidCol (str) – Input for participant ID column label

  • outHTML (str) – Output file to print HTML summary to


HTML file reporting kappa, accuracy, and confusion matrix

Return type