Alternative polyadenylation - FunGen-xQTL Consortium

This mini-protocol converts aligned RNA-seq reads into an analysis-ready alternative-polyadenylation (APA) phenotype matrix for apaQTL analysis.

Miniprotocol Timing¶

Timing: TBD

Overview¶

APA calling derives 3′UTR regions, converts transcriptome BAM files to per-base coverage, and runs DaPars2 to estimate percentage of distal polyadenylation site usage (PDUI). APA imputation and QC imputes missing PDUI values, quantile-normalizes the matrix, and can replace internal sample identifiers with analysis identifiers.

The full calling route requires transcriptome BAM files, which are not included with the example data. A precomputed chromosome-22 DaPars result is provided so that the imputation and renaming routes can be run independently.

Steps¶

Choose the route that matches the available starting data; the six commands are not always one mandatory chain.

Analysis goal	Commands to run, in order	Inputs
Call and process APA from transcriptome alignments	1 → 2 → 3 → 4 → 5	`input/reference_data/protocol_example.apa.chr22.gtf`; transcriptome BAM files under `output/rnaseq/bam/` (not bundled)
Resume from per-sample coverage files	3 → 4 → 5	`output/apa/wig/*.wig`; matching depth files; `output/apa/protocol_example.apa.chr22_3UTR.bed`
Impute and normalize an existing chromosome-22 DaPars result	5	`tests/fixtures/apa_impute/apa_chr22/Dapars_result_result_temp.chr22.txt`
Impute, normalize and rename samples	5 → 6	DaPars result above; `tests/fixtures/apa_impute/protocol_example.apa_matchtable.txt`

Within the selected route, run the listed commands in numerical order.

1. Build the 3′UTR reference¶

What it does: UTR_reference extracts transcript-level 3′UTR intervals from the reference GTF for DaPars2.

sos run pipeline/apa_calling.ipynb UTR_reference \
  --cwd output/apa \
  --hg-gtf output/apa/protocol_example.apa.chr22.gtf

2. Generate coverage and read-depth files¶

What it does: bam2tools converts each transcriptome BAM into a per-base WIG file and a matching read-depth summary.

sos run pipeline/apa_calling.ipynb bam2tools \
    --cwd output/apa \
    --bam-dir output/rnaseq/bam

3. Build the DaPars2 configuration¶

What it does: APAconfig creates the sample mapping and DaPars2 configuration files from the coverage directory and 3′UTR annotation.

sos run pipeline/apa_calling.ipynb APAconfig \
  --cwd output/apa \
  --bfile output/apa/wig \
  --annotation output/apa/protocol_example.apa.chr22_3UTR.bed

4. Estimate chromosome-level PDUI¶

What it does: APAmain runs DaPars2 for chromosome 22 and writes the unprocessed PDUI result used by the QC module.

sos run pipeline/apa_calling.ipynb APAmain \
    --cwd output/apa \
    --chrlist chr22 \
    --chr-prefix true \
    --dapars-path code/SoS/molecular_phenotypes/calling/apa

5. Impute and normalize PDUI¶

What it does: APAimpute imputes missing chromosome-level PDUI values and applies quantile normalization.

sos run pipeline/apa_impute.ipynb APAimpute \
    --cwd output/apa \
    --chrlist chr22

6. Rename samples and assemble the final matrix¶

What it does: APArename maps sample identifiers, combines requested chromosomes, and bgzip-indexes the final APA phenotype matrix.

sos run pipeline/apa_impute.ipynb APArename \
    --cwd output/apa \
    --chrlist chr22 \
    --match tests/fixtures/apa_impute/protocol_example.apa_matchtable.txt

Output¶

Step	Output filename and relative path	Description
1	`output/apa/protocol_example.apa.chr22.bed`; `output/apa/protocol_example.apa.chr22.transcript_to_geneName.txt`; `output/apa/protocol_example.apa.chr22_3UTR.bed`	BED12 annotation, transcript-to-gene map and DaPars2 3′UTR intervals
2	`output/apa/.wig`; `output/apa/.depth`	Per-sample coverage and read-depth files
3	`output/apa/sample_mapping_files.txt`; `output/apa/sample_configuration_file.txt`	DaPars2 sample mapping and configuration
4	`tests/fixtures/apa_impute/apa_chr22/Dapars_result_result_temp.chr22.txt`	Raw chromosome-22 DaPars2 PDUI result
5	`output/apa/apa_chr22/Dapars_result_impute_chr22.bed`	Imputed and normalized chromosome-22 PDUI matrix
6	`output/apa/apa_chr22/Dapars_result_impute_renamed_chr22.bed`; `output/apa/apa_chr22/Dapars_result_impute_renamed_chr22.bed.gz`; `output/apa/apa_chr22/Dapars_result_impute_renamed_chr22.bed.gz.tbi`; `output/apa/Dapars_allchrom_renamed.bed`; `output/apa/Dapars_allchrom_renamed.bed.gz`; `output/apa/Dapars_allchrom_renamed.bed.gz.tbi`	Renamed chromosome-level and combined analysis-ready APA phenotype matrices

Anticipated Results¶

The complete calling route produces 3′UTR intervals, per-sample coverage summaries, a DaPars2 configuration and one raw PDUI result per requested chromosome. Step 5 produces an imputed chromosome-level phenotype matrix. Step 6 is optional but recommended when the BAM identifiers differ from the identifiers used by covariates and genotypes; its combined bgzip-compressed BED file is the input for downstream apaQTL association testing.

The bundled example starts at step 5 because transcriptome BAM files are not included.

Command Interface¶

sos run pipeline/apa_calling.ipynb -h

sos run pipeline/apa_impute.ipynb -h