cfDNAanalyzer feature extraction¶

1. About¶

Extracts genomic and fragmentomic feature matrices with a second toolkit, over the same analysis BAMs. Off unless --cda-features selects something.

cfDNAanalyzer (Zhang et al.) is a separate cfDNA analysis suite from FinaleToolkit, which every other page in this section documents. It bundles eleven feature extractors — copy number calling with ichorCNA, nucleosome positioning with DANPOS3, nucleosome profiling with Griffin, promoter fragmentation entropy with Epic-seq — and this pipeline can run any subset of them over the same bams/{sample}.sorted.bam the FinaleToolkit analyses read.

Nothing about it runs by default. --cda-features names the features to extract, and an empty selection (the default) leaves cfDNAanalyzer out of the DAG entirely: no rules are defined and its container is never pulled.

2. As the pipeline runs it¶

Three rules, a scatter and a gather:

cda_regions_bed     once per run, only if a region-specific feature was selected
cda_extract         once per sample
cda_merge_features  once per run, gathers every sample

2.1 cda_regions_bed¶

Normalizes the regions the region-specific features are scored over into the sorted BED3 cfDNAanalyzer expects, keeping only the first three columns so any BED flavor can be handed in:

grep -v -e '^#' -e '^track' -e '^browser' <--cda-regions | tss_interval> \
    | cut -f1,2,3 \
    | sort -k1,1V -k2,2n \
    > cfdnaanalyzer/regions.bed

Comment and track lines are dropped rather than passed through, since every consumer reads this file as plain intervals and would otherwise score a header line as a region.

2.2 cda_extract¶

CDA -I <one-line BAM list> -o <scratch> \
    -F <--cda-features> \
    -g <--genome> \
    -f <reference_fa> \
    -s <pair | single, from the sample's flagstat report> \
    -t <threads> \
    -B <--cda-cna-bin-size> \
    -u <--left-tss-flank> -d <--right-tss-flank> \
    -b cfdnaanalyzer/regions.bed \
    --noDA --labelFile <synthesized>

Why one sample per job. cfDNAanalyzer walks its -I list serially in a single process, so a single all-samples invocation gets no parallelism at all. The rule hands it a one-line BAM list instead, and cda_merge_features puts the matrices back together. That is safe because nothing in extraction is cross-sample: each matrix's columns are derived from an input shared by every sample (the region BED, the bundled site lists, the 256 end motifs, the fixed genomic bins), PFE standardization z-scores each row against itself, and the NP site-list tables are one row per sample.

Four packaging constraints shape the rule, and none are optional:

Sample naming

cfDNAanalyzer names a sample after its BAM with .bam stripped, so the analysis BAM is symlinked in as <sample>.bam. Passing bams/{sample}.sorted.bam directly would label every result "{sample}.sorted".

The installation tree gets written to, so CDA is not invoked in place

The image puts a CDA symlink on PATH, and the rule resolves it to find the installation rather than hardcoding a path. It cannot just call it, though: the driver locates itself with readlink -f "$0", which follows the symlink all the way back to the real install tree — and that tree is read-only, while the NP feature generates Griffin snakemake configs and workflows inside it.

So the rule builds a shadow install in scratch. The driver is copied (a symlink would resolve straight back out again), keeping the CDA name so logs still show what ran; everything beside it is symlinked; and Griffin/snakemakes is copied and made writable, since that is the part written to.

NP runs snakemake itself

A nested snakemake keeps state in ./.snakemake and is invoked with --unlock. The whole thing therefore runs with scratch as its working directory — leaving the pipeline's working directory in place would point that --unlock at the outer workflow's own lock.

NOF needs libR.so on the loader path

The rule exports LD_LIBRARY_PATH="$(R RHOME)/lib:$LD_LIBRARY_PATH" before invoking the driver. NOF drives DANPOS3, which reaches R through rpy2, and rpy2 embeds R in the Python process rather than going through R's launcher script — which is the thing that normally puts $R_HOME/lib on the search path, by sourcing $R_HOME/etc/ldpaths. That directory is on no default path otherwise: it has no /etc/ld.so.conf.d entry, so libR.so is absent from the ldconfig cache, and the R binary carries no RUNPATH.

