R/plot_genome_circular.R

In RomainFeron/radsex-vis: Visualization of results from the RADSex pipeline

#' @title Mapping circular plot
#'
#' @description Generates a circular plot of RADSex mapping results in which each sector represents a linkage group and
#' the x-axis represents the position on the linkage group. The y-axis on the first track shows the sex-bias of a sequence, and the second track shows the
#' probability of association with sex of a sequence.
#'
#' @param mapping_file_path Path to a mapping results file generated by RADSex map.
#'
#' @param contig_lengths_file_path Path to a contig lengths file generated by RADSex map.
#'
#' @param chromosomes_names_file_path Path to a chromosomes names file, i.e. a tabulated file with name in the reference genome file as the first column and
#' corresponding chromosome name as the second column. If the chromosomes names in the reference genome file start with "LG", "NC", or "CHR" (case unsensitive),
#' chromosomes can be detected automatically (default NULL).
#'
#' @param plot.unplaced If TRUE, unplaced contigs will be plotted as a supercontig (default TRUE).
#'
#' @param output_file_path Path to the plot output file. If the output file is not specified, the circular plot will be plotted in the default device (default NULL).
#'
#' @param width Width of the output file in pixels (default 1400).
#'
#' @param height Height of the output file in pixels (default 1400).
#'
#' @param res Resolution of the output file in \% (default 100).
#'
#' @param highlights A vector of scaffolds to highlight: c("LG1", "LG7", "scaffold_8") ... (default NULL).
#'
#' @param zoom.highlights If TRUE, highlighted scaffolds will be zoomed on at the top of the plot (default FALSE).
#'
#' @param zoom.ratio Zooming factor for highlighted scaffolds, i.e. a size multiplier (default 2)
#'
#' @param zoom.suffix A suffix to add after the name of a zoomed scaffold (default " (zoom)")
#'
#' @param point.size Size of a point in the plot (default )
#'
#' @param base.color Background color of a standard sector of the plot (default "white").
#'
#' @param highlight.color Background color of a highlighted sector of the plot (default "grey80").
#'
#' @param color.sex.bias If TRUE, points on the sex-bias track will be colored according to sex.bias.palette (default TRUE).
#'
#' @param sex.bias.palette A vector of three colors defining the sex-bias track palette: female-biased, neutral, male-biased. (default c("firebrick1", "black", "dodgerblue2"))
#'
#' @param color.unmapped If TRUE, unmapped scaffolds will be colored with alternating colors, similar to a manhattan plot (default TRUE).
#'
#' @param unmapped.paltte A named vector of three colors: "0" = alternating color 1, "1" = alternating color2, and "2" = color for mapped scaffolds (default c("0"="dodgerblue3", "1"="goldenrod1", "2"="grey30")).
#'
#' @param signif.threshold Significance threshold for association with sex (default 0.05).
#'
#' @param sector.title.expand A factor that controls the distance between sector titles and sector top axes (default 1.9).
#'
#' @examples
#' plot_genome_circular("mapping_results.tsv", "contig_lengths.tsv", chromosomes_names_file_path = "chromosomes_names.tsv",
#'                      output_file_path = "mapping_results.png", highlight = c("LG24"), zoom.highlights = TRUE, zoom.ratio = 4, point.size = 0.25,
#'                      color.sex.bias = TRUE, sex.bias.palette = c("firebrick1", "grey10", "dodgerblue2"), color.unmapped = FALSE)
#'

plot_genome_circular <- function(mapping_file_path, contig_lengths_file_path, chromosomes_names_file_path = NULL, plot.unplaced = TRUE,
                                 output_file_path = NULL, width = 1400, height = 1400, res = 100,
                                 highlight = NULL, zoom.highlights = FALSE, zoom.ratio = 2, zoom.suffix = " (zoom)",
                                 base.color = "white", highlight.color = "grey80", point.size = 0.5,
                                 color.sex.bias = TRUE, sex.bias.palette = c("firebrick1", "black", "dodgerblue2"),
                                 color.unmapped = TRUE, unmapped.palette = c("0"="dodgerblue3", "1"="goldenrod1", "2"="grey30"),
                                 signif.threshold = 0.05, sector.titles.expand = 1.9) {

    # Check that all files exist and can be opened
    if (!file.exists(mapping_file_path)) {
        stop(paste0("The specified input file (", mapping_file_path, ") does not exist."))
    }

    if (!file.exists(contig_lengths_file_path)) {
        stop(paste0("The specified contig lengths file (", contig_lengths_file_path, ") does not exist."))
    }

    if (!is.null(chromosomes_names_file_path)) {
        if (!file.exists(chromosomes_names_file_path)) {
            stop(paste0("The specified chromosomes names file (", chromosomes_names_file_path, ") does not exist."))
        }
    }

    # Load input files
    mapping_data <- load_mapping_results(mapping_file_path, contig_lengths_file_path,
                                         contig_names_file_path = chromosomes_names_file_path, plot.unplaced = plot.unplaced)

    # Create output device if specified
    if (!is.null(output_file_path)) {
        png(output_file_path, width = width, height = height, res = res)
    }

    # Generate plot
    mapping_circular_plot(mapping_data,
                          highlight = highlight, zoom.highlights = zoom.highlights, zoom.ratio = zoom.ratio, zoom.suffix = zoom.suffix,
                          base.color = base.color, highlight.color = highlight.color, point.size = point.size,
                          color.sex.bias = color.sex.bias, sex.bias.palette = sex.bias.palette,
                          color.unmapped = color.unmapped, unmapped.palette = unmapped.palette,
                          signif.threshold = signif.threshold, sector.titles.expand = sector.titles.expand)

    # Close output device if specified
    if (!is.null(output_file_path)) {
        dev.off()
    }
 }