anndata_tokenizer (#170)

- Added anndata tokenizer and switched to Dataset.from_generator (b6ca56647a16de97f6f95785eb76cb1a965f9960)
- Generalized (5cb733f4fed85e1568ba9671e5b1f9babd7b8491)
- Addressed issues for tokenizer, anndata tokenizer now uses a fraction of memory (b24676d0956565ff7b4f8b57d1e936ad17f8740e)
- Fixed issues (94e8d231c41a89232a55c064e5c8ea95edd51d2e)
- Fixed issue, loom and h5ad now produce same checksums (9c62f4c6e3ab0afd1943079306655bd20eba2246)
- Rename loom tokenizer function and modify example notebook for adata. (4fdb85061180ccf022ab761c2557be6ba67d848e)


Co-authored-by: Rico Meinl <[email protected]>

examples/tokenizing_scRNAseq_data.ipynb

@@ -7,7 +7,7 @@
     "tags": []
    },
    "source": [
-    "## Tokenizing .loom single cell RNA-seq data to rank value encoding .dataset format"
+    "## Tokenizing .loom or .h5ad single cell RNA-seq data to rank value encoding .dataset format"
    ]
   },
   {
@@ -15,15 +15,17 @@
    "id": "350e6252-b783-494b-9767-f087eb868a15",
    "metadata": {},
    "source": [
-    "#### Input data is a directory with .loom files containing raw counts from single cell RNAseq data, including all genes detected in the transcriptome without feature selection. \n",
+    "#### Input data is a directory with .loom or .h5ad files containing raw counts from single cell RNAseq data, including all genes detected in the transcriptome without feature selection. The input file type is specified by the argument file_format in the tokenize_data function.\n",
     "\n",
-    "#### Genes should be labeled with Ensembl IDs (row attribute \"ensembl_id\"), which provide a unique identifer for conversion to tokens. Other forms of gene annotations (e.g. gene names) can be converted to Ensembl IDs via Ensembl Biomart. Cells should be labeled with the total read count in the cell (column attribute \"n_counts\") to be used for normalization.\n",
+    "#### The discussion below references the .loom file format, but the analagous labels are required for .h5ad files, just that they will be column instead of row attributes and vice versa due to the transposed format of the two file types.\n",
+    "\n",
+    "#### Genes should be labeled with Ensembl IDs (loom row attribute \"ensembl_id\"), which provide a unique identifer for conversion to tokens. Other forms of gene annotations (e.g. gene names) can be converted to Ensembl IDs via Ensembl Biomart. Cells should be labeled with the total read count in the cell (loom column attribute \"n_counts\") to be used for normalization.\n",
     "\n",
     "#### No cell metadata is required, but custom cell attributes may be passed onto the tokenized dataset by providing a dictionary of custom attributes to be added, which is formatted as loom_col_attr_name : desired_dataset_col_attr_name. For example, if the original .loom dataset has column attributes \"cell_type\" and \"organ_major\" and one would like to retain these attributes as labels in the tokenized dataset with the new names \"cell_type\" and \"organ\", respectively, the following custom attribute dictionary should be provided: {\"cell_type\": \"cell_type\", \"organ_major\": \"organ\"}. \n",
     "\n",
     "#### Additionally, if the original .loom file contains a cell column attribute called \"filter_pass\", this column will be used as a binary indicator of whether to include these cells in the tokenized data. All cells with \"1\" in this attribute will be tokenized, whereas the others will be excluded. One may use this column to indicate QC filtering or other criteria for selection for inclusion in the final tokenized dataset.\n",
     "\n",
-    "#### If one's data is in other formats besides .loom, one can use the relevant tools (such as Anndata tools) to convert the file to a .loom format prior to running the transcriptome tokenizer."
+    "#### If one's data is in other formats besides .loom or .h5ad, one can use the relevant tools (such as Anndata tools) to convert the file to a .loom or .h5ad format prior to running the transcriptome tokenizer."
    ]
   },
   {
@@ -43,8 +45,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "tk = TranscriptomeTokenizer({\"cell_type\": \"cell_type\", \"organ_major\": \"organ_major\"}, nproc=4)\n",
-    "tk.tokenize_data(\"loom_data_directory\", \"output_directory\", \"output_prefix\")"
+    "tk = TranscriptomeTokenizer({\"cell_type\": \"cell_type\", \"organ_major\": \"organ\"}, nproc=16)\n",
+    "tk.tokenize_data(\"loom_data_directory\", \n",
+    "                 \"output_directory\", \n",
+    "                 \"output_prefix\", \n",
+    "                 file_format=\"loom\")"
    ]
   }
  ],

geneformer/tokenizer.py

