Package: cellfinder-core
This package has moved!cellfinder-corehas merged with it's napari plugin and is now available as asingle package calledcellfinder.
We recommend you uninstallcellfinder-coreand instead use the functionality provided in thecellfinderpackage.These changes are part of ourwider restructuringof the BrainGlobe suite of tools and analysis pipelines, which you cankeep up to date with on our blog.cellfinder-coreStandalone cellfinder cell detection algorithmThis package implements the cell detection algorithm fromTyson, Rousseau & Niedworok et al. (2021)without any dependency on data type (i.e. it can be used outside of
whole-brain microscopy).cellfinder-coresupports thecellfindersoftware for
whole-brain microscopy analysis, and the algorithm can also be implemented innapariusing thecellfinder napari plugin.InstructionsInstallationcellfinder-coresupports 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 installcellfinder-corewith:pipinstallcellfinder-coreOnce you haveinstalled napari.
You can install napari either through the napari plugin installation tool, or
directly from PyPI with:pipinstallcellfinder-napariN.B. To speed up cellfinder, you need CUDA & cuDNN installed. Instructionshere.Conda InstallLinux and MacOS users can also installcellfinder-corefromconda-forge, by runningcondainstall-cconda-forgecellfinder-coreWindows users can also use the command above to installcellfinder-core, howevertensorflow(one ofcellfinder-core's core dependencies) is not available so will not be included.
Consequentially,cellfinder-corewill be usable - you will getPackageNotFounderrors when attempting to import.
To rectify this, Windows usersmustmanually installtensorflow(and ensure their Python interpreter can see this install) forcellfinder-coreto work.
Please refer to thetensorflowinstall pagefor further guidance.
Whethertensorflowis installed before or afterconda installingcellfinder-coreshouldn't matter, so long astensorflowis visible to the Python interpreter.UsageBefore using cellfinder-core, it may be useful to take a look at thepaperwhich
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 thecellfinder napari pluginso you can adjust the parameters in a GUI.To run the full pipeline (cell candidate detection and classification)fromcellfinder_core.mainimportmainascellfinder_runimporttifffilesignal_array=tifffile.imread("/path/to/signal_image.tif")background_array=tifffile.imread("/path/to/background_image.tif")voxel_sizes=[5,2,2]# in micronsdetected_cells=cellfinder_run(signal_array,background_array,voxel_sizes)The output is a list ofbrainglobe-utils Cell objectsEachCellhas 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):frombrainglobe_utils.cells.cellsimportCellprint(Cell.CELL)# 2print(Cell.NO_CELL)# 1Saving the resultsIf you want to save the detected cells for use in other BrainGlobe software (e.g. thecellfinder napari plugin),
you can save in the cellfinder XML standard:frombrainglobe_utils.IO.cellsimportsave_cellssave_cells(detected_cells,"/path/to/cells.xml")You can load these back with:frombrainglobe_utils.IO.cellsimportget_cellscells=get_cells("/path/to/cells.xml")Using dask for lazy loadingcellfinder-coresupports most array-like objects. UsingDask arraysallows for lazy
loading of data, allowing large (e.g. TB) datasets to be processed.cellfinder-corecomes with a function
(based onnapari-ndtiffs) to
load a series of image files (e.g. a directory of 2D tiff files) as a Dask
array.cellfinder-corecan then be used in the same way as with a numpy array.fromcellfinder_core.mainimportmainascellfinder_runfromcellfinder_core.tools.IOimportread_with_dasksignal_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 micronsdetected_cells=cellfinder_run(signal_array,background_array,voxel_sizes)Running the cell candidate detection and classification separately.importtifffilefrompathlibimportPathfromcellfinder_core.detectimportdetectfromcellfinder_core.classifyimportclassifyfromcellfinder_core.tools.prepimportprep_classificationsignal_array=tifffile.imread("/path/to/signal_image.tif")background_array=tifffile.imread("/path/to/background_image.tif")voxel_sizes=[5,2,2]# in micronshome=Path.home()install_path=home/".cellfinder"# defaultstart_plane=0end_plane=-1trained_model=Nonemodel_weights=Nonemodel="resnet50_tv"batch_size=32n_free_cpus=2network_voxel_sizes=[5,1,1]soma_diameter=16ball_xy_size=6ball_z_size=15ball_overlap_fraction=0.6log_sigma_size=0.2n_sds_above_mean_thresh=10soma_spread_factor=1.4max_cluster_size=100000cube_width=50cube_height=50cube_depth=20network_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,)iflen(cell_candidates)>0:# Don't run if there's nothing to classifyclassified_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 networkThe 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-corecomes with a 50-layer ResNet trained on ~100,000 data points
from serial two-photon microscopy images of mouse brains
(availablehere).Training the network is likely simpler using thecommand-line interfaceor theNapari plugin,
but it is possible through the Python API.frompathlibimportPathfromcellfinder_core.train.train_ymlimportrunasrun_training# list of training yml filesyaml_files=[Path("/path/to/training_yml.yml)]# where to save the outputoutput_directory=Path("/path/to/saved_training_data")home=Path.home()install_path=home/".cellfinder"# defaultrun_training(output_directory,yaml_files,install_path=install_path,learning_rate=0.0001,continue_training=True,# by default use supplied modeltest_fraction=0.1,batch_size=32,save_progress=True,epochs=10,)More infoMore documentation about cellfinder and other BrainGlobe tools can be
foundhere.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 touchon the forumor byraising an issue.IllustrationIntroductioncellfinder 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 cellsCell candidate detectionClassical image analysis (e.g. filters, thresholding) is used to find
cell-like objects (with false positives):Candidate cells (including many artefacts)Cell candidate classificationA deep-learning network (ResNet) is used to classify cell candidates as true
cells or artefacts:Cassified cell candidates. Yellow - cells, Blue - artefactsContributingContributions to cellfinder-core are more than welcome. Please see thedevelopers guide.Citing cellfinderIf 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), e1009074https://doi.org/10.1371/journal.pcbi.1009074If you use this, or any other tools in the brainglobe suite, pleaselet us know, and
we'd be happy to promote your paper/talk etc.