Skip to content
Back to Liquid Agent DOCUMENTATION

Liquid-Biopsy Method Advisor

The method advisor helps users choose liquid-biopsy analysis tools for a dataset or a research question, including mature tools, external runtimes, and explicitly marked research/watchlist methods. It is not a black-box classifier. It compares the detected input files, the user's goal, local dependency availability, external runtime status, and safe internal fallback routes.

For the complete project-wide inventory of callable internal workflows, encoders, external runtimes, LLM engines, and supported data types, see Capability Matrix. For install/smoke/run details, see External Tool Runtimes.

Use it when the question is about analysis methods, algorithms, external tools, or assay-specific routes such as fragmentomics, methylation, copy-number analysis, variant calling, cfRNA, small RNA, CTC tables, or plasma proteomics.

How To Use It

Interactive shell:

/methods fragmentomics CNV methylation
/methods check low-pass cfDNA WGS copy number
/methods run which tools should I use for cfMeDIP and fragmentomics?

Natural language:

What mature tools should I consider for fragmentomics, methylation, and CNV in this dataset?

Check whether this folder is better suited for cfDNAPro, FinaleToolkit, WisecondorX, QSEA, Bismark, cfTools, or variant calling.

CLI:

liquid-agent methods --input <dataset_or_subdir> --query "fragmentomics CNV methylation"

Write a JSON and Markdown report:

liquid-agent methods \
  --input <dataset_or_subdir> \
  --query "fragmentomics CNV methylation" \
  --output-dir <output_dir>

Script form:

python scripts/run_liquid_biopsy_method_advisor.py \
  --input <dataset_or_subdir> \
  --query "fragmentomics CNV methylation" \
  --output_dir <output_dir>

Python API:

from liquidbiopsy_agent.methods import recommend_liquid_biopsy_methods, write_method_advice_report

advice = recommend_liquid_biopsy_methods(
    input_path="<dataset_or_subdir>",
    query="fragmentomics CNV methylation",
)
summary = write_method_advice_report(
    output_dir="<output_dir>",
    input_path="<dataset_or_subdir>",
    query="fragmentomics CNV methylation",
)

Local web API:

  • GET /api/methods?query=fragmentomics%20CNV%20methylation
  • POST /api/session/{session_id}/methods/advice

What The Report Contains

The advisor writes:

  • liquid_biopsy_method_advice.json
  • liquid_biopsy_method_advice.md

The report includes:

  • matched method names and scores
  • why each method was selected
  • expected input files
  • expected outputs
  • local dependency status
  • install hints for missing optional tools
  • safe internal fallback routes
  • references for each method family

The output is advisory. It does not claim that an external method has run unless a later execution task actually runs it.

External Runtime Layer

For selected tools, the method advisor is connected to the external runtime manager. The same tool status is available through:

liquid-agent tools status
liquid-agent tools status --tool purecn --json
liquid-agent tools install purecn --execute
liquid-agent tools smoke purecn

The advisor uses this runtime status in method output:

  • external_runtime_ready: runtime and required resources are present
  • external_runtime_installed: the runtime, source checkout, executable, Python module, or R package is locally present and no method-specific missing resource is currently reported
  • external_runtime_needs_resources: part of the runtime is installed, but real analysis still needs data, model, reference, or workflow resources
  • missing_external_tools: no callable runtime is available
  • reimplementation_candidate: upstream code is useful but too old or unstable for ordinary users; prefer an internal proxy or a maintained modern alternative

Examples:

  • PureCN and FACETS core can be installed into isolated R/conda runtimes, but need coverage tables, normal resources, or SNP pileups for real analysis.
  • modkit can be installed and called through the nanopore methylation route, while Dorado basecalling and ONT model resources remain explicit user-provided requirements.
  • CopywriteR is tracked as a reimplementation candidate on macOS arm64 because the available conda builds depend on old R/Bioconductor stacks that do not solve cleanly; Liquid Agent includes a conservative internal copywriter-proxy for first-pass off-target/bin-count CNV screening.

Supported Method Families

