The R package planner is dedicated to create ready to
print calendars. Calendars are saved as PDF files in the A4 paper
format. User can add various information: holidays (several countries
available), moon phases, custom events (single-day, multi-day and
multi-week events), and special days (like birthdays, etc.).
This vignette shows how to customize calendars.
First, let’s import the package.
Monthly calendar
The function monthly_calendar() creates a monthly
calendar. Two arguments are mandatory and must be set by the user:
year and month.
monthly_calendar(year = 2024,
month = 4)
Monthly calendar - Default settings
By default, the calendar is exported as
calendar-2024-04.pdf in the current working directory. Use
the argument path to change the destination and the
argument filename to rename the PDF file.
Working week
If you want to remove Saturdays and Sundays, add
weekend = FALSE. This will produce a calendar with working
weeks.
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE)
Monthly calendar - Working weeks
Moon phases
You can add moon phases by setting the argument moon to
TRUE. Only full moons (empty circles), new moons (black
circles), first and third quarters are available. You need an Internet
connection when using moon = TRUE to scrap the website https://www.timeanddate.com/moon/phases/.
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE)
Monthly calendar - Moon phases
Holidays
The function get_holidays() can be used to retrieve
holidays for a specific country and for given year and month. This
function also requires an Internet connection to scrap the website https://www.timeanddate.com/holidays/.
holidays <- get_holidays(year = 2024,
month = 4,
country = "UK")
holidays
#> date name type
#> 1 2024-04-01 Easter Monday Common Local Holiday
#> 2 2024-04-05 Laylatul Qadr (Night of Power) Muslim
#> 3 2024-04-10 Eid ul Fitr (Tentative Date) Muslim
#> 4 2024-04-22 Stephen Lawrence Day Observance
#> 5 2024-04-23 First day of Passover Jewish Holiday
#> 6 2024-04-30 Last day of Passover Jewish HolidayThe output contains different types of holidays (field
type) which may vary by country. To add this information to
the monthly calendar, use the argument holidays.
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE,
holidays = holidays)
Monthly calendar - UK Holidays
Note the position of holidays on the calendar and the background of
cells: data pass to the argument holidays will always be
added at the top of cells.
You can filter holidays by types with the function
filter_holidays().
holidays <- filter_holidays(data = holidays,
types = "Common Local Holiday")
holidays
#> date name type
#> 1 2024-04-01 Easter Monday Common Local HolidayTip: to get available types for the selected
country, have a look at the function
get_holiday_types().
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE,
holidays = holidays)
Monthly calendar - UK Holidays (filtered)
Note that you can create your own holidays (days off) and pass the
data.frame to the holidays argument of the
function monthly_calendar(). Only two columns are required:
date and name.
Special events
You can also use the argument specials of the function
monthly_calendar() to add special days, like
birthdays. There will be added at the bottom of the cell (with a
glyph).
Let’s create two special dates:
birthdays <- data.frame("date" = c("2024-04-11", "2024-04-17"),
"name" = c("John's birthday", "Jane's birthday"))
birthdays
#> date name
#> 1 2024-04-11 John's birthday
#> 2 2024-04-17 Jane's birthday
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE,
holidays = holidays,
specials = birthdays)
Monthly calendar - Special dates
Adding events
The package planner can deal with different calendar
events:
- single-day events
- multi-day events
- multi-week events
To add these events to a monthly calendar you can use the argument
events of the function monthly_calendar() that
requires a data.frame with the following columns:
-
name: the name of the event, -
from: the starting date of the event, -
to: the ending date of the event.
Single-day events
Let’s add single-day events. First, we will create four events for the April 2, 2024.
events <- data.frame()
events <- rbind(events,
data.frame("name" = "Single-day event 1",
"from" = "2024-04-02",
"to" = "2024-04-02"))
events <- rbind(events,
data.frame("name" = "Single-day event 2",
"from" = "2024-04-02",
"to" = "2024-04-02"))
events <- rbind(events,
data.frame("name" = "Single-day event 3",
"from" = "2024-04-02",
"to" = "2024-04-02"))
events <- rbind(events,
data.frame("name" = "Single-day event 4",
"from" = "2024-04-02",
"to" = "2024-04-02"))
events
#> name from to
#> 1 Single-day event 1 2024-04-02 2024-04-02
#> 2 Single-day event 2 2024-04-02 2024-04-02
#> 3 Single-day event 3 2024-04-02 2024-04-02
#> 4 Single-day event 4 2024-04-02 2024-04-02Of course, you can store your events in a file (CSV, Excel, etc.) and
read it from R. You just need to name the columns according to the
structure of the events object (as shown above).
Let’s add these events to the calendar with the argument
events.
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE,
holidays = holidays,
specials = birthdays,
events = events)
Monthly calendar - Single-day events
You can omit the ending date for single-day events. In that case, the event will be displayed as a bullet point.
## Add a bullet point event ----
events <- rbind(events,
data.frame("name" = "Single-day event 5",
"from" = "2024-04-03",
"to" = NA))
events
#> name from to
#> 1 Single-day event 1 2024-04-02 2024-04-02
#> 2 Single-day event 2 2024-04-02 2024-04-02
#> 3 Single-day event 3 2024-04-02 2024-04-02
#> 4 Single-day event 4 2024-04-02 2024-04-02
#> 5 Single-day event 5 2024-04-03 <NA>
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE,
holidays = holidays,
specials = birthdays,
events = events)
Monthly calendar - Single-day events (bis)
Multi-day events
The logic is the same for multi-day events. Let’s create new calendar events.
events <- data.frame()
events <- rbind(events,
data.frame("name" = "Multi-day event 1",
"from" = "2024-04-02",
"to" = "2024-04-03"))
events <- rbind(events,
data.frame("name" = "Multi-day event 2",
"from" = "2024-04-02",
"to" = "2024-04-05"))
events <- rbind(events,
data.frame("name" = "Single-day event 1",
"from" = "2024-04-02",
"to" = "2024-04-02"))
events <- rbind(events,
data.frame("name" = "Single-day event 2",
"from" = "2024-04-02",
"to" = "2024-04-02"))
events <- rbind(events,
data.frame("name" = "Single-day event 3",
"from" = "2024-04-03",
"to" = NA))
events
#> name from to
#> 1 Multi-day event 1 2024-04-02 2024-04-03
#> 2 Multi-day event 2 2024-04-02 2024-04-05
#> 3 Single-day event 1 2024-04-02 2024-04-02
#> 4 Single-day event 2 2024-04-02 2024-04-02
#> 5 Single-day event 3 2024-04-03 <NA>
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE,
holidays = holidays,
specials = birthdays,
events = events)
Monthly calendar - Multi-day events
Multi-week events
Multi-week events are also supported.
events <- data.frame()
events <- rbind(events,
data.frame("name" = "Multi-day event 1",
"from" = "2024-04-02",
"to" = "2024-04-03"))
events <- rbind(events,
data.frame("name" = "Multi-day event 2",
"from" = "2024-04-02",
"to" = "2024-04-05"))
events <- rbind(events,
data.frame("name" = "Single-day event 1",
"from" = "2024-04-02",
"to" = "2024-04-02"))
events <- rbind(events,
data.frame("name" = "Single-day event 2",
"from" = "2024-04-02",
"to" = "2024-04-02"))
events <- rbind(events,
data.frame("name" = "Single-day event 3",
"from" = "2024-04-03",
"to" = NA))
events <- rbind(events,
data.frame("name" = "Multi-week event 1",
"from" = "2024-04-09",
"to" = "2024-04-23"))
events
#> name from to
#> 1 Multi-day event 1 2024-04-02 2024-04-03
#> 2 Multi-day event 2 2024-04-02 2024-04-05
#> 3 Single-day event 1 2024-04-02 2024-04-02
#> 4 Single-day event 2 2024-04-02 2024-04-02
#> 5 Single-day event 3 2024-04-03 <NA>
#> 6 Multi-week event 1 2024-04-09 2024-04-23
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE,
holidays = holidays,
specials = birthdays,
events = events)
Monthly calendar - Multi-week events
The vertical order of events by day follow these rules: events are ordered by duration (number of days by week), then by ending date (bullet-point events are added after boxed-events), and finally by event names.
For readability purposes, the number of events by day is limited to four (special days included).
Colors
The argument palette of the
monthly_calendar() allows you to change the color of events
(box background and bullet point). By providing only one
color all events will be colored the same way.
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE,
holidays = holidays,
specials = birthdays,
events = events,
palette = "#990000")
Monthly calendar - Customize colors
In planner it’s possible to categorize events and to
attribute a specific color to each category. First you need to add a new
column, named category, in the events
data.frame.
## Events with category ----
events <- data.frame()
events <- rbind(events,
data.frame("name" = "Multi-day event 1",
"from" = "2024-04-02",
"to" = "2024-04-03",
"category" = "A"))
events <- rbind(events,
data.frame("name" = "Multi-day event 2",
"from" = "2024-04-02",
"to" = "2024-04-05",
"category" = "B"))
events <- rbind(events,
data.frame("name" = "Single-day event 1",
"from" = "2024-04-02",
"to" = "2024-04-02",
"category" = "A"))
events <- rbind(events,
data.frame("name" = "Single-day event 2",
"from" = "2024-04-02",
"to" = "2024-04-02",
"category" = "A"))
events <- rbind(events,
data.frame("name" = "Single-day event 3",
"from" = "2024-04-03",
"to" = NA,
"category" = "B"))
events <- rbind(events,
data.frame("name" = "Multi-week event 1",
"from" = "2024-04-09",
"to" = "2024-04-23",
"category" = "C"))
events
#> name from to category
#> 1 Multi-day event 1 2024-04-02 2024-04-03 A
#> 2 Multi-day event 2 2024-04-02 2024-04-05 B
#> 3 Single-day event 1 2024-04-02 2024-04-02 A
#> 4 Single-day event 2 2024-04-02 2024-04-02 A
#> 5 Single-day event 3 2024-04-03 <NA> B
#> 6 Multi-week event 1 2024-04-09 2024-04-23 CTo associate a specific color to each event category, the argument
palette must contain as many colors as there are event
categories. Moreover, the palette argument must be a
named vector, where names match event categories.
monthly_calendar(year = 2024,
month = 4,
weekend = FALSE,
moon = TRUE,
holidays = holidays,
specials = birthdays,
events = events,
palette = c("A" = "#00356a",
"B" = "#990000",
"C" = "#a17900"))
Monthly calendar - Customize colors (bis)
Calendar language
Finally, it’s possible to change the language of the calendar (only
day and month names are supported) with the argument lang.
Not all languages are supported, and the rendering depends on your
system encoding and OS.
monthly_calendar(year = 2024,
month = 4,
lang = "Finnish")
Monthly calendar - Customize language (Finnish)
monthly_calendar(year = 2024,
month = 4,
lang = "Greek")
Monthly calendar - Customize language (Greek)