@@ -14,6 +14,8 @@ Usage:
   tk.tokenize_data("loom_data_directory", "output_directory", "output_prefix")
 """
 
+from __future__ import annotations
+from typing import Literal
 import pickle
 from pathlib import Path
 
@@ -22,8 +24,10 @@ import logging
 import warnings
 warnings.filterwarnings("ignore", message=".*The 'nopython' keyword.*")
 
+import anndata as ad
 import loompy as lp
 import numpy as np
+import scipy.sparse as sp
 from datasets import Dataset
 
 logger = logging.getLogger(__name__)
@@ -32,6 +36,15 @@ GENE_MEDIAN_FILE = Path(__file__).parent / "gene_median_dictionary.pkl"
 TOKEN_DICTIONARY_FILE = Path(__file__).parent / "token_dictionary.pkl"
 
 
+def rank_genes(gene_vector, gene_tokens):
+    """
+    Rank gene expression vector.
+    """
+    # sort by median-scaled gene values
+    sorted_indices = np.argsort(-gene_vector)
+    return gene_tokens[sorted_indices]
+
+
 def tokenize_cell(gene_vector, gene_tokens):
     """
     Convert normalized gene expression vector to tokenized rank value encoding.
@@ -39,11 +52,8 @@ def tokenize_cell(gene_vector, gene_tokens):
     # create array of gene vector with token indices
     # mask undetected genes
     nonzero_mask = np.nonzero(gene_vector)[0]
-    # sort by median-scaled gene values
-    sorted_indices = np.argsort(-gene_vector[nonzero_mask])
-    # tokenize
-    sentence_tokens = gene_tokens[nonzero_mask][sorted_indices]
-    return sentence_tokens
+    # rank by median-scaled gene values
+    return rank_genes(gene_vector[nonzero_mask], gene_tokens[nonzero_mask])
 
 
 class TranscriptomeTokenizer:
@@ -92,53 +102,133 @@ class TranscriptomeTokenizer:
         # protein-coding and miRNA gene list dictionary for selecting .loom rows for tokenization
         self.genelist_dict = dict(zip(self.gene_keys, [True] * len(self.gene_keys)))
 
-    def tokenize_data(self, loom_data_directory, output_directory, output_prefix):
+    def tokenize_data(
+        self,
+        data_directory: Path | str,
+        output_directory: Path | str,
+        output_prefix: str,
+        file_format: Literal["loom", "h5ad"] = "loom",
+        use_generator: bool = False,
+    ):
         """
         Tokenize .loom files in loom_data_directory and save as tokenized .dataset in output_directory.
 
         Parameters
         ----------
         loom_data_directory : Path
-            Path to directory containing loom files
+            Path to directory containing loom files or anndata files
         output_directory : Path
             Path to directory where tokenized data will be saved as .dataset
         output_prefix : str
             Prefix for output .dataset
+        file_format : str
+            Format of input files. Can be "loom" or "h5ad".
+        use_generator : bool
+            Whether to use generator or dict for tokenization.
         """
-        tokenized_cells, cell_metadata = self.tokenize_files(Path(loom_data_directory))
-        tokenized_dataset = self.create_dataset(tokenized_cells, cell_metadata)
+        tokenized_cells, cell_metadata = self.tokenize_files(
+            Path(data_directory), file_format
+        )
+        tokenized_dataset = self.create_dataset(tokenized_cells, cell_metadata, use_generator=use_generator)
 
         output_path = (Path(output_directory) / output_prefix).with_suffix(".dataset")
         tokenized_dataset.save_to_disk(output_path)
 
-    def tokenize_files(self, loom_data_directory):
+    def tokenize_files(
+        self, data_directory, file_format: Literal["loom", "h5ad"] = "loom"
+    ):
         tokenized_cells = []
         if self.custom_attr_name_dict is not None:
-            loom_cell_attr = [attr_key for attr_key in self.custom_attr_name_dict.keys()]
+            cell_attr = [attr_key for attr_key in self.custom_attr_name_dict.keys()]
             cell_metadata = {attr_key: [] for attr_key in self.custom_attr_name_dict.values()}
 
         # loops through directories to tokenize .loom files
         file_found = 0
-        for loom_file_path in loom_data_directory.glob("*.loom"):
+        # loops through directories to tokenize .loom or .h5ad files
+        tokenize_file_fn = (
+            self.tokenize_loom if file_format == "loom" else self.tokenize_anndata
+        )
+        for file_path in data_directory.glob("*.{}".format(file_format)):
             file_found = 1
-            print(f"Tokenizing {loom_file_path}")
-            file_tokenized_cells, file_cell_metadata = self.tokenize_file(
-                loom_file_path
-            )
+            print(f"Tokenizing {file_path}")
+            file_tokenized_cells, file_cell_metadata = tokenize_file_fn(file_path)
             tokenized_cells += file_tokenized_cells
             if self.custom_attr_name_dict is not None:
-                for k in loom_cell_attr:
+                for k in cell_attr:
                     cell_metadata[self.custom_attr_name_dict[k]] += file_cell_metadata[k]
             else:
                 cell_metadata = None
 
         if file_found == 0:
             logger.error(
-                f"No .loom files found in directory {loom_data_directory}.")
+                f"No .{file_format} files found in directory {data_directory}.")
             raise
         return tokenized_cells, cell_metadata
 
