Functions
PALM()
PALM() generates a frequency heatmap for an HLA allele, HLA amino-acid motif, or HLA haplotype. Alleles and amino acid motif maps are generated based on the allele frequency data in the Solberg dataset, or the user provided dataset. Haplotypes maps are generated based on the mock haplotype dataset, or the user specified dataset. User specified datasets MUST follow the same format and convention as the Solberg Dataset or mock haplotype dataset. Maps are created using the gmt R package and the Generic Mapping Tools (GMT) map-making software. GMT software is required for this function and can be downloaded at https://www.soest.hawaii.edu/gmt/.
JPEG heatmap files named “‘variant’.jpg”, where ‘variant’ is an
allele, motif, or haplotype, are written to a directory identified by
the direct parameter, with the working directory set as the default. The
file names of maps generated on Microsoft Windows systems have a
different delimiter between the locus name and the amino acid positions;
instead of an asterisk (*), a dash (-) is used to accommodate for
Windows naming conventions (e.g. DRB1-26F~28E~30Y).
The filename parameter is either the full path to the
user specified dataset, the Solberg dataset bunded in the package, or
the mock haplotype dataset bundled in the package.
The variantType parameter identifies whether the variant
entered is an allele, motif, or haplotype. The variantType
parameter must be changed to ‘allele’ if an allele frequency map is
desired, or changed to ‘haplotype’ if a haplotype frequency map is
desired. Alleles in haplotypes may be delimited with “-” or “~”.
The mask parameter defaults to FALSE, where all areas on
the generated map are visible. If mask = TRUE, areas with
little to no data table coverage will be masked out.
The color and filter_migrant parameters
default to TRUE. When color = TRUE, PALM generates a color
heatmap; when color = FALSE, a greyscale heatmap is
generated. When filterMigrant = TRUE, populations from the
OTH region and populations with complexity values suffixed with ‘mig’,
or migrant populations, are excluded from the heatmap plot. When
filter_migrant = FALSE, these populations are included in
the heatmap plot.
The mapScale parameter determines if the max frequency
of the map scale should be 1, or the max frequency of the chosen motif,
allele, or haplotype. When mapScale = TRUE, which is the
default, the max frequency of the chosen variant is used. When
mapScale=FALSE, the max frequency is 1.
The direct parameter is the working directory to output
created maps to. The default is the user’s current working
directory.
The generateLowFrequency parameter determines whether
maps should be generated for a variant if the maximum frequency for the
variant is low frequency. Low frequency populations are defined as those
with a frequency of 0.000, indicating three zeros after the decimal
point.
The resolution parameter is an integer value for raster
resolution in dpi for the final map output. It is not recommended to go
below 400. Default is set to 500.
If an allele with more than two fields is entered and the Solberg dataset is selected as the data source, the allele will automatically be truncated to two fields, as the Solberg dataset only contains two field alleles.
The Ghostscript software suite (>= version 9.26) is required to
generate the heatmap file. Versions of Ghostscript < 9.26 introduce a
layering error during heatmap generation. To determine if maps are being
generated correctly, compare heatmaps of the
DRB1*26F~28E~30Y motif (with filter_migrant = TRUE) against
the examples in this vignette.
Note: While the map legend identifies the highest frequency value, values in this range may not be represented on the map due to frequency averaging over neighboring populations.
#color motif heatmap plot with masking OFF
>PALM("DRB1*26F~28E~30Y", variantType="motif", filename=SSHAARP::solberg_dataset, resolution = 480)
…
#greyscale allele heatmap plot with masking OFF
> PALM("DRB1*01:01", variantType="allele", color=F, mask = T, filename=SSHAARP::solberg_dataset, resolution = 480)
…
#color haplotype heatmap plot with masking OFF with bundled mock haplotype dataset
PALM("A*01:01~DRB1*01:01", variantType="haplotype", filename=SSHAARP::mock_haplotype_dataset, color = TRUE, resolution = 480)
…
#if the locus of a variant is valid but not in the Solberg dataset, a warning message is output:
> PALM("TAP1*01:01", variantType="allele", filename=SSHAARP::solberg_dataset)
Warning message:
In PALM("TAP1*01:01", variantType = "allele", filename=SSHAARP::solberg_dataset) :
TAP1 is a valid locus, but is not in the Solberg dataset
#if an amino acid motif does not exist, a warning is output:
>PALM('A*-24F', variantType = "motif", filename=SSHAARP::solberg_dataset)
Warning message:
In PALM("A*-24F", variantType = "motif", filename = SSHAARP::solberg_dataset) :
A*-24F: No alleles possess this motif
#if an amino acid motif exists but is not found in the Solberg dataset, a warning is output:
>PALM("DRB1*-25R~13S~16H~26Y~47Y~86V", variantType="motif", filename=SSHAARP::solberg_dataset)
Warning message:
In PALM("DRB1*-25R~13S~16H~26Y~47Y~86V", variantType="motif", filename=SSHAARP::solberg_dataset) :
DRB1*-25R~13S~16H~26Y~47Y~86V: No alleles possess this motif
#if an allele is not found in IMGTprotalignments, a warning is output:
> PALM("DRB1*01999:01", variantType="allele",filename=SSHAARP::solberg_dataset)
Warning message:
In PALM("DRB1*01999:01", variantType = "allele", filename=SSHAARP::solberg_dataset) :
The allele you entered is not present in the current release of ANHIG/IMGTHLA alignments.
#if an allele is valid but is not present in the Solberg dataset, a warning is output:
> PALM("A*01:37", variantType = "allele", filename=SSHAARP::solberg_dataset)
Warning message:
In PALM("A*01:37", variantType = "allele", filename=SSHAARP::solberg_dataset) :
The A*01:37 allele entered is a valid allele and exists in the IMGT protein alignments, but is not present in the Solberg dataset.