Skip to contents

How to use plotly in Pmetrics

Source: vignettes/articles/plotly.Rmd
plotly.Rmd

Overview

As of version 2, Pmetrics uses the plotly package for most plots. Plots made with plotly are interactive, so that moving your cursor over them results in pop up information being displayed. A nice feature of plotly is the ggplotly command which takes any ggplot plot object and turns it into a plotly plot. This route doesn’t provide complete control of plotly objects, so Pmetrics uses plotly from the ground up.

However, the documentation for plotly is a bit complex and often lacking in sufficient examples. This vignette attempts to orient you to the specific aspects of plotly most relevant to Pmetrics.

General

Plotly is based on a foundation of lists. Most plot elements are lists whose arguments control characteristics of the elements. Pmetrics chiefly uses only a handful of the elements.

Full descriptions of plotly elements and options to control them can be accessed by typing plotly::schema() into the R console. If you have already loaded plotly you can just type schema(). You will see something like the menu below in the Viewer tab in Rstudio.

Top level plotly schema
Top level plotly schema

In plotly, the traces items control appearance of the data. The layout items control everything to do with the appearance of the axes and the legend.

Traces

Pmetrics almost exclusively uses scatter traces, and those elements can be referenced by expanding traces ▶ scatter ▶ attributes.

There are many such attributes, but the most commonly used and accessible to the user are line and marker.

Line attributes

All plotly plots in Pmetrics have a line argument which maps to the line attribute of a plotly scatter trace. When Pmetrics detects a boolean argument, e.g. TRUE or FALSE it either plots the default line or suppresses the line altogether. A good example of this is the line argument to plot.PM_op to generate an observed vs. predicted plot. In this function, line is a list of named lines that can be plotted. If NPex is a PM_result object loaded with PM_load() then the default is NPex$plot$op(line = list(lm = F, loess = T, ref = T)).This means that a linear model (regression) will not be plotted, a loess regression will be plotted, and a reference line with slope = 1 and intercept = 0 will also be plotted. If we are happy with all the defaults, we simply need to call the plot method for the PM_op object field in NPex.

NPex$op$plot()

Below is a simple example of how to change the default lines plotted, but retain the default formatting. Now a linear regression (using the R lm function) is plotted with a reference line, but not a loess regression.

NPex$op$plot(line = list(lm = T, loess = F, ref = T))

The default formats for lines may differ from function to function and are indicated in the help files. However all lines may be formatted using three arguments as a list.

  • color Specify the color of the line as a character with either the
    • name: a good reference in R is to use the colors() function, e.g. “dodgerblue”
    • hexadecimal code: this can be searched on the web, and is specified as a character with leading “#” followed by 6 hexidecimal digits, two each for Red, Green, Blue, e.g. “#C0C0C0”. Adding an extra two digits specifies transparency, with 00 fully transparent and FF fully opaque, e.g. #C0C0C066”.
    • a plotly function toRGB which takes a color name and alpha (transparency) value on a scale of 0 - 1, e.g., toRGB("red", 0.5).
  • width Units are pixels.
  • dash Sets the dash style of lines. Set to a dash type string (solid,dot, dash, longdash, dashdot, or longdashdot) or a dash length list in px (eg 5px,10px,2px,2px)
NPex$op$plot(line = list(loess = list(color = "orange", dash = "dashdot", width = 2)))

Note the default is lm = F and ref = T, so we don’t need to specify them if that’s what we want.

Marker attributes

All plotly plots in Pmetrics have a marker argument which maps to the marker attribute of a plotly scatter trace. When Pmetrics detects a boolean argument, e.g. TRUE or FALSE it either plots the default marker or suppresses the marker altogether. A good example of this is also the marker argument to plot.PM_op to generate an observed vs. predicted plot. In this function, marker controls the plotting symbol. If NPex is a PM_result object loaded with PM_load() then the default is NPex$plot$op(marker = T).This means that the symbols will be plotted with default formatting. If we are happy with all the defaults, we simply need to call the plot method for the PM_op object field in NPex.

NPex$op$plot()

The default formats for markers may differ from function to function and are indicated in the help files. However all markers may be formatted using most commonly four arguments as a list.

  • color Specify the color of the marker fill as a character with either the
    • name: a good reference in R is to use the colors() function, e.g. “dodgerblue”
    • hexadecimal code: this can be searched on the web, and is specified as a character with leading “#” followed by 6 hexidecimal digits, two each for Red, Green, Blue, e.g. “#C0C0C0”. Adding an extra two digits specifies transparency, with 00 fully transparent and FF fully opaque, e.g. #C0C0C066”.
    • a plotly function toRGB which takes a color name and alpha (transparency) value on a scale of 0 - 1, e.g., toRGB("red", 0.5).
  • size Units are points.
  • symbol Either a character name or the numeric value associated with the character. See schema() traces ▶ scatter ▶ attributes ▶ marker ▶ symbol ▶ values for all the possibilities, e.g. “circle-open” is equivalent to 100, “square” is equivalent to 1, and “diamond-open-dot” is equivalent to 302.
  • opacity On a scale of 0 (transparent) to 1 (opaque).

Any other marker attribute is possible, including line, which itself is a list to specify attributes of the outline for a marker.

NPex$op$plot(marker = list(color = "slategray", size = 12, 
                           opacity = 0.5, line = list(color = "navy")))

Layout

Layout layout ▶ layoutAttributes ▶ displays all the options for the layout. Pmetrics plot functions currently only provide access to the following layout options: * legend * xaxis * yaxis * title Details of how each is accessed are below.

Legend

In all relevant Pmetrics plotly plots, the argument for legend can take one of three forms: TRUE, FALSE, or a list. The first and second options choose to include the default legend or to suppress the legend, respectively.

Specifying legend as a list allows for detailed formatting of the legend using any of the attributes documented by typing schema() into the R console, and expanding layout ▶ layoutAttributes ▶ legend. These can be included as elements in the legend list.

Here’s a basic legend.

NPex$data$plot(legend = T)

…and a more complex one.

NPex$data$plot(line = list(join = F, 
                           pred = list(NPex$post, color = "navy")), 
               legend = list(
                 x = 0.75,
                 y = 0.85,
                 borderwidth = 1,
                 bgcolor = "antiquewhite"
               ),
               xlim = c(119, 146))