Upload README.md with huggingface_hub

README.md

@@ -1,13 +1,13 @@
 ---
-license: cc-by-4.0
 library_name: scvi-tools
+license: cc-by-4.0
 tags:
 - biology
 - genomics
 - single-cell
 - model_cls_name:SCANVI
-- scvi_version:1.1.3
-- anndata_version:0.10.7
+- scvi_version:1.2.0
+- anndata_version:0.11.1
 - modality:rna
 - tissue:nose
 - tissue:respiratory airway
@@ -15,15 +15,140 @@ tags:
 - annotated:True
 ---
 
-# Description
 
-The integrated Human Lung Cell Atlas (HLCA) represents the first large-scale, integrated single-cell reference atlas of the human lung.
+ScANVI is a variational inference model for single-cell RNA-seq data that can learn an underlying
+latent space, integrate technical batches and impute dropouts.
+In addition, to scVI, ScANVI is a semi-supervised model that can leverage labeled data to learn a
+cell-type classifier in the latent space and afterward predict cell types of new data.
+The learned low-dimensional latent representation of the data can be used for visualization and
+clustering.
+
+scANVI takes as input a scRNA-seq gene expression matrix with cells and genes as well as a
+cell-type annotation for a subset of cells.
+We provide an extensive [user guide](https://docs.scvi-tools.org/en/1.2.0/user_guide/models/scanvi.html).
+
+- See our original manuscript for further details of the model:
+[scANVI manuscript](https://www.embopress.org/doi/full/10.15252/msb.20209620).
+- See our manuscript on [scvi-hub](https://www.biorxiv.org/content/10.1101/2024.03.01.582887v2)
+how to leverage pre-trained models.
 
-# Model properties
+This model can be used for fine tuning on new data using our Arches framework:
+[Arches tutorial](https://docs.scvi-tools.org/en/1.0.0/tutorials/notebooks/scarches_scvi_tools.html).
 
-Many model properties are in the model tags. Some more are listed below.
 
-**model_init_params**:
+# Model Description
+
+The integrated Human Lung Cell Atlas (HLCA) represents the first large-scale, integrated single-cell reference atlas of the human lung.
+
+# Metrics
+
+We provide here key performance metrics for the uploaded model, if provided by the data uploader.
+
+<details>
+<summary><strong>Coefficient of variation</strong></summary>
+
+The cell-wise coefficient of variation summarizes how well variation between different cells is
+preserved by the generated model expression. Below a squared Pearson correlation coefficient of 0.4
+, we would recommend not to use generated data for downstream analysis, while the generated latent
+space might still be useful for analysis.
+
+**Cell-wise Coefficient of Variation**:
+
+| Metric                  | Training Value |
+|-------------------------|----------------|
+| Mean Absolute Error | 1.43   |
+| Pearson Correlation | 0.93  |
+| Spearman Correlation | 0.85 |
+| R² (R-Squared) | 0.85  |
+
+The gene-wise coefficient of variation summarizes how well variation between different genes is
+preserved by the generated model expression. This value is usually quite high.
+
+**Gene-wise Coefficient of Variation**:
+
+| Metric                  | Training Value |
+|-------------------------|----------------|
+| Mean Absolute Error | 6.58   |
+| Pearson Correlation | 0.86  |
+| Spearman Correlation | 0.98 |
+| R² (R-Squared) | 0.61  |
+
+</details>
+
+<details>
+<summary><strong>Differential expression metric</strong></summary>
+
+The differential expression metric provides a summary of the differential expression analysis
+between cell types or input clusters. We provide here the F1-score, Pearson Correlation
+Coefficient of Log-Foldchanges, Spearman Correlation Coefficient, and Area Under the Precision
+Recall Curve (AUPRC) for the differential expression analysis using Wilcoxon Rank Sum test for each
+cell-type.
+
+**Differential expression**:
+
+| Index | gene_f1 | lfc_mae | lfc_pearson | lfc_spearman | roc_auc | pr_auc | n_cells |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| respiratory basal cell | 0.98 | 0.29 | 0.91 | 0.99 | 0.28 | 0.98 | 80113.00 |
+| alveolar macrophage | 0.98 | 0.23 | 0.95 | 0.99 | 0.27 | 0.98 | 78816.00 |
+| type II pneumocyte | 0.96 | 0.24 | 0.94 | 0.98 | 0.20 | 0.99 | 62405.00 |
+| club cell | 0.94 | 0.61 | 0.80 | 0.97 | 0.18 | 0.97 | 36023.00 |
+| nasal mucosa goblet cell | 0.97 | 0.66 | 0.81 | 0.98 | 0.21 | 0.98 | 35833.00 |
+| ciliated columnar cell of tracheobronchial tree | 0.96 | 0.25 | 0.95 | 0.99 | 0.26 | 0.98 | 35225.00 |
+| CD8-positive, alpha-beta T cell | 0.96 | 0.32 | 0.91 | 0.98 | 0.30 | 0.97 | 29074.00 |
+| elicited macrophage | 0.96 | 0.46 | 0.86 | 0.98 | 0.30 | 0.97 | 28223.00 |
+| capillary endothelial cell | 0.98 | 0.73 | 0.81 | 0.97 | 0.27 | 0.98 | 23205.00 |
+| CD4-positive, alpha-beta T cell | 0.95 | 0.49 | 0.84 | 0.96 | 0.30 | 0.97 | 21285.00 |
+| classical monocyte | 0.95 | 0.41 | 0.88 | 0.98 | 0.27 | 0.96 | 17695.00 |
+| natural killer cell | 0.96 | 0.65 | 0.82 | 0.97 | 0.28 | 0.97 | 16978.00 |
+| vein endothelial cell | 0.95 | 0.70 | 0.79 | 0.95 | 0.26 | 0.96 | 12975.00 |
+| alveolar type 2 fibroblast cell | 0.92 | 0.65 | 0.83 | 0.97 | 0.27 | 0.97 | 10321.00 |
+| CD1c-positive myeloid dendritic cell | 0.92 | 0.67 | 0.68 | 0.96 | 0.33 | 0.96 | 9133.00 |
+| non-classical monocyte | 0.93 | 0.75 | 0.79 | 0.96 | 0.32 | 0.97 | 8834.00 |
+| type I pneumocyte | 0.95 | 1.31 | 0.67 | 0.88 | 0.18 | 0.95 | 7937.00 |
+| pulmonary artery endothelial cell | 0.95 | 1.17 | 0.72 | 0.93 | 0.29 | 0.97 | 7391.00 |
+| mast cell | 0.94 | 0.67 | 0.78 | 0.95 | 0.22 | 0.95 | 6623.00 |
+| multi-ciliated epithelial cell | 0.90 | 1.40 | 0.74 | 0.94 | 0.30 | 0.97 | 5873.00 |
+| alveolar type 1 fibroblast cell | 0.96 | 1.44 | 0.71 | 0.93 | 0.28 | 0.96 | 5182.00 |
+| lung macrophage | 0.94 | 1.41 | 0.70 | 0.93 | 0.31 | 0.95 | 4805.00 |
+| respiratory hillock cell | 0.92 | 1.31 | 0.77 | 0.95 | 0.28 | 0.96 | 4600.00 |
+| endothelial cell of lymphatic vessel | 0.93 | 1.04 | 0.67 | 0.93 | 0.23 | 0.95 | 4595.00 |
+| B cell | 0.93 | 1.47 | 0.59 | 0.89 | 0.27 | 0.96 | 4511.00 |
+| epithelial cell of lower respiratory tract | 0.94 | 1.07 | 0.63 | 0.90 | 0.15 | 0.95 | 4393.00 |
+| lung pericyte | 0.93 | 2.60 | 0.65 | 0.87 | 0.23 | 0.94 | 3032.00 |
+| tracheobronchial smooth muscle cell | 0.92 | 1.57 | 0.68 | 0.89 | 0.25 | 0.93 | 2996.00 |
+| plasma cell | 0.82 | 1.41 | 0.58 | 0.84 | 0.17 | 0.94 | 1773.00 |
+| bronchial goblet cell | 0.93 | 1.45 | 0.75 | 0.93 | 0.19 | 0.93 | 1670.00 |
+| bronchus fibroblast of lung | 0.90 | 1.93 | 0.71 | 0.89 | 0.28 | 0.93 | 1573.00 |
+| serous secreting cell | 0.89 | 5.09 | 0.58 | 0.70 | 0.15 | 0.98 | 1472.00 |
+| epithelial cell of alveolus of lung | 0.94 | 2.33 | 0.56 | 0.84 | 0.21 | 0.91 | 1440.00 |
+| tracheobronchial serous cell | 0.80 | 3.41 | 0.57 | 0.70 | 0.11 | 0.96 | 1417.00 |
+| acinar cell | 0.88 | 1.97 | 0.69 | 0.91 | 0.22 | 0.93 | 1274.00 |
+| tracheobronchial goblet cell | 0.88 | 4.27 | 0.58 | 0.73 | 0.14 | 0.97 | 968.00 |
+| myofibroblast cell | 0.80 | 3.86 | 0.61 | 0.82 | 0.31 | 0.92 | 716.00 |
+| ionocyte | 0.87 | 3.51 | 0.61 | 0.78 | 0.31 | 0.87 | 561.00 |
+| smooth muscle cell | 0.87 | 3.03 | 0.65 | 0.86 | 0.33 | 0.91 | 556.00 |
+| plasmacytoid dendritic cell | 0.89 | 4.15 | 0.53 | 0.72 | 0.30 | 0.90 | 552.00 |
+| mucus secreting cell | 0.86 | 4.68 | 0.56 | 0.68 | 0.22 | 0.94 | 537.00 |
+| T cell | 0.89 | 2.83 | 0.57 | 0.84 | 0.40 | 0.93 | 500.00 |
+| stromal cell | 0.82 | 5.60 | 0.57 | 0.70 | 0.24 | 0.91 | 335.00 |
+| conventional dendritic cell | 0.73 | 4.19 | 0.52 | 0.73 | 0.37 | 0.90 | 322.00 |
+| dendritic cell | 0.75 | 4.16 | 0.55 | 0.75 | 0.35 | 0.85 | 312.00 |
+| fibroblast | 0.77 | 3.68 | 0.63 | 0.81 | 0.39 | 0.90 | 276.00 |
+| mesothelial cell | 0.78 | 4.12 | 0.57 | 0.72 | 0.39 | 0.87 | 230.00 |
+| brush cell of trachebronchial tree | 0.55 | 4.98 | 0.59 | 0.74 | 0.35 | 0.83 | 165.00 |
+| lung neuroendocrine cell | 0.74 | 4.34 | 0.57 | 0.71 | 0.39 | 0.86 | 159.00 |
+| hematopoietic stem cell | 0.37 | 6.88 | 0.50 | 0.57 | 0.38 | 0.75 | 60.00 |
+
+</details>
+
+# Model Properties
+
+We provide here key parameters used to setup and train the model.
+
+<details>
+<summary><strong>Model Parameters</strong></summary>
+
+These provide the settings to setup the original model:
 ```json
 {
     "n_hidden": 128,
@@ -40,7 +165,12 @@ Many model properties are in the model tags. Some more are listed below.
 }
 ```
 
-**model_setup_anndata_args**:
+</details>
+
+<details>
+<summary><strong>Setup Data Arguments</strong></summary>
+
+Arguments passed to setup_anndata of the original model:
 ```json
 {
     "labels_key": "scanvi_label",
@@ -49,11 +179,34 @@ Many model properties are in the model tags. Some more are listed below.
     "batch_key": "dataset",
     "size_factor_key": null,
     "categorical_covariate_keys": null,
-    "continuous_covariate_keys": null
+    "continuous_covariate_keys": null,
+    "use_minified": true
 }
 ```
 
-**model_summary_stats**:
+</details>
+
+<details>
+<summary><strong>Data Registry</strong></summary>
+
+Registry elements for AnnData manager:
+|   Registry Key    |         scvi-tools Location          |
+|-------------------|--------------------------------------|
+|         X         |               adata.X                |
+|       batch       |       adata.obs['_scvi_batch']       |
+|      labels       |      adata.obs['_scvi_labels']       |
+|    latent_qzm     |   adata.obsm['scanvi_latent_qzm']    |
+|    latent_qzv     |   adata.obsm['scanvi_latent_qzv']    |
+|    minify_type    | adata.uns['_scvi_adata_minify_type'] |
+| observed_lib_size |    adata.obs['observed_lib_size']    |
+
+- **Data is Minified**: False
+
+</details>
+
+<details>
+<summary><strong>Summary Statistics</strong></summary>
+
 |     Summary Stat Key     | Value  |
 |--------------------------|--------|
 |         n_batch          |   14   |
@@ -65,38 +218,25 @@ Many model properties are in the model tags. Some more are listed below.
 |       n_latent_qzv       |   30   |
 |          n_vars          |  2000  |
 
-**model_data_registry**:
-|   Registry Key    |          scvi-tools Location           |
-|-------------------|----------------------------------------|
-|         X         |                adata.X                 |
-|       batch       |        adata.obs['_scvi_batch']        |
-|      labels       |       adata.obs['_scvi_labels']        |
-|    latent_qzm     |    adata.obsm['_scanvi_latent_qzm']    |
-|    latent_qzv     |    adata.obsm['_scanvi_latent_qzv']    |
-|    minify_type    |  adata.uns['_scvi_adata_minify_type']  |
-| observed_lib_size | adata.obs['_scanvi_observed_lib_size'] |
-
-**model_parent_module**: scvi.model
-
-**data_is_minified**: True
+</details>
 
-# Training data
 
-This is an optional link to where the training data is stored if it is too large
-to host on the huggingface Model hub.
+<details>
+<summary><strong>Training</strong></summary>
 
 <!-- If your model is not uploaded with any data (e.g., minified data) on the Model Hub, then make
 sure to provide this field if you want users to be able to access your training data. See the
 scvi-tools documentation for details. -->
+**Training data url**: Not provided by uploader
 
-Training data url: https://cellxgene.cziscience.com/collections/6f6d381a-7701-4781-935c-db10d30de293
+If provided by the original uploader, for those interested in understanding or replicating the
+training process, the code is available at the link below.
 
-# Training code
+**Training Code URL**: https://github.com/LungCellAtlas/HLCA_reproducibility
 
-This is an optional link to the code used to train the model.
+</details>
 
-Training code url: https://github.com/LungCellAtlas/HLCA_reproducibility
 
 # References
 
-Lisa Sikkema, Ciro Ramírez-Suástegui, Daniel C. Strobl, Tessa E. Gillett, Luke Zappia, Elo Madissoon, Nikolay S. Markov, Laure-Emmanuelle Zaragosi, Yuge Ji, Meshal Ansari, Marie-Jeanne Arguel, Leonie Apperloo, Martin Banchero, Christophe Bécavin, Marijn Berg, Evgeny Chichelnitskiy, Mei-i Chung, Antoine Collin, Aurore C. A. Gay, Janine Gote-Schniering, Baharak Hooshiar Kashani, Kemal Inecik, Manu Jain, Theodore S. Kapellos, Tessa M. Kole, Sylvie Leroy, Christoph H. Mayr, Amanda J. Oliver, Michael von Papen, Lance Peter, Chase J. Taylor, Thomas Walzthoeni, Chuan Xu, Linh T. Bui, Carlo De Donno, Leander Dony, Alen Faiz, Minzhe Guo, Austin J. Gutierrez, Lukas Heumos, Ni Huang, Ignacio L. Ibarra, Nathan D. Jackson, Preetish Kadur Lakshminarasimha Murthy, Mohammad Lotfollahi, Tracy Tabib, Carlos Talavera-López, Kyle J. Travaglini, Anna Wilbrey-Clark, Kaylee B. Worlock, Masahiro Yoshida, Lung Biological Network Consortium, Maarten van den Berge, Yohan Bossé, Tushar J. Desai, Oliver Eickelberg, Naftali Kaminski, Mark A. Krasnow, Robert Lafyatis, Marko Z. Nikolic, Joseph E. Powell, Jayaraj Rajagopal, Mauricio Rojas, Orit Rozenblatt-Rosen, Max A. Seibold, Dean Sheppard, Douglas P. Shepherd, Don D. Sin, Wim Timens, Alexander M. Tsankov, Jeffrey Whitsett, Yan Xu, Nicholas E. Banovich, Pascal Barbry, Thu Elizabeth Duong, Christine S. Falk, Kerstin B. Meyer, Jonathan A. Kropski, Dana Pe’er, Herbert B. Schiller, Purushothama Rao Tata, Joachim L. Schultze, Sara A. Teichmann, Alexander V. Misharin, Martijn C. Nawijn, Malte D. Luecken, and Fabian J. Theis. An integrated cell atlas of the lung in health and disease. Nature Medicine, June 2023. doi:10.1038/s41591-023-02327-2.
+Lisa Sikkema, Ciro Ramírez-Suástegui, Daniel C. Strobl, Tessa E. Gillett, Luke Zappia, Elo Madissoon, Nikolay S. Markov, Laure-Emmanuelle Zaragosi, Yuge Ji, Meshal Ansari, Marie-Jeanne Arguel, Leonie Apperloo, Martin Banchero, Christophe Bécavin, Marijn Berg, Evgeny Chichelnitskiy, Mei-i Chung, Antoine Collin, Aurore C. A. Gay, Janine Gote-Schniering, Baharak Hooshiar Kashani, Kemal Inecik, Manu Jain, Theodore S. Kapellos, Tessa M. Kole, Sylvie Leroy, Christoph H. Mayr, Amanda J. Oliver, Michael von Papen, Lance Peter, Chase J. Taylor, Thomas Walzthoeni, Chuan Xu, Linh T. Bui, Carlo De Donno, Leander Dony, Alen Faiz, Minzhe Guo, Austin J. Gutierrez, Lukas Heumos, Ni Huang, Ignacio L. Ibarra, Nathan D. Jackson, Preetish Kadur Lakshminarasimha Murthy, Mohammad Lotfollahi, Tracy Tabib, Carlos Talavera-López, Kyle J. Travaglini, Anna Wilbrey-Clark, Kaylee B. Worlock, Masahiro Yoshida, Lung Biological Network Consortium, Maarten van den Berge, Yohan Bossé, Tushar J. Desai, Oliver Eickelberg, Naftali Kaminski, Mark A. Krasnow, Robert Lafyatis, Marko Z. Nikolic, Joseph E. Powell, Jayaraj Rajagopal, Mauricio Rojas, Orit Rozenblatt-Rosen, Max A. Seibold, Dean Sheppard, Douglas P. Shepherd, Don D. Sin, Wim Timens, Alexander M. Tsankov, Jeffrey Whitsett, Yan Xu, Nicholas E. Banovich, Pascal Barbry, Thu Elizabeth Duong, Christine S. Falk, Kerstin B. Meyer, Jonathan A. Kropski, Dana Pe’er, Herbert B. Schiller, Purushothama Rao Tata, Joachim L. Schultze, Sara A. Teichmann, Alexander V. Misharin, Martijn C. Nawijn, Malte D. Luecken, and Fabian J. Theis. An integrated cell atlas of the lung in health and disease. Nature Medicine, June 2023. doi:10.1038/s41591-023-02327-2.