Metadata-Version: 2.3
Name: arcos4py
Version: 0.3.1
Summary: A python package to detect collective spatio-temporal phenomena.
License: MIT
Author: Benjamin Graedel
Author-email: benjamin.graedel@unibe.ch
Requires-Python: >=3.9.1,<4.0.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Natural Language :: English
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: Programming Language :: Python :: 3.9
Provides-Extra: dev
Provides-Extra: doc
Provides-Extra: test
Requires-Dist: PyYAML (>=6.0,<7.0) ; extra == "test"
Requires-Dist: black (>=24.1.1,<25.0.0) ; extra == "test"
Requires-Dist: bump2version (>=1.0.1,<2.0.0) ; extra == "dev"
Requires-Dist: flake8 (>=3.9.2,<4.0.0) ; extra == "test"
Requires-Dist: flake8-docstrings (>=1.6.0,<2.0.0) ; extra == "test"
Requires-Dist: isort (>=5.8.0,<6.0.0) ; extra == "test"
Requires-Dist: joblib (>=1.2.0,<2.0.0)
Requires-Dist: kneed (>=0.7.0)
Requires-Dist: matplotlib (>=3.6)
Requires-Dist: mkdocs (>=1.3.0,<2.0.0) ; extra == "doc"
Requires-Dist: mkdocs-autorefs (>=0.5.0,<0.6.0) ; extra == "doc"
Requires-Dist: mkdocs-include-markdown-plugin (>=3.3.0,<4.0.0) ; extra == "doc"
Requires-Dist: mkdocs-material (>=9.5.9,<10.0.0) ; extra == "doc"
Requires-Dist: mkdocs-material-extensions (>=1.0.3,<2.0.0) ; extra == "doc"
Requires-Dist: mkdocstrings-python (>=1.2.1,<2.0.0) ; extra == "doc"
Requires-Dist: mypy (>=0.981,<0.982) ; extra == "test"
Requires-Dist: numba (>=0.60.0,<0.61.0)
Requires-Dist: numpy (>=1.23)
Requires-Dist: pandas (>=1.4.0)
Requires-Dist: pot (>=0.9.4,<0.10.0)
Requires-Dist: pre-commit (>=2.12.0,<3.0.0) ; extra == "dev"
Requires-Dist: pytest (>=8.0.0,<9.0.0) ; extra == "test"
Requires-Dist: pytest-cov (>=2.12.0,<3.0.0) ; extra == "test"
Requires-Dist: scikit-image (>=0.20.0) ; python_version < "3.12"
Requires-Dist: scikit-image (>=0.22.0) ; python_version >= "3.12"
Requires-Dist: scikit-learn (>=1.3.0)
Requires-Dist: scipy (>=1.9)
Requires-Dist: seaborn (>=0.13.2,<0.14.0)
Requires-Dist: toml (>=0.10.2,<0.11.0) ; extra == "dev"
Requires-Dist: tox (>=3.20.1,<4.0.0) ; extra == "dev"
Requires-Dist: tqdm (>=4.64.1,<5.0.0)
Requires-Dist: twine (>=3.3.0,<4.0.0) ; extra == "dev"
Requires-Dist: virtualenv (>=20.2.2,<21.0.0) ; extra == "dev"
Project-URL: Homepage, https://github.com/bgraedel/arcos4py
Description-Content-Type: text/markdown

# arcos4py

