DOCSEARCHbyAlgolia
Submit Docs

BiaPy: Bioimage Analysis Pipelines in Python

repository·master·Indexed 42 days ago

https://github.com/biapyx/biapy

An open-source platform for deep learning in bioimage analysis, providing a Python library and a GUI for 2D and 3D tasks. Supported workflows include semantic and instance segmentation, object detection, image denoising, single image super-resolution, self-supervised learning, image classification, and image-to-image translation. Version 3.7.1 supports distributed execution via torch.distributed.run and includes specialized tools for instance-segmentation representations like CellPose, StarDist, and HoVer-Net.

Tokens
17.3K
Snippets
39
Records
69
Agent score
51%

What's inside BiaPy

  1. Overview of BiaPy for bioimage analysis

    master

    BiaPy is an open-source library and application designed to streamline deep-learning workflows for bioimage analysis. It supports a wide range of 2D and 3D tasks, making it accessible to both computer scientists and users with limited programming experience.

    Supported workflows include:

    • Semantic segmentation
    • Instance segmentation
    • Object detection
    • Image denoising
    • Single image super-resolution
    • Self-supervised learning
    • Image classification
    • Image to image translation

  2. Scientific use cases and tutorials for BiaPy

    master

    BiaPy is used in various scientific research contexts for bioimage analysis, including instance segmentation, wound segmentation, and domain adaptation. The following research areas have specific tutorials or documentation available:

    • MitoEM Challenge (3D Mitochondria Instance Segmentation): Used for the MitoEM challenge baseline (U2D-BC). Tutorial
    • CartoCell (3D Epithelial Cyst Analysis): A high-content pipeline for 3D image analysis to unveil cell morphology patterns. Tutorial
    • Stable Neural Network Architectures: Comparison of U-Net variations for mitochondria segmentation. Tutorial
    • Wound Healing Modeling: Used for creating wound segmentation masks in Drosophila embryo studies. Documentation
    • EM Domain Adaptation: Implementation of Attention U-Net for mitochondria segmentation across different datasets. Documentation
    • Dark Matter Halo Characterization: Used in the creation of watershed approaches for structure formation. Paper

  4. Reproduce sanity-check experiments from the *Representation matters* paper

    master

    This guide allows you to reproduce the experiments used to verify that BiaPy's instance-segmentation representations (e.g., CellPose, StarDist, HoVer-Net) behave identically to their original implementations. These experiments use the DSB2018 dataset (2D nuclei).

    Available Sanity Checks

    Sanity checkConfiguration fileRepresentation (PROBLEM.INSTANCE_SEG.DATA_CHANNELS)
    cellposesanity_cellpose.yaml['F', 'Gh', 'Gv'] (foreground + CellPose flows)
    omniposesanity_omnipose.yaml['Db', 'Gh', 'Gv'] (Omnipose distance + flows)
    stardistsanity_stardist.yaml['Db', 'R'] (object probability + star-convex distances)
    embedsegsanity_embedseg.yaml['E_offset', 'E_sigma', 'E_seediness'] (EmbedSeg)
    hovernetsanity_hovernet.yaml['F', 'H', 'V'] (HoVer-Net horizontal/vertical maps)

    Prerequisites

    1. BiaPy Repository: A clone of the BiaPy repository is required as the script run_sanity_experiments.py locates main.py automatically.
    2. Environment: The BiaPy environment must be installed and activated.
    3. Hardware: A GPU is strongly recommended. You can fall back to CPU using --gpu "", but training is not practical on CPU.
    4. Data: Download the DSB2018 dataset and checkpoints from Zenodo (10.5281/zenodo.21649394).

    Data Layout Requirements

    DSB2018 Dataset Structure:

    dsb2018/
├── train/
│   ├── images/     # raw images
│   └── masks/      # instance labels
└── test/
    ├── images/
    └── masks/

    Checkpoints Structure: All checkpoints must be in a single directory (or subdirectories) and filenames must contain the experiment job name (e.g., sanity_cellpose-checkpoint-best.pth).

    checkpoints/
├── sanity_cellpose-checkpoint-best.pth
├── sanity_embedseg-checkpoint-best.pth
├── sanity_hovernet-checkpoint-best.pth
├── sanity_omnipose-checkpoint-best.pth
└── sanity_stardist-checkpoint-best.pth
    conda activate BiaPy_env

# Run only inference for a specific experiment
python run_sanity_experiments.py \
    --experiment cellpose \
    --output_dir /path/to/output \
    --checkpoint_dir /path/to/checkpoints \
    --data_dir /path/to/dsb2018

  5. Use BioImage Model Zoo (BMZ) models with BiaPy

    master

    BiaPy can consume pre-trained models from the BioImage Model Zoo.

    1. Use biapy.models.find_bmz_models() to list available models.
    2. Use biapy.models.check_bmz_model_compatibility(model, workflow_specs) to verify if a model is compatible with the BiaPy detection workflow (requires workflow_type: 'DETECTION', ndim: '3D').
    3. When configuring your training, set the model source to BioImage Model Zoo and provide the model's nickname or ID.
    from biapy.models import find_bmz_models, check_bmz_model_compatibility

