1. Introduction
This document describes the usage of CShaperApp. CShaperApp is built based on the CShaper published in Nature Communications, which adopts the deep learning to segment the C. elegans emebyro at single-cell elevel (Cao JF et al., Nat. Commun, 2020).
Briefly speaking, CShaperApp is composed of five functional sections, including Preprocess, Segmentation, Analysis, Result and Train. While the first four parts are designed to be excuted sequentially, the user can choose to train the model with Train module. In order to use this software efficiently, especially for functions Segmentation and Train, GPU acceleration is preferred. However, all components has been tested successfully on basic desktop (RAM=16G, no GPU).
The user can download the installer of CShaperApp from this link. The pretrained model and name dictionary can be downloaded as Resource file. CShaperApp was tested on Windows 7 and Windows 10 (64 bit). For the user's reference, we list the time that CShaperApp takes to process the example dataset 181210plc1p1.
| Platform | Performance | Preprocess | Segmentation | Analysis |
|---|---|---|---|---|
| Windows 10 | 16G RAM, 4 cores, no GPU | 45 s | 33 min 32 s | 30 s |
| Windows 10 | 64G RAM, 48 cores, GPU 2080Ti | 6 s | 3 min 7 s | 7 s |
With the help of microscopy, fluorescent signals of nucleus and membrane are collected through two channels respectly. These images are saved slice by slice. Preprocess is used to compose these slices into a volume according to the user's config. Subsequently, Segmentation is used to segment these volumetric images. Analysis is designed to collect the biological information, such as volume and surface, from the segmentation result. Finally, Result can be used to inspect the segmentation results interactively. For the large potential difference between different datasets, Train can be optionally used to retintrain the model.
The user can get familiar with the usage of CShaperApp by following the steps in the figure as follows.
The folders which are required or generated by CShaperApp are listed here. To get a perceptual view on the structure of the workplace, the user can refer to our example [link], where the example dataset can be also found.
# 181210plc1p1 is the name of an embryo sample, which can be configured.
Raw Folder/: raw image folder
|--181210plc1p1/: embryo name
|--aceNuc/: nucleus lineage file from StarryNite and AceTree
|--tif/: raw nucleus image
|--tifR/: raw membrane image
Project Folder/: the target folder where all results will be saved
|--CellMembrane/: binary membrane surface
|--CellMembranePostseg/: segmentation results
|--181210plc1p1/: cell segmentations without cell labels
|--181210plc1p2LabelUnified/: cell segmentations whose labels can be queried
|--NucleusLoc/: nucleus location information
|--RawStack/: stacked membrane and nucleus images
|--StatShape/: statistical results from the segmentations
|--181210plc1/: embryo name
|--181210plc1_contact.csv: cell-cell contact surface
|--181210plc1_surface.csv: cell surface area
|--181210plc1_volume.csv: cell volume
|--TemCellGraph/: Temporary results
Resource/: resources that are required by CShaperApp
|--number_dictionary.csv: pairwise cell name and digital label in the segmentation
|--TrainedModel/: pretrained model for the deep learning frameworkIn these files, Raw Folder is the data that the user needs to process. All data generated by CShaperApp directly or indirectly will be saved to Project Folder. Resource includes the trained model that can downloaded through the preivous link.
The user needs to set meta-information about the image data. The meaning of each parameters is listed as follows (based on the example data).
Parameter list
| Name | Value | Example |
|---|---|---|
| Raw Folder | name of raw data folder | root/MembRaw |
| Embryo Name | Name of the embryo | 181210plc1p1 |
| X-Y Resolution | Intra-slice resolution (μm) | 0.09 |
| Z Resolution | Inter-slice resolution | 0.42 |
| Reduce Ratio | The scale of image to be reduced. Setting this value to be smaller will reduce the time the Segmentation takes, but the resolution will be reduced | 0.3 |
| Slice Num | The number of slices at each time point | 68 |
| Max Time | The largest time points to be processed (start from t=1) | 100 |
| Lineage File | The nucleus lineage file (from StarryNite and AceTree) | root/MembRaw/181210plc1p1/aceNuc/CD181210plc1p1.csv |
| Number Dictionary | The dictionary used for finding out the cell name according to the segmentation results because only integers as opposed to strings are saved. | root/Resource/number_dictionary.csv |
Membrane or nucleus slices at each time point are composed together as volumetric stacks. These volumetric stacks are saved as *.nii.gz files under folder Project Folder/MembRaw, which can be loaded by itk-SNAP.
At this stage, some parameters are assumed to be the same as that of Preprocess. If not, the user can change the settings but please make sure the embryo to be segmented has been processed by the stage Preprocess.
Parameter list
| Name | Value | Example |
|---|---|---|
| Project Folder | Preprocess | Preprocess |
| Embryo Names | Preprocess | Preprocess |
| Max Time | Preprocess | Preprocess |
| Batch Size | The number of images to be computed in parallel. The value should be set based on your computer resources (i.e., GPU). | 1 |
| Use Lineage | Three cases: no lineage; after segmentation (used in CShaper, cell cavity can be detected); before segmentation (nuclei are used as seeds in watershed segmentation, so cell cavity cannot be detected) | After Lineage |
| Model File | The file of pretrained model | root/Resource/TrainedModel/DMapNet_pub_5000.ckpt |
Volumetric raw images are further segmented at single-cell level. Segmentations are saved at folder Project Folder/CellMembranePostseg/181210plc1p2. The user can visually inspect the segmentation performance by loading the raw image (from Preprocess) and the segmentation with itk-SNAP. Please note that at this stage, cells are not strictly lablled according to the name_dictionary.csv, which remains to be solved in Analysis.
Section Analysis will collect cell morphological information, including cell volume, cell surface area and cell-cell contact area. It also combines two daughter cells during the the division process in which case one cell includes two nuclei.
Parameter list
| Name | Value | Example |
|---|---|---|
| Slice Num | Preprocess | Preprocess |
| Number Dictionary | Preprocess | Preprocess |
| Raw Folder | Preprocess | Preprocess |
| Embryo Names | Preprocess | Preprocess |
| Project Folder | Preprocess | Preprocess |
| Lineage File | Preprocess | Preprocess |
The user can set all parameters in Preprocess, Segmentation and Anlysis once, and runs them together.
Morphological information are saved to StatShape. These results can be either viewed in section Result or processed for different needs.
This part provides a window for the user to view both the segmentation results and the collected information. All tables are exportable for further studies. In 3D component, the user can inspect the segmentation results at each time point interactively. Please note that because all segmentations are preloaded here, this function might be computationally consuming when there are too many time points. Besides, CShaperApp concentrates on segmenting the embryo data, so we recommend the itk-SNAP to the user for user-friendly interface to view the results.
In order to deliver reasonable results on your own dataset, retraining the model is recommended, especially when the meta-information varies a lot with the dataset used by CShaper. The model can be easily trained with the user interface Train.
Parameter list
| Name | Value | Example |
|---|---|---|
| Data Folder | The root folder of training dataset | root/MembraneTrain |
| Data Names | The datasets used for training | 181210plc1p1; 181210plc1p2 |
| Batch Size | The batch size used for training | 2 |
| Model Name | The name of model to be saved | CShaper |
| Save Folder | The folder of model to be saved | Resource/TrainedModel |
The trained model will be saved as three files (*.index, *.meta, *001) under Save Folder. At the Segmentation stage, any one of them can be filled into Model File.
Demo of CShaperApp
For user whoe wants to extend the usage of CShaperApp, the development environment can be constructed by following:
# create environment
conda create -n cshaptertf python=3.9.13
pip install -r requirements.txt
# Packkage the library
pyinstaller CShaperApp_MacOS.specThe packaged software can be found at dist/CShaperApp.
Please contact Jianfeng Cao at jfcao3-c(at)my.cityu.edu.hk or create an issue under this source code repository.
1). Due to the considerable computation resource required on 3D rendering in function `Result/3D View`, it's highly recommended to run this function only when the number of time point is small, otherwise the software may be nonresponsive for the lack of memory;
2). If retraining the model is needed, the folder structure should strictly follow that referred in Folder Structure.
The license can be found here.