R: 'tidyverse' methods for 'sftime' objects

tidyverse {sftime}

R Documentation

'tidyverse' methods for `sftime` objects

Description

'tidyverse' methods for sftime objects. Geometries are sticky, use as.data.frame to let dplyr's own methods drop them. Use these methods without the .sftime suffix and after loading the 'tidyverse' package with the generic (or after loading package 'tidyverse').

Usage

inner_join.sftime(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

left_join.sftime(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

right_join.sftime(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

full_join.sftime(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

semi_join.sftime(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

anti_join.sftime(x, y, by = NULL, copy = FALSE, suffix = c(".x", ".y"), ...)

filter.sftime(.data, ..., .dots)

arrange.sftime(.data, ..., .dots)

group_by.sftime(.data, ..., add = FALSE)

ungroup.sftime(.data, ...)

rowwise.sftime(.data, ...)

mutate.sftime(.data, ..., .dots)

transmute.sftime(.data, ..., .dots)

select.sftime(.data, ...)

rename.sftime(.data, ...)

slice.sftime(.data, ..., .dots)

summarise.sftime(.data, ..., .dots, do_union = TRUE, is_coverage = FALSE)

summarize.sftime(.data, ..., .dots, do_union = TRUE, is_coverage = FALSE)

distinct.sftime(.data, ..., .keep_all = FALSE)

## S3 method for class 'sftime'
gather(
  data,
  key,
  value,
  ...,
  na.rm = FALSE,
  convert = FALSE,
  factor_key = FALSE
)

## S3 method for class 'sftime'
pivot_longer(
  data,
  cols,
  names_to = "name",
  names_prefix = NULL,
  names_sep = NULL,
  names_pattern = NULL,
  names_ptypes = NULL,
  names_transform = NULL,
  names_repair = "check_unique",
  values_to = "value",
  values_drop_na = FALSE,
  values_ptypes = NULL,
  values_transform = NULL,
  ...
)

## S3 method for class 'sftime'
spread(data, key, value, fill = NA, convert = FALSE, drop = TRUE, sep = NULL)

sample_n.sftime(
  tbl,
  size,
  replace = FALSE,
  weight = NULL,
  .env = parent.frame()
)

sample_frac.sftime(
  tbl,
  size = 1,
  replace = FALSE,
  weight = NULL,
  .env = parent.frame()
)

## S3 method for class 'sftime'
nest(.data, ...)

## S3 method for class 'sftime'
unnest(data, ..., .preserve = NULL)

## S3 method for class 'sftime'
separate(
  data,
  col,
  into,
  sep = "[^[:alnum:]]+",
  remove = TRUE,
  convert = FALSE,
  extra = "warn",
  fill = "warn",
  ...
)

## S3 method for class 'sftime'
unite(data, col, ..., sep = "_", remove = TRUE)

## S3 method for class 'sftime'
separate_rows(data, ..., sep = "[^[:alnum:]]+", convert = FALSE)

Arguments

`x`	An object of class `sftime`.
`y`	A pair of data frames, data frame extensions (e.g. a tibble), or lazy data frames (e.g. from dbplyr or dtplyr). See Methods, below, for more details.
`by`	A character vector of variables to join by. If `NULL`, the default, `⁠*_join()⁠` will perform a natural join, using all variables in common across `x` and `y`. A message lists the variables so that you can check they're correct; suppress the message by supplying `by` explicitly. To join by different variables on `x` and `y`, use a named vector. For example, `by = c("a" = "b")` will match `x$a` to `y$b`. To join by multiple variables, use a vector with length > 1. For example, `by = c("a", "b")` will match `x$a` to `y$a` and `x$b` to `y$b`. Use a named vector to match different variables in `x` and `y`. For example, `by = c("a" = "b", "c" = "d")` will match `x$a` to `y$b` and `x$c` to `y$d`. To perform a cross-join, generating all combinations of `x` and `y`, use `by = character()`.
`copy`	If `x` and `y` are not from the same data source, and `copy` is `TRUE`, then `y` will be copied into the same src as `x`. This allows you to join tables across srcs, but it is a potentially expensive operation so you must opt into it.
`suffix`	If there are non-joined duplicate variables in `x` and `y`, these suffixes will be added to the output to disambiguate them. Should be a character vector of length 2.
`...`	other arguments
`.data`	An object of class `stime`.
`.dots`	see corresponding function in package `dplyr`
`add`	see corresponding function in dplyr
`do_union`	logical; in case `summary` does not create a geometry column, should geometries be created by unioning using st_union, or simply by combining using st_combine? Using st_union resolves internal boundaries, but in case of unioning points, this will likely change the order of the points; see Details.
`is_coverage`	logical; if `do_union` is `TRUE`, use an optimized algorithm for features that form a polygonal coverage (have no overlaps)
`.keep_all`	see corresponding function in dplyr
`data`	see original function docs
`key`	see original function docs
`value`	see original function docs
`na.rm`	see original function docs
`convert`	see separate_rows
`factor_key`	see original function docs
`cols`	<`tidy-select`> Columns to pivot into longer format.
`names_to`	A string specifying the name of the column to create from the data stored in the column names of `data`. Can be a character vector, creating multiple columns, if `names_sep` or `names_pattern` is provided. In this case, there are two special values you can take advantage of: `NA` will discard that component of the name. `.value` indicates that component of the name defines the name of the column containing the cell values, overriding `values_to`.
`names_prefix`	A regular expression used to remove matching text from the start of each variable name.
`names_sep`	If `names_to` contains multiple values, these arguments control how the column name is broken up. `names_sep` takes the same specification as `separate()`, and can either be a numeric vector (specifying positions to break on), or a single string (specifying a regular expression to split on). `names_pattern` takes the same specification as `extract()`, a regular expression containing matching groups (`⁠()⁠`). If these arguments do not give you enough control, use `pivot_longer_spec()` to create a spec object and process manually as needed.
`names_pattern`	If `names_to` contains multiple values, these arguments control how the column name is broken up. `names_sep` takes the same specification as `separate()`, and can either be a numeric vector (specifying positions to break on), or a single string (specifying a regular expression to split on). `names_pattern` takes the same specification as `extract()`, a regular expression containing matching groups (`⁠()⁠`). If these arguments do not give you enough control, use `pivot_longer_spec()` to create a spec object and process manually as needed.
`names_ptypes`	A list of column name-prototype pairs. A prototype (or ptype for short) is a zero-length vector (like `integer()` or `numeric()`) that defines the type, class, and attributes of a vector. Use these arguments to confirm that the created columns are the types that you expect. If not specified, the type of the columns generated from `names_to` will be character, and the type of the variables generated from `values_to` will be the common type of the input columns used to generate them.
`names_transform`	A list of column name-function pairs. Use these arguments if you need to change the type of specific columns. For example, `names_transform = list(week = as.integer)` would convert a character week variable to an integer.
`names_repair`	What happens if the output has invalid column names? The default, `"check_unique"` is to error if the columns are duplicated. Use `"minimal"` to allow duplicates in the output, or `"unique"` to de-duplicated by adding numeric suffixes. See `vctrs::vec_as_names()` for more options.
`values_to`	A string specifying the name of the column to create from the data stored in cell values. If `names_to` is a character containing the special `.value` sentinel, this value will be ignored, and the name of the value column will be derived from part of the existing column names.
`values_drop_na`	If `TRUE`, will drop rows that contain only `NA`s in the `value_to` column. This effectively converts explicit missing values to implicit missing values, and should generally be used only when missing values in `data` were created by its structure.
`values_ptypes`	A list of column name-prototype pairs. A prototype (or ptype for short) is a zero-length vector (like `integer()` or `numeric()`) that defines the type, class, and attributes of a vector. Use these arguments to confirm that the created columns are the types that you expect. If not specified, the type of the columns generated from `names_to` will be character, and the type of the variables generated from `values_to` will be the common type of the input columns used to generate them.
`values_transform`	A list of column name-function pairs. Use these arguments if you need to change the type of specific columns. For example, `names_transform = list(week = as.integer)` would convert a character week variable to an integer.
`fill`	see original function docs
`drop`	see original function docs
`sep`	see separate_rows
`tbl`	see original function docs
`size`	see original function docs
`replace`	see original function docs
`weight`	see original function docs
`.env`	see original function docs
`.preserve`	see unnest
`col`	see separate
`into`	see separate
`remove`	see separate
`extra`	see separate

Value

For _join methods: An object of class sftime representing the joining result of x and y. See mutate-joins.
For filter: See filter.
For arrange: See arrange.
For group_by and ungroup: A grouped sftime object. See arrange.
For rowwise: An sftime object. See rowwise.
For mutate and transmute: See mutate.
For select: See select. If the active time column is not explicitly selected, a sf object is returned.
For rename: See rename.
For slice: See slice.
For summarize and summarise: See summarise.
For distinct: See distinct.
For gather: See gather.

Examples

g1 <- st_sfc(st_point(1:2), st_point(c(5, 8)), st_point(c(2, 9)))
x1 <- st_sftime(a = 1:3, geometry = g1, time = Sys.time())

g2 <- st_sfc(st_point(c(4, 6)), st_point(c(4, 6)), st_point(c(4, 6)))
x2 <- st_sftime(a = 2:4, geometry = g2, time = Sys.time())

library(dplyr)

## inner_join
inner_join(x1, as.data.frame(x2), by = "a") # note: the active time column is
# time.x and the active geometry column geometry.x

inner_join(x2, as.data.frame(x1), by = "a")

## left_join
left_join(x1, as.data.frame(x2), by = "a")

left_join(x2, as.data.frame(x1), by = "a")

## right_join
right_join(x1, as.data.frame(x2), by = "a")

right_join(x2, as.data.frame(x1), by = "a")

## full_join
full_join(x1, as.data.frame(x2), by = "a")

full_join(x2, as.data.frame(x1), by = "a")

## semi_join
semi_join(x1, as.data.frame(x2), by = "a")

semi_join(x2, as.data.frame(x1), by = "a")

## anti_join
anti_join(x1, as.data.frame(x2), by = "a")

anti_join(x2, as.data.frame(x1), by = "a")

## filter
filter(x1, a <= 2)

## arrange
arrange(x1, dplyr::desc(a))

## group_by
group_by(x1, time)

## ungroup
ungroup(group_by(x1, time))

## rowwise
x1 %>%
  mutate(a1 = 5:7) %>%
  rowwise() %>%
  mutate(a2 = mean(a, a1))

## mutate
x1 %>%
  mutate(a1 = 5:7)

## transmute
x1 %>%
  transmute(a1 = 5:7)

## select
x1 %>%
  select(-time) %>%
  select(geometry)

## rename
x1 %>%
  rename(a1 = a)

## slice
x1 %>%
  slice(1:2)

## summarise
x1 %>%
  summarise(time = mean(time))
  
x1 %>%
  summarize(time = mean(time))

## distinct
x1 %>%
  distinct(geometry)

## gather
library(tidyr)
x1 %>%
  mutate(a1 = 5:7) %>%
  gather(key = "variable", value = "value", a, a1)

## pivot_longer
x1 %>%
  mutate(a1 = 5:7) %>%
  pivot_longer(cols = c("a", "a1"), names_to = "variable", values_to = "value")

## spread
x1 %>%
  mutate(a1 = 5:7) %>%
  gather(key = "variable", value = "value", a, a1) %>%
  spread(key = "variable", value = "value")

## sample_n
set.seed(234)
x1 %>%
  sample_n(size = 10, replace = TRUE)

## sample_frac
x1 %>%
  sample_frac(size = 10, replace = TRUE) %>%
  sample_frac(size = 0.1, replace = FALSE)

## nest
x1 %>%
  nest(a1 = -time)

## unnest
x1 %>%
  mutate(a1 = list(1, c(1, 2), 5)) %>%
  unnest(a1)

## separate
x1 %>%
  mutate(x = c(NA, "a.b", "a.d")) %>%
  separate(x, c("A", "B"))

## unite
x1 %>%
  mutate(x = c(NA, "a.b", "a.d")) %>%
  separate(x, c("A", "B")) %>%
  unite(x, c("A", "B"))
  
## separate_rows
x1 %>%
  mutate(z = c("1", "2,3,4", "5,6")) %>%
  separate_rows(z, convert = TRUE)