Comprehensive plotly wrapper function — roboplot • roboplotr

This function wraps numerous Plotly features into a single, well-parametrized interface. It also manages complex Plotly tasks, such as resizing and customization, simplifying the creation of advanced visualizations.

Usage

roboplot(
  d = NULL,
  color = NULL,
  title = NULL,
  subtitle = "",
  caption = NULL,
  legend = NULL,
  trace_color = NULL,
  highlight = NULL,
  zeroline = FALSE,
  rangeslider = FALSE,
  pattern = NULL,
  line_width = getOption("roboplot.linewidth"),
  hovertext = NULL,
  plot_type = "scatter",
  plot_mode = NULL,
  plot_axes = set_axes(),
  markers = set_markers(),
  height = getOption("roboplot.height"),
  error_bars = deprecated(),
  confidence_interval = NULL,
  facet_split = NULL,
  xaxis_ceiling = getOption("roboplot.xaxis.ceiling"),
  width = getOption("roboplot.width"),
  shadearea = NULL,
  secondary_yaxis = NULL,
  modebar = NULL,
  labels = NULL,
  artefacts = getOption("roboplot.artefacts")$auto,
  info_text = NULL,
  updatemenu = NULL,
  zoom = getOption("roboplot.zoom"),
  roboplot_options = NULL,
  legend_position = deprecated(),
  legend_maxwidth = deprecated(),
  ...
)

Arguments

d: Data frame. Data to be plotted with at least "time" (Date or POSIXt) and "value" (numeric) columns. Other columns can be specified using plot_axes via set_axes().
color: Symbol or string. Column from d to use for trace color. If NULL, title text is used for color and hover labels.
title, caption: Characters or functions. Labels for plot elements. Use set_title(include = F) to omit the title from the displayed plot but include it in modebar downloads, or alter the title's relative positioning. When using set_title(include = F), you probably want to include a title for roboplot()'s internal use. Use set_caption() to override any caption defaults set with set_roboplot_options().
subtitle: Character. Label for plot element.
legend: Character or function. Use set_legend(). If character, use "bottom", or NA for no legend. The legend is removed by default if color in d has only one observation.
trace_color: Character vector, named if length > 1. Trace colors. When named, must correspond to values in column in d referenced by color.
highlight: Numeric or list. Determines if a trace is included in the legend and assigned a color. Traces with max(value) < highlight are given a trace color matching the grid color and removed from the legend. Will not work with multiple patterns.
zeroline: Logical or numeric. TRUE to include zeroline, or numeric for exact placement.
rangeslider: Logical or character in %Y-%m-%d format. TRUE to include a rangeslider, or a date string for the start date.
pattern: Symbol or string. Column from d to use for scatter plot linetype or bar plot pattern. Not supported for pie charts. Use set_pattern() for detailed control.
line_width: Numeric vector, named if length > 1. Line width. When named, must correspond to values in column in d referenced by color.
hovertext: Function. Hovertext configuration parameters. Use set_hovertext().
plot_type: Character vector, named if length > 1. Determines the trace type for the plot or variables defined by color.
plot_mode: Character vector, named if length > 1. Controls plot specifics along with plot_type. Available modes vary by plot_type. For plot_type "scatter", the available modes are "line" "scatter", "smooth", "step" and "scatter+line". For plot_type of "bar", the available modes are "dodge" "stack", "horizontal", "horizontalfill" and "horizontalstack". For plot_type "pie", the available modes are "normal" and "rotated".
plot_axes: Function. Axis configuration. Use set_axes().
markers: Function. Marker appearance parameters. Use set_markers().
height, width: Numeric. Height and width of the plot. Default width is NA for responsive plots.
error_bars: Deprecated. Use confidence_interval instead.
confidence_interval: Function. Confidence layer configuration. Use set_confidence_interval().
facet_split: Currently unused. Variable from d for facet splits.
xaxis_ceiling: Character or date. Sets or rounds the upper bound of the x-axis for non-bar plots. Use "guess" for automatic ceiling based on the data. use "days", "weeks", "months", "quarters" or "years" for giving that much room, preceded with a number like "2 weeks", for a specific amount of time. Use "default" for the default set with set_roboplot_options().
shadearea: Date, numeric or function. Highlight an area on the plot. Use set_shadearea() for detailed control. Works with numeric or date x-axis and numeric y-axis.
secondary_yaxis: Character vector. Observations from color using a secondary y-axis. Use plot_axes with set_axes() for more control.
modebar: Function. Use set_modebar().
labels: Function. Use set_labels(). Control labels on plot traces. Use params title, plot_axes, caption etc. to control other labels.
artefacts: Logical or function. Use set_artefacts() for detailed control. TRUE for automated artefact creation based on set_roboplot_options().
info_text: Character. Adds an info button to the modebar with this text, along with plot title and caption.
updatemenu: Function. Use set_updatemenu() for detailed control.
zoom: Character of function. Use set_zoom(), or give "none", "scroll", or "drag".
roboplot_options: Character. A name of roboplot options set with set_roboplot_options() param name. See documentation of set_roboplot_options() for details.
legend_position: Deprecated. Character. Use legend instead.
legend_maxwidth: Deprecated. Numeric. Use legend instead.
...: Placeholder for other parameters.

