https://github.com/DavisVaughan/warp

Group Dates
https://github.com/DavisVaughan/warp

Last synced: about 2 months ago
JSON representation

Group Dates

• Host: GitHub
• URL: https://github.com/DavisVaughan/warp
• Owner: DavisVaughan
• License: other
• Created: 2019-11-29T13:06:18.000Z (almost 5 years ago)
• Default Branch: main
• Last Pushed: 2023-11-02T18:21:48.000Z (11 months ago)
• Last Synced: 2024-06-11T20:02:19.929Z (3 months ago)
• Language: R
• Homepage: https://davisvaughan.github.io/warp/
• Size: 847 KB
• Stars: 23
• Watchers: 4
• Forks: 3
• Open Issues: 0
• Metadata Files:
  • Readme: README.Rmd
  • License: LICENSE
  • Code of conduct: .github/CODE_OF_CONDUCT.md

Awesome Lists containing this project

• jimsghstars - DavisVaughan/warp - Group Dates (R)

README

        
---

output: github_document

editor_options:

  chunk_output_type: console

---

```{r, include = FALSE}

knitr::opts_chunk$set(

  collapse = TRUE,

  comment = "#>",

  fig.path = "man/figures/README-",

  out.width = "100%"

)

```

# warp

[![R-CMD-check](https://github.com/DavisVaughan/warp/actions/workflows/R-CMD-check.yaml/badge.svg)](https://github.com/DavisVaughan/warp/actions/workflows/R-CMD-check.yaml)

[![Codecov test coverage](https://codecov.io/gh/DavisVaughan/warp/branch/main/graph/badge.svg)](https://app.codecov.io/gh/DavisVaughan/warp?branch=main)

![](https://media.giphy.com/media/jjeK2Er3E5igw/giphy.gif)

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.

```{r}

library(warp)

```

## Installation

You can install the release version from CRAN with:

```r

install.package("warp")

```

You can install the development version from [GitHub](https://github.com/) with:

``` r

# install.packages("pak")

pak::pak("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.

```{r}

x <- as.Date("1970-01-01") + -2:2

x

warp_distance(x, period = "month")

```

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

```{r}

# Groups 1970-01-01 and 1970-01-02 together

warp_distance(x, period = "day", every = 2)

```

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

```{r}

origin <- as.Date("1970-01-02")

origin

# Groups 1970-01-02 and 1970-01-03 together

warp_distance(x, period = "day", every = 2, origin = origin)

```

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

```{r}

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

tibble::tibble(

  y = y,

  mweek = warp_distance(y, "mweek")

)

```

## Inspiration

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