Skip to content
Back to Liquid Agent DOCUMENTATION

cfDNA Analysis and Raw Signals

The project now has two parallel cfDNA downstream layers:

  1. standard analysis / visualization for feature-space and standard derived tables
  2. raw-signal suites for raw or near-raw cfDNA views and numeric summaries

For guided operation, use liquid-agent or liquid-agent web and describe the analysis goal in natural language. Generated figures and readable artifacts can be inspected from the web UI results panel.

The current report path is markdown-first. When an analysis produces key tables or static PNG figures, the integrated report links or embeds those user-facing outputs directly so the Results panel can show the scientific evidence without requiring users to open backend JSON, TXT, or HTML artifacts.

Standard cfDNA Visualization

Script:

  • scripts/run_cfdna_plot_suite.py

It accepts:

  • cfdna_features_dir
  • frag_dir
  • meth_summary_path
  • region_signal_table
  • cnv_dir
  • cnv_matrix_table
  • methylation_matrix_table
  • signal_matrix_table
  • arm_burden_dir
  • segments_dir
  • labels_table

It now also accepts preprocessing-derived:

  • region_signal_table
  • arm_burden_dir
  • segments_dir

If only cleaned intervals exist, the assistant can backfill standard downstream summaries by running the BED cohort pipeline on those cleaned intervals.

Supplied matrix tables are treated as processed downstream signals, not raw sequencing inputs. The matrix adapter can read either sample x feature tables or feature x sample tables. For EPIC-like methylation signal matrices with paired methylated/unmethylated signal columns, it computes a beta-like value as methylated / (methylated + unmethylated).

The plot suite writes PNG heatmaps and PCA projections. When plotly is available in the local Python environment, it can also write HTML heatmaps and projections. The current Web Results panel focuses on reports, CSV/TSV tables, JSON summaries, and static figures; HTML is filtered by default to avoid misclassifying cached external pages as generated analysis outputs.

Standard cfDNA Analysis

Script:

  • scripts/run_cfdna_analysis_suite.py

It writes numeric summaries such as:

  • feature-space distance tables
  • outlier summaries
  • grouped metric summaries
  • methylation-proxy effects
  • epigenomic region-signal summaries
  • CNV bin / arm / segment summaries
  • supplied CNV, methylation, and generic signal-matrix summaries

Supplied matrix summaries include sample-level metrics, robust outlier scores, feature variance tables, top grouped feature effects when labels are available or inferable from sample names, and PCA projection tables.

Raw-Signal Visualization

Script:

  • scripts/run_cfdna_raw_signal_suite.py

Implemented views include:

  • fragment-length distributions
  • periodicity windows
  • genome-wide signal profiles
  • sample/bin heatmaps
  • region metaprofiles
  • region heatmaps
  • VAF distributions
  • longitudinal VAF trajectories
  • arm-burden heatmaps
  • end-motif heatmaps
  • browser-style locus snapshots
  • browser-track bundle export

When Plotly is installed, genome-wide signal profiles, sample/bin heatmaps, and VAF distributions can also write HTML files next to the PNG and CSV artifacts. Those HTML files are generated by the Python suite but are not shown in the default Web Results list until generated-HTML whitelisting is added.

Raw-Signal Numeric Analysis

Script:

  • scripts/run_cfdna_raw_signal_analysis_suite.py

Implemented numeric summaries include:

  • fragmentomics summaries
  • genome-wide signal burden
  • region-level effects
  • variant/VAF summaries
  • longitudinal VAF deltas
  • arm-level burden summaries
  • end-motif tables
  • browser-track inventories

For compatible browser-track-style inputs, the raw-signal path can now produce first-pass track inventories, per-track summaries, chromosome summaries, representative density plots, and focused second-pass comparison reports. These outputs are treated as exploratory signal QC and distribution review unless metadata labels and a validated study design support stronger grouped or supervised interpretation.

Assistant Integration

The assistant now connects preprocessing outputs into the semantically correct downstream routes:

  • epigenomic region_signal_table into standard cfDNA analysis / visualization
  • LPWGS arm_burden and segments into the standard CNV chain
  • supplied CNV/methylation/signal matrices into standard cfDNA analysis and visualization
  • cleaned intervals can trigger a standard BED cohort pipeline backfill when only cleaned intervals exist but no standard downstream summaries exist yet
  • metadata profiles into grouped summaries, group-coloured plots, or exploratory supervised modeling when label coverage and class balance support those routes

After each task, the result evaluator reads generated summaries, tables, figures, and reports. The next plan should move forward from those outputs rather than repeating the same first-pass plan unless the user explicitly asks to rerun.

Validated public-data examples on the mounted local data disk:

Accession Input detected Validation route Result
GSE186573 GSE186573_DNA-CNV_CPM_matrix_gene.txt.gz --cnv_matrix_table 86 samples, 1000 representative features, CRC/NC labels inferred from sample names
GSE186575 GSE186575_DNA-Met_CPM_matrix_promoter.txt.gz --methylation_matrix_table 98 samples, 1000 representative promoter features, CRC/NC labels inferred from sample names
GSE214344 GSE214344_MatrixSignalGEO.txt.gz --methylation_matrix_table 12 samples, beta-like values from methylated/unmethylated signal columns
GSE171434 12 BED.GZ fragment-center files and 6 bigWig raw-signal tracks raw-signal visualization / numeric analysis representative 63 MB bigWig first-pass run, 512 genome-wide bins, PNG plots, CSV summaries, browser-track manifest
msk_access_2021 cBioPortal MSK-ACCESS-style cfDNA mutation subset raw-signal variant/VAF visualization / numeric analysis 2025 mutation rows, 580 samples, ref/alt count and VAF parsing, sample/gene summaries, PNG VAF distribution, tabular summaries

The assistant can also call the method advisor when the user asks which mature external tools fit the dataset. This is most useful for fragmentomics, CNV, and methylation questions where local internal summaries may be feasible now, while deeper tools such as FinaleToolkit, ichorCNA, QSEA, Bismark, QDNAseq, or CNVkit may require extra installation or assay-specific reference resources.

Method Notes

Current standard and raw-signal suites use mature, conventional visualization and summary patterns:

  • standard feature-space scatter plots now default to projection="auto", which prefers UMAP, then t-SNE, then PCA
  • raw-signal views follow the assay-style conventions already common in cfDNA and liquid-biopsy literature: genome-wide profiles, sample/bin heatmaps, region-centered metaprofiles, VAF summaries, arm-level burden views, and related inspection plots

For the component and method rationale, see Components and Methods.

Key references: