# MN UNet segmenter
A package for segmenting micronuclei in micrographs.
## Quick-start
````
from mnfinder import MNClassifier
import numpy as np
from tifffile import TiffFile
trained_model = MNClassifier.get_model()
image = TiffFile.imread('path/to/image.tiff').asarray()
labels = 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.
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`: `True`
* `opening_radius`: 1
#### 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`: `True`
* `opening_radius`: 1
#### Combined
An Attention U-Net trained on the micronucleus output of `Attention` and `MSAttention`.
**Defaults**
* `skip_opening`: `False`
* `expand_masks`: `True`
* `use_argmax`: `True`
* `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"))
labels = trained_model.predict(img, skip_opening=[bool], expand_masks=[bool], use_argmax=[bool], area_thresh=[int], return_raw_output=[bool])
````
A single method is used to predict and label nuclear and micronucler segments.
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.
Labels are returned as a 3-channel image. Channel 1 contains the unique cell label for each segmented nucleus; channel 2 has each micronucleus labelled with its corresponding cell label; channel 3 has a unique label for each micronucleus.
#### 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 this to `False` to skip this conversion. Defaults to `250`.
`return_raw_output=bool`
: If you wish to examine the fields returned by the semantic and instance classifier neural nets, set this to `True`.
### Prediction info
````
mn_df, nuc_df = MNClassifier.get_label_data(labels)
````
Provides some basic information about each MN and nuclear label predicted.
Raw data
{
"_id": null,
"home_page": null,
"name": "mnfinder",
"maintainer": null,
"docs_url": null,
"requires_python": ">3.11",
"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/3d/0c/96cb7d849ad8e6d7c6aaf09d4298b0670fbaf60823b12d98dbe6a4adfcf7/mnfinder-1.2.3.tar.gz",
"platform": null,
"description": "# MN UNet segmenter\nA package for segmenting micronuclei in micrographs.\n\n## Quick-start\n````\nfrom mnfinder import MNClassifier\nimport numpy as np\nfrom tifffile import TiffFile\n\ntrained_model = MNClassifier.get_model()\n\nimage = TiffFile.imread('path/to/image.tiff').asarray()\nlabels = 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.\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`: `True`\n* `opening_radius`: 1\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`: `True`\n* `opening_radius`: 1\n\n#### Combined\nAn Attention U-Net trained on the micronucleus output of `Attention` and `MSAttention`.\n\n**Defaults**\n* `skip_opening`: `False`\n* `expand_masks`: `True`\n* `use_argmax`: `True`\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\"))\nlabels = trained_model.predict(img, skip_opening=[bool], expand_masks=[bool], use_argmax=[bool], area_thresh=[int], return_raw_output=[bool])\n````\nA single method is used to predict and label nuclear and micronucler segments. \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\nLabels are returned as a 3-channel image. Channel 1 contains the unique cell label for each segmented nucleus; channel 2 has each micronucleus labelled with its corresponding cell label; channel 3 has a unique label for each micronucleus. \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 this to `False` to skip this conversion. Defaults to `250`.\n\n`return_raw_output=bool`\n: If you wish to examine the fields returned by the semantic and instance classifier neural nets, set this to `True`.\n\n### Prediction info\n````\nmn_df, nuc_df = MNClassifier.get_label_data(labels)\n````\nProvides some basic information about each MN and nuclear label predicted.",
"bugtrack_url": null,
"license": null,
"summary": "A package for segmenting micronuclei in microscopy images",
"version": "1.2.3",
"project_urls": {
"Homepage": "https://github.com/hatch-lab/mnfinder"
},
"split_keywords": [
"u-net",
" micronuclei",
" micronucleus",
" segmentation"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c6a40be44dc1da46500ba6d4449c704a4132c0bf56792cf68d5582928f9191b7",
"md5": "592987984e8b4253a4efe4b1aeab990d",
"sha256": "11b1f6aea9f40b4dd3cf6c3de30ef8d517a4833907b88b86ce2b7ab1f9dbce4a"
},
"downloads": -1,
"filename": "mnfinder-1.2.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "592987984e8b4253a4efe4b1aeab990d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">3.11",
"size": 68240702,
"upload_time": "2024-10-08T04:52:32",
"upload_time_iso_8601": "2024-10-08T04:52:32.960340Z",
"url": "https://files.pythonhosted.org/packages/c6/a4/0be44dc1da46500ba6d4449c704a4132c0bf56792cf68d5582928f9191b7/mnfinder-1.2.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3d0c96cb7d849ad8e6d7c6aaf09d4298b0670fbaf60823b12d98dbe6a4adfcf7",
"md5": "a45b336d714b6a82a312484e4d42cc1d",
"sha256": "fcd39f5e84972496af12058738b13c627e89a41376e17a168d6c0ff58fa09b32"
},
"downloads": -1,
"filename": "mnfinder-1.2.3.tar.gz",
"has_sig": false,
"md5_digest": "a45b336d714b6a82a312484e4d42cc1d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">3.11",
"size": 69435568,
"upload_time": "2024-10-08T04:53:36",
"upload_time_iso_8601": "2024-10-08T04:53:36.640877Z",
"url": "https://files.pythonhosted.org/packages/3d/0c/96cb7d849ad8e6d7c6aaf09d4298b0670fbaf60823b12d98dbe6a4adfcf7/mnfinder-1.2.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-08 04:53:36",
"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
