refactor model wrapper classes (#1)

* refactor model wrapper classes
* documentation updates
---------

Co-authored-by: Kuo <[email protected]>

Author: tony-kuo

docs/_static/integrate_thumbnail.png

@@ -22,6 +22,9 @@ API Reference
     :hidden:
 
     modules/models/scimilarity
+    modules/models/scfoundation
+    modules/models/scvi
+    modules/models/ssl
 
 .. toctree::
     :maxdepth: 2
@@ -44,6 +47,9 @@ Models
 These modules provide functionality for wrapping models to generate attributions.
 
 * :mod:`SIGnature.models.scimilarity`
+* :mod:`SIGnature.models.scfoundation`
+* :mod:`SIGnature.models.scvi`
+* :mod:`SIGnature.models.ssl`
 
 Utilities
 --------------------------------------------------------------------------------

docs/api.rst

@@ -57,6 +57,7 @@
 nbsphinx_thumbnails = {
     'notebooks/1-QueryingAttributions': '_static/query_thumbnail.png',
     'notebooks/2-GeneratingAttributions': '_static/generate_thumbnail.png',
+    'notebooks/3-IntegratingAttributions': '_static/integrate_thumbnail.png',
 }
 
 # Add any paths that contain templates here, relative to this directory.

docs/conf.py

@@ -25,8 +25,17 @@ https://zenodo.org/communities/signature/
 Downloading models
 --------------------------------------------------------------------------------
 
-Download the SCimilarity model from Zenodo:
-https://zenodo.org/records/15729925
+To generate attribution scores on new data, helper files can be downloaded from Zenodo:
+https://zenodo.org/records/17903196
+
+SIGnature currently supports calculating attributions using the following models:
+
+
+1. `SCimilarity <https://doi.org/10.1038/s41586-024-08411-y>`_: pretrained weights included in helper files, but can also be downloaded here: https://zenodo.org/records/15729925
+2. `scFoundation <https://doi.org/10.1038/s41592-024-02305-7>`_: pretrained weights can be downloaded here: https://huggingface.co/genbio-ai/scFoundation/tree/main
+3. `scVI <https://doi.org/10.1038/s41592-018-0229-2>`_: pretrained weights for scVI models trained on CZI Census data can be downloaded here: https://cellxgene.cziscience.com/census-models
+4. `SSL-scTab <https://doi.org/10.1038/s42256-024-00934-3>`_: pretrained weights for self-supervised learning models trained on scTab data can be downloaded here: https://huggingface.co/TillR/sc_pretrained/tree/main
+
 
 Conda environment setup
 --------------------------------------------------------------------------------

docs/install.rst

@@ -0,0 +1,6 @@
+SIGnature.models.scfoundation
+--------------------------------------------------------------------------------
+
+.. automodule:: SIGnature.models.scfoundation
+    :members:
+    :show-inheritance:

docs/modules/models/scfoundation.rst

@@ -0,0 +1,6 @@
+SIGnature.models.scvi
+--------------------------------------------------------------------------------
+
+.. automodule:: SIGnature.models.scvi
+    :members:
+    :show-inheritance:

docs/modules/models/scvi.rst

@@ -0,0 +1,6 @@
+SIGnature.models.ssl
+--------------------------------------------------------------------------------
+
+.. automodule:: SIGnature.models.ssl
+    :members:
+    :show-inheritance:

docs/modules/models/ssl.rst

@@ -13,11 +13,11 @@
     "\n",
     "Before running this tutorial, you need to:\n",
     "\n",
-    "1. Download the SCimilarity model from https://zenodo.org/records/15729925\n",
-    "2. Download the cell type-level attributions you are interested in from https://zenodo.org/communities/signature/. For this tutorial, you will need two attribution folders from Zenodo (https://zenodo.org/records/15794176):\n",
+    "1. Download the model_files folder from [here](https://zenodo.org/records/17903196)\n",
+    "2. Download the cell type-level attributions you are interested in from [here](https://zenodo.org/communities/signature/). For this tutorial, you will need two attribution folders from [here](https://zenodo.org/records/17905668):\n",
     "\n",
-    "    1. `celltype_attributions_lung`: contains data for the first part of the tutorial showing a simple querying example. This folder can be extracted with the command `tar -xzf celltype_attributions_lung.tar.gz`\n",
-    "    2. `celltype_attributions`: contains data from myeloid cells to replicate the MS1 signature analysis from the paper. This folder can be extracted with the command `tar -xzf celltype_attributions.tar.gz`"
+    "    1. **celltype_attributions_lung**: contains data for the first part of the tutorial showing a simple querying example. This folder can be extracted with the command \"tar -xzf celltype_attributions_lung.tar.gz\"\n",
+    "    2. **celltype_attributions**: contains data from myeloid cells to replicate the MS1 signature analysis from the paper. This folder can be extracted with the command \"tar -xzf celltype_attributions.tar.gz\""
    ]
   },
   {
@@ -33,9 +33,8 @@
     "from os.path import join\n",
     "import pandas as pd\n",
     "import seaborn as sns\n",
-    "from SIGnature import SIGnature, SCimilarity, Meta\n",
-    "import tiledb\n",
-    "import time\n",
+    "from SIGnature import SIGnature, Meta\n",
+    "from SIGnature.models.scimilarity import SCimilarityWrapper\n",
     "from tqdm import tqdm\n",
     "import warnings\n",
     "\n",
@@ -67,10 +66,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "## Path to Scimilarity Model Downloaded from Zenodo (https://zenodo.org/records/15729925)\n",
-    "scim_model_path = \"/home/scimilarity_model\"\n",
+    "## Path to Scimilarity Model Downloaded from Zenodo (https://zenodo.org/records/17903196)\n",
+    "scim_model_path = \"/home/model_files/scimilarity\" # change to path where model_files was downloaded\n",
     "## Set use_gpu false when querying attributions\n",
-    "scim = SCimilarity(model_path=scim_model_path, use_gpu=False)"
+    "scim = SCimilarityWrapper(model_path=scim_model_path, use_gpu=False)"
    ]
   },
   {
@@ -80,8 +79,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "## Folder where the cell type attributions are stored\n",
-    "## Downloaded from Zenodo (https://zenodo.org/records/15794176)\n",
+    "## Folder where the cell type attributions are stored, Downloaded from Zenodo (https://zenodo.org/records/17905668)\n",
     "ct_base = \"/home/celltype_attributions_lung\"\n",
     "all_ct = os.listdir(ct_base)"
    ]
