VIEWpoly: a visualization tool to integrate and explore results of polyploid genetic analysis
Cristiane Taniguti, Gabriel de Siqueira Gesteira, Jeekin Lau, Guilherme da Silva Pereira, David Byrne, Zhao-Bang Zeng, Oscar Riera-Lizarazu and Marcelo Mollinari
2022-07-27
Introduction
VIEWpoly is a shiny app and R package for visualizing
and exploring results from polyploid computational tools
using an interactive graphical user interface. The package allows users
to directly upload output files from polymapR
(Bourke et al. (2018)), MAPpoly
(Mollinari et al. (2019)), polyqtlR
(Bourke et al. (2021)), QTLpoly
(Pereira et al. (2019)), diaQTL (Amadeu et al. (2021)) and genomic assembly,
variants, annotation and alignment files. VIEWpoly uses shiny,
golem,
ggplot2,
plotly,
and JBrowseR
libraries to integrate and graphically display the QTL profiles,
positions, estimated allele effects, progeny individuals containing
specific haplotypes, and their breeding values. When genomic information
is available, QTL positions can be interactively explored using JBrowseR
interface, allowing the search for candidate genes. The software allows
for visualization of parental haplotypes and marker dosages, and
provides features to download specific information into comprehensive
tables and images for further analysis and presentation.
The app is organized in the Input data section and three
main modules: VIEWqtl, VIEWgenome, and
VIEWmap. Please check our tutorial video
for a step-by-step guide through all VIEWpoly’s features
and functionalities.
Install and run the app
VIEWpoly is available in both stable and development
versions. To install and load its stable version from the CRAN
repository, please run:
install.packages("viewpoly")
viewpoly::run_app()If you want to install and check the development version from the Github repository, please run the commands below:
install.packages("devtools")
devtools::install_github("mmollina/viewpoly")
viewpoly::run_app()NOTE: Windows users may need to install Rtools
before running the commands above.
The four VIEWpoly’s main modules are available in the
top menu, which are described in the following sections:
Input data
The first module allows users to upload datasets or select pre-loaded examples. Uploaded datasets may include results from at least one of the following: linkage analysis, QTL analysis. Users can use RData or standard format files (CSV and TSV) to upload linkage and QTL analysis results. Genome assemblies can be provided in the regular FASTA format. VIEWpoly also accepts remote URLs to access genome-related files on-the-fly (see description here), and can optionally integrate other genomic information (GFF3, VCF, BAM, WIG files).
Please note that each section accepts multiple options for the same type of analysis. When files for more than one option is provided, only the last one will be displayed. Users need to make sure that linkage, QTL and genome-related files are tied to each other, e.g., uploaded QTL results were obtained using the uploaded linkage map, and both were based on the same uploaded genome assembly and gene annotation versions. Each section-related features will be enabled once their respective files are uploaded. The package also detects results from the supported software that are currently loaded in the R environment.
The app will automatically convert linkage and QTL analysis results
to the VIEWpoly file format. Users may optionally download it using the
Download VIEWpoly dataset button, so it can be used in
future sessions to expedite data processing and loading time. This file
can be loaded directly within the R environment (code:
load("my_dataset.RData")) or uploaded using the
Upload VIEWpoly dataset button. Due to their size, genome
information cannot be stored using the VIEWpoly data structure, so these
files need to be provided each section.
Available example datasets
Linkage and QTL analysis results from a previous study in a tetraploid potato (S. tuberosum) mapping population are available as a pre-loaded example in the app:
NOTE: to save space in the package repository, only a small subset of the progeny individuals is provided.
Other example files are available here, including data from an hexaploid sweetpotato (I. batatas) mapping population:
Users may choose one of the pre-loaded examples to explore the software features. By default, the app will display the tetraploid potato dataset.
Upload linkage map files
Click in the + on the right side of the
Upload linkage map files box to upload linkage analysis
results:
Users can upload files in three different formats:
MAPpoly, polymapR, and standard formats (CSV
or TSV files). There is a brief description with useful links on how to
build linkage maps and obtain the necessary files using the supported
packages.
Upload MAPpoly
All you need is an object of class mappoly.map saved in
a RData file. Click on the + icon in the upper right side
of the box to upload the file:
Click in Browse... to search the file on your computer
and load it into the app.
Wait for the upload to complete and click in the submit button (in
this case:submit MAPpoly):
NOTE: if you want to make changes to any uploaded file, please click
on the reset button before uploading new files.
Here is an example code to get this input object using data of the MAPpoly
tutorial:
lg10.map <- est_rf_hmm_sequential(input.seq = LGS[[10]]$seq, start.set = 10, thres.twopt = 10, thres.hmm = 10, extend.tail = 30, info.tail = TRUE, twopt = LGS[[10]]$tpt, sub.map.size.diff.limit = 8, phase.number.limit = 20, reestimate.single.ph.configuration = TRUE, tol = 10e-3, tol.final = 10e-4)
lg10.map.mds <- est_rf_hmm_sequential(input.seq = LGS.mds[[10]]$seq, start.set = 10, thres.twopt = 10, thres.hmm = 10, extend.tail = 30, info.tail = TRUE, twopt = LGS.mds[[10]]$tpt, sub.map.size.diff.limit = 10, phase.number.limit = 20, reestimate.single.ph.configuration = TRUE, tol = 10e-3, tol.final = 10e-4)
map_list <- list(lg10.map, lg10.map.mds)
save(map_list, file = "my_mappoly_list.RData") Upload polymapR output
The app expects two RData files for polymapR-based maps:
one with dosage information and the other with phase information. Here
is an example on how to obtain these files using a function from polymapR
tutorial:
ALL_dosages <- read.csv("tetraploid_dosages.csv", stringsAsFactors = FALSE, row.names = 1) #first column contains rownames
save(ALL_dosages, file = "polymapR.dataset.RData")
phased.maplist <- create_phased_maplist(maplist = integrated.maplist, dosage_matrix.conv = filtered_data, N_linkages = 5, ploidy = 4, marker_assignment.1 = marker_assignments$P1, marker_assignment.2 = marker_assignments$P2)
save(phased.maplist, file = "polymapR.map.RData") Click on the + icon in the upper right side of the box
to upload the necessary files, select the data type and ploidy level,
then click on submit polymapR.
Upload linkage map files with stardard format (.csv, .tsv or tsv.gz)
Users have the option to submit linkage map files in standard file
formats, including .csv, .tsv, and .tsv.gz. Please download the example
files that are available to check for the correct format and structure.
You can do so by selecting one of the supported file types and clicking
on the Download button at the bottom of the box.
After formatting and submitting the necessary files, click on the
submit map custom buttom at the upper right corner of the
box.
Upload QTL analysis files
This section allows users to upload files containing results from QTL
mapping analysis using one of the four data formats:
QTLpoly, diaQTL, polyqtlR, or
standard formats.
Users may choose one of the options and click on the +
on the upper right side of the box to open the description of the
necessary files.
Upload QTLpoly output
When the QTL analysis is performed using the QTLpoly
package, users need to upload four files containing objects of the
following classes: qtlpoly.data,
qtlpoly.remim, qtlpoly.effects, and
qtlpoly.fitted. The code below shows an example on how to
generate the such objects using QTLpoly functions (see the
QTLpoly
tutorial for details):
data <- read_data(ploidy = 6, geno.prob = genoprob, pheno = pheno, step = 1)
save(data, file = "QTLpoly_data.RData")
remim.mod <- remim(data = data, w.size = 15, sig.fwd = 0.01, sig.bwd = 1e-04, d.sint = 1.5, n.clusters = 4, plot = "remim")
save(remim.mod, file = "QTLpoly_remim.mod.RData")
est.effects <- qtl_effects(ploidy = 6, fitted = fitted.mod)
save(est.effects, file = "QTLpoly_est.effects.RData")
fitted.mod <- fit_model(data = data, model = remim.mod, probs = "joint", polygenes = "none")
save(fitted.mod, file = "QTLpoly_fitted.mod.RData") After loading the required files, click on the
submit QTLpoly button at the upper right corner of the
box:
Upload diaQTL output
Similarly, users need to upload four files to display QTL mapping
results from the diaQTL package. The code below shows an
example on how to use diaQTL functions to generate the
required objects (see the diaQTL
tutorial for details):
ans1 <- scan1(data = data, trait = "tuber_shape", params = list(burnIn=50,nIter=500), n.core = 2)
ans2 <- scan1(data = data, trait = "height", params = list(burnIn=50,nIter=500), n.core = 2)
scan1_list <- list(ans1, ans2)
names(scan1_list) <- c("tuber_shape","height")
save(scan1_list, file = "diaQTL_scan1_list.RData")
summary_ans1 <- scan1_summary(ans1, position="bp")
summary_ans2 <- scan1_summary(ans2, position="bp")
scan1.summaries_list <- list(summary_ans1, summary_ans2)
names(scan1.summaries_list) <- c("tuber_shape","height")
save(scan1.summaries_list, file = "diaQTL_scan1.summaries_list.RData")
bayes1 <- BayesCI(ans1,data,chrom="5",CI.prob=0.9)
bayes2 <- BayesCI(ans1,data,chrom="7",CI.prob=0.9)
bayes3 <- BayesCI(ans1,data,chrom="10",CI.prob=0.9)
BayesCI_list <- list(cbind(pheno = "tuber_shape", bayes1),
cbind(pheno = "tuber_shape", bayes2),
cbind(pheno = "tuber_shape", bayes3))
save(BayesCI_list, file = "diaQTL_BayesCI_list.RData")
fit1.1 <- fitQTL(data=data, trait="tuber_shape", params=params, qtl=model1.1) # Selected model for phenotype tuber_shape
fit2.2 <- fitQTL(data=data, trait="height", params=params, qtl=model2.2,
epistasis=data.frame(marker1=qtl.10at63,marker2=qtl.1at133)) # Selected model for phenotype height
fitQTL_list <- list(fit1.1, fit2.2)
names(fitQTL_list) <- c("tuber_shape","height")
save(fitQTL_list, file = "diaQTL_fitQTL_list.RData")Once the required files are loaded, click on the
submit diaQTL button at the upper right corner of the
box.
Upload polyqtlR output
When the QTL mapping is performed using the polyqtlR
package, only three input files are necessary. The code below shows how
to use polyqtlR functions to generate the required objects
(see the polyqtlR
tutorial for details). Since all combinations of phenotypes and
linkage groups are necessary to display the results correctly, users
need to organize the results after performing the QTL analysis with
polyqtlR:
qtl_info <- effects <- data.frame()
qtl_LODs.4x.trait1 <- QTLscan(IBD_list = IBD_4x, Phenotype.df = Phenotypes_4x, genotype.ID = "geno", trait.ID = "pheno1", block = "year")
qtl_LODs.4x.trait2 <- QTLscan(IBD_list = IBD_4x, Phenotype.df = Phenotypes_4x, genotype.ID = "geno", trait.ID = "pheno2", block = "year")
polyqtlR_QTLscan_list <- list(trait1 = qtl_LODs.4x.trait1, trait2 = qtl_LODs.4x.trait2)
save(polyqtlR_QTLscan_list, file = "polyqtlR_QTLscan_list.RData")
# Get information for each phenotype and group
LGs <- unique(polyqtlR_QTLscan_list[[1]]$Map$chromosome)
qtl_info <- effects <- data.frame()
for(i in 1:length(polyqtlR_QTLscan_list)){
pheno <- names(polyqtlR_QTLscan_list)[i]
for(j in 1:length(LGs)){
# Get QTL peak
if (is.null(polyqtlR_QTLscan_list[[i]]$Perm.res)) {
thresh <- 0
} else {
thresh <- polyqtlR_QTLscan_list[[i]]$Perm.res$threshold
}
lgdata <- polyqtlR_QTLscan_list[[i]]$QTL.res[polyqtlR_QTLscan_list[[i]]$QTL.res$chromosome ==
LGs[j], ]
maxdata <- lgdata[which.max(lgdata$LOD), ]
if (maxdata$LOD >= thresh) {
qtl_info_temp <- cbind(maxdata, thresh = thresh)
} else qtl_info_temp <- NULL
if(!is.null(qtl_info_temp)){
qtl_info_temp <- data.frame(LG = qtl_info_temp$chromosome,
Pos = qtl_info_temp$position,
pheno = pheno,
Pos_lower = NA, # Add here QTL confidence interval if exist
Pos_upper = NA,
thresh = qtl_info_temp$thresh)
qtl_info <- rbind(qtl_info, qtl_info_temp)
}
# Get effects
effects.t <- visualiseQTLeffects(IBD_list = IBD_4x,
Phenotype.df = polyqtlR_phenotypes,
trait.ID = pheno,
linkage_group = j,
LOD_data = polyqtlR_QTLscan_list[[i]],
genotype.ID = colnames(polyqtlR_phenotypes)[1],
return_plotData = TRUE)
effects.t <- data.frame(pos= IBD_4x[[j]]$map$position, pheno = pheno, LG = j, effects.t)
effects <- rbind(effects, effects.t)
}
}
save(qtl_info, file = "tetra_polyqtlR_qtl_info.RData")
save(effects, file = "tetra_polyqtlR_effects.RData")Upload QTL analysis results with standard format (.csv, .tsv or .tsv.gz)
Users may choose to submit the QTL analysis files with standard formats. We encourage you to download the available example files at the bottom of the section to check whether your input data files are in the correct format:
Upload Genome Browser files
Providing URLs or uploading files in this section will enable
accessing the Genome tab features. All information will be
included as tracks into the JBrowseR genome explorer.
Only the assembly (FASTA) file is required to access the feature, while
other genomic data such as gene annotation and alignment files are
optional.
Please choose only one of the options for all submitted files: URL or upload files. Do not submit some of them through upload and others through URL.
Providing the files through URL improves VIEWpoly efficiency. You can check further descriptions about these options in the JBrowseR tutorial.
- Assembly
Any FASTA file should have gone through a series of steps to standardize its format, which basically involves file compression and indexation. You can compress the FASTA file using bgzip:
bgzip NSP306_trifida_chr_v3.faThen index it using samtools:
samtools faidx NSP306_trifida_chr_v3.fa.gzPlease notice that all files (FASTA.GZ, FASTA.GZ.GZI, and GZ.FAI ) should be submitted through the app if you have chosen the option of uploading the files:
Or they should be hosted together in the provided URL directory:
- Annotation
Users may need to sort the annotation file before uploading it. For that you can use the following code:
sort -k1,1 -k4,4n NSP306_trifida_v3.hc.gene_models.gff3 | bgzip > NSP306_trifida_v3.hc.gene_models.sorted.gff3.gz After sorting it, one can generate the indexes with tabix:
tabix -p gff NSP306_trifida_v3.hc.gene_models.sorted.gff3.gz- Variants
Variant files are accepted in the VCF format, and should be indexed. One may index it with tabix:
tabix -p variants.vcf- Alignment
Alignment files are accepted in both BAM and CRAM formats. The former must be accompanied by BAI or CSI files, whereas the latter must be accompanied by its respective CRAI file. One can create BAI index files with samtools:
samtools index *.bam- bigWig
No indexation is required for bigWig files. Please check the JBrowse documentation for more information.
Download VIEWpoly dataset
Once the linkage map and QTL analysis results are uploaded, VIEWpoly
will convert all necessary objects to a single R object of class
viewpoly. The app basically keeps only the information
required for building graphics for linkage and QTL analysis. Users have
the option to download the final RData object by clicking the
Download button.
Upload VIEWpoly dataset
Once a VIEWpoly object is generated, it is possible to
access the VIEWpoly features for this dataset by just
submitting this unique file in the Upload VIEWpoly dataset
box:
The app also automatically detects and lists any
VIEWpoly object that is loaded into the current R
environment session:
load("viewpoly.RData")
viewpoly::run_app()
When more than one VIEWpoly object is available in the
current R environment session, they will be listed so users can select
which one they want to visualize:
Please remember to press the submit button after
uploading the VIEWpoly file or choosing a pre-loaded
object. Users can go back to the
Upload Genome Browser files at any time to upload
genome-related information for the current session.
VIEWqtl: the QTL Browser
Select linkage groups and phenotypes
This module allows users to explore any of the linkage groups and/or phenotypes, individually or together. Users can use the two upper boxes to select and explore the desired features:
QTL profile
Once the desired groups and phenotypes are selected, their respective QTL profile curve(s) will show up for each trait (line colors) with their associated measure of statistical significance (that can be different according to the software used) on the y-axis, for each map position (x-axis). The triangles in the bottom represent the peaks of significant QTL. The black line spanning the triangle defines the QTL supporting interval.
For QTLpoly-based analysis, a graphic like this will show up:
For diaQTL-based analysis, a graphic like this will show up:
For polymapR-based analysis, a graphic like this will show up:
Users are able to download these and other figures from
VIEWpoly by selecting the format in the
file type field and pressing the Download
button positioned right on top of each figure.
For further information about these graphics, please check Pereira et al. (2019), Amadeu et al. (2021) and Bourke et al. (2021) tutorials.
Effects
Please click and drag the mouse cursor to select the desired QTL triangles at the bottom of the graphic to explore particular haplotypic effects, check progeny breeding values, and get the QTL summary table:
WARNING: If you want to change the linkage group or phenotype selection, please deselect the triangles beforehand by clicking at any other location on the graphic. Not doing this will crash the app.
Click in the + in the right corner of the
Effects section to see the graphics. By default,
VIEWpoly displays the bar design:
- Additive (bar)
If you uploaded QTL data from QTLpoly, you will see a graphic like this:
This graphic displays the additive effect for each parental haplotype on the selected QTL positions. Color shades emphasize the intensity of the effects.
If you uploaded QTL data from diaQTL, you will see a graphic like this:
If you uploaded QTL data from polymapR, you will see a graphic like this:
This graphic plots the intensity of the effects across the entire linkage group for the selected QTL phenotype.
- Additive (circle)
Changing the Design to Additive (circle)
the intensity of the effects is plotted in a circle graphic. The
selected QTL from the same linkage group are plotted together in the
same graphic. To be possible to compare the effects across different QTL
and phenotypes, the values are standardized to be between -1 (center or
circle) and 1. The dots colors are more intense close to the extreme
values (-1 and 1) and their transparency increase when they are close to
0.
This design is only available for QTLpoly and diaQTL software results.
- Alleles combination
Changing the Design to Alleles combination
a heatmap is plotted with the combined alleles (parents alleles x-axis x
parents alleles y-axis) sum of additive and digenic effects in the upper
diagonal and just the additive in the bottom diagonal.
This design is only available for QTLpoly and diaQTL software results.
If you uploaded QTL data from QTLpoly, you will see something like this:
QTLpoly only considers additive effects.
If you uploaded QTL data from diaQTL, you will see something like this:
For further information about this graphics, please check Pereira et al. (2019), Amadeu et al. (2021) and Bourke et al. (2021).
Progenies haplotypes
To access this feature, first set the Design to
Additive (bar). By now, it is only implemented for results
coming from QTLpoly.
Click on update available haplotypes button and after in
the right corner of the Select haplotypes gray box, a
window will open presenting all possible parents alleles for the QTL
selected in the QTL profile graphic. You can select any combination of
alleles and, after clicking on submit selected haplotypes,
VIEWpoly will search the individuals in the progeny that have a
probability higher than 0.5 of having all the alleles selected.
For example, here we selected the allele P1.1 and P2.2 in LG 5, position 0 referring to the QTL for trait ST08 (Trait:ST08_LG:5_Pos:0_homolog:P1.1; Trait:ST08_LG:5_Pos:0_homolog:P2.1), P1.2 in LG 5, position 28 referring to the QTL for trait NI08 (Trait:NI08_LG:5_Pos:28_homolog:P1.2) and P2.4 in LG 5, position 26 referring to the QTL for trait FM14 (Trait:FM14_LG:5_Pos:26_homolog:P2.3).
VIEWpoly displays the genotype probability profile for each individual identified with the selected alleles. The QTL position are pointed by dashed vertical lines. If only one linkage group is selected, the graphic will split vertically the probabilities for each possible homolog:
In case we include the QTL for trait NS06 in chromosome 1 and try to find also individuals that have the allele P1.1 in this QTL position:
Because two groups must be represented in this case, the graphic design change to a stacked version.
Breeding values
This feature is only available for software QTLpoly. Only the effects of the selected QTL in the QTL profile graphic are considered to estimate the breeding values.
You can download the tables in VIEWpoly by clicking on the top
buttons. CSV, Excel and PDF formats are available. Copy
will copy the table to your clipboard.
QTL summary
VIEWpoly also provides a table with some of the main information about the selected QTL. This table also changes according to the software used to evaluate the QTL.
VIEWgenome: the Genome Browser
This module has the goal to relate the QTL position in the linkage map with the available genomic information.
Select phenotypes and linkage group
The visualization here is made defining a range in the
Map range (cM) section by chromosome. Therefore, you can
select only one chromosome to be visualized at the time. You can also
select the phenotypes then the QTL positions and confidence interval are
plotted just below the range. The QTL profile graphic will be also
available in the QTL profile section.
QTL profile
Click on the + on the right corner of the
QTL profile section to access a plotly graphic with the QTL
significance profile.
Linkage Map x Physical
A scatterplot of the genetic versus the physical positions is displayed to highlight the relationship between the genetic map, the reference genome, the QTL positions and intervals, and the recombination rate along the chromosomes.
JBrowseR
If you uploaded the genome information in the Input data
tab, you can click on Open JBrowseR to visualize the genome
and all the tracks according to the files uploaded:
The range in the genome is set from the position of the first marker e to the position of the last marker in the selected linkage map range.
Changing the range:
You can also explore all the JBrowse features by clicking on the buttons inside the window.
For example, zoom in:
Access the menu clicking in the upper left corner:
For further information about the JBrowseR features, please access its documentation.
If you uploaded the genome files instead of using the URLs, VIEWpoly
creates a local server to host the genome files to JBrowseR to be able
to access it. Before exiting the app or changing the genome file, you
must turn off the generated server by clicking on the button
Local server section. If not, the server will only be off
when you close or restart R.
Annotation table
If you uploaded the GFF3 file in the Input data section,
a table will be available with annotation information inside the range
selected in the linkage map.
VIEWmap: the Map Browser
This module’s goal is to provide tools to explore the linkage map
proprieties. The sections to select the phenotypes and the linkage group
and to display the QTL profile are the same already described in the
QTL Browser
Map
In this section, it is plotted the parent’s haplotypes and linkage
map related to the range selected in the map range (cM). If
the reference and alternative alleles information are present in the
uploaded linkage map files, the variants are represented with different
colors for each nucleotide (A, T, C, and G) or indel (-). If this
information is not present, red and white will differentiate the
biallelic sites. The dots position and color represent the dosage
number.
Parents haplotypes table
The parents haplotypes information used to build the graphic can be download in this section in table format:
Map summary
VIEWpoly also provides a table with the linkage map main characteristics:
And the linkage map draw:
Help us to improve
If you find issues using VIEWpoly, write to us in the
issues tab in VIEWpoly
github page. If you would like to contribute adding new features,
please, follow these
guidelines.