Merge branch 'main' into isles

.github/doc_env.yaml

@@ -0,0 +1,13 @@
+channels:
+    - pytorch
+    - conda-forge
+name:
+    sam
+dependencies:
+    - cpuonly
+    - pdoc
+    - python-elf
+    - pytorch
+    - torchvision
+    - tqdm
+    - zarr

.github/workflows/build_docs.yaml

@@ -0,0 +1,65 @@
+name: build_documentation
+
+# build the documentation for a new release
+on:
+  release:
+    types: created
+
+# # for debugging
+# on: [push, pull_request]
+
+# security: restrict permissions for CI jobs.
+permissions:
+  contents: read
+
+# NOTE: importing of napari fails with CI and I am not quite sure why
+# I tried to adjust it based on the napari CI tests, but that didn't seem to help
+
+# https://github.com/napari/napari/blob/main/.github/workflows/test_comprehensive.yml
+jobs:
+  # Build the documentation and upload the static HTML files as an artifact.
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup miniconda
+        uses: conda-incubator/setup-miniconda@v2
+        with:
+          activate-environment: sam
+          mamba-version: "*"
+          auto-update-conda: true
+          environment-file: .github/doc_env.yaml
+          python-version: ${{ matrix.python-version }}
+          auto-activate-base: false
+        env:
+          ACTIONS_ALLOW_UNSECURE_COMMANDS: true
+
+      - name: Install package
+        shell: bash -l {0}
+        run: pip install --no-deps -e .
+
+      # We use a custom build script for pdoc itself, ideally you just run `pdoc -o docs/ ...` here.
+      - name: Run pdoc
+        shell: bash -l {0}
+        run: python build_doc.py --out
+
+      - uses: actions/upload-pages-artifact@v1
+        with:
+          path: tmp/
+
+  # Deploy the artifact to GitHub pages.
+  # This is a separate job so that only actions/deploy-pages has the necessary permissions.
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v2

README.md

