Automated 3D cell detection in large microscopy images
Project description
cellfinder-core
Standalone cellfinder cell detection algorithm
This package implements the cell detection algorithm from Tyson, Rousseau & Niedworok et al. (2021) without any dependency on data type (i.e. it can be used outside of whole-brain microscopy).
cellfinder-core
supports the
cellfinder software for
whole-brain microscopy analysis, and the algorithm can also be implemented in
napari using the
cellfinder napari plugin.
Instructions
Installation
cellfinder-core
supports Python >=3.7,
and works across Linux, Windows, and should work on most versions of macOS
(although this is not tested).
Assuming you have a Python environment set up
(e.g. using conda),
you can install cellfinder-core
with:
pip install cellfinder-core
Once you have installed napari. You can install napari either through the napari plugin installation tool, or directly from PyPI with:
pip install cellfinder-napari
N.B. To speed up cellfinder, you need CUDA & cuDNN installed. Instructions here.
Usage
Before using cellfinder-core, it may be useful to take a look at the preprint which outlines the algorithm.
The API is not yet fully documented. For an idea of what the parameters do, see the documentation for the cellfinder whole-brain microscopy image analysis command-line tool (cell candidate detection, cell candidate classification). It may also be useful to try the cellfinder napari plugin so you can adjust the parameters in a GUI.
To run the full pipeline (cell candidate detection and classification)
from cellfinder_core.main import main as cellfinder_run
import tifffile
signal_array = tifffile.imread("/path/to/signal_image.tif")
background_array = tifffile.imread("/path/to/background_image.tif")
voxel_sizes = [5, 2, 2] # in microns
detected_cells = cellfinder_run(signal_array,background_array,voxel_sizes)
The output is a list of
imlib Cell objects.
Each Cell
has a centroid coordinate, and a type:
print(detected_cells[0])
# Cell: x: 132, y: 308, z: 10, type: 2
Cell type 2 is a "real" cell, and Cell type 1 is a "rejected" object (i.e. not classified as a cell):
from imlib.cells.cells import Cell
print(Cell.CELL)
# 2
print(Cell.NO_CELL)
# 1
Saving the results
If you want to save the detected cells for use in other BrainGlobe software (e.g. the cellfinder napari plugin), you can save in the cellfinder XML standard:
from imlib.IO.cells import save_cells
save_cells(detected_cells, "/path/to/cells.xml")
You can load these back with:
from imlib.IO.cells import get_cells
cells = get_cells("/path/to/cells.xml")
Using dask for lazy loading
cellfinder-core
supports most array-like objects. Using
Dask arrays allows for lazy
loading of data, allowing large (e.g. TB) datasets to be processed.
cellfinder-core
comes with a function
(based on napari-ndtiffs) to
load a series of image files (e.g. a directory of 2D tiff files) as a Dask
array. cellfinder-core
can then be used in the same way as with a numpy array.
from cellfinder_core.main import main as cellfinder_run
from cellfinder_core.tools.IO import read_with_dask
signal_array = read_with_dask("/path/to/signal_image_directory")
background_array = read_with_dask("/path/to/background_image_directory")
voxel_sizes = [5, 2, 2] # in microns
detected_cells = cellfinder_run(signal_array,background_array,voxel_sizes)
Running the cell candidate detection and classification separately.
import tifffile
from pathlib import Path
from cellfinder_core.detect import detect
from cellfinder_core.classify import classify
from cellfinder_core.tools.prep import prep_classification
signal_array = tifffile.imread("/path/to/signal_image.tif")
background_array = tifffile.imread("/path/to/background_image.tif")
voxel_sizes = [5, 2, 2] # in microns
home = Path.home()
install_path = home / ".cellfinder" # default
start_plane=0
end_plane=-1
trained_model=None
model_weights=None
model="resnet50_tv"
batch_size=32
n_free_cpus=2
network_voxel_sizes=[5, 1, 1]
soma_diameter=16
ball_xy_size=6
ball_z_size=15
ball_overlap_fraction=0.6
log_sigma_size=0.2
n_sds_above_mean_thresh=10
soma_spread_factor=1.4
max_cluster_size=100000
cube_width=50
cube_height=50
cube_depth=20
network_depth="50"
model_weights = prep_classification(
trained_model, model_weights, install_path, model, n_free_cpus
)
cell_candidates = detect.main(
signal_array,
start_plane,
end_plane,
voxel_sizes,
soma_diameter,
max_cluster_size,
ball_xy_size,
ball_z_size,
ball_overlap_fraction,
soma_spread_factor,
n_free_cpus,
log_sigma_size,
n_sds_above_mean_thresh,
)
if len(cell_candidates) > 0: # Don't run if there's nothing to classify
classified_cells = classify.main(
cell_candidates,
signal_array,
background_array,
n_free_cpus,
voxel_sizes,
network_voxel_sizes,
batch_size,
cube_height,
cube_width,
cube_depth,
trained_model,
model_weights,
network_depth,
)
Training the network
The training data needed are matched pairs (signal & background) of small (usually 50 x 50 x 100um) images centered on the coordinate of candidate cells. These can be generated however you like, but I recommend using the Napari plugin.
cellfinder-core
comes with a 50-layer ResNet trained on ~100,000 data points
from serial two-photon microscopy images of mouse brains
(available here).
Training the network is likely simpler using the command-line interface or the Napari plugin, but it is possible through the Python API.
from pathlib import Path
from cellfinder_core.train.train_yml import run as run_training
# list of training yml files
yaml_files = [Path("/path/to/training_yml.yml)]
# where to save the output
output_directory = Path("/path/to/saved_training_data")
home = Path.home()
install_path = home / ".cellfinder" # default
run_training(
output_directory,
yaml_files,
install_path=install_path,
learning_rate=0.0001,
continue_training=True, # by default use supplied model
test_fraction=0.1,
batch_size=32,
save_progress=True,
epochs=10,
)
More info
More documentation about cellfinder and other BrainGlobe tools can be found here.
This software is at a very early stage, and was written with our data in mind. Over time we hope to support other data types/formats. If you have any questions or issues, please get in touch by email, on the forum or by raising an issue.
Illustration
Introduction
cellfinder takes a stitched, but otherwise raw dataset with at least two channels:
- Background channel (i.e. autofluorescence)
- Signal channel, the one with the cells to be detected:
Raw coronal serial two-photon mouse brain image showing labelled cells
Cell candidate detection
Classical image analysis (e.g. filters, thresholding) is used to find cell-like objects (with false positives):
Candidate cells (including many artefacts)
Cell candidate classification
A deep-learning network (ResNet) is used to classify cell candidates as true cells or artefacts:
Cassified cell candidates. Yellow - cells, Blue - artefacts
Citing cellfinder
If you find this plugin useful, and use it in your research, please cite the preprint outlining the cell detection algorithm:
Tyson, A. L., Rousseau, C. V., Niedworok, C. J., Keshavarzi, S., Tsitoura, C., Cossell, L., Strom, M. and Margrie, T. W. (2021) “A deep learning algorithm for 3D cell detection in whole mouse brain image datasets’ PLOS Computational Biology, 17(5), e1009074 https://doi.org/10.1371/journal.pcbi.1009074
If you use this, or any other tools in the brainglobe suite, please let us know, and we'd be happy to promote your paper/talk etc.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for cellfinder_core-0.2.7-cp39-cp39-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0e7914777bdb90255a2ed2aee3e2087c2a2918692661d819d72521ae239da687 |
|
MD5 | 66911b434e8487bec5c2189f2d450274 |
|
BLAKE2b-256 | 14601fd6640cc4ec5d513177842aab0432bde44ba59805e866344fab82bef958 |
Hashes for cellfinder_core-0.2.7-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | cd0f306a8b666c1008b5054b9b4c5ee4a0392b8617ff3343b3ca3dc1a14552cb |
|
MD5 | ea1839dd8982fc45680e00591b2cbc0b |
|
BLAKE2b-256 | 08f00e689ff6ca74d69671b90bd4faa806b29f47bc63081a08681d629ea196b1 |
Hashes for cellfinder_core-0.2.7-cp39-cp39-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7489248a5c5d88d7cada1e86f67c89afe146a8c5153d1f06cb6abafc9e7f40d2 |
|
MD5 | ab4524e1b8888593d14b15d9027ec29f |
|
BLAKE2b-256 | d815af03109669fa1dd0720448db8225dbd4a13568247532078c0ec07dc6d88b |
Hashes for cellfinder_core-0.2.7-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a0b6dde9abfa712c21274fb7755871f94415d94b5af2019d1fe02acaebc08f9b |
|
MD5 | 2e411889638c2eb7947ad2d6b4c5b215 |
|
BLAKE2b-256 | 324c2dd1c50f022352c3e2b662c5d8f9abe27cc505a11e3c225477f642c07cf5 |
Hashes for cellfinder_core-0.2.7-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 89f38caccfdae7e8157cdd63b8f337d89097dedb06972a2cbc696b1352da3449 |
|
MD5 | 76c74213301a42be80b3e72bc74550f3 |
|
BLAKE2b-256 | 5f7c1ad00f06bb490339a400f6603176ed1a8cdc9631053ce7a933360f76bfa2 |
Hashes for cellfinder_core-0.2.7-cp38-cp38-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 34bc94a5139a9f1e862ce3ffbb697d8f467e693182baae6fc002fcc969f1ec9b |
|
MD5 | 2c626afc563bbcc28ba74b58ce68d36d |
|
BLAKE2b-256 | 65ce5a7c631f5bb4f67484a10c6d3303b75fb6a7e81f9abbf1263c31059543b0 |
Hashes for cellfinder_core-0.2.7-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 5b3c11e42e0cb64baa9071f9a73ec7da84e8f837cf26a5d23be7ca06da04dc92 |
|
MD5 | d10fd8a437d4444d1166a1c1f1097727 |
|
BLAKE2b-256 | b7545d4e702e0b1dd1960043c333e6c21f37d1b7a12e74307c9461b7cb157341 |
Hashes for cellfinder_core-0.2.7-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 92ebcc2479a1e5c0886112e245cde24ccd1ffc5af6fa93d43d250210af1316d4 |
|
MD5 | db5c791b8d35b1ad1e27bd725ba33c3a |
|
BLAKE2b-256 | ee20df774b1c3021f6904661492aa4d1c8e0b7b68b7b4734fc812d3f7ed35c0c |
Hashes for cellfinder_core-0.2.7-cp37-cp37m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0bcca401fb13c17b3ed2e7516fd7cad3e584034c07835ddc5ed7eef2a6d700a2 |
|
MD5 | 297de29d055bc5236d63a624d02e7522 |
|
BLAKE2b-256 | 7ec3d0110ffa824ed87d8481322ad14a13cd38163ff28c009e37b43c2134336f |