# Find models
models = find_bmz_models()

# Check compatibility for 3D detection
workflow_specs = {
    "workflow_type": "DETECTION",
    "ndim": "3D",
    "nclasses": "all",
}

for model in models:
    compat = check_bmz_model_compatibility(model, workflow_specs=workflow_specs)
    if "error" not in compat or not compat["error"]:
        print(f"Compatible model found: {model.get('nickname')}")

  6. Configure 3D Semantic Segmentation via YAML

    master

    BiaPy uses YAML configuration files to define the segmentation pipeline. You can configure the model architecture, data paths, training hyperparameters, and augmentation settings.

    Key configuration sections include:

    • DATA: Paths for TRAIN, TEST, and VAL (validation) sets, including PATCH_SIZE and GT_PATH.
    • TRAIN: EPOCHS, BATCH_SIZE, OPTIMIZER, LR (learning rate), and PATIENCE for early stopping.
    • MODEL: ARCHITECTURE (e.g., resunet, attention_unet, unetr), N_CLASSES, and SOURCE (e.g., biapy, bmz, or torchvision).
    • AUGMENTOR: Settings for data augmentation like GRIDMASK, CUTBLUR, or CUTNOISE.
    • TEST: Settings for evaluation, including AUGMENTATION and FULL_IMG.

  7. Analyze Training Progress via Loss and MSE

    master

    Monitor the training evolution by comparing Training Loss and Validation Loss.

    • Convergence: Both curves should decrease and eventually plateau. If they haven't flattened, increase number_of_epochs.
    • Overfitting: If Training Loss continues to decrease while Validation Loss starts to increase, the model is overfitting. Consider increasing the training dataset size.
    • MSE (Mean Squared Error): Used as a metric to evaluate the model's accuracy by comparing predictions against ground truth.

  8. Interpret 3D Semantic Segmentation training metrics

    master

    During training, monitor the following metrics to evaluate model performance:

    • Training Loss: Discrepancy between model predictions and ground-truth after each epoch.
    • Validation Loss: Error between model estimates and ground-truth on validation images.
    • Jaccard Index (Intersection over Union / IoU): Measures the overlap between the target mask and prediction. A score closer to 1 indicates optimal performance.

    Interpreting Loss Curves:

    • Improving Model: Both training and validation losses are decreasing. If they haven't flattened, consider increasing number_of_epochs.
    • Overfitting: Training loss continues to decrease toward zero, but validation loss begins to increase. This suggests the model is memorizing training patterns rather than generalizing. To fix this, use a larger training dataset.

  9. Prepare data for 3D Semantic Segmentation

    master

    The 3D semantic segmentation pipeline requires a specific directory structure containing training and testing sets for both raw images and their corresponding semantic labels.

    Supported Formats: .tif, .npy, and any 3D image format supported by scikit-image (e.g., .tiff, .h5, .zarr).

    Required Directory Structure: Ensure that images and masks are sorted identically (e.g., by using padded numbers in filenames).

    dataset/
├── train
│   ├── raw
│   │   ├── training-0001.tif
│   │   └── ...
│   └── label
│       ├── training_groundtruth-0001.tif
│       └── ...
└── test
    ├── raw
    │   ├── testing-0001.tif
    │   └── ...
    └── label
        ├── testing_groundtruth-0001.tif
        └── ...

  10. Reconstruct workflow from a .pth checkpoint

    master

    BiaPy .pth checkpoints can embed the entire configuration used during training. If you pass the path to a .pth file as the config argument to the BiaPy constructor, it will automatically extract the configuration, switch it to inference mode (enabling TEST and disabling TRAIN), and rebuild the workflow for prediction.

    Note: .safetensors files do not embed configuration and cannot be used this way. For .safetensors, you must provide the configuration explicitly.

    from biapy import BiaPy

# Rebuild the inference workflow directly from a checkpoint
biapy = BiaPy(config="path/to/model_checkpoint.pth", result_dir="./inference_results")

  11. Interpret training metrics: Loss and IoU

    master

    Monitor training progress using two primary metrics:

    1. Loss (Training vs. Validation):

      • Decreasing both: Model is learning; consider increasing number_of_epochs.
      • Divergent (Training ↓, Validation ↑): Indicates overfitting. The model is memorizing training data. Solution: Use a larger dataset.
      • Convergence: When both curves flatten, training is complete.

    2. Intersection over Union (IoU) / Jaccard Index:

      • Measures the overlap between predicted masks and ground truth.
      • Score of 1.0 denotes optimal performance.

  12. Visualize detection associations

    master

    BiaPy provides visual feedback on how predictions relate to ground truth. In the visualization output, associations are color-coded:

    • Green: True Positives (TP)
    • Red: False Negatives (FN)
    • Blue: False Positives (FP)

    Results can be viewed as interactive 2D stacks (scrolling through Z-slices) in notebooks or by inspecting the point_associations directory in the output folder.