align: Time Series and Signal Interpolation and Alignment

Description

Aligns or interpolates a time series or signal to new positions.

Usage

align(x, pos, how="NA", error.how="NA", localzone=FALSE, matchtol=0, by, 
      k.by=1, week.align=NULL, holidays=timeDate())

Value

returns a new time series or a signal whose positions are the passed-in positions or positions generated from by, k.by, and so on, and whose rows are derived from x as specified in the arguments. (Can be a subset if how or error.how is "drop".)

Arguments

x

the object to be aligned or interpolated.

pos

the new positions to align or interpolate it to (either pos or by is required).

how

specifies how to treat unmatched positions. Must be one of the following:

`"NA"`	Insert a row of `NA`.
`"drop"`	Drop that position entirely.
`"nearest"`	Use the row with the nearest position.
`"before"`	Use the data from the row whose position is just before the unmatched position.
`"after"`	Use the data from the row whose position is just after the unmatched position.
`"interp"`	Interpolate linearly between `"before"` and `"after"`.

error.how

specifies available actions when an out of bounds error occurs. (Such an error can occur when how is "before", "after", or "interp"). Must be one of the following:

`"NA"`	Insert a row of `NA`.
`"drop"`	Drop that position entirely.
`"nearest"`	Use the row with the nearest position.

localzone

if T (x must be a calendar-based time series), align by matching/interpolating with both x and pos in their local time zones, instead of with the absolute GMT times.

matchtol

the tolerance for matching positions. Positions that match within matchtol do not invoke the how argument methods.

by

if pos is missing and by is supplied for aligning a calendar-based time series, new positions are generated as a regular time/date sequence using one of the following:

by
k.by
week.align
holidays

by gives the spacing between successive values in the sequence. This can be a timeSpan, timeRelative, or numeric value, in which case k.by is ignored.

Alternatively, it can be one of the following character strings:

"milliseconds"
"seconds"
"minutes"
"hours"
"days"
"weekdays"
"bizdays"
"weeks"
"months"
"quarters"
"years"

These strings give the time units of intervals between values in the sequence.

k.by

a non-zero integer giving the width of the interval between consecutive values in the sequence in terms of the units given in by. Ignored if by is not a character string or if pos is given.

week.align

if not NULL, and by is "weeks", you can supply a character string (or a number, 0 to 6, with 0 being Sunday) to specify a weekday to align to. The character string must be sufficient to make a unique case-insensitive match to the strings in timeSeriesOptions("time.day.name"). Ignored if by is not a character string or if a pos is given.

holidays

the holidays for business day sequences. (Ignored if by is not a character string or if pos is given.)

Details

If either x or pos (or the generated sequence) has zero length, a zero-length series is returned.

Examples

Run this code

a <- signalSeries(pos=1:10, data=data.frame(a = 11:20, b = 5 * (1:10))) 
align(a, c(.2, 3, 7.8, 12), how = "interp", error.how = "nearest") 
a <- timeSeries(pos=as(1:10, "timeDate"), 
		data=data.frame(a = 11:20, b = 5 * (1:10))) 
alpos <- as(c(.2, 3, 7.8, 12), "timeDate") 
alpos@time.zone <- "JST" 
positions(a)@time.zone <- "PST" 
align(a, alpos, matchtol = 1, localzone = TRUE) 
align(a, matchtol=1, localzone=TRUE, by="days", k.by=2)