stepcount

Improved Step Counting via Foundation Models for Wrist-Worn Accelerometers

https://github.com/oxwearables/stepcount

Science Score: 77.0%

This score indicates how likely this project is to be science-related based on various indicators:

✓
CITATION.cff file
Found CITATION.cff file
✓
codemeta.json file
Found codemeta.json file
✓
.zenodo.json file
Found .zenodo.json file
✓
DOI references
Found 4 DOI reference(s) in README
✓
Academic publication links
Links to: nature.com, plos.org, zenodo.org
✓
Committers with academic emails
1 of 4 committers (25.0%) from academic institutions
○
Institutional organization owner
○
JOSS paper metadata
○
Scientific vocabulary similarity
Low similarity (15.5%) to scientific vocabulary

Keywords

deep-learning fitness-tracker gait-analysis healthcare machine-learning self-supervised-learning wearables

Last synced: 6 months ago · JSON representation ·

Repository

Improved Step Counting via Foundation Models for Wrist-Worn Accelerometers

Basic Info

Host: GitHub
Owner: OxWearables
License: other
Language: Jupyter Notebook
Default Branch: main
Homepage:
Size: 26.8 MB

Statistics

Stars: 41
Watchers: 4
Forks: 15
Open Issues: 9
Releases: 51

Topics

deep-learning fitness-tracker gait-analysis healthcare machine-learning self-supervised-learning wearables

Created over 4 years ago · Last pushed 6 months ago

Metadata Files

Readme Contributing License Citation

stepcount

Improved step counting based on a foundation model for wrist-worn accelerometers.

The foundation model was trained using self-supervised learning on the large-scale UK Biobank Accelerometer Dataset, and fine-tuned on the OxWalk Dataset.

The command-line tool can process Axivity AX3 files (UK Biobank, China Kadoorie Biobank) directly. For consumer devices like Fitbit and Apple Watch, convert them to raw CSV first.

Available models: - Self-supervised learning model of Hang et al. (default): https://www.nature.com/articles/s41746-024-01062-3 - Random forest (enable with the flag -t rf)

Install

Minimum requirements: Python>=3.8, Java 8 (1.8)

The following instructions make use of Anaconda to meet the minimum requirements:

Download & install Miniconda (light-weight version of Anaconda).
(Windows) Once installed, launch the Anaconda Prompt.
Create a virtual environment: console $ conda create -n stepcount python=3.9 openjdk pip This creates a virtual environment called stepcount with Python version 3.9, OpenJDK, and Pip.
Activate the environment: console $ conda activate stepcount You should now see (stepcount) written in front of your prompt.
Install stepcount: console $ pip install stepcount

You are all set! The next time that you want to use stepcount, open the Anaconda Prompt and activate the environment (step 4). If you see (stepcount) in front of your prompt, you are ready to go!

Check out the 5-minute video tutorial to get started: https://www.youtube.com/watch?v=FPb7H-jyRVQ.

Usage

```bash

Process an AX3 file

$ stepcount sample.cwa

Or an ActiGraph file

$ stepcount sample.gt3x

Or a GENEActiv file

$ stepcount sample.bin

Or a CSV file (see data format below)

$ stepcount sample.csv ```

Output: ```console

Summary

{ "Filename": "sample.cwa", "Filesize(MB)": 65.1, "Device": "Axivity", "DeviceID": 2278, "ReadErrors": 0, "SampleRate": 100.0, "ReadOK": 1, "StartTime": "2013-10-21 10:00:07", "EndTime": "2013-10-28 10:00:01", "TotalWalking(min)": 655.75, "TotalSteps": 43132, ... }

Estimated Daily Steps

          steps

time 2013-10-21 5368 2013-10-22 7634 2013-10-23 10009 ...

Output: outputs/sample/ ``` Refer to the GLOSSARY.md for a comprehensive list of outputs.

Troubleshooting

Some systems may face issues with Java when running the script. If this is your case, try fixing OpenJDK to version 8: console $ conda install -n stepcount openjdk=8

Output files

By default, output files will be stored in a folder named after the input file, outputs/{filename}/, created in the current working directory. You can change the output path with the -o flag:

