Bump dependencies and update documentation (#64)

* add reference for mantis

* replace lapsolver with scipy
lapsolver is abandoned and does not work with new python versions

* update dependencies

* update docs

* test on python 3.11

* drop python 3.9 support

* do not update example setup script
it checks out a previous commit

.github/workflows/pr.yml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ["3.9", "3.10"]
+        python-version: ["3.10", "3.11"]
     steps:
       - uses: actions/checkout@v3
       - uses: actions/setup-python@v4

CONTRIBUTING.md

@@ -3,17 +3,17 @@
 ## Development installation
 
 Clone or fork the repository,
-then make an editable installation with optional dependencies:
+then make an editable installation with all the optional dependencies:
 
 ```sh
-# in project root directory (where you can see README.md with `ls`)
-pip install -e ".[dev,metrics]"
+# in project root directory (parent folder of pyproject.toml)
+pip install -e ".[dev,visual,metrics]"
 ```
 
 ## Testing
 
 Run tests with `pytest`:
 
 ```sh
-pytest
+pytest -v
 ```

README.md

@@ -8,39 +8,44 @@ Our pipeline also provides utilities to export the models to ONNX format for use
 We will grow the collection of the models suitable for high-throughput imaging and phenotyping.
 Expect rough edges until we release a PyPI package.
 
-
 ![virtual_staining](docs/figures/phase_to_nuclei_membrane.svg)
 
-This pipeline evolved from the [TensorFlow version of virtual staining pipeline](https://github.com/mehta-lab/microDL), which we reported in [this paper in 2020](https://elifesciences.org/articles/55502). The previous pipeline is now a public archive, and we will be focusing our efforts on viscy.
+This pipeline evolved from the [TensorFlow version of virtual staining pipeline](https://github.com/mehta-lab/microDL), which we reported in [this paper in 2020](https://elifesciences.org/articles/55502). The previous pipeline is now a public archive, and we will be focusing our efforts on VisCy.
 
 ## Installing viscy
 
-1. We highly encourage using new Conda/virtual environment.
-    ([Mamba](https://github.com/mamba-org/mamba) is a faster re-implementation Conda.)
+1. We highly encourage using a new Conda/virtual environment.
+    The example below uses [Mamba](https://github.com/mamba-org/mamba),
+    a faster re-implementation of Conda.
 
     ```sh
     mamba create --name viscy python=3.10
-    # OR
+    # OR specify a custom path since the dependencies are large
     mamba create --prefix /path/to/conda/envs/viscy python=3.10
     ```
 
-
 2. Clone this repository and install with pip:
 
     ```sh
-    git clone https://github.com/mehta-lab/viscy.git
+    git clone https://github.com/mehta-lab/VisCy.git
     # change to project root directory (parent folder of pyproject.toml)
     cd VisCy
     pip install .
     ```
 
     If evaluating virtually stained images for segmentation tasks,
-    additional dependencies need to be installed:
+    install additional dependencies:
 
     ```sh
     pip install ".[metrics]"
     ```
 
+    Visualizing the model architecture requires `visual` dependencies:
+
+    ```sh
+    pip install ".[visual]"
+    ```
+
 3. Verify installation by accessing the CLI help message:
 
     ```sh
@@ -49,9 +54,11 @@ This pipeline evolved from the [TensorFlow version of virtual staining pipeline]
 
 For development installation, see [the contributing guide](CONTRIBUTING.md).
 
-The pipeline is built using the [PyTorch Lightning](https://www.pytorchlightning.ai/index.html) framework and [iohub](https://github.com/czbiohub-sf/iohub) library for reading and writing data in [OME-Zarr](https://www.nature.com/articles/s41592-021-01326-w) format.
+The pipeline is built using the [PyTorch Lightning](https://www.pytorchlightning.ai/index.html) framework.
+The [iohub](https://github.com/czbiohub-sf/iohub) library is used
+for reading and writing data in [OME-Zarr](https://www.nature.com/articles/s41592-021-01326-w) format.
 
-The full functionality is  tested only on Linux `x86_64` with NVIDIA Ampere GPUs (CUDA 12.0).
+The full functionality is only tested on Linux `x86_64` with NVIDIA Ampere GPUs (CUDA 12.3).
 Some features (e.g. mixed precision and distributed training) may not work with other setups,
 see [PyTorch documentation](https://pytorch.org) for details.
 
@@ -111,3 +118,17 @@ flowchart LR
 
 ![2.5D U-Net light](docs/figures/2_5d_unet_light.svg#gh-light-mode-only)
 ![2.5D U-Net dark](docs/figures/2_5d_unet_dark.svg#gh-dark-mode-only)
+
+### Reference
+
+We report the use of the virtual staining pipeline in [this preprint](https://doi.org/10.1101/2023.12.19.572435):
+
+```bibtex
+@misc{ivanov_mantis_2023,
+ title = {Mantis: high-throughput {4D} imaging and analysis of the molecular and physical architecture of cells},
+ url = {https://www.biorxiv.org/content/10.1101/2023.12.19.572435v1},
+ doi = {10.1101/2023.12.19.572435},
+ publisher = {bioRxiv},
+ author = {Ivanov, Ivan E. and Hirata-Miyasaki, Eduardo and Chandler, Talon and Kovilakam, Rasmi Cheloor and Liu, Ziwen and Liu, Chad and Leonetti, Manuel D. and Huang, Bo and Mehta, Shalin B.},
+}
+```

examples/demo_dlmbl/setup.sh

@@ -18,7 +18,7 @@ cd viscy
 git checkout 7c5e4c1d68e70163cf514d22c475da8ea7dc3a88 # Exercise is tested with this commit of viscy
 # Find path to the environment - mamba activate doesn't work from within shell scripts.
 ENV_PATH=$(conda info --envs | grep 04_image_translation | awk '{print $NF}')
-$ENV_PATH/bin/pip install ."[metrics]"
+$ENV_PATH/bin/pip install ".[metrics]"
 
 # Create data directory
 mkdir -p ~/data/04_image_translation

pyproject.toml

@@ -6,12 +6,11 @@ build-backend = "setuptools.build_meta"
 name = "viscy"
 description = "computer vision for image-based phenotyping of single cells"
 readme = "README.md"
-# cannot build on 3.11 due to https://github.com/cheind/py-lapsolver/pull/18
-requires-python = ">=3.9,!=3.11"
+requires-python = ">=3.10"
 license = { file = "LICENSE" }
 authors = [{ name = "CZ Biohub SF", email = "[email protected]" }]
 dependencies = [
-    "iohub==0.1.0.dev4",
+    "iohub==0.1.0rc0",
     "torch>=2.0.0",
     "timm>=0.9.5",
     "tensorboard>=2.13.0",
@@ -20,21 +19,17 @@ dependencies = [
     "jsonargparse[signatures]>=4.20.1",
     "scikit-image",
     "matplotlib",
-    "ipykernel", # used by demo_dlmbl
-    "graphviz", # used by demo_dlmbl
-    "torchview", # used by demo_dlmbl
-    ]
+]
 dynamic = ["version"]
 
 [project.optional-dependencies]
 metrics = [
     "cellpose==2.1.0",
-    "lapsolver==1.1.0",
     "scikit-learn>=1.1.3",
-    "scipy>=1.8.0",
     "torchmetrics[detection]>=1.0.0",
     "ptflops>=0.7",
 ]
+visual = ["ipykernel", "graphviz", "torchview"]
 dev = ["pytest", "pytest-cov", "hypothesis", "profilehooks", "onnxruntime"]
 
 [project.scripts]

viscy/evaluation/evaluation_metrics.py

@@ -5,8 +5,8 @@
 import numpy as np
 import torch
 import torch.nn.functional as F
-from lapsolver import solve_dense
 from monai.metrics.regression import compute_ssim_and_cs
+from scipy.optimize import linear_sum_assignment
 from skimage.measure import label, regionprops
 from torchmetrics.detection import MeanAveragePrecision
 from torchvision.ops import masks_to_boxes
@@ -88,8 +88,8 @@ def POD_metric(target_bin, pred_bin):
 
     distance_threshold = np.mean(lab_targ_major_axis) / 2
 
-    # LAPsolver for minimizing cost matrix of objects
-    rids, cids = solve_dense(cost_matrix)
+    # minimize cost matrix of objects
+    rids, cids = linear_sum_assignment(cost_matrix)
 
     # filter out rid and cid pairs that exceed distance threshold
     matching_targ = []