10X Genomics 的 Cell Ranger 软件相关的，用于处理条形码（barcode）的功能模块。
目录结构概述
3M-february-2018.txt.gz 9K-LT-march-2021.txt.gz visium-v1_coordinates.txt visium-v2.txt visium-v5.gal
737K-april-2014_rc.txt __init__.py visium-v1.gal visium-v3_coordinates.txt visium-v5.txt
737K-arc-v1.txt.gz __pycache__ visium-v1.txt visium-v3.gal
737K-august-2016.txt translation visium-v2_coordinates.txt visium-v3.txt
737K-fixed-rna-profiling.txt.gz utils.py visium-v2.gal visium-v5_coordinates.txt
主要文件和目录说明
-
条形码白名单文件 (
*.txt.gz,*.txt):-
示例:
3M-february-2018.txt.gz9K-LT-march-2021.txt.gzarc-v1.txt.gzaugust-2016.txtfixed-rna-profiling.txt.gz
-
说明:
- 这些文件通常包含用于过滤和识别有效条形码的列表。Cell Ranger 使用这些白名单文件来确定哪些条形码是有效的，以便在单细胞测序数据中准确地分配细胞。
- 文件格式通常为纯文本，可能经过 gzip 压缩以节省存储空间。
-
示例:
-
Visium 相关文件 (
visium-*.txt,visium-*.gal,visium-*_coordinates.txt):-
示例:
visium-v1_coordinates.txtvisium-v1.galvisium-v1.txtvisium-v2_coordinates.txtvisium-v2.galvisium-v2.txtvisium-v3_coordinates.txtvisium-v3.galvisium-v3.txtvisium-v5.galvisium-v5_coordinates.txtvisium-v5.txt
-
说明:
- Visium 是 10X Genomics 的空间转录组测序平台。这些文件可能包含与不同版本的 Visium 数据相关的条形码、坐标信息和其他元数据。
-
.gal文件可能包含基因表达相关的信息，.txt文件则可能包含纯文本的条形码或其他元数据，*_coordinates.txt文件则包含空间坐标信息。
-
示例:
-
Python 模块和辅助文件:
-
__init__.py:- 此文件表明该目录应被视为一个 Python 包。它可以包含初始化代码或导入模块。
-
__pycache__:- 这是 Python 自动生成的目录，用于存储编译后的字节码（
.pyc文件），以加快模块的加载速度。
- 这是 Python 自动生成的目录，用于存储编译后的字节码（
-
translation:- 这可能是一个目录或文件，用于存储条形码翻译映射，例如将一套条形码映射到另一套条形码。
-
utils.py:- 这是一个实用工具模块，包含处理条形码的各种函数。以下将详细介绍该文件的内容。
-
utils.py 文件详细介绍
utils.py 文件主要包含用于处理条形码白名单、翻译映射和内存需求估算的函数。以下是对其内容的详细解析：
模块头部
from __future__ import annotations
import os
from typing import List, Literal, Optional, Set, Union, overload
import numpy as np
import cellranger.constants as cr_constants
import cellranger.h5_constants as h5_constants
import cellranger.io as cr_io
-
导入模块:
- 使用
from __future__ import annotations提高类型注解的灵活性。 - 导入标准库模块
os和类型提示模块typing。 - 导入第三方库
numpy。 - 导入 10X Cell Ranger 软件的内部模块，如
constants,h5_constants, 和io，它们包含常量定义、HDF5 文件相关的常量和 I/O 操作函数。
- 使用
常量定义
SPATIAL_WHITELIST = [
"odin-5K-v2",
"visium-v1",
"visium-v2",
"visium-v3",
"visium-v4",
"visium-v5",
"omni-v1",
"omni-hires-v1",
"omni-pat7-v1",
"pseudo-xl-v1",
"thor-v1",
"thor-v2",
"thor-v3",
"thor-XL-v1",
]
NUM_BARCODES_PER_MEM_GB = 500000
-
SPATIAL_WHITELIST:- 一个包含空间条形码白名单名称的列表。用于识别哪些条形码白名单与空间测序（如 Visium）相关。
-
NUM_BARCODES_PER_MEM_GB:- 定义每 GB 内存可以处理的条形码数量，用于内存需求估算。
函数定义
-
is_whitelist_spatial(whitelist_name):def is_whitelist_spatial(whitelist_name): return whitelist_name in SPATIAL_WHITELIST- 功能: 判断给定的条形码白名单名称是否属于空间条形码白名单。
-
参数:
-
whitelist_name(字符串): 白名单名称。
-
-
返回值: 布尔值，若在
SPATIAL_WHITELIST中则返回True，否则False。
-
load_barcode_tsv(filename, as_set=False):def load_barcode_tsv(filename: Union[str, bytes], as_set=False) -> Union[Set[bytes], List[bytes]]: with cr_io.open_maybe_gzip(filename, "rb") as bc_file: barcodes = [x.strip() for x in bc_file if b"#" not in x] barcode_set = set(barcodes) if len(barcodes) != len(barcode_set): raise Exception(f"Duplicates found in barcode whitelist: {filename}") return barcode_set if as_set else barcodes- 功能: 加载条形码白名单文件，返回条形码列表或集合。
-
参数:
-
filename(字符串或字节串): 白名单文件路径，可以是.txt或.txt.gz格式。 -
as_set(布尔值, 默认为False): 若为True，返回集合；否则返回列表。
-
- 返回值: 条形码的集合或列表。
- 备注: 如果文件中存在重复条形码，将抛出异常。
-
get_barcode_whitelist_path(filename):def get_barcode_whitelist_path(filename: Optional[str]) -> Optional[str]: if filename is None: return None elif os.path.exists(filename): return filename else: gz = os.path.join(cr_constants.BARCODE_WHITELIST_PATH, filename + ".txt.gz") if os.path.exists(gz): return gz txt = os.path.join(cr_constants.BARCODE_WHITELIST_PATH, filename + ".txt") return txt- 功能: 获取条形码白名单文件的完整路径。
-
参数:
-
filename(可选字符串): 白名单文件名。
-
-
返回值: 完整的文件路径（字符串）或
None。 -
逻辑:
- 如果
filename为None，返回None。 - 若
filename路径存在，直接返回。 - 否则，尝试在预定义的白名单目录中查找
.txt.gz或.txt后缀的文件。
- 如果
-
get_all_whitelist_filenames():def get_all_whitelist_filenames() -> List[str]: basenames = os.listdir(cr_constants.BARCODE_WHITELIST_PATH) allowed_suffixes = (".txt", ".txt.gz") all_files = [] for name in basenames: full_name = os.path.join(cr_constants.BARCODE_WHITELIST_PATH, name) if ( name.endswith(allowed_suffixes) and name.count("coordinates") == 0 and os.path.isfile(full_name) ): all_files.append(full_name) return all_files- 功能: 获取所有有效的条形码白名单文件名。
- 返回值: 字符串列表，每个字符串为一个白名单文件的完整路径。
-
逻辑:
- 列出白名单目录中的所有文件。
- 过滤出以
.txt或.txt.gz结尾且不包含 "coordinates" 的文件。
-
get_barcode_whitelist_paths(filenames):def get_barcode_whitelist_paths(filenames: str): paths = filenames.split(",") return ",".join([get_barcode_whitelist_path(p) for p in paths])- 功能: 获取多个白名单文件的完整路径，输入为逗号分隔的文件名字符串。
-
参数:
-
filenames(字符串): 逗号分隔的文件名列表。
-
- 返回值: 逗号分隔的完整路径字符串。
-
load_barcode_whitelist(filename, as_set=False):def load_barcode_whitelist(filename: Optional[str], as_set: bool = False): path = get_barcode_whitelist_path(filename) if path is None: return None if not os.path.isfile(path): raise NameError("Unable to find barcode whitelist: %s" % path) return load_barcode_tsv(path, as_set)- 功能: 加载指定的条形码白名单文件。
-
参数:
-
filename(可选字符串): 白名单文件名。 -
as_set(布尔值, 默认为False): 决定返回集合还是列表。
-
-
返回值: 条形码的集合或列表，或
None（若filename为None）。 -
逻辑:
- 获取文件路径。
- 如果路径不存在，抛出异常。
- 使用
load_barcode_tsv加载文件内容。
-
load_barcode_translate_map(bc_whitelist):def load_barcode_translate_map(bc_whitelist): if bc_whitelist is None: return None file_path = None for extension in [".txt", ".txt.gz"]: file_ext = os.path.join( cr_constants.BARCODE_WHITELIST_TRANSLATE_PATH, bc_whitelist + extension ) if os.path.exists(file_ext): file_path = file_ext break if file_path is None: return None else: translate_map = {} for line in cr_io.open_maybe_gzip(file_path, "r"): if line.startswith("#"): continue bcs = line.strip().split() translate_map[bcs[0]] = bcs[1] return translate_map- 功能: 加载条形码白名单的翻译映射，将一种条形码映射到另一种条形码。
-
参数:
-
bc_whitelist(字符串): 条形码白名单名称。
-
-
返回值: 字典，键为原始条形码，值为翻译后的条形码，或
None（若无翻译文件）。 -
逻辑:
- 在预定义的翻译目录中查找对应的
.txt或.txt.gz文件。 - 读取文件，跳过注释行（以
#开头）。 - 构建翻译字典。
- 在预定义的翻译目录中查找对应的
-
load_probe_barcode_map(bc_whitelist):def load_probe_barcode_map(bc_whitelist): if bc_whitelist is None: return None file_path = None for extension in [".txt", ".txt.gz"]: file_ext = os.path.join( cr_constants.BARCODE_WHITELIST_TRANSLATE_PATH, bc_whitelist + extension ) if os.path.exists(file_ext): file_path = file_ext break if file_path is None: return None else: translate_map = {} for line in cr_io.open_maybe_gzip(file_path, "r"): if line.startswith("#"): continue bcs = line.strip().split() translate_map[bcs[2]] = bcs[1] return translate_map- 功能: 加载探针条形码的映射，将探针条形码 ID 映射到其折叠序列。
-
参数:
-
bc_whitelist(字符串): 条形码白名单名称。
-
-
返回值: 字典，键为探针条形码 ID，值为折叠序列，或
None（若无映射文件）。 -
逻辑:
- 类似于
load_barcode_translate_map，但映射关系取决于文件内容的特定列。
- 类似于
-
get_mem_gb_request_from_barcode_whitelist(barcode_whitelist_fn, gem_groups=None, use_min=True, double=False):def get_mem_gb_request_from_barcode_whitelist( barcode_whitelist_fn, gem_groups=None, use_min=True, double=False ): barcode_whitelist = load_barcode_whitelist(barcode_whitelist_fn) if use_min: if barcode_whitelist is None: min_mem_gb = h5_constants.MIN_MEM_GB_NOWHITELIST else: min_mem_gb = h5_constants.MIN_MEM_GB else: min_mem_gb = 0 if barcode_whitelist is None: return min_mem_gb if gem_groups is not None: num_bcs = len(barcode_whitelist) * max(gem_groups) else: num_bcs = len(barcode_whitelist) if double: return np.ceil(max(min_mem_gb, 2 * num_bcs // NUM_BARCODES_PER_MEM_GB)) else: return np.ceil(max(min_mem_gb, num_bcs // NUM_BARCODES_PER_MEM_GB))- 功能: 根据条形码白名单估算所需的内存（以 GB 为单位）。
-
参数:
-
barcode_whitelist_fn(字符串): 条形码白名单文件名。 -
gem_groups(可选列表): GEM（Gel Bead-In Emulsion）组数，用于估算条形码数量。 -
use_min(布尔值, 默认为True): 是否使用最小内存限制。 -
double(布尔值, 默认为False): 是否将估算的内存需求加倍。
-
- 返回值: 所需内存的估算值（浮点数），以 GB 为单位。
-
逻辑:
- 加载条形码白名单。
- 根据是否使用最小内存限制，确定基础内存需求。
- 根据条形码数量和 GEM 组数，计算总条形码数。
- 根据
double参数调整最终的内存需求。
总结
utils.py 文件在整个模块中扮演了关键角色，负责加载和处理条形码白名单文件，管理条形码的翻译映射，以及根据条形码数量估算所需的内存。这些功能对于确保单细胞或空间转录组数据的准确处理和高效分析至关重要。
此外，目录中的其他文件如 __init__.py、__pycache__、以及各种条形码和 Visium 相关的文件，都是支持 utils.py 功能运行所需的资源和模块。通过这些文件的协同工作，Cell Ranger 能够高效地处理和分析复杂的单细胞和空间转录组数据。
