Extensions to 'ggplot2' for Radiation Spectra

Additional annotations, stats, geoms and scales for plotting "light" spectra with 'ggplot2', together with specializations of ggplot() and autoplot() methods for spectral data and waveband definitions stored in objects of classes defined in package 'photobiology'. Part of the 'r4photobiology' suite, Aphalo P. J. (2015) .


ggspectra

cran version cran checks

The goal of 'ggspectra' is to make it easy to plot radiation spectra and similar data, such and transmittance, absorbance and reflectance spectra, producing fully annotated publication- and presentation-ready plots. It is an extension to packages 'ggplot2' and 'photobiology', and part of the 'r4phototbiology' suite.

Package 'ggspectra' provides stats, geoms, scales and functions to be used for plotting radiation-related spectra and annotating the plots with quantities derived from spectral data. All summary quantities implemented in 'photobiology' can be used for annotations including biologically effective irradiances and exposures.

Please, see the web site r4photobiology for details on other packages available as part of the suite, and on how to install them.

Example

Plotting spectra with an specialization of the autoplot() method provides the most automatic approach.

library(ggspectra)
autoplot(sun.spct)

Some degree of flexibility can be obtained by passing arguments.

autoplot(sun.spct, annotations = c("+", "title:where:when"), unit.out = "photon")

Maximum flexibilty is achieved when building a plot layer by layer using the grammar of graphics approach, as implemented in 'ggplot2', but taking advantage of the specialized ggplot() methods, geometries, statistics and scales specialized for the plotting of spectra, defined in this package .

photon_as_default()
ggplot(sun.spct) +
  geom_spct() +
  scale_y_s.q.irrad_continuous() +
  scale_x_wl_continuous(sec.axis = sec_axis_w_number()) +
  theme_bw()

Installation

Installation of the most recent stable version from CRAN:

install.packages("ggspectra")

Installation of the current unstable version from Bitbucket:

devtools::install_bitbucket("aphalo/ggspectra")

Documentation

