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.
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-coreOnce you have installed napari. You can install napari either through the napari plugin installation tool, or directly from PyPI with:
pip install cellfinder-napariN.B. To speed up cellfinder, you need CUDA & cuDNN installed. Instructions here.
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.
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: 2Cell 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)
# 1If 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")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)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,
)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 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.
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
Classical image analysis (e.g. filters, thresholding) is used to find cell-like objects (with false positives):
Candidate cells (including many artefacts)
A deep-learning network (ResNet) is used to classify cell candidates as true cells or artefacts:
Cassified cell candidates. Yellow - cells, Blue - artefacts
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.
The BrainGlobe project is generously supported by the Sainsbury Wellcome Centre and the Institute of Neuroscience, Technical University of Munich, with funding from Wellcome, the Gatsby Charitable Foundation and the Munich Cluster for Systems Neurology - Synergy.
