@hongmaple0820/med-scale-research-os 0.43.0

package/target-research-platform/src/api_clients/gtex_client.py

@@ -0,0 +1,209 @@
+"""
+GTEx API客户端
+用于获取正常组织基因表达数据
+API文档：https://gtexportal.org/api/v2/
+"""
+from typing import Optional
+from .base_client import BaseAPIClient, APIResponse
+
+
+class GTExClient(BaseAPIClient):
+    """GTEx Portal API客户端"""
+
+    @property
+    def source_name(self) -> str:
+        return "GTEx"
+
+    @property
+    def base_url(self) -> str:
+        return "https://gtexportal.org/api/v2"
+
+    def health_check(self) -> bool:
+        """检查GTEx API可用性"""
+        response = self._make_request("GET", "/dataset/tissueSiteDetail", use_cache=False)
+        return response.success
+
+    def get_gene_expression(self, gene_symbol: str) -> APIResponse:
+        """
+        获取基因在正常组织中的表达数据
+
+        Args:
+            gene_symbol: 基因符号，如 "CDK4"
+
+        Returns:
+            APIResponse包含 {tissue: median_tpm} 数据
+        """
+        # 先获取基因ID（GTEx API 使用 geneId 参数）
+        gene_response = self._make_request(
+            "GET",
+            "/reference/gene",
+            params={"geneId": gene_symbol}
+        )
+
+        if not gene_response.success or not gene_response.data:
+            return gene_response
+
+        # 从返回数据中提取gencode_id
+        gene_data = gene_response.data
+        if isinstance(gene_data, dict) and 'data' in gene_data:
+            genes = gene_data['data']
+        elif isinstance(gene_data, list):
+            genes = gene_data
+        else:
+            return APIResponse(
+                success=False,
+                data=None,
+                source=self.source_name,
+                endpoint="/reference/gene",
+                params={"geneSymbol": gene_symbol},
+                timestamp=gene_response.timestamp,
+                error="无法解析基因数据"
+            )
+
+        # 查找匹配的基因
+        gencode_id = None
+        for gene in genes:
+            if gene.get('geneSymbol') == gene_symbol:
+                gencode_id = gene.get('gencodeId')
+                break
+
+        if not gencode_id:
+            return APIResponse(
+                success=False,
+                data=None,
+                source=self.source_name,
+                endpoint="/expression/geneExpression",
+                params={"geneSymbol": gene_symbol},
+                timestamp=gene_response.timestamp,
+                error=f"未找到基因 {gene_symbol}"
+            )
+
+        # 获取表达数据
+        expression_response = self._make_request(
+            "GET",
+            "/expression/geneExpression",
+            params={
+                "gencodeId": gencode_id,
+                "datasetId": "gtex_v8"
+            }
+        )
+
+        if not expression_response.success:
+            return expression_response
+
+        # 解析表达数据
+        return self._parse_expression(expression_response, gene_symbol)
+
+    def _parse_expression(self, response: APIResponse, gene_symbol: str) -> APIResponse:
+        """解析GTEx表达数据（v2 API 格式）"""
+        try:
+            import statistics
+
+            raw_data = response.data
+            if not raw_data or 'data' not in raw_data:
+                return response
+
+            # GTEx v2 API: raw_data['data'] 是 tissue items 的数组
+            # 每个 item: {data: [expr_values], tissueSiteDetailId: "Thyroid", unit: "TPM", ...}
+            expression_data = {}
+            tissue_items = raw_data['data']
+            if not isinstance(tissue_items, list):
+                return response
+
+            for item in tissue_items:
+                tissue = item.get('tissueSiteDetailId', '')
+                expr_values = item.get('data', [])
+                if tissue and expr_values and len(expr_values) > 0:
+                    # 计算中位数表达值
+                    median_tpm = statistics.median(expr_values)
+                    expression_data[tissue] = round(float(median_tpm), 2)
+
+            return APIResponse(
+                success=True,
+                data={
+                    "gene": gene_symbol,
+                    "tissues": expression_data,
+                    "unit": "TPM",
+                    "dataset": "GTEx v8"
+                },
+                source=self.source_name,
+                endpoint="/expression/geneExpression",
+                params={"geneSymbol": gene_symbol},
+                timestamp=response.timestamp,
+                raw_response=response.raw_response
+            )
+
+        except (KeyError, ValueError, TypeError) as e:
+            return APIResponse(
+                success=False,
+                data=None,
+                source=self.source_name,
+                endpoint="/expression/geneExpression",
+                params={"geneSymbol": gene_symbol},
+                timestamp=response.timestamp,
+                error=f"数据解析错误: {str(e)}"
+            )
+
+    def validate_expression(self, data: dict) -> tuple[bool, list[str]]:
+        """
+        验证表达数据合理性
+
+        Returns:
+            (是否通过, 问题列表)
+        """
+        issues = []
+
+        if not data or 'tissues' not in data:
+            return False, ["缺少表达数据"]
+
+        tissues = data['tissues']
+
+        # 检查组织数量
+        if len(tissues) < 30:
+            issues.append(f"组织数量不足: {len(tissues)} < 30")
+
+        # 检查TPM值范围
+        for tissue, tpm in tissues.items():
+            if tpm < 0:
+                issues.append(f"组织 {tissue} 的TPM值为负数: {tpm}")
+            if tpm > 100000:
+                issues.append(f"组织 {tissue} 的TPM值异常高: {tpm}")
+
+        return len(issues) == 0, issues
+
+    def get_tissue_specificity(self, gene_symbol: str) -> APIResponse:
+        """
+        计算组织特异性指数
+
+        返回基因在哪些组织中高表达（>中位数的2倍）
+        """
+        response = self.get_gene_expression(gene_symbol)
+        if not response.success:
+            return response
+
+        tissues = response.data.get('tissues', {})
+        if not tissues:
+            return response
+
+        values = list(tissues.values())
+        median_tpm = sorted(values)[len(values) // 2]
+
+        high_expression_tissues = {
+            tissue: tpm for tissue, tpm in tissues.items()
+            if tpm > median_tpm * 2
+        }
+
+        return APIResponse(
+            success=True,
+            data={
+                "gene": gene_symbol,
+                "median_tpm_all_tissues": median_tpm,
+                "high_expression_tissues": high_expression_tissues,
+                "tissue_count": len(tissues),
+                "high_expression_count": len(high_expression_tissues)
+            },
+            source=self.source_name,
+            endpoint="/expression/geneExpression",
+            params={"geneSymbol": gene_symbol},
+            timestamp=response.timestamp
+        )

package/target-research-platform/src/api_clients/hpa_client.py

@@ -0,0 +1,170 @@
+"""
+Human Protein Atlas (HPA) API客户端
+用于获取蛋白表达、亚细胞定位等数据
+API文档：https://www.proteinatlas.org/about/help/api
+"""
+from typing import Optional
+from .base_client import BaseAPIClient, APIResponse
+
+
+class HPAClient(BaseAPIClient):
+    """Human Protein Atlas API客户端"""
+
+    @property
+    def source_name(self) -> str:
+        return "HPA"
+
+    @property
+    def base_url(self) -> str:
+        return "https://www.proteinatlas.org"
+
+    def health_check(self) -> bool:
+        """检查HPA API可用性"""
+        response = self._make_request(
+            "GET",
+            "/ENSG00000146648.json",
+            use_cache=False
+        )
+        return response.success
+
+    def get_protein_expression(self, ensg_id: str) -> APIResponse:
+        """
+        获取蛋白表达数据（IHC）
+
+        Args:
+            ensg_id: Ensembl基因ID，如 "ENSG00000146648"
+
+        Returns:
+            包含蛋白表达数据的APIResponse
+        """
+        response = self._make_request("GET", f"/{ensg_id}.json")
+
+        if not response.success:
+            return response
+
+        return self._parse_protein_data(response, ensg_id)
+
+    def _parse_protein_data(self, response: APIResponse, ensg_id: str) -> APIResponse:
+        """解析HPA蛋白数据"""
+        try:
+            raw_data = response.data
+            if not raw_data:
+                return response
+
+            # HPA返回的是数组，取第一个
+            if isinstance(raw_data, list):
+                protein_data = raw_data[0] if raw_data else {}
+            else:
+                protein_data = raw_data
+
+            # 提取组织表达数据
+            tissue_expression = []
+            for tissue in protein_data.get('tissueExpression', []):
+                tissue_expression.append({
+                    "tissue": tissue.get('tissue', ''),
+                    "level": tissue.get('level', ''),  # High/Medium/Low/Not detected
+                    "cell_type": tissue.get('cellType', ''),
+                    "reliability": tissue.get('reliability', '')
+                })
+
+            # 提取亚细胞定位
+            subcellular = []
+            for loc in protein_data.get('subcellularLocation', []):
+                subcellular.append({
+                    "location": loc.get('location', ''),
+                    "reliability": loc.get('reliability', '')
+                })
+
+            return APIResponse(
+                success=True,
+                data={
+                    "ensg_id": ensg_id,
+                    "gene_name": protein_data.get('Gene', ''),
+                    "protein_name": protein_data.get('Gene description', ''),
+                    "tissue_expression": tissue_expression,
+                    "subcellular_location": subcellular,
+                    "antibody": protein_data.get('Antibody', '')
+                },
+                source=self.source_name,
+                endpoint=f"/{ensg_id}.json",
+                params={"ensg_id": ensg_id},
+                timestamp=response.timestamp
+            )
+
+        except (KeyError, ValueError, TypeError) as e:
+            return APIResponse(
+                success=False,
+                data=None,
+                source=self.source_name,
+                endpoint=f"/{ensg_id}.json",
+                params={"ensg_id": ensg_id},
+                timestamp=response.timestamp,
+                error=f"数据解析错误: {str(e)}"
+            )
+
+    def get_subcellular_location(self, ensg_id: str) -> APIResponse:
+        """
+        获取亚细胞定位信息
+
+        Args:
+            ensg_id: Ensembl基因ID
+
+        Returns:
+            包含亚细胞定位的APIResponse
+        """
+        response = self.get_protein_expression(ensg_id)
+        if not response.success:
+            return response
+
+        return APIResponse(
+            success=True,
+            data={
+                "ensg_id": ensg_id,
+                "subcellular_location": response.data.get("subcellular_location", [])
+            },
+            source=self.source_name,
+            endpoint=f"/{ensg_id}.json",
+            params={"ensg_id": ensg_id},
+            timestamp=response.timestamp
+        )
+
+    def validate_protein_data(self, data: dict) -> tuple[bool, list[str]]:
+        """验证蛋白数据合理性"""
+        issues = []
+
+        if not data:
+            return False, ["缺少数据"]
+
+        # 检查组织表达数据
+        tissue_expr = data.get("tissue_expression", [])
+        if len(tissue_expr) < 10:
+            issues.append(f"组织表达数据不足: {len(tissue_expr)} < 10")
+
+        # 检查亚细胞定位
+        subcellular = data.get("subcellular_location", [])
+        if not subcellular:
+            issues.append("缺少亚细胞定位数据")
+
+        return len(issues) == 0, issues
+
+    def search_gene_by_symbol(self, gene_symbol: str) -> APIResponse:
+        """
+        通过基因符号搜索Ensembl ID
+
+        Args:
+            gene_symbol: 基因符号
+
+        Returns:
+            包含Ensembl ID的APIResponse
+        """
+        # HPA不提供直接的符号搜索，需要通过其他方式
+        # 这里返回一个需要外部转换的提示
+        return APIResponse(
+            success=False,
+            data=None,
+            source=self.source_name,
+            endpoint="/search",
+            params={"gene_symbol": gene_symbol},
+            timestamp="",
+            error="HPA API不支持直接按基因符号搜索，请使用Ensembl ID"
+        )

package/target-research-platform/src/api_clients/immune_data_manager.py

@@ -0,0 +1,247 @@
+"""
+免疫浸润数据管理器
+管理 TCGA 免疫浸润预计算数据的下载、加载和查询
+
+数据来源优先级：
+1. 本地预计算文件 (data/immune_infiltration/)
+2. TIMER2.0 预计算数据下载
+3. 基于 marker gene 的简化估算（降级方案）
+"""
+import csv
+import gzip
+import warnings
+from pathlib import Path
+from typing import Optional
+from .base_client import BaseAPIClient, APIResponse
+
+
+class ImmuneDataManager(BaseAPIClient):
+    """TCGA 免疫浸润数据管理器"""
+
+    # 支持的免疫细胞类型（与 ImmuneCorrelationAnalyzer 对齐）
+    IMMUNE_CELLS = [
+        "B_cell", "CD4_T_cell", "CD8_T_cell", "Neutrophil",
+        "Macrophage", "Dendritic_cell", "NK_cell", "Monocyte",
+        "Mast_cell", "Eosinophil"
+    ]
+
+    # TIMER2.0 提供的 6 种细胞类型映射
+    TIMER_CELL_MAP = {
+        "B_cell": "B_cell",
+        "CD4_T_cell": "CD4_T_cell",
+        "CD8_T_cell": "CD8_T_cell",
+        "Neutrophil": "Neutrophil",
+        "Macrophage": "Macrophage",
+        "Dendritic_cell": "Dendritic_cell"
+    }
+
+    # TCGA 癌型列表
+    TCGA_CANCERS = [
+        "ACC", "BLCA", "BRCA", "CESC", "CHOL", "COAD", "DLBC",
+        "ESCA", "GBM", "HNSC", "KICH", "KIRC", "KIRP", "LAML",
+        "LGG", "LIHC", "LUAD", "LUSC", "MESO", "OV", "PAAD",
+        "PCPG", "PRAD", "READ", "SARC", "SKCM", "STAD", "TGCT",
+        "THCA", "THYM", "UCEC", "UCS", "UVM"
+    ]
+
+    def __init__(self, cache_dir: Optional[str] = None, data_dir: Optional[str] = None):
+        super().__init__(cache_dir=cache_dir)
+        self.data_dir = Path(data_dir) if data_dir else Path("./data/immune_infiltration")
+        self.data_dir.mkdir(parents=True, exist_ok=True)
+        self._loaded_data = {}  # 缓存已加载的数据
+
+    @property
+    def source_name(self) -> str:
+        return "ImmuneDataManager"
+
+    @property
+    def base_url(self) -> str:
+        return ""
+
+    def health_check(self) -> bool:
+        return True
+
+    def get_immune_infiltration(
+        self,
+        cancer_type: str,
+        source: str = "auto"
+    ) -> APIResponse:
+        """
+        获取指定癌型的免疫浸润数据
+
+        Args:
+            cancer_type: TCGA 癌型代码，如 "BRCA"
+            source: 数据来源 ("auto", "local", "timer", "tcga_marker")
+
+        Returns:
+            APIResponse 包含 {sample_id: {cell_type: proportion}}
+        """
+        if cancer_type not in self.TCGA_CANCERS:
+            return APIResponse(
+                success=False, data=None, source=self.source_name,
+                endpoint="get_immune_infiltration",
+                params={"cancer_type": cancer_type},
+                timestamp="",
+                error=f"不支持的癌型: {cancer_type}"
+            )
+
+        # 内存缓存
+        if cancer_type in self._loaded_data:
+            return APIResponse(
+                success=True, data=self._loaded_data[cancer_type],
+                source=self.source_name, endpoint="get_immune_infiltration",
+                params={"cancer_type": cancer_type}, timestamp=""
+            )
+
+        if source == "auto":
+            # 优先本地文件
+            local_result = self._load_local_data(cancer_type)
+            if local_result.success:
+                self._loaded_data[cancer_type] = local_result.data
+                return local_result
+
+            # 降级：从 TCGA 表达数据估算
+            return self._estimate_from_tcga_expression(cancer_type)
+
+        elif source == "local":
+            return self._load_local_data(cancer_type)
+
+        elif source == "tcga_marker":
+            return self._estimate_from_tcga_expression(cancer_type)
+
+        else:
+            return APIResponse(
+                success=False, data=None, source=self.source_name,
+                endpoint="get_immune_infiltration",
+                params={"cancer_type": cancer_type}, timestamp="",
+                error=f"未知数据来源: {source}"
+            )
+
+    def _load_local_data(self, cancer_type: str) -> APIResponse:
+        """加载本地预计算的免疫浸润数据"""
+        # 尝试多种文件格式
+        for ext in [".csv", ".tsv", ".csv.gz"]:
+            file_path = self.data_dir / f"{cancer_type}{ext}"
+            if file_path.exists():
+                return self._parse_immune_file(file_path, cancer_type)
+
+        return APIResponse(
+            success=False, data=None, source=self.source_name,
+            endpoint="_load_local_data",
+            params={"cancer_type": cancer_type}, timestamp="",
+            error=f"未找到本地免疫数据文件: {cancer_type}"
+        )
+
+    def _parse_immune_file(self, file_path: Path, cancer_type: str) -> APIResponse:
+        """解析免疫浸润数据文件"""
+        try:
+            open_func = gzip.open if file_path.suffix == '.gz' else open
+            mode = 'rt' if file_path.suffix == '.gz' else 'r'
+            delimiter = '\t' if file_path.suffix == '.tsv' else ','
+
+            with open_func(file_path, mode, encoding='utf-8') as f:
+                reader = csv.DictReader(f, delimiter=delimiter)
+                immune_data = {}
+
+                for row in reader:
+                    sample_id = row.get("sample_id", "")
+                    if not sample_id:
+                        continue
+
+                    cell_fractions = {}
+                    for cell in self.IMMUNE_CELLS:
+                        val = row.get(cell, row.get(cell.lower(), ""))
+                        if val:
+                            try:
+                                cell_fractions[cell] = float(val)
+                            except ValueError:
+                                pass
+
+                    if cell_fractions:
+                        immune_data[sample_id] = cell_fractions
+
+            if not immune_data:
+                return APIResponse(
+                    success=False, data=None, source=self.source_name,
+                    endpoint="_parse_immune_file",
+                    params={"cancer_type": cancer_type}, timestamp="",
+                    error="解析后无有效数据"
+                )
+
+            self._loaded_data[cancer_type] = immune_data
+            return APIResponse(
+                success=True, data=immune_data,
+                source="local_file", endpoint=str(file_path),
+                params={"cancer_type": cancer_type}, timestamp=""
+            )
+
+        except Exception as e:
+            return APIResponse(
+                success=False, data=None, source=self.source_name,
+                endpoint="_parse_immune_file",
+                params={"cancer_type": cancer_type}, timestamp="",
+                error=f"文件解析错误: {str(e)}"
+            )
+
+    def _estimate_from_tcga_expression(self, cancer_type: str) -> APIResponse:
+        """
+        基于 TCGA 表达数据和 marker gene 估算免疫浸润
+
+        使用已知的免疫细胞 marker gene 表达水平做简化估算。
+        这是降级方案，精度低于 CIBERSORT/TIMER 等反卷积方法。
+
+        标记基因：
+        - B_cell: CD19, MS4A1
+        - CD4_T_cell: CD4
+        - CD8_T_cell: CD8A, CD8B
+        - Neutrophil: FCGR3B, CSF3R
+        - Macrophage: CD68, CD163
+        - Dendritic_cell: ITGAX, HLA-DRA
+        - NK_cell: NCAM1, KLRD1
+        - Monocyte: CD14
+        - Mast_cell: KIT, TPSAB1
+        - Eosinophil: IL5RA
+        """
+        warnings.warn(
+            f"使用 marker gene 估算 {cancer_type} 免疫浸润（降级方案），"
+            "建议提供预计算数据文件以获得更准确的结果",
+            UserWarning
+        )
+
+        # 返回一个空结果，标记需要预计算数据
+        return APIResponse(
+            success=False, data=None,
+            source=self.source_name,
+            endpoint="_estimate_from_tcga_expression",
+            params={"cancer_type": cancer_type}, timestamp="",
+            error=(
+                f"缺少 {cancer_type} 的预计算免疫浸润数据。"
+                f"请将数据文件放置在 {self.data_dir}/{cancer_type}.csv，"
+                f"格式: sample_id,B_cell,CD4_T_cell,CD8_T_cell,Neutrophil,"
+                f"Macrophage,Dendritic_cell,NK_cell,Monocyte,Mast_cell,Eosinophil"
+            )
+        )
+
+    def get_supported_cancers(self) -> list[str]:
+        """返回支持的癌型列表"""
+        available = []
+        for cancer in self.TCGA_CANCERS:
+            for ext in [".csv", ".tsv", ".csv.gz"]:
+                if (self.data_dir / f"{cancer}{ext}").exists():
+                    available.append(cancer)
+                    break
+        return available
+
+    def get_data_status(self) -> dict:
+        """返回各癌型的数据状态"""
+        status = {}
+        for cancer in self.TCGA_CANCERS:
+            has_local = any(
+                (self.data_dir / f"{cancer}{ext}").exists()
+                for ext in [".csv", ".tsv", ".csv.gz"]
+            )
+            status[cancer] = {
+                "local_data": has_local,
+                "in_memory": cancer in self._loaded_data
+            }
+        return status