Family Methods tracked Typical inputs Internal fallback or current project route
Fragmentomics FinaleToolkit, cfDNAPro, DELFI-style features, Griffin, LIQUORICE, LBFextract, cfDNAFE, cfDNAanalyzer, EMIT, DeepFRAG paired-end cfDNA WGS BAM/CRAM, fragment files, region tables, end-motif/fragment-size matrices raw-signal numeric and visualization suites; BED cohort pipeline where suitable
Broad cfDNA WGS/WGBS workflow cfDNApipe, cfDNA UniFlow FASTQ/BAM plus reference resources modular preprocessing, raw-signal, CNV, and methylation-summary routes when a full external pipeline is unnecessary
Copy number ichorCNA, QDNAseq, WisecondorX, HMMcopy readcount correction, CNVkit, Control-FREEC, CopywriteR, FACETS/facetsSuite, PureCN, BayesCNV LPWGS/ULPWGS BAM, WIG/read-count bins, CNV tables, higher-coverage WGS/WES/panel BAMs LPWGS preprocessing, segmentation, arm-burden, CNV summaries, and copywriter-proxy for first-pass off-target/bin-count CNV screening
Methylation enrichment QSEA, MEDIPS cfMeDIP/MeDIP BAM, enrichment windows, CpG resources epigenomic preprocessing, region-signal summaries, methylation-aware encoding routes
Bisulfite / EM-seq / nanopore methylation Bismark, MethylDackel, nf-core/methylseq, Dorado + modkit FASTQ, aligned methylation BAM/CRAM, nanopore POD5/FAST5 or modified-base BAM summarize generated methylation tables after external calling
Methylation deconvolution and advanced models FinaleMe, cfTools/cfSort, MethylBERT, cfDecon, CelFiE-ISH, CelFEER, UXM, MethAtlas, cfNOMe, MetDecode, CpGPT, MethylGPT, MethFormer, cfMethylPre WGBS/cfMethyl-Seq methylation calls, read-level methylation patterns, marker/reference atlases, methylation matrices internal methylation summaries and metadata-aware review until compatible external inputs exist
ctDNA variants fgbio UMI consensus, Mutect2, LoFreq, VarDict UMI-tagged BAM/FASTQ, VCF, MAF, variant tables variant preprocessing, VAF summaries, effect-profile aggregation when annotations exist
cfRNA Salmon, STAR, featureCounts cfRNA FASTQ or count matrices method guidance and supplied-matrix review
EV-miRNA / small RNA sRNAbench, miRge-style routes small-RNA FASTQ or miRNA count matrices method guidance and supplied-matrix review
CTC tables Scanpy, Seurat, CellTypist-style downstream analysis CTC count tables, marker tables, h5ad/RDS outputs table-level summaries and expert-guided interpretation
Plasma or EV proteomics DIA-NN, MaxQuant, OpenMS-style upstream workflows mzML/vendor raw files or abundance matrices supplied-matrix summaries and metadata-aware review

Selection Rules

The advisor intentionally separates three questions:

  1. Can Liquid Agent analyze the supplied files directly?
  2. Which external tools or research methods are appropriate for deeper assay-specific analysis?
  3. What safe internal route should run now if external dependencies are missing?

This keeps autopilot practical. For example, if a low-pass cfDNA WGS folder has no configured ichorCNA resources, the agent can still run LPWGS preprocessing and CNV burden summaries, then report ichorCNA as the recommended deeper follow-up rather than pretending that tumor fraction was estimated.

Agent Integration

The assistant can include method advice in three places:

  • planning, when the dataset contains relevant liquid-biopsy file types
  • autopilot, when method advice is useful and no report exists yet
  • review, when existing outputs should be summarized alongside method recommendations

In an end-to-end run, the method advisor should not block feasible internal analysis. It should document what is mature, what is locally available, what is missing, and what the agent did instead.

Dependency Semantics

Requirement status values are interpreted conservatively:

  • ready: required external tools are available locally
  • ready_with_optional_gaps: required tools exist, optional helpers are missing
  • partial: at least one requirement is available, but the method is not fully ready
  • missing_external_tools: external tools are not available locally
  • internal_or_guidance_only: no external dependency is required for the advisory entry
  • external_runtime_ready: the external runtime wrapper and required resources are all present
  • external_runtime_installed: the external runtime wrapper is locally present and no missing method-specific resource is currently reported
  • external_runtime_needs_resources: the external runtime wrapper or source checkout is present, but method-specific resources are still incomplete

Missing optional tools are not treated as failures. They are reported with install hints and internal fallback routes.

Some methods also need manual resources such as reference panels, model files, or method-specific code bundles. The advisor reports those as incomplete until the user configures them explicitly; it should not mark a method as fully runnable only because a generic runtime such as Java, R, or Python exists locally.

Cross-Language Execution Guardrails

Many mature liquid-biopsy tools are not Python packages. Liquid Agent therefore treats them as external runtimes unless a dedicated local wrapper is available.

  • R/Bioconductor methods such as PureCN and FACETS are handled in isolated conda R runtimes when possible; QDNAseq, HMMcopy, QSEA, MEDIPS, and cfTools remain method-guidance entries until dedicated wrappers are added.
  • Command-line tools such as FinaleToolkit, CNVkit, modkit, and Snakemake workflows are checked through executable discovery in their configured runtime.
  • Java or manually downloaded methods such as FinaleMe and several atlas/model-based deconvolution tools require explicit manual_resource configuration.
  • Research models with code/model checkpoints, such as MethylBERT, CpGPT, MethylGPT, cfDecon, CelFEER, UXM, EMIT, and DeepFRAG, can have source/runtime wrappers while still remaining ready=False until checkpoints, atlases, and input-format resources are configured. MethFormer is currently model-resource guidance rather than a registered executable wrapper.

This means the agent may recommend an R, Java, Snakemake, or deep-learning method, but it must not claim that the method has run unless the required runtime and method-specific resources are present and an execution task actually invokes it. If those checks fail, the agent should continue with safe internal summaries and report the external method as a follow-up.

References