console $ stepcount sample.cwa -o /path/to/some/folder/

The following output files will be generated:

Info.json Summary info, as shown above.
Steps.csv Raw time-series of step counts
Minutely.csv Minutely summaries
Hourly.csv Hourly summaries
Daily.csv Daily summaries

Machine learning model type

By default, the stepcount tool employs a self-supervised Resnet18 model to detect walking periods. However, it is possible to switch to a random forest model, by using the -t flag:

console $ stepcount sample.cwa -t rf

When using the random forest model, a set of signal features is extracted from the accelerometer data. These features are subsequently used as inputs for the model's classification process. For a comprehensive list of the extracted features, see the glossary.

Crude vs. Adjusted Estimates

Adjusted estimates are provided that account for missing data. Missing values in the time-series are imputed with the mean of the same timepoint of other available days. For adjusted totals and daily statistics, 24h multiples are needed and will be imputed if necessary. Estimates will be NaN where data is still missing after imputation.

Processing CSV files

If a CSV file is provided, the following header is expected: time, x, y, z.

Example: console time,x,y,z 2013-10-21 10:00:08.000,-0.078923,0.396706,0.917759 2013-10-21 10:00:08.010,-0.094370,0.381479,0.933580 2013-10-21 10:00:08.020,-0.094370,0.366252,0.901938 2013-10-21 10:00:08.030,-0.078923,0.411933,0.901938 ...

If the CSV file has a different header, use the option --txyz to specify the time and x-y-z columns, in that order. For example:

console HEADER_TIMESTAMP,X,Y,Z 2013-10-21 10:00:08.000,-0.078923,0.396706,0.917759 2013-10-21 10:00:08.010,-0.094370,0.381479,0.933580 2013-10-21 10:00:08.020,-0.094370,0.366252,0.901938 2013-10-21 10:00:08.030,-0.078923,0.411933,0.901938 ...

then use: console $ stepcount my-file.csv --txyz HEADER_TIMESTAMP,X,Y,Z

Processing multiple files

Windows

To process multiple files you can create a text file in Notepad which includes one line for each file you wish to process, as shown below for file1.cwa, file2.cwa, and file2.cwa.

