Arrhythpy

Arrhythpy is an open-source Python-based program designed to quantify and classify arrhythmias in calcium transients in an automated manner. See the corresponding paper at [https://doi.org/10.1152/ajpheart.00414.2025] for a detailed explanation.

For any questions or assistance, please feel free to contact me at karim.ajmail@mtl.maxplanckschools.de. So far, Arrhythpy only reads lsm or tif files from line scans as described in the paper. Additionally, there is the possibility to read in the transients directly as a csv file. If you need support for another file type, let me know and I will add it.

Installation

Easiest Way

The easiest way to use Arrhythpy is to download the precompiled zip file that contains the executable. To do this, go to 'Releases'. Ensure you install the correct version for your operating system:

• Windows: Arrhythpy.zip in the Arrhythpy for Windows release
• Mac: Arrhythpy.zip in the Arrhythpy for MacOS release

This executable should run independently without needing to install Python. Your operating system will probably warn you about the safety of the executable. Please trust me and download it anyway (on Windows: click 'More info' and then 'Run anyway').

Via pip / PyPI

Arrhythpy is also available as a regular Python package:

pip install arrhythpy

This installs the arrhythpy library as well as four command-line tools:

• arrhythpy – launches the graphical user interface (same as double-clicking the compiled executable)
• arrhythpy-cli – interactive single-folder analysis from the terminal (equivalent to the old main.py)
• arrhythpy-batch – runs the analysis over many sub-folders at once (equivalent to the old run_folders.py)
• arrhythpy-split – splits a long transient CSV into smaller chunks (equivalent to the old split_csv.py)

Note: the GUI (arrhythpy / arrhythpy-cli dialogs) relies on Tkinter, which ships with most standard Python installations but is occasionally missing from minimal/headless setups (some Linux distros). If import tkinter fails, install your OS's python3-tk package (e.g. sudo apt install python3-tk on Debian/Ubuntu) or use Arrhythpy purely as a library instead (see below).

You can also use Arrhythpy directly as a library in your own scripts:

from arrhythpy import run

run(
    files=["path/to/scan1.tif", "path/to/scan2.tif"],
    frequency=0.5,
    duration=10.0,
    threshold_freq=0.1,
    threshold_arrythmia=0.1,
)

Alternative Installation (build your own executable)

If the precompiled version does not work or your institution doesn't allow downloading executables without an official license, you can compile the executable yourself. To do this, first install Python and download the Python scripts by typing these commands into a terminal (e.g. Anaconda Prompt):

1. Clone the repository:

git clone https://github.com/karim-ajmail/Arrhythpy.git
cd Arrhythpy

2. Create a new environment:

conda create -n arrhythpy_env python=3.10
conda activate arrhythpy_env

3. Install dependencies:

pip install -e .[build]

4. Generate the executable via PyInstaller:

pyinstaller -n Arrhythpy --onefile src/arrhythpy/gui.py

When you navigate to the 'dist' folder, you will find the executable called Arrhythpy. You can move to a convenient directory if you like and it can be easily run to open the GUI.

Running

Once installed, simply double-click the application (or run arrhythpy from a terminal if installed via pip) to run. It takes some time until the program is open, but eventually the GUI window is opened. Please refer to the Manual for information on the parameters. After running the program, the results are saved as an excel file including some figures about the data.

You can alternatively run Arrhythpy from a terminal. If you installed via pip, run arrhythpy-cli; otherwise make sure to install the environment as instructed above and run main.py. You are prompted to provide the same parameters as in the GUI, after which the same excel sheet will be saved. In addition, if you have a folder structure where you want to run Arrhythpy over many folders you can use arrhythpy-batch (pip install) or the run_folders.py script.

If you are working with csv files, they can also be uploaded, but have to be a single column containing the values of the transient. If the file however is too long and contains too many beats (max. 25) you have to split the csv into multiple smaller ones, because Arrhythpy cannot handle such large files. For this, use arrhythpy-split (pip install) or the split_csv.py script, which splits a single csv into multiple csvs into its own folder. The created folder can then be used as path in the Arrhythpy GUI. You can either download the CSVSplitter in the release folder or compile it yourself similar to how you compile Arrhythpy. First perform steps 1.-3. as described in Alternative Installation above and replace the last command by:

pyinstaller -n CSVSplitter --onefile --windowed src/arrhythpy/csv_splitter.py