[![pypi](https://img.shields.io/pypi/v/arcos4py.svg)](https://pypi.org/project/arcos4py/)
[![conda-forge](https://img.shields.io/conda/vn/conda-forge/arcos4py)](https://anaconda.org/conda-forge/arcos4py)
[![python](https://img.shields.io/pypi/pyversions/arcos4py.svg)](https://pypi.org/project/arcos4py/)
[![Build Status](https://github.com/pertzlab/arcos4py/actions/workflows/dev.yml/badge.svg)](https://github.com/bgraedel/arcos4py/actions/workflows/dev.yml)
[![codecov](https://codecov.io/gh/pertzlab/arcos4py/branch/main/graphs/badge.svg)](https://codecov.io/github/bgraedel/arcos4py)

**arcos4py** is a Python package designed to detect and analyze collective spatiotemporal phenomena in biological imaging data.

- **Documentation:** [https://pertzlab.github.io/arcos4py](https://pertzlab.github.io/arcos4py)
- **GitHub Repository:** [https://github.com/pertzlab/arcos4py](https://github.com/pertzlab/arcos4py)
- **PyPI Package:** [https://pypi.org/project/arcos4py/](https://pypi.org/project/arcos4py/)
- **Free Software License:** MIT

---

## Features

**Automated Recognition of Collective Signalling for Python (arcos4py)** identifies collective spatial events in time-series data or microscopy images. The software tracks waves of protein activity in 2D and 3D cell cultures and follows them over time.

Such collective dynamics have been observed in:
- Epithelial homeostasis (Gagliardi et al., 2020; Takeuchi et al., 2020; Aikin et al., 2020)
- Acinar morphogenesis (Ender et al., 2020)
- Osteoblast regeneration (De Simone et al., 2021)
- Coordination of collective cell migration (Aoki et al., 2017; Hino et al., 2020)

The R package ARCOS ([https://github.com/dmattek/ARCOS](https://github.com/dmattek/ARCOS)) provides a similar R implementation. The `arcos4py` version includes more recent upgrades and added functionality:
- Event tracking directly on image data
- Split/merge detection
- Motion prediction for robust temporal linking

**Data format:** Long-table format with object coordinates, time, and optionally measurements; or binary image sequences for pixel-level analysis.

**Modular API:** Use the full ARCOS class or individual tools via `arcos.tools`. Process binary images directly using `track_events_images` in `arcos4py.tools`.

---

## New in ARCOS with ARCOS.px 🎉

We recently released a major update, **ARCOS.px**, extending `arcos4py` to track *subcellular dynamic structures* like actin waves, podosomes, and focal adhesions directly from binarized time-lapse images.

**Publication:**  
Tracking Coordinated Cellular Dynamics in Time-Lapse Microscopy with ARCOS.px. [*bioRxiv*](https://doi.org/10.1101/2025.03.14.643386)

**What’s new:**
- **Pixel-based tracking** of discontinuous, irregular structures
- **Lineage tracking** across merges and splits
- Optional **Motion prediction** and frame-to-frame linking with **optimal transport**
- **Support for DBSCAN and HDBSCAN** clustering and custom clustering methods
- **Improved memory usage and lazy evaluation** for long time series
- Integrated into **Napari** via the [`arcosPx-napari plugin`](https://github.com/pertzlab/arcospx-napari) plugin
---

### Notebooks and Reproducible Analysis

To facilitate reproducibility and provide practical examples, we have made available a collection of Jupyter notebooks that demonstrate the use of ARCOS.px in various scenarios. These notebooks cover:

**Wave Simulation**: Scripts to simulate circular & directional waves, and target & chaotic patterns using cellular automaton.

**Synthetic RhoA** Activity Wave: Analysis of optogenetically induced synthetic RhoA activity waves.

**Podosome Dynamics**: Tracking and analysis of podosome-like structures under different conditions.

**Actin Wave Tracking**: Tracking and analysis of actin waves in 2D and extractin temporal order.

You can access these notebooks in the [ARCOSpx-publication](https://github.com/pertzlab/ARCOSpx-publication) repository under the scripts directory.


## Installation

Install from PyPI:
```bash
pip install arcos4py
```

Napari Plugin
-------------
Arcos4py is also available as a Napari Plugin [arcos-gui](https://github.com/pertzlab/arcos-gui).
[arcos-gui](https://github.com/pertzlab/arcos-gui) can simplify parameter finding and visualization.

or images directly: [arcosPx-napari](https://github.com/pertzlab/arcospx-napari)

[![arcos_demo](https://img.youtube.com/vi/hG_z_BFcAiQ/0.jpg)](https://www.youtube.com/watch?v=hG_z_BFcAiQ)

## Credits

[Maciej Dobrzynski](https://github.com/dmattek) created the first version of ARCOS.

This package was created with [Cookiecutter](https://github.com/audreyr/cookiecutter) and the [waynerv/cookiecutter-pypackage](https://github.com/waynerv/cookiecutter-pypackage) project template.

