4.1.merge.data.pems: Merging data and pems objects
In pems.utils: Portable Emissions (and Other Mobile) Measurement System Utilities

Description Usage Arguments Details Value Note Author(s) References See Also Examples

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

  #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)

`data1, data2`	(`pems` or `data.frame`; optional for `cAlign`, required for other alignment functions) `pems` objects or `data.frame`s 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.

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.

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.

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).

Karl Ropkins

align uses the dplyr function full_join.

cAlign function uses the stats function ccf.

tAlign uses the dplyr function full_join.

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

###########
##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)