3.1.generic.pems.handlers {pems.utils}

Generic handling of pems objects

Description

pems objects can be manipulated using generic functions like print, plot and summary in a similar fashion to objects of other R classes.

Usage

## S3 method for class 'pems'
as.data.frame(x,...)

## S3 method for class 'pems'
 dim(x, ...)

## S3 method for class 'pems'
 x$name, ...

## S3 replacement method for class 'pems'
 x$name, ... <- value

## S3 method for class 'pems'
 x[i, j, ..., force = FALSE, simplify = TRUE]

## S3 replacement method for class 'pems'
 x[i, j, ..., force = FALSE] <- value

## S3 method for class 'pems'
 x[[k, ...]]

## S3 replacement method for class 'pems'
 x[[k, ...]] <- value

## S3 method for class 'pems'
 with(data, expr, ...)

## S3 method for class 'pems'
 subset(x, ...)

## S3 method for class 'pems'
names(x, ...)

## S3 replacement method for class 'pems'
names(x, ...) <- value

## S3 method for class 'pems'
print(x,..., rows=NULL, cols=NULL, width=NULL)

## S3 method for class 'pems'
plot(x, id = NULL, ignore = "time.stamp", n = 3, ...)

## S3 method for class 'pems'
head(x, n = 6, ...)

## S3 method for class 'pems'
tail(x, n = 6, ...)

## S3 method for class 'pems'
summary(object, ...)

## S3 method for class 'pems'
na.omit(object, ...)

## S3 method for class 'pems'
units(x)

## S3 replacement method for class 'pems'
units(x) <- value

Arguments

x, object, data

(An Object of pems class). For direct use with print, plot, summary, etc. NOTE: Object naming (i.e., x or object) is determined in parent or base function in R, so naming can vary by method.

name

Element name, which operates in a similar fashion to data.frame names, e.g. pems$name extracts the element name from the pems object pems.

i, j

Row and column (elements) indices, which operate as a stricter version of data.frame indices. See Note below.

k

Structural indices. See Note below.

expr

(Expression) For with(pems), an expression to be evaluated inside the supplied pems object.

value

(vector, data.frame or pems) An object to be inserted into a pems object in e.g. the form pems[i,j] <- value or pems$name <- value.

...

Addition options, typically passed to associated default method(s).

force

(Logical or character) Data element handling options. force provides various options to forces data to fit it destination. This can either be set as a logical (TRUE/FALSE force/don't force) or one or more character strings to specify particular types of forcing to try when e.g. fitting value into pems[i,j]: 'omit.err.cases', equivalent to TRUE, remove any unknown/unfound i or j terms; 'na.pad.insert' expand the value to fit larger pems[i,j], placing NAs in any holes generated; 'na.pad.target' like previous but expanding pems[i,j] to fit larger value; 'fill.insert' like 'na.pad.inert' but holes are filled by wrapping the supplied value within elements and then by element.

simplify

(Logical) simplify returns a pems.element rather than a pems object if possible.

id, ignore

(local plot parameters). id identifies which data series to plot; ignore identifies which data series to ignore when leaving the choice of id to the function; and, n gives the maximum number of data series to plot when leaving the choice of id to the function.

rows, cols, width

(numerics, optional). For print, if supplied, these reset the number of rows and columns to table when printing a pems object, and character width to print across.

n

(various). For plot, sets the maximum number of data series to plot when leaving the choice of id to the function. For head or tail, sets the number of rows.

Value

Generic functions provide appropriate (conventional) handling of objects of 'pems' class:

as.data.frame(pems) extracts the data.frame component of a pems object.

dim(pems) extracts the dimensions, row count and column count, respectively, of the data.frame component of a pems object. The function also allows nrow(pems) and ncol(pems).

pems$name extracts the named element from a pems objects in a similar fashion to data.frame$name. Likewise, pems$name <- value inserts value into a pems objects in a similar fashion to data.frame$name <- value.

pems.object[i, j] extracts the [i,j] elements of the data held in a pems object. This is returned as either a pems or pems.element object depending on the dimension of the extracted data and the simplify setting.

pems.object[i, j]<- insert value into the [i,j] region of the supplied pems object. By default this action is strict and mismatching pems[i, j] and value dimension produce an error, although mismatching insertions may be forced using the force argument.

pems.object[[k]] extracts structural elements of a pems object: data, the data.frame; units the unit table, etc.

with(pems.object, expression) evaluates the supplied expression using the elements of the supplied pems.object.

subset(pems.object, expression) behaves like subset(data.frame, expression).

print(pems.object) provides a (to console) description of a pems object. This forshortens large datasets in a similar fashion to a tibble.

plot(pems.object) generates a standard R plot using selected data series in a pems object.

names(pems.object) returns a vector of the names of data series held in a pems object when used in the form names(pems) or resets names when used in the form names(pems) <- new.names.

na.omit(pems.object) returns the supplied pems object with all rows including NAs removed.

summary(pems.object) generates a summary report for data series held in a pems object.

units(pems.object) extracts the units from a supplied pems object when used in the form units(pems) or sets/resets units when used in the form units(pems) <- new.units.

Note

The pems object is intended to be a stricter version of a standard R data.frame. Unless the user specifically forces the operation, a pems[] or pems[]<- call is not allowed unless it fits exactly. So, for example by default the call pems[,1]<-10 will not place 10 in every row of column one in the same fashion as data.frame[,1]<-10.

The logic behind this is that columns (elements) of pems objects are time-series. So, users would want to place these exactly and avoid any unintended wrapping. The force argument should be used in cases where data padding or wrapping operations are required.

pems$name and pems$name<- are not are rigorously managed, so behave more like data.frame$name and data.frame$name<- calls, although even these do wrap by default.

pems[[]] provides access to structural components of the pems object, e.g. pems[["data"]] extracts the data.frame component of the pems object, pems[["units"]] extracts the units component, etc. See also pems.structure.

Author(s)

Karl Ropkins

References

generics in general:

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

(Not yet fully implemented within this package.)

Examples

##example 1
##basics pems handling

#extract a subset pems object from pems.1
a <- pems.1[1:4, 1:5]
a      

#indices work like data.frame
#a[x] and a[,x] recovers element/column number x
#a[x,] recovers row number x
#a["name"] and a[,"name"] recovers element/column named "name"
#a[4:5, "name"] recovers rows 4 to 5 of element/column named "name"
#a[x,y] <- z inserts z into a at row x, element y 
#etc

#insert 10 in at element 3, row 2
a[2,3] <- 10
a

#replace element conc.co2 with conc.co
a["conc.co2"] <- a$conc.co
a

#Note: by default pems objects subsetting and inserting is 
#more rigorous than data.frame subsetting/insertion
#for example, a[1:2, "conc.hc"] <- 8 would generate error
#because the target, a[1:2], and insert, 8, dimensions do not 
#match exactly: target 2 x 1; insert 1 x 1 

#By default no wrapping is applied.  

#the force argument allows the user to control how mismatching 
#targets and insertions are handled

#na pad target for larger insert
a[1:2, "conc.hc", force="na.pad.target"] <- 1:5
a

#Note here when the target is padded existing enteries are NOT 
#overwritten if they are not declared in a[], and the next 
#previously unassigned cells are used for any extra cases in
#the insert.

#wrap insert to fill hole made by a[i,j]  
a[1:2, "conc.hc", force="fill.insert"] <- 8
a

#pems$name <- value is equivalent to 
#pems[name, force=c("na.pad.target", "na.pad.insert")]
a$new <- 1:4
a