Input File Formats

This page documents the expected formats for custom input files used as overrides. Krewlyzer validates these formats when you provide custom files.

Quick Reference

File Type	Columns	Used By	Example
Sample List	paths	build-pon	/path/to/sample.bam
BED3	chrom, start, end	--bin-input, --target-regions	chr1\t0\t100000
Gene BED	chrom, start, end, gene, [name]	--gene-bed	chr1\t100\t5000\tTP53\texon1
Transcript Overrides	gene, transcript_id	build_gene_bed.py --transcript-overrides	TP53\tENST00000269305
Arms BED	chrom, start, end, arm	--arms-file	chr1\t0\t125000000\t1p
WPS Anchors	BED6 format	--wps-anchors, --wps-background	chr1\t1000\t2000\tGene_TSS\t0\t+
Region BED	chrom, start, end, label	--ocr-file, --tfbs-regions, --atac-regions	chr1\t500\t800\tLiver
GC Factors TSV	length_bin, gc_pct, factor	--gc-factors	10\t45\t1.05

---

Sample List

Plain text file with one sample path per line for PON building.

Format

/path/to/sample1.bam
/path/to/sample2.bam
/path/to/sample3.bed.gz

Input Type	Description
.bam / .cram	Full processing including MDS baseline
.bed.gz	Pre-extracted fragments (faster, no MDS)

Notes

• One path per line
• No header row
• Paths can be absolute or relative to working directory
• Mixing BAM and BED.gz inputs is allowed

Used By

• build-pon SAMPLE_LIST - First positional argument

---

BED3

Standard 3-column BED format for genomic intervals.

Format

chrom    start    end

Column	Type	Description
chrom	string	Chromosome (e.g., chr1, chrX)
start	int	0-based start position
end	int	1-based end position (exclusive)

Example

chr1    0   100000
chr1    100000  200000
chr2    0   100000

Used By

• --bin-input / -b - Custom bins for FSC/FSR
• --target-regions / -T - Panel capture regions
• --mark-input / -m - UXM methylation markers

---

Gene BED

Extended BED format for gene annotations with 4-5 columns.

Format

chrom    start    end    gene    [name]

Column	Type	Required	Description
chrom	string	✅	Chromosome
start	int	✅	0-based start
end	int	✅	1-based end
gene	string	✅	Gene symbol (e.g., TP53)
name	string	Optional	Exon/region name

Example

chr17   7676594 7676707 TP53    exon1
chr17   7676707 7676863 TP53    exon2
chr7    140719327   140724764   BRAF    exon15

Bundled assets carry four extra columns

The gene BEDs shipped in src/krewlyzer/data/genes/ are generated from a GENCODE GTF by scripts/build_gene_bed.py and extend the format:

chrom  start  end  gene  name  transcript_id  exon_number  strand  is_e1  is_first_captured

Column	Description
transcript_id	Canonical transcript: MANE Select → Ensembl canonical → longest CDS
exon_number	Transcription order from the GTF, not coordinate order
strand	+ / -; absent from the panel assets before 0.9.0
is_e1	Row overlaps the canonical transcript's exon 1
is_alt_e1	Row overlaps another basic protein-coding transcript's exon 1
is_first_captured	Most 5′ row for this gene, in transcription order

The first five columns are unchanged, so a custom 4- or 5-column file still works and readers indexing gene/name are unaffected.

The three first columns are not interchangeable

Genes have several annotated first exons — a median of 13 — because alternative promoters are common. On xs1, 25 of 128 genes have a tile on the canonical exon 1, 15 more on another basic protein-coding transcript's first exon, and 88 on neither. is_first_captured always exists but is frequently an internal exon, which is not a promoter proxy.

Use is_e1 when the promoter-proximal interpretation matters, is_alt_e1 to include alternative promoters, and is_first_captured only as a positional anchor.

The canonical transcript is configurable per gene via --transcript-overrides, so a panel built around specific clinical transcripts can say so rather than inherit MANE.

exon_number deserves the same caution when reading older assets: the pre-0.9.0 WGS BED numbered exons by coordinate, so its exon_num 0 was the last exon for every minus-strand gene.

Used By

• Custom gene files for panel FSC

---

Transcript Overrides

Two-column TSV naming the transcript to treat as canonical for specific genes, consumed at build time by scripts/build_gene_bed.py. Not a runtime input: its effect is baked into the generated gene BED.

Format

gene    transcript_id

