Skip to contents

Interactive 3D Surface and 2D Contour Plots for the Series of EPR Spectra

Source: R/plot_EPR_Specs3D_interact.R
plot_EPR_Specs3D_interact.Rd

Interactive plotting of EPR spectra or their integrals based on plotly package. The aim of this function is to nicely visualize the series of EPR spectra (or their corresponding integrals), while checking out the EPR intensities upon e.g. kinetic (time series), variable temperature or simultaneous spectroelectrochemical experiments (potential series). For such purpose, the data frame input (see the data.spectra.series argument) is transformed into the matrix (with columns/variables corresponding to intensities at defined times, potentials, temperatures...etc.). In the next step the plot_ly function generates either 3D surface or 2D contour plot objects which are finally customized by the layout as well as by the colorbar. Similarly, as for the plot_EPR_Specs2D_interact final plots can be stored or attached to a certain document format, using the plot_EPR_present_interact function (or directly within Rstudio), as .png or .html.

Usage

plot_EPR_Specs3D_interact(
  data.spectra.series,
  x = "B_mT",
  Intensity = "dIepr_over_dB",
  var2nd.series = "time_s",
  plot.type = "surface",
  scheme.color = "Viridis",
  contour.labels = FALSE,
  xlim = NULL,
  xlab = "<i>B</i> (mT)",
  ylab = "<i>Time</i> (s)",
  zlab = "d <i>I</i><sub>EPR</sub> / d <i>B</i> (p.d.u.)",
  axis.title.size = 12,
  axis.text.size = 11,
  bg.x.color = "rgb(220, 220,220)",
  grid.x.color = "rgb(255, 255, 255)",
  bg.y.color = "rgb(220, 220,220)",
  grid.y.color = "rgb(255, 255, 255)",
  bg.z.color = "rgb(220, 220,220)",
  grid.z.color = "rgb(255, 255, 255)",
  output.matrix.df = FALSE
)

Arguments

data.spectra.series

Spectrum data frame/table, object containing magnetic flux density, \(g\)-value or radio-frequency columns as x variable. They can be labeled as Field, B_mT in mT (or B_G in gauss), see also x parameter/argument. The y/Intensity variable can be labeled as dIepr_over_dB, in case of derivative intensity, or if integrated or simulated spectral intensities are present, they can be labeled accordingly. See also Intensity parameter/argument. A second independent variable var2nd.series column (e.g. var2nd.series = "time_s") must be available. In such case, the entire data.spectra must be present in the form of tidy/long table format (see also parameter/argument var2nd.series).

x

Character string, pointing to \(x\)-axis/column quantity in the original data.spectrum like magnetic flux density \(B\), \(Field\), \(g\)-Value or \(RF\) (radio frequency), default: x = "B_mT".

Intensity

Character string, corresponding to the intensity column header in the original data.spectrum if other than dIepr_over_dB name/label is used (e.g. for integrated or simulated spectra), default: Intesity = "dIepr_over_dB".

var2nd.series

Character string, referred to name of the second independent variable/quantity column in the original data.spectra.series (such as time, Temperature, Electrochemical Potential, Microwave Power...etc) altered upon individual experiments. Data must be available in long table (or tidy) format (see also data.spectra.series argument). Default: var2nd.series = NULL. Otherwise, usually, var2nd.series = "time_s".

plot.type

Character string, inherited from plot_ly, specifying the trace. Only two character strings are available: plot.type = "surface" (default, for 3D surface plots) or plot.type = "contour" (for 2D contour plots).

scheme.color

Character string, corresponding to color scale. See also surface-colorscale. Color scale must be an array containing arrays mapping a normalized value to an RGB, RGBa, HEX, HSL, HSV, or named color string. At minimum, a mapping for the lowest (0) and the highest (1) values are required. For example, [[0, 'rgb(0,0,255)'], [1, 'rgb(255,0,0)']] or as a list: list(c(0, 1), c("tan", "blue")) or list(c(0, "tan"), c(1, "blue")). To control the bounds of the color scale in the corresponding space, use cmin and cmax. Alternatively, color scale may be a palette name string of the following list: "Blackbody","Bluered","Blues", "Cividis","Earth","Electric","Greens","Greys","Hot", "Jet","Picnic","Portland","Rainbow","RdBu","Reds", "Viridis","YlGnBu","YlOrRd". Default: scheme.color = "Viridis".

contour.labels

Logical, whether contours of intensity "hills" and "valleys" are projected onto the \(x,y\)-plane. Default: contour.labels = FALSE.

xlim

Numeric vector, pointing to lower and upper limit of the \(x\)-axis range. Assignment of xlim = NULL (default) actually corresponds to the entire original range (see also the data.spectra.series argument).

