discotoolkit 1.1.4__tar.gz → 1.2.1__tar.gz

discotoolkit-1.2.1/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.md
+include requirements.txt

discotoolkit-1.2.1/PKG-INFO

@@ -0,0 +1,146 @@
+Metadata-Version: 2.4
+Name: discotoolkit
+Version: 1.2.1
+Summary: DISCOtoolkit is an python package that allows users to access data and use the tools provided by the DISCO database.
+Home-page: https://disco.bii.a-star.edu.sg/
+Author: Li Mengwei, Rom Uddamvathanak
+Author-email: uddamvathanak_rom@immunol.a-star.edu.sg
+Project-URL: Documentation, https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/
+Project-URL: Source, https://github.com/JinmiaoChenLab/DISCOtoolkit_py
+Project-URL: Issues, https://github.com/JinmiaoChenLab/DISCOtoolkit_py/issues
+Project-URL: DISCO, https://disco.bii.a-star.edu.sg/v1/
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: pandas>=1.4.2
+Requires-Dist: numpy>=1.21.6
+Requires-Dist: scanpy>=1.9.3
+Requires-Dist: scipy>=1.10.1
+Requires-Dist: joblib>=1.1.0
+Requires-Dist: pandarallel>=1.6.5
+Requires-Dist: requests>=2.28.1
+Requires-Dist: colorcet>=3.0.1
+Requires-Dist: leidenalg
+Requires-Dist: h5py>=3.8
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: seaborn>=0.12
+Dynamic: author
+Dynamic: author-email
+Dynamic: description
+Dynamic: description-content-type
+Dynamic: home-page
+Dynamic: project-url
+Dynamic: requires-dist
+Dynamic: requires-python
+Dynamic: summary
+
+<!--
+ * @Descripttion: 
+ * @version: 
+ * @Author: Mengwei Li
+ * @Date: 2023-04-16 21:20:42
+ * @LastEditors: Mengwei Li
+ * @LastEditTime: 2023-04-16 21:22:03
+-->
+[![Documentation](https://img.shields.io/badge/docs-disco.bii.a--star.edu.sg-blue)](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/) [![Downloads](https://static.pepy.tech/personalized-badge/discotoolkit?period=total&units=international_system&left_color=black&right_color=orange&left_text=Downloads)](https://pepy.tech/project/discotoolkit) [![PyPI version](https://img.shields.io/pypi/v/discotoolkit)](https://pypi.org/project/discotoolkit)
+
+# DISCOtoolkit 1.2.1
+
+DISCOtoolkit is a Python package for accessing the data and tools of the [DISCO database](https://disco.bii.a-star.edu.sg/) (DISCO v1). Read the documentation, with tutorials and the API reference, at [disco.bii.a-star.edu.sg/v1/docs/toolkit/guide](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/).
+
+- Filter and download DISCO data based on sample metadata and cell type information
+- Gene search: a gene's expression across cell types and tissues
+- CELLiD: cell type annotation
+- scEnrichment: gene set enrichment using DISCO DEGs
+
+> **DISCO v1 and v2.** The toolkit talks to **DISCO v1** by default. DISCO v2 has its own R package ([DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit)); the Python package can still be pointed at a v2 server, see [Choosing a server](#choosing-a-server).
+
+## Quickstart (Google Colab)
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/quickstart_disco_v1.ipynb)
+
+Installs, checks the server, filters, downloads and plots in about ten cells, with nothing to set up locally.
+
+## Installation
+
+Python 3.9 or newer. In your current environment:
+
+```
+pip install discotoolkit
+```
+
+To try the latest development version straight from GitHub:
+
+```
+pip install "git+https://github.com/JinmiaoChenLab/DISCOtoolkit_py.git"
+```
+
+To work on the code, or to test changes before they are released, install from a local clone. `-e` links the install to the folder, so edits take effect without reinstalling:
+
+```
+git clone https://github.com/JinmiaoChenLab/DISCOtoolkit_py.git
+cd DISCOtoolkit_py
+pip install -e .
+```
+
+`pip install discotoolkit` and a local install give the same code when the versions match. The difference is the source: PyPI delivers a released, packaged copy, while a local install uses the files in your folder.
+
+Dependencies (installed automatically): numpy, pandas, scanpy, scipy, joblib, pandarallel, requests, colorcet, leidenalg, h5py, matplotlib, seaborn.
+
+We recommend a virtual environment, for example with miniconda:
+
+```
+conda create --name disco python=3.10
+conda activate disco
+conda install ipykernel
+python -m ipykernel install --user --name disco --display-name "disco"
+python -m pip install -U discotoolkit
+```
+
+## Choosing a server
+
+```python
+import discotoolkit as dt
+
+dt.get_server()                       # 'https://disco.bii.a-star.edu.sg/disco_v3_api/'  (DISCO v1, the default)
+dt.set_server("v2")                   # DISCO v2
+dt.set_server("https://my.server/disco_v3_api/")   # any server with the same API
+```
+
+or set the `DISCO_API_URL` environment variable before importing the package.
+
+## Testing
+
+Two small test files need nothing beyond `requests`, so they run anywhere, including Colab:
+
+```
+python tests/test_settings.py           # offline: server selection logic
+python tests/test_version.py            # offline: setup.py and __init__.py agree on the version
+python tests/test_docs.py               # offline: notebooks are clean, every public function is in the API reference
+python tests/test_server_contract.py    # online: does the server answer everything the toolkit needs?
+python tests/test_server_contract.py https://immunesinglecell.org/disco_v3_api/   # check another server
+```
+
+GitHub Actions runs these, and installs the package on Python 3.9-3.12, on every push. Maintainers: see [RELEASING.md](RELEASING.md) for how a release, and its documentation, is published.
+
+`test_server_contract.py` checks status codes and the shape of each response (the columns and file types the toolkit reads). It only samples the large reference files, it does not download them.
+
+## Basic Usage
+Example in Jupyter notebook.
+
+<em>please select disco as the kernel for running the jupyter notebook</em>
+
+### [Quickstart for DISCO v1](https://github.com/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/quickstart_disco_v1.ipynb)
+
+### [Filter and download DISCO data](https://github.com/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/download_data.ipynb)
+
+### [Cell Type Annotation using CELLiD](https://github.com/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/CELLiD_celltype_annotation.ipynb)
+
+### [scEnrichment](https://github.com/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/scEnrichment.ipynb)
+
+## Citation
+1. [Li, Mengwei, et al. "DISCO: a database of Deeply Integrated human Single-Cell Omics data." Nucleic acids research 50.D1 (2022): D596-D602.](https://academic.oup.com/nar/article/50/D1/D596/6430491)
+2. [Mengwei Li, Kok Siong Ang, Brian Teo, Uddamvathanak Rom, Minh N Nguyen, Sebastian Maurer-Stroh, Jinmiao Chen. "Rediscovering publicly available single-cell data with the DISCO platform." Nucleic Acids Research (2024): gkae1108](https://academic.oup.com/nar/advance-article/doi/10.1093/nar/gkae1108/7899529)
+
+## Follow us on our social media!
+- [HSCRM2](https://twitter.com/HSCRM2)
+- [JinmiaoChenLab Github repo](https://github.com/JinmiaoChenLab)

discotoolkit-1.2.1/README.md

@@ -0,0 +1,111 @@
+<!--
+ * @Descripttion: 
+ * @version: 
+ * @Author: Mengwei Li
+ * @Date: 2023-04-16 21:20:42
+ * @LastEditors: Mengwei Li
+ * @LastEditTime: 2023-04-16 21:22:03
+-->
+[![Documentation](https://img.shields.io/badge/docs-disco.bii.a--star.edu.sg-blue)](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/) [![Downloads](https://static.pepy.tech/personalized-badge/discotoolkit?period=total&units=international_system&left_color=black&right_color=orange&left_text=Downloads)](https://pepy.tech/project/discotoolkit) [![PyPI version](https://img.shields.io/pypi/v/discotoolkit)](https://pypi.org/project/discotoolkit)
+
+# DISCOtoolkit 1.2.1
+
+DISCOtoolkit is a Python package for accessing the data and tools of the [DISCO database](https://disco.bii.a-star.edu.sg/) (DISCO v1). Read the documentation, with tutorials and the API reference, at [disco.bii.a-star.edu.sg/v1/docs/toolkit/guide](https://disco.bii.a-star.edu.sg/v1/docs/toolkit/guide/).
+
+- Filter and download DISCO data based on sample metadata and cell type information
+- Gene search: a gene's expression across cell types and tissues
+- CELLiD: cell type annotation
+- scEnrichment: gene set enrichment using DISCO DEGs
+
+> **DISCO v1 and v2.** The toolkit talks to **DISCO v1** by default. DISCO v2 has its own R package ([DISCOtoolkit](https://github.com/JinmiaoChenLab/DISCOtoolkit)); the Python package can still be pointed at a v2 server, see [Choosing a server](#choosing-a-server).
+
+## Quickstart (Google Colab)
+
+[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/quickstart_disco_v1.ipynb)
+
+Installs, checks the server, filters, downloads and plots in about ten cells, with nothing to set up locally.
+
+## Installation
+
+Python 3.9 or newer. In your current environment:
+
+```
+pip install discotoolkit
+```
+
+To try the latest development version straight from GitHub:
+
+```
+pip install "git+https://github.com/JinmiaoChenLab/DISCOtoolkit_py.git"
+```
+
+To work on the code, or to test changes before they are released, install from a local clone. `-e` links the install to the folder, so edits take effect without reinstalling:
+
+```
+git clone https://github.com/JinmiaoChenLab/DISCOtoolkit_py.git
+cd DISCOtoolkit_py
+pip install -e .
+```
+
+`pip install discotoolkit` and a local install give the same code when the versions match. The difference is the source: PyPI delivers a released, packaged copy, while a local install uses the files in your folder.
+
+Dependencies (installed automatically): numpy, pandas, scanpy, scipy, joblib, pandarallel, requests, colorcet, leidenalg, h5py, matplotlib, seaborn.
+
+We recommend a virtual environment, for example with miniconda:
+
+```
+conda create --name disco python=3.10
+conda activate disco
+conda install ipykernel
+python -m ipykernel install --user --name disco --display-name "disco"
+python -m pip install -U discotoolkit
+```
+
+## Choosing a server
+
+```python
+import discotoolkit as dt
+
+dt.get_server()                       # 'https://disco.bii.a-star.edu.sg/disco_v3_api/'  (DISCO v1, the default)
+dt.set_server("v2")                   # DISCO v2
+dt.set_server("https://my.server/disco_v3_api/")   # any server with the same API
+```
+
+or set the `DISCO_API_URL` environment variable before importing the package.
+
+## Testing
+
+Two small test files need nothing beyond `requests`, so they run anywhere, including Colab:
+
+```
+python tests/test_settings.py           # offline: server selection logic
+python tests/test_version.py            # offline: setup.py and __init__.py agree on the version
+python tests/test_docs.py               # offline: notebooks are clean, every public function is in the API reference
+python tests/test_server_contract.py    # online: does the server answer everything the toolkit needs?
+python tests/test_server_contract.py https://immunesinglecell.org/disco_v3_api/   # check another server
+```
+
+GitHub Actions runs these, and installs the package on Python 3.9-3.12, on every push. Maintainers: see [RELEASING.md](RELEASING.md) for how a release, and its documentation, is published.
+
+`test_server_contract.py` checks status codes and the shape of each response (the columns and file types the toolkit reads). It only samples the large reference files, it does not download them.
+
+## Basic Usage
+Example in Jupyter notebook.
+
+<em>please select disco as the kernel for running the jupyter notebook</em>
+
+### [Quickstart for DISCO v1](https://github.com/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/quickstart_disco_v1.ipynb)
+
+### [Filter and download DISCO data](https://github.com/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/download_data.ipynb)
+
+### [Cell Type Annotation using CELLiD](https://github.com/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/CELLiD_celltype_annotation.ipynb)
+
+### [scEnrichment](https://github.com/JinmiaoChenLab/DISCOtoolkit_py/blob/main/docs/scEnrichment.ipynb)
+
+## Citation
+1. [Li, Mengwei, et al. "DISCO: a database of Deeply Integrated human Single-Cell Omics data." Nucleic acids research 50.D1 (2022): D596-D602.](https://academic.oup.com/nar/article/50/D1/D596/6430491)
+2. [Mengwei Li, Kok Siong Ang, Brian Teo, Uddamvathanak Rom, Minh N Nguyen, Sebastian Maurer-Stroh, Jinmiao Chen. "Rediscovering publicly available single-cell data with the DISCO platform." Nucleic Acids Research (2024): gkae1108](https://academic.oup.com/nar/advance-article/doi/10.1093/nar/gkae1108/7899529)
+
+## Follow us on our social media!
+- [HSCRM2](https://twitter.com/HSCRM2)
+- [JinmiaoChenLab Github repo](https://github.com/JinmiaoChenLab)

{discotoolkit-1.1.4 → discotoolkit-1.2.1}/discotoolkit/CELLiD.py

@@ -18,7 +18,7 @@ from pandarallel import pandarallel  # multiprocessing library
 pd.options.mode.chained_assignment = None
 
 # import variable and class from other script
-from .GlobalVariable import logging, prefix_disco_url, timeout
+from .GlobalVariable import logging, api_url, timeout
 from .DiscoClass import FilterData, Filter
 from .GetMetadata import check_in_list
 
@@ -56,11 +56,11 @@ def generate_correlation_map(x, y):
 
 
 # get the total atlas from DISCO website for the user to select which atlas to use
-def get_atlas(ref_data=None, ref_path=None):
+def get_atlas(ref_data=None, ref_path=None) -> list:
     """get the all the atlas string from the DISCO website and return to the user
 
     Returns:
-        List: return list of string
+        list: the atlas names, as a list of strings
     """
     # Download reference data and ref_deg if missing
     if ref_data is None:
@@ -72,23 +72,92 @@ def get_atlas(ref_data=None, ref_path=None):
         if not os.path.exists(ref_path):
             os.mkdir(ref_path)
 
-        # download reference data from the server in pickle extension and read as pandas dataframe
+        # download the reference data from the server (once) and read it as a pandas dataframe
         if ref_data is None:
-            if not (os.path.exists(ref_path + "/ref_data.pkl")):
-                logging.info("Downloading reference dataset...")
-                response = requests.get(
-                    url=prefix_disco_url + "toolkit/getRef?type=pkl", timeout=timeout
-                )
-                open(ref_path + "/ref_data.pkl", "wb").write(response.content)
-            ref_data = pd.read_pickle(
-                ref_path + "/ref_data.pkl",
-                compression={"method": "gzip", "compresslevel": 6},
-            )
+            ref_data = _load_reference(ref_path, "ref_data", "getRef", index_col=0)
 
     all_atlas = [each.split("--")[1] for each in ref_data.columns]
     return list(set(all_atlas))
 
 
+def _load_reference(ref_path: str, name: str, endpoint: str, **csv_options) -> pd.DataFrame:
+    """Get a CELLiD reference table (`name` is "ref_data" or "ref_deg"), downloading it once.
+
+    DISCO v1 serves it as plain CSV (`toolkit/<endpoint>?type=csv`, gzip-compressed on the wire),
+    read with pandas.read_csv. A copy already in `ref_path` is used as it is (a CSV, or the
+    pickle that earlier versions saved). Older servers only offer a pickle; that is the fallback,
+    with a warning, because unpickling data from a network is only safe if the server is trusted.
+    """
+    csv_file = "%s/%s.csv" % (ref_path, name)
+    pkl_file = "%s/%s.pkl" % (ref_path, name)
+
+    if os.path.exists(csv_file):
+        return pd.read_csv(csv_file, **csv_options)
+    if os.path.exists(pkl_file):
+        return pd.read_pickle(pkl_file, compression={"method": "gzip", "compresslevel": 6})
+
+    logging.info("Downloading reference dataset (%s)...", name)
+    with requests.get(
+        url=api_url("toolkit/" + endpoint), params={"type": "csv"}, stream=True, timeout=timeout
+    ) as response:
+        if response.status_code == 200:
+            # write to a temporary name so an interrupted download is not mistaken for the file
+            with open(csv_file + ".part", "wb") as handle:
+                for chunk in response.iter_content(chunk_size=1 << 20):
+                    handle.write(chunk)
+            os.replace(csv_file + ".part", csv_file)
+            return pd.read_csv(csv_file, **csv_options)
+
+    logging.warning(
+        "This server has no CSV for %s (HTTP %s); falling back to the pickle download.",
+        name,
+        response.status_code,
+    )
+    response = requests.get(
+        url=api_url("toolkit/" + endpoint), params={"type": "pkl"}, timeout=timeout
+    )
+    response.raise_for_status()
+    with open(pkl_file, "wb") as handle:
+        handle.write(response.content)
+    return pd.read_pickle(pkl_file, compression={"method": "gzip", "compresslevel": 6})
+
+
+def _load_geneset(ref_path: str) -> pd.DataFrame:
+    """Get the gene-set reference (columns logfc, gene, atlas, name), downloading it once.
+
+    DISCO v1 serves it as plain CSV (`toolkit/getGeneSet?format=csv`), which is read with
+    pandas.read_csv. Older servers only offer a pickle (`getGeneSetPkl`); that is used as a
+    fallback, with a warning, because unpickling data from a network is only safe if the
+    server is trusted.
+    """
+    csv_file = ref_path + "/ref_geneset.csv"
+    pkl_file = ref_path + "/ref_geneset.pkl"
+
+    if os.path.exists(csv_file):
+        return pd.read_csv(csv_file)
+    if os.path.exists(pkl_file):
+        return pd.read_pickle(pkl_file, compression={"method": "gzip", "compresslevel": 6})
+
+    logging.info("Downloading gene set reference...")
+    response = requests.get(
+        url=api_url("toolkit/getGeneSet"), params={"format": "csv"}, timeout=timeout
+    )
+    if response.status_code == 200:
+        with open(csv_file, "wb") as handle:
+            handle.write(response.content)
+        return pd.read_csv(csv_file)
+
+    logging.warning(
+        "This server has no CSV gene set (HTTP %s); falling back to the pickle download.",
+        response.status_code,
+    )
+    response = requests.get(url=api_url("getGeneSetPkl"), timeout=timeout)
+    response.raise_for_status()
+    with open(pkl_file, "wb") as handle:
+        handle.write(response.content)
+    return pd.read_pickle(pkl_file, compression={"method": "gzip", "compresslevel": 6})
+
+
 def CELLiD_cluster(
     rna,
     ref_data: pd.DataFrame = None,
@@ -97,7 +166,7 @@ def CELLiD_cluster(
     n_predict: int = 1,
     ref_path: str = None,
     ncores: int = 10,
-):
+) -> pd.DataFrame:
     """Cell type annotation using reference data and compute the correlation between the user cell gene expression as compare
         to the reference data. The celltype with highest correlation will be concluded as the celltype
 
@@ -139,31 +208,13 @@ def CELLiD_cluster(
         if not os.path.exists(ref_path):
             os.mkdir(ref_path)
 
-        # download reference data from the server in pickle extension and read as pandas dataframe
+        # download the reference data from the server (once) and read it as a pandas dataframe
         if ref_data is None:
-            if not (os.path.exists(ref_path + "/ref_data.pkl")):
-                logging.info("Downloading reference dataset...")
-                response = requests.get(
-                    url=prefix_disco_url + "toolkit/getRef?type=pkl", timeout=timeout
-                )
-                open(ref_path + "/ref_data.pkl", "wb").write(response.content)
-            ref_data = pd.read_pickle(
-                ref_path + "/ref_data.pkl",
-                compression={"method": "gzip", "compresslevel": 6},
-            )
+            ref_data = _load_reference(ref_path, "ref_data", "getRef", index_col=0)
 
         # similarly do the same for the DEG reference
         if ref_deg is None:
-            if not (os.path.exists(ref_path + "/ref_deg.pkl")):
-                logging.info("Downloading deg dataset...")
-                response = requests.get(
-                    url=prefix_disco_url + "toolkit/getRefDeg?type=pkl", timeout=timeout
-                )
-                open(ref_path + "/ref_deg.pkl", "wb").write(response.content)
-            ref_deg = pd.read_pickle(
-                ref_path + "/ref_deg.pkl",
-                compression={"method": "gzip", "compresslevel": 6},
-            )
+            ref_deg = _load_reference(ref_path, "ref_deg", "getRefDeg")
 
     ####
     # write list of atlas function
@@ -254,7 +305,7 @@ def CELLiD_cluster(
         predict.columns = ["cor"]
         predict = predict.sort_values(["cor"], ascending=False)
         res = [
-            [each.split("--")[0], each.split("--")[1], predict["cor"][index], i]
+            [each.split("--")[0], each.split("--")[1], predict["cor"].iloc[index], i]
             for index, each in enumerate(predict.index)
             if index < n_predict
         ]
@@ -305,7 +356,7 @@ def CELLiD_enrichment(
     reference: pd.DataFrame = None,
     ref_path: str = None,
     ncores: int = 1,
-):
+) -> pd.DataFrame:
     """Function to generate enrichment analysis based on the reference gene sets and following the DISCO pipeline.
 
     Args:
@@ -347,24 +398,7 @@ def CELLiD_enrichment(
         if not os.path.exists(ref_path):
             os.mkdir(ref_path)
 
-        # check if the file does not exist
-        if not (os.path.exists(ref_path + "/ref_geneset.pkl")):
-            # downloading the geneset data from disco database
-            response = requests.get(
-                url=prefix_disco_url + "/getGeneSetPkl", timeout=timeout
-            )
-            open(ref_path + "/ref_geneset.pkl", "wb").write(response.content)
-            reference = pd.read_pickle(
-                ref_path + "/ref_geneset.pkl",
-                compression={"method": "gzip", "compresslevel": 6},
-            )
-
-        else:
-            # read the data into pandas dataframe for subsequent analysis
-            reference = pd.read_pickle(
-                ref_path + "/ref_geneset.pkl",
-                compression={"method": "gzip", "compresslevel": 6},
-            )
+        reference = _load_geneset(ref_path)
 
     # rename the name data to include the reference atlas
     reference["name"] = reference["name"] + " in " + reference["atlas"]

{discotoolkit-1.1.4 → discotoolkit-1.2.1}/discotoolkit/DiscoClass.py

@@ -3,21 +3,25 @@ Class for filtering dataset
 """
 
 class Filter:
-    """
-    Filter class object to save the attributes for filtering the dataset from DISCO
-
-    sample_id                      String    e.g. ERX2757110;
-    project_id                     String;
-    tissue                      String    e.g. lung, bladder;
-    disease                     String    e.g. COVID-19;
-    platform                    String    e.g. 10x3';
-    sample_type                 String;
-    cell_type                   String;
-    cell_type_confidence        String    e.g. high;
-    include_cell_type_children  Bool      e.g. True;
-    min_cell_per_sample         Int       e.g. 300;
-
-    return Class object
+    """Which DISCO samples and cells to look for.
+
+    Every argument is optional; a filter with none of them matches everything. Give a string or a
+    list of strings. The list of values each field accepts is `list_metadata_item(field)`.
+
+    Args:
+        sample_id (str or list, optional): sample identifier, e.g. "ERX2757110".
+        project_id (str or list, optional): project (a study or dataset), e.g. "GSE147520".
+        tissue (str or list, optional): e.g. "lung", "bladder".
+        disease (str or list, optional): e.g. "COVID-19".
+        platform (str or list, optional): sequencing platform, e.g. "10x3'".
+        sample_type (str or list, optional): e.g. "control".
+        cell_type (str or list, optional): keep samples that contain these cell types, and download
+            only those cells.
+        cell_type_confidence (str): how sure DISCO's annotation must be: "high", "medium" or "all".
+            Defaults to "medium".
+        include_cell_type_children (bool): also match the more specific cell types under
+            `cell_type`. Defaults to True.
+        min_cell_per_sample (int): drop samples with fewer matching cells than this. Defaults to 100.
     """
 
     def __init__(self, sample_id = None, project_id = None, tissue = None, disease = None, platform = None, sample_type = None,
@@ -43,8 +47,16 @@ class Filter:
 
 class FilterData:    
 
-    """
-    Wrapper class on top of the Filter object to get dataset's summary such as cell count and sample count and the metadata
+    """The result of a filter: the matching samples, with their counts.
+
+    Returned by `filter_disco_metadata` and passed to `download_disco_data`.
+
+    Attributes:
+        sample_metadata (pandas.DataFrame): one row per matching sample.
+        cell_type_metadata (pandas.DataFrame): the cell types found in each sample.
+        sample_count (int): number of matching samples.
+        cell_count (int): number of matching cells.
+        filter (Filter): the filter that produced this result.
     """
     def __init__(self, sample_metadata = None, cell_type_metadata = None, sample_count = None, cell_count = None, filter = Filter()):
         self.sample_metadata = sample_metadata

{discotoolkit-1.1.4 → discotoolkit-1.2.1}/discotoolkit/DownloadDiscoData.py

@@ -17,19 +17,23 @@ import hashlib
 import scanpy as sc
 
 # import variable and class from other script
-from .GlobalVariable import logging, prefix_disco_url
+from .GlobalVariable import logging, api_url
 from .DiscoClass import FilterData, Filter
 from .GetMetadata import check_in_list
 
 
-def download_disco_data(metadata, output_dir: str = "DISCOtmp"):
-    """function to download the data based on the given filter
+def download_disco_data(metadata, output_dir: str = "DISCOtmp") -> None:
+    """Download the samples of a filter result, one AnnData `.h5ad` file per sample.
+
+    Each file holds only the cells that matched the filter, with DISCO's annotation in
+    `obs["cell_type"]`.
+
     Args:
-        metadata (FilterData) : FilterData class to filters data from DISCO database
-        output_dir (Sting) : directory for storing the downloaded data. Default DISCOtmp
+        metadata (FilterData): the result of `filter_disco_metadata`.
+        output_dir (str): directory to save the files in; created if missing. Defaults to "DISCOtmp".
 
     Returns:
-        None: This function does not return any object and instead download the data for the user
+        None: the files are written to `output_dir`.
     """
 
     # define a list to store the error sample that can not be download
@@ -52,11 +56,11 @@ def download_disco_data(metadata, output_dir: str = "DISCOtmp"):
         if os.path.exists(output_file):
             os.remove(output_file)
 
-        url = prefix_disco_url + "download/getRawH5/" + p + "/" + s
+        url = api_url("download/getRawH5/" + p + "/" + s)
         rna = sc.read_10x_h5(filename=output_file, backup_url=url)
 
         cell = pd.read_csv(
-            prefix_disco_url + "toolkit/" + "getCellTypeSample?sampleId=" + s,
+            api_url("toolkit/getCellTypeSample?sampleId=" + s),
             sep="\t",
             header=0,
         )

{discotoolkit-1.1.4 → discotoolkit-1.2.1}/discotoolkit/GeneSearch.py

@@ -7,8 +7,10 @@ import numpy as np
 from typing import Union
 import colorcet as cc
 
+from .GlobalVariable import api_url
 
-def gene_search(gene : str, atlas : Union[str, list] = None, figsize : tuple = None, dpi : int = 300):
+
+def gene_search(gene : str, atlas : Union[str, list] = None, figsize : tuple = None, dpi : int = 300) -> None:
 
     """Function to search for the gene expression level the same as the input gene search bar in DISCO website.
 
@@ -27,8 +29,8 @@ def gene_search(gene : str, atlas : Union[str, list] = None, figsize : tuple = N
         atlas = [atlas]
 
     # url to get the API data
-    url = "https://www.immunesinglecell.org/api/vishuo/geneExp/getRefExp?gene=%s" % (gene)
-    response = requests.get(url)
+    response = requests.get(api_url("geneExp/getRefExp"), params={"gene": gene})
+    response.raise_for_status()
     data = response.json()
 
     # Extract relevant information from JSON data
@@ -56,8 +58,8 @@ def gene_search(gene : str, atlas : Union[str, list] = None, figsize : tuple = N
     if atlas is not None:
         sample_df = sample_df[sample_df["atlases"].isin(atlas)].copy()
 
-    # Define the colorcet paletteasdasd
-    custom_palette = cc.glasbey_hv
+    # Define the colorcet palette, one colour per atlas shown
+    custom_palette = cc.glasbey_hv[: max(sample_df["atlases"].nunique(), 1)]
 
     # saturation for the plot color
     saturation=0.8
@@ -78,7 +80,7 @@ def gene_search(gene : str, atlas : Union[str, list] = None, figsize : tuple = N
     fig = plt.figure(figsize=figsize)
 
     # Create the violin plot with different colors based on the 'Category' variable and adding boxplot to assist user with median value
-    ax = sns.violinplot(data=sample_df, x='cell types', y='value', hue="atlases", width=0.8, dodge=False, cut=1, saturation = saturation,  plot_kws={'alpha':0.1},
+    ax = sns.violinplot(data=sample_df, x='cell types', y='value', hue="atlases", width=0.8, dodge=False, cut=1, saturation = saturation,
                         inner=None, linewidth=0.0, palette=custom_palette)
 
     ax_2 = sns.boxplot(x='cell types', y='value', hue="atlases", data=sample_df, palette=custom_palette, dodge=False, width=0.5, saturation = saturation, 
@@ -111,7 +113,7 @@ def gene_search(gene : str, atlas : Union[str, list] = None, figsize : tuple = N
     # Set labels and title
     plt.xlabel('Cell Types')
     plt.ylabel('Expression Value')
-    plt.title(gene, fontweight='bold')
+    plt.title(gene, fontweight='bold', loc='left')  # left: the legend sits above the centre
 
     # Show the plot
     plt.show()