mnfinder 1.2.3
A package for segmenting micronuclei in microscopy images
Requires Python: >3.11
Keywords: U-Net, micronuclei, micronucleus, segmentation

# 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.