xlab

Character string \(\equiv\) title of the \(x\)-axis. Either simple, like xlab = "B (mT)" can be applied or if additional formatting is required, the html markup language is used, such as xlab = "<i>B</i> (mT)" (default). If a \(\LaTeX\) typesetting is required for the title, please refer to e.g. LaTeX Plotly Tepesetting.

ylab

Character string \(\equiv\) title of the \(y\)-axis (see also xlab), default: ylab = "<i>Time</i> (s)".

zlab

Character string \(\equiv\) title of the \(z\)-axis (see also xlab), default: zlab = "d <i>I</i><sub>EPR</sub> / d <i>B</i> (p.d.u.)".

axis.title.size

Numeric, text size (in px) for the axis title, default: axis.title.size = 15.

axis.text.size

Numeric, text size (in px) for the axis unit values/descriptions, default: axis.text.size = 14.

bg.x.color

Character string, setting the background color of the \(x\)-axis wall. Default: bg.x.color = "rgb(220, 220,220)" (light gray). For additional color definitions, consult CSS Color Module Homepage.

grid.x.color

Character string, pointing to color of \(x\)-axis grid lines, default: grid.x.color = "rgb(255, 255, 255)" (white). For additional color definitions, consult CSS Color Module Homepage.

bg.y.color

Character string, setting the background color of the \(y\)-axis wall (see also bg.x.color), default: bg.y.color = "rgb(220, 220,220)" (light gray).

grid.y.color

Character string, pointing to color of \(y\)-axis grid lines, default: grid.y.color = "rgb(255, 255, 255)" (white).

bg.z.color

Character string, setting the background color of the \(z\)-axis wall (see also bg.x.color), default: bg.z.color = "rgb(220, 220,220)" (light gray).

grid.z.color

Character string, pointing to color of \(z\)-axis grid lines, default: grid.z.color = "rgb(255, 255, 255)" (white).

output.matrix.df

Logical, if output.matrix.df = TRUE a wide data frame format, with all spectral/integral intensities and within the (time, Temperature,...etc.) series, represented by individual columns/variables, is returned. Default: output.matrix.df = FALSE.

Value

Depending on output.matrix.df, function returns either interactive plot object (output.matrix.df = FALSE) or if otput.matrix.df = TRUE, it results in the list consisting of

plot

Interactive object plot (see below).

df

Associated data fame object in wide table format for subsequent processing by other graphing software programs. It can be also quite easily transformed into the long/tidy format by the pivot_longer.

In both cases the interactive plot can be visualized either in 3D surface mode (plot.type = "surface") or in 2D contour mode with the intensity scale mapped onto the color bar (plot.type = "contour").

See also

Other Visualizations and Graphics: draw_molecule_by_rcdk(), plot_EPR_Specs(), plot_EPR_Specs2D_interact(), plot_EPR_Specs_integ(), plot_EPR_present_interact(), plot_labels_xyz(), plot_layout2D_interact(), plot_theme_In_ticks(), plot_theme_NoY_ticks(), plot_theme_Out_ticks(), present_EPR_Sim_Spec()

Examples

## loading the built-in package example to demonstrate
## visualizatioin of time series EPR spectra:
triarylamine.decay.series.dsc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.DSC")
triarylamine.decay.series.asc.path <-
load_data_example(file =
        "Triarylamine_radCat_decay_series.zip")
unzip(triarylamine.decay.series.asc.path,
      exdir = tempdir()
      )
## loading the kinetics:
triarylamine.decay.series.data <-
  readEPR_Exp_Specs_kin(name.root =
                          "Triarylamine_radCat_decay_series",
                        dir_ASC = tempdir(),
                        dir_dsc_par =
                          system.file("extdata",
                                      package = "eprscope")
                        )
#
## plot basics `surface` plot (with default arguments)
## and the `Jet` color scheme including
## Intensity contour labels
plot_EPR_Specs3D_interact(triarylamine.decay.series.data$df,
  contour.labels = TRUE,
  scheme.color = "Jet")


#
## plot basic `contour` plot (with default arguments)
plot_EPR_Specs3D_interact(triarylamine.decay.series.data$df,
  plot.type = "contour")


#
if (FALSE) { # \dontrun{
## 3D surface plotting EPR spectra series (in the region
## of <334,345> mT) from variable temperature
## (VT) experiments
plot_EPR_Specs3D_interact(data.spectra.series,
  var2nd.series = "Temperature_K",
  xlim = c(334,345),
  contour.labels = T,
  ylab = "<i>Temperature</i> (K)")
} # }