Metadata-Version: 2.4
Name: actipy
Version: 3.8.2
Summary: Python package to process wearable accelerometer data
Home-page: https://github.com/OxWearables/actipy
Download-URL: https://github.com/OxWearables/actipy
Author: Shing Chan, Aiden Doherty
Maintainer: Shing Chan
Maintainer-email: shing.chan@ndph.ox.ac.uk
License: See LICENSE.md
Keywords: wearable accelerometer data processing
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.md
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.7
Requires-Dist: pandas>=1.3
Requires-Dist: statsmodels>=0.13
Requires-Dist: tqdm
Provides-Extra: dev
Requires-Dist: flake8; extra == "dev"
Requires-Dist: autopep8; extra == "dev"
Requires-Dist: ipython; extra == "dev"
Requires-Dist: ipdb; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: tomli; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: joblib; extra == "dev"
Requires-Dist: memray; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.2; extra == "docs"
Requires-Dist: sphinx_rtd_theme>=1.0; extra == "docs"
Requires-Dist: readthedocs-sphinx-search>=0.1; extra == "docs"
Requires-Dist: docutils<0.18; extra == "docs"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: download-url
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# actipy

[![Github all releases](https://img.shields.io/github/release/OxWearables/actipy.svg)](https://github.com/OxWearables/actipy/releases/)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.14514488.svg)](https://doi.org/10.5281/zenodo.14514488)

A Python package to process accelerometer data.

Axivity3 and Axivity6 (.cwa), Actigraph (.gt3x), GENEActiv (.bin), and Matrix (.bin) files are supported,
as well as custom CSV files.

Axivity3 is the activity tracker watch used in the large-scale
[UK-Biobank accelerometer study](https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0169649).

## 🚀 Getting started

### Prerequisite

- 🐍 Python 3.8 or greater
    ```console
    $ python --version  # or python3 --version
    ```

- ☕ Java 8 (1.8.0) or greater
    ```console
    $ java -version
    ```

### 📦 Install

```bash
$ pip install actipy
```

<!-- With Conda:
```bash
$ conda install -c oxwear actipy
``` -->

## 📖 Usage

```python
import actipy

data, info = actipy.read_device("sample.cwa.gz",  # or "sample.gt3x.gz" or "sample.bin.gz"
                                 lowpass_hz=20,
                                 calibrate_gravity=True,
                                 detect_nonwear=True,
                                 resample_hz=50)
```

Output:
```console
data [pandas.DataFrame]
                                 x         y         z  temperature      light
 time
 2014-05-07 13:29:50.430 -0.513990  0.070390  1.671922    20.000000  78.420235
 2014-05-07 13:29:50.440 -0.233940 -0.586568  0.082067    20.000000  78.420235
 2014-05-07 13:29:50.450 -0.080319 -0.950817 -0.810613    20.000000  78.420235
 2014-05-07 13:29:50.460 -0.067236 -0.975886 -0.865132    20.000000  78.420235
 2014-05-07 13:29:50.470 -0.109636 -0.857004 -0.508666    20.000000  78.420235
 ...                           ...       ...       ...          ...        ...

info [dict]
 Filename                 : data/sample.cwa.gz
 Filesize(MB)             : 69.4
 Device                   : Axivity
 DeviceID                 : 13110
 ReadErrors               : 0
 SampleRate               : 100.0
 ReadOK                   : 1
 StartTime                : 2014-05-07 13:29:50
 EndTime                  : 2014-05-13 09:50:33
 NumTicks                 : 51391800
 WearTime(days)           : 5.847725231481482
 NumInterrupts            : 1
 ResampleRate             : 50
 NumTicksAfterResample    : 25262174
 LowpassOK                : 1
 LowpassCutoff(Hz)        : 20.0
 CalibErrorBefore(mg)     : 82.95806873592024
 CalibErrorAfter(mg)      : 4.434966371604519
 CalibOK                  : 1
 NonwearTime(days)        : 0.0
 NumNonwearEpisodes       : 0
 ...

```
📚 Refer to the [Glossary](GLOSSARY.md) for a comprehensive list of outputs.

### ⚙️ Optional parameters

You can also specify time ranges and additional options:

```python
data, info = actipy.read_device(
    "sample.cwa.gz",
    lowpass_hz=20,
    calibrate_gravity=True,
    detect_nonwear=True,
    resample_hz=50,
    start_time="2014-05-07 18:00:00",  # Start time (ISO format)
    end_time="2014-05-09 18:00:00",    # End time (ISO format)
    skipdays=1,                         # Skip first day
    cutdays=2,                          # Cut last 2 days
    start_first_complete_minute=True,  # Align to minute boundaries
    calibrate_gravity_kwargs={'stdtol_min': 0.01},  # Custom calibration params
    flag_nonwear_kwargs={'patience': '60m'}         # Custom nonwear params
)
```

### 📊 Processing a custom CSV file
You can also use the routines in `actipy.processing` to process custom CSV files, or for more fine-grained control:

```python
import actipy.processing as P

data, info_lowpass = P.lowpass(data, 100, 20)
data, info_calib = P.calibrate_gravity(data)
data, info_nonwear = P.flag_nonwear(data)
data, info_resample = P.resample(data, 50)
```

See the [documentation](https://actipy.readthedocs.io/en/latest/) for more.

### 💻 Processing from the command line
We also provide a command-line tool to process a device file (currently, only AX3 and AX6 are supported) and output to CSV:
```bash
$ read_cwa sample.cwa.gz -o outputs --lowpass-hz 20 --resample-hz 50 --calibrate-gravity --detect-nonwear
```

Outputs:
  - 📄 `outputs/sample/sample.csv.gz`
  - 📋 `outputs/sample/sample-Info.json`


## 🤝 Contributing
If you would like to contribute to this repository, please check out [CONTRIBUTING.md](https://github.com/OxWearables/actipy/blob/main/CONTRIBUTING.md).
We welcome contributions in the form of bug reports, feature requests, and pull requests. 

## 📜 License
See [LICENSE.md](LICENSE.md).