HTML documentation is available at (http://docs.r4photobiology.info/ggspectra/), including a User Guide.

News on updates to the different packages of the 'r4photobiology' suite are regularly posted at (https://www.r4photobiology.info/).

Two articles introduce the basic ideas behind the design of the suite and its use: Aphalo P. J. (2015) (https://doi.org/10.19232/uv4pb.2015.1.14) and Aphalo P. J. (2016) (https://doi.org/10.19232/uv4pb.2016.1.15).

A book is under preparation, and the draft is currently available at (https://leanpub.com/r4photobiology/). The book conatins many examples of plots created with 'ggspectra'.

A handbook written before the suite was developed contains useful information on the quantification and manipulation of ultraviolet and visible radiation: Aphalo, P. J., Albert, A., Björn, L. O., McLeod, A. R., Robson, T. M., & Rosenqvist, E. (Eds.) (2012) Beyond the Visible: A handbook of best practice in plant UV photobiology (1st ed., p. xxx + 174). Helsinki: University of Helsinki, Department of Biosciences, Division of Plant Biology. ISBN 978-952-10-8363-1 (PDF), 978-952-10-8362-4 (paperback). PDF file available from (http://hdl.handle.net/10138/37558).

Contributing

Pull requests, bug reports, and feature requests are welcome at (https://bitbucket.org/aphalo/ggspectra).

Citation

If you use this package to produce scientific or commercial publications, please cite according to:

citation("ggspectra")
#> 
#> To cite package 'ggspectra' in publications, please use:
#> 
#>   Aphalo, Pedro J. (2015) The r4photobiology suite. UV4Plants
#>   Bulletin, 2015:1, 21-29. DOI:10.19232/uv4pb.2015.1.14
#> 
#> A BibTeX entry for LaTeX users is
#> 
#>   @Article{,
#>     author = {Pedro J. Aphalo},
#>     title = {The r4photobiology suite},
#>     journal = {UV4Plants Bulletin},
#>     volume = {2015},
#>     number = {1},
#>     pages = {21-29},
#>     year = {2015},
#>     doi = {10.19232/uv4pb.2015.1.14},
#>   }

License

© 2015-2018 Pedro J. Aphalo ([email protected]). Released under the GPL, version 2 or greater. This software carries no warranty of any kind.

News

ggspectra 0.3.2 (2019-02-19)

  • Move 'ggplot2' from Imports: to Depends: as the objects returned belong to classes defined in this package.
  • Move 'photobiology' from Imports: to Depends: as the objects accepted as input belong to classes defined in this package and is natural for users to want to use specialized methods to operate on them.
  • Define autoplot() methods as replacements for plot() methods, which are now deprecated. All documentation now uses autoplot().
  • As 'ggplot2' exports a generic for autoplot() and the expected returned value is a ggplot which matches the returned value of the methods defined here, we have renamed them to autoplot(). For backwards compatibility plot() methods remain available, but their use in new code is deprecated.

ggspectra 0.3.1 (2018-10-28)

  • Fix major bug in plot() methods for source_spct and response_spct classes, that triggered errors in all cases when time.unit was not "second".
  • Add scale_y_s.e.irrad_log10() and scale_y_s.q.irrad_log10().
  • Test with 'ggplot2' version 3.1.0.

ggspectra 0.3.0 (2018-10-06)

** Change the names of some the values calculated by the stats defined in 'ggspectra' to avoid confusion with the names of 'ggplot2' aesthetics. ** This is a code breaking change!

Revise to track changes in 'photobiology' version 0.9.24 and 'ggplot2' 3.0.0, which are now required.

  • stat_label_peaks() and stat_label_valleys() now have a new parameter, label.fill which can be used to set the content of ..x.label.. and ..y.label.. for labels not labelled as peaks or valleys. The earlier use of "" is retained as default.
  • Add stat_find_wls() and stat_find_qtys(), two new statistics useful for highlighting and labelling features in spectra.
  • Add parameter ylim to all plot() methods.
  • Revise plot() methods to support objects with multiple spectra in long form.
  • Revise plot() methods to NOT display by default calculated summaries in annotations when a plot contains multiple spectra.
  • Revise plot() methods to retrieve and validate the name of the factor used to identify multiple spectra, using as default the value stored in the attribute "idfactor" implemented in 'photobiology' 0.9.21 and later.
  • Add autoplot() as an alias of plot() for spectra and collections of spectra.

ggspectra 0.2.4 (2018-05-05)

Revise to track changes in 'photobiology' 0.9.20 to avoid spurious messages.

  • Add ggplot() method specialization for collections of spectra.
  • Add plot() method specializations for collections of spectra.

ggspectra 0.2.3 (2017-12-18)

Track changes in package 'photobiology' 0.9.18.

  • Add plot.calibration_spct()
  • Add ggplot.calibration_spct()

Improve handling of plot titles.

  • Add utility function ggtitle_spct()
  • Update all plot() methods to allow flexible contents in automatic titles including setting of the time zone and format used for displaying time.

ggspectra 0.2.2

Track changes in package 'photobiology' 0.9.16 and 0.9.17. This among other improvements makes it easy to plot spectral absorptance. Expand y scale to expected range in all cases, but do not force these limits in any case when data exceeds them, except for absorbance for which the y scale is not expanded past 6 a.u. Add new annotation "boundaries" to highlight with horizontal line(s) the expected range of the plotted quantity, highlighting the limit(s) exceeded if data fall outside the expected/range. Add previously missing ggplot() method for class object_spct. Revise vignettes.

ggspectra 0.2.1

Track changes in package 'photobiology' 0.9.14. Add continuous scales with defaults suitable for spectral data, with support for automatic axis labels both as R-expressions and as LaTeX mark-up. Add utility functions for SI scale prefixes. Add utility functions for x-axis-labels and secondary x-axis. Add utility functions for y-axis-labels. Update User Guide (add examples of graphical comparison of multiple lists of wavebands).

ggspectra 0.2.0

Improve handling of annotations parameter in plot() methods. Add functions ggcolorchart() and black_or_white(). Add statistics stat_wb_box() and stat_wb_column() with "rect" as default geom and stat_wb_hbar() with "errorbarh" as default geom. Change default geom from "rect" to "text" in all the summary stats for spectra. Update stats with "text" as default geom to use an additional variable BW.color computed by black_or_white() as default mapping for color. As default geoms and color mapping have changed, this update can break existing code. Changes to plot() methods are backwards compatible but default color of some text labels is changed from "white" to "black" to improve readability, and fewer peaks and valleys are highlighted by default. In addition more ticks marks are used on the wavelength axis. Fix minor bugs in handling of color mapping. Update documentation.

ggspectra 0.1.12 (ver 0.1.11 was not submitted to CRAN)

Import ggplot2 in whole as only the most basic use of plot() methods would not require user access to 'ggplot2'. Add stat_label_peaks() and stat_label_valleys() which are designed to fully take advantage of 'geom_text_repel()' and 'geom_label_repel()' as revised in package 'ggrepel' (>= 0.6.3). Change behaviour of plot() methods so that "illegal" values such as negative spectral irradiances or transmittances are plotted by default. Fix several minor bugs affecting plot() methods with certain non-default sets of annotations. Improve documentation and vignettes.

ggspectra 0.1.10

Add code to maintain same stacking order under ggplot2 1.1.0, 2.0.0, 2.1.0, and 2.1.9000 in plot.object_spct().

ggspectra 0.1.9

Add support for na.rm to all plot() methods setting default to TRUE, and avoid triggering spurious warnings from internal code. Make default for parameter 'label.qty' in plot methods dependent on whether data are expressed in absolute units or have been rescaled or normalized. Move from the 'User Guide' the sections on plot() methods creating a new vignette titled 'Plot Methods'.

ggspectra 0.1.8

Add support for plot.qty = "absorptance" to plot.filter_spct() Add support for plot.qty to plot.object_spct() with possible values: "all" or NULL (previous behaviour, and current default), "transmittance", "absorbance", "absorptance", and "reflectance". The new options plot only one quantity at a time as a line instead of the default area plot.

ggspectra 0.1.7

Add stat_wb_label(), stat_wb_e_irrad(), stat_wb_q_irrad(), stat_wb_e_sirrad(), and stat_wb_q_irrad(). Revise plot.raw_spct() to handle multiple "counts" columns. Revise plot.cps_spct() to handle multiple "cps" columns. Add text.size parameter to all plot() methods. Can be used to control the size of the font used for text decorations related to wavebands, peaks and valleys. Increase slightly the default font size for plot decorations, and decrease the number of peaks and valleys labelled by the plot() methods. Fix existing bug revealed by dplyr update. Fix bug in decoration() affecting plot.objects_spct(). Fix other minor bugs.

ggspectra 0.1.6

Clean documentation and code for CRAN submission. Add examples of plotting of waveband objects as these were removed from the vignette of package 'photobiologyWavebands'.

ggspectra 0.1.5

Fix bug in documentation.

ggspectra 0.1.4

Improve documentation.

ggspectra 0.1.3

Remove wb_guide() Remove wb_wb_summary() Add stat_wb_mean(), stat_wb_total(), stat_wb_contribution(), stat_wb_relative() Add stat_wb_irrad(), stat_wb_sirrad()

Implement 100% of the old functionality of the plot() methods, but without using any annotations. In other words, now all calculations work as expected with grouping and panels. Some aesthetics may require tweaking in the case of grouping.

Tested with packages ggrepel and cowplot.

ggspectra 0.1.2

Add text explaining examples to User Guide.

Rename several stats and functions with more descriptive names.

stat_color_guide() -> stat_wl_strip() stat_average() -> stat_wl_summary() stat_waveband() -> stat_wb_summary() color_guide() -> wl_guide() waveband_guide() -> wb_guide()

ggspectra 0.1.1

Add multiplot() function (unchanged from package photobiologygg). Improve stat_waveband(). Add color_guide(), waveband_guide().

Add ggplot() methods for spectra, which use default mappings if mapping not explicitly supplied as argument to call.

Make plot() methods almost fully functional. "contribution" and "participation" summary values not yet implemented. Neither summaries for BSWFs. If requested these summaries will show as "NaN" (not a number) in the plots.

ggspectra 0.1.0

First preview version. Still with incomplete functionality.

Reference manual

It appears you don't have a PDF plugin for this browser. You can click here to download the reference manual.