8.1.pems.tidyverse.tools {pems.utils}

Functions to use tidyverse code with pems.utils outputs

Description

Various codes and methods.

Usage

#ggplot2 

## S3 method for class 'pems'
fortify(model, data, ...)

#dplyr (1) standard methods

## S3 method for class 'pems'
select(.data, ...)
## S3 method for class 'pems'
rename(.data, ...)
## S3 method for class 'pems'
filter(.data, ...)
## S3 method for class 'pems'
arrange(.data, ...)
## S3 method for class 'pems'
slice(.data, ...)
## S3 method for class 'pems'
mutate(.data, ..., units=NULL, warn=TRUE)
## S3 method for class 'pems'
group_by(.data, ..., .add=FALSE)
## S3 method for class 'pems'
groups(x)
## S3 method for class 'pems'
ungroup(x, ...)
## S3 method for class 'pems'
group_size(x)
## S3 method for class 'pems'
n_groups(x)
## S3 method for class 'pems'
summarise(.data, ...)
## S3 method for class 'pems'
pull(.data, ...)

#dplyr (2) related underscore methods

## S3 method for class 'pems'
select_(.data, ..., warn=TRUE)
## S3 method for class 'pems'
rename_(.data, ..., warn=TRUE)
## S3 method for class 'pems'
filter_(.data, ..., warn=TRUE)
## S3 method for class 'pems'
arrange_(.data, ..., warn=TRUE)
## S3 method for class 'pems'
slice_(.data, ..., warn=TRUE)
## S3 method for class 'pems'
mutate_(.data, ..., units=NULL, warn=TRUE)
## S3 method for class 'pems'
group_by_(.data, ..., .add=FALSE, warn=TRUE)             
## S3 method for class 'pems'
summarise_(.data, ..., warn=TRUE)

#dplyr (3) joining methods
## S3 method for class 'pems'
inner_join(x, y, by = NULL, copy = FALSE, ...)
## S3 method for class 'pems'
left_join(x, y, by = NULL, copy = FALSE, ...)
## S3 method for class 'pems'
right_join(x, y, by = NULL, copy = FALSE, ...)
## S3 method for class 'pems'
full_join(x, y, by = NULL, copy = FALSE, ...)
## S3 method for class 'pems'
semi_join(x, y, by = NULL, copy = FALSE, ...)
## S3 method for class 'pems'
anti_join(x, y, by = NULL, copy = FALSE, ...)

Arguments

model, data

(pems.object) In fortify, the pems object to be used as a data source when plotting using ggplot2 code. The method is rotuinely applied by ggplot2, so users can typically ignore this. See below.

...

(Optional) Other arguments, typically passed on to equivalent tidyverse function or method.

.data

(pems.object) For dplyr functions, the pems object to be used with, e.g. dplyr code.

warn

(Optional) Give warnings? For an underscore methods: a warning that an underscore method was used (See Below). For mutate: if new elements are generated without unit assignments.

units

(Character) In mutate, the units to assign to new elements created by call. See Below.

x, y

(Various) For group... functions, x is the pems dataset to be grouped. For ...join functions, x and y are the two datasets (pems, codedata.frame, etc) to be joined together.

.add

(Optional) Argument used by group_by and related dplyr grouping functions.

by, copy

(Various) For ...join functions, consistent with dplyr, by and copy are optional arguments. See Below.

Details

fortify is used by ggplot2 functions when these are used to plot data in a pems dataset. Most users will never have to use this directly.

The pems object methods select, rename, filter, arrange, slice, mutate, group_by and summarise are similar to data.frame methods of the same names in dplyr, but (hopefully) they also track units, etc, like a pems object. Work in progress. See below, especially Note.

Equivalent underscore methods (select_, etc) are also provided, although it should be noted that they are probably going when dplyr drops these.

Data joining methods include inner_join, left_join, right_join, full_join, semi_join and anti_join. Like above these are similar data.frame equivalents in dplyr, but (hopefully) also track units, etc, like a pems object. Same 'work in progress' caveat. See Note.

Value

select returns the requested part of the supplied pems object, e.g.: select(pems.1, velocity) returns the velocity element of pems.1 as a single column pems.object, consistent with the data.frame handling of select.data.frame.

rename returns the supplied pems object with the requested name change, e.g.: rename(pems.1, speed=velocity) returns pems.1 with the velocity column renamed speed.

filter returns the supplied pems object after the requested filter operation has been applied, e.g.: filter(pems.1, velocity>0.5) returns pems.1 after excluding all rows where the velocity value was less than or equal to 0.5.

arrange returns the supplied pems object reordered based on order of values in an identified element, e.g.: arrange(pems.1, velocity) returns pems.1 with its row reordered lowest to highest velocity entry.

slice returns requested rows of the supplied pems object, e.g.: slice(pems.1, 1:10) returns rows 1 to 10 of pems.1 as a new pems object.

mutate returns the supplied pems object with extra elements calculated as requested, e.g.: mutate(pems.1, new=velocity*2) returns the pems object with additional column, called new, which is twice the values in the velocity column. The units of the new column can be set using the additional argument units, e.g. mutate(pems.1, new=velocity*2, units="ick").

group_by returns a grouped_df object, which allowed by-group handling in subsequent dplyr code.

summarise works like summarise(data.frame, ...) and allows dataset calculations, e.g. summarise(pems, mean(velocity)) calculates the mean of the velocity of a supplied pems object. Units cannot be tracked during such calls and outputs are returned as a tibble as with summarise.data.frame.

The ..._join joining methods, join two supplied datasets. The first, x, must be a pems to employ ..._join.pems but the second, y can be e.g. a data.frame, etc.

Warning

This currently work in progress - handle with care.

Note

Currently not sure what I think about tidyverse, but it is always interesting, and ideas like fortify are nice.

The fortify method was developed by Hadley Wickham to simplify the integration of ggplot2 functions and special object classes.

It is a really nice idea for multiple reasons, the main one being that package users will probably never have to worry about it. However, packaging it means you can use a pems object directly as the data argument with ggplot2 code.

Author(s)

Karl Ropkins

References

Generics in general:

H. Wickham. Advanced R. CRC Press, 2014.

(Not yet fully implemented within this package.)

ggplot2:

H. Wickham. ggplot2: elegant graphics for data analysis. Springer New York, 2009.

(See Chapter 9, section 9.3, pages 169-175, for discussion of fortify)

dplyr:

Hadley Wickham, Romain Francois, Lionel Henry and Kirill Muller (2020). dplyr: A Grammar of Data Manipulation. R package version 1.0.2. https://CRAN.R-project.org/package=dplyr