Skip to main content

micronuclAI

PyPI PyPI - Python Version PyPI - License PyPI - Downloads

Automated assessment of Chromosomal Instability through quantification of micronuclei (MN) and Nuclear Buds (NBUDs).

screenshot

micronuclAI is an automated pipeline for the reliable quantification of micronuclei of varying size, morphology and location from nuclei-stained images. The pipeline can be divided into 3 steps: 1) segmentation, 2) nuclei isolation, and 3) quantification. In brief, single-cell crops are extracted from high-resolution microscopy images with the help of segmentation masks, which are then used to train a convolutional neural network (CNN) to output the number of MN associated with each cell.

Getting Started

Stream-lit App

A webapp implementation of micronuclAI is available through streamlit under:

GitHub:
https://github.com/SchapiroLabor/micronuclAI_streamlit

Streamlit:
https://micronuclai.streamlit.app

screenshot

Inference of micronuclei can be achieved in small to medium-sized example images that can be uploaded to the streamlit app. Image data is processed within a virtual machine (VM) on Heicloud, a local Cloud infrastructure provided by University Computing Center Heidelberg, and images are immediately deleted after micronuclei inference. Once micronuclei are inferred, results predictions as well as several plots describing the results are generated and presented to the user within the streamlit app, which can also be downloaded as CSV files.

Installation

We recommend installing micronuclAI in a clean environment with Python 3.10, 3.11, or 3.12.
micronuclAI uses PyTorch as the main deep learning framework, check the official website for the specific installation instructions for your system.

Install micronuclAI from PyPI.

pip install micronuclai

Usage

Two input files are required for micronuclAI

  1. Nuclei-stained Image
  2. Associated Mask

You can use micronuclAI to predict micronuclei in an image using the following command:

micronuclai-predict.py -i <path/to/image> -m <path/to/mask> -mod <path/to/model> -o <path/to/output/folder>

A test dataset has been provided in the test_data folder with a mask and its corresponding image file.

python src/model/micronuclai_predict.py -i ./test/test_image.tiff -m ./test/test_mask.tiff -mod ./models/micronuclai.pt -o ./test/output

Parameters and Arguments

Parameter Short Form Required Default Type Description
--image -i Yes N/A String Pathway to image.
--mask -m Yes N/A String Pathway to mask.
--model -mod Yes N/A String Pathway to prediction model.
--out -o Yes N/A String Path to the output data folder.
--size -s No (256, 256) List of int Size of images for training.
--resizing_factor -rf No 0.6 Float Resizing factor for images.
--expansion -e No 25 Int Expansion factor for images.
--device -d No "cpu" String Device to be used for training.
--batch_size -bs No 32 Int Batch size for training.

Citation

https://doi.org/10.1038/s42003-025-07796-4

@article{IbarraArellano2025,
  title = {micronuclAI enables automated quantification of micronuclei for assessment of chromosomal instability},
  volume = {8},
  ISSN = {2399-3642},
  url = {http://dx.doi.org/10.1038/s42003-025-07796-4},
  DOI = {10.1038/s42003-025-07796-4},
  number = {1},
  journal = {Communications Biology},
  publisher = {Springer Science and Business Media LLC},
  author = {Ibarra-Arellano,  Miguel A. and Caprio,  Lindsay A. and Hada,  Aroj and Stotzem,  Niklas and Cai,  Luke L. and Shah,  Shivem B. and Walsh,  Zachary H. and Melms,  Johannes C. and W\"{u}nneman,  Florian and Bestak,  Kresimir and Mansaray,  Ibrahim and Izar,  Benjamin and Schapiro,  Denis},
  year = {2025},
  month = mar 
}

License

micronuclAI offers a dual licensing mode the GNU Affero General Public License v3.0 - see LICENSE and ESSENTIAL_LICENSE_CONDITIONS.txt

Metadata

Release files for micronuclai 0.1.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for micronuclai 0.1.3
File Size Uploaded Provenance Actions
micronuclai-0.1.3.tar.gz 509.5 kB Without provenance Details for micronuclai-0.1.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for micronuclai 0.1.3
File Interpreter ABI Platform Actions
micronuclai-0.1.3-py3-none-any.whl Python 3 none any Details for micronuclai-0.1.3-py3-none-any.whl

Total release size: 548.5 kB

Release files / micronuclai-0.1.3.tar.gz

Download URL micronuclai-0.1.3.tar.gz
Size 509.5 kB
Tags Source
SHA-256 checksum
How to use checksums
92ad9bfaf49d4917056437b991ca09ad60ccbcf5087eea3b297262daece87ff1
BLAKE2b-256 checksum
How to use checksums
e97d5d5b575d247168bc291b0158eb7db0776417b3706efdc0b4408711bee991
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.9.21

Release files / micronuclai-0.1.3-py3-none-any.whl

Download URL micronuclai-0.1.3-py3-none-any.whl
Size 39.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
835693981511805ffbf645f7dbf24ffacef161b2ac25d89bc12d55f7c0a0196d
BLAKE2b-256 checksum
How to use checksums
b0ab8af666d612fa2e80c0cb737a5c27038ac3edca7abeaeea23ce16f587583e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.1.0 CPython/3.9.21

Security for micronuclai 0.1.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page