calendr

calendr is a lightweight and consistent package to manipulate dates with an easy to use and extend API for holidays and other calendars.

Design choices

  • Support ISO date formats only (YYYY-MM-DD)
  • No support for time or time zones (UTC only)
  • Limited support for dates preceding the introduction of the Gregorian calendar (1582)
  • No support for dates prior than Common Era
  • Humanize names (weekdays, months etc.) based on locale by default
  • Inherit behaviors from locale matched to Unicode Common Locale Data Repository (CLDR) by default

Installation

You can install the development version of calendr like so:

# install.packages("remotes")
remotes::install_git('https://git.b4d8.fr/b4D8/calendr.git')

Dates

Most functions in the package have an iso argument which allows one to modify the date representation standard.

The gregorian standard used by default, was introduced in 1582 by the Pope Gregory XIII with a design based on the Christian celebration of Easter. It defines a 400 years cycle (146097 days) starting on Year 11 and based on 12 months of defined length (ranging from 28 to 31 days), each year starting on January 1st and ending on December 31st. A common Gregorian year has 365 days (52 weeks of 7 days + 1 day). To compensate for the fact that a period of 365 days is shorter than a tropical year by almost 6 hours, 97 years in the cycle have an extra day (February 29th) resulting in years of 366 days (52 weeks + 2 days). They are called leap years and and occurs every 4 years. Every 100 years, one leap year is skipped unless the year is divisible by 400 ).

The iso 8601 standard was introduced in 1988 by the ISO Swiss private organization. It is also based on a 400 years cycle but which starts on Year 0 (same as 1 BC) but uses weeks instead of months. An ISO year starts on the Monday of the week that contains year’s first Thursday (midpoint of the week). The difference between the start of the ISO year and the start of the standard year ranges from -3 to 3. It has either 364 days or 371 (the later being an ISO leap years which occurs every 5, 6 or 7 years) and 52 weeks (53 for ISO leap years). For a given 400 year cycle, 71 years are leap.

Note that the iso standard is based on 2 variables: week_start (1L) and min_days (4L), expecting values ranging from 1 (Monday) to 7 (Sunday).

Calendars

The package provides 3 types of calendars days:

  • holidays: for national holidays matched on region (default is extracted from LC_TIME).
  • vacations: for school holidays matched on region (default is extracted from LC_TIME).
  • custom: any other.

Available

calendar region zone
holidays FR Métropole, Alsace-Moselle, Guadeloupe, Guyane, Martinique, Mayotte, Nouvelle-Calédonie, La Réunion, Polynésie Française, Saint-Barthélémy, Saint-Martin, Wallis-et-Futuna, Saint-Pierre-et-Miquelon

New calendar

  • Choose a name (holidays, shool_holidays or any other) for the calendar and register it in calendars in the relevant section (holidays, school_holidays, custom)
  • Create a new R script named <section>__<calendar_name> with 1 function for each holiday with a year argument and optionally further arguments like zone that returns a vector of values that are either intervals or NA_real_ as well as a general function <section>_<calendar_name> which returns all holiday in given year. See R/holidays_FR.R for an example.

Options

name description default
calendr.lang Defines the months and weekdays names (locale must be available on your system). Use FALSE to prevent localization. extracted from LC_TIME
calendr.region Defines the default holidays and vacations calendars extracted from LC_TIME
calendr.week.start calendr.region matched to CLDR/weekData
calendr.week.min calendr.region matched to CLDR/weekData
calendr.weekend.start calendr.region matched to CLDR/weekData
calendr.wekend.end calendr.region matched to CLDR/weekData

Todo

  • [ ] school_holidays_FR (zones A, B, C)
  • [ ] holidays_ECB
  • astro_season: Spring, Summer, Fall, Winter (depending on Hemisphere)
  • meteo_season: Spring, Summer, Fall, Winter (depending on Hemisphere)
  • year_start argument for fiscal year or academic year.
  • quarter
  • day_of_quarter
  • week_of_quarter: if iso== TRUE, the quarters are fixed length of 13 weeks
  • quarter_first
  • quarter_last
  • semester
  • day_of_semester
  • week_of_semester
  • semester_first
  • semester_last
  • year_semester
  • Use CLDR months and weekdays names (wide, short, narrow)
  • schedule
    • date rolling conventions (Following, “Modified Following” etc.)
    • date counting conventions (30/360 etc.)

License

This project is under an MIT License.

  1. Year 0 does not exists in the Gregorian calendar so the year preceding 1 AD (meaning Anno Domini which is the same as Common Era or CE) is 1 BC (meaning Before Christ which is the same Before Common Era or BCE).↩︎