buildAllPlots {JunctionSeq} | R Documentation

## Create and save a full battery of JunctionSeq expression plots.

### Description

Saves a large battery of plots displaying the analysis results, for the purposes of data visualization. By default it saves a full set of plots for every gene that shows statistical significance and the adjusted-p < 0.01 level. Alternatively, it can be supplied with a specific gene list using the `gene.list` parameter, and will plot those specific genes.

Note that this function has MANY parameters, allowing the user to tweak the appearance of the plots to suit their particular needs and preferences. Don't be daunted: the default parameters are probably fine for most purposes.

### Usage

    buildAllPlots(jscs,
        outfile.prefix = "./",
        gene.list = NULL, FDR.threshold = 0.01, max.gene.ct,
        method.selectionCriterion = c("feature-pAdjust", "genewise-pAdjust"),
        use.plotting.device = c("png","CairoPNG","svg",
                                "tiff","cairo_ps","custom"),
        sequencing.type = c("paired-end","single-end"),
        use.vst=FALSE,use.log = TRUE,
        exon.rescale.factor = 0.3,
        subdirectories.by.type = TRUE,
        ma.plot=TRUE, variance.plot=TRUE,
        with.TX=TRUE,without.TX=TRUE,
        expr.plot=TRUE,normCounts.plot=TRUE,
        rExpr.plot=TRUE,rawCounts.plot=FALSE,
        colorRed.FDR.threshold = FDR.threshold,
        colorList=list(),
        plot.gene.level.expression = TRUE,
        plot.exon.results, plot.junction.results, plot.novel.junction.results,
        plot.untestable.results = FALSE,
        plot.lwd=3, axes.lwd = plot.lwd, anno.lwd = plot.lwd,
        gene.lwd = plot.lwd / 2,
        par.cex = 1, anno.cex.text = 1, anno.cex.axis = anno.cex.text,
        anno.cex.main = anno.cex.text * 1.2,
        drawCoordinates = TRUE,
        yAxisLabels.inExponentialForm = FALSE,
        show.strand.arrows = 1,
        graph.margins = c(2, 3, 3, 3),
        base.plot.height = 12, base.plot.width = 12,
        base.plot.units = "in",
        GENE.annotation.relative.height = 0.15,
        TX.annotation.relative.height = 0.05,
        CONNECTIONS.relative.height = 0.1,
        SPLICE.annotation.relative.height = 0.1,
        TX.margins = c(0,0.5),
        autoscale.height.to.fit.TX.annotation = TRUE,
        autoscale.width.to.fit.bins = 35,
        plotting.device.params = list(),
        number.plots = FALSE,
        name.files.with.geneID = TRUE,
        condition.legend.text, include.TX.names = TRUE,
        draw.start.end.sites = TRUE,
        openPlottingDeviceFunc, closePlottingDeviceFunc,
        writeHTMLresults = TRUE,
        html.cssFile, html.cssLink, html.imgFileExtension,
        html.plot.height = 90, html.plot.height.units = "vh",
        html.compare.results.list = NULL,
        minimalImageFilenames = writeHTMLresults,
        verbose=TRUE, debug.mode = FALSE,
        INTERNAL.VARS = list(),
        ...)

### Arguments

