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.7rc0-cp39-cp39-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | d4426a87c1751a3561dee9dc43dfe996b0aa9e9a4b3c1a3dc4af6f4e025d9f2b |
|
MD5 | 0347c53c58ae5d68b77bbd458445e769 |
|
BLAKE2b-256 | 17698a7ad000a6aac374f22449e432f821f84f1a616ea334b9230433dcae9aba |
Hashes for cellfinder_core-0.2.7rc0-cp39-cp39-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bf52645fdebe261bd30b9aabd90c918e291adfbb4791f7ec70c6a466c1a70d68 |
|
MD5 | 0b0073777dfdb3d3885910ac4cb993ab |
|
BLAKE2b-256 | ca3e6efbede3540e7fe52643974f112ae1358d1bfbc92a54f2d5a6b43bd216f4 |
Hashes for cellfinder_core-0.2.7rc0-cp39-cp39-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a5fee8b95fd3334210f036817b0d9fec63f4ced0d42fcd599e3bd7ad0a752b94 |
|
MD5 | 68dad356d23e6d9fc2e548bee6cae50f |
|
BLAKE2b-256 | 7e0be885ff26c9de208fe5828e4c413b7ac8e65d65f2b512c069e7304194d754 |
Hashes for cellfinder_core-0.2.7rc0-cp38-cp38-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3e8134c6ca24716d1716a5e704f406b92b03192b4bcc09a15677f03a643a0254 |
|
MD5 | 187ff5d96862490f83c52f9618d2bac4 |
|
BLAKE2b-256 | 8f650447d0e2198052dcb3f9afae90cd21746356482b553bba0afd8096d69c28 |
Hashes for cellfinder_core-0.2.7rc0-cp38-cp38-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | bccb2d3b4bd367665172727f5bda0236c044498ffd3fee03d52eb7c5fe201dcc |
|
MD5 | 2e620ca7b7f0f14966358e014c8eac64 |
|
BLAKE2b-256 | 2c53eb8e4847422a202d1d1a10052592809564e0b7b7d3fef7ae11aa4089f6ed |
Hashes for cellfinder_core-0.2.7rc0-cp38-cp38-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 8458c1f51dde37dc8724739d3b82e214eaace5044e66e8873810a38d69a121c7 |
|
MD5 | 7758fe93fbd57a5e1f4744837d414a90 |
|
BLAKE2b-256 | 030a72e66e0c3e6ac68e166ec9e7107dd0a0025796d412557cebaa6906b9ecef |
Hashes for cellfinder_core-0.2.7rc0-cp37-cp37m-win_amd64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 7a8da1bf61b5fb855eb1f6647211c55979ad1c36273db917169b895f5020f0ac |
|
MD5 | d4ebc385e6df79f49ed670da404763ff |
|
BLAKE2b-256 | 9ec3670cfb3f3968658b13a9af4b9f2fe70de2754493d4bdb59a5f43b53025da |
Hashes for cellfinder_core-0.2.7rc0-cp37-cp37m-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 3ef5fc9e41f72d09dafcd47f0c71d1b9788864f899bdfd5619bcb86055927038 |
|
MD5 | 67018baac04336b3841f4bfd5f21396a |
|
BLAKE2b-256 | 36577fe9bdbfa11d88010b1bf28f2bd6f3fb08f8f99be3bf088f0fe6769b0df2 |
Hashes for cellfinder_core-0.2.7rc0-cp37-cp37m-macosx_10_14_x86_64.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9a0f162cce6d0aff46dc6d5a9e5a24a3920381b4e236c9efb53e396f2bddf9e0 |
|
MD5 | 570de16a0926a3db0fdbf23b78bb41a0 |
|
BLAKE2b-256 | 97a78ac3d405e75e4196dd9033400d23d99aa1df685f220d7540c98994bab883 |