calendar v0.0.1

0

Monthly downloads

0th

Percentile

Create, Read, Write, and Work with 'iCalander' Files, Calendars and Scheduling Data

Provides function to create, read, write, and work with 'iCalander' files (which typically have '.ics' or '.ical' extensions), and the scheduling data, calendars and timelines of people, organisations and other entities that they represent. 'iCalendar' is an open standard for exchanging calendar and scheduling information between users and computers, described at <https://icalendar.org/>.

Readme

The API of a maturing package has been roughed out, but finer details
likely to
change. Travis build
status

calendar

The goal of calendar is to make it easy to create, read, write, and work with iCalander (.ics, .ical or similar) files, and the scheduling data they represent, in R. iCalendar is an open standard for “exchanging calendar and scheduling information between users and computers” described at icalendar.org (the full spec can be found in a plain text file here).

Recently the UK Government endorsed the iCal format in a publication for the ‘Open Standards for Government’ series. An example .ics file is provided by the .gov.uk domain, which shows holidays in England and Wales.

Installation

devtools::install_github("ATFutures/calendar")
library(calendar)

Example

A minimal example representing the contents of an iCalendar file is provided in the dataset ical_example, which is loaded when the package is attached. This is what iCal files look like:

ical_example
#>  [1] "BEGIN:VCALENDAR"                                  
#>  [2] "PRODID:-//Google Inc//Google Calendar 70.9054//EN"
#>  [3] "VERSION:2.0"                                      
#>  [4] "CALSCALE:GREGORIAN"                               
#>  [5] "METHOD:PUBLISH"                                   
#>  [6] "X-WR-CALNAME:atf-test"                            
#>  [7] "X-WR-TIMEZONE:Europe/London"                      
#>  [8] "BEGIN:VEVENT"                                     
#>  [9] "DTSTART:20180809T160000Z"                         
#> [10] "DTEND:20180809T163000Z"                           
#> [11] "DTSTAMP:20180810T094100Z"                         
#> [12] "UID:1119ejg4vug5758527atjcrqj3@google.com"        
#> [13] "CREATED:20180807T133712Z"                         
#> [14] "DESCRIPTION:\\n"                                  
#> [15] "LAST-MODIFIED:20180807T133712Z"                   
#> [16] "LOCATION:"                                        
#> [17] "SEQUENCE:0"                                       
#> [18] "STATUS:CONFIRMED"                                 
#> [19] "SUMMARY:ical programming mission"                 
#> [20] "TRANSP:OPAQUE"                                    
#> [21] "END:VEVENT"                                       
#> [22] "END:VCALENDAR"

Relevant fields can be found and extracted as follows:

which(ic_find(ical_example, "TSTAMP"))
#> [1] 11
ic_extract(ical_example, "TSTAMP")
#> [1] "D20180810T094100Z"

A larger example shows all national holidays in England and Wales. It can be read-in as follows:

ics_file <- system.file("extdata", "england-and-wales.ics", package = "calendar")
ics_raw = readLines(ics_file) 
head(ics_raw) # check it's in the ICS format
#> [1] "BEGIN:VCALENDAR"                     
#> [2] "VERSION:2.0"                         
#> [3] "METHOD:PUBLISH"                      
#> [4] "PRODID:-//uk.gov/GOVUK calendars//EN"
#> [5] "CALSCALE:GREGORIAN"                  
#> [6] "BEGIN:VEVENT"

A list representation of the calendar can be created using ic_list() as follows:

ics_list = ic_list(ics_raw)
ics_list[1:2]
#> [[1]]
#> [1] "DTEND;VALUE=DATE:20120103"                    
#> [2] "DTSTART;VALUE=DATE:20120102"                  
#> [3] "SUMMARY:New Year’s Day"                       
#> [4] "UID:ca6af7456b0088abad9a69f9f620f5ac-0@gov.uk"
#> [5] "SEQUENCE:0"                                   
#> [6] "DTSTAMP:20180806T114130Z"                     
#> 
#> [[2]]
#> [1] "DTEND;VALUE=DATE:20120407"                    
#> [2] "DTSTART;VALUE=DATE:20120406"                  
#> [3] "SUMMARY:Good Friday"                          
#> [4] "UID:ca6af7456b0088abad9a69f9f620f5ac-1@gov.uk"
#> [5] "SEQUENCE:0"                                   
#> [6] "DTSTAMP:20180806T114130Z"