`jscs` | A `JunctionSeqCountSet`. Usually created by `runJunctionSeqAnalyses`. Alternatively, this can be created manually by `readJunctionSeqCounts`. However in this case a number of additional steps will be necessary: Dispersions and size factors must then be set, usually using functions `estimateSizeFactors` and `estimateJunctionSeqDispersions`. Hypothesis tests must be performed by `testForDiffUsage`. Effect sizes and parameter estimates must be created via `estimateEffectSizes`.
`outfile.prefix` | The prefix file path to save the images to.
`gene.list` | Character vector. List of genes to plot. Either this variable OR FDR.threshold must be set.
`FDR.threshold` | If this option is used, genes will be selected for plotting based on the presence of statistically significant junctions. The adjusted-p-value threshold used to determine significance. Only genes containing at least 1 significant feature will be plotted.
`max.gene.ct` | Integer or numeric value. This option is usually only used with the FDR.threshold parameter (as opposed to the gene.list parameter). This option sets an upper limit to the number of genes to plot. This prevents JunctionSeq from taking too long to complete, or from using too much disk space if an enormous number of genes turn out to be significant at the selected significance value. If there are more genes than max.gene.ct, then JunctionSeq will only plot the top max.gene.ct genes.
`method.selectionCriterion` | Determines the method used to select genes for plotting. If set to "feature-pAdjust", genes will be selected if one or more features show significance. If "genewise-pAdjust" is used, gene-wise adjusted p-values will be generated and genes will be filtered on that basis.
`use.plotting.device` | The plotting device to use.
`sequencing.type` | The type of sequencing used, either "paired-end" or "single-end". This only affects the labelling of the y-axis, and does not affect the actual plots in any way.
`use.vst` | Logical. If `TRUE`, all plots will be scaled via a variance stabilizing transform.
`use.log` | Logical. If `TRUE`, all plots will be log-scaled.
`exon.rescale.factor` | Floating point numeric value. To improve readability the exons drawn in the coordinate annotation are rescaled by default so that they take up 30 percent of the x axis. This makes the plots easier to read, as exons are usually much smaller than introns and thus a group of clustered exons can be hard to distinguish when plotted on a simple scale. If this value is set to NA or a value not between 0 and 1 inclusive, then the exons and introns will be drawn on the same scale. Note that this function can also take the `exonRescaleFunction` parameter, which is passed to `plotJunctionSeqResultsForGene`.
`subdirectories.by.type` | Logical value. If `TRUE`, then subdirectories will be created for each plot type using outfile.prefix as a parent directory. Note that `FALSE` is not compatible with some functionality, including HTML generation. For advanced users only.
`ma.plot` | if TRUE, generate and save a MA plot. A MA-plot is a plot of fold change versus base mean normalized counts.
`variance.plot` | if TRUE, generate and save a plot of the dispersion as a function of the base mean.
`with.TX` | if TRUE, save expression plots with the full transcripts printed
`without.TX` | if TRUE, save expression plots with only the compiled exons printed. Note that if this and with.TX.plot are both TRUE, both versions will be saved seperately.
`expr.plot` | if TRUE, save an expression plot of the expression parameter estimates for each splice site, for each condition.
`normCounts.plot` | if TRUE, save an expression plot of the normalized mean counts for each splice site, for each sample.
`rExpr.plot` | if TRUE, save an expression plot of the expression parameter estimates, relative to gene-wide expression, for each splice site, for each condition.
`rawCounts.plot` | if TRUE, save an expression plot of the raw counts for each splice site, for each sample. Note that these will never be VST-transformed, even when use.vst == TRUE.
`colorRed.FDR.threshold` | The adjusted-p-value threshold used to determine whether a feature should be marked as "significant" and colored pink. By default this will be the same as the FDR.threshold.
`colorList` | A named list of R colors, setting the colors used for various things. See `plotJunctionSeqResultsForGene`
`plot.gene.level.expression` | Logical value. If `TRUE`, gene-level expression (when applicable) will be plotted beside the sub-element-specific expression in a small seperate plotting box. For the "relative expression" plots the simple mean normalized expression will be plotted (since it doesn't make sense to plot something relative to itself).
`plot.exon.results` | Logical. If `TRUE`, plot results for exons. By default everything that was tested will be plotted.
`plot.junction.results` | Logical. If `TRUE`, plot results for splice junctions. By default everything that was tested will be plotted.
`plot.novel.junction.results` | Logical. If `TRUE`, plot results for novel splice junctions. If false, novel splice junctions will be ignored. By default everything that was tested will be plotted.
`plot.untestable.results` | Logical. If `TRUE`, plots splice junctions that had coverage that was too low to be tested. Note that, in general, only normCounts and rawCounts plots will have non-`NA` values for untestable counting bins.
`plot.lwd` | The line width for the plotting lines.
`axes.lwd` | The line width for the axes.
`anno.lwd` | The line width for the various other annotation lines.
`gene.lwd` | The line width used for the gene annotation lines. The default is half the standard line width.
`par.cex` | The base cex value to be passed to par() immediately before all plots are created. See `par`.
`anno.cex.text` | The font size multiplier for most annotation text. This will be multiplied by a factor of the par.cex value. More specifically: The cex value to be passed to all function calls that take graphical parameters. See `par`.
`anno.cex.axis` | The font size multiplier for the axis text. This will be multiplied by a factor of the par.cex value. More specifically: The cex.axis value to be passed to all function calls that take graphical parameters. See `par`.
`anno.cex.main` | The font size multiplier for the main title text. This will be multiplied by a factor of the par.cex value. More specifically: The cex.main value to be passed to all function calls that take graphical parameters. See `par`.
`drawCoordinates` | Whether to label the genomic coordinates at the bottom of the plot.
`yAxisLabels.inExponentialForm` | Logical. If `TRUE`, then the y-axis will be labelled in exponential form.
`show.strand.arrows` | The number of strand-direction arrows to display. If equal to `1` (the default) then the arrow will extend from the end of the gene drawing, if it is greater than `1` then arrows will be drawn along the gene length. If it is `0` or `NA` then arrows will not be drawn.
`graph.margins` | Numeric vector of length 4. These margins values used (as if for par("mar")) for the main graph. The lower part of the plot uses the same left and right margins.
`base.plot.height` | The base height of the standard-sized plots. Plots that include the full transcript annotation will be expanded by the height of these additional rows. See the withTxPlot.height.multiplier parameter, below.
`base.plot.width` | The width of the plots.
`base.plot.units` | The units of measurement for the plot height and width. Default is px, or pixels.
`GENE.annotation.relative.height` | The height of the "gene track" displayed underneath the main graph, relative to the height of the main graph. By default it is 20 percent.
`TX.annotation.relative.height` | For all plots that draw the annotated-transcript set (when the `with.TX` parameter is `TRUE`), this sets the height of each transcript, as a fraction of the height of the main graph. By default it is 2.5 percent.
`CONNECTIONS.relative.height` | The height of the panel that connects the plotting area to the gene annotation area, relative to the height of the plotting area. This panel has the lines that connects the counting bin columns to their actual loci on the gene. By default it is 10 percent.
`SPLICE.annotation.relative.height` | The height of the area that shows the splice junction loci, relative to the size of the plotting area.
`TX.margins` | A numeric vector of length 2. The size of the blank space between the gene plot and the transcript list and then beneath the transcript list, relative to the size of each transcript line.
`autoscale.height.to.fit.TX.annotation` | Logical. Plots that include the full transcript annotation generally need to have a larger height in order to maintain readability. If `TRUE`) (the default), all plots that include transcripts will be expanded vertically to fit the additional transcripts. This maintains the same appearance and aspect ratio of the main graph area, but means that the height of the plot will differ between genes when TX are included. This parameter can be used to override that behavior if a specific figure size is desired. If `FALSE`, then the height of the entire output image will always be equal to `base.plot.height`.
`autoscale.width.to.fit.bins` | Integer value. JunctionSeq will automatically go to great lengths to autofit the data in a readable way. By default, any plots that have more than 35 plotting columns will be widened linearly to fit the excess columns. This parameter can be used to change that value, or turn it off entirely by setting this parameter to `NA`.
`condition.legend.text` | List or named vector of character strings. This optional parameter can be used to assign labels to each condition variable values. It should be a list or named vector with length equal to `factor(condition)`. Each element should be named with one of the values from `factor(condition)`, and should contain the label. They will be listed in this order in the figure legend.
`include.TX.names` | Logical value. If `TRUE`, then for the plots that include the annotated transcript, the transcript names will be listed. The labels will be drawn at half the size of `anno.cex.text`.
`plotting.device.params` | Additional parameters to be passed to the plotting device.
`number.plots` | Whether to number each gene in the image names, based on either the order they appear in the input gene.list, or in order of ascending p-values.
`name.files.with.geneID` | Whether to use the geneID (rather than gene name) for naming the files.
`draw.start.end.sites` | Logical value. If `TRUE`, then transcript start/end sites will be marked on the main gene annotation.
`openPlottingDeviceFunc` | An R function. This option can be used to use plotting devices other than the ones directly supported by JunctionSeq. This must be a function that must have 3 parameters: filename, heightMult, and widthMult. It should open the desired plotting device. For advanced users only.
`closePlottingDeviceFunc` | An R function. This must be used in conjunction with openPlottingDeviceFunc. For most devices, you can just use the function "dev.off". For advanced users only.
`writeHTMLresults` | If TRUE, write an index html file to present the results in a navigable way.
`html.cssFile` | Optional: specify a css file to use. Copies the entire contents of the supplied file into the page directory and links to it with relative links.
`html.cssLink` | Optional: specify an external css file to use. This can be an absolute or relative link.
`html.imgFileExtension` | The file extension of the image files. This is only needed if you are using a custom device. If you are using one of the default devices, it will autodetect the file extension.
`html.plot.height` | Numeric. The base height of the plot, for the plots without TX annotation. The default is 90.
`html.plot.height.units` | The units used for the `html.plot.height` parameter. The default is "vh", which sets the height relative to the available max height.
`html.compare.results.list` | Named list of character strings. (Advanced) Optional parameter that allows you to cross-link multiple analyses for easy navigation between analysis for specific genes of interest. In order to create such cross-linking, you will need to run `builtAllPlots` separately for each analysis. The `outfile.prefix` for each run must be a sub-directory of the same parent directory. The `html.compare.results.list` must be a named list of these subdirectories. `names(html.compare.results.list)` must be the title of each analysis as you want it to appear in the navigation links. Note: This parameter is incompatible with the `number.plots` option.
`minimalImageFilenames` | Logical. If `TRUE`, then the image files will not include the gene names, but instead will be numbered in order. The html files will still have the full length names. This option was added because many web host servers will refuse to host image files whose length exceeds 32 characters. By default this option will be `TRUE` iff writeHTMLresults is `TRUE`.
`verbose` | if TRUE, send debugging and progress messages to the console / stdout.
`debug.mode` | if TRUE, send even more debugging and progress messages to the console / stdout.
`INTERNAL.VARS` | NOT FOR GENERAL USE. Intended only for use by JunctionSeq itself, internally. This is used for passing pre-generated data (when generating many similar plots, for example), and for internally-generated parameters. DO NOT USE.
`...` | Additional options to pass to `buildAllPlotsForGene`, `plotJunctionSeqResultsForGene`, or graphical parameters passed to plotting functions.

