Usage¶
cellfinder -s signal_channel_images optional_signal_channel_images -b background_channel_images -o /path/to/output_directory -x 0.001 -y 0.001 -z 0.005
Arguments¶
Mandatory¶
-s
or--signal-planes-paths
Path to the directory of the signal files. Can also be a text file pointing to the files. There can be as many signal channels as you like, and each will be treated independently.b
or--signal-planes-path
Path to the directory of the background files. Can also be a text file pointing to the files. This background channel will be used for all signal channels.-o
or--output-dir
Output directory for all intermediate and final results
Either
-x
or--x-pixel-um
Pixel spacing of the data in the first dimension, specified in um.-y
or--y-pixel-um
Pixel spacing of the data in the second dimension, specified in um.-z
or--z-pixel-um
Pixel spacing of the data in the third dimension, specified in um.
Or
--metadata
Metadata file containing pixel sizes (any format supported by micrometa can be used). If both pixel sizes and metadata are provided, the command line arguments will take priority.
The following options can also be used:¶
Additional options
--register
Register the background channel to the Allen brain atlas--summarise
Generate summary csv files showing how many cells are in each brain area (will also run registration if not specified.--signal-channel-ids
Channel ID numbers, in the same order as--figures
Generate figures
Only run parts of cellfinder
If for some reason you don’t want some parts of cellfinder to run, you can use
the following options. If a part of the pipeline is required by another
part it will be run (i.e. --no-detection
won’t do anything unless
--no-classification
is also used). Cellfinder will attempt to work out
what parts of the pipeline have allready been run (in a given output
directory) and not run them again if appropriate.
--no-detection
Don’t run cell candidate detection--no-classification
Don’t run cell classification--no-standard_space
Dont convert cell positions to standard space. Otherwise will run automatically if registration and classification has run.
If you have channel numbers that you’d like to carry over into cellfinder
--signal-channel-ids
. Channel ID numbers, in the same order as ‘signal-planes-paths. Will default to ‘0, 1, 2’ etc, but maybe useful to specify.--background-channel-id
Channel ID number, corresponding to ‘background-planes-path’
Figures options
Figures cannot yet be customised much, but the current options are here:
--no-heatmap
Don’t generate a heatmap of cell locations--heatmap-bin
Heatmap bin size (mm of each edge of histogram cube)--heatmap-smoothing
Gaussian smoothing sigma, in mm.--no-outlines
Don’t generate outlines of segmentation regions (for overlay)--no-mask-figs
Don’t mask the figures (removing any areas outside the brain, from e.g. smoothing)
Performance/debugging
--debug
Increase verbosity of statements printed to console and save all intermediate files.--n-free-cpus
The number of CPU cores on the machine to leave unused by the program to spare resources.--max-ram
Maximum amount of RAM to use (in GB) - not currently fully implemented for all parts of cellfinder
Input/output options
Useful for testing or if you know your cells are only in a specific region
--start-plane
The first plane to process in the Z dimension--end-plane
The last plane to process in the Z dimension
Cell candidate detection
--save-planes
Whether to save the individual planes after processing and thresholding. Useful for debugging.--outlier-keep
Dont remove putative cells that fall outside initial clusters--artifact-keep
Save artifacts into the initial xml file--max-cluster-size
Largest putative cell cluster where splitting should be attempted--soma-diameter
The expected soma size in pixels in the x/y dimensions--ball-xy-size
The size in pixels of the ball used for the morphological filter in the x/y dimensions--ball-z-size
The size in pixels of the ball used for the morphological filter in the z dimension--ball-overlap-fraction
The fraction of the ball that has to cover thresholded pixels for the centre pixel to be considered a nucleus pixel
Cell candidate classification
--trained-model
To use your own network (not the one supplied with cellfinder) specify the model file.--model-weights
To use pretrained model weights. Ensure that this model matches the--network-depth
parameter.--batch-size
Batch size for classification. Can be adjusted depending on GPU memory
If the pixel sizes of the cubes used to train your network are different to that of the network supplied with cellfinder (0.001 x 0.001 x 0.005 mm), this can be set:
--x-pixel-network
--y-pixel-network
--z-pixel-network
Registration to atlas
--registration-config
To supply your own, custom registration configuration file.
If the supplied data does not match the NifTI standard orientation (origin is the most ventral, posterior, left voxel), then the atlas can be flipped to match the input data:
--flip-x
Flip the sample brain along the first dimension for atlas registration--flip-y
Flip the sample brain along the second dimension for atlas registration--flip-z
Flip the sample brain along the third dimension for atlas registration
Input data definitions
--orientation
The orientation of the sample braincoronal
,saggital
orhorizontal
--x-pixel-mm-network
The pixel size (in the first dimension) that the machine learning network was trained on. Set this to adjust the pixel sizes of the extracted cubes.--y-pixel-mm-network
The pixel size (in the second dimension) that the machine learning network was trained on. Set this to adjust the pixel sizes of the extracted cubes.
Standard space options
--transform-all
Transform all cell positions (including artifacts).
Atlas specification
When cellfinder runs, the appropriate machine learning models and
reference atlas will be downloaded (if not previously done so). If you would
like to download in advance to save time (or if you will not have an internet
connection) please use cellfinder_download
.
Currently, the only supported atlas is the Allen reference mouse
brain, originally from here.
The atlas will download into ~/.cellfinder/atlas
.
In the future, other atlases will be available, and you will be able to choose which is downloaded.
If you want to modify the cellfinder download, use:
--atlas-install-path
Supply a path to download the atlas elsewhere. This should also update the defaultregistration.conf.custom
file so that the correct atlas is sourced. Alternatively, use this command to tell cellfinder where an existing atlas is, to save it being downloaded twice. (Requires 20GB disk space)--atlas download path
The path to download the atlas into. (Requires 1.2GB disk space). Defaults to/tmp
.
Further help¶
All cellfinder options can be found by using the -h
flag
cellfinder -h
If you have any issues, common issues can be found here. If you’re still having issues, get in touch, or even better raise an issue on Github.