6.113
Working with Date and Time Values in R

Introduction

Working with date and time objects is essential for time-series analysis and when working with temporal data. Breaking apart dates into day, month, or year components, or grouping by a date component are essential data shaping tasks. R, like many other languages, provides robust methods for handling dates and times, both through its base functionality and through specialized packages like lubridate. In this lesson, we will explore how to extract, parse, and manipulate date and time values in R using various approaches. Additionally, we will discuss important standards such as POSIX and ISO 8601 that underpin the representation of temporal data.

Date and Time Objects

In R, the Date class is used to store dates without times. These objects are represented as the number of days since January 1, 1970 (the Unix epoch). The as.Date() function is the primary tool for converting character data into Date objects. Note the format of the input date is generally “YYYY-MM-DD” but the as.Date() function also recognizes other formats as illustrated below.

# Converting character to Date
date1 <- as.Date("2025-01-23")
print(date1)

## [1] "2025-01-23"

class(date1)

## [1] "Date"

date2 <- as.Date("2025/01/23")
print(date2)

## [1] "2025-01-23"

Objects of class Date can be used in calculations. The function makes automatic adjustments for leap years.

# Adding or subtracting days
future_date <- date1 + 10
print(future_date)

## [1] "2025-02-02"

Current Date and Time

To get the current time, you can use the Sys.time() function. This function returns a POSIXct object that contains both the date and time, but you can extract only the time component if desired. The current date and time can be obtained using the mechanisms illustrated below:

# Get the current time
current_time <- Sys.time()
print(current_time)  # Example output: "2025-01-23 15:45:12 UTC"

## [1] "2025-01-24 07:22:40 EST"

# Extract only the time component using strftime
time_only <- format(current_time, "%H:%M:%S")
print(time_only)  # Example output: "15:45:12"

## [1] "07:22:40"

The format() function can be used to extract various date or time elements. Of course, other text processing functions can be used as well.

POSIXt Classes: POSIXct and POSIXlt

For date-time values, R provides the POSIXt class, which has two implementations: POSIXct and POSIXlt. These classes are designed to handle both dates and times.

• POSIXct: Represents date-time as the number of seconds since the Unix epoch. It is useful for computations.
• POSIXlt: Stores date-time as a list with separate components (e.g., year, month, day, hour).

# Creating a POSIXct object
datetime1 <- as.POSIXct("2025-01-23 14:30:00")
print(datetime1)
class(datetime1)

# Extracting components from a POSIXlt object
datetime2 <- as.POSIXlt(datetime1)
print(datetime2$hour)  # Extracting hour

Parsing Date Objects

Extracting various elements of the date and time from a Date object or date formatted text string can be done using various text processing functions such as substr() or using the format() function. Additional convenience functions exist within the lubridate package explained in detail in a subsequent section. For now, we will present various examples of extracting different elements.

Note that the Sys.time() function returns a POSIXct formatted object and not an ISO 8601 formatted string. Both format are explained in more detailed below. The format of a POSIXct object is: “YYYY-MM-DD hh:mm:ss UTC”, e.g., “2025-01-23 15:45:12 UTC”. Since we use string processing functions to extract the elements, they will be of type “character”; any calculation with them will require a conversion to an integer using the as.integer() function.

# Get the current time
now <- Sys.time()

# Extract the year
year <- substr(now, 1, 4)
print(year)

## [1] "2025"

# Extract the month
month <- substr(now, 6, 7)
print(month)

## [1] "01"

# Extract the hour and minutes
hr_min <- format(now, "%H:%M")
print(hr_min)

## [1] "07:22"

Of course, we could have used the substr() function for the hr_min extraction or even a regular expression. There isn’t a single correct approach; it is programming preference and ease of comprehensibility.

An alternative for parsing formatted date and time string is the strptime() function. Similar to the format() function shown below, the formats must adhere to specific codes, such as %Y for the year, %m for the month, and %d for the day.

# Parsing a custom date-time string
datetime_str <- "23-01-2025 14:30:00"
parsed_datetime <- strptime(datetime_str, format = "%d-%m-%Y %H:%M:%S")
print(parsed_datetime)

