4.1.merge.data.pems {pems.utils}

Merging data and pems objects

Description

Various pems.utils functions to merge data of different types.

Usage

  #basic alignment
  align(data1, data2, n = 0, ...)
 
  #alignment based on correlation
  cAlign(form, data1 = NULL, data2 = NULL, ...)

  #alignment based on time.stamp
  tAlign(form, data1, data2 = NULL, order=TRUE, ...)

  #basic stacking
  stackPEMS(..., key=key, ordered=TRUE)

  #historical
  findLinearOffset(x = NULL, y = NULL, ...)

  #c wrappers
  C_ylagxCOR(x, y)

Arguments

data1, data2

(pems or data.frame; optional for cAlign, required for other alignment functions) pems objects or data.frames to be aligned.

n

(numeric; required) An offset to be applied to data2 when aligning data1 and data2. The default, n = 0, applies no offset and directly aligns the two supplied data sets, first row to first row.

...

(Any other arguments) For stackPEMS this is typically a series of pems objects to be stacked. For other functions, this may be passed on but are typically ignored. See Notes.

form

(formula; required) A formula identifying the elements in the supplied data sets to be used as references for the alignment. This typically takes the form, e.g. cAlign(x~y, d1, d2) where d1$x and d2$y are the data series to be used to correlation align the two data sets.

order

(logical; optional) If TRUE the function orders the data.

key

(character or NSE) For stackPEMS the name to key column that identifies the data sources of elements in a stack of pems objects.

ordered

(logical; default TRUE) For stackPEMS, when creating the source key should the order pems objects were supplied be retained.

x, y

(Required objects, various classes) For bindPEMS, two pems, data.frame, pems.elements or vectors to be bound together. For findLinearOffset, two pems.elements or vectors to be aligned.

Details

The align function accepts two pems objects, data.frame, etc, and returns a single dataset (as a pems object) of the aligned data. An extra argument, n, may be supplied to offset the starting row of the second data set relative to the first. It is intended to be used in the form:

aligned.data <- align(data1, data2) #aligned row 1-to-1

aligned.data <- align(data1, data2, 3) #row 3-to-1, etc

The cAlign function accepts a formula and up to two data sets and returns a single data set (as a pems object) of correlation aligned data. This uses the best fit linear offset correlation for the elements identifed in the formula term.

It is intended to be used in the form:

aligned.data <- cAlign(name1~name2, data1, data2)

C_ylagxCOR is a wrapper for C++ code used by cAlign.

The tAlign function accepts a formula and two data sets and returns a single data set (as a pems object) of the time stamp aligned data. This is this done by matching entries in the elements identifed in the formula term.

It is intended to be used in the form:

aligned.data <- tAlign(name1~name2, data1, data2)

The stackPEMS function stacks two or more pems objects and returns a single pems object. stackPEMS stacks using dplyr function bind_rows so handles pems with column names that do not completely intersect. However it also attempts to units match. It is intended to be used in the form:

stacked.data <- stackPEMS(data1, data2)

Historical functions:

findLinearOffset is historical code.

Value

align, cAlign, tAlign, etc all return a single object of pem class containing the aligned data from data1 and data2.

findLinearOffset returns the best fit offset for y relative to x.

Note

These functions are under revision and need to be handled with care.

cAlign: By default cAlign generates an alignment plot and returns a pems object of aligned data. But it also allows several hidden arguments to refine outputs, the logicals plot, offset and pems, which turn off/on plot, offset and pems reporting individually, and output = c("plot", "offset", "pems") or combinations thereof also provides a single argument alternative.

bindPEMS: The historical function bindPEMS has been superceded by align.

findLinearOffset: findLinearOffset is currently retained but will most likely be removed from future versions of pems.utils.

The call cAlign(x~y, output = "offset") is equivalent to findLinearOffset(x, y).

Author(s)

Karl Ropkins

References

align uses the dplyr function full_join.

cAlign function uses the stats function ccf.

tAlign uses the dplyr function full_join.

See Also

See also: cbind for standard column binding in R; dplyr for full_join.

Examples

###########
##example 1 
###########

##data vector alignment

#make two offset ranges
temp <- rnorm(500)
x <- temp[25:300]
y <- temp[10:200]

#plot pre-alignment data
plot(x, type="l"); lines(y, col="blue", lty=2)

#estimated offset
findLinearOffset(x,y)
#[1] -15

#applying linear offset
ans <- align(x, y, findLinearOffset(x,y))
names(ans) <- c("x", "y")

#plot post-alignment data
plot(ans$x, type="l"); lines(ans$y, col="blue", lty=2)

#shortcut using cAlign
## Not run: 
plot(x, type="l"); lines(y, col="blue", lty=2)
ans <- cAlign(x~y)
plot(ans$x, type="l"); lines(ans$y, col="blue", lty=2)

## End(Not run)


###########
##example 2 
###########

##aligning data sets
##(pems object example)

#make some offset data
p1 <- pems.1[101:200, 1:5]
p2 <- pems.1[103:350, 1:3]

#correlation alignment using ccf 
ans <- cAlign(~conc.co, p1, p2)

#this aligns by comparing p1$conc.co and p2$conc.co
#and aligning at point of best linear regression fit

## Not run: 

#compare:

cAlign(~conc.co, p2, p1)
cAlign(conc.co2~conc.co, p1, p2)
#(aligns using p1$conc.co2 and p2$conc.co)
cAlign(conc.co2~conc.co, p1)
#(realigns just conc.co within p1 based on best fit 
# with conc.co2 and returns as output ans) 

#time stamp alignment  
tAlign(~time.stamp, p1, p2)

#this aligns by pairing elements in p1$time.stamp 
#and p2$time.stamp
#(if time stamps have different names 
# tAlign(time1~time2, p1, p2), the time stamp name 
# from p1 would be retained when merging p1$time1 
# and p2$time2, generating [output]$time1)  


## End(Not run)

###########
##example 3 
###########

##stacking pems

#make some offset data
p1 <- pems.1[1:2, 1:4]
p2 <- pems.1[3, 2:4]
p3 <- pems.1[4:6, 1:3]

#stack  
stackPEMS(p1, p2, p3, key=source)