diyar (version 0.2.0)

number_line: Number line objects

Description

number_line - A range of numeric values on a number line.

Usage

number_line(l, r, id = NULL, gid = NULL)
as.number_line(x)
is.number_line(x)
left_point(x)
left_point(x) <- value
right_point(x)
right_point(x) <- value
start_point(x)
start_point(x) <- value
end_point(x)
end_point(x) <- value
number_line_width(x)
reverse_number_line(x, direction = "both")
shift_number_line(x, by = 1)
expand_number_line(x, by = 1, point = "both")
invert_number_line(x, point = "both")
compress_number_line(
  x,
  methods = "overlap",
  collapse = FALSE,
  deduplicate = TRUE,
  method = "overlap"
)
number_line_sequence(x, by = 1, length.out = NULL)

Arguments

l

Left point of the number_line object. Must be able to be coerced to a numeric object

r

Right point of the number_line object. Must be able to be coerced to a numeric object

id

Unique numeric element identifier. Optional

gid

Unique numeric group identifier. Optional

x

number_line object

value

numeric based value

direction

Type of "number_line" objects to be reversed. Options are; "increasing", "decreasing" or "both" (default).

by

increment or decrement. Passed to seq() in number_line_sequence()

point

"start" or "end" point

methods

Methods of overlap. Check different pairs of number_line objects with the different methods

collapse

If TRUE, collapse the compressed results yet again.

deduplicate

if TRUE, retains only one number_line object per set of overlapping number_line.

method

Method of overlap. Check every pair of number_line objects with the same method. Deprecated. Please use methods instead.

length.out

desired length of the sequence. Passed to seq()

Value

number_line object

Details

A number_line object represents a range of real numbers on a number line.

Visually, it's presented as the left (l) and right (r) points of the range. This may differ from start and end points. The start point is the lowest value in the range, regardless of whether it's at the left or right point.

The location of the start point - left or right, indicates whether it's an "increasing" or "decreasing" range. This is the direction of the number_line.

reverse_number_line() - reverses the direction of a number_line object. A reversed number_line object has its l and r points swapped. The direction argument specifies which type of number_line objects will be reversed. number_line objects with non-finite starts or end points i.e. (NA, NaN and Inf) can't be reversed.

shift_number_line() - Shift a number_line object towards the positive or negative end of the number line.

expand_number_line() - Increase or decrease the width or length of a number_line object.

invert_number_line() - Invert the left and/or right points from a negative to positive value or vice versa.

compress_number_line() - "compress" or "collapse" overlapping number_line objects into a new number_line object that covers the start and end points of the originals. This results in duplicate number_line objects with the start and end points of the new expanded number_line object. See overlaps for further details on overlapping number_line objects. If a familiar (but unique) id is used when creating the number_line objects, compress_number_line can be an alternative for simple implementations of links or episodes.

number_line_sequence() - Convert a number_line object into a sequence of finite numbers. The direction of the sequence will correspond to that of the number_line object.

See Also

overlaps, set_operations, episodes and links

Examples

# NOT RUN {
date <- function(x) as.Date(x, "%d/%m/%Y")
dttm <- function(x) as.POSIXct(x, "UTC",format="%d/%m/%Y %H:%M:%S")

number_line(-100, 100); number_line(10, 11.2)

# Other numeric based object classes are also compatible
number_line(dttm("15/05/2019 13:15:07"), dttm("15/05/2019 15:17:10"))

# However, a warning is given if 'l' and 'r' have different classes.
# Consider if this needs to be corrected.
number_line(2, date("05/01/2019"))

# Convert numeric based objects to `number_line` objects
as.number_line(5.1); as.number_line(date("21/10/2019"))

# A test for number_line objects
a <- number_line(0, -100)
b <- number_line(date("25/04/2019"), date("01/01/2019"))
is.number_line(a); is.number_line(b)

# Structure of a number_line object
left_point(a); right_point(a); start_point(a); end_point(a)

# Reverse number_line objects
reverse_number_line(number_line(date("25/04/2019"), date("01/01/2019")))
reverse_number_line(number_line(200, -100), "increasing")
reverse_number_line(number_line(200, -100), "decreasing")

# Shift number_line objects
c <- number_line(5, 6)
# Towards the positive end of the number line
shift_number_line(x = c(c, c), by = c(2, 3))
# Towards the negative end of the number line
shift_number_line(x = c(c, c), by = c(-2, -3))

# Change the width or length of a number_line object
d <- c(number_line(3, 6), number_line(6, 3))

expand_number_line(d, 2)
expand_number_line(d, -2)
expand_number_line(d, c(2,-1))
expand_number_line(d, 2, "start")
expand_number_line(d, 2, "end")

# Invert `number_line` objects
e <- c(number_line(3, 6), number_line(-3, -6), number_line(-3, 6))

e
invert_number_line(e)
invert_number_line(e, "start")
invert_number_line(e, "end")

# Collapse number line objects
x <- c(number_line(10,10), number_line(10,20), number_line(5,30),  number_line(30,40))
compress_number_line(x, deduplicate = FALSE)
compress_number_line(x)
compress_number_line(x, collapse=TRUE)
compress_number_line(x, collapse=TRUE, methods = "inbetween")

# Convert a number line object to its series of real numbers
number_line_sequence(number_line(1, 5))
number_line_sequence(number_line(5, 1), .5)
number_line_sequence(number_line(5:1, 1:5), 1:5)

nl <- number_line(dttm("01/04/2019 00:00:00"), dttm("04/04/2019 00:00:00"))

number_line_sequence(c(nl, nl), c(episode_unit[["days"]] * 1.5, episode_unit[["hours"]] * 12))

# }