R: Check whether a variable represents a linear sequence

is_linear_sequence {validate} | R Documentation

## Check whether a variable represents a linear sequence

### Description

A variable X = (x_1, x_2,…, x_n) (n≥q 0) represents a linear sequence when x_{j+1} - x_j is constant for all j≥q 1. That is, elements in the series are equidistant and without gaps.

### Usage

    is_linear_sequence(x, by = NULL, ...)

    ## S3 method for class 'numeric'
    is_linear_sequence(
      x,
      by = NULL,
      begin = NULL,
      end = NULL,
      sort = TRUE,
      tol = 1e-08,
      ...
    )

    ## S3 method for class 'Date'
    is_linear_sequence(x, by = NULL, begin = NULL, end = NULL, sort = TRUE, ...)

    ## S3 method for class 'POSIXct'
    is_linear_sequence(
      x,
      by = NULL,
      begin = NULL,
      end = NULL,
      sort = TRUE,
      tol = 1e-06,
      ...
    )

    ## S3 method for class 'character'
    is_linear_sequence(
      x,
      by = NULL,
      begin = NULL,
      end = NULL,
      sort = TRUE,
      format = "auto",
      ...
    )

    in_linear_sequence(x, ...)

    ## S3 method for class 'character'
    in_linear_sequence(
      x,
      by = NULL,
      begin = NULL,
      end = NULL,
      sort = TRUE,
      format = "auto",
      ...
    )

    ## S3 method for class 'numeric'
    in_linear_sequence(
      x,
      by = NULL,
      begin = NULL,
      end = NULL,
      sort = TRUE,
      tol = 1e-08,
      ...
    )

    ## S3 method for class 'Date'
    in_linear_sequence(x, by = NULL, begin = NULL, end = NULL, sort = TRUE, ...)

    ## S3 method for class 'POSIXct'
    in_linear_sequence(
      x,
      by = NULL,
      begin = NULL,
      end = NULL,
      sort = TRUE,
      tol = 1e-06,
      ...
    )

### Arguments

`x` | An R vector.
`by` | bare (unquoted) variable name or a list of unquoted variable names, used to split `x` into groups. The check is executed for each group.
`...` | Arguments passed to other methods.
`begin` | Optionally, a value that should equal `min(x)`
`end` | Optionally, a value that should equal `max(x)`
`sort` | `[logical]`. When set to `TRUE`, `x` is sorted within each group before testing.
`tol` | numerical tolerance for gaps.
`format` | `[character]`. How to interpret `x` as a time period. Either `"auto"` for automatic detection or a specification passed to `strptime`. Automatically detected periods are of the form year: `"2020"`, yearMmonth: `"2020M01"`, yearQquarter: `"2020Q3"`, or year-Qquarter: `"2020-Q3"`.

### Details

Presence of a missing value (`NA`) in `x` will result in `NA`, except when `length(x) <= 2` and `start` and `end` are `NULL`. Any sequence of length ≤q 2 is a linear sequence.

### Value

For `is_linear_sequence`: a single `TRUE` or `FALSE`, equal to `all(in_linear_sequence)`.

For `in_linear_sequence`: a `logical` vector with the same length as `x`.

### See Also

Other cross-record-helpers: `contains_exactly()`, `do_by()`, `exists_any()`, `hb()`, `hierarchy()`, `is_complete()`, `is_unique()`

### Examples

    is_linear_sequence(1:5) # TRUE
    is_linear_sequence(c(1,3,5,4,2)) # FALSE
    is_linear_sequence(c(1,3,5,4,2), sort=TRUE) # TRUE
    is_linear_sequence(NA_integer_) # TRUE
    is_linear_sequence(NA_integer_, begin=4) # FALSE
    is_linear_sequence(c(1, NA, 3)) # FALSE

    d <- data.frame(
        number = c(pi, exp(1), 7)
      , date = as.Date(c("2015-12-17","2015-12-19","2015-12-21"))
      , time = as.POSIXct(c("2015-12-17","2015-12-19","2015-12-20"))
    )

    rules <- validator(
        is_linear_sequence(number)  # fails
      , is_linear_sequence(date)    # passes
      , is_linear_sequence(time)    # fails
    )
    summary(confront(d,rules))

    ## check groupwise data
    dat <- data.frame(
       time = c(2012, 2013, 2012, 2013, 2015)
     , type = c("hi", "hi", "ha", "ha", "ha")
    )
    rule <- validator(in_linear_sequence(time, by=type))
    values(confront(dat, rule)) ## 2xT, 3xF

    rule <- validator(in_linear_sequence(time, type))
    values( confront(dat, rule) )

[Package validate version 1.1.1 Index]