diff_dates {ds4psy}

Get the difference between two dates (in human units).

Description

diff_dates computes the difference between two dates (i.e., from some from_date to some to_date) in human measurement units (periods).

Usage

diff_dates(
  from_date,
  to_date = Sys.Date(),
  unit = "years",
  as_character = TRUE
)

Arguments

from_date

From date (required, scalar or vector, as "Date"). Date of birth (DOB), assumed to be of class "Date", and coerced into "Date" when of class "POSIXt".

to_date

To date (optional, scalar or vector, as "Date"). Default: to_date = Sys.Date(). Maximum date/date of death (DOD), assumed to be of class "Date", and coerced into "Date" when of class "POSIXt".

unit

Largest measurement unit for representing results. Units represent human time periods, rather than chronological time differences. Default: unit = "years" for completed years, months, and days. Options available:

1. unit = "years": completed years, months, and days (default)

2. unit = "months": completed months, and days

3. unit = "days": completed days

Units may be abbreviated.

as_character

Boolean: Return output as character? Default: as_character = TRUE. If as_character = FALSE, results are returned as columns of a data frame and include from_date and to_date.

Details

diff_dates answers questions like "How much time has elapsed between two dates?" or "How old are you?" in human time periods of (full) years, months, and days.

Key characteristics:

• If to_date or from_date are not "Date" objects, diff_dates aims to coerce them into "Date" objects.

• If to_date is missing (i.e., NA), to_date is set to today's date (i.e., Sys.Date()).

• If to_date is specified, any intermittent missing values (i.e., NA) are set to today's date (i.e., Sys.Date()). Thus, dead people (with both birth dates and death dates specified) do not age any further, but people still alive (with is.na(to_date), are measured to today's date (i.e., Sys.Date()).

• If to_date precedes from_date (i.e., from_date > to_date) computations are performed on swapped days and the result is marked as negative (by a character "-") in the output.

• If the lengths of from_date and to_date differ, the shorter vector is recycled to the length of the longer one.

By default, diff_dates provides output as (signed) character strings. For numeric outputs, use as_character = FALSE.

Value

A character vector or data frame (with dates, sign, and numeric columns for units).

See Also

Time spans (interval as.period) in the lubridate package.

Other date and time functions: change_time(), change_tz(), cur_date(), cur_time(), days_in_month(), diff_times(), diff_tz(), is_leap_year(), what_date(), what_month(), what_time(), what_wday(), what_week(), what_year(), zodiac()

Examples

y_100 <- Sys.Date() - (100 * 365.25) + -1:1
diff_dates(y_100)

# with "to_date" argument: 
y_050 <- Sys.Date() - (50 * 365.25) + -1:1 
diff_dates(y_100, y_050)
diff_dates(y_100, y_050, unit = "d") # days (with decimals)

# Time unit and output format:
ds_from <- as.Date("2010-01-01") + 0:2
ds_to   <- as.Date("2020-03-01")  # (2020 is leap year)
diff_dates(ds_from, ds_to, unit = "y", as_character = FALSE)  # years
diff_dates(ds_from, ds_to, unit = "m", as_character = FALSE)  # months
diff_dates(ds_from, ds_to, unit = "d", as_character = FALSE)  # days

# Robustness:
days_cur_year <- 365 + is_leap_year(Sys.Date())
diff_dates(Sys.time() - (1 * (60 * 60 * 24) * days_cur_year))  # for POSIXt times
diff_dates("10-08-11", "20-08-10")   # for strings
diff_dates(20200228, 20200301)       # for numbers (2020 is leap year)

# Recycling "to_date" to length of "from_date":
y_050_2 <- Sys.Date() - (50 * 365.25)
diff_dates(y_100, y_050_2)

# Note maxima and minima: 
diff_dates("0000-01-01", "9999-12-31")  # max. d + m + y
diff_dates("1000-06-01", "1000-06-01")  # min. d + m + y

# If from_date == to_date:
diff_dates("2000-01-01", "2000-01-01")

# If from_date > to_date:
diff_dates("2000-01-02", "2000-01-01")  # Note negation "-"
diff_dates("2000-02-01", "2000-01-01", as_character = TRUE)
diff_dates("2001-02-02", "2000-02-02", as_character = FALSE)

# Test random date samples:
f_d <- sample_date(size = 10)
t_d <- sample_date(size = 10)
diff_dates(f_d, t_d, as_character = TRUE)

# Using 'fame' data:
dob <- as.Date(fame$DOB, format = "%B %d, %Y")
dod <- as.Date(fame$DOD, format = "%B %d, %Y")
head(diff_dates(dob, dod))  # Note: Deceased people do not age further.
head(diff_dates(dob, dod, as_character = FALSE))  # numeric outputs