Example text file commands.txt: console stepcount file1.cwa & stepcount file2.cwa & stepcount file3.cwa :ENDOnce this file is created, runcmd < commands.txt` from the terminal.

Linux

Create a file command.sh with: console stepcount file1.cwa stepcount file2.cwa stepcount file3.cwa Then, run bash command.sh from the terminal.

Collating outputs

A utility script is provided to collate outputs from multiple runs:

console $ stepcount-collate-outputs outputs/ This will collate all *-Info.json files found in outputs/ and generate a CSV file.

Contributing

If you would like to contribute to this repository, please check out CONTRIBUTING.md. We welcome contributions in the form of bug reports, feature requests, and pull requests.

Citing our work

When using this tool, please consider citing the works listed in CITATION.md.

Licence

See LICENSE.md.

Acknowledgements

We would like to thank all our code contributors, manuscript co-authors, and research participants for their help in making this work possible.

Owner

Name: Oxford Wearables Group
Login: OxWearables
Kind: organization
Location: United Kingdom

Twitter: OxWearables
Repositories: 27
Profile: https://github.com/OxWearables

Citation (CITATION.cff)

cff-version: 1.0.0
message: "If you use this software, please cite it as below."
authors:
- family-names: "Chan"
  given-names: "Shing"
  orcid: "https://orcid.org/0000-0001-9600-5575"
- family-names: "Small"
  given-names: "Scott R"
  orcid: "https://orcid.org/0000-0003-3603-8062"
- family-names: "Acquah"
  given-names: "Aidan"
  orcid: "https://orcid.org/0000-0002-3241-1280"
- family-names: "Mertes"
  given-names: "Gert"
  # orcid: 
- family-names: "Doherty"
  given-names: "Aiden"
  orcid: "https://orcid.org/0000-0003-1840-0451"
title: "Improved Step Counting via Foundation Models for Wrist-Worn Accelerometers"
doi: 10.5281/zenodo.14535974
date-released: 2023-02-10
url: "https://github.com/OxWearables/stepcount"

GitHub Events

Total

Create event: 27
Issues event: 7
Release event: 10
Watch event: 18
Delete event: 18
Issue comment event: 7
Push event: 36
Pull request event: 37
Fork event: 1

Last Year

Create event: 27
Issues event: 7
Release event: 10
Watch event: 18
Delete event: 18
Issue comment event: 7
Push event: 36
Pull request event: 37
Fork event: 1

Committers

Last synced: almost 3 years ago

All Time

Total Commits: 172
Total Committers: 4
Avg Commits per committer: 43.0
Development Distribution Score (DDS): 0.128

Top Committers

Name	Email	Commits
Shing Chan	c**m@g**m	150
Scott Small	4**r@u**m	15
Gert Mertes	h**y@g**e	5
Scott Small	s**l@n**k	2

Committer Domains (Top 20 + Academic)

ndph.ox.ac.uk: 1 gertmertes.be: 1

Issues and Pull Requests

Last synced: 6 months ago

All Time

Total issues: 44
Total pull requests: 178
Average time to close issues: about 1 month
Average time to close pull requests: about 14 hours
Total issue authors: 19
Total pull request authors: 6
Average comments per issue: 1.86
Average comments per pull request: 0.09
Merged pull requests: 161
Bot issues: 0
Bot pull requests: 0

Past Year

Issues: 4
Pull requests: 49
Average time to close issues: 6 days
Average time to close pull requests: about 10 hours
Issue authors: 4
Pull request authors: 2
Average comments per issue: 0.25
Average comments per pull request: 0.02
Merged pull requests: 40
Bot issues: 0
Bot pull requests: 0

View more stats

Top Authors

Issue Authors

chanshing (15)
muschellij2 (5)
smallsr (4)
ashreves (3)
Maylor8 (2)
angerhang (2)
freeman-jr1 (1)
StephenLeonardGreen (1)
steffenhartmeyer (1)
chriszal (1)
cWam-zz (1)
lilykoff (1)
SrinivasChoudhury (1)
choesy (1)
dannylvn (1)

Pull Request Authors

chanshing (162)
aidanacquah (5)
muschellij2 (4)
smallsr (3)
gmertes (2)
KPCOFGS (2)

Top Labels

Issue Labels

Pull Request Labels

Packages

Total packages: 1
Total downloads:
- pypi 756 last-month

Total dependent packages: 1
Total dependent repositories: 0
Total versions: 61
Total maintainers: 1

pypi.org: stepcount

Step counter for wrist-worn accelerometers compatible with the UK Biobank Accelerometer Dataset

Homepage: https://github.com/OxWearables/stepcount
Documentation: https://stepcount.readthedocs.io/
License: See LICENSE file.
Latest release: 3.14.0
published 6 months ago

Versions: 61
Dependent Packages: 1
Dependent Repositories: 0
Downloads: 756 Last month

Rankings

Dependent packages count: 6.6%

Downloads: 8.3%

Average: 16.9%

Forks count: 17.3%

Stargazers count: 21.8%

Dependent repos count: 30.6%

Maintainers (1)

chanshing

Last synced: 6 months ago

stepcount

Science Score: 77.0%

Keywords

Repository

Basic Info

Statistics

Topics

Metadata Files

README.md

stepcount

Install

Usage

Process an AX3 file

Or an ActiGraph file

Or a GENEActiv file

Or a CSV file (see data format below)

Summary

Estimated Daily Steps

Troubleshooting

Output files

Machine learning model type

Crude vs. Adjusted Estimates

Processing CSV files

Processing multiple files

Windows

Linux

Collating outputs

Contributing

Citing our work

Licence

Acknowledgements

Owner

Citation (CITATION.cff)

GitHub Events

Total

Last Year

Committers

All Time

Top Committers

Committer Domains (Top 20 + Academic)

Issues and Pull Requests

All Time

Past Year

Top Authors

Issue Authors

Pull Request Authors

Top Labels

Issue Labels

Pull Request Labels

Packages

pypi.org: stepcount

Rankings

Maintainers (1)