{"id":13716123,"url":"https://github.com/Sentinal4D/cellshape","last_synced_at":"2025-05-07T05:32:22.274Z","repository":{"id":37448350,"uuid":"505812768","full_name":"Sentinal4D/cellshape","owner":"Sentinal4D","description":"3D shape analysis using deep learning","archived":false,"fork":false,"pushed_at":"2023-10-19T11:21:54.000Z","size":5762,"stargazers_count":24,"open_issues_count":5,"forks_count":6,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-12T00:44:45.249Z","etag":null,"topics":["cancer-biology","cell-biology","deep-learning","geometric-deep-learning"],"latest_commit_sha":null,"homepage":"https://www.biorxiv.org/content/10.1101/2022.06.17.496550v2","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Sentinal4D.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":"CITATION.cff","codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-21T11:25:12.000Z","updated_at":"2025-03-21T15:15:29.000Z","dependencies_parsed_at":"2024-01-05T23:43:54.205Z","dependency_job_id":null,"html_url":"https://github.com/Sentinal4D/cellshape","commit_stats":null,"previous_names":[],"tags_count":50,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sentinal4D%2Fcellshape","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sentinal4D%2Fcellshape/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sentinal4D%2Fcellshape/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Sentinal4D%2Fcellshape/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Sentinal4D","download_url":"https://codeload.github.com/Sentinal4D/cellshape/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252823143,"owners_count":21809701,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cancer-biology","cell-biology","deep-learning","geometric-deep-learning"],"created_at":"2024-08-03T00:01:07.281Z","updated_at":"2025-05-07T05:32:18.757Z","avatar_url":"https://github.com/Sentinal4D.png","language":"Python","funding_links":[],"categories":["Image processing and segmentation"],"sub_categories":[],"readme":"[![Project Status: Active – The project has reached a stable, usable\nstate and is being actively\ndeveloped.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)\n[![Python Version](https://img.shields.io/pypi/pyversions/cellshape.svg)](https://pypi.org/project/cellshape)\n[![PyPI](https://img.shields.io/pypi/v/cellshape.svg)](https://pypi.org/project/cellshape)\n[![Downloads](https://pepy.tech/badge/cellshape)](https://pepy.tech/project/cellshape)\n[![Wheel](https://img.shields.io/pypi/wheel/cellshape.svg)](https://pypi.org/project/cellshape)\n[![Development Status](https://img.shields.io/pypi/status/cellshape.svg)](https://github.com/Sentinal4D/cellshape)\n[![Tests](https://img.shields.io/github/workflow/status/Sentinal4D/cellshape/tests)](\n    https://github.com/Sentinal4D/cellshape/actions)\n[![Coverage Status](https://coveralls.io/repos/github/Sentinal4D/cellshape/badge.svg?branch=main)](https://coveralls.io/github/Sentinal4D/cellshape?branch=main)\n[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n\n\u003cimg src=\"https://github.com/Sentinal4D/cellshape/blob/main/img/cellshape.png\" \n     alt=\"Cellshape logo by Matt De Vries\"\u003e\n\n# 3D single-cell shape analysis of cancer cells using geometric deep learning\n\n\nThis is a Python package for 3D cell shape features and classes using deep learning. Please refer to our preprint [here](https://www.biorxiv.org/content/10.1101/2022.06.17.496550v1).\n\ncellshape is the main package which imports from sub-packages:\n- [cellshape-helper](https://github.com/Sentinal4D/cellshape-helper): Facilitates point cloud generation from 3D binary masks.\n- [cellshape-cloud](https://github.com/Sentinal4D/cellshape-cloud): Implementations of graph-based autoencoders for shape representation learning on point cloud input data.\n- [cellshape-voxel](https://github.com/Sentinal4D/cellshape-voxel): Implementations of 3D convolutional autoencoders for shape representation learning on voxel input data.\n- [cellshape-cluster](https://github.com/Sentinal4D/cellshape-cluster): Implementation of deep embedded clustering to add to autoencoder models.\n\n## Installation and requirements\n### Dependencies\nThe software requires Python 3.7 or greater. The following are package dependencies that are installed automatically when cellshape is installed: [`PyTorch`](https://pytorch.org/), [`pyntcloud`](https://github.com/daavoo/pyntcloud), [`numpy`](https://numpy.org/), [`scikit-learn`](https://scikit-learn.org/stable/), `tensorboard`, [`tqdm`](https://github.com/tqdm/tqdm) (The full list is shown in the [setup.py](https://github.com/Sentinal4D/cellshape/blob/main/setup.py) file). This repo makes extensive use of [`cellshape-cloud`](https://github.com/Sentinal4D/cellshape-cloud), [`cellshape-cluster`](https://github.com/Sentinal4D/cellshape-cluster), [`cellshape-helper`](https://github.com/Sentinal4D/cellshape-helper), and [`cellshape-voxel`](https://github.com/Sentinal4D/cellshape-voxel). To reproduce our results in our paper, only [`cellshape-cloud`](https://github.com/Sentinal4D/cellshape-cloud), [`cellshape-cluster`](https://github.com/Sentinal4D/cellshape-cluster) are needed.\n\n### To install\n1. We recommend creating a new conda environment. In the terminal, run:\n```bash \nconda create --name cellshape-env python=3.8 -y\nconda activate cellshape-env\npip install --upgrade pip\n```\n2. Install cellshape from pip. In the same terminal, run:\n```bash\npip install cellshape\n```\nThis should take ~5mins or less.\n\n### Hardware requirements\nWe have tested this software on an Ubuntu 20.04LTS and 18.04LTS with 128Gb RAM and NVIDIA Quadro RTX 6000 GPU.\n\n## Data availability and structure\n### Data availability\nUpdate (19/10/2023): Our sample data was originally published on Zenodo Sandbox, however, there are currently issues with this website and the link to the data is broken. We are working to put the data on a public data store and will update this page when this is done.\n\nOld:\nDatasets to reproduce our results in our paper are available [here](https://sandbox.zenodo.org/record/1080300#.YsX7f3XMIaz). \n- SamplePointCloudData.zip contains a sample dataset of a point cloud of cells in order to test our code.\n- FullData.zip contains 3 plates of point cloud representations of cells for several treatments. This data can be used to reproduce our results.\n- Output.zip contains trained model weights and deep learning cell geometric features extracted using these trained models.\n- BinaryCellMasks.zip contains a sample set of binary masks of cells which can be used as input to [`cellshape-helper`](https://github.com/Sentinal4D/cellshape-helper) to test our point cloud generation code. \n\n### Data structure\nWe suggest testing our code on the data contained in `SamplePointCloudData.zip`. This data is structured in the following way:\n\n```\ncellshapeSamplePointCloudDatset/\n    small_data.csv\n    Plate1/\n        stacked_pointcloud/\n            Binimetinib/\n                0010_0120_accelerator_20210315_bakal01_erk_main_21-03-15_12-37-27.ply\n                ...\n            Blebbistatin/\n            ...\n    Plate2/\n        stacked_pointcloud/\n    Plate3/\n        stacked_pointcloud/\n```\nThis 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_type` as `\"Other\"`.\n\n\n## Usage\nThe 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 to [`cellshape-helper`](https://github.com/Sentinal4D/cellshape-helper).\n\n### Downloading the dataset\nWe suggest testing our code on the data contained in `SamplePointCloudData.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 install `wget` and `unzip` with `apt-get` (e.g. `apt-get install wget`).\n1. Download the data into the `~/Documents/` folder with wget\n```bash\ncd ~/Documents\nwget https://sandbox.zenodo.org/record/1080300/files/SamplePointCloudDataset.zip\n```\n2. Unzip the data with unzip:\n```bash \nunzip SamplePointCloudDataset.zip\n```\n\nThis will create a directory called `cellshapeSamplePointCloudDatset` under your `~Documents/` folder, i.e. `/home/USER/Documents/cellshapeSamplePointCloudDatset/` (`USER` will be different for you).\n\n### Training\nThe training procedure follows two steps:\n1. Training the dynamic graph convolutional foldingnet (DFN) autoencoder to automatically learn shape features.\n2. Adding the clustering layer to refine shape features and learn shape classes simultaneously.\n\nInference can be done after each step. \n\nOur training functions are run through a command line interface with the command ```cellshape-train```.\nFor help on all command line options, run the following in the terminal:\n```bash\ncellshape-train -h\n```\n#### 1. Train DFN autoencoder\nThe 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_dir` parmaeters 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:\n```bash\ncd ~/Documents\n```\nThen run the following:\n\n```bash\ncellshape-train \\\n--model_type \"cloud\" \\\n--pretrain \"True\" \\\n--train_type \"pretrain\" \\\n--cloud_dataset_path \"./cellshapeSamplePointCloudDataset/\" \\\n--dataset_type \"SingleCell\" \\\n--dataframe_path \"./cellshapeSamplePointCloudDataset/small_data.csv\" \\\n--output_dir \"./cellshapeOutput/\" \\\n--num_epochs_autoencoder 5 \\\n--encoder_type \"dgcnn\" \\\n--decoder_type \"foldingnetbasic\" \\\n--num_features 128 \\\n```\n\nThis step will create an output directory `/home/USER/Documents/cellshapeOutput/` with the subfolders: `nets`, `reports`, and `runs` which 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-path` parameter.\n\n\n#### 2. Add clustering layer to refine shape features and learn shape classes simultaneously\nThe 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-path` parmaeters 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:\n\n```bash\ncellshape-train \\\n--model_type \"cloud\" \\\n--train_type \"DEC\" \\\n--pretrain False \\\n--cloud_dataset_path \"./cellshapeSamplePointCloudDataset/\" \\\n--dataset_type \"SingleCell\" \\\n--dataframe_path \"./cellshapeSamplePointCloudDataset/small_data.csv\" \\\n--output_dir \"./cellshapeOutput/\" \\\n--num_features 128 \\\n--num_clusters 5 \\\n--pretrained_path \"./cellshapeOutput/nets/dgcnn_foldingnetbasic_128_pretrained_001.pt\" \\\n```\n\nTo monitor the training using [Tensorboard](https://pytorch.org/docs/stable/tensorboard.html), in a new terminal run:\n```bash\npip install tensorboard\ncd ~/Documents\ntensorboard --logdir \"./cellshapeOutput/runs/\"\n```\n\n#### Alternatively, the training steps can be run sequentially through one command line\nThis would be to state that you would like to `pretrain` and that you want to train `DEC`. \n```bash\ncellshape-train \\\n--model_type \"cloud\" \\\n--train_type \"DEC\" \\\n--pretrain True \\\n--cloud_dataset_path \"./cellshapeSamplePointCloudDataset/\" \\\n--dataset_type \"SingleCell\" \\\n--dataframe_path \"./cellshapeSamplePointCloudDataset/small_data.csv\" \\\n--output_dir \"./cellshapeOutput/\" \\\n--num_features 128 \\\n--num_clusters 5 \\\n```\n\n\n### Inference\nExample inference notebooks can be found in the `docs/notebooks/` folder.\n\n## Issues\nIf you have any problems, please raise an issue [here](https://github.com/Sentinal4D/cellshape/issues)\n\n## Citation\n```bibtex\n@article{DeVries2022single,\n\tauthor = {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},\n\ttitle = {3D single-cell shape analysis using geometric deep learning},\n\telocation-id = {2022.06.17.496550},\n\tyear = {2023},\n\tdoi = {10.1101/2022.06.17.496550},\n\tpublisher = {Cold Spring Harbor Laboratory},\n\tURL = {https://www.biorxiv.org/content/early/2023/03/27/2022.06.17.496550},\n\teprint = {https://www.biorxiv.org/content/early/2023/03/27/2022.06.17.496550.full.pdf},\n\tjournal = {bioRxiv}\n}\n```\n\n## References\n[1] An Tao, 'Unsupervised Point Cloud Reconstruction for Classific Feature Learning', [GitHub Repo](https://github.com/AnTao97/UnsupervisedPointCloudReconstruction), 2020\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSentinal4D%2Fcellshape","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSentinal4D%2Fcellshape","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSentinal4D%2Fcellshape/lists"}