4.9.2 SeRP overlap¶

`serp_overlap`¶

serp_overlap compares transcript-level SeRP peak intervals between two biological conditions and classifies peaks as shared or condition-specific.

Function¶

Use this command when you want to:

compare two SeRP peak result tables generated by serp_peak;
identify peaks that overlap on the same transcript;
label peaks as shared or specific to one condition;
summarize overlap relationships, shared peak clusters, and peak-length comparisons.

Input¶

The command takes two peak tables generated by serp_peak:

Input	Description
Peak table A	Peak result table for condition A (`*_peaks.txt`).
Peak table B	Peak result table for condition B (`*_peaks.txt`).

The required columns are:

transcripts  peak_start  peak_end

When --interval extended is used, the tables must also contain:

collision_start  collision_end

Optional columns:

Column	Purpose
`peak_num`	When present, only rows with `peak_num > 0` and valid coordinates are treated as called peaks. When absent, every row with valid `peak_start`/`peak_end` is treated as a called peak.
`gene_name`	Used for gene-level counts in the summary table.
`BHFDR`	Required only when `--max-fdr` is used.

By default, all called peaks are compared. --max-fdr is used only when BHFDR-based filtering is explicitly required.

Parameters¶

Parameter	Required	Meaning
`-a`	yes	Peak table for condition A. Legacy `-m`/`--mock` aliases are supported.
`-b`	yes	Peak table for condition B. Legacy `-f`/`--flag` aliases are supported.
`-o`	yes	Output prefix for all overlap-analysis tables.
`--name-a`	no	Condition-A label used in output tables and file names. Default: peak-A filename stem.
`--name-b`	no	Condition-B label used in output tables and file names. Default: peak-B filename stem.
`--min-overlap`	no	Minimum inclusive overlap in codon positions required for a shared relationship. Default: `6`.
`--min-reciprocal`	no	Minimum overlap fraction required for both peaks. Default: `0.5`.
`--interval`	no	Interval type to compare: `core` uses `peak_start`/`peak_end`; `extended` uses `collision_start`/`collision_end`. Default: `core`.
`--max-fdr`	no	Optional maximum BHFDR applied before overlap analysis. Peaks with missing BHFDR are excluded only when this option is used. Default: not applied.

Output¶

The output prefix is controlled by -o.

Output	Description
`<prefix>.summary.txt`	Comparison-level peak counts and QC metrics, including input rows, FDR-filtered rows, called/shared/specific peaks, transcripts and genes with peaks, physical and qualifying overlap relationships, shared-cluster counts, and the applied parameter values.
`<prefix>.length_summary.txt`	Peak-length distributions (core and match-span lengths) for all, shared, and specific categories in each condition.
`<prefix>.relationships.txt`	Transcript-level overlap relationships between peaks, including overlap length, overlap fractions, reciprocal overlap, Jaccard similarity, and center shift.
`<prefix>.shared.clusters.txt`	Shared peak clusters across transcripts, supporting 1:1, 1:N, N:1, and N:N peak relationships.
`<prefix>.shared.peaks.txt`	Shared peaks annotated from the two condition tables.
`<prefix>.<label_a>.specific.peaks.txt`	Peaks specific to condition A, where `<label_a>` is derived from `--name-a`.
`<prefix>.<label_b>.specific.peaks.txt`	Peaks specific to condition B, where `<label_b>` is derived from `--name-b`.
`<prefix>.length_compare.txt`	Pairwise length metrics for qualifying shared relationships, including core length difference, span-length difference, overlap length, fractions, reciprocal overlap, Jaccard, and center shift.

Each peak is annotated with an overlap_status value:

Value	Meaning
`shared`	The peak overlaps at least one peak from the other condition on the same transcript.
`specific`	The peak has no overlapping partner peak from the other condition on the same transcript.

Examples¶

Compare two peak tables generated by serp_peak, with explicit condition labels:

serp_overlap \
  -a SeRP_mock_peaks.txt \
  -b SeRP_flag_peaks.txt \
  --name-a mock \
  --name-b flag \
  -o SeRP_overlap

Use extended collision intervals with stricter overlap criteria:

serp_overlap \
  -a SeRP_mock_peaks.txt \
  -b SeRP_flag_peaks.txt \
  --interval extended \
  --min-overlap 10 \
  --min-reciprocal 0.6 \
  -o SeRP_overlap.extended

Apply BHFDR-based filtering before overlap analysis:

serp_overlap \
  -a SeRP_mock_peaks.txt \
  -b SeRP_flag_peaks.txt \
  --max-fdr 0.05 \
  -o SeRP_overlap.sig

Notes¶

Peak coordinates are transcript-relative codon positions, so peaks are matched only within the same transcript.
By default, all called peaks in *_peaks.txt are compared; BHFDR filtering is applied only when --max-fdr is given.
A shared relationship requires both the minimum inclusive overlap (--min-overlap) and the minimum reciprocal overlap fraction (--min-reciprocal) to be satisfied.
--interval extended requires collision_start/collision_end columns in both input tables.
--name-a and --name-b must be different and cannot contain tabs or line breaks.
This command writes tables only; Venn-diagram plotting is no longer part of serp_overlap.