## [1] "2025-01-23 14:30:00 EST"

format Function

The format() function in R is a often used to format and extract components from date and time objects. It allows you to convert Date or POSIXt objects into character strings with customized formats, suitable for extracting specific date or time elements.

The basic syntax for format is show below:

format(x, format = "", tz = "", usetz = FALSE)

Here is a detailed explanation of each parameter:

1. x:
   • The input date or time object, such as a Date, POSIXct, or POSIXlt object. This is the value you want to format.
2. format:
   • A character string specifying the desired output format. This string uses specific placeholders (format codes) to represent components of the date and time.
   • Common format codes include:
     • %Y: Full year (e.g., “2025”).
     • %y: Last two digits of the year (e.g., “25”).
     • %m: Month as a two-digit number (e.g., “01”).
     • %B: Full month name (e.g., “January”).
     • %b: Abbreviated month name (e.g., “Jan”).
     • %d: Day of the month as a two-digit number (e.g., “23”).
     • %H: Hour in 24-hour format (e.g., “15”).
     • %I: Hour in 12-hour format (e.g., “03”).
     • %M: Minute (e.g., “45”).
     • %S: Second (e.g., “12”).
     • %p: AM/PM indicator.
     • %A: Full weekday name (e.g., “Thursday”).
     • %a: Abbreviated weekday name (e.g., “Thu”).
     • %j: Day of the year as a number (e.g., “023”).
     • %W: Week number of the year (starting with Monday as the first day of the week).
     • %w: Weekday number (0 = Sunday, 1 = Monday, etc.).
     • %z: Timezone offset (e.g., “-0500”).
     • %Z: Timezone abbreviation (e.g., “UTC”).
3. tz:
   • A character string specifying the desired time zone (e.g., "UTC", "America/New_York"). If not provided, the system’s default time zone is used.
4. usetz:
   • A logical value (TRUE or FALSE) that specifies whether to include the time zone abbreviation in the formatted output. This is relevant for POSIXt objects.

Let’s take a look at some examples. You can format a Date object to extract or display specific components.

# Creating a Date object
date_obj <- as.Date("2025-01-23")

# Extracting the year
year <- format(date_obj, "%Y")
print(year)  # Output: "2025"

## [1] "2025"

# Extracting the month as a name
month_name <- format(date_obj, "%B")
print(month_name)  # Output: "January"

## [1] "January"

# Extracting the day of the week
weekday <- format(date_obj, "%A")
print(weekday)  # Output: "Thursday"

## [1] "Thursday"

The format() function also works with POSIXct objects in addition to Date objects.

# Creating a POSIXct object
datetime_obj <- as.POSIXct("2025-01-23 15:45:12", tz = "UTC")

# Extracting the hour
hour <- format(datetime_obj, "%H")
print(hour)  # Output: "15"

## [1] "15"

# Extracting the minute
minute <- format(datetime_obj, "%M")
print(minute)  # Output: "45"

## [1] "45"

# Extracting the timezone
timezone <- format(datetime_obj, "%Z")
print(timezone)  # Output: "UTC"

## [1] "UTC"

Here is a more elaborate example in which we combine different components to create custom date-time strings.

# Custom formatted string
custom_format <- format(datetime_obj, "%d-%b-%Y %I:%M %p (%Z)")
print(custom_format)  # Output: "23-Jan-2025 03:45 PM (UTC)"

## [1] "23-Jan-2025 03:45 PM (UTC)"

The tz parameter allows you to format the date-time in a specific time zone allowing for conversion to a common time zone or to localize times.

# Formatting with a specific time zone
datetime_obj_tz <- format(datetime_obj, "%Y-%m-%d %H:%M:%S %Z", tz = "America/New_York")
print(datetime_obj_tz)  # Output: "2025-01-23 10:45:12 EST"

## [1] "2025-01-23 10:45:12 EST"

The usetz parameter can be used to control whether the time zone is displayed in the output.

# Including the time zone
formatted_with_tz <- format(datetime_obj, "%Y-%m-%d %H:%M:%S", usetz = TRUE)
print(formatted_with_tz)  # Output: "2025-01-23 15:45:12 UTC"

