BodenmillerGroup · Milad4849 · Feb 24, 2023 · Feb 24, 2023 · Feb 24, 2023 · Apr 10, 2023
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -1,7 +1,7 @@
 exclude: ^\.vscode/.*
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v4.5.0
     hooks:
       - id: check-added-large-files
       - id: check-case-conflict
@@ -16,25 +16,25 @@ repos:
       - id: requirements-txt-fixer
       - id: trailing-whitespace
   - repo: https://github.com/PyCQA/isort
-    rev: "5.12.0"
+    rev: "5.13.2"
     hooks:
       - id: isort
   - repo: https://github.com/PyCQA/autoflake
-    rev: v2.0.1
+    rev: v2.2.1
     hooks:
       - id: autoflake
         args: [--in-place, --remove-all-unused-imports]
   - repo: https://github.com/psf/black
-    rev: '23.1.0'
+    rev: '23.12.1'
     hooks:
       - id: black
   - repo: https://github.com/PyCQA/flake8
-    rev: "6.0.0"
+    rev: "7.0.0"
     hooks:
       - id: flake8
         additional_dependencies: [flake8-typing-imports]
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.0.0
+    rev: v1.8.0
     hooks:
       - id: mypy
         additional_dependencies: [types-requests, types-PyYAML]

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -5,6 +5,27 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+
+## [0.17.0]
+
+### Added
+  - Cellpose2.0 segmentation and training
+  - Cellpose2.0 as an app
+  - Added the parameter `--xti` to ` steinbockpreprocess imc images` which provides the option to generate individual txt files for ROIs.
-  - Added the parameter `--xti` to ` steinbockpreprocess imc images` which provides the option to generate individual txt files for ROIs.
+  - Added the parameter `--xti` to ` steinbock preprocess imc images` which provides the option to generate individual txt files for ROIs.
-  - Added the parameter `--xti` to ` steinbockpreprocess imc images` which provides the option to generate individual txt files for ROIs.
+  - Added the parameter `--xti` to ` steinbock preprocess imc images` which provides the option to generate individual txt files for ROIs.
+
+### Changed
+  - Cellpose default parameters
+  - Segmentation, Utils and docker container Documentation
+  - List of contributors
+
+
+### Fixed
+- No neighborhood Data in h5ad-files [#210](https://github.com/BodenmillerGroup/steinbock/issues/210)
+- Unifying how panel column datatypes are handled [#174](https://github.com/BodenmillerGroup/steinbock/discussions/174)
+- Tissuenet model support and documentation [#208](https://github.com/BodenmillerGroup/steinbock/issues/208)
+- Maximum amount of segmented cells bounded from segmentation output file format (16-bit unsigned integer TIFF images) [#207](https://github.com/BodenmillerGroup/steinbock/issues/207)
+
+
 ## [0.16.2] - 2023-08-15
 
 ### Changed

diff --git a/CONTRIBUTORS.md b/CONTRIBUTORS.md
@@ -4,6 +4,11 @@
 
 [[email protected]](mailto:[email protected])
 
-  - Logo
-  - Documentation
-  - Testing, feedback & discussion
+- Logo
+- Documentation
+- Testing, feedback & discussion
+
+
+## Milad Adibi
+
+[[email protected]](mailto:[email protected])
diff --git a/docs/cli/segmentation.md b/docs/cli/segmentation.md
@@ -7,6 +7,12 @@ Various segmentation approaches are supported, each of which is described in the
 !!! note "Pixel classification-based image segmentation vs end-to-end approaches"
     While [pixel classification](classification.md)-based image segmentation using CellProfiler uses probability images to segment objects, end-to-end workflows such as DeepCell/Mesmer and Cellpose directly operate on images without the need for a preceding pixel classification step.
 
+
+!!! note "Large masks containing more than 65535 objects"
+  Please refer to the [installation page](../install-docker.md##Using-the-docker-container-with-large-images-containing-more-than-65535-objects) when analizing large masks with more than 65535 objects.
+
+
+
 ## CellProfiler
 
 [CellProfiler](https://cellprofiler.org) is an open-source software for measuring and analyzing cell images. Here, CellProfiler is used for object detection and region growth-based object segmentation.
@@ -87,7 +93,7 @@ This will create grayscale cell/nuclear masks of the same x and y dimensions as
     Specify `--minmax` to enable min-max normalization and `--zscore` to enable z-score normalization.
 
 !!! note "Preprocessing/postprocessing parameters"
-    Application-dependent preprocessing/postprocessing parameters can be specified in YAML files using the `--preprocess`/`--postprocess` options. For the Mesmer application, this can e.g. be used to control thresholding, histogram normalization and watershed segmentation. Please refer to the DeepCell online documentation for available parameters. For example, one could specify `--preprocess preprocessing.yml`, where `preprocessing.yml` is a file in the steinbock data/working directory containing:
+    Application-dependent preprocessing/postprocessing parameters can be specified in YAML files using the `--preprocess`/`--postprocess` options. For the Mesmer application, this can e.g. be used to control thresholding, histogram normalization and watershed segmentation. Please refer to the DeepCell online documentation for available parameters. For example, one could specify `--preprocess preprocessing.yml`, where `preprocessing.yml` is a file in the *steinbock* data/working directory containing:
 
         threshold: true
         percentile: 99.9
@@ -99,28 +105,46 @@ This will create grayscale cell/nuclear masks of the same x and y dimensions as
 !!! danger "Experimental feature"
     This is an experimental feature and is only available in the `-cellpose` flavors of the *steinbock* Docker container.
 
-    Segmentation using cellpose likely requires fine-tuning of parameters, e.g. using steinbock command-line interface options.
+    Segmentation using cellpose likely requires fine-tuning of parameters, e.g. using steinbock command-line interface options. The steinbock default parameters for the cellpose models (cell probability threshhold, flow threshhold etc) are not the same as the default values of *cellpose* itself. The steinbock default values are the result of manual optimization of cellpose parameters for segmentation of IMC images in the Bodenmiller lab.
 
 [Cellpose](https://www.cellpose.org) is a generalist algorithm for cellular segmentation.
 
 !!! note "End-to-end cell segmentation"
     This approach operates directly on image intensities and does not require a preceding pixel classification step.
 
-To segment cells using the default `cyto2` model:
+To segment cells using the default `tissuenet` model:
 
     steinbock segment cellpose --minmax
 
 To segment nuclei using the `nuclei` model:
 
     steinbock segment cellpose --minmax --model nuclei
 
+Models introduced in [cellpose 2.0](https://www.nature.com/articles/s41592-022-01663-4) can also be chosen, bringing the total number of available models to 14, these are 'nuclei',
+            'cyto', 'cyto2', 'tissuenet', 'livecell', 'CP', 'CPx', 'TN1', 'TN2', 'TN3', 'LC1', 'LC2', 'LC3' and 'LC4'. The user can utilize any of these mdoels by specifying them using the `--model` argument as demonstrated above. The default is set to `tissuenet` model. The user can choose from these by specifying them via the `--model` argument, note that `tissuenet` is also the default model for training a cellpose model (See training a cellpose model below). Furthermore user-trained models (see `Training a cellpose model` below) can be used via the `pretrained-model` argument. When both the `--model` and `pretrained_mdodel` parameters are provided, the model specified by `--model`is used. Therefoore when the user provides the `pretrained-model` argument, *steinbock* automatically sets `--model` argument to `None`.
+
 !!! note "Cellpose image data"
     Cellpose expects two-channel images as input, where the first channel must be a nuclear channel (e.g. DAPI) and the second channel must be a cytoplasmic channel (e.g. E-Cadherin). The nuclear channel is optional and only the cytoplasmic channel ("channel to segment") is required. Note that - compared to the original cellpose implementation - the channel order is reversed for compatibility with DeepCell/Mesmer.
 
     If a `cellpose` column is present in the *steinbock* panel file, channels are sorted and grouped according to values in that column to generate the required input for DeepCell: For each image, each group of channels is aggregated by computing the mean along the channel axis (use the `--aggr` option to specify a different aggregation strategy). The resulting images consist of one channel per group; channels without a group label are ignored.
 
     If no `cellpose` column is present, images are expected to be in the correct format already.
 
+### Training a cellpose model
+Training a cellpose model is performed using two commands
+
+      steinbock segment train prepare
+      steinbock segment train run
+
+By default the first command generates crops of images in `img` and stores them in `cellpose_crops` folder. These crops consist of a nuclear and a Cytoplasmic channels as described above. By default crops are then segmented using the `tissuenet` pre-trained model and the resulting masks are placed in the folder `cellpose_labels`. Any model from the  model zoo can be specified using the`--model_type` argument. User trained models can be specified by providing the full path to the model using the `pretrained-model` option (when `pretrained-model` is provided, the `--model_type` argument is set to `None`, see above). The user can optionally specify a list of files for cropping and training.  After running the first command the user should open and inspect the generated masks and correct them if necessary. This can be done by starting the `cellpose` gui via *steinbock*: `steinbock apps cellpose` (See `Apps`in this document. For details on how to use cellpose to correct gui segmentations, see its relevant [documentation](https://cellpose.readthedocs.io/en/latest/gui.html).
+
+The second command runs the cellpose training module. Unless specified via the `--train_data` and `--train_labels` options, the command looks in `cellpose_crops` and `cellpose_labels` for images and masks that are used as ground truth. The resulting model is by default saved in `training_out`. The trained model can subsequently be used for segmentation via the `--pretrained-model` argument, for example as following;
+
+
+
+	  steinbock segment cellpose run pretrained-model ./training_out/models/myModel
+
+
 !!! note "GPU support"
     Currently. steinbock does not support cellpose segmentation with GPU support.
 

diff --git a/docs/cli/utils.md b/docs/cli/utils.md
@@ -40,3 +40,10 @@ The created image tiles will have the following file name, where `{IMG}` is the
 The following command will stitch all mask tiles in `masks` (following the file conventions above) to assemble masks of original size and save them to `masks_full`:
 
     steinbock utils mosaics stitch masks -o masks_full
+
+### Expansion
+
+This utility incorporates the `expand_labels` from (`skimage.segmentation`)[https://scikit-image.org/docs/stable/api/skimage.segmentation.html#skimage.segmentation.expand_labels]. It expands mask objects outwards by up to a distance specified in pixels without overflowing into neighboring regions.
+The following command expands the masks in each fils contained in `masks` directory by a maximum of 5 pixels and saves the resulting masks in `expanded_masks`:
+
+    steinbock utils expand masks 5 -o expanded_masks
diff --git a/docs/install-docker.md b/docs/install-docker.md
@@ -4,6 +4,20 @@ The *steinbock* toolkit can be used interactively using the *steinbock* Docker c
 
 In this section, the installation and configuration of the *steinbock* Docker container is described.
 
+## Docker container flavors
+
+The *steinbock* docker container is offered in several [flavors] (https://github.com/BodenmillerGroup/steinbock/pkgs/container/steinbock). This is for the most part to avoid overly large containers. The current flavors differ from each other in inclusion of cellpose segmentation and training, [Xpra] (https://xpra.org/)(to run a steinbock-enabled desktop environment within a web browser) and gpu functionality. Apart from the default falvor of *steinbock*, the following flavors are currently available:
+
+  - cellpose
+  - gpu
+  - xpra
+  - cellpose-gpu
+  - gpu-xpra
+  - cellpose-xpra
+
+To install a specific flavor of *steinbock* visit its [package page](https://github.com/BodenmillerGroup/steinbock/pkgs/container/steinbock) and click on the image version of your choice, from the page that follows, copy the path to the container on Github container registry and substitute it for the container path in the following instructions.
+
+
 ## Prerequisites
 
 ### Windows
@@ -131,6 +145,11 @@ The created command alias is retained for the current session and enables runnin
 
         xhost +local:root
 
+### Using the docker container with large images containing more than 65535 objects
+
+by default 16-bit masks are supported at this moment. This may be problematic for large masks containing more than 2^16 - 1 = 65535 Objects. In such situations, there is the option to run the steinbock Docker container with `-e STEINBOCK_MASK_DTYPE=uint32`, for example,  the steinbock alias command for linux becomes:
+
+    alias steinbock="docker run  -e STEINBOCK_MASK_DTYPE=uint32 -v /path/to/data:/data -u $(id -u):$(id -g) --network host -v /tmp/.X11-unix:/tmp/.X11-unix -e DISPLAY ghcr.io/bodenmillergroup/steinbock:0.16.1"
 ## Usage
 
 Please refer to [command-line usage](cli/intro.md) for usage instructions.

diff --git a/requirements.txt b/requirements.txt
@@ -12,6 +12,7 @@ networkx==3.0
 numpy==1.23.5  # deepcell 0.12.4 requires <1.24
 opencv-python-headless==4.7.0.68
 pandas==1.5.3
+pydantic<2
 pyyaml==6.0
 readimc==0.6.2
 scikit-image==0.19.3

diff --git a/setup.cfg b/setup.cfg
@@ -28,6 +28,7 @@ install_requires =
     imageio
     networkx
     numpy
+    opencv-python
     opencv-python-headless
     pandas
     scikit-image

diff --git a/steinbock/_cli/apps.py b/steinbock/_cli/apps.py
@@ -49,7 +49,7 @@ def ilastik_cmd(ilastik_binary, ilastik_args, ilastik_env):
     "--python",
     "python_path",
     type=click.Path(dir_okay=False),
-    default="/opt/cellprofiler-venv/bin/python",
+    default="usr/bin/python",
     show_default=True,
     help="Python path",
 )
@@ -148,3 +148,28 @@ def jupyterlab_cmd(python_path, jupyter_module, jupyterlab_args):
     args = [python_path, "-m", jupyter_module, "lab"] + jupyterlab_args
     result = run_captured(args)
     sys.exit(result.returncode)
+
+
+@apps_cmd_group.command(
+    name="cellpose",
+    context_settings={"ignore_unknown_options": True},
+    help="Run cellpose GUI",
+    add_help_option=False,
+)
+@click.option(
+    "--python",
+    "python_path",
+    type=click.Path(dir_okay=False),
+    default="usr/bin/python",
+    show_default=True,
+    help="Python path",
+)
+
+# @click.argument("cellprofiler_args", nargs=-1, type=click.UNPROCESSED)
+@click_log.simple_verbosity_option(logger=steinbock_logger)
+@catch_exception(handle=SteinbockException)
+def cellpose_view_cmd(python_path):
+    args = [python_path, "-m", "cellpose"]
+
+    result = run_captured(args)
+    sys.exit(result.returncode)
diff --git a/steinbock/export/_cli/data.py b/steinbock/export/_cli/data.py
@@ -275,7 +275,7 @@ def write_anndata(adata, anndata_file, ignore_suffix=False):
             del adata
     if concatenate:
         adata = anndata_concat(
-            adatas, merge="first", label="Image", index_unique=" in "
+            adatas, merge="first", label="Image", index_unique=" in ", pairwise=True
         )
         obs_cols = list(adata.obs.columns)
         obs_cols.insert(0, obs_cols.pop(obs_cols.index("Image")))

diff --git a/steinbock/preprocessing/_cli/imc.py b/steinbock/preprocessing/_cli/imc.py
@@ -191,9 +191,16 @@ def panel_cmd(
     show_default=True,
     help="Path to the image information output file",
 )
+@click.option(
+    "--xti/--no-xti",
+    "xti",
+    default=False,
+    show_default=True,
+    help="generate txt files from xti imc file",
+)
 @click_log.simple_verbosity_option(logger=steinbock_logger)
 @catch_exception(handle=SteinbockException)
-def images_cmd(mcd_dir, txt_dir, unzip, panel_file, hpf, img_dir, image_info_file):
+def images_cmd(mcd_dir, txt_dir, unzip, panel_file, hpf, img_dir, image_info_file, xti):
     channel_names = None
     if Path(panel_file).is_file():
         panel = io.read_panel(panel_file)
@@ -205,14 +212,19 @@ def images_cmd(mcd_dir, txt_dir, unzip, panel_file, hpf, img_dir, image_info_fil
     txt_files = imc.list_txt_files(txt_dir, unzip=unzip)
     mcd_txt_files = {}
     num_dupl = 0
+
     for (
         mcd_or_txt_file,
         acquisition,
         img,
         recovery_txt_file,
         recovered,
     ) in imc.try_preprocess_images_from_disk(
-        mcd_files, txt_files, channel_names=channel_names, hpf=hpf, unzip=unzip
+        mcd_files,
+        txt_files,
+        channel_names=channel_names,
+        hpf=hpf,
+        unzip=unzip,
     ):
         img_file_stem = Path(mcd_or_txt_file).stem
         if acquisition is not None:
@@ -239,3 +251,30 @@ def images_cmd(mcd_dir, txt_dir, unzip, panel_file, hpf, img_dir, image_info_fil
     image_info = pd.DataFrame(data=image_info_data)
     io.write_image_info(image_info, image_info_file)
     logger.info(image_info_file)
+    if xti:
+        mcd_txt_files = {}
+        num_dupl = 0
+        for (
+            mcd_file,
+            acquisition,
+            img,
+        ) in imc.try_gen_text_file_from_mcd(mcd_files, unzip=unzip):
+            img_file_stem = Path(mcd_file).stem
+            if acquisition is not None:
+                img_file_stem += f"_{acquisition.id:03d}"
+            if img_file_stem in mcd_txt_files:
+                num_dupl += 1
+                first_mcd_txt_file = mcd_txt_files[img_file_stem][0]
+                img_file_stem = f"DUPLICATE{num_dupl:03d}_{img_file_stem}"
+                logger.warning(
+                    f"File {mcd_file} is a duplicate of {first_mcd_txt_file}, "
+                    f"saving as {img_file_stem}"
+                )
+                mcd_txt_files[img_file_stem].append(mcd_file)
+            else:
+                mcd_txt_files[img_file_stem] = [mcd_file]
+
+            gentxt_file = Path(txt_dir) / f"{img_file_stem}.txt"
+            img.to_csv(gentxt_file, header=True, index=None, sep="\t")
+            del img
+            logger.info(gentxt_file)