henhaobio
Sign in

bioRxivBioinformaticsPreprint

IOBRpy enables agentic multi-omics decoding of anti-tumor immunity

Haonan Huang, Xin LiiD, Lu LiuiD, Wenchao GuiD, Gaofeng WangiD, Dongqiang ZengiD

PDFDOICode
In-depth full-text digest available · Jump to digest ↓

Abstract

Decoding the tumor immunity is pivotal for cancer immunotherapy, yet transcriptomic pipelines remain bottlenecked by fragmented tools and biased interpretations. Here we present IOBRpy, a Python toolkit driven by an innovative AI dual-agent layer for automated, highly standardized immuno-oncology workflows. Moving beyond conventional expression profiling, IOBRpy enables agentic multi-omics decoding. From raw FASTQ or TPM matrices, it seamlessly integrates upstream quality control, transcript quantification, and downstream TME parsing, encompassing signature scoring, ligand-receptor crosstalk, and cellular deconvolution. Crucially, IOBRpy expands data dimensions by incorporating complementary immunogenomic layers, empowering concurrent high-resolution SpecHLA typing and TRUST4-based TCR/BCR repertoire reconstruction from sequencing data. Deployed across two large-scale cohorts (IMvigor210 and OAKPOPLAR), IOBRpy successfully captured multi-dimensional prognostic insights. While broad HLA-I heterozygosity showed negligible impact, it precisely unmasked treatment-stratified, allele-specific survival associations (e.g., HLA-A*01 and HLA-DPA1*02) tightly coupled with distinct immunosuppressive ligand-receptor networks (such as HMGB1-THBD and EFNB2-EPHB6) and dynamic TCR clonal diversity shifts. Empowering this lifecycle is a paired agent framework: a workflow agent automatically audits project states to execute validated, path-aware commands, while a result agent evaluates tool provenance, handles method-aware adaptive visualizations, and organizes findings into evidence-constrained biological hypotheses. Collectively, IOBRpy provides a reproducible, scalable, and intelligence-augmented Python gateway to transform raw sequencing data into multi-omic, interpretation-ready discoveries for cohort-scale precision immunotherapy (https://iobr.github.io/IOBRpy/).

In-depth summary

Claude Opus 5.5 · xhigh effort · 8 Nov 2026 · from the full text of version 1 (22 Jul 2026) · CC BY 4.0

Python toolkit chains RNA-seq quantification, six-method tumour microenvironment (TME) profiling, SpecHLA typing and TRUST4 repertoire analysis with AI agents; TME outputs match R implementations (Spearman 0.986 to ~1.0).

Tumour microenvironment methods for bulk RNA-seq are scattered across languages, web services and scripts with incompatible inputs and outputs, so moving from reads to HLA- and repertoire-aware readouts means manual chaining that risks provenance loss and over-interpretation. IOBRpy extends the group's R-based IOBR framework to Python without altering the underlying methods, linking FASTQ processing, TME profiling, SpecHLA and TRUST4 modules under agents that guard execution and interpretation.

Key results

  1. ShownPython-native versions of six TME methods reproduce the R outputs. Runtime differences depend on the method, and CIBERSORT speeds up substantially with more threads.

    936-sample OP matrix, Python-R total Spearman: IPS, quanTIseq, MCP-counter, ESTIMATE about 1.0; EPIC 0.997; CIBERSORT 0.986 (wider bootstrap CIs for some immune subsets). CIBERSORT mean runtime fell from 2,864.8 s (1 thread) to 368.4 s (8 threads) and 209.7 s (16 threads), a 13.7-fold speed-up; R was faster for MCP-counter and IPS, though Python timing included data loading. · Python-native TME modules preserve R-derived…; Benchmarking against R workflows

  2. SuggestedBroad HLA class I heterozygosity showed no nominally significant survival association. An HLA-wide screen flagged HLA-A*01 carriage (shorter overall survival, IMvigor210 urothelial carcinoma) and HLA-DPA1*02 carriage (longer, OP-IO non-small-cell lung cancer).

    None of the all-locus, two-locus, single-locus or pairwise heterozygosity definitions reached P < 0.05 in IMvigor210, OP-IO or OP-Chemo. IMvigor210 HLA-A*01: 110 carriers vs 235 non-carriers, 230 events, HR = 1.51 (95% CI 1.16-1.98), P = 0.0024. OP-IO HLA-DPA1*02: 177 vs 256, 312 events, HR = 0.73 (95% CI 0.58-0.91), P = 0.0064; both nominal, univariate Cox. · Exploratory HLA/TCR analysis nominates…; HLA/TCR cohort analysis

  3. SuggestedCarriers of the two flagged alleles differed nominally in ligand-receptor and signature scores. The authors present these differences as follow-up hypotheses, not mechanisms.

    Nominal Wilcoxon screens (P < 0.05). IMvigor210 A*01 carriers: higher HMGB1-THBD, CCL23-CCR1 and EFNB2-EPHB6; lower CX3CL1-CX3CR1 and Toll signaling signature scores. OP-IO DPA1*02 carriers: higher HLA-C-KIR2DS4 and IL5-CSF2RB; lower PLAU-ST14, SERPINE2-LRP1, IL1A-IL1R2, TNC-ITGB1 and IL1B-IL1RAP. · Exploratory HLA/TCR analysis nominates…; HLA/TCR cohort analysis

  4. SuggestedIn OP, TCR repertoire metrics were associated with survival in the immunotherapy subgroup but not the chemotherapy subgroup. HLA-DPA1*02:02 carriers showed a nominally more even repertoire.

    Cox per 1-s.d., Benjamini-Hochberg within each endpoint-by-treatment set of six tests. In OP-IO, 5 of 6 metrics had FDR-adjusted P < 0.05 for overall survival and 4 for progression-free survival; OP-Chemo associations did not pass; clonality showed little association. OP-IO DPA1*02:02 carriers (n = 73) vs non-carriers (n = 362): nominally lower Gini index and a trend to lower clonality (two-sided Wilcoxon). · Exploratory HLA/TCR analysis nominates…; HLA/TCR cohort analysis

  5. SuggestedIn simulated natural-language tasks on ten OP samples, the workflow agent inspected the project and ran a recommended route. The result agent then rendered CIBERSORT, signature, ligand-receptor, HLA class I and TCR outputs.

    Five OP-IO and five OP-Chemo samples. A representative dialogue covered path inspection, checklist-based recommendation, execution and hand-off for plotting. Schema checks and Python guardrails are described (e.g. blocking FASTQ input to TPM-only commands or re-logging a transformed matrix), but no success rate or factuality metric is reported. · Paired agents separate workflow execution from…; Simulated tasks demonstrate agent-guided…; Workflow-facing natural-language analysis layer; Result interpretation and visualisation layer

Methods, data and reproducibility

IOBRpy (v.0.2.0) wraps fastp/MultiQC, Salmon or STAR, a six-method TME panel, BayesPrism, signature and ligand-receptor scoring, SpecHLA and TRUST4 in one project structure. The structure is exposed to a workflow agent with schema guardrails and to a result-interpretation agent. Six modules were benchmarked against R, and the toolkit was then applied retrospectively to IMvigor210 and OAK/POPLAR with Cox models.

  • IMvigor210: single-arm phase II atezolizumab trial in advanced urothelial carcinoma (NCT02108652); RNA-seq used for SpecHLA, TRUST4 and TME features · human (trial patients) · n = 348 samples with SpecHLA calls; 347 with TRUST4 metrics · EGAS00001002556; EGAD00001003977
  • Pooled OAK (NCT02008227) and POPLAR (NCT01903993) non-small-cell lung cancer trials (OP), with OP-IO and OP-Chemo treatment subgroups; also the Python-R benchmark matrix · human (trial patients) · n = 936 samples · EGAS00001005013; EGAD00001007703
  • Subset of the OP immunotherapy group with full two-field DPA1 calls and every TCR metric available, used to compare repertoires by HLA-DPA1*02:02 status · human (trial patients) · n = 435 (73 HLA-DPA1*02:02 carriers, 362 non-carriers)
  • Agent demonstration subset of OP samples · human (trial patients) · n = 10 (5 OP-IO, 5 OP-Chemo)
  • Bundled single-cell expression reference with cell-type and cell-state labels for BayesPrism
Methods & tools
fastp, MultiQC, Salmon, STAR, SpecHLA, TRUST4, CIBERSORT, EPIC, quanTIseq, MCP-counter, ESTIMATE, IPS
Software & environment
IOBRpy v.0.2.0 on Python 3.11 (Linux/POSIX), distributed via PyPI and Bioconda; fastp 1.3.6, MultiQC 1.31, Salmon 1.10.3, STAR 2.7.11b, TRUST4 1.1.9, bundled SpecHLA with IPD-IMGT/HLA release 3.38.0, samtools/htslib/bcftools 1.21, pysam 0.23.3, freebayes 1.3.8.
Experimental conditions
Hardware not described; runtimes recorded over 10 repeated runs per setting on 936 samples, with CIBERSORT run at 1, 8 and 16 Python threads.
Reproducibility gaps
IMvigor210 and OP data are EGA controlled access (application, approval and a data-use agreement); accessions are in methods.data. Derived statistical summaries, original HLA calls, deconvolution/scoring outputs and TCR metrics are in Supplementary Tables 1-4.
Limitations (6)
  • IOBRpy inherits the assumptions and input requirements of the wrapped methods. Estimates are sensitive to reference signatures, sequencing depth, tissue processing and cohort composition, and bulk RNA-seq mixes together cell abundance, state and spatial organisation. · stated by the authors
  • Benchmark depth varies across modules and broader stress testing is needed. Runtimes are descriptive only: Python timings included input loading while R timings started afterwards. · stated by the authors
  • The HLA/TCR associations and nominal TME-feature comparisons are retrospective and exploratory, need independent validation, and are not clinically actionable biomarkers. The randomisation of the parent trials does not validate them. · stated by the authors
  • The result-facing agent relies on available metadata and companion files. Its recommendations, visual designs and interpretations have not yet been quantitatively evaluated across varied result directories. · stated by the authors
  • The allele hits rest on nominal P values from a screen of many alleles, with no multiplicity correction reported for them. Each was found in a single cohort or subgroup, with no replication reported. · noted in this summary
  • Python-R concordance was tested on one expression matrix (936 OP samples), and only for the six TME methods. No accuracy benchmark is reported for the SpecHLA or TRUST4 modules against reference calls. · noted in this summary

Read this if you run bulk RNA-seq immuno-oncology analyses in Python and want one pipeline from FASTQ or TPM to deconvolution, HLA typing and TCR/BCR repertoire metrics, or are designing guardrailed language-model agents for bioinformatics workflows.

Citations
0

Reproducibility ledger

Nobody has reported trying to reproduce this paper yet. Did you replicate an experiment or run the code? Your report saves the next lab a week.

Sign in to file a reproducibility report.

Related papers

Similarity Map
SelectedSame fieldCross-field
THISZeng '21Zeng '24Jin '24Mahapatra '25Wang '25Mahapatra '25
69% semantic matchBioinformatics
Dongqiang Zeng, Zilan Ye, Rongfang Shen+12 more·Frontiers in Immunology·Jul 2, 2021· 1,264 citations