Value

A list of classes "htmlwidget", "plotly", and "roboplotr.roboplot"

Examples

# The default use for `roboplot()` is for line charts. Providing
# a title is mandatory, subtitle and color is optional but  very likely
# necessary. Use `set_roboplot_options()` to control the various global options.


d <- energiantuonti |>
  dplyr::filter(Alue %in% c("USA","Norja","Iso-Britannia"))
d1 <- d |> dplyr::filter(Suunta == "Tuonti")
d1 |> roboplot(color = Alue,
               title = "Energian tuonti",
               subtitle = "Milj. \u20AC",
               caption = "Lähde: Tilastokeskus.")


# Legend will automatically be omitted if only a single observation exists
# for `color` is unless legend_position is given (currently only "bottom"
# works). Caption may be further specified with the helper function
# `set_caption()` (see documentation for more control).
d1 |>
  dplyr::filter(Alue == "Iso-Britannia") |>
  roboplot(Alue,"Energian tuonti Yhdistyneest\uE4 kuningaskunnasta","Milj. \u20AC",
           caption = set_caption(text = "Tilastokeskus")
  )


# You can also use `set_roboplot_options()` to preconstruct some caption texts.

set_roboplot_options(
  caption_template = "{prepend}.<br>Source: {caption}.<br>{append}.")
#> Warning: The `caption_template` argument of `set_roboplot_options()` is deprecated as of
#> roboplotr 2.4.0.
#> ℹ Please use the `caption` argument instead.

d1 |>
  roboplot(Alue, "Energy import","Million euros",
           caption = set_caption(
             prepend ="Canada",
             caption = "Statistics Finland",
             append = paste0("(Customs Finland, International trade ",
                             "statistics;<br>Radiation and Nuclear Safety ",
                             "Authority; Gasum LLC)")))


# Reset to defaults
set_roboplot_options(reset = TRUE)

# You can omit caption by setting it to NA.

d1 |> roboplot(Alue, "Energian tuonti","Milj. \u20AC",caption = NA)


# Legend can also be omitted by giving `legend_position` of NA. Height and
# width can also be specified, while for most uses width specification is
# unnecessary, as roboplotr is designed for plots with responsive widths.
d1 |> roboplot(Alue,"Energian tuonti","Milj. \u20AC","Tilastokeskus",
               legend = set_legend(position = NA),
               height = 600,
               width = 400
)


# For a long list of legend items, use `updatemenu`. See the documentation
# of `set_updatemenu()` function for more control.
energiantuonti |> roboplot(color = Suunta, updatemenu = Alue)



# `pattern` can be used in addition to color and you can control the ordering of
# the traces by transforming your variables to factors. You can also let
# `roboplot()` guess how much space is given to yaxis end in line plots, or give a
# string such as "weeks" or "days" with `xaxis_ceiling`. Message about missing
# frequency can be silenced  by setting the information as an attribute.

d2 <- d |> dplyr::mutate(Alue = forcats::fct_reorder(Alue, value))
attr(d2, "frequency") <- "Quarterly"
d2 |> roboplot(Alue,"Energian tuonti ja vienti","Milj. \u20AC","Tilastokeskus",
               pattern = Suunta,
               xaxis_ceiling = "guess")


# Bar plots use `pattern` too.
d2 |> roboplot(Alue,"Energian tuonti ja vienti","Milj. \u20AC","Tilastokeskus",
               pattern = Suunta,
               plot_type = "bar")

# Use `set_pattern()` if you want more options. See documentation for a more
# detailed explanation.
d2 |> roboplot(Alue,"Energian tuonti ja vienti","Milj. \u20AC","Tilastokeskus",
                              pattern = set_pattern(pattern = Suunta, sep = " - "),
                              xaxis_ceiling = "guess")

