Motion2Health: Livestock Accelerometry & Health Outcome Prediction

Motion2Health is an open-source Python package and research framework for livestock health outcome prediction (Gamma-Glutamyl Transferase - GGT) using continuous triaxial accelerometry data and behavior classification.

---

🚀 Key Features

• Package-First Modular Architecture: Includes high-level API wrappers, pre-trained PyTorch deep learning models, preprocessing pipelines, and a command-line interface (CLI).
• Unified Predictor Engine (GGTPredictor): Simple Python API and CLI tool to run GGT outcome predictions using 12 pre-trained classical and deep learning workflows.
• CLI Terminal Tool (motion2health): Run predictions directly from your terminal or bash scripts without writing Python boilerplate code.
• Automated Test Suite: Built-in pytest coverage for data preprocessing, neural network inference, and CLI execution.
• 12 Benchmarking Workflows:
  • Classical Tabular Models: ElasticNet, LME, RandomForest, SVM
  • Deep Learning Models: MultiScale-CNN + LSTM, MultiScale-CNN + Causal Transformer
  • Direct Sensor & Behavior-Disentangled Architectures

---

📦 Installation

Install directly via pip:

pip install motion2health

Or install from source in editable mode:

git clone https://github.com/SydneyBioX/motion2health.git
cd motion2health
pip install -e .[dev]

---

💡 Quick Start

Python API

from motion2health import GGTPredictor

# Initialize predictor with the behavior-disentangled Random Forest model
predictor = GGTPredictor(workflow="behaviour_rf")

# Predict GGT outcome on Study Day 14
predicted_ggt = predictor.predict_ggt(
    csv_path="data/sample_animal.csv",
    baseline_ggt=32.0,    # Pre-trial baseline GGT (U/L)
    study_day=14          # Target day (-7 to 24)
)

print(f"Predicted GGT Value: {predicted_ggt:.2f} U/L")

Deep Learning (PyTorch Causal Transformer) Workflow

# Initialize deep learning Transformer workflow
predictor_dl = GGTPredictor(workflow="behaviour_transformer")

# Predict GGT with Monte Carlo Test-Time Augmentation (TTA)
predicted_ggt_dl = predictor_dl.predict_ggt(
    csv_path="data/sample_animal.csv",
    baseline_ggt=28.5,
    study_day=7
)

print(f"Transformer Predicted GGT: {predicted_ggt_dl:.2f} U/L")

---

💻 Command-Line Interface (CLI)

Run predictions directly from the shell:

# Display package info and available model workflows
motion2health info

# Run prediction on a 1 Hz sensor CSV file
motion2health predict \
  --csv data/sample_animal.csv \
  --baseline-ggt 35.0 \
  --study-day 10 \
  --workflow direct_transformer

Output as JSON for automated pipelines:

motion2health predict --csv data/sample_animal.csv --baseline-ggt 35.0 --study-day 10 --json

---

🏗️ Repository Layout

motion2health/
├── motion2health/               # Package source code
│   ├── __init__.py              # Package initialization & exports
│   ├── predictor.py            # Main GGTPredictor class
│   ├── architectures.py        # PyTorch neural net architectures (CNN/LSTM/Transformer)
│   ├── preprocessing.py        # 1 Hz rolling feature extraction & validation
│   ├── cli.py                  # Command Line Interface (CLI) engine
│   └── models/                 # Pre-trained model weight binaries
├── tests/                      # Automated pytest unit test suite
│   ├── test_predictor.py
│   ├── test_preprocessing.py
│   └── test_cli.py
├── examples/                   # Python usage examples
│   ├── basic_prediction.py
│   └── advanced_workflows.py
├── docs/                       # User guides and architecture documentation
│   ├── user_guide.md
│   └── architectures/
├── paper/                      # Research paper benchmark & reproduction scripts
│   ├── README.md
│   ├── evaluate.py
│   └── train_production_models.py
├── pyproject.toml              # Build & package configuration
├── setup.py                    # Setuptools entrypoint
└── README.md

---

🧪 Running Tests

Run unit tests locally with pytest:

pytest

---

📖 Research Paper Benchmarks

Research paper evaluation scripts, 5-fold cross-validation benchmarks, and SHAP explainability routines are located in the paper/ directory.

---

📜 License

Distributed under the MIT License.