@@ -103,7 +101,7 @@
    "source": [
     "## Check genes (AT1 associated genes from CellMarker)\n",
     "goi = ['CAV1', 'CAV2', 'CLIC5']\n",
-    "sig = SIGnature(gene_order=scim.gene_order, model=scim)\n",
+    "sig = SIGnature(gene_order=scim.gene_order)\n",
     "gene_list = sig.check_genes(goi)"
    ]
   },
@@ -259,10 +257,10 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "## Path to Scimilarity Model Downloaded from Zenodo (https://zenodo.org/records/15794176)\n",
-    "scim_model_path = \"/home/scimilarity_model\"\n",
+    "## Path to Scimilarity Model Downloaded from Zenodo (https://zenodo.org/records/17903196)\n",
+    "scim_model_path = \"/home/model_files/scimilarity\"\n",
     "## Set use_gpu false when querying attributions\n",
-    "scim = SCimilarity(model_path=scim_model_path, use_gpu=False)"
+    "scim = SCimilarityWrapper(model_path=scim_model_path, use_gpu=False)"
    ]
   },
   {
@@ -272,8 +270,7 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "## This should be the folder where the attributions are stored\n",
-    "## Path to cell type attributions downloaded from Zenodo (https://zenodo.org/records/15794176)\n",
+    "## This should be the folder where the attributions are stored, downloaded from Zenodo (https://zenodo.org/records/17905668)\n",
     "ct_base = \"/home/celltype_attributions\"\n",
     "all_ct = os.listdir(ct_base)"
    ]
@@ -343,7 +340,7 @@
     }
    ],
    "source": [
-    "sig = SIGnature(gene_order=scim.gene_order, model=scim)\n",
+    "sig = SIGnature(gene_order=scim.gene_order)\n",
     "gene_list = sig.check_genes(ms1_genes)"
    ]
   },
@@ -867,14 +864,6 @@
     "    dotsize=9,\n",
     ")"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "e98b6563-124d-40c5-a9be-783944f52e01",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {