# Run Stardist <!-- omit in toc -->
A complete training and inference pipeline for 3D StarDist with an example on 3D biological (ovules) datasets. Please submit an issue if you encountered errors or if you have any questions or suggestions.
- [Models](#models)
- [Model information](#model-information)
- [Training data stats and links](#training-data-stats-and-links)
- [Installation](#installation)
- [Install Anaconda/Miniconda python](#install-anacondaminiconda-python)
- [Install this repo using Conda without Git](#install-this-repo-using-conda-without-git)
- [Install this repo using Conda with Git](#install-this-repo-using-conda-with-git)
- [Usage](#usage)
- [Example configuration file for both training and inference](#example-configuration-file-for-both-training-and-inference)
- [Training](#training)
- [Prediction](#prediction)
- [Specifying a Graphic Card (GPU)](#specifying-a-graphic-card-gpu)
## Models
A 3D nucleus segmentation model is available for download from Bioimage.IO and ready to be used directly for segmenting your nuclei. The model is trained on a 3D confocal ovule dataset from *Arabidopsis thaliana*.
### Model information
Model weights and related files can be found at: https://zenodo.org/doi/10.5281/zenodo.8421755.
After downloading the model, put it in your `PATH_TO_MODEL_DIR` and specify the model name as `MY_MODEL_NAME` in the configuration file (see below). Then you can run `predict.py` in this repository and use the model for inference (see below).
### Training data stats and links
The training data is publicly available on Zenodo at `[LINK](to be published after paper submission)`. Some key information about the training data is listed below:
```python
original_voxel_size = { # z, y, x
1135: [0.28371836501901143, 0.12678642066720086, 0.12678642066720086], # validation
1136: [0.2837183895131086, 0.12756971653115998, 0.12756971653115998], # training
1137: [0.2837183895131086, 0.1266211463645486, 0.1266211463645486 ], # training
1139: [0.2799036917562724, 0.12674335484590543, 0.12674335484590543], # training
1170: [0.27799632231404964, 0.12698523961670266, 0.12698522349145364], # training
} # [0.2837, 0.1268, 0.1268] is taken as the median
original_median_extents = { # z, y, x
1135: [16, 32, 33], # validation
1136: [16, 32, 32], # training
1137: [16, 32, 32], # training
1139: [16, 32, 33], # training
1170: [16, 29, 30], # training
'average':
} # [16, 32, 32] is taken as the median
```
## Installation
### Install Anaconda/Miniconda python
First step required to use the pipeline is installing Miniconda. If you already have a working Anaconda setup you can go directly to the next step. Anaconda can be downloaded for all platforms from [here](https://www.anaconda.com/products/distribution). We suggest to use Miniconda, because it is lighter and install fewer unnecessary packages.
To download Miniconda, open a terminal and type:
```bash
$ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh
```
Then install by typing:
```bash
$ bash ./Miniconda3-latest-Linux-x86_64.sh
```
<details>
<summary>
### Install this repo using Conda without Git
</summary>
1. [Download](https://github.com/qin-yu/ovules-instance-segmentation/archive/refs/heads/main.zip) and unzip this repository into your machine if you haven't done so
2. Go into the StarDist subdirectory:
```bash
$ cd ovules-instance-segmentation-main/stardist/
```
3. Create the environment from the environment.yml file:
```bash
$ conda env create -f environment.yml
```
4. Activate the environment:
```bash
$ conda activate stardist
```
</details>
<details open>
<summary>
### Install this repo using Conda with Git
</summary>
1. Clone this repository into your machine if you haven't done so:
```bash
$ git clone git@github.com:qin-yu/ovules-instance-segmentation.git
```
2. Go into the StarDist subdirectory:
```bash
$ cd ovules-instance-segmentation/stardist/
```
3. Create the environment from the environment.yml file:
```bash
$ conda env create -f environment.yml
```
4. Activate the environment:
```bash
$ conda activate stardist
```
</details>
## Usage
### Example configuration file for both training and inference
The original configuration file used for training the final ResNet StarDist model published on Bioimage.IO for wide applicability can be found at `stardist/configs/final_resnet_model_config.yml`, which can used for both training and inference (note that the inference output is only used for illustration in this repository because it's segmenting the training data).
The generic template is shown below. A configuration template with more guidelines can be found at `stardist/configs/train_and_infer.yml`.
```yaml
wandb: # optional, remove this part if not using W&B
project: ovules-instance-segmentation
name: final-stardist-model
data:
# Rescale outside StarDist
rescale_factor: Null
# Training (ignored in inference config file)
training:
- PATH_TO_INPUT_DIR_1 or PATH_TO_INPUT_FILE_1
- PATH_TO_INPUT_DIR_2 or PATH_TO_INPUT_FILE_2
validation:
- PATH_TO_INPUT_DIR_3 or PATH_TO_INPUT_FILE_3
raw_name: raw/noisy # only required if HDF5
label_name: label/gold # only required if HDF5
# Inference (ignored in training config file)
prediction:
- PATH_TO_INPUT_DIR_4 or PATH_TO_INPUT_FILE_4
- PATH_TO_INPUT_DIR_5 or PATH_TO_INPUT_FILE_5
format: tiff # only 'hdf5' or 'tiff'
name: raw/nuclei # dataset name of the raw image in HDF5 files, only required if format is `hdf5`
output_dir: MY_OUTPUT_DIR
output_dtype: uint16 # `uint8`, `uint16`, or `float32` are recommended
resize_to_original: True # output should be of he same shape as input
target_voxel_size: Null # the desired voxel size to rescale to during inference, null if rescale factor is set
save_probability_map: True
stardist:
model_dir: PATH_TO_MODEL_DIR
model_name: MY_MODEL_NAME
model_type: StarDist3D
model_config: # model configuration should stay identical for training and inference
backbone: resnet
n_rays: 96
grid: [2, 4, 4]
use_gpu: False
n_channel_in: 1
patch_size: [96, 96, 96] # multiple of 16 prefered
train_batch_size: 8
train_n_val_patches: 16
steps_per_epoch: 400
epochs: 1000
augmenter:
name: default
```
### Training
```shell
$ train-stardist --config CONFIG_PATH
```
where CONFIG_PATH is the path to the YAML configuration file. For example, if you want to train the model with the example configuration file `configs/train_and_infer.yml`:
```shell
$ cd ovules-instance-segmentation/stardist/
$ train-stardist --config configs/train_and_infer.yml
```
### Prediction
```shell
$ predict-stardist --config CONFIG_PATH
```
where CONFIG_PATH is the path to the YAML configuration file. For example, if you want to use the model with the example configuration file `configs/train_and_infer.yml`:
```shell
$ cd ovules-instance-segmentation/stardist/
$ predict-stardist --config configs/train_and_infer.yml
```
**Preprocessing:** For the published [StarDist Plant Nuclei 3D ResNet](https://zenodo.org/doi/10.5281/zenodo.8421755) the median size of nuclei in training data is `[16, 32, 32]`. To achieve the best segmentation result, the input 3D images should be rescaled so that your nucleus size in ZYX matches the training data. For example, if the median nucleus size of your data is `[32, 32, 32]`, then `rescale_factor` should be `[0.5, 1., 1.]`; if it's `[15, 33, 31]`, then it does not have to be rescaled. You may also choose to leave `rescale_factor` as `Null` and rescale your images with Fiji or other tools before running the pipeline. If `resize_to_original` is `True` then the output will have the original size of the input image.
### Specifying a Graphic Card (GPU)
If you need to specify a graphic card, for example to use the No. 7 card, do:
```shell
$ CUDA_VISIBLE_DEVICES=7 predict-stardist --config configs/train_and_infer.yml
```
Raw data
{
"_id": null,
"home_page": null,
"name": "run-stardist",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.12,>=3.10",
"maintainer_email": null,
"keywords": "bioimage-analysis,deep-learning,image-processing,nucleus-segmentation,stardist",
"author": null,
"author_email": "Qin Yu <qin.yu@embl.de>",
"download_url": "https://files.pythonhosted.org/packages/f8/d0/809727f5e6346773ae1f2f23e263166b0af421270bdb76fe12e5d9a1511c/run_stardist-0.0.2.tar.gz",
"platform": null,
"description": "# Run Stardist <!-- omit in toc -->\n\n\n\n\n\n\nA complete training and inference pipeline for 3D StarDist with an example on 3D biological (ovules) datasets. Please submit an issue if you encountered errors or if you have any questions or suggestions.\n\n- [Models](#models)\n - [Model information](#model-information)\n - [Training data stats and links](#training-data-stats-and-links)\n- [Installation](#installation)\n - [Install Anaconda/Miniconda python](#install-anacondaminiconda-python)\n - [Install this repo using Conda without Git](#install-this-repo-using-conda-without-git)\n - [Install this repo using Conda with Git](#install-this-repo-using-conda-with-git)\n- [Usage](#usage)\n - [Example configuration file for both training and inference](#example-configuration-file-for-both-training-and-inference)\n - [Training](#training)\n - [Prediction](#prediction)\n - [Specifying a Graphic Card (GPU)](#specifying-a-graphic-card-gpu)\n\n\n## Models\nA 3D nucleus segmentation model is available for download from Bioimage.IO and ready to be used directly for segmenting your nuclei. The model is trained on a 3D confocal ovule dataset from *Arabidopsis thaliana*.\n\n### Model information\nModel weights and related files can be found at: https://zenodo.org/doi/10.5281/zenodo.8421755.\n\nAfter downloading the model, put it in your `PATH_TO_MODEL_DIR` and specify the model name as `MY_MODEL_NAME` in the configuration file (see below). Then you can run `predict.py` in this repository and use the model for inference (see below).\n\n### Training data stats and links\nThe training data is publicly available on Zenodo at `[LINK](to be published after paper submission)`. Some key information about the training data is listed below:\n```python\noriginal_voxel_size = { # z, y, x\n 1135: [0.28371836501901143, 0.12678642066720086, 0.12678642066720086], # validation\n 1136: [0.2837183895131086, 0.12756971653115998, 0.12756971653115998], # training\n 1137: [0.2837183895131086, 0.1266211463645486, 0.1266211463645486 ], # training\n 1139: [0.2799036917562724, 0.12674335484590543, 0.12674335484590543], # training\n 1170: [0.27799632231404964, 0.12698523961670266, 0.12698522349145364], # training\n} # [0.2837, 0.1268, 0.1268] is taken as the median\n\noriginal_median_extents = { # z, y, x\n 1135: [16, 32, 33], # validation\n 1136: [16, 32, 32], # training\n 1137: [16, 32, 32], # training\n 1139: [16, 32, 33], # training\n 1170: [16, 29, 30], # training\n 'average':\n} # [16, 32, 32] is taken as the median\n```\n\n## Installation\n\n### Install Anaconda/Miniconda python\nFirst step required to use the pipeline is installing Miniconda. If you already have a working Anaconda setup you can go directly to the next step. Anaconda can be downloaded for all platforms from [here](https://www.anaconda.com/products/distribution). We suggest to use Miniconda, because it is lighter and install fewer unnecessary packages.\n\nTo download Miniconda, open a terminal and type:\n```bash\n$ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh\n```\n\nThen install by typing:\n```bash\n$ bash ./Miniconda3-latest-Linux-x86_64.sh\n```\n\n<details>\n<summary>\n\n### Install this repo using Conda without Git\n</summary>\n\n1. [Download](https://github.com/qin-yu/ovules-instance-segmentation/archive/refs/heads/main.zip) and unzip this repository into your machine if you haven't done so\n2. Go into the StarDist subdirectory:\n ```bash\n $ cd ovules-instance-segmentation-main/stardist/\n ```\n3. Create the environment from the environment.yml file:\n ```bash\n $ conda env create -f environment.yml\n ```\n4. Activate the environment:\n ```bash\n $ conda activate stardist\n ```\n</details>\n\n\n<details open>\n<summary>\n\n### Install this repo using Conda with Git\n</summary>\n\n1. Clone this repository into your machine if you haven't done so:\n ```bash\n $ git clone git@github.com:qin-yu/ovules-instance-segmentation.git\n ```\n2. Go into the StarDist subdirectory:\n ```bash\n $ cd ovules-instance-segmentation/stardist/\n ```\n3. Create the environment from the environment.yml file:\n ```bash\n $ conda env create -f environment.yml\n ```\n4. Activate the environment:\n ```bash\n $ conda activate stardist\n ```\n</details>\n\n## Usage\n\n### Example configuration file for both training and inference\nThe original configuration file used for training the final ResNet StarDist model published on Bioimage.IO for wide applicability can be found at `stardist/configs/final_resnet_model_config.yml`, which can used for both training and inference (note that the inference output is only used for illustration in this repository because it's segmenting the training data).\n\nThe generic template is shown below. A configuration template with more guidelines can be found at `stardist/configs/train_and_infer.yml`.\n```yaml\nwandb: # optional, remove this part if not using W&B\n project: ovules-instance-segmentation\n name: final-stardist-model\n\ndata:\n # Rescale outside StarDist\n rescale_factor: Null\n\n # Training (ignored in inference config file)\n training:\n - PATH_TO_INPUT_DIR_1 or PATH_TO_INPUT_FILE_1\n - PATH_TO_INPUT_DIR_2 or PATH_TO_INPUT_FILE_2\n validation:\n - PATH_TO_INPUT_DIR_3 or PATH_TO_INPUT_FILE_3\n raw_name: raw/noisy # only required if HDF5\n label_name: label/gold # only required if HDF5\n\n # Inference (ignored in training config file)\n prediction:\n - PATH_TO_INPUT_DIR_4 or PATH_TO_INPUT_FILE_4\n - PATH_TO_INPUT_DIR_5 or PATH_TO_INPUT_FILE_5\n format: tiff # only 'hdf5' or 'tiff'\n name: raw/nuclei # dataset name of the raw image in HDF5 files, only required if format is `hdf5`\n output_dir: MY_OUTPUT_DIR\n output_dtype: uint16 # `uint8`, `uint16`, or `float32` are recommended\n resize_to_original: True # output should be of he same shape as input\n target_voxel_size: Null # the desired voxel size to rescale to during inference, null if rescale factor is set\n save_probability_map: True\n\nstardist:\n model_dir: PATH_TO_MODEL_DIR\n model_name: MY_MODEL_NAME\n model_type: StarDist3D\n model_config: # model configuration should stay identical for training and inference\n backbone: resnet\n n_rays: 96\n grid: [2, 4, 4]\n use_gpu: False\n n_channel_in: 1\n patch_size: [96, 96, 96] # multiple of 16 prefered\n train_batch_size: 8\n train_n_val_patches: 16\n steps_per_epoch: 400\n epochs: 1000\n\naugmenter:\n name: default\n```\n\n### Training\n```shell\n$ train-stardist --config CONFIG_PATH\n```\nwhere CONFIG_PATH is the path to the YAML configuration file. For example, if you want to train the model with the example configuration file `configs/train_and_infer.yml`:\n```shell\n$ cd ovules-instance-segmentation/stardist/\n$ train-stardist --config configs/train_and_infer.yml\n```\n\n### Prediction\n```shell\n$ predict-stardist --config CONFIG_PATH\n```\nwhere CONFIG_PATH is the path to the YAML configuration file. For example, if you want to use the model with the example configuration file `configs/train_and_infer.yml`:\n```shell\n$ cd ovules-instance-segmentation/stardist/\n$ predict-stardist --config configs/train_and_infer.yml\n```\n\n**Preprocessing:** For the published [StarDist Plant Nuclei 3D ResNet](https://zenodo.org/doi/10.5281/zenodo.8421755) the median size of nuclei in training data is `[16, 32, 32]`. To achieve the best segmentation result, the input 3D images should be rescaled so that your nucleus size in ZYX matches the training data. For example, if the median nucleus size of your data is `[32, 32, 32]`, then `rescale_factor` should be `[0.5, 1., 1.]`; if it's `[15, 33, 31]`, then it does not have to be rescaled. You may also choose to leave `rescale_factor` as `Null` and rescale your images with Fiji or other tools before running the pipeline. If `resize_to_original` is `True` then the output will have the original size of the input image.\n\n### Specifying a Graphic Card (GPU)\nIf you need to specify a graphic card, for example to use the No. 7 card, do:\n```shell\n$ CUDA_VISIBLE_DEVICES=7 predict-stardist --config configs/train_and_infer.yml\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "Train and use StarDist models",
"version": "0.0.2",
"project_urls": {
"Documentation": "https://github.com/qin-yu/ovules-instance-segmentation/stardist/README.md",
"Homepage": "https://github.com/qin-yu/ovules-instance-segmentation"
},
"split_keywords": [
"bioimage-analysis",
"deep-learning",
"image-processing",
"nucleus-segmentation",
"stardist"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "6b67ae77da6fe039246741671a4d1d5753b5de6739b9f31179b4fbd212eb12a2",
"md5": "e7e48208a235b2ade7aaf48b5c9a574d",
"sha256": "29b4f51afffee882392d4cca1c4b2178e6745727b37dc891990627c9a6965d67"
},
"downloads": -1,
"filename": "run_stardist-0.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e7e48208a235b2ade7aaf48b5c9a574d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.12,>=3.10",
"size": 21786,
"upload_time": "2023-11-06T16:26:49",
"upload_time_iso_8601": "2023-11-06T16:26:49.404830Z",
"url": "https://files.pythonhosted.org/packages/6b/67/ae77da6fe039246741671a4d1d5753b5de6739b9f31179b4fbd212eb12a2/run_stardist-0.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "f8d0809727f5e6346773ae1f2f23e263166b0af421270bdb76fe12e5d9a1511c",
"md5": "06dd494f63c026a1e8f60acfed8cda70",
"sha256": "9b856696d85cbb4cefe9170481a4fc34749e7eb822926735a45b41ec5708da3c"
},
"downloads": -1,
"filename": "run_stardist-0.0.2.tar.gz",
"has_sig": false,
"md5_digest": "06dd494f63c026a1e8f60acfed8cda70",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.12,>=3.10",
"size": 19126,
"upload_time": "2023-11-06T16:26:48",
"upload_time_iso_8601": "2023-11-06T16:26:48.107951Z",
"url": "https://files.pythonhosted.org/packages/f8/d0/809727f5e6346773ae1f2f23e263166b0af421270bdb76fe12e5d9a1511c/run_stardist-0.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-06 16:26:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "qin-yu",
"github_project": "ovules-instance-segmentation",
"github_not_found": true,
"lcname": "run-stardist"
}
JSON
