Package: hcat
HCAT - Hair Cell Analysis ToolboxHcat is a suite of machine learning enabled algorithms for performing common image analyses in the hearing field.
At present, it performs one fully automated analyses: (1) 2D hair cell detectionHCAT is highly accurate for most cochlear tissue, very fast, and easy to integrate into existing workflows!
For full documentation, please visit:hcat.readthedocs.ioQuickstart GuideInstallationInstallAnacondaPerform the installation by copying and pasting the following comands into yourAnaconda Prompt(Windows) orTerminal(Max/Linux)Create a new anaconda environment:conda create -yn hcat python=3.9Activate the anaconda environment:conda activate hcatWARNING: You will need to avtivate your conda environment every time you restart your prompt!Install pytorch for CPU ONLY:conda install pytorch torchvision torchaudio cpuonly -c pytorchInstall hcat and dependencies:pip install hcat --upgradeRun hcat:hcatNOTE: It is strongly recommended you follow the installation guide for correct installation!NOTE: Follow the detailed installation guide for instructions on how to enable GPU accelerationDetection Gui:Run in terminal:hcatCLI Hair Cell Detection Analysis:Run in terminal:hcat detect "path/to/file.tif"RequirementsThe following requirements are necessary to runhcat.Pytorch 1.12.0Torchvision 0.13.0python 3.9Detailed InstallationTo install hcat, ensure you thatPython Version 3.9as well as all dependencies properly installed. It is recommended
to use theAnacondadistribution of python with a dedicated environment. To do a reccomendned install,
please use the following steps.Download the Anaconda distribution of python from the following link:Anaconda. This will install
python for you! There isno needto install python from an additional source.On Windows, launch theAnaconda Promptapplication. On Mac or Linux launch a newterminal. If installed correctly you
should see(base)to the left of your terminal input.This is your anacondaenvironemnt.To avoid dependency issues, we will create a new environment to install hcat. This acts like an isolated sandbox where
we can install specificversionsnecessary software. To do this, in the prompt, typeconda create -n hcat python=3.9and typeywhen asked.This creates an environment to install our software. We must now activate this environment to
access our isolated sandbox and installhcat.To activate our environment, type in the terminalconda activate hcat. Notice how(base)has been replaced with(hcat).To run hcat we first need to installpytorch, a deep learning library. To do this, follow the instructions on thePytorchwebsite for your particular system. It is recommended to use these install settings:SettingSelectionPyTorch BuildStable (1.12.0)Your OSLinux/Mac/WindowsPackageCondaLanguagePythonCompute PlatformCUDA 11.3 (If you have an Nvidia GPU, otherwise use CPU)This will create a command to run in the prompt. With these settings, this might look like:conda install pytorch torchvision torchaudio cudatoolkit=11.3 -c pytorch.
This may take a while.NOTE: Installing pytorch with pip can cause issues in some systems. To ensure GPU capabilities and
prevent errors, please install with the package managerConda.Once we've installed pytorch, we can use the command line to installhcat. To do this, typepip install hcat --upgrade. This command will install all
remaining libraries necessary to run the software into our protected sandbox environment. This means that the software can only be
called from the hcat environment.If the installation finishes with no errors, we can runhcatby simply typinghcatin the prompt!WARNING: If you restart your prompt or terminal, you will need to reactivate the environment to launch the program.Detection GuiWe provide an easy to use gui to the performance of hcat's detection capabilites on your own data. To launch the gui and
analyze your own data, please follow the following steps.Open a terminal (Mac/Linux) or Anaconda Prompt (Windows) and type:conda activate hcatVerify the environment is activated by(hcat)being displayed to the left of the input promptTypehcatin the prompt to launch the guiA gui should launch.On the top left, click browse to select a file, then load to load the file into the software. The image should be displayed on the screen.Enter the diameter of the cell in pixels. Best measured in ImageJ. Click 'OK'De-select the channels not representing the cell cytosol and hair bundle.Adjust the brightness and contrast of the image to minimize background fluorescence.Press 'Run Analysis'. A pretrained model will download off the internet and loaded into the software. This may take a few minutes and should only happen once.Predictions should appear on screen. Fine tune the predictions by adjusting the cell probability rejection threshold and prediction box overlap threshold.Press 'Save' to save the analysis to a CSV and JPG. This will create two new files in the same location as your image called:<filename>_analysis.csvand<filename>_analysis.jpgComand Line UsageThe comand line tool has two entry points:detect, andsegment (Beta).detecttakes in a 2D, multichannel maximum projection of a cochlea and predicts inner and outer hair cell detection predictionssegment (Beta)takes in a 3D, multichannel volume of cochlear hair cells and generates unique segmentation masks which which may be usedDetecthcat detectis the entrypoint for the detection of hair cells from max projection tilescans of a cochlea.
Hair cell detection is one of the most basic tasks in cochlear image analysis;
useful for evaluating cochlear trauma, aging, ototoxicity, and noise exposure. To evaluate an image, run the following in
the command line:hcat detect [INPUT] [OPTIONS]INPUTThe program accepts confocal max-projected z-stacks of cochlear hair cells stained with a hair cell specific cytosol stain
(usually anti-Myo7a)anda stereocilia stain (ESPN, phalloidin, etc...). The input image must only have these 2 channels. This may be easiest achieved with the Fiji application. The best performing images will have
high signal-to-noise ratio and low background staining.OPTIONS--cell_detection_threshold        (float) Rejection for objects with mean cytosolic intensity below threshold
--curve_path                      (str) Path to collection of points for curve estimation
--dtype                           (str) Data type of input image: (uint8 or uint16)
--save_fig                        (flag) Render diagnostic figure containing cell detection information
--save_xml                        (flag) Save detections as xml format compatable with labelImg software
--pixel_size                      (int) X/Y pixel size in nm
--cell_diameter                   (int) Rough diameter of hair cell in pixelsOUTPUTThe program will save two files with the same name and in the same location as the original file:filename.csvandfilename.cochlea.filename.csvcontains human-readable data on each hair cell segmented in the original image.filename.cochleais a dataclass of the analysis which is accessible via the python programing language
and contains a compressed tensor array of the predicted segmentation mask.To accessfilename.cochelain a python script:importtorchfromhcat.lib.cellimportCellfromtypingimportList# Detected cells are stored as "Cell" objectscochlea=torch.load('filename.cochlea')cells:List[Cell]=cochlea.cells# To access each cell:forcellincells:print(cell.loc,cell.frequency)#location (x, y, z); frequency (Hz)Please visit the official documentation for more details!Common IssuesThe program doesn't predict anything: This is most likely a channel issue. The machine learning backbones to each
model is not only channel specific, but also relies onspecific channel ordering. Check the--channelflag is set
properly forhcat segment. Forhcat detectcheck that the order of your channels is correct (cytosol then hair bundle).The program still doesn't show anything: If it is not the channel, then it is likely a datatype issue. Ensure you are
passing in an image of dtypeuint8oruint16. This can be double checked in thefijiapplication by clicking theImagedropdown then clickingtype, it should show either 8-bit or 16-bit.I cannot find the output: The program saves the output of each analysis as a CSV file with the same name
in the same location as the original file! Beware, subsequent excecutions of this program will overwrite previous analysis files.