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")