### Value

This is a side-effecting function, and does not return a value.

### Examples

    data(exampleDataSet,package="JctSeqData");
    buildAllPlots(jscs);

    ## Not run:
    ########################################
    #Set up example data:
    decoder.file <- system.file(
                      "extdata/annoFiles/decoder.bySample.txt",
                      package="JctSeqData");
    decoder <- read.table(decoder.file,
                      header=TRUE,
                      stringsAsFactors=FALSE);
    gff.file <- system.file(
                "extdata/cts/withNovel.forJunctionSeq.gff.gz",
                package="JctSeqData");
    countFiles <- system.file(paste0("extdata/cts/",
         decoder$sample.ID,
         "/QC.spliceJunctionAndExonCounts.withNovel.forJunctionSeq.txt.gz"),
         package="JctSeqData");
    ########################################
    #Run example analysis:
    jscs <- runJunctionSeqAnalyses(sample.files = countFiles,
               sample.names = decoder$sample.ID,
               condition=factor(decoder$group.ID),
               flat.gff.file = gff.file,
               analysis.type = "junctionsAndExons"
    );
    ########################################

    #Generate all plots and the html index
    #   Save them as pngs to the current directory:
    buildAllPlots(jscs);

    ## End(Not run)

[Package JunctionSeq version 1.12.1 Index]