Phenotype Data Formatting

Phenotype Data Formatting#

Splits a molecular phenotype matrix by chromosome or by region so the association scan can be parallelised.

Overview#

Association testing and fine-mapping run per chromosome or per region, so the phenotype matrix has to be partitioned the same way before that work can be parallelised. These workflows split a phenotype BED by chromosome or by region, annotate features against TAD boundaries when region-based analysis is wanted, and accept GCT-format input as well as BED. Two further workflows trim inputs rather than split them: one subsets BAM files by coordinate, the other drops samples from a GCT matrix.

The pipeline’s author has flagged it as needing improvement, so treat the interface as unstable and re-check -h before relying on any option.

When to run it. After phenotype QC, normalisation and imputation, and before covariate preprocessing and the association scan.

Input#

--phenoFile: the molecular phenotype data, required by every workflow. A tabix-indexed UCSC bed.gz for the BED workflows, a gct.gz for the GCT ones, and a list of BAM paths for bam_subsetting. Example output/rnaseq/protocol_example.rnaseq.bed.bed.gz:
```
#chr   start     end       ID               SAMPLE_001         SAMPLE_002
chr22  10939387  10961337  ENSG00000283047  37.0768403309204   0.0
```
--chrom: the chromosomes to extract, taking one or more values. Used by phenotype_by_chrom and phenotype_by_chrom_gct.
--region-list: a 4-column index of the regions to analyse, giving chr, start, end and region name. Used by phenotype_by_region. Example input/reference_data/TAD/protocol_example_protein.enhanced_cis_chr22.bed:
```
#chr   start  end       gene_id
chr22  0      18960000  ENSG00000131100_P36543
```
--TAD-list: the TAD boundary file for phenotype_annotate_by_tad, in the same 4-column shape. Example input/reference_data/TAD/TADB_enhanced_cis.bed.
--phenotype-per-tad: the minimum number of features a TAD must contain to be kept, 2 by default.
--region: coordinates passed through to samtools view by bam_subsetting, for example --region chr21 chr22.
--keep-samples: for gct_extract_samples, a file listing the sample IDs to retain, one per line. Example input/colocboost/keep_samples.txt:
```
SAMPLE_001
SAMPLE_002
SAMPLE_003
```
--name: the stem of the output files, derived from --phenoFile by default.
--cwd: the directory outputs are written to.

Output#

{cwd}/{name}.{chrom}.bed.gz - one phenotype BED per requested chromosome, with a tabix index, from phenotype_by_chrom.
{cwd}/{name}.phenotype_by_chrom_files.txt and {cwd}/{name}.phenotype_by_chrom_files.region_list.txt - the manifest of those per-chromosome files and the matching region list, both written by the collecting substep. Example output/phenotype_protein/protocol_example_protein.phenotype_by_chrom_files.region_list.txt:
```
#chr   start     end       ID                      path
chr22  17592135  17628748  ENSG00000131100_P36543  output/phenotype_protein/protocol_example_protein.chr22.bed.gz
```
{cwd}/{region_list}_phenotype_by_region/{name}.{region}.bed.gz and {cwd}/{name}.phenotype_by_region_files.txt - the per-region equivalents from phenotype_by_region.
{cwd}/{phenoFile}.{TAD_list}.{n}_pheno_per_region.region_list - the TAD-grouped region list from phenotype_annotate_by_tad.
{cwd}/{name}.{chrom}.gct - one GCT per chromosome, from phenotype_by_chrom_gct.
{cwd}/{bam}.subsetted.bam - the coordinate-restricted BAM from bam_subsetting.
{phenoFile}.sample_matched.gct.gz - the sample-filtered GCT from gct_extract_samples, written beside its input rather than under --cwd.

Minimal Working Example#

Partition a phenotype BED by chromosome#

phenotype_by_chrom runs two substeps in sequence: _1 pulls the records for each requested chromosome out of the tabix-indexed BED and writes a per-chromosome bed.gz with its index, and _2 collects those into the *_files.txt and *.region_list.txt lists. This is the partitioning cis TensorQTL analysis needs. Only chr22 is present in the toy phenotype data.