用途:读取已注释单细胞 AnnData 的 obs[cell_name_col] 中自由文本细胞类型标签,映射为 Cell Ontology(CL)规范术语,写入 obs['cell_ontology'](术语名)、obs['cell_ontology_cl_id'](如 CL:0000084)、obs['cell_ontology_score'](余弦相似度)。
主要能力与三种模式:
- 普通映射:句向量余弦相似度匹配,适合完整描述性标签,速度最快。
- LLM 缩写扩展:调用 LLM 先将缩写(如 'TIL-1')扩展为完整描述再匹配,适合短标签或缩写多的场景。
- Cell Taxonomy 增强:加载 Jin 2023 Cell Taxonomy 资源,结合物种与组织上下文,同时匹配物种特异分类与 CL。
使用方式:用 ov.single.download_cl(output_dir='new_ontology', filename='cl.json') 下载 CL;构造 mapper = ov.single.CellOntologyMapper(cl_obo_file='new_ontology/cl.json', embeddings_path='new_ontology/ontology_embeddings.pkl', local_model_dir='./my_models');随后调用 mapper.map_adata(adata, cell_name_col='cell_label'),或 map_adata_with_expansion / map_adata_with_taxonomy。默认阈值 0.5,缩写扩展场景可用 0.3。LLM 配置用 mapper.setup_llm_expansion(api_type='openai' 或 'custom_openai', api_key=..., model=..., base_url=..., cache_file='abbreviation_cache.json', tissue_context=..., species=..., study_context=...),支持 OpenAI 兼容端点。
辅助与检查:search_ontology_cells、list_ontology_cells、find_similar_cells、get_cell_info、check_ontology_status、print_mapping_summary、show_expansion_summary;embeddings 与缩写扩展结果可缓存和持久化。默认句向量模型 all-mpnet-base-v2,首次约 30 秒计算约 3000 术语嵌入;CPU 即可。
适用场景:把作者自定义的细胞类型标签统一到 CL 标准术语,便于跨数据集比较与下游分析。
限制:只做注释后映射,不负责从零构建细胞类型注释或纯 LLM 注释;跨模态标签转移、参考图谱标签转移、MetaTiME 肿瘤微环境注释属于其他技能。LLM 扩展需外网访问与有效 api_key;Cell Taxonomy 资源需单独下载。费用、价格、性能数值等资料未提供,暂未提供。