A data frame representing the calendar can be created as follows (work in progress):

ics_df = ic_read(ics_file) # read it in
head(ics_df) # check the results
#> # A tibble: 6 x 6
#>   `DTEND;VALUE=DAT… `DTSTART;VALUE=D… SUMMARY   UID       SEQUENCE DTSTAMP 
#>   <date>            <date>            <chr>     <chr>     <chr>    <chr>   
#> 1 2012-01-03        2012-01-02        New Year… ca6af745… 0        2018080…
#> 2 2012-04-07        2012-04-06        Good Fri… ca6af745… 0        2018080…
#> 3 2012-04-10        2012-04-09        Easter M… ca6af745… 0        2018080…
#> 4 2012-05-08        2012-05-07        Early Ma… ca6af745… 0        2018080…
#> 5 2012-06-05        2012-06-04        Spring b… ca6af745… 0        2018080…
#> 6 2012-06-06        2012-06-05        Queen’s … ca6af745… 0        2018080…

What class is each column?

vapply(ics_df, class, character(1))
#>   DTEND;VALUE=DATE DTSTART;VALUE=DATE            SUMMARY 
#>             "Date"             "Date"        "character" 
#>                UID           SEQUENCE            DTSTAMP 
#>        "character"        "character"        "character"

Trying on calendars ‘in the wild’

To make the package robust we test on a wide range of ical formats. Here’s an example from my work calendar, for example:

my_cal = ic_dataframe(ical_outlook)
my_cal$SUMMARY[1]
#> [1] "In Budapest for European R Users Meeting (eRum) conference"
# calculate the duration of the European R users meeting event:
my_cal$`DTEND;VALUE=DATE`[1] - my_cal$`DTSTART;VALUE=DATE`[1]
#> Time difference of 4 days

Functions in calendar

Name Description
ic_bind_list Bind list of named vectors of variable length into data frame
ic_dataframe Convert iCal lines of text into a data frame
properties The key 'properties' that are allowed in ical files
properties_core The key 'properties' that are allowed in ical files
ic_spec View or download the ical specification
ic_vector Return a named vector from raw iCal text
ic_event Create ical object from properties_core inputs
ic_date Convert ical date into R date
ic_write Write ics file
holidays Example ics file on English and Welsh holidays
ic_attributes_vec Extract attributes from ical text
ical Create object of class ical
ic_char_event Convert ical object to character strings of events
ic_character Convert ical object to character strings of attributes
ic_find Find contents of iCal fields
ic_list Convert raw ical text into a list of items
ic_read Read ics file
properties_ical ical default VCALENDAR properties in one line vectors.
ic_guid Get an ical GUID
ical_example Minimal example of raw ical data
ical_outlook Example of event data with multi-line description from Outlook
ic_datetime Convert ical datetime into R datetime Z at the end of an ical stamp stands of Zulu time https://en.wikipedia.org/wiki/Coordinated_Universal_Time#Time_zones which is UTC = GMT https://greenwichmeantime.com/info/zulu/
ic_extract Extract contents of iCal fields
ic_extract_raw Extract raw contents of iCal fields
calendar ics files with R
formats Convenient datetime formats
ic_char_datetime Convert datetime object to character string
No Results!

Vignettes of calendar

Name
ical-creating-calendars.Rmd
No Results!

Last month downloads

Details

License Apache License (>= 2.0)
Encoding UTF-8
LazyData true
RoxygenNote 6.1.1
VignetteBuilder knitr
NeedsCompilation no
Packaged 2019-02-05 11:59:18 UTC; robin
Repository CRAN
Date/Publication 2019-02-11 13:53:13 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/calendar)](http://www.rdocumentation.org/packages/calendar)