Usage

Our tool uses published methods to extract summary sleep and activity statistics from accelerometer data.

Basic usage

To extract a summary of movement metrics from raw accelerometer files:

$ actinet data/sample.cwa.gz
<summary output written to outputs/sample/sample-summary.json>
<time-series output written to outputs/sample/sample-timeSeries.csv.gz>

See CLI and API reference for more details.

This will output a number of files, described in the table below. The sample-timeSeries-plot.png file is optional, by adding the ‘-p’ flag, to visualise the output time-series.

File	Description
outputSummary.json	Summary statistics for the entire input file, such as data quality, acceleration and non-wear time grouped hour of day, and histograms of acceleration levels.
timeSeries.csv.gz	Acceleration time-series and predicted activities.
timeSeries-plot.png	Output plot of overall activity and class predictions for each 30sec time window.

Processing a CSV file

$ actinet data/sample.csv.gz

The CSV file must have at least four columns, expected to be named “time”, “x”, “y” and “z”. The “time” column should contain the date and time of each measurement as a string. The “x”, “y” and “z” columns should contain the numeric tri-axial acceleration values. A template can be downloaded as follows:

$ wget "http://gas.ndph.ox.ac.uk/aidend/accModels/sample-small.csv.gz"
$ mv sample-small.csv.gz data/
$ gunzip data/sample.csv.gz
$ head -3 data/sample.csv
time,x,y,z
2014-05-07 13:29:50.439+0100 [Europe/London],-0.514,0.07,1.671
2014-05-07 13:29:50.449+0100 [Europe/London],-0.089,-0.805,-0.59

If the CSV file has a different header, use the option –txyz to specify the time and x-y-z columns, in that order. The –csv-start-row option can be used to specify the first row of data in the CSV file, starting from the header row. The –csv-date-format option can be used to specify the date format of the time column. Further information on valid date format strings can be found in the Python datetime documentation.

For example: .. code-block:: console SAMPLE CSV FILE

HEADER_TIMESTAMP,temperature,X,Y,Z 21/10/2013 10:00:08.000,26.3,-0.078923,0.396706,0.917759 21/10/2013 10:00:08.010,26.2,-0.094370,0.381479,0.933580 21/10/2013 10:00:08.020,26.2,-0.094370,0.366252,0.901938 21/10/2013 10:00:08.030,26.2,-0.078923,0.411933,0.901938 …

Then run the command as follows: .. code-block:: console

$ actinet data/sample.csv.gz –txyz HEADER_TIMESTAMP,X,Y,Z –csv-start-row 3 –csv-date-format “%d/%m/%Y %H:%M:%S.%f”

Other accelerometer file formats

Multiple accelerometer file formats can be processed by this model. These are limited to:

• Axivity (.cwa/.cwa.gz)

• GENEActiv (.bin/.bin.gz)

• Actigraph (.gt3x/.gt3x.gz)

• CSV (.csv/.csv.gz)

• Pickle (.pkl/.pkl.gz)

Visualisation

The quickest way to visualise the activity intensty classification output is to run the model with the ‘-p’ flag, saving the time-series-plot.png file.

$ actinet data/sample.cwa.gz -p
<summary output written to outputs/sample/sample-summary.json>
<time-series output written to outputs/sample/sample-timeSeries.csv.gz>
<plot output written to outputs/sample/sample-timeSeries-plot.png>

Alternatively, you can use the accPlot tool to visualise the time-series output. This tool offers more options for customisation.

$ accPlot sample-timeSeries.csv.gz --showFirstNDays 4 --showFileName True --plotFile my_plot.png
<plot output written to my_plot.png>

Offline usage

To use the classifier and model without internet access:

Option 1: Cache them while online:

actinet --cache-classifier

Option 2: Manually download from the ssl-wearables repository and specify paths:

actinet sample.cwa -c /path/to/classifier.joblib.lzma -m /path/to/ssl-wearables

Processing multiple files

Windows: Create a file commands.txt with:

actinet file1.cwa &
actinet file2.cwa &
actinet file3.cwa
:END

Run with:

cmd < commands.txt

Linux: Create a file command.sh with:

actinet file1.cwa
actinet file2.cwa
actinet file3.cwa

Run with:

bash command.sh

Collating multiple runs

To combine output summaries from multiple runs:

actinet-collate-outputs outputs/

Crude vs. Adjusted Activity Estimates

Adjusted estimates account for missing data using imputation:

• Imputes based on means of corresponding timepoints on other days

• Requires full 24h blocks

• Outputs NaN if still missing after imputation

Troubleshooting

If Java errors occur, try explicitly setting OpenJDK version 8:

conda create -n actinet openjdk=8

Choice of activity classifier

By default, the ActiNet tool uses the “walmsley” activity classifier, trained on the Walmsley2020 annotations for labels activity intensity. To instead use the “willetts” activity classifier, using the Willetts2018 annotations for labels for activities of daily living, you can specify it using the –classifier or ‘-c’ argument:

actinet data/sample.cwa -c willetts

It is also possible to train a bespoke activity classification model. This requires a labelled dataset of accelerometer data. To do so, you can use the TrainModel.ipynb notebook with clear instructions, to show the training of the ActiNet model to your own data. It should be noted that as the ActiNet model is a deep learning model, it is strongly advised to use a GPU for training.

To deploy this model, trained and saved locally, to a new set of data, you can use the command line interface as follows:

actinet data/sample.cwa -c /path/to/bespoke_classifier.joblib.lzma

Tool versions

Data processing methods are under continual development. We periodically retrain the classifiers to reflect developments in data processing or the training data. This means data processed with different versions of the tool may not be directly comparable.