footprint

Score transcription-factor footprints at a set of motif sites using a per-base editing BigWig. A bound factor shields its motif from deaminase editing, so a footprint appears as a local depletion of signal at the motif relative to its flanks.

Synopsis

deamtools footprint --bigwig FILE --regions FILE --out_dir DIR --out_name NAME [options]

Required inputs

Argument	Description
--bigwig FILE	Per-base editing BigWig, e.g. produced by deamtools bam2bw.
--regions FILE	BED of motif sites to score (e.g. from deamtools match). Column 4, if present, is carried through as the site name.
--out_dir DIR	Output directory. Created automatically if it does not exist.
--out_name NAME	Base name (without extension) for the output. Writes <out_dir>/<out_name>.bed.

Optional arguments

Argument	Default	Description
--n_shuffles INT	1000	Permutations used to build the footprint p-value null (only computed for sites with a positive score).
--threads INT	1	Number of worker processes; chromosomes are scored in parallel. Results do not depend on the worker count, including with --seed.
--seed INT	(unseeded)	RNG seed for reproducible p-values.
--log_level LEVEL	INFO	Global flag (before the subcommand): DEBUG, INFO, WARNING, ERROR.

How it works

For a motif site of width L = end − start, the per-base signal is read over the 3 × L window [start − L, end + L) and split into three equal parts:

[ left flank ][ motif centre ][ right flank ]
  L bases        L bases          L bases

The footprint score is

fp_score = mean(left flank) + mean(right flank) − mean(centre)

so a depleted centre flanked by high signal yields a positive score. For sites with a positive score, the per-base values in the window are permuted --n_shuffles times to form a null distribution, and the p-value is (#permutations with score ≥ observed + 1) / (n_shuffles + 1). Sites with a non-positive score are assigned p_value = 1.0 without permutation.

Sites whose 3 × L window would extend beyond the chromosome ends (or are absent from the BigWig header) are skipped.

Output

A BED-like, tab-delimited file with one line per scored site:

chrom    start    end    name    fp_score    p_value

• fp_score — the footprint score (higher = stronger depletion at the motif).

• p_value — permutation p-value (small = significant footprint).

Examples

# Score motif sites from `match` against a bam2bw track
deamtools footprint \
    --bigwig sample.bw \
    --regions mpbs.bed \
    --out_dir results --out_name footprints

# Reproducible p-values, 8 worker processes
deamtools footprint \
    --bigwig sample.bw \
    --regions mpbs.bed \
    --seed 0 --threads 8 \
    --out_dir results --out_name footprints

Notes

• Use a count-mode BigWig (raw or normalized); the score is scale-aware, so normalized tracks are fine for comparing across samples.

• Filtering the output by p_value (e.g. < 0.001) gives the set of confidently bound sites.