warp v0.1.0

0

0th

Percentile

Group Dates

Tooling to group dates by a variety of periods including: yearly, monthly, by second, by week of the month, and more. The groups are defined in such a way that they also represent the distance between dates in terms of the period. This extracts valuable information that can be used in further calculations that rely on a specific temporal spacing between observations.

warp

The goal of warp is to provide tooling to group dates by a variety of periods, such as: yearly, monthly, by second, by week of the month, and more.

library(warp)


Installation

You can install the release version from CRAN with:

install.package("warp")


You can install the development version from GitHub with:

# install.packages("devtools")
devtools::install_github("DavisVaughan/warp")


Example

One of the core functions in warp is warp_distance(), which allows you to provide a date time vector and compute the “distance” from an origin. For example, this computes the number of months from the unix epoch.

x <- as.Date("1970-01-01") + -2:2
x
#> [1] "1969-12-30" "1969-12-31" "1970-01-01" "1970-01-02" "1970-01-03"

warp_distance(x, period = "month")
#> [1] -1 -1  0  0  0


The values that warp_distance() returns correspond to the distance from x to the origin, in units defined by the period and the width defined by every. The origin defaults to the unix epoch of 1970-01-01 00:00:00 in the time zone of x, but you can change that. In this case the distances are saying that, for example, "1970-01-02" is in the same month as the origin, and "1969-12-31" is 1 month group away.

You can also compute daily distances. Rather than grouping by 1 day, let’s lump every 2 days together, starting from the default origin.

# Groups 1970-01-01 and 1970-01-02 together
warp_distance(x, period = "day", every = 2)
#> [1] -1 -1  0  0  1


You will often want to set your own origin date. Let’s shift it forward 1 to 1970-01-02.

origin <- as.Date("1970-01-02")
origin
#> [1] "1970-01-02"

# Groups 1970-01-02 and 1970-01-03 together
warp_distance(x, period = "day", every = 2, origin = origin)
#> [1] -2 -1 -1  0  0


Another interesting period to group by is the "mweek", i.e. the week of the month. Notice that days 1-7 of January 1970 are grouped into the same bucket. Also note that days 29-31 of December 1969 fell at the end of their corresponding month. This irregular week of size 3 is treated as the 5th week of that month, but the offset value of -1 is still the number of week buckets from the origin of 1970-01-01.

y <- as.Date("1969-12-28") + 0:14

tibble::tibble(
y = y,
mweek = warp_distance(y, "mweek")
)
#> # A tibble: 15 x 2
#>    y          mweek
#>    <date>     <dbl>
#>  1 1969-12-28    -2
#>  2 1969-12-29    -1
#>  3 1969-12-30    -1
#>  4 1969-12-31    -1
#>  5 1970-01-01     0
#>  6 1970-01-02     0
#>  7 1970-01-03     0
#>  8 1970-01-04     0
#>  9 1970-01-05     0
#> 10 1970-01-06     0
#> 11 1970-01-07     0
#> 12 1970-01-08     1
#> 13 1970-01-09     1
#> 14 1970-01-10     1
#> 15 1970-01-11     1


Inspiration

The algorithm for warp_distance() was inspired by xts::endpoints().

Functions in warp

 Name Description warp_distance Compute distances from a date time origin warp_change Detect changes in a date time vector warp_boundary Locate period boundaries for a date vector warp-package warp: Group Dates No Results!