# Introduction to Calendars

#### Peter Hurford

#### 2024-03-13

A calendar is an external file that lists events for a time series, such as holidays. For example, we might consider this calendar:

    library(knitr)
    calendar <- read.csv(system.file("extdata", "calendar.csv", package = "datarobot"))
    kable(calendar)

Date | Name
--- | ---
2018-01-01 | New Year’s Day
2018-02-14 | Valentine’s Day
2018-04-01 | April Fools
2018-05-05 | Cinco de Mayo
2018-07-04 | July 4th

## Connect to DataRobot

To explore calendars, let’s first connect to DataRobot. First, you must load the DataRobot R package library.

If you have set up a credentials file, `library(datarobot)` will initialize a connection to DataRobot automatically. Otherwise, you can specify your `endpoint` and `apiToken` as in this example to connect to DataRobot directly. For more information on connecting to DataRobot, see the “Introduction to DataRobot” vignette.

    library(datarobot)
    endpoint <- "https://<YOUR DATAROBOT URL GOES HERE>/api/v2"
    apiToken <- "<YOUR API TOKEN GOES HERE>"
    ConnectToDataRobot(endpoint = endpoint, token = apiToken)

## Creating Calendars

To create a DataRobot calendar from the CSV file, use `CreateCalendar`:

    calendar <- CreateCalendar("calendar.csv", name = "holidays")
    print(calendar)

$name [1] “holidays”

$created [1] “2019-10-25T08:38:43.286329Z”

$calendarStartDate [1] “2018-01-01”

$numEventTypes [1] 5

$source [1] “calendar.csv”

$calendarEndDate [1] “2018-07-04”

$projectIds list()

$id [1] “5db2b48a34ccce7a4df1425c”

attr(,“class”) [1] “dataRobotCalendar”

## Retrieving Calendars

You can retrieve a calendar from the list of calendars. This will list all calendars across all projects.

    calendars <- ListCalendars()
    calendar <- calendars[[1]]
    print(calendar)

$name [1] “holidays”

$created [1] “2019-10-25T08:38:43.286329Z”

$calendarStartDate [1] “2018-01-01”

$numEventTypes [1] 5

$source [1] “calendar.csv”

$calendarEndDate [1] “2018-07-04”

$projectIds list()

$id [1] “5db2b48a34ccce7a4df1425c”

attr(,“class”) [1] “dataRobotCalendar”

## Modifying Calendars

You can rename the calendar using `UpdateCalendar`.

    newCalendar <- UpdateCalendar(calendar, name = "newName")
    print(newCalendar)

$name [1] “newName”

$created [1] “2019-10-25T08:38:43.286329Z”

$calendarStartDate [1] “2018-01-01”

$numEventTypes [1] 5

$source [1] “calendar.csv”

$calendarEndDate [1] “2018-07-04”

$projectIds list()

$id [1] “5db2b48a34ccce7a4df1425c”

attr(,“class”) [1] “dataRobotCalendar”

## Making a Time Series Project using a Calendar

The main point of having calendars is not to admire them, but to use them for time series modeling! To do this, make a datetime partition like you usually would and pass the calendar using the `calendar` parameter.

    project <- SetupProject(timeSeriesData, projectName = "time series with calendar")
    cal <- CreateCalendar("calendar.csv")
    partition <- CreateDatetimePartitionSpecification("date",
                                                      autopilotDataSelectionMethod = "duration",
                                                      useTimeSeries = TRUE,
                                                      calendar = cal)
    StartProject(project, partition = partition, target = "target")

## Getting the Calendar Associated with a Project

You can get the calendar associated with a project using `GetCalendarFromProject`

    projectId <- "59dab74bbd2a54035786bfc0"
    calendar <- GetCalendarFromProject(project)
    print(calendar)

$name [1] “holidays”

$created [1] “2019-10-25T08:38:43.286329Z”

$calendarStartDate [1] “2018-01-01”

$numEventTypes [1] 5

$source [1] “calendar.csv”

$calendarEndDate [1] “2018-07-04”

$projectIds list()

$id [1] “5db2b48a34ccce7a4df1425c”

attr(,“class”) [1] “dataRobotCalendar”

## Getting the Projects Associated with a Calendar

To see all the projects associated with a particular calendar, look at the `projectIds` parameter of the calendar.

    print(calendar$projectIds)

[[1]] [1] “59dab74bbd2a54035786bfc0”

## Sharing Projects with Others

Calendars can also be shared:

    Share(calendar, "other.person.email@your.company.com")