FlowReg1D

Python toolbox scaffold for fast variational 1D alignment.

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.

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

On Linux or macOS:

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

Quickstart

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

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:

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:

flowreg1d erp validate --config examples/erp_config.toml

Development

pip install -e .[test,docs]
pytest

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

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:

@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:

@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}
}