Metadata-Version: 2.4
Name: benchmarkhar
Version: 0.1.0
Summary: Benchmark framework for Human Activity Recognition (HAR) with classical, deep learning, and external model adapters.
Author: BenchmarkHAR contributors
License-Expression: MIT
Keywords: har,human activity recognition,benchmark,machine learning,deep learning,foundation model
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.21.0
Requires-Dist: pandas>=1.3.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: scikit-learn>=1.0.0
Requires-Dist: joblib>=1.1.0
Requires-Dist: PyYAML>=6.0
Requires-Dist: tqdm>=4.60.0
Requires-Dist: psutil>=5.8.0
Provides-Extra: deep-learning
Requires-Dist: torch>=1.10.0; extra == "deep-learning"
Requires-Dist: tensorflow>=2.8.0; extra == "deep-learning"
Requires-Dist: keras>=3.0.0; extra == "deep-learning"
Requires-Dist: einops>=0.3.0; extra == "deep-learning"
Requires-Dist: h5py>=3.0.0; extra == "deep-learning"
Provides-Extra: visualization
Requires-Dist: matplotlib>=3.5.0; extra == "visualization"
Requires-Dist: seaborn>=0.11.0; extra == "visualization"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.5.0; extra == "dev"
Requires-Dist: build>=1.0.0; extra == "dev"
Provides-Extra: all
Requires-Dist: torch>=1.10.0; extra == "all"
Requires-Dist: tensorflow>=2.8.0; extra == "all"
Requires-Dist: keras>=3.0.0; extra == "all"
Requires-Dist: einops>=0.3.0; extra == "all"
Requires-Dist: h5py>=3.0.0; extra == "all"
Requires-Dist: matplotlib>=3.5.0; extra == "all"
Requires-Dist: seaborn>=0.11.0; extra == "all"
Requires-Dist: pytest>=8.0.0; extra == "all"
Requires-Dist: ruff>=0.5.0; extra == "all"
Requires-Dist: build>=1.0.0; extra == "all"
Dynamic: license-file

# BenchmarkHAR

BenchmarkHAR is a Human Activity Recognition (HAR) benchmarking framework for classical machine learning, deep learning, and external foundation-model adapters.

The library is packaged as a standard Python package and can be installed with `pip`.

Important:
- The core framework lives in `benchmarkhar/`.
- Raw datasets and research outputs stay outside the installable wheel.
- External repositories such as BioPM and TinyHAR / ISWC22_HAR are treated as optional dependencies or adapters rather than being merged into the core package.

## Installation

From the repository root:

```bash
pip install .
```

Optional feature sets:

```bash
pip install ".[deep-learning]"
pip install ".[visualization]"
pip install ".[all]"
```

## Package structure

```text
BenchmarkHAR/
├── src/
│   └── benchmarkhar/
│       ├── datasets/
│       ├── models/
│       ├── preprocessing/
│       ├── features/
│       ├── dimension_reduction/
│       ├── utils/
│       ├── cli.py
│       └── __init__.py
├── configs/
├── scripts/
├── data/
├── results/
├── tests/
├── pyproject.toml
├── requirements.txt
├── README.md
└── LICENSE
```

## Python usage

```python
import benchmarkhar
from benchmarkhar.utils.load_config import load_config

config = load_config("pamap2")
print(config["name"])
```

The recommended pattern is to keep datasets and generated artifacts under a project root you control:

```python
from benchmarkhar.utils.load_config import load_config

config = load_config("pamap2", root="/path/to/your/project")
print(config["raw_path"])
```

## Dataset loading

BenchmarkHAR expects datasets to be provided separately from the wheel. The repo contains dataset YAML files in `configs/datasets/`, but raw data is never bundled into the package.

Typical usage:

```python
from benchmarkhar.utils.load_config import load_dataset

cfg = load_dataset("pamap2", root="/path/to/data-root")
```

## Preprocessing

```python
from benchmarkhar.preprocessing.windowing import sliding_window_multilabel
import numpy as np

X = np.random.randn(100, 3).astype(np.float32)
labels = {"activity_id": np.array(["Walking"] * 100, dtype=object)}
windows, out_labels = sliding_window_multilabel(X, labels, window_size=10, step_size=5)
```

## Models

Core model registry:

```python
from benchmarkhar.models import MODEL_REGISTRY
print(sorted(MODEL_REGISTRY))
```

Common models include:
- random_forest
- logistic_regression
- cnn, lstm, dnn, rnn, deepconv_lstm
- tinyhar (when the external TinyHAR repository is available)
- astar_har
- biopm (via the external BioPM dependency / adapter)

## External model repositories

BenchmarkHAR keeps external repositories separate from the core package.

### BioPM

BioPM should be cloned separately and made importable through your environment, or used via the adapter class:

```python
from benchmarkhar.models import BioPM

bio = BioPM()
```

This wrapper intentionally does not copy or rewrite the BioPM source code. It only adapts the external dependency to the benchmark interface.

### TinyHAR / ISWC22_HAR

```python
from benchmarkhar.models import TinyHAR

tiny = TinyHAR()
```

If the external TinyHAR repository is not available, the adapter raises a clear `ImportError` explaining how to install it.

## CLI

The installable CLI is available after installation:

```bash
benchmarkhar --help
benchmarkhar --list-datasets
```

## Experimental scripts

Research scripts are kept under `scripts/` and are not installed as library modules. They can still be run from the repository checkout:

```bash
python scripts/run.py --dataset pamap2 --model random_forest --step full
```

## Testing

From the repository root:

```bash
python -m pytest -q
```

## Build

```bash
python -m build
```

## Citation / provenance

BenchmarkHAR is designed to preserve external repositories used in the benchmark pipeline.

- BioPM: please cite the original BioPM publication and repository.
- TinyHAR / ISWC22_HAR: please cite the original TinyHAR / ISWC22_HAR paper and repository.

## Notes

- Raw data, processed artifacts, and experiment outputs remain outside the wheel.
- The project is built to work from any Python environment after `pip install .`.
- The installation is intentionally compatible with a research workflow that stores data and checkpoints outside the package.
