# MN UNet segmenter
A package for segmenting micronuclei in micrographs.
## Quick-start
````
from mnfinder import MNModel
import numpy as np
from tifffile import TiffFile
trained_model = MNModel.get_model()
image = TiffFile.imread('path/to/image.tiff').asarray()
nuclei_labels, mn_labels, mn_raw = trained_model.predict(image)
````
## Installation
MNFinder depends on TensorFlow. It will be installed for you via `pip`.
### pip
````
pip install mnfinder
````
## Usage
### Loading a model
````
trained_model = MNModel.get_model([model_name])
````
MNFinder supports several different trained models with different architectures. The default is an Attention U-Net using 128x128 images as input.
Weights will be automatically downloaded.
### Available models
#### Attention
The default network is an Attention U-Net that was trained on 128x128 crops.
**Defaults**
* `skip_opening`: `False`
* `expand_masks`: `True`
* `use_argmax`: `False`
* `opening_radius`: 1
#### Attention96
An Attention U-Net trained on 96x96 crops.
**Defaults**
* `skip_opening`: `False`
* `expand_masks`: `True`
* `use_argmax`: `True`
* `opening_radius`: 2
#### MSAttention
This is a modification of the Attention U-Net that incorporates a multi-scale convolution in the down blocks.
**Defaults**
* `skip_opening`: `False`
* `expand_masks`: `True`
* `use_argmax`: `False`
* `opening_radius`: 1
#### MSAttention96
A multiscale Attention U-Net trained on 96x96 crops.
**Defaults**
* `skip_opening`: `False`
* `expand_masks`: `True`
* `use_argmax`: `True`
* `opening_radius`: 1
#### Combined
An Attention U-Net trained on the output of `Attention` and `MSAttention`.
**Defaults**
* `skip_opening`: `False`
* `expand_masks`: `True`
* `use_argmax`: `False`
* `opening_radius`: 1
#### LaplaceDeconstruction
Images are first transformed into Laplace pyramids, and recombined only using the top 2 levels of the pyramid to highlight cell edges.
**Defaults**
* `skip_opening`: `False`
* `expand_masks`: `True`
* `use_argmax`: `False`
* `opening_radius`: 2
### Predictions
````
img = np.array(Image.open("my/image.png"))
nuclei_masks, mn_masks, mn_raw = trained_model.predict(img, skip_opening=[bool], expand_masks=[bool], use_argmax=[bool], area_thresh=[int])
````
A single method is used to predict nuclear and micronucler segments. This package is not designed to replace existing nuclear segmentation models--while it performs well at identifying nucleus pixel classes, it makes no effort at separating nuclei accurately.
These neural nets were trained on images taken at 20x. **Predictions for micrographs taken at other resolutions are greatly improved if they are scaled to match a 20x resolution.**
Images of arbitrary size will be cropped by a sliding window and segments combined.
#### Optional parameters
`skip_opening=bool`
: Whether to skip running opening on MN predictions prior to labelling. Many models are improved by removing small 1- or 2-px segments by image opening—erosion following by dilation. Defaults to the model default.
`expand_masks=bool`
: Whether to expand micronucleus masks by returning the convex hulls of each segment. Defaults to the model default.
`use_argmax=bool`
: Whether to determine pixel classes by taking the maximum probability. Some models are improved by instead setting a simple threshold on the micronucleus class probability, setting a pixel to the micronucleus class even if the model’s nucleus class probability is higher. If `use_argmax` is `False`, the model will select pixels with a background class > `model.bg_max` and a micronucleus class < `model.fg_min`. Defaults to the model default.
`area_thresh=int|False`
: Large micronuclei separated from the nucleus are often classed as nuclei. Any nucleus segments < `area_thresh` will be converted to micronuclei. Set to `False` to skip this conversion. Defaults to `250`.
### Training
````
model, model_history = trained_model.train(train_path=[path/to/training], val_path=[path/to/validation], batch_size=[int], epochs=[int], checkpoint_path=[path/to/training-checkpoints], num_per_image=[int], save_weights=[bool], save_path=[path/to/saved_model])
````
Each model was trained on a relatively small data set of RPE-1 and U2 OS cells. They may be improved by training on your own data set.
Training and validation data should be organized as follows:
````
path/to/folder/
- dataset1/
-- nucleus_masks/
-- mn_masks/
-- images/
- dataset2/
-- nucleus_masks/
-- mn_masks/
-- images/
...
- dataset_n/
-- nucleus_masks/
-- mn_masks/
-- images/
````
The name of the dataset folders is arbitrary and can be whatever you wish. The names of the images in the `images` folder is also arbitrary, but should match the names of the corresponding ground truth segments in the `nucleus_masks` and `mn_masks` folders.
`nucleus_masks` should contain images where nuclei have a pixel value > 0. `mn_masks` should likewise contain images where micronuclei have a pixel value > 0. If you wish to distinguish between intact and ruptured micronuclei, set intact micronuclei pixels to `1` and ruptured micronuclei pixels to `2`.
The following is an example set up for training and validation data:
````
path/to/training-data/
- imageset1/
-- nucleus_masks/
--- image1.png
--- image2.png
-- mn_masks/
--- image1.png
--- image2.png
-- images/
--- image1.tiff
--- image2.tiff
- imageset2/
-- nucleus_masks/
--- IMG2.tif
--- IMG3.tif
-- mn_masks/
--- IMG2.tif
--- IMG3.tif
-- images/
--- IMG2.tiff
--- IMG3.tiff
path/to/validation-data/
- imageset1/
-- nucleus_masks/
--- image3.png
--- image4.png
-- mn_masks/
--- image3.png
--- image4.png
-- images/
--- image3.tiff
--- image4.tiff
````
Images will be processed according to the needs of each model. If the images are multichannel, the first channel will be used for training.
Generally, images are cropped at random locations. Crops without any micronucleus or nucleus segments are ignored. Crops are then subject to augmentation via the Albumentations library.
#### Required parameters
`train_path=str|Path|None`
: Path to training data root. If None, will use this package's training data.
`val_path=str|Path|None`
: Path to validation data root. If None, will use this package's training data.
#### Optional parameters
`batch_size=int|None`
: Training batch size. If None, will default to the model’s prediction batch size. Defaults to `None`.
`epochs=int`
: The number of training epochs. Defaults to `100`.
`checkpoint_path=Path|str|None`
: Where to save checkpoints during training. If `None`, no checkpoints will be saved.
`num_per_image=int|None`
: The number of crops to return per image. Because crops are randomly positioned and can be randomly augmented, more crops can be extracted from a given image than otherwise. If `None`, will default to width/crop size * height/crop_size.
`save_weights=bool`
: Whether to save the model weights. Defaults to `True`.
`save_path=str|Path|None`
: Where to save model weights. If `None`, will overwrite the model’s default weights. Defaults to `None`.
Raw data
{
"_id": null,
"home_page": null,
"name": "mnfinder",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "U-Net, micronuclei, micronucleus, segmentation",
"author": null,
"author_email": "Lucian DiPeso <ldipeso@uw.edu>",
"download_url": "https://files.pythonhosted.org/packages/f9/55/1564da60799b67d22b2ff122f3c4d1c2e25994f054aa176c923ddb625913/mnfinder-1.0.1.tar.gz",
"platform": null,
"description": "# MN UNet segmenter\nA package for segmenting micronuclei in micrographs.\n\n## Quick-start\n````\nfrom mnfinder import MNModel\nimport numpy as np\nfrom tifffile import TiffFile\n\ntrained_model = MNModel.get_model()\n\nimage = TiffFile.imread('path/to/image.tiff').asarray()\nnuclei_labels, mn_labels, mn_raw = trained_model.predict(image)\n````\n\n## Installation\nMNFinder depends on TensorFlow. It will be installed for you via `pip`.\n\n### pip\n````\npip install mnfinder\n````\n\n## Usage\n### Loading a model\n````\ntrained_model = MNModel.get_model([model_name])\n````\n\nMNFinder supports several different trained models with different architectures. The default is an Attention U-Net using 128x128 images as input.\n\nWeights will be automatically downloaded.\n\n### Available models\n#### Attention\nThe default network is an Attention U-Net that was trained on 128x128 crops. \n\n**Defaults**\n* `skip_opening`: `False`\n* `expand_masks`: `True`\n* `use_argmax`: `False`\n* `opening_radius`: 1\n\n#### Attention96\nAn Attention U-Net trained on 96x96 crops.\n\n**Defaults**\n* `skip_opening`: `False`\n* `expand_masks`: `True`\n* `use_argmax`: `True`\n* `opening_radius`: 2\n\n#### MSAttention\nThis is a modification of the Attention U-Net that incorporates a multi-scale convolution in the down blocks.\n\n**Defaults**\n* `skip_opening`: `False`\n* `expand_masks`: `True`\n* `use_argmax`: `False`\n* `opening_radius`: 1\n\n#### MSAttention96\nA multiscale Attention U-Net trained on 96x96 crops.\n\n**Defaults**\n* `skip_opening`: `False`\n* `expand_masks`: `True`\n* `use_argmax`: `True`\n* `opening_radius`: 1\n\n#### Combined\nAn Attention U-Net trained on the output of `Attention` and `MSAttention`.\n\n**Defaults**\n* `skip_opening`: `False`\n* `expand_masks`: `True`\n* `use_argmax`: `False`\n* `opening_radius`: 1\n\n#### LaplaceDeconstruction\nImages are first transformed into Laplace pyramids, and recombined only using the top 2 levels of the pyramid to highlight cell edges.\n\n**Defaults**\n* `skip_opening`: `False`\n* `expand_masks`: `True`\n* `use_argmax`: `False`\n* `opening_radius`: 2\n\n### Predictions\n````\nimg = np.array(Image.open(\"my/image.png\"))\nnuclei_masks, mn_masks, mn_raw = trained_model.predict(img, skip_opening=[bool], expand_masks=[bool], use_argmax=[bool], area_thresh=[int])\n````\n\nA single method is used to predict nuclear and micronucler segments. This package is not designed to replace existing nuclear segmentation models--while it performs well at identifying nucleus pixel classes, it makes no effort at separating nuclei accurately.\n\nThese neural nets were trained on images taken at 20x. **Predictions for micrographs taken at other resolutions are greatly improved if they are scaled to match a 20x resolution.**\n\nImages of arbitrary size will be cropped by a sliding window and segments combined.\n\n#### Optional parameters\n`skip_opening=bool`\n: Whether to skip running opening on MN predictions prior to labelling. Many models are improved by removing small 1- or 2-px segments by image opening\u2014erosion following by dilation. Defaults to the model default.\n\n`expand_masks=bool`\n: Whether to expand micronucleus masks by returning the convex hulls of each segment. Defaults to the model default.\n\n`use_argmax=bool`\n: Whether to determine pixel classes by taking the maximum probability. Some models are improved by instead setting a simple threshold on the micronucleus class probability, setting a pixel to the micronucleus class even if the model\u2019s nucleus class probability is higher. If `use_argmax` is `False`, the model will select pixels with a background class > `model.bg_max` and a micronucleus class < `model.fg_min`. Defaults to the model default.\n\n`area_thresh=int|False`\n: Large micronuclei separated from the nucleus are often classed as nuclei. Any nucleus segments < `area_thresh` will be converted to micronuclei. Set to `False` to skip this conversion. Defaults to `250`.\n\n### Training\n````\nmodel, model_history = trained_model.train(train_path=[path/to/training], val_path=[path/to/validation], batch_size=[int], epochs=[int], checkpoint_path=[path/to/training-checkpoints], num_per_image=[int], save_weights=[bool], save_path=[path/to/saved_model])\n````\n\nEach model was trained on a relatively small data set of RPE-1 and U2 OS cells. They may be improved by training on your own data set.\n\nTraining and validation data should be organized as follows:\n````\npath/to/folder/\n- dataset1/\n-- nucleus_masks/\n-- mn_masks/\n-- images/\n\n- dataset2/\n-- nucleus_masks/\n-- mn_masks/\n-- images/\n\n...\n\n- dataset_n/\n-- nucleus_masks/\n-- mn_masks/\n-- images/\n````\n\nThe name of the dataset folders is arbitrary and can be whatever you wish. The names of the images in the `images` folder is also arbitrary, but should match the names of the corresponding ground truth segments in the `nucleus_masks` and `mn_masks` folders.\n\n`nucleus_masks` should contain images where nuclei have a pixel value > 0. `mn_masks` should likewise contain images where micronuclei have a pixel value > 0. If you wish to distinguish between intact and ruptured micronuclei, set intact micronuclei pixels to `1` and ruptured micronuclei pixels to `2`.\n\nThe following is an example set up for training and validation data:\n````\npath/to/training-data/\n- imageset1/\n-- nucleus_masks/\n--- image1.png\n--- image2.png\n\n-- mn_masks/\n--- image1.png\n--- image2.png\n\n-- images/\n--- image1.tiff\n--- image2.tiff\n\n- imageset2/\n-- nucleus_masks/\n--- IMG2.tif\n--- IMG3.tif\n\n-- mn_masks/\n--- IMG2.tif\n--- IMG3.tif\n\n-- images/\n--- IMG2.tiff\n--- IMG3.tiff\n\npath/to/validation-data/\n- imageset1/\n-- nucleus_masks/\n--- image3.png\n--- image4.png\n\n-- mn_masks/\n--- image3.png\n--- image4.png\n\n-- images/\n--- image3.tiff\n--- image4.tiff\n````\n\nImages will be processed according to the needs of each model. If the images are multichannel, the first channel will be used for training.\n\nGenerally, images are cropped at random locations. Crops without any micronucleus or nucleus segments are ignored. Crops are then subject to augmentation via the Albumentations library.\n\n#### Required parameters\n`train_path=str|Path|None`\n: Path to training data root. If None, will use this package's training data.\n\n`val_path=str|Path|None`\n: Path to validation data root. If None, will use this package's training data.\n\n#### Optional parameters\n`batch_size=int|None`\n: Training batch size. If None, will default to the model\u2019s prediction batch size. Defaults to `None`.\n\n`epochs=int`\n: The number of training epochs. Defaults to `100`.\n\n`checkpoint_path=Path|str|None`\n: Where to save checkpoints during training. If `None`, no checkpoints will be saved.\n`num_per_image=int|None`\n: The number of crops to return per image. Because crops are randomly positioned and can be randomly augmented, more crops can be extracted from a given image than otherwise. If `None`, will default to width/crop size * height/crop_size.\n\n`save_weights=bool`\n: Whether to save the model weights. Defaults to `True`.\n\n`save_path=str|Path|None`\n: Where to save model weights. If `None`, will overwrite the model\u2019s default weights. Defaults to `None`.\n",
"bugtrack_url": null,
"license": null,
"summary": "A package for segmenting micronuclei in microscopy images",
"version": "1.0.1",
"project_urls": {
"Homepage": "https://github.com/hatch-lab/mnfinder"
},
"split_keywords": [
"u-net",
" micronuclei",
" micronucleus",
" segmentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "8c28cab281f647bcb4d5ba6ced238662c682f212ceb0d7dc5c663669fca72ddd",
"md5": "77152032537e22f5b15bc6128c094f61",
"sha256": "5f51667687bc8cbf3599473930a40e9921092ceb37d6cc20b428042e58c0fd11"
},
"downloads": -1,
"filename": "mnfinder-1.0.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "77152032537e22f5b15bc6128c094f61",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 25113854,
"upload_time": "2024-03-21T20:49:49",
"upload_time_iso_8601": "2024-03-21T20:49:49.089703Z",
"url": "https://files.pythonhosted.org/packages/8c/28/cab281f647bcb4d5ba6ced238662c682f212ceb0d7dc5c663669fca72ddd/mnfinder-1.0.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "f9551564da60799b67d22b2ff122f3c4d1c2e25994f054aa176c923ddb625913",
"md5": "2f59da284f24bef170eed21d8529926e",
"sha256": "a0addfdd88ea0b3d7502e909758a6ca465715be72752564661f262333adb4ebd"
},
"downloads": -1,
"filename": "mnfinder-1.0.1.tar.gz",
"has_sig": false,
"md5_digest": "2f59da284f24bef170eed21d8529926e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 26112874,
"upload_time": "2024-03-21T20:50:23",
"upload_time_iso_8601": "2024-03-21T20:50:23.413208Z",
"url": "https://files.pythonhosted.org/packages/f9/55/1564da60799b67d22b2ff122f3c4d1c2e25994f054aa176c923ddb625913/mnfinder-1.0.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-21 20:50:23",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "hatch-lab",
"github_project": "mnfinder",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [],
"lcname": "mnfinder"
}
JSON