-    def tokenize_file(self, loom_file_path):
+    def tokenize_anndata(self, adata_file_path, target_sum=10_000, chunk_size=512):
+        adata = ad.read(adata_file_path, backed="r")
+
+        if self.custom_attr_name_dict is not None:
+            file_cell_metadata = {
+                attr_key: [] for attr_key in self.custom_attr_name_dict.keys()
+            }
+
+        coding_miRNA_loc = np.where(
+            [self.genelist_dict.get(i, False) for i in adata.var["ensembl_id"]]
+        )[0]
+        norm_factor_vector = np.array(
+            [
+                self.gene_median_dict[i]
+                for i in adata.var["ensembl_id"][coding_miRNA_loc]
+            ]
+        )
+        coding_miRNA_ids = adata.var["ensembl_id"][coding_miRNA_loc]
+        coding_miRNA_tokens = np.array(
+            [self.gene_token_dict[i] for i in coding_miRNA_ids]
+        )
+
+        try:
+            _ = adata.obs["filter_pass"]
+        except KeyError:
+            var_exists = False
+        else:
+            var_exists = True
+
+        if var_exists:
+            filter_pass_loc = np.where(
+                [i == 1 for i in adata.obs["filter_pass"]]
+            )[0]
+        elif not var_exists:
+            print(
+                f"{adata_file_path} has no column attribute 'filter_pass'; tokenizing all cells."
+            )
+            filter_pass_loc = np.array([i for i in range(adata.shape[0])])
+
+        tokenized_cells = []
+
+        for i in range(0, len(filter_pass_loc), chunk_size):
+            idx = filter_pass_loc[i:i+chunk_size]
+
+            n_counts = adata[idx].obs['n_counts'].values[:, None]
+            X_view = adata[idx, coding_miRNA_loc].X
+            X_norm = (X_view / n_counts * target_sum / norm_factor_vector)
+            X_norm = sp.csr_matrix(X_norm)
+
+            tokenized_cells += [
+                rank_genes(X_norm[i].data, coding_miRNA_tokens[X_norm[i].indices])
+                for i in range(X_norm.shape[0])
+            ]
+
+            # add custom attributes for subview to dict
+            if self.custom_attr_name_dict is not None:
+                for k in file_cell_metadata.keys():
+                    file_cell_metadata[k] += adata[idx].obs[k].tolist()
+            else:
+                file_cell_metadata = None
+
+        return tokenized_cells, file_cell_metadata
+
+    def tokenize_loom(self, loom_file_path, target_sum=10_000):
         if self.custom_attr_name_dict is not None:
             file_cell_metadata = {
                 attr_key: [] for attr_key in self.custom_attr_name_dict.keys()
@@ -168,11 +258,11 @@ class TranscriptomeTokenizer:
             else:
                 var_exists = True
 
-            if var_exists is True:
+            if var_exists:
                 filter_pass_loc = np.where(
-                    [True if i == 1 else False for i in data.ca["filter_pass"]]
+                    [i == 1 for i in data.ca["filter_pass"]]
                 )[0]
-            elif var_exists is False:
+            elif not var_exists:
                 print(
                     f"{loom_file_path} has no column attribute 'filter_pass'; tokenizing all cells."
                 )
@@ -189,7 +279,7 @@ class TranscriptomeTokenizer:
                 subview_norm_array = (
                     subview[:, :]
                     / subview.ca.n_counts
-                    * 10_000
+                    * target_sum
                     / norm_factor_vector[:, None]
                 )
                 # tokenize subview gene vectors
@@ -207,18 +297,25 @@ class TranscriptomeTokenizer:
 
         return tokenized_cells, file_cell_metadata
 
-    def create_dataset(self, tokenized_cells, cell_metadata):
+    def create_dataset(self, tokenized_cells, cell_metadata, use_generator=False):
+        print("Creating dataset.")
         # create dict for dataset creation
         dataset_dict = {"input_ids": tokenized_cells}
         if self.custom_attr_name_dict is not None:
             dataset_dict.update(cell_metadata)
 
         # create dataset
-        output_dataset = Dataset.from_dict(dataset_dict)
+        if use_generator:
+            def dict_generator():
+                for i in range(len(tokenized_cells)):
+                    yield {k: dataset_dict[k][i] for k in dataset_dict.keys()}
+            output_dataset = Dataset.from_generator(dict_generator, num_proc=self.nproc)
+        else:
+            output_dataset = Dataset.from_dict(dataset_dict)
 
         # truncate dataset
         def truncate(example):
-            example["input_ids"] = example["input_ids"][0:2048]
+            example["input_ids"] = example["input_ids"][:2048]
             return example
 
         output_dataset_truncated = output_dataset.map(truncate, num_proc=self.nproc)
@@ -232,4 +329,4 @@ class TranscriptomeTokenizer:
             measure_length, num_proc=self.nproc
         )
 
-        return output_dataset_truncated_w_length
+        return output_dataset_truncated_w_length