Upload folder using huggingface_hub

README.md

@@ -1,206 +1,9 @@
-
-
-# SCimilarity Model
-
-## Model Details
-
-- **Model Name**: SCimilarity
-- **Version**: 1.0 [deeplife version]
-- **Type**: Metric learning framework for single-cell RNA-seq data
-- **Paper**: [Scalable querying of human cell atlases via a foundational model reveals commonalities across fibrosis-associated macrophages
-](https://www.biorxiv.org/content/10.1101/2023.07.18.549537v1)
-- **Original Implementation**: [SCimilarity GitHub Repository](https://github.com/genentech/scimilarity)
-
-## Model Description
-
-SCimilarity is a metric learning framework that learns and searches a unified and interpretable representation of single-cell RNA-seq data. It enables annotation of cell types and instant querying for cell states across tens of millions of profiles. In the context of DeepLife ML Infra, we focus on its cell embedding capabilities.
-
-### Abstract
-
-Single-cell RNA-seq (scRNA-seq) studies have profiled over 100 million human cells across diseases, developmental stages, and perturbations to date. A singular view of this vast and growing expression landscape could help reveal novel associations between cell states and diseases, discover cell states in unexpected tissue contexts, and relate in vivo cells to in vitro models. However, these require a common, scalable representation of cell profiles from across the body, a general measure of their similarity, and an efficient way to query these data. Here, we present SCimilarity, a metric learning framework to learn and search a unified and interpretable representation that annotates cell types and instantaneously queries for a cell state across tens of millions of profiles. We demonstrate SCimilarity on a 22.7 million cell corpus assembled across 399 published scRNA-seq studies, showing accurate integration, annotation and querying. We experimentally validated SCimilarity by querying across tissues for a macrophage subset originally identified in interstitial lung disease, and showing that cells with similar profiles are found in other fibrotic diseases, tissues, and a 3D hydrogel system, which we then repurposed to yield this cell state in vitro. SCimilarity serves as a foundational model for single cell gene expression data and enables researchers to query for similar cellular states across the entire human body, providing a powerful tool for generating novel biological insights from the growing Human Cell Atlas.
-
-### Key Features
-
-- Generates unified embeddings for single-cell expression profiles
-- Enables efficient querying and annotation across large-scale datasets
-- Generalizes to new studies without retraining
-- Supports discovery of novel cell state associations across diseases and tissues
-
-## Intended Use
-
-SCimilarity is designed for researchers working with single-cell RNA sequencing (scRNA-seq) data. Within the DeepLife ML Infra framework, it can be used for:
-
-- Generating cell embeddings from scRNA-seq data
-- Querying for similar cell states across large datasets
-- Annotating cell types in new datasets
-- Discovering novel associations between cell states and diseases
-
-## Training Data
-
-The model was trained on a corpus of 22.7 million cells assembled from 399 published scRNA-seq studies. For detailed information about the training data, please refer to the original paper.
-
-## Performance
-
-SCimilarity has demonstrated:
-
-- Accurate integration and annotation across a large corpus of cells
-- Efficient querying for similar cell states across tissues and diseases
-- Ability to reveal novel biological insights, as validated experimentally
-
-For specific performance metrics, please refer to the original paper.
-
-## Limitations
-
-- The model's performance may vary for cell types or states that are underrepresented in the training data
-- As with any embedding model, care should be taken when interpreting similarities, especially across different experimental conditions or protocols
-
-## Ethical Considerations
-
-Users should be aware that while the data used to train SCimilarity is from public sources, it represents human tissue samples and should be treated with appropriate respect and consideration. Researchers using this model should adhere to ethical guidelines for human subjects research.
-
-## Usage
-
-To use the SCimilarity model within the DeepLife ML Infra:
-
-1. Install the package:
-   ```
-   pip install deeplife-mlinfra
-   ```
-
-2. Import and use the model:
-   ```python
-   import anndata as ad
-   from huggingface_hub import hf_hub_download
-   from dl_models.models.scimilarity.model import SCimilarityEmbedModel
-   from dl_models.models.scimilarity.processor import SCimilarityProcessor
-
-   # Load the model and preprocessor
-   model = SCimilarityEmbedModel.from_pretrained("deeplife/scimilarity_model")
-   preprocessor = SCimilarityProcessor.from_pretrained("deeplife/scimilarity_model")
-   model.eval()
-
-   # Load your data (example using a sample dataset)
-   filepath = hf_hub_download(
-       repo_id="deeplife/h5ad_samples",
-       filename="GSE136831small.h5ad",
-       repo_type="dataset",
-   )
-   adata = ad.read_h5ad(filepath)
-
-   # Preprocess and create a dataloader
-   dataloader = preprocessor.transform_to_dataloader(adata, batch_size=256)
-
-   # Get embeddings
-   for batch in dataloader:
-       embed = model.get_cell_embeddings(batch)
-       break  # This gets embeddings for the first batch
-
-   # You can now use these embeddings for downstream tasks
-   ```
-
-For visualization of the embeddings, you can use techniques like PCA or UMAP:
-
-```python
-import numpy as np
-from sklearn.decomposition import PCA
-import matplotlib.pyplot as plt
-import umap
-
-# Convert embed to numpy
-embed_np = embed.detach().cpu().numpy()
-
-# Perform PCA
-pca = PCA(n_components=2)
-embed_pca = pca.fit_transform(embed_np)
-
-# Perform UMAP
-umap_reducer = umap.UMAP(n_components=2, random_state=42)
-embed_umap = umap_reducer.fit_transform(embed_np)
-
-# Plot the results
-fig, (ax1, ax2) = plt.subplots(1, 2, figsize=(20, 8))
-
-# PCA plot
-scatter1 = ax1.scatter(embed_pca[:, 0], embed_pca[:, 1], alpha=0.7)
-ax1.set_title('SCimilarity Embeddings - PCA')
-ax1.set_xlabel('PC1')
-ax1.set_ylabel('PC2')
-plt.colorbar(scatter1, ax=ax1)
-
-# UMAP plot
-scatter2 = ax2.scatter(embed_umap[:, 0], embed_umap[:, 1], alpha=0.7)
-ax2.set_title('SCimilarity Embeddings - UMAP')
-ax2.set_xlabel('UMAP1')
-ax2.set_ylabel('UMAP2')
-plt.colorbar(scatter2, ax=ax2)
-
-plt.tight_layout()
-plt.show()
-```
-
-For more detailed usage instructions, please refer to the [documentation](https://github.com/deeplifeai/deeplife-mlinfra).
-
-## Citation
-
-If you use this model in your research, please cite both the original SCimilarity paper and the DeepLife ML Infra package:
-
-```
-@article{yoo2023scimilarity,
-  title={SCimilarity: a scalable and universal cell state similarity metric for single cell RNA-sequencing data},
-  author={Yoo, Byungjin and Nawy, Tal and Hu, Yuanjie and Szeto, Gregory L and Wuster, Arthur},
-  journal={bioRxiv},
-  pages={2023.07.18.549537},
-  year={2023},
-  publisher={Cold Spring Harbor Laboratory}
-}
-
-@software{deeplife_mlinfra,
-  title={DeepLife ML Infra: Infrastructure for Biological Deep Learning Models},
-  author={DeepLife AI Team},
-  year={2023},
-  url={https://github.com/deeplifeai/deeplife-mlinfra},
-  version={1.0.0}
-}
-```
-
-## License
-
-### Code License
-
-The SCimilarity code is licensed under the Apache License, Version 2.0. The full text of the license is as follows:
-
-```
-Copyright 2023 Genentech, Inc.
-
-Licensed under the Apache License, Version 2.0 (the "License");
-you may not use this file except in compliance with the License.
-You may obtain a copy of the License at
-
-    http://www.apache.org/licenses/LICENSE-2.0
-
-Unless required by applicable law or agreed to in writing, software
-distributed under the License is distributed on an "AS IS" BASIS,
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-See the License for the specific language governing permissions and
-limitations under the License.
-```
-
-### Model Weights License
-
-The SCimilarity model weights are licensed under the Creative Commons Attribution Share Alike 4.0 International license. Users are free to share and adapt the material under the following terms:
-
-- Attribution — You must give appropriate credit, provide a link to the license, and indicate if changes were made.
-- ShareAlike — If you remix, transform, or build upon the material, you must distribute your contributions under the same license as the original.
-
-For the full text of this license, please visit: [CC BY-SA 4.0](https://creativecommons.org/licenses/by-sa/4.0/)
-
-## Additional Resources
-
-- [SCimilarity Documentation](https://genentech.github.io/scimilarity/index.html)
-- [Pretrained Model Weights and Data](https://zenodo.org/records/10685499)
-
-## Contact
-
-For questions or issues related to this model implementation in DeepLife ML Infra, please open an issue in the [repository](https://github.com/deeplifeai/deeplife-mlinfra).
-
-For questions about the original SCimilarity model, please refer to the [original repository](https://github.com/genentech/scimilarity).
+---
+tags:
+- model_hub_mixin
+- pytorch_model_hub_mixin
+---
+
+This model has been pushed to the Hub using the [PytorchModelHubMixin](https://huggingface.co/docs/huggingface_hub/package_reference/mixins#huggingface_hub.PyTorchModelHubMixin) integration:
+- Library: [More Information Needed]
+- Docs: [More Information Needed]