# Scatter plots and bar plot may be combined, and colors determined by
# trace by giving named character vectors as the appropriate arguments.
# Barmode or scatter type is controlled by `plot_mode`.
d1 |> roboplot(Alue,"Energian tuonti ja vienti","Milj. \u20AC","Tilastokeskus",
             trace_color =  c("USA" = "red","Norja" = "blue", .other = "black"),
             plot_type = c("Norja" = "scatter","USA" = "bar",".other" = "scatter"),
             plot_mode = c("Iso-Britannia" = "scatter",
                           "Norja" = "scatter+line", ".bar" = "dodge",
                           ".scatter" = "line"
             ))


# If you omit ".other" from the trace colors,` roboplot()` will give the rest of
# of the traces colors from the default colors set in `set_roboplot_options()`
d1 |> roboplot(Alue,"Energian tuonti ja vienti","Milj. \u20AC","Tilastokeskus",
               trace_color = c("USA" = "pink"))


# But if you need more control, you're better off just excplicity specifying
# the colors.
d1 |> roboplot(Alue,"Energian tuonti ja vienti","Milj. \u20AC","Tilastokeskus",
  trace_color =
    stats::setNames(c("#0052A5", "darkred", "#D52B1E"),
                    unique(d1$Alue))
)


# With single "time" observation x-axis tickmarks lose tick labels. There are
# several places where this information fits nicely.
d3 <- d2 |> dplyr::filter(time == max(time))

d3 |>
  roboplot(
    Alue,
    stringr::str_glue(
      "Energian tuonti ja vienti vuonna {lubridate::year(max(d3$time))}"
    ),
    stringr::str_glue("Milj. \u20AC ({lubridate::year(max(d3$time))})"),
    pattern = Suunta,
    plot_type = "bar",
    caption =
      set_caption(
        text = stringr::str_glue(
          "Tilastokeskus.<br>Tieto vuodelta {lubridate::year(max(d3$time))}"
        )
      )
 )


# Plot axis can be controlled with `set_axes()` (see documentation).
d2 |>
  dplyr::filter(Suunta == "Tuonti") |>
  roboplot(Alue, "Energian tuonti","Milj. \u20AC","Tilastokeskus",
           plot_axes = set_axes(
             ytitle = "Arvo",
             xformat = "Vuonna %Y",
             ylim = c(-100,100))
  )


# Bar plot can be horizontal with plot axis control and `plot_mode` set to
# horizontal but then is better off with only a single "time" observation. Long
# legend items and axis labels can be cut off with `legend_maxwidth` in `legend`,
# while still showing the proper labels on hover. Control the order of the axes
# by explicitly setting them as factors.
d3 |>
  dplyr::mutate(Suunta = paste0(Suunta, " m\uE4\uE4r\uE4maittain")) |>
  dplyr::mutate(Alue = forcats::fct_reorder(Alue, value),
                Suunta = forcats::fct_reorder(Suunta, value) |>
                  forcats::fct_rev()
  ) |>
  roboplot(Suunta,
           stringr::str_glue("Energian tuonti {lubridate::year(max(d$time))}"),
           "Milj. \u20AC","Tilastokeskus",
           plot_type = "bar",
           legend = set_legend(maxwidth = 12),
           plot_mode = "horizontal",
           plot_axes = set_axes(
             y = "Alue",
             x = "value"
             )
  )


# If you want the bars to fill the available space in a horizontal bar chart,
# use `plot_mode` of "horizontalfill" instead of "horizontal".
d3 |>
  roboplot(Suunta,
           stringr::str_glue("Energian tuonti {lubridate::year(max(d$time))}"),
           "Milj. \u20AC","Tilastokeskus",
           plot_type = "bar",
           plot_mode = "horizontalfill",
           plot_axes = set_axes(
             y = "Alue",
             x = "value"
             )
  )



# Or stack the bars horizontally by using "horizontalstack". You might want to
# move title and caption to left edge of the container instead of the plot area
# with horizontal bars.
d3 |>
  roboplot(
    Suunta,
    set_title(
      stringr::str_glue("Energian tuonti {lubridate::year(max(d$time))}"),
      xref = "container"
    ),
    "Milj. \u20AC",
    set_caption("Tilastokeskus", xref = "container"),
    plot_type = "bar",
    plot_mode = "horizontalstack",
    plot_axes = set_axes(
      y = "Alue",
      x = "value"
    )
  )


# You can use `secondary_yaxis` to define which observations from 'color' use
# go to a secondary yaxis on the right.
d2 |>
  dplyr::filter(Suunta == "Tuonti", Alue %in% c("Iso-Britannia", "USA", "Norja")) |>
  roboplot(Alue,
           "Energian tuonti",
           "Milj. \u20AC",
           "Tilastokeskus",
           secondary_yaxis = "Iso-Britannia",
           zeroline = 1000)


