![[Maturing]](figures/lifecycle-maturing.svg)
link_to_timeline() is a function that links local times onto a two-day
timeline based on a specified threshold time.
This function is particularly useful for time arithmetic when dealing with
circular time representations. For information about circular time
representations, see cycle_time() Details
section.
Usage
link_to_timeline(x, threshold = hms::parse_hms("12:00:00"))Value
An POSIXt object with the same time as x,
but linked to a timeline based on the threshold time and the
Unix epoch. See the Details
section for more information.
Details
link_to_timeline() will link local times onto a two-day timeline based on
the threshold time and the
Unix epoch (1970-01-01).
If the threshold time is 12:00:00, for example, all times before this
threshold will be linked on the day after the Unix epoch (1970-01-02) and
all times after this threshold will be linked to the Unix epoch
(1970-01-01).
The exception is when all times are before the threshold. In this case, the
function will just return all times linked to the Unix epoch (1970-01-01).
Please note that the Unix Epoch is the origin of time for the POSIXct
class. This means that
as.POSIXct("1970-01-01 00:00:00", tz = "UTC") |> as.numeric()
is equal to 0. Learn more about the POSIXct class in
as.POSIXct().
See also
Other circular time functions:
assign_date(),
cycle_time(),
shorter_int()
Examples
## Scalar Example (Always on `1970-01-01`)
hms::parse_hm("18:00") |>
link_to_timeline(threshold = hms::parse_hms("12:00:00"))
#> [1] "1970-01-01 18:00:00 UTC"
#> [1] "1970-01-01 18:00:00 UTC" # Expected
as.POSIXct("2020-01-01 05:00:00", tz = "UTC") |>
link_to_timeline(threshold = hms::parse_hms("12:00:00"))
#> [1] "1970-01-01 05:00:00 UTC"
#> [1] "1970-01-01 05:00:00 UTC" # Expected
## Vector Example
c(hms::parse_hm("18:00"), hms::parse_hm("06:00")) |>
link_to_timeline(threshold = hms::parse_hms("12:00:00"))
#> [1] "1970-01-01 18:00:00 UTC" "1970-01-02 06:00:00 UTC"
#> [1] "1970-01-01 18:00:00 UTC" "1970-01-02 06:00:00 UTC" # Expected
c(as.POSIXct("2020-01-01 20:00:00", tz = "UTC"),
as.POSIXct("2020-01-01 05:00:00", tz = "UTC")) |>
link_to_timeline()
#> [1] "1970-01-01 20:00:00 UTC" "1970-01-02 05:00:00 UTC"
#> [1] "1970-01-01 20:00:00 UTC" "1970-01-02 05:00:00 UTC" # Expected
## Using a Different Threshold
c(as.POSIXct("2020-01-01 20:00:00", tz = "UTC"),
as.POSIXct("2020-01-01 01:00:00", tz = "UTC")) |>
link_to_timeline(threshold = hms::parse_hms("02:00:00"))
#> [1] "1970-01-01 20:00:00 UTC" "1970-01-02 01:00:00 UTC"
#> [1] "1970-01-01 20:00:00 UTC" "1970-01-02 01:00:00 UTC" # Expected
c(hms::parse_hm("06:00"), hms::parse_hm("18:00")) |>
link_to_timeline(threshold = hms::parse_hms("02:00:00"))
#> [1] "1970-01-01 06:00:00 UTC" "1970-01-01 18:00:00 UTC"
#> [1] "1970-01-01 06:00:00 UTC" "1970-01-01 18:00:00 UTC" # Expected
## With All Values Below or Above the Threshold
## (Returns on day one (`1970-01-01`))
c(hms::parse_hm("03:00"), hms::parse_hm("06:00")) |>
link_to_timeline(threshold = hms::parse_hms("12:00:00"))
#> [1] "1970-01-01 03:00:00 UTC" "1970-01-01 06:00:00 UTC"
#> [1] "1970-01-01 03:00:00 UTC" "1970-01-01 06:00:00 UTC" # Expected
c(hms::parse_hm("06:00"), hms::parse_hm("18:00")) |>
link_to_timeline(threshold = hms::parse_hms("02:00:00"))
#> [1] "1970-01-01 06:00:00 UTC" "1970-01-01 18:00:00 UTC"
#> [1] "1970-01-01 06:00:00 UTC" "1970-01-01 18:00:00 UTC" # Expected
## Doing Time Arithmetic
# 8h (Day 1) 8h
# <----|-----------------------|-----------------------|----->
# 06:00 14:00 22:00h
c(hms::parse_hm("06:00"), hms::parse_hm("22:00")) |>
mean() |>
hms::as_hms()
#> 14:00:00
#> 14:00:00 # Expected
# (Day 1) 4h 4h (Day 2)
# <----|-----------------------|-----------------------|----->
# 22:00 02:00 06:00h
c(hms::parse_hm("22:00"), hms::parse_hm("06:00")) |>
link_to_timeline(threshold = hms::parse_hms("12:00:00")) |>
mean() |>
hms::as_hms()
#> 02:00:00
#> 02:00:00 # Expected