Improve SnapCCESS usability and citation guidance

Author: PYangLab

CHAGES.md

@@ -0,0 +1,5 @@
+# Change Log
+
+## 2024-07-26
+
+- Updated the PyTorch dependency version to pass GitHub security checks.

CHANGES.md

@@ -0,0 +1,34 @@
+cff-version: 1.2.0
+message: "If you use SnapCCESS, please cite the associated Bioinformatics paper."
+title: "SnapCCESS: Ensemble deep learning of embeddings for clustering multimodal single-cell omics data"
+version: 0.2.2
+license: GPL-3.0-only
+repository-code: "https://github.com/PYangLab/SnapCCESS"
+authors:
+  - family-names: Yu
+    given-names: Lijia
+  - family-names: Liu
+    given-names: Chunlei
+  - family-names: Yang
+    given-names: "Jean Yee Hwa"
+  - family-names: Yang
+    given-names: Pengyi
+preferred-citation:
+  type: article
+  title: "Ensemble deep learning of embeddings for clustering multimodal single-cell omics data"
+  authors:
+    - family-names: Yu
+      given-names: Lijia
+    - family-names: Liu
+      given-names: Chunlei
+    - family-names: Yang
+      given-names: "Jean Yee Hwa"
+    - family-names: Yang
+      given-names: Pengyi
+  journal: Bioinformatics
+  year: 2023
+  volume: 39
+  issue: 6
+  article-number: btad382
+  doi: "10.1093/bioinformatics/btad382"
+  url: "https://doi.org/10.1093/bioinformatics/btad382"

CITATION.cff

@@ -1,46 +1,99 @@
 # SnapCCESS <a href="https://github.com/PYangLab/SnapCCESS"><img src="https://i.imgur.com/XHEB9j1.png" title="SnapCCESS hex sticker" align="right" height="138" /></a>
 
-SnapCCESS: Ensemble deep learning of embeddings for clustering multimodal single-cell omics data.
+SnapCCESS is an unsupervised ensemble deep learning framework for clustering
+multimodal single-cell omics data. It creates snapshots of multimodal variational
+autoencoder embeddings, which can then be used with downstream clustering
+methods to generate consensus cell clusters.
 
+The repository contains both:
 
-We propose SnapCCESS for clustering cells by integrating data modalities in multimodal
-single-cell omics data using an unsupervised ensemble deep learning framework. By creating snapshots
-of embeddings of multimodality using variational autoencoders, SnapCCESS can be coupled with
-various clustering algorithms for generating consensus clustering of cells.
+- `snapccess-py/`: the Python implementation distributed through PyPI.
+- `snapccess-r/SnapCCESS/`: an R wrapper that calls the Python package through
+  `reticulate`.
 
+![SnapCCESS workflow](https://i.imgur.com/krfBTGP.png)
 
-![img](https://i.imgur.com/krfBTGP.png)
+## Publication
 
+SnapCCESS accompanies:
 
+> Yu, L., Liu, C., Yang, J. Y. H. & Yang, P. Ensemble deep learning of
+> embeddings for clustering multimodal single-cell omics data.
+> *Bioinformatics* 39(6), btad382 (2023).
+> <https://doi.org/10.1093/bioinformatics/btad382>
 
 ## Installation
 
 ### Python
 
+```bash
+pip install snapccess --index-url https://pypi.org/simple
 ```
-pip install snapccess  --index-url https://pypi.org/simple
-```
-
-For detailed description of each function, please see [https://github.com/PYangLab/SnapCCESS/tree/main/snapccess-py](https://github.com/PYangLab/SnapCCESS/tree/main/snapccess-py)
 
+The Python package depends on PyTorch. GPU acceleration is optional and depends
+on the local PyTorch/CUDA or PyTorch/ROCm installation.
 
-### R
+### R Wrapper
 
+```r
+remotes::install_github(
+  repo = "PYangLab/SnapCCESS",
+  branch = "main",
+  subdir = "snapccess-r/SnapCCESS"
+)
 ```
-remotes::install_github(repo='PYangLab/SnapCCESS',branch='main',subdir='snapccess-r/SnapCCESS')
+
+After installing the R wrapper, install the Python package into a reticulate
+environment:
+
+```r
+SnapCCESS::install_SnapCCESS(envname = "SnapCCESS", method = "conda")
 ```
 
-For detailed description of each function, please see [https://github.com/PYangLab/SnapCCESS/tree/main/snapccess-r](https://github.com/PYangLab/SnapCCESS/tree/main/snapccess-r)
+If Python dependencies are already managed through Conda, virtualenv, or a
+cluster module, configure `reticulate` to use that environment before loading
+the R wrapper.
+
+## Input Data
 
+SnapCCESS expects a list of modalities measured across the same cells, for
+example RNA and ADT matrices from CITE-seq. Each modality should be arranged as
+features by cells before preprocessing in the R wrapper. The Python API expects
+the combined PyTorch data loader used by the training routine.
 
-## [Tutorial](https://github.com/PYangLab/SnapCCESS/tree/main/tutorials)
-### NOTE: This tutorial only explains how to use this package; it doesn't recommend the best parameters for your datasets. For the datasets used in the published paper associated with this package, the parameters are listed in the same paper. Please refer to the paper to guide you in finding the best parameters.
+The tutorial data in `tutorials/in/` includes small CITE-seq RNA, ADT, and cell
+type files that can be used to run the examples.
 
+## Tutorials
 
-For python version of script, please see [an_example_of_generate_embedding_using_SnapCCESS_python_version](https://github.com/PYangLab/SnapCCESS/blob/main/tutorials/src/an_example_of_generate_embedding_using_SnapCCESS_python_version.ipynb)
+- Python example:
+  [`tutorials/src/an_example_of_generate_embedding_using_SnapCCESS_python_version.ipynb`](tutorials/src/an_example_of_generate_embedding_using_SnapCCESS_python_version.ipynb)
+- R example:
+  [`tutorials/src/SnapCCESS_R_example.html`](tutorials/src/SnapCCESS_R_example.html)
+- Tutorial overview:
+  [`tutorials/README.md`](tutorials/README.md)
+
+The tutorials demonstrate package usage. The best hyperparameters can vary by
+dataset; for the datasets used in the publication, refer to the paper.
+
+## Citation
+
+If you use SnapCCESS, please cite:
+
+```bibtex
+@article{Yu2023SnapCCESS,
+  title = {Ensemble deep learning of embeddings for clustering multimodal single-cell omics data},
+  author = {Yu, Lijia and Liu, Chunlei and Yang, Jean Yee Hwa and Yang, Pengyi},
+  journal = {Bioinformatics},
+  year = {2023},
+  volume = {39},
+  number = {6},
+  pages = {btad382},
+  doi = {10.1093/bioinformatics/btad382},
+  url = {https://doi.org/10.1093/bioinformatics/btad382}
+}
+```
 
-For R version of script, please see
-[SnapCCESS_R_example](https://htmlpreview.github.io/?https://github.com/PYangLab/SnapCCESS/blob/main/tutorials/src/SnapCCESS_R_example.html)
+## License
 
-## References
-Lijia Yu, Chunlei Liu, Jean Yee Hwa Yang, Pengyi Yang. Ensemble deep learning of embeddings for clustering multimodal single-cell omics data. *Bioinformatics*, 39(6), btad382, doi: [https://doi.org/10.1093/bioinformatics/btad382](https://doi.org/10.1093/bioinformatics/btad382), (2023).
+SnapCCESS is distributed under the GPL-3 license.

README.md

@@ -0,0 +1,5 @@
+# Change Log
+
+## 2024-07-26
+
+- Updated the PyTorch dependency version to pass GitHub security checks.

snapccess-py/CHANGES.md

@@ -1,129 +1,93 @@
-## SnapCCESS
-
-A python package to generate ensemble deep learning of embeddings for clustering multimodal single-cell omics data
+# snapccess
 
+Python implementation of SnapCCESS, an ensemble deep learning framework for
+learning multimodal single-cell embeddings for downstream clustering.
 
 ## Installation
 
-### Stable version
+```bash
+pip install snapccess --index-url https://pypi.org/simple
 ```
-pip install snapccess  --index-url https://pypi.org/simple
-``` 
-
-https://pypi.org/project/snapccess/
 
+Development builds, when available, can be installed from TestPyPI:
 
-### Development version
+```bash
+pip install snapccess --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple
 ```
-pip install snapccess  --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple
-``` 
-
-https://test.pypi.org/project/snapccess/
-
 
-## The functions in this package are described below.
+## Main Functions
 
-### snapshotVAE
+### `snapshotVAE`
 
-#### Description
+Create the multimodal variational autoencoder model.
 
-To create the VAE model
+```python
+from snapccess.model import snapshotVAE
 
-#### Usage
-
-```
-model = snapshotVAE(num_features=[nfeatures_rna,nfeatures_pro], num_hidden_features=[hidden_rna2,hidden_pro2], z_dim=z_dim)
+model = snapshotVAE(
+    num_features=[nfeatures_rna, nfeatures_protein],
+    num_hidden_features=[hidden_rna, hidden_protein],
+    z_dim=100,
+)
 ```
 
-#### Arguments
-
-- num_features: a list of number of features of each modality
-- num_hidden_features: the number of hidden features we will used in training the model, in our paper, we use `hidden_rna=185`, and `hidden_pro=30`
-- z_dim: dimension of the latent space, in our paper, we use `z_dim=100`
- 
-
-#### Output
+### `train_model`
 
-A VAE model
+Train a VAE with either snapshot learning-rate cycles or a constant learning
+rate.
 
+```python
+from snapccess.train import train_model
 
-----------------------
-
-### train_model
-
-#### Description
-
-Training a VAE model with Snapshot learning rate or constant learning rate 
-
-
-#### Usage
-
+model, history, embeddings = train_model(
+    model,
+    train_dl,
+    valid_dl,
+    lr=0.02,
+    epochs=50,
+    epochs_per_cycle=2,
+    save_path="",
+    snapshot=True,
+)
 ```
-model,histroy,embedding = train_model(model, train_dl, valid_dl, lr=lr, epochs=epochs,epochs_per_cycle=epochs_per_cycle, save_path=\"\",snapshot=True,embedding_number=1)
-```
-
-#### Arguments
 
-- model: a vae model
-- train_dl: training dataset
-- valid_dl: validation dataset
-- lr: initial learning rate
-- epochs: total number of train cycles for snapshot ensemble vae
-- epochs_per_cycle: the number of epochs per cycle
-- save_path: the output file path of embeddings, by default leave it blank will not save any embeddings into the `save_path`, but the `train_model` will return the embeddings
-- snapshot: a boolean value to indicate the model whether to use the snapshot ensemble method or the traditional VAE method (with constant learning rate)
-- embeddings_number: a value to indicate the index of embeddings in the output filename when apply the traditional VAE
+The function returns the trained model, training/validation loss history, and a
+list of latent-space embeddings. When `save_path` is provided, embeddings are
+also written as gzip-compressed CSV files.
 
+### `get_encodings`
 
-#### Output
+Return embeddings from a trained model.
 
-This function will return the model, the loss of training and validation dataset (history) and a list of the latent space embeddings (for Snapshot ensemble method) or a single embedding for traditional VAE method.
-
-
--------------------
-
-### get_encodings
-
-#### Description
-
-To get the embeddings from model after training.
-
-#### Usage
+```python
+from snapccess.util import get_encodings
 
+embedding = get_encodings(model, valid_dl)
 ```
-embedding = get_encodings(model,valid_dl)
-```
-
 
-#### Arguments
+Convert the result to a pandas data frame with:
 
-- model: a VAE model
-- valid_dl: the dataset that used as input to training the VAE model
+```python
+import pandas as pd
 
-#### Output
-
-Embedding of the `valid_dl` dataset in the VAE model, to convert it to a matrix, try `pd.DataFrame(embedding.cpu().numpy())`
-
-
--------------------
-
-### nvidia_info
+embedding_df = pd.DataFrame(embedding.cpu().numpy())
+```
 
-#### Description
+### `nvidia_info`
 
-To monitor the memory usage of GPU
+Monitor GPU memory usage for a process when NVIDIA drivers and `pynvml` are
+available.
 
-#### Usage
+```python
+from snapccess.util import nvidia_info
 
+memory = nvidia_info(pid)["memory"]
 ```
-memory = nvidia_info(pid)['memory']
-```
-
-#### Arguments
-
-- pid: the pid of running script
 
+## Citation
 
-#### Output
+If you use SnapCCESS, please cite:
 
-This function will return the memory usage of the pid process.
+Yu, L., Liu, C., Yang, J. Y. H. & Yang, P. Ensemble deep learning of embeddings
+for clustering multimodal single-cell omics data. *Bioinformatics* 39(6),
+btad382 (2023). <https://doi.org/10.1093/bioinformatics/btad382>

snapccess-py/README.md

@@ -1,9 +1,25 @@
 [tool.poetry]
-name = "SnapCCESS"
+name = "snapccess"
 version = "0.2.2"
 description = "Ensemble deep learning of embeddings for clustering multimodal single-cell omics data"
-authors = ["Lijia Yu <[email protected]>"]
+authors = [
+  "Lijia Yu <[email protected]>",
+  "Chunlei Liu",
+  "Jean Yee Hwa Yang",
+  "Pengyi Yang <[email protected]>"
+]
+license = "GPL-3.0-only"
 readme = "README.md"
+repository = "https://github.com/PYangLab/SnapCCESS"
+homepage = "https://github.com/PYangLab/SnapCCESS"
+keywords = ["single-cell", "multimodal", "clustering", "deep-learning", "vae"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
 
 [tool.poetry.dependencies]
 python = ">=3.8"
@@ -13,7 +29,7 @@ torch = ">=2.2.0"
 pynvml = ">=11.4.1"
 
 [project.urls]
-Changelog = "https://github.com/PYangLab/SnapCCESS/CHANGES.md"
+Changelog = "https://github.com/PYangLab/SnapCCESS/blob/main/CHANGES.md"
 Homepage = "https://github.com/PYangLab/SnapCCESS"
 
 [tool.hatch.metadata.hooks.fancy-pypi-readme]

snapccess-py/pyproject.toml

@@ -1 +1 @@
-__version__ = '0.2.0'
+__version__ = "0.2.2"