# Furthermore, you can use `set_axes()` in `plot_axes` for further control, like
# titles. Documentation for `set_axes()` has more detailed examples.
d2 |>
  dplyr::filter(Suunta == "Tuonti", Alue %in% c("Iso-Britannia", "USA", "Norja")) |>
  roboplot(Alue,
           "Energian tuonti",
           "Milj. \u20AC",
           "Tilastokeskus",
           plot_axes = set_axes(y2 = "Iso-Britannia"))


# Pie plots are possible too, but `pattern` is currently ignored by `plotly`
# and thus by `roboplot()`.
d3 |> roboplot(
  Alue,
  "Energian tuonti ja vienti",
  "Milj. \u20AC",
  "Tilastokeskus",
  pattern = Suunta,
  plot_type = "pie"
)


# Aside from `pattern`, you might want to change `markers` used on "scatter"
# plots by using `set_markers()`. You can also include `confidence_interval` on any
# numeric axis by specifying them with `set_confidence_interval()`. See both functions
# for more details.
d2 |>
dplyr::filter(Alue == "Norja") |>
  dplyr::group_by(Suunta) |>
  dplyr::mutate(confidence_interval = sd(value)) |>
  dplyr::ungroup() |>
  roboplot(Suunta,
           plot_type = "scatter",
           plot_mode = "scatter",
           markers = set_markers("star", 12),
           confidence_interval = set_confidence_interval(type = "bars")
  )

# Pie plot can be centered to the first factor level of argument `color` with
# with `plot_mode` "rotated".
d3 |> roboplot(Alue,"Energian tuonti ja vienti","Milj. \u20AC",
                    "Tilastokeskus",
                    plot_type = "pie",
                    plot_mode = "rotated")


# You can give a `highlight` value if you don't have a `pattern`. Any trace with
# get assigned a background grid color and no legend entry. Useful mostly with
# very large amounts of traces.

d2 |>
  dplyr::filter(Suunta == "Tuonti") |>
  roboplot(Alue, "Energian tuonti","Milj. \u20AC","Tilastokeskus",
           plot_type = "scatter",
           highlight = 160)


# This works best with line plots, but can be included in other plots, too -
# with varying results, these are work in progress. `highlight` can also be a
# list with "value" and ".fun" used to determine which traces are highlighted.
d2 |> dplyr::filter(Suunta == "Tuonti") |>
  roboplot(Alue, "Energian tuonti","Milj. \u20AC","Tilastokeskus",
           plot_type = "bar",
           highlight = list(value = 22, .fun = mean))


# `rangeslider` can be added as logical, or as character in date format of
# %Y-%m-%d, in which case the given date will control where the `rangeslider`
# start is initially set. `zeroline` can be controlled in a similar way.
d2 |> dplyr::filter(Suunta == "Tuonti") |>
  roboplot(Alue, "Energian tuonti","Milj. \u20AC","Tilastokeskus",
           rangeslider = "2014-01-01",
           zeroline = 128)


# `shadearea` can be used to draw attention to specific area of the plot.
d2 |> dplyr::filter(Suunta == "Tuonti") |>
  roboplot(Alue, "Energian tuonti","Milj. \u20AC","Tilastokeskus",
           shadearea = "2019-01-01")

# Use` set_shadearea()` for more fine-tuned control.
d2 |> dplyr::filter(Suunta == "Tuonti") |>
  roboplot(Alue, "Energian tuonti","Milj. \u20AC","Tilastokeskus",
           shadearea = set_shadearea(
             xmin = "2010-06-10",
             xmax = "2016-01-01",
             color = "green",
             opacity = 0.5,
             border = "gray",
             layer = "below"
           ))

# `roboplotr()` can't currently validate `xmin` and `xmax` for `shadearea`,
# and wrong input will probably just fail to produce the area.
d2 |> dplyr::filter(Suunta == "Tuonti") |>
  roboplot(Alue, "Energian tuonti","Milj. \u20AC","Tilastokeskus",
           shadearea = set_shadearea(
             xmin = "182625",
           ))

# Finally, you may export from the plots you create either by using `create_widget()`
# or simply using the parameter `artefacts`. The global defaults of artefact
# creation are set with `set_roboplot_options()`, and for this example the
# default filepath will be changed to a temporary directory. See `set_artefacts()`
# and `create_widget()` documentation.
if (FALSE) { # \dontrun{
set_roboplot_options(
  artefacts = set_artefacts(filepath = tempdir())
)

d2 |>
  dplyr::filter(Suunta == "Tuonti") |>
  roboplot(Alue,"Energian tuonti","Milj. \u20AC","Tilastokeskus",
  artefacts = TRUE)

file.exists(paste0(tempdir(),"/energian_tuonti.html"))

# Reset to defaults

set_roboplot_options(reset = TRUE)
} # }