## [1] "2025-01-23 15:45:12 UTC"

# Excluding the time zone
formatted_without_tz <- format(datetime_obj, "%Y-%m-%d %H:%M:%S", usetz = FALSE)
print(formatted_without_tz)  # Output: "2025-01-23 15:45:12"

## [1] "2025-01-23 15:45:12"

The format() function is a commonly used date parsing function because you can:

• extract specific date or time elements (e.g., year, month, day, hour).
• create custom date-time strings for display or reporting purposes.
• convert date-time objects into character strings for labeling or exporting data.

Parsing Date Strings

Data files often have date and time stamps in non-standard format which require test processing functions to extract the various components. In such situations, the format() or strptime() functions is not appropriate as the date strings do not correspond to a Date or POSIXct format.

d <- "Dec 24, 2024"
month <- substr(d, 1, 3)
day <- substr(d, 5, 6)

months <- c("Jan", "Feb", "Mar", "Apr", "May", "Jun", 
            "Jul", "Aug", "Sep", "Oct", "Nov", "Dec")

month_num <- which(months == month)

month_day <- paste0(month_num, "/", day)
print(month_day)

## [1] "12/24"

Of course, the above code gets a bit more challenging if the encoding allows for “Dec 3, 2024” and “Apr 12, 2024” as the day is either one or two digits. In this situation looking for the comma might be better or applying a regular expression. This can be fun…

The lubridate Package

While Base R offers a plethora of functions, the lubridate package simplifies many common date-time operations with simpler-to-use functions. This package is particularly useful for parsing, extracting, and manipulating date-time values.

The lubridate package provides intuitive functions like ymd(), mdy(), and dmy() for parsing dates in different formats.

library(lubridate)

# Parsing with lubridate
date_parsed <- ymd("2025-01-23")
print(date_parsed)

## [1] "2025-01-23"

datetime_parsed <- ymd_hms("2025-01-23 14:30:00")
print(datetime_parsed)

## [1] "2025-01-23 14:30:00 UTC"

lubridate makes it easier to extract specific components of date-time objects using functions like year(), month(), and day(). Some examples are shown below.

# Extracting components
year_val <- year(datetime_parsed)
month_val <- month(datetime_parsed)
day_val <- day(datetime_parsed)

print(paste("Year:", year_val, "Month:", month_val, "Day:", day_val))

## [1] "Year: 2025 Month: 1 Day: 23"

Additionally, lubridate simplifies date-time arithmetic. For example, you correctly can add months, days, or years to a date.

# Adding duration
new_date <- date_parsed + months(2)
print(new_date)

## [1] "2025-03-23"

# Computing differences
date_diff <- as.duration(interval(date_parsed, new_date))
print(date_diff)

## [1] "5097600s (~8.43 weeks)"

Standards: POSIX and ISO 8601

POSIX

POSIX (Portable Operating System Interface) defines how date-time values are represented and manipulated in Unix-like systems. In R, POSIXct and POSIXlt adhere to this standard.

ISO 8601

ISO 8601 is an international standard for representing dates and times in a consistent, unambiguous format. It uses formats such as YYYY-MM-DD for dates and YYYY-MM-DDTHH:MM:SS for date-time values. The full datetime stamp structure is shown in the diagram below. Notice the use of ‘-’ as the separator for the date elements and ‘:’ as the separator for the time elements. A dot (.) separates the milliseconds. The hours are in 24-hour format – there is no accommodation for an ‘am’ or ‘pm’ indicator.

The functions of lubridate automatically recognize and handle ISO 8601 formatted date and time strings.

Summary

In this lesson, we explored the foundational tools in Base R for working with date and time objects, including Date, POSIXct, and POSIXlt. We also introduced the lubridate package, which simplifies parsing, extraction, and computation. Along the way, we discussed important standards like POSIX and ISO 8601, which ensure consistency in date-time representations, particularly across programming languages and databases.

---

Files & Resources

All Files for Lesson 6.113

---

References

No references.

Errata

Let us know.