@@ -1,3 +1,4 @@
+[![DOC](https://shields.mitmproxy.org/badge/docs-pdoc.dev-brightgreen.svg)](https://constantinpape.github.io/torch-em/torch_em.html)
 [![Build Status](https://github.com/constantinpape/torch-em/workflows/test/badge.svg)](https://github.com/constantinpape/torch-em/actions)
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.5108853.svg)](https://doi.org/10.5281/zenodo.5108853)
 [![Anaconda-Server Badge](https://anaconda.org/conda-forge/torch_em/badges/version.svg)](https://anaconda.org/conda-forge/torch_em)
@@ -103,7 +104,7 @@ If you want to use the GPU version, make sure to set the correct CUDA version fo
 
 You can set up a conda environment using one of these files like this:
 ```bash
-mamba create -f <ENV>.yaml -n <ENV_NAME>
+mamba env create -f <ENV>.yaml -n <ENV_NAME>
 mamba activate <ENV_NAME>
 pip install -e .
 ```

build_doc.py

@@ -0,0 +1,14 @@
+import argparse
+from subprocess import run
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--out", "-o", action="store_true")
+args = parser.parse_args()
+
+cmd = ["pdoc", "--docformat", "google"]
+
+if args.out:
+    cmd.extend(["--out", "tmp/"])
+cmd.append("torch_em")
+
+run(cmd)

doc/datasets_and_dataloaders.md

@@ -1,54 +1,32 @@
 # Datasets in `torch-em`
 
-Available open-source datasets in `torch-em` located at `torch_em/data/datasets/` (see `scripts/datasets` for a quick guide on how to use the dataloaders out-of-the-box):
+We provide PyTorch Datasets / DataLoaders for many different biomedical datasets, mostly for segmentation tasks.
+They are implemented in `torch_em.data.datasets`. See `scripts/datasets` for examples on how to visualize images from these datasets.
 
-### Microscopy
 
-- ASEM (`asem.py`): Segmentation of organelles in FIB-SEM cells.
-- AxonDeepSeg (`axondeepseg.py`): Segmentation of myelinated axons in electron microscopy.
-- MitoLab* (`cem.py`):
-    - CEM MitoLab: Segmentation of mitochondria in electron microscopy.
-    - CEM Mito Benchmark: Segmentation of mitochondria in 7 benchmark electron microscopy datasets.
-- Covid IF (`covidif.py`): Segmentation of cells and nuclei in immunofluoroscence.
-- CREMI (`cremi.py`): Segmentation of neurons in electron microscopy.
-- Cell Tracking Challenge (`ctc.py`): Segmentation data for cell tracking challenge (consists of 10 datasets).
-- DeepBacs (`deepbacs.py`): Segmentation of bacteria in light microscopy.
-- DSB (`dsb.py`): Segmentation of nuclei in light microscopy.
-- DynamicNuclearNet* (`dynamicnuclearnet.py`): Segmentation of nuclei in fluorescence microscopy.
-- HPA (`hpa.py`): Segmentation of cells in light microscopy.
-- ISBI (`isbi2012.py`): Segmentation of neurons in electron microscopy.
-- Kasthuri (`kasthuri.py`): Segmentation of mitochondria in electron microscopy.
-- LIVECell (`livecell.py`): Segmentation of cells in phase-contrast microscopy.
-- Lucchi (`lucchi.py`): Segmentation of mitochondria in electron microscopy.
-- MitoEM (`mitoem.py`): Segmentation of mitochondria in electron microscopy.
-- Mouse Embryo (`mouse_embryo.py`): Segmentation of nuclei in confocal microscopy.
-- NeurIPS CellSeg (`neurips_cell_seg.py`): Segmentation of cells in multi-modality light microscopy datasets.
-- NucMM (`nuc_mm.py`): Segmentation of nuclei in electron microscopy and micro-CT.
-- PlantSeg (`plantseg.py`): Segmentation of cells in confocal and light-sheet microscopy.
-- Platynereis (`platynereis.py`): Segmentation of nuclei in electron microscopy.
-- PNAS* (`pnas_arabidopsis.py`): TODO
-- SNEMI (`snemi.py`): Segmentation of neurons in electron microscopy.
-- Sponge EM (`sponge_em.py`): Segmentation of sponge cells and organelles in electron microscopy.
-- TissueNet* (`tissuenet.py`): Segmentation of cellls in tissue imaged with light microscopy.
-- UroCell (`uro_cell.py`): Segmentation of mitochondria and other organelles in electron microscopy.
-- VNC (`vnc.py`): Segmentation of mitochondria in electron microscopy
+## Available Datasets
 
-### Histopathology
+All datasets in `torch_em.data.datasets` are implemented according to the following logic:
+- The function `get_..._data` downloads the respective datasets. Note that some datasets cannot be downloaded automatically. In these cases the function will raise an error with a message that explains how to download the data.
+- The function `get_..._dataset` returns the PyTorch Dataset for the corresponding dataset.
+- The function `get_..._dataloader` returns the PyTorch DataLoader for the corresponding dataset.
 
-- BCSS (`bcss.py`): Segmentation of breast cancer tissue in histopathology.
-- Lizard* (`lizard.py`): Segmentation of nuclei in histopathology.
-- MoNuSaC (`monusac.py`): Segmentation of multi-organ nuclei in histopathology.
-- MoNuSeg (`monuseg.py`): Segmentation of multi-organ nuclei in histopathology.
-- PanNuke (`pannuke.py`): Segmentation of nuclei in histopathology.
+### Light Microscopy
+
+We provide several light microscopy datasets. See `torch_em.data.datasets.light_microscopy` for an overview.
+
+### Electron Microscopy
 
+We provide several electron microscopy datasets. See `torch_em.data.datasets.electron_microscopy` for an overview.
+
+### Histopathology 
+
+`torch_em.data.datasets.histopathology`
 
 ### Medical Imaging
 
-- AutoPET* (`medical/autopet.py`): Segmentation of lesions in whole-body FDG-PET/CT.
-- BTCV* (`medical/btcv.py`): Segmentation of multiple organs in CT.
+`torch_em.data.datasets.medical`
 
-### NOTE:
-- \* - These datasets cannot be used out of the box (mostly because of missing automatic downloading). Please take a look at the scripts and the dataset object for details.
 
 ## How to create your own dataloader?
 
@@ -157,3 +135,51 @@ dataset = RawImageCollectionDataset(
     # there are other optional parameters, see `torch_em.data.raw_image_collection_dataset.py` for details.
 )
 ```
+
+
+<!-- I would rather auto-generate this in a proper pdoc documentation.
+- ASEM (`asem.py`): Segmentation of organelles in FIB-SEM cells.
+- AxonDeepSeg (`axondeepseg.py`): Segmentation of myelinated axons in electron microscopy.
+- MitoLab* (`cem.py`):
+    - CEM MitoLab: Segmentation of mitochondria in electron microscopy.
+    - CEM Mito Benchmark: Segmentation of mitochondria in 7 benchmark electron microscopy datasets.
+- Covid IF (`covidif.py`): Segmentation of cells and nuclei in immunofluoroscence.
+- CREMI (`cremi.py`): Segmentation of neurons in electron microscopy.
+- Cell Tracking Challenge (`ctc.py`): Segmentation data for cell tracking challenge (consists of 10 datasets).
+- DeepBacs (`deepbacs.py`): Segmentation of bacteria in light microscopy.
+- DSB (`dsb.py`): Segmentation of nuclei in light microscopy.
+- DynamicNuclearNet* (`dynamicnuclearnet.py`): Segmentation of nuclei in fluorescence microscopy.
+- HPA (`hpa.py`): Segmentation of cells in light microscopy.
+- ISBI (`isbi2012.py`): Segmentation of neurons in electron microscopy.
+- Kasthuri (`kasthuri.py`): Segmentation of mitochondria in electron microscopy.
+- LIVECell (`livecell.py`): Segmentation of cells in phase-contrast microscopy.
+- Lucchi (`lucchi.py`): Segmentation of mitochondria in electron microscopy.
+- MitoEM (`mitoem.py`): Segmentation of mitochondria in electron microscopy.
+- Mouse Embryo (`mouse_embryo.py`): Segmentation of nuclei in confocal microscopy.
+- NeurIPS CellSeg (`neurips_cell_seg.py`): Segmentation of cells in multi-modality light microscopy datasets.
+- NucMM (`nuc_mm.py`): Segmentation of nuclei in electron microscopy and micro-CT.
+- PlantSeg (`plantseg.py`): Segmentation of cells in confocal and light-sheet microscopy.
+- Platynereis (`platynereis.py`): Segmentation of nuclei in electron microscopy.
+- PNAS* (`pnas_arabidopsis.py`): TODO
+- SNEMI (`snemi.py`): Segmentation of neurons in electron microscopy.
+- Sponge EM (`sponge_em.py`): Segmentation of sponge cells and organelles in electron microscopy.
+- TissueNet* (`tissuenet.py`): Segmentation of cellls in tissue imaged with light microscopy.
+- UroCell (`uro_cell.py`): Segmentation of mitochondria and other organelles in electron microscopy.
+- VNC (`vnc.py`): Segmentation of mitochondria in electron microscopy
+
+### Histopathology
+
+- BCSS (`bcss.py`): Segmentation of breast cancer tissue in histopathology.
+- Lizard* (`lizard.py`): Segmentation of nuclei in histopathology.
+- MoNuSaC (`monusac.py`): Segmentation of multi-organ nuclei in histopathology.
+- MoNuSeg (`monuseg.py`): Segmentation of multi-organ nuclei in histopathology.
+- PanNuke (`pannuke.py`): Segmentation of nuclei in histopathology.
+
+### Medical Imaging
+
+- AutoPET* (`medical/autopet.py`): Segmentation of lesions in whole-body FDG-PET/CT.
+- BTCV* (`medical/btcv.py`): Segmentation of multiple organs in CT.
+
+### NOTE:
+- \* - These datasets cannot be used out of the box (mostly because of missing automatic downloading). Please take a look at the scripts and the dataset object for details.
+-->

doc/start_page.md

@@ -0,0 +1,3 @@
+[torch_em](https://github.com/constantinpape/torch-em) is a library for deep learning in microscopy images. It is built on top of [PyTorch](https://pytorch.org/).
+
+We are working on the documentation and will extend and improve it soon!

experiments/unet-segmentation/dsb/train_boundaries.py

@@ -9,11 +9,16 @@ def train_boundaries(args):
 
     patch_shape = (1, 256, 256)
     train_loader = get_dsb_loader(
-        args.input, patch_shape, split="train",
+        args.input, patch_shape=patch_shape, split="train",
         download=True, boundaries=True, batch_size=args.batch_size
     )
+
+    # Uncomment this for checking the loader.
+    # from torch_em.util.debug import check_loader
+    # check_loader(train_loader, 4)
+
     val_loader = get_dsb_loader(
-        args.input, patch_shape, split="test",
+        args.input, patch_shape=patch_shape, split="test",
         boundaries=True, batch_size=args.batch_size
     )
     loss = torch_em.loss.DiceLoss()

notebooks/README.md

@@ -1,3 +1,3 @@
 # Jupyter Notebooks for `torch-em`-based Implementations and Tutorials
 
-1. `tutorial_create_dataloaders.ipynb`: This notebook gives you a head-start on how to create your custom dataloaders for segmentation for most data structures. It's recommended to checkout `torch_em.data.datasets.README.md` for the first outlook before getting started.
+1. `tutorial_create_dataloaders.ipynb`: This notebook gives you a head-start on how to create your custom dataloaders for segmentation for most data structures. It's recommended to checkout https://github.com/constantinpape/torch-em/blob/main/doc/datasets_and_dataloaders.md for the first outlook before getting started.

scripts/datasets/check_busi.py

@@ -0,0 +1,22 @@
+from torch_em.util.debug import check_loader
+from torch_em.data.datasets.medical import get_busi_loader
+
+
+ROOT = "/media/anwai/ANWAI/data/busi"
+
+
+def check_busi():
+    loader = get_busi_loader(
+        path=ROOT,
+        patch_shape=(512, 512),
+        batch_size=2,
+        category=None,
+        resize_inputs=False,
+        download=True,
+    )
+
+    check_loader(loader, 8)
+
+
+if __name__ == "__main__":
+    check_busi()

scripts/datasets/check_drive.py

@@ -0,0 +1,21 @@
+from torch_em.util.debug import check_loader
+from torch_em.data.datasets.medical import get_drive_loader
+
+
+ROOT = "/media/anwai/ANWAI/data/drive"
+
+
+def check_drive():
+    loader = get_drive_loader(
+        path=ROOT,
+        patch_shape=(256, 256),
+        batch_size=2,
+        resize_inputs=True,
+        download=True,
+    )
+
+    check_loader(loader, 8)
+
+
+if __name__ == "__main__":
+    check_drive()