sarc-asm 1.0.0b1

A Python package for comprehensive analysis of sarcomere structure and function in cardiomyocytes

Overview

SarcAsM (Sarcomere Analysis Multitool) is an AI-powered Python package for cardiomyocyte sarcomere analysis. It enables precise multilevel structural and functional assessment of sarcomeres in microscopy images and movies, making it suitable for drug screening, disease phenotyping, and biomechanical studies.

For details, check out our preprint:

Daniel Haertter, Lara Hauke, Til Driehorst, Kengo Nishi, Jaden Long, Malte Tiburcy, Branimir Berecic, et al. 2025. “SarcAsM: AI-Based Multiscale Analysis of Sarcomere Organization and Contractility in Cardiomyocytes.” bioRxiv. https://doi.org/10.1101/2025.04.29.650605.

➡️ Documentation: https://sarcasm.readthedocs.io/

💾 Download App (Windows/MacOS): https://github.com/danihae/SarcAsM/releases

⚙️ Python Package: https://pypi.org/project/sarc-asm

Table of Contents

• Features
• Installation
• Usage
• Documentation
• Contributing
• Support
• Citation
• License

Features

• Robust AI-based sarcomere feature detection in microscopy images
• Comprehensive multilevel analysis of sarcomere structure
  • Z-bands morphometrics and lateral alignment
  • Sarcomere lengths and orientations (sarcomere 'vectors')
  • Myofibril lengths and shape
  • Cell-level myofibril domains
• High-precision tracking of individual and average sarcomere motion with ~20 nm accuracy
• Functional analysis of sarcomere contraction dynamics
• App with interactive Graphical User Interface (GUI)
• Comprehensive Python API for integration into custom workflows
• Batch processing capabilities for high-throughput analysis

Summary of SarcAsM workflow and analyzed features

Installation of Python package

Option 1: Installation via PyPI (Recommended)

The easiest way to install SarcAsM is via pip:

pip install sarc-asm

Option 2: Installation from GitHub

For the latest development version:

pip install git+https://github.com/danihae/sarcasm.git

Setting up a dedicated environment (Recommended)

We strongly recommend creating a dedicated conda environment to avoid dependency conflicts:

conda create -y -n sarcasm-env python=3.12
conda activate sarcasm-env
pip install sarc-asm

Note: The full installation usually takes less than 5 minutes, depending on your internet connection. For computers equipped with an NVIDIA GPU, ensure the installed PyTorch and CUDA toolkit versions are compatible. See PyTorch installation instructions for details.

Usage

Test data for getting started can be found here.

Python Package

After installation, SarcAsM can be imported and used in your Python scripts or Jupyter notebooks:

# Example workflow for structural analysis
from sarcasm import SarcAsM, Export

# Load an image or movie
sarc = SarcAsM("path/to/your/image_or_movie.tif")

# Detect sarcomeres
sarc.detect_sarcomeres()

# Analyze sarcomere length and orientations (sarcomere 'vectors')
sarc.analyze_sarcomere_vectors()

# Analyze Z-bands
sarc.analyze_z_bands()

# Analyze myofibrils
sarc.analyze_myofibrils()

# Analyze domains
sarc.analyze_sarcomere_domains()

# Export data to xlsx file (summary statistics per frame; the full results live in the
# sibling <name>.ome.zarr store next to the tif)
Export.export_structure_data('/path/to/xlsx/file.xlsx', sarc)

Tip: Control logging verbosity with the log_level parameter:

# Verbose output for troubleshooting
sarc = SarcAsM("file.tif", log_level='DEBUG')

# Quiet mode - only warnings and errors  
sarc = SarcAsM("file.tif", log_level='WARNING')

Check out quickstart_demo.ipynb in the repository root or our documentation for a practical introduction to SarcAsM's functionalities.

Upgrading from 0.5? SarcAsM 1.0 is a breaking release: Structure became SarcAsM, the manual line-of-interest motion workflow was replaced by 2D sarcomere tracking, results now live in a single .ome.zarr store, and result keys changed. Analyses from 0.5 have to be recomputed; see the changelog and the key migration table.

App

SarcAsM includes an app with intuitive Graphical User Interface (GUI) built with Napari for interactive analysis and visualization.

How to Run the App:

There are two main ways to run the SarcAsM App:

1. Standalone Applications (Recommended for ease of use):

   • Pre-built applications for Windows (.exe) and macOS (.app) are available for download directly from the GitHub Releases page.
   • This method does not require a separate Python installation.
   • Note: As mentioned in the release notes, these are early versions, and the initial startup might take some time. The Windows version currently uses CPU only.

2. From your Python Environment (Recommended for developers or API users):

   • If you have installed SarcAsM into a Python environment (e.g., via pip or conda from the source), you can launch the GUI using this command:

   # After activating your environment (e.g., conda activate sarcasm-env)
   python -m sarcasm_app
   

   • Alternatively, you can run ./sarcasm_app/__main__.py directly from the SarcAsM root directory if the necessary dependencies are in your PYTHONPATH.

Documentation

Detailed documentation, including tutorials, API reference, and usage examples, can be found at:

https://sarcasm.readthedocs.io/

Additional resources:

• Example notebooks located in the docs/notebooks directory within the repository.
• Sample data for testing purposes is available at https://doi.org/10.5281/zenodo.8232837.

Contributing

We welcome contributions from the community! If you'd like to contribute to SarcAsM:

• Development Guide: See docs/development.md for detailed instructions on setting up your development environment, running tests, code quality standards, and publishing releases.
• Quick Start for Developers:

  git clone https://github.com/danihae/SarcAsM.git
  cd SarcAsM
  
  # Using uv (recommended)
  uv sync --all-groups
  
  # Or using pip 25.1+ with dependency groups
  pip install -e . --group dev
  
  # Run tests
  pytest
  

• Please follow the contribution workflow outlined in the development guide
• Ensure all tests pass and code quality checks are met before submitting pull requests

Support

If you encounter any issues, have questions, or want to suggest improvements:

• Please check the online documentation first.
• If the issue persists, open an issue on our GitHub repository. Provide as much detail as possible, including steps to reproduce the problem, error messages, and your operating system/environment details.

Citation

If you use SarcAsM in your research, please cite our preprint for now (peer-reviewed publication will follow):

Daniel Haertter, Lara Hauke, Til Driehorst, Kengo Nishi, Jaden Long, Malte Tiburcy, Branimir Berecic, et al. 2025. “SarcAsM: AI-Based Multiscale Analysis of Sarcomere Organization and Contractility in Cardiomyocytes.” bioRxiv. https://doi.org/10.1101/2025.04.29.650605.

License

This software is patent pending (Patent Application No. DE 10 2024 112 939.5, Priority Date: 8.5.2024).

Academic and Non-Commercial Use

This software is free for academic and non-commercial use. Users are granted a non-exclusive, non-transferable license to use the software for research, educational, and other non-commercial purposes.

Commercial Use Restrictions

Commercial use of this software is strictly prohibited without obtaining a separate license agreement. This includes but is not limited to:

• Using the software in a commercial product or service
• Using the software to provide services to third parties
• Reselling or redistributing the software

For commercial licensing inquiries, please contact:

MBM ScienceBridge GmbH, Hans-Adolf-Krebs-Weg 1, 37077 Göttingen, Germany, https://sciencebridge.de/en/

All rights not expressly granted are reserved. Unauthorized use may result in legal action.