ApplyPolygenicScore (version 4.0.1)

assess.pgs.vcf.allele.match: Assess PGS allele match to VCF allele

Description

Assess whether PGS reference and effect alleles match provided VCF reference and alternative alleles. Mismatches are checked for potential switching of effect and reference PGS alleles (cases where the effect allele is the REF VCF allele) and are evaluated for DNA strand flips (by flipping the PGS alleles). INDEL alleles are not supported for strand flip assessment.

Usage

assess.pgs.vcf.allele.match(
  vcf.ref.allele,
  vcf.alt.allele,
  pgs.ref.allele,
  pgs.effect.allele,
  return.indels.as.missing = FALSE,
  return.ambiguous.as.missing = FALSE,
  max.strand.flips = 0
)

Value

A list containing the match assessment, a new PGS effect allele, and a new PGS other allele.

Output Structure

The outputed list contains the following elements:

• match.status: A character vector indicating the match status for each pair of allele pairs. Possible values are default_match, effect_switch, strand_flip, effect_switch_with_strand_flip, ambiguous_flip, indel_mismatch, and unresolved_mismatch.

• new.pgs.effect.allele: A character vector of new PGS effect alleles based on the match status. If the match status is default_match, effect_switch or missing_allele, the original PGS effect allele is returned. If the match status is strand_flip or effect_switch_with_strand_flip the flipped PGS effect allele is returned. If the match status is ambiguous_flip, indel_mismatch, or unresolved_mismatch, the return value is either the original allele or NA as dictated by the return.indels.as.missing, return.ambiguous.as.missing, and max.strand.flips parameters.

• new.pgs.other.allele: A character vector of new PGS other alleles based on the match status, following the same logic as new.pgs.effect.allele.

The match.status output indicates the following:

• default_match: The default PGS reference allele matches the VCF REF allele and the default PGS effect allele matches one of the VCF ALT alleles.

• effect_switch: The PGS effect allele matches the VCF REF allele and the PGS reference allele matches one of the VCF ALT alleles.

• strand_flip: The PGS reference and effect alleles match their respective VCF pairs when flipped.

• effect_switch_with_strand_flip: The PGS effect allele matches the VCF REF allele and the PGS reference allele matches one of the VCF ALT alleles when flipped.

• ambiguous_flip: Both an effect switch and a strand flip have been detected. This is an ambiguous case caused by palindromic SNPs.

• indel_mismatch: A mismatch was detected between pairs of alleles where at least one was an INDEL. INDEL alleles are not supported for strand flip assessment.

• unresolved_mismatch: A mismatch was detected between pairs of non-INDEL alleles that could not be resolved by an effect switch or flipping the PGS alleles.

• missing_allele: One of the four alleles is missing, making it impossible to assess the match.

Arguments

vcf.ref.allele

A character vector of singular VCF reference (REF) alleles.

vcf.alt.allele

A character vector of VCF alternative (ALT) alleles. Multiple alleles at a multiallelic site must be separated by commas.

pgs.ref.allele

A character vector of singular PGS reference alleles aka "non-effect" or "other" alleles.

pgs.effect.allele

A character vector of singular PGS effect alleles.

return.indels.as.missing

A logical value indicating whether to return NA for INDEL alleles with detected mismatches. Default is FALSE.

return.ambiguous.as.missing

A logical value indicating whether to return NA for ambiguous cases where both a strand flip and effect switch are possible, or no strand flip is detected and a mismatch cannot be resolved. Default is FALSE.

max.strand.flips

An integer indicating the number of non-ambiguous strand flips that must be present to implement the discarding all allele matches labeled "ambiguous_flip". Only applies if return.ambiguous.as.missing == TRUE. Defaults to 0, meaning that no strand flips are allowed. Allele matches labeled "unresolved_mismatch" are not affected by this parameter.

Examples

# Example data demonstrating the following cases in each vector element:
# 1. no strand flips
# 2. effect allele switch
# 3. strand flip
# 4. effect allele switch AND strand flip
# 5. palindromic (ambiguous) alleles
# 6. unresolved mismatch
vcf.ref.allele <- c('A', 'A', 'A', 'A', 'A', 'A');
vcf.alt.allele <- c('G', 'G', 'G', 'G', 'T', 'G');
pgs.ref.allele <- c('A', 'G', 'T', 'C', 'T', 'A');
pgs.effect.allele <- c('G', 'A', 'C', 'T', 'A', 'C');
assess.pgs.vcf.allele.match(vcf.ref.allele, vcf.alt.allele, pgs.ref.allele, pgs.effect.allele);