readable_julian_breaks: Create human-readable labels for julian dates

In nationalparkservice/NSNSDAcoustics: Streamline National Park Service Bioacoustics Analysis

Create human-readable labels for julian dates

Description

Create human-readable labels for julian dates, to be used downstream in plots. Particularly useful for generating plots that compare multiple years of data in one graph, especially when dealing with leap years (see Details).

Usage

readable_julian_breaks(
  data,
  posix.column,
  format,
  sep,
  timestep,
  julian.breaks
)

Arguments

data	A data.frame or data.table that must contain a column of class "POSIXct" "POSIXt".
posix.column	Character name of the "POSIXct" "POSIXt" column in 'data'.
format	Character string containing your desired date label components; any options in c('%d', '%m', '%b', '%B', '%y', '%Y'). For example, c('%Y', '%m', '%d') used with sep = '-' results in labels like: '2022-01-28'. See Details. Do not use '%y' or '%Y' options if data contains multiple years.
sep	Character value used to separate options in format. Any value may be used, but common uses would be options in c(' ', '-', '/').
timestep	Integer specifying the number of days that should be spaced between each label. For example, a value of 14 means labels will occur every two weeks.
julian.breaks	Optional integer vector specifying the values of julian dates to use; will override timestep argument.

Details

Note: to accommodate multi-year datasets that contain leap years (and thus, differing julian dates for the same human-readable date label), the behavior of this function is to remove leap year labels from the output data for clean plotting.

The format argument accepts any of the following options:

Format Option Code: Value

• %d: Day of month (integer).

• %m: Month (integer).

• %b: Month (abbreviated character).

• %B: Month (full name character).

• %y: Year (2 digit integer).

• %Y: Year (4 digit integer).

Value

A data.table with two columns: julian.date (integer) and date.lab (character) which can be used downstream in ggplot with the scale_x_continuous() element to customize human-readable dates on the x-axis.

Examples

## Not run: 

# Read in example data
data(exampleAI)

exampleAI <- data.table(exampleAI)

# Add a posix date time column
exampleAI[,dateTime := lubridate::ymd_hms(
     paste0(Date,' ', Hr, ':', Min, ':', Sec),
     tz = 'America/Anchorage')
]

# Add year and julian.date columns
exampleAI[, Year := factor(lubridate::year(dateTime))]
exampleAI[,julian.date := lubridate::yday(dateTime)]

# Create human-readable julian breaks
brks <- readable_julian_breaks(
  data = exampleAI,
  posix.column = 'dateTime',
  format = c('%B', '%d'),
  sep = ' ',
  timestep = 30
)

# Example plot of using breaks with human-readable data across years
# WARNING: May take a moment to plot the following
ggplot(exampleAI, aes(julian.date, ACIoutI, col = Year, group = Year)) +
 geom_smooth(method = 'loess', aes(fill = Year)) +
 scale_x_continuous(expand = c(0, 0),
                    breaks = brks$julian.date,
                    labels = brks$date.lab) +
 xlab('Date') +
 ylab('Acoustic Complexity Index') +
 theme(axis.text.x = element_text(angle = 90))


## End(Not run)

nationalparkservice/NSNSDAcoustics documentation built on March 4, 2025, 10:24 p.m.