R/plot_contig.R

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

#' @title Mapping contig
#'
#' @description Generates a linear plot of RADSex mapping results for a specified contig. The resulting figure contains two plot: the top plot shows sex-bias against
#' position on the contig, and the bottom plot shows probability of association with sex against position on the contig.
#' A specific region of the contig can also be plotted.
#'
#' @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 contig Name of the contig to plot.
#'
#' @param region A vector of two integers specifying the region of the contig to plot (default NULL).
#'
#' @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 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 title Title of the plot (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 signif.threshold Significance threshold for association with sex (default 0.05).
#'
#' @param point.size Size of a point in the plot (default 1.5).
#'
#' @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 significance.line.color Color for significance line, set to NULL for no line (default "black").
#'
#' @param significance.line.type Linetype for the significance line, as usually defined in R (default 2).
#'
#' @param significance.text.position X and Y axis offset for the significance text, as fractions of total axis length (default c(0.05, 0.05)).
#'
#' @examples
#'
#' plot_contig("mapping_results.tsv", "contig_lengths.tsv", "LG01", region = c(10000000, 15000000),
#'             output_file_path = "mapping_results.png", width = 10, height = 7)


plot_contig <- function(mapping_file_path, contig_lengths_file_path, contig, region = NULL,
                        chromosomes_names_file_path = NULL, title = NULL,
                        output_file_path = NULL, width = 12, height = 8, dpi = 300,
                        color.sex.bias = TRUE, sex.bias.palette = c("firebrick1", "grey10", "dodgerblue2"),
                        association.color = "grey20",
                        signif.threshold = 0.05, point.size = 1.5,
                        significance.line.color = "black",
                        significance.line.type = 2,
                        significance.text.position = c(0.05, 0.05)) {

    # 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 = TRUE)

    # Generate plot
    contig_plot <- mapping_contig(mapping_data, contig = contig, region = region, title = title,
                                  signif.threshold = signif.threshold, point.size = point.size,
                                  color.sex.bias = color.sex.bias, sex.bias.palette = sex.bias.palette,
                                  association.color = association.color,
                                  significance.line.color = significance.line.color,
                                  significance.line.type = significance.line.type,
                                  significance.text.position = significance.text.position)

    # Save the plot to output file if specified, otherwise display the plot
    if (!is.null(output_file_path)) {
        cowplot::ggsave(output_file_path, plot = contig_plot$combined, width = width, height = height, dpi = dpi)
    } else {
        print(contig_plot$combined)
    }

    return(contig_plot)
}