Embedded, R then starts and fails to dyn.load its own base packages, all of which link libR.so, so NOF dies before writing a single wig while the ten other features carry on. The image sets this too; the rule sets it as well so the feature works against published tags that predate that.

2.3 cda_merge_features¶

Runs workflow/scripts/merge_cda_features.py, a row concatenation aligned on column name. Where two samples disagree on columns the union is kept and the mismatch reported, rather than either side being silently trimmed. A sample that cfDNAanalyzer dropped for failing a feature's quality control has a header-only CSV and is simply absent from the merged rows, exactly as it would have been.

3. Features¶

Names are case-insensitive; all selects every feature and none selects none.

3.1 Genome-wide¶

3.2 Region-specific¶

Scored over --cda-regions, or the build's tss_interval if it is not given.

3.3 Transcription start sites¶

4. Output¶

cfdnaanalyzer/
├── regions.bed                     normalized region BED3 (region features only)
├── samples/{sample}/               per-sample matrices, the scatter's output
│   ├── <matrix>.csv
│   └── NP_site_list/               NP only
└── features/                       ← the deliverables
    ├── <matrix>.csv                one row per sample, one column per measurement
    └── NP_site_list/               NP only, one table per TF site list

features/ holds one CSV per matrix in the tables above, each with a leading sample,label pair followed by that feature's measurements. NP_site_list/ holds one table per Griffin transcription factor site list — 377 of them for hg38 — which is why it is tracked as a directory rather than as enumerated targets: how many there are is a property of the container image.

5. Controlling it¶

"cda_extract": {
    "threads": 16,
    "mem": "96G",
    "time": "5-00:00:00",
    "gres": "lscratch:400",
    "partition": "norm"
}

The five-day walltime and 400 GB of local scratch are deliberate. --cda-features all runs eleven extractors including a nested Griffin snakemake, and the shadow install plus intermediate wigs and BEDs all land in lscratch. Trim both if you are selecting only cheap features.

--cda-cna-bin-size is restricted because cfDNAanalyzer reads pre-computed GC and mappability wigs for the requested bin size out of the ichorCNA it bundles, and those exist only at 10, 50, 500 and 1000 kb. Any other value is rejected by the frontend rather than failing mid-run.

6. Requires¶

The cfdnaanalyzer container image — see docker/cfDNAanalyzer/README.md. Cache it with fragmentomics cache before a run.

cfDNAanalyzer bundles most of its own reference data. Three things come from the pipeline, and a selected feature that needs a missing one is silently dropped from the selection rather than failing the run:

• reference_fa for the selected build — required by EM, EMR and NP
• a region BED — --cda-regions, or the build's tss_interval, required by NOF, NP, WPS, OCF, EMR and FPR
• a build name cfDNAanalyzer accepts, which gates every feature rather than some, since it is an argument to its driver rather than something one extractor reads

Both bundled builds (hg19, hg38) provide all three, so in practice every feature is available. hg19 and hg38 are the only builds cfDNAanalyzer supports at all: its CNA, FP, PFE and TSSC extractors read GC/mappability tracks, 100 kb bin definitions and gene annotations from inside its own installation, indexed by build name, and its driver rejects any other name outright. A --genome config file describing references of your own therefore has to declare which of the two its coordinates match, with a cda_genome entry:

{
    "chrom_sizes":  "/refs/hg19_ucscM.chrom.sizes",
    "reference_fa": "/refs/hg19_ucscM.fa",
    "tss_interval": "/refs/tss.hg19_interval_sorted.bed",
    "cda_genome":   "hg19"
}

Without it, --cda-features selects nothing and the frontend says so.

7. Reference¶

Zhang J, et al. cfDNAanalyzer: a comprehensive toolkit for cell-free DNA genomic sequencing data analysis. See the project repository for the per-feature method citations (ichorCNA, DANPOS3, Griffin, Epic-seq, DELFI).