planner.Rmd

---
title: "Get started"
output: rmarkdown::html_vignette
vignette: >
  %\VignetteIndexEntry{Get started}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---

```{r include=FALSE}
knitr::opts_chunk$set(collapse  = TRUE,
                      echo      = TRUE,
                      eval      = FALSE,
                      comment   = "#>",
                      out.width = "100%",
                      dpi       = 96,
                      fig.align = "center")
```

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.

```{r setup, eval=TRUE}
library("planner")
```

## Monthly calendar

The function `monthly_calendar()` creates a monthly calendar. Two arguments are mandatory and must be set by the user: `year` and `month`.


```{r 'default-settings'}
monthly_calendar(year  = 2024, 
                 month = 4)
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Default settings", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-01.png")
```

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.

```{r 'working-week'}
monthly_calendar(year    = 2024, 
                 month   = 4, 
                 weekend = FALSE)
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Working weeks", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-02.png")
```


### 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/>.

```{r 'moon-phases'}
monthly_calendar(year    = 2024, 
                 month   = 4, 
                 weekend = FALSE, 
                 moon    = TRUE)
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Moon phases", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-03.png")
```


### 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/>.

```{r 'get-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 Holiday
```

The 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`.

```{r 'holidays-1'}
monthly_calendar(year     = 2024, 
                 month    = 4, 
                 weekend  = FALSE, 
                 moon     = TRUE,
                 holidays = holidays)
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - UK Holidays", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-04.png")
```

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.

<br />

You can filter holidays by types with the function `filter_holidays()`.


```{r 'filter-holidays'}
holidays <- filter_holidays(data  = holidays, 
                            types = "Common Local Holiday")
holidays
#>         date          name                 type
#> 1 2024-04-01 Easter Monday Common Local Holiday
```

**Tip:** to get available types for the selected country, have a look at the function `get_holiday_types()`.


```{r 'holidays-2'}
monthly_calendar(year     = 2024, 
                 month    = 4, 
                 weekend  = FALSE,
                 moon     = TRUE,
                 holidays = holidays)
```


```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - UK Holidays (filtered)", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-05.png")
```

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:

```{r 'get-birthdays'}
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
```


```{r 'birthdays'}
monthly_calendar(year     = 2024, 
                 month    = 4, 
                 weekend  = FALSE,
                 moon     = TRUE,
                 holidays = holidays,
                 specials = birthdays)
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Special dates", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-06.png")
```


### 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.

```{r 'get-single-day-events'}
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-02
```

Of 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`.

```{r 'single-day-events'}
monthly_calendar(year     = 2024, 
                 month    = 4, 
                 weekend  = FALSE,
                 moon     = TRUE,
                 holidays = holidays,
                 specials = birthdays,
                 events   = events)
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Single-day events", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-07.png")
```

You can omit the ending date for single-day events. In that case, the event will be displayed as a bullet point.


```{r 'get-single-day-events-2'}
## 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>
```

```{r 'single-day-event-2'}
monthly_calendar(year     = 2024, 
                 month    = 4, 
                 weekend  = FALSE,
                 moon     = TRUE,
                 holidays = holidays,
                 specials = birthdays,
                 events   = events)
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Single-day events (bis)", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-08.png")
```



#### Multi-day events

The logic is the same for multi-day events. Let's create new calendar events.

```{r 'get-multi-day-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>
```


```{r 'multi-day-event'}
monthly_calendar(year     = 2024, 
                 month    = 4, 
                 weekend  = FALSE,
                 moon     = TRUE,
                 holidays = holidays,
                 specials = birthdays,
                 events   = events)
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Multi-day events", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-09.png")
```


#### Multi-week events

Multi-week events are also supported.


```{r 'get-multi-week-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 <- 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
```


```{r 'multi-week-event'}
monthly_calendar(year     = 2024, 
                 month    = 4, 
                 weekend  = FALSE,
                 moon     = TRUE,
                 holidays = holidays,
                 specials = birthdays,
                 events   = events)
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Multi-week events", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-10.png")
```


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.


```{r 'change-color'}
monthly_calendar(year     = 2024, 
                 month    = 4, 
                 weekend  = FALSE,
                 moon     = TRUE,
                 holidays = holidays,
                 specials = birthdays,
                 events   = events,
                 palette  = "#990000")
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Customize colors", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-11.png")
```

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`.

```{r 'category-argument'}
## 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        C
```

To 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.

```{r 'change-color-2'}
monthly_calendar(year     = 2024, 
                 month    = 4, 
                 weekend  = FALSE,
                 moon     = TRUE,
                 holidays = holidays,
                 specials = birthdays,
                 events   = events,
                 palette  = c("A" = "#00356a",
                              "B" = "#990000",
                              "C" = "#a17900"))
```

```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Customize colors (bis)", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-12.png")
```


### 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.

```{r 'finnish'}
monthly_calendar(year  = 2024, 
                 month = 4, 
                 lang  = "Finnish")
```


```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Customize language (Finnish)", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-13.png")
```


```{r 'greek'}
monthly_calendar(year  = 2024, 
                 month = 4, 
                 lang  = "Greek")
```


```{r echo=FALSE, eval=TRUE, out.width="100%", fig.cap = "Monthly calendar - Customize language (Greek)", fig.align='center'}
knitr::include_graphics("figures/calendar-demo-14.png")
```

## Annual calendar

Not implemented yet...