Column	Type	Description
gene	string	Gene symbol, matching the panel BED (TP53)
transcript_id	string	Ensembl/GENCODE id, with or without version

Blank lines and # comments are ignored.

Example

# Panel was designed around these transcripts, not MANE Select
TP53    ENST00000269305
MTOR    ENST00000361445
H3F3A   ENST00000366813

Why it exists

A capture panel is designed around particular transcripts. Imposing MANE Select on it annotates a gene structure the assay was not built for — which decides where is_e1 lands, and therefore what any promoter-proximal feature measures.

An override takes precedence over every other tier of the canonical-transcript policy.

Errors

These are fatal by design. A silent fall back to MANE would produce an asset that disagrees with the file you wrote, with nothing to indicate it:

Condition	Result
Transcript absent from the GTF	Error; the message lists what is present for that gene
Transcript belongs to a different gene	Error
Malformed line, or a gene listed twice with different transcripts	Error
A gene listed twice with the same transcript	Accepted
Gene absent from this build	Warning — one file may serve several assays

Version suffixes are optional: ENST00000269305 matches ENST00000269305.9_9, so a file need not track GENCODE releases. An unversioned id matching two transcripts is an error rather than a guess.

---

Arms BED

Chromosome arm annotations for FSD analysis.

Format

chrom    start    end    arm

Column	Type	Description
chrom	string	Chromosome (e.g., chr1)
start	int	0-based start position
end	int	1-based end position
arm	string	Arm identifier (must match pattern: Np or Nq)

Arm Pattern

The arm column must match the regex pattern: ^\d{1,2}[pq]$

Valid examples: 1p, 1q, 22p, 22q
Invalid: Arm1, chr1p, p

Example

chr1    0   125000000   1p
chr1    125000000   249250621   1q
chr2    0   93300000    2p
chr2    93300000    243199373   2q

Used By

• --arms-file / -a - Custom chromosome arms for FSD

---

WPS Anchors

BED6 format for WPS anchor regions (TSS, CTCF sites, etc.).

Format

chrom    start    end    name    score    strand

Column	Type	Description
chrom	string	Chromosome
start	int	0-based start
end	int	1-based end
name	string	Anchor name (e.g., TP53_TSS)
score	int	Score (typically 0)
strand	string	Strand: +, -, or .

Example

chr1    11873   14409   DDX11L1_TSS 0   +
chr1    29553   31109   MIR1302-2_TSS   0   +
chr17   7676594 7676707 TP53_TSS    0   -

Used By

• --wps-anchors - Custom WPS anchor regions
• --wps-background / -B - Background normalization regions

---

Region BED

Labeled genomic regions for OCF, TFBS, and ATAC analysis.

Format

chrom    start    end    label

Column	Type	Description
chrom	string	Chromosome
start	int	0-based start
end	int	1-based end
label	string	Region label (tissue, TF name, cancer type)

Example

chr1    100 500 Liver
chr1    600 900 Lung
chr2    1000    1500    Blood

Used By

• --ocr-file / -r - Open chromatin regions for OCF
• --tfbs-regions - Transcription factor binding sites
• --atac-regions - ATAC-seq peaks

---

GC Factors TSV

Tab-separated correction factors for GC bias normalization.

Format

length_bin    gc_pct    factor

Column	Type	Description
length_bin	int	Fragment length bin: (length - 60) // 5
gc_pct	int	GC percentage (0-100)
factor	float	Correction factor (typically 0.5-2.0)

Example

length_bin  gc_pct  factor
10  40  1.05
10  41  1.03
10  42  0.98
11  40  1.02

Notes

• Length bin 10 corresponds to fragments 110-114bp
• GC percentage is rounded to the nearest integer
• Factors near 1.0 indicate minimal bias

Used By

• --gc-factors / -F - Custom GC correction factors

---

Compression Support

All BED files can be gzip-compressed (.bed.gz). Krewlyzer automatically detects and handles compression.

# Both work
krewlyzer validate --arms-bed my_arms.bed
krewlyzer validate --arms-bed my_arms.bed.gz

---

Validation

Validate your files before analysis:

# Validate specific files
krewlyzer validate --gene-bed my_genes.bed
krewlyzer validate --arms-bed my_arms.bed --wps-anchors my_anchors.bed

# Validate bundled assets
krewlyzer validate --genome hg19

If validation fails, you'll see: - Expected format and columns - Line number of the first error - Example of correct format

See Troubleshooting > Asset Validation for common errors.