# number_line and overlaps

#### 12 November 2023

# Introduction

A `number_line` object is a range of `numeric` values. `number_line` objects as based off `interval` objects from the `lubridate` package but supports any object that can be successfully coerced to a `numeric` object.

# Overview

For a given `number_line` object e.g. `8 <- 1`, its main components are;

- `left_point()` - left side of the `number_line` `i.e.` `8`
- `right_point()` - right side of the `number_line` `i.e.` `1`
- `start_point()` - lower end of the range `i.e.` `1`
- `end_point()` - upper end of the range `i.e.` `8`
- `direction` - `"decreasing"` `(<-)`, `"increasing"` `(->)` or no direction `(==)`
- `number_line_width()` - difference between the left and right points `i.e.` `-7`

For an `"increasing"` `number_line`, its `start_point()` is at the `left_point()`. In contrast, the `start_point()` of a `"decreasing"` `number_line` is at the `right_point()`.

    library(diyar)
    # `number_line` objects
    nl_a <- number_line(l = c(3, 5), r = c(4, 1))
    nl_a
    #> [1] "3 -> 4" "5 <- 1"

    # Lower end of the range
    start_point(nl_a)
    #> [1] 3 1
    # Left part of the range
    left_point(nl_a)
    #> [1] 3 5

# Implementation

## Manipulating a `number_line`

There are convenience functions to reverse, shrink, expand or shift a `number_line` along the number line.

    nl_c <- number_line(as.Date("2019-04-04"), as.Date("2019-4-07"))
    nl_c
    #> [1] "2019-04-04 -> 2019-04-07"

    # Expand the `number_line` by 2 days from both ends
    nl_d <- expand_number_line(nl_c, 2); nl_d
    #> [1] "2019-04-02 -> 2019-04-09"

    # Expand the `number_line` by 2 days from the lower end only
    nl_e <- expand_number_line(nl_c, 2, "start"); nl_e
    #> [1] "2019-04-02 -> 2019-04-07"

    # Shrink the `number_line` by 2 days from the upper end only
    nl_f <- expand_number_line(nl_c, -2, "end"); nl_f
    #> [1] "2019-04-04 -> 2019-04-05"

    # Shrink the `number_line` by 2 days from both ends
    nl_g <- expand_number_line(nl_c, -2); nl_g
    #> [1] "2019-04-06 <- 2019-04-05"

    # Reverse the direction of the `number_line`
    nl_h <- reverse_number_line(nl_c); nl_h
    #> [1] "2019-04-07 <- 2019-04-04"

    # Shift the `number_line` towards the negative end of the number line by 2 days
    nl_i <- shift_number_line(nl_c, -2); nl_i
    #> [1] "2019-04-02 -> 2019-04-05"

    # Shift the `number_line` towards the positive end of the number line by 2 days
    nl_j <- shift_number_line(nl_c, 2); nl_j
    #> [1] "2019-04-06 -> 2019-04-09"

    # Change the left part of the `number_line` to a negative value
    nl_k <- invert_number_line(nl_c, "left"); nl_k
    #> [1] "-17990 -> 17993"

    # Split a `number_line`
    nl_l <- seq(nl_c, length.out = 3); nl_l
    #> [1] "2019-04-04 -> 2019-04-05" "2019-04-05 -> 2019-04-07"

## Overlaps

`number_line` objects can overlap with each other. `diyar` recognises seven ways this can happen. These are `exact()`, `inbetween()`, `across()`, `chain()`, `aligns_start()` and `aligns_end()`. The 6 methods are mutually exclusive. There are 2 convenience methods - `"none"` and `overlap()`, which are mutually inclusive with the other 6. See Figure 1.

Figure 1: Overlap methods for `number_line`

## Set operations

    nl_1 <- c(number_line(1, 5), number_line(1, 5), number_line(5, 9))
    nl_2 <- c(number_line(1, 2), number_line(2, 7), number_line(0, 6))

    # Union
    nl_1; nl_2; union_number_lines(nl_1, nl_2)
    #> [1] "1 -> 5" "1 -> 5" "5 -> 9"
    #> [1] "1 -> 2" "2 -> 7" "0 -> 6"
    #> [1] "1 -> 5" "1 -> 7" "0 -> 9"

    nl_3 <- number_line(as.Date(c("01/01/2020", "03/01/2020","09/01/2020"), "%d/%m/%Y"),
                        as.Date(c("09/01/2020", "09/01/2020","25/12/2020"), "%d/%m/%Y"))

    nl_4 <- number_line(as.Date(c("04/01/2020","01/01/2020","01/01/2020"), "%d/%m/%Y"),
                        as.Date(c("05/01/2020","05/01/2020","03/01/2020"), "%d/%m/%Y"))

    # Intersect
    nl_3; nl_4; intersect_number_lines(nl_3, nl_4)
    #> [1] "2020-01-01 -> 2020-01-09" "2020-01-03 -> 2020-01-09"
    #> [3] "2020-01-09 -> 2020-12-25"
    #> [1] "2020-01-04 -> 2020-01-05" "2020-01-01 -> 2020-01-05"
    #> [3] "2020-01-01 -> 2020-01-03"
    #> [1] "2020-01-04 -> 2020-01-05" "2020-01-03 -> 2020-01-05"
    #> [3] "NA == NA"

    # Subtract
    nl_3; nl_4; subtract_number_lines(nl_3, nl_4)
    #> [1] "2020-01-01 -> 2020-01-09" "2020-01-03 -> 2020-01-09"
    #> [3] "2020-01-09 -> 2020-12-25"
    #> [1] "2020-01-04 -> 2020-01-05" "2020-01-01 -> 2020-01-05"
    #> [3] "2020-01-01 -> 2020-01-03"
    #> $n1
    #> [1] "2020-01-01 -> 2020-01-04" "2020-01-01 -> 2020-01-03"
    #> [3] "NA == NA"
    #>
    #> $n2
    #> [1] "2020-01-05 -> 2020-01-09" "2020-01-05 -> 2020-01-09"
    #> [3] "NA == NA"