Metadata-Version: 2.4
Name: flowreg1d
Version: 1.0.0a1
Summary: Python toolbox scaffold for fast variational 1D signal and ERP alignment
Author-email: Philipp Flotho <Philipp.Flotho@uni-saarland.de>
License: CC BY-NC-SA 4.0
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: Other/Proprietary License
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: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Image Processing
Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=2.0.0
Requires-Dist: scipy>=1.14.0
Requires-Dist: opencv-contrib-python>=4.10.0
Requires-Dist: numba>=0.60.0
Requires-Dist: pydantic<3.0.0,>=2.11.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli>=2.0.0; python_version < "3.11"
Provides-Extra: vis
Requires-Dist: matplotlib>=3.8.0; extra == "vis"
Requires-Dist: scikit-learn>=1.5.0; extra == "vis"
Provides-Extra: test
Requires-Dist: pytest>=8.0.0; extra == "test"
Requires-Dist: pytest-cov>=5.0.0; extra == "test"
Provides-Extra: docs
Requires-Dist: sphinx~=7.3; extra == "docs"
Requires-Dist: myst-parser~=4.0; extra == "docs"
Requires-Dist: linkify-it-py~=2.0; extra == "docs"
Requires-Dist: sphinx-copybutton~=0.5; extra == "docs"
Requires-Dist: sphinx-design~=0.6; extra == "docs"
Requires-Dist: sphinxcontrib-bibtex~=2.6; extra == "docs"
Requires-Dist: pydata-sphinx-theme~=0.15; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints~=2.0; extra == "docs"

[![PyPI - Version](https://img.shields.io/pypi/v/flowreg1d)](https://pypi.org/project/flowreg1d/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/flowreg1d)](https://pypi.org/project/flowreg1d/)
[![PyPI - License](https://img.shields.io/pypi/l/flowreg1d)](LICENSE)
[![PyPI - Downloads](https://img.shields.io/pypi/dm/flowreg1d)](https://pypistats.org/packages/flowreg1d)
[![PyPI Downloads](https://static.pepy.tech/personalized-badge/flowreg1d?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=GREEN&left_text=all+time+downloads)](https://pepy.tech/projects/flowreg1d)[![GitHub Actions](https://github.com/FlowRegSuite/flowreg1D/actions/workflows/pypi-release.yml/badge.svg)](https://github.com/FlowRegSuite/flowreg1D/actions/workflows/pypi-release.yml)
[![Documentation Status](https://readthedocs.org/projects/flowreg1d/badge/?version=latest)](https://flowreg1d.readthedocs.io/en/latest/?badge=latest)

# FlowReg1D

Python toolbox scaffold for fast variational 1D alignment.

![Synthetic line scan alignment](https://raw.githubusercontent.com/FlowRegSuite/flowreg1D/843af758b57d7aaac12e6d52c40deb4ae94e59a4/img/banner.gif)

## Under Development

This project is still in an **alpha stage**. Expect rapid changes, incomplete features, and possible breaking updates between releases.

- The API may evolve as we stabilize core functionality.
- Documentation and examples are incomplete.
- Feedback and bug reports are especially valuable at this stage.

## Purpose

FlowReg1D is intended to provide Python workflows for 1D signal and ERP latency
alignment using the same general software style as PyFlowReg: installable
`src` package layout, typed options, ERP-focused TOML configuration, examples,
Sphinx documentation, pytest coverage, CLI support, and release-ready GitHub
Actions files.

The future numerical port should use these MATLAB/C++ baselines:

- `variational_aligner/core/align_lines.m`
- `variational_aligner/core/align_core.cpp`
- `ERP_alignment/VERPA/functionsERP/Var_Alignment.m`
- `ERP_alignment/VERPA/functionsERP/CrossCorrRef.m`

## Requirements

Python 3.10 or newer.

```bash
python -m venv .venv
.venv\Scripts\activate
pip install -e .[test]
```

On Linux or macOS:

```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .[test]
```

## Quickstart

The public API is already shaped for the later solver port:

```python
import numpy as np

from flowreg1d.core import AlignmentOptions, align_lines

signals = np.random.rand(20, 500)
reference = signals.mean(axis=0)
options = AlignmentOptions(alpha=1.0, sigma=5.0, iterations=100)

registered, displacement = align_lines(signals, reference, options=options)
```

In this scaffold version, `align_lines` raises `NotImplementedError`.

## ERP CLI Configuration

ERP alignment configuration follows the same typed-options pattern as PyFlowReg
without adding higher-level workflow orchestration:

```toml
input_file = "erp_trials.npy"
output_file = "aligned_erp_trials.npy"

[alignment_options]
alpha = 1.0
sigma = 5.0
iterations = 100
levels = 40

[erp_options]
reference_method = "mean"
iter_ref = 1
fs = 200.0
denoising = "none"
```

Validate a configuration with:

```bash
flowreg1d erp validate --config examples/erp_config.toml
```

## Development

```bash
pip install -e .[test,docs]
pytest
```

Pre-commit hooks are included for code style and file hygiene:

```bash
pip install pre-commit
pre-commit install
pre-commit run --all-files
```

## Citation

If you use this toolbox for your work, please cite:

> P. Flotho, D. Thinnes, B. Kuhn, C. J. Roome, J. F. Vibell, and D. J. Strauss,
> "Fast variational alignment of non-flat 1D displacements for applications in
> neuroimaging," Journal of Neuroscience Methods, 353, 109076, 2021.
> doi: 10.1016/j.jneumeth.2021.109076

BibTeX:

```bibtex
@article{flotho2021fast,
  author = {Flotho, Philipp and Thinnes, David and Kuhn, Bernd and Roome, Christopher J. and Vibell, Jonas F. and Strauss, Daniel J.},
  title = {Fast variational alignment of non-flat 1D displacements for applications in neuroimaging},
  journal = {Journal of Neuroscience Methods},
  volume = {353},
  pages = {109076},
  year = {2021},
  doi = {10.1016/j.jneumeth.2021.109076}
}
```

If you use it for ERP alignment, please additionally cite:

> D. Thinnes, P. Flotho, F. I. Corona-Strauss, D. J. Strauss, and J. F. Vibell,
> "Compensation of ERP Latency Jitter Using Fast Variational 1D Displacement
> Estimation," TechRxiv, 2025. doi: 10.36227/techrxiv.174062901.13096882/v1

BibTeX:

```bibtex
@article{thinnes2025erp,
  author = {Thinnes, D. and Flotho, P. and Corona-Strauss, F. I. and Strauss, D. J. and Vibell, J. F.},
  title = {Compensation of ERP Latency Jitter Using Fast Variational 1D Displacement Estimation},
  journal = {TechRxiv},
  year = {2025},
  doi = {10.36227/techrxiv.174062901.13096882/v1}
}
```
