cellfinder-core has merged with it's napari plugin and is now available as a single package called cellfinder.
We recommend you uninstall cellfinder-core and instead use the functionality provided in the cellfinder package.
These changes are part of our wider restructuring of the BrainGlobe suite of tools and analysis pipelines, which you can keep up to date with on our blog.
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.9,
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.
Linux and MacOS users can also install cellfinder-core from conda-forge, by running
conda install -c conda-forge cellfinder-coreWindows users can also use the command above to install cellfinder-core, however tensorflow (one of cellfinder-core's core dependencies) is not available so will not be included.
Consequentially, cellfinder-core will be usable - you will get PackageNotFound errors when attempting to import.
To rectify this, Windows users must manually install tensorflow (and ensure their Python interpreter can see this install) for cellfinder-core to work.
Please refer to the tensorflow install page for further guidance.
Whether tensorflow is installed before or after conda installing cellfinder-core shouldn't matter, so long as tensorflow is visible to the Python interpreter.
Before using cellfinder-core, it may be useful to take a look at the paper 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
brainglobe-utils 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 brainglobe_utils.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 brainglobe_utils.IO.cells import save_cells
save_cells(detected_cells, "/path/to/cells.xml")You can load these back with:
from brainglobe_utils.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](https://brainglobe. info/documentation/cellfinder/user-guide/napari-plugin/training-data-generation.html).
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 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
Contributions to cellfinder-core are more than welcome. Please see the developers guide.
If you find this plugin useful, and use it in your research, please cite the paper 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.