Home

Awesome

This package has moved!

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.

Python Version PyPI Downloads Wheel Development Status Tests codecov Code style: black Imports: isort pre-commit Contributions Twitter

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

Conda Install

Linux and MacOS users can also install cellfinder-core from conda-forge, by running

conda install -c conda-forge cellfinder-core

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

Usage

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.

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 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: 2

Cell 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)
# 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 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")

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](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 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 on the forum or by raising an issue.

Illustration

Introduction

cellfinder takes a stitched, but otherwise raw dataset with at least two channels:

raw 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):

raw Candidate cells (including many artefacts)

Cell candidate classification

A deep-learning network (ResNet) is used to classify cell candidates as true cells or artefacts:

raw Cassified cell candidates. Yellow - cells, Blue - artefacts

Contributing

Contributions to cellfinder-core are more than welcome. Please see the developers guide.

Citing cellfinder

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.