annotate_lunarphase: Annotate ggplot with lunar phases

In gghourglass: Plot Records per Time of Day

Annotate ggplot with lunar phases

Description

This function uses the suncalc package to calculate the lunar phase and uses it to annotate your plot. If your plot has an axis with a continuous datetime scale, lunar phases are plot along this axis. Otherwise you have to specify the date of the lunar phase.

Usage

AnnotateLunarphase

annotate_lunarphase(
  date = NULL,
  longitude = NULL,
  latitude = NULL,
  breaks = ggplot2::waiver(),
  placement = 0.9,
  radius = grid::unit(5, "mm"),
  n = 26,
  ...
)

Arguments

date	A datetime object used to calculate the illuminated fraction of the moon
longitude, latitude	Used to calculate zenith angle. This will result in a more accurate shape of the moon as observed at the specified location.
breaks	One of: NULL for no breaks waiver() for the breaks specified by date_breaks A Date/POSIXct vector giving positions of breaks A function that takes the limits as input and returns breaks as output
placement	Relative placement of the lunar annotation in the plotting panel. It should be between 0 and 1. Default is 0.9.
radius	Size of the lunar pictogram. It is best to use an absolute unit from the grid package. Default is a radius of 5 mm (grid::unit(5, "mm"))
n	Number of coordinates in the returned polygon shape (should be even).
...	Passed to the list of layer parameters.

Format

An object of class AnnotateLunarphase (inherits from GeomPolygon, Geom, ggproto, gg) of length 6.

Value

Returns a ggplot2::layer() which can be added to a ggplot2::ggplot()

Author(s)

Pepijn de Vries

Examples

library(ggplot2)
library(dplyr)
library(lubridate)
data(bats)

monitoring <- attr(bats, "monitoring")

## A lunar annotation can be added to a geom_hourglass layer
ggplot(mutate(bats, YEAR = year(RECDATETIME), MONTH = month(RECDATETIME)) |>
         filter(YEAR == 2018, MONTH == 5),
       aes(x = RECDATETIME, col = SPECDESCSCI)) +
  
  geom_hourglass() +
  
  annotate_lunarphase(
    longitude = monitoring$longitude[[1]],
    latitude  = monitoring$latitude[[1]],
    placement = 0.8) +
  
  scale_x_datetime(limits = as_datetime(c("2018-04-27", "2018-05-31")))

## In fact, it can be added to any plot with a continuous datetime scale

ggplot(data.frame(stamp = seq(as_datetime("2025-04-01 UTC"),
                              as_datetime("2025-04-30 UTC"),
                              length.out = 20),
                  value = 1:20), aes(x = stamp, y = value)) +
  geom_point() +
  annotate_lunarphase()

## Moreover, you can add it to an arbitrary plot without such scales,
## but then you need to specify the date

ggplot(data.frame(stamp = 1:20,
                  value = 1:20), aes(x = stamp, y = value)) +
  geom_point() +
  annotate_lunarphase(date = "2020-01-01", placement = c(0.1, 0.9))

gghourglass documentation built on April 11, 2025, 5:53 p.m.