Package: cellshape
3D single-cell shape analysis of cancer cells using geometric deep learningThis is a Python package for 3D cell shape features and classes using deep learning. Please refer to our preprinthere.cellshape is the main package which imports from sub-packages:cellshape-helper: Facilitates point cloud generation from 3D binary masks.cellshape-cloud: Implementations of graph-based autoencoders for shape representation learning on point cloud input data.cellshape-voxel: Implementations of 3D convolutional autoencoders for shape representation learning on voxel input data.cellshape-cluster: Implementation of deep embedded clustering to add to autoencoder models.Installation and requirementsDependenciesThe software requires Python 3.7 or greater. The following are package dependencies that are installed automatically when cellshape is installed:PyTorch,pyntcloud,numpy,scikit-learn,tensorboard,tqdm(The full list is shown in thesetup.pyfile). This repo makes extensive use ofcellshape-cloud,cellshape-cluster,cellshape-helper, andcellshape-voxel. To reproduce our results in our paper, onlycellshape-cloud,cellshape-clusterare needed.To installWe recommend creating a new conda environment. In the terminal, run:condacreate--namecellshape-envpython=3.8-y
condaactivatecellshape-env
pipinstall--upgradepipInstall cellshape from pip. In the same terminal, run:pipinstallcellshapeThis should take ~5mins or less.Hardware requirementsWe have tested this software on an Ubuntu 20.04LTS and 18.04LTS with 128Gb RAM and NVIDIA Quadro RTX 6000 GPU.Data availability and structureData availabilityDatasets to reproduce our results in our paper are availablehere.SamplePointCloudData.zip contains a sample dataset of a point cloud of cells in order to test our code.FullData.zip contains 3 plates of point cloud representations of cells for several treatments. This data can be used to reproduce our results.Output.zip contains trained model weights and deep learning cell geometric features extracted using these trained models.BinaryCellMasks.zip contains a sample set of binary masks of cells which can be used as input tocellshape-helperto test our point cloud generation code.Data structureWe suggest testing our code on the data contained inSamplePointCloudData.zip. This data is structured in the following way:cellshapeSamplePointCloudDatset/
    small_data.csv
    Plate1/
        stacked_pointcloud/
            Binimetinib/
                0010_0120_accelerator_20210315_bakal01_erk_main_21-03-15_12-37-27.ply
                ...
            Blebbistatin/
            ...
    Plate2/
        stacked_pointcloud/
    Plate3/
        stacked_pointcloud/This data structure is only necessary if wanting to use our data. If you would like to use your own dataset, you may structure it in any way as long as the extension of the point clouds are.ply. If using your own data structure, please define the parameter--dataset_typeas"Other".UsageThe following steps assume that one already has point cloud representations of cells or nuclei. If you need to generate point clouds from 3D binary masks, please go tocellshape-helper.Downloading the datasetWe suggest testing our code on the data contained inSamplePointCloudData.zip. Please download the data and unzip the contents into a directory of your choice. We recommend doing this in your~Documents/folder. This is used as parameters in the steps below, so please remember where you download the data to. Downloading and unzipping the data can be done in the terminal. You might need to first installwgetandunzipwithapt-get(e.g.apt-get install wget).Download the data into the~/Documents/folder with wgetcd~/Documents
wgethttps://sandbox.zenodo.org/record/1080300/files/SamplePointCloudDataset.zipUnzip the data with unzip:unzipSamplePointCloudDataset.zipThis will create a directory calledcellshapeSamplePointCloudDatsetunder your~Documents/folder, i.e./home/USER/Documents/cellshapeSamplePointCloudDatset/(USERwill be different for you).TrainingThe training procedure follows two steps:Training the dynamic graph convolutional foldingnet (DFN) autoencoder to automatically learn shape features.Adding the clustering layer to refine shape features and learn shape classes simultaneously.Inference can be done after each step.Our training functions are run through a command line interface with the commandcellshape-train.
For help on all command line options, run the following in the terminal:cellshape-train-h1. Train DFN autoencoderThe first step trains the autoencoder without the additional clustering layer. Run the following in the terminal. Remember to change the--cloud_dataset_path,--dataframe_path, and--output_dirparmaeters to be specific to your directories, if you have saved the data somewhere else. To test the code, we train for 5 epochs. First make sure you're in the directory where you downloaded the data to. If this is your `~/Documents/ folder, go into this:cd~/DocumentsThen run the following:cellshape-train\--model_type"cloud"\--pretrain"True"\--train_type"pretrain"\--cloud_dataset_path"./cellshapeSamplePointCloudDataset/"\--dataset_type"SingleCell"\--dataframe_path"./cellshapeSamplePointCloudDataset/small_data.csv"\--output_dir"./cellshapeOutput/"\--num_epochs_autoencoder5\--encoder_type"dgcnn"\--decoder_type"foldingnetbasic"\--num_features128\This step will create an output directory/home/USER/Documents/cellshapeOutput/with the subfolders:nets,reports, andrunswhich contain the model weights, logged outputs, and tensorboard runs, respectively, for each experiment. Each experiment is named with the following convention{encoder_type}_{decoder_type}_{num_features}_{train_type}_{xxx}, where {xxx} is a counter. For example, if this was the first experiment you have run, the trained model weights will be saved to:/home/USER/Documents/cellshapeOutput/nets/dgcnn_foldingnetbasic_128_pretrained_001.pt. This path will be used in the next step for the--pretrained-pathparameter.2. Add clustering layer to refine shape features and learn shape classes simultaneouslyThe next step is to add the clustering layer to refine the model weights. As before, run the following in the terminal. Remember to change the--cloud_dataset_path,--dataframe_path,--output_dir, and--pretrained-pathparmaeters to be specific to your directories. If you have followed the previous steps, then you will still be in the~Documents/path. In the same terminal, run:cellshape-train\--model_type"cloud"\--train_type"DEC"\--pretrainFalse\--cloud_dataset_path"./cellshapeSamplePointCloudDataset/"\--dataset_type"SingleCell"\--dataframe_path"./cellshapeSamplePointCloudDataset/small_data.csv"\--output_dir"./cellshapeOutput/"\--num_features128\--num_clusters5\--pretrained_path"./cellshapeOutput/nets/dgcnn_foldingnetbasic_128_pretrained_001.pt"\To monitor the training usingTensorboard, in a new terminal run:pipinstalltensorboardcd~/Documents
tensorboard--logdir"./cellshapeOutput/runs/"Alternatively, the training steps can be run sequentially through one command lineThis would be to state that you would like topretrainand that you want to trainDEC.cellshape-train\--model_type"cloud"\--train_type"DEC"\--pretrainTrue\--cloud_dataset_path"./cellshapeSamplePointCloudDataset/"\--dataset_type"SingleCell"\--dataframe_path"./cellshapeSamplePointCloudDataset/small_data.csv"\--output_dir"./cellshapeOutput/"\--num_features128\--num_clusters5\InferenceExample inference notebooks can be found in thedocs/notebooks/folder.IssuesIf you have any problems, please raise an issuehereCitation@article{DeVries2022single,author={Matt De Vries and Lucas Dent and Nathan Curry and Leo Rowe-Brown and Vicky Bousgouni and Adam Tyson and Christopher Dunsby and Chris Bakal},title={3D single-cell shape analysis using geometric deep learning},elocation-id={2022.06.17.496550},year={2023},doi={10.1101/2022.06.17.496550},publisher={Cold Spring Harbor Laboratory},URL={https://www.biorxiv.org/content/early/2023/03/27/2022.06.17.496550},eprint={https://www.biorxiv.org/content/early/2023/03/27/2022.06.17.496550.full.pdf},journal={bioRxiv}}References[1] An Tao, 'Unsupervised Point Cloud Reconstruction for Classific Feature Learning',GitHub Repo, 2020