Metadata-Version: 2.4
Name: actirhythm-toolkit
Version: 0.2.0
Summary: Reproducible accelerometer analysis pipeline for circadian and behavioral rhythm studies
Home-page: https://github.com/nerminjukan/masters-thesis
Author: Nermin Jukan
License: MIT
Project-URL: Source, https://github.com/nerminjukan/masters-thesis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: pyarrow>=5.0.0
Requires-Dist: matplotlib>=3.4.0
Requires-Dist: seaborn>=0.11.0
Requires-Dist: statsmodels>=0.13.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: hmmlearn>=0.2.7
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: loguru>=0.5.3
Provides-Extra: ml
Requires-Dist: xgboost>=1.5.0; extra == "ml"
Requires-Dist: pomegranate>=0.14.8; extra == "ml"
Requires-Dist: CosinorPy>=1.1; extra == "ml"
Provides-Extra: glmm
Requires-Dist: pymer4>=0.7.0; extra == "glmm"
Requires-Dist: polars>=1.0.0; extra == "glmm"
Requires-Dist: rpy2>=3.6.0; extra == "glmm"
Requires-Dist: great-tables>=0.23.0; extra == "glmm"
Provides-Extra: notebooks
Requires-Dist: jupyter>=1.0.0; extra == "notebooks"
Requires-Dist: ipykernel>=6.0.0; extra == "notebooks"
Requires-Dist: nbformat>=5.1.0; extra == "notebooks"
Requires-Dist: tqdm>=4.62.0; extra == "notebooks"
Provides-Extra: dev
Requires-Dist: pytest>=6.2.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: python-dotenv>=0.19.0; extra == "dev"
Dynamic: author
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# ActiRhythm Toolkit

ActiRhythm Toolkit is a command-line workflow for analysing accelerometer activity data and characterising behavioural and circadian rhythms. It provides preprocessing, hidden Markov model state estimation, downstream rhythm analysis, and optional machine-learning and GLMM workflows.

## Installation

### Install from PyPI (recommended)

```bash
python -m pip install actirhythm-toolkit
```

Optional extras from PyPI:

```bash
python -m pip install "actirhythm-toolkit[ml]"
python -m pip install "actirhythm-toolkit[glmm]"
python -m pip install "actirhythm-toolkit[notebooks]"
```

PyPI project page:

https://pypi.org/project/actirhythm-toolkit/

### Optional capabilities

```bash
python -m pip install "actirhythm-toolkit[ml]"
python -m pip install "actirhythm-toolkit[glmm]"
python -m pip install "actirhythm-toolkit[notebooks]"
```

The `glmm` extra also requires a local R installation and compatible R packages. Check your environment with:

```bash
actirhythm glmm-doctor
```

## Quick Start

Run the complete workflow from a project directory containing your input data and optional `config.yaml`:

```bash
actirhythm
```

Inspect the planned inputs and outputs before running:

```bash
actirhythm --dry-run
```

Run a named analysis version:

```bash
actirhythm full --run-version v1
```

## Commands

```bash
actirhythm full
actirhythm preprocess
actirhythm analytics
actirhythm glmm-doctor
```

Run `actirhythm --help` for all configuration, data-path, output-path, and resume options.

## Input Data

The workflow accepts accelerometer CSV data with a timestamp, subject identifier, activity measure, and optional axis or posture measurements. Use `--data-revised-dir` to specify an input directory and `--raw-data-file` to provide a fallback CSV file.

### Choosing an activity signal

Set the analysis signal with `--activity-signal` (default `ActMindata`).

Some loggers export only the **average** of each accelerometer axis per epoch. The
magnitude of a mean acceleration vector is dominated by gravity, so it describes body
**orientation**, not movement intensity: it is longest when the animal holds a single
posture and shortens as orientation varies within the epoch. Such a magnitude can
therefore be *negatively* correlated with real activity and must not be used as an
intensity index.

The toolkit still computes `activity_xy` and `activity_xyz` from the axes, but treats them
as posture descriptors. A genuine intensity metric (ODBA/VeDBA) requires within-epoch
variance, which averaged exports do not retain. Where a firmware activity count such as
`ActMindata` is available, prefer it.

Posture descriptors remain useful for **validating** decoded states: resting states should
show a higher and less variable posture magnitude than active ones. The preprocessing
stage writes this check to `posture_state_validation.csv`.

### Deployment windows

Records collected after a device is removed cannot be identified from the signal alone —
a retrieved logger still registers varying posture and occasional activity while it is
being transported, which is indistinguishable from genuine low-activity behaviour.
Documented removal times are required.

Supply them via `qc.DEPLOYMENT_END_OVERRIDES`, or call `qc.apply_deployment_windows()`
with your own mapping of subject to cut-off timestamp.

### Subject anonymisation

`qc.assign_subject_codes()` replaces subject names with codes (`S01`, `S02`, …) ordered by
first observation, and the preprocessing stage writes the mapping to
`subject_code_mapping.csv`. Treat that file as confidential — it is the re-identification
key. It is not required to reproduce any result.

### Dwell-time filtering

`--min-dwell` sets the minimum bout length in bins for the post-decoding filter
(default `2`; at 15-minute sampling that is 30 minutes).

This filter suppresses decoder flicker but also alters the decoded sequence, so transition
probabilities and dwell-time summaries describe the filtered series. Choose the threshold
against your own data rather than by convention: a value above the unfiltered median bout
length discards a large share of genuine bouts. Each run writes
`dwell_time_sensitivity.csv` comparing 15-, 30- and 60-minute thresholds so the choice can
be justified.

## Development

1. Clone the repository:

```bash
git clone https://github.com/nerminjukan/masters-thesis.git
cd masters-thesis
```

2. Create a virtual environment:

```bash
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
```

3. Install in editable mode:

```bash
python -m pip install -e .
```

Development extras:

```bash
python -m pip install -e .[dev]
python -m pip install -e .[ml]
python -m pip install -e .[glmm]
python -m pip install -e .[notebooks]
```

## Source

Source code and issue tracking: https://github.com/nerminjukan/masters-thesis

## License

MIT License.
