HolidayCalendars {fCalendar}R Documentation

Holiday Calendars and Utilities

Description

A collection and description of functions and methods dealing with holiday calendars. Included are functions for the computation of the date of easter and related feasts. These functions allow the generation of holiday calendars. Included are some utility functions to compute special dates from n-dates, and to manage dates formatted in the ISO-8601 integer CCYYMMDD calendar format. Furthermore, functions are available to convert Julian counts to formatted calendar dates and vice versa. These are SPlus like functions.

The functions for the generation of holiday calendars are:

easter Returns date of easter or related feasts as 'sdate'-s,
holiday Returns a holiday date of G7 and CH as 'sdate',
holiday.NYSE Computes 'timeDate' object for full-day NYSE holidays.

The N-Day functions are:

on.or.after Date in month that is a "n-day" on-or-after a "date",
on.or.before Date in month that is a "n-day" on-or-before a "date",
nth.of.nday The "n-th" ocurrance of a "n"day in year/month,
last.of.nday The last "n"day in a given year/month.

The ISO-8601 day functions and methods are:

sjulian Julian day counts from ISO formatted dates,
sdate ISO-8601 formatted dates from Julian day counts,
sday.of.week day of week from CCYYMMDD formatted dates,
sleap.year Decides if CCYYMMDD is a leap year or not,
print S3 Print method for objects of class sdate.

SPlus like Functions are:

fjulian Calculates Julian counts from different formats,
.julian Converts formatted calendar dates to Julian counts,
month.day.year Returns months, days, and years from Julian counts,
leap.year Deciding if a year is a leap year or not,
day.of.week Determines the day of week, starting with Sunday as 0.

Usage

easter(year, shift = 0)
holiday(year, Holiday = Easter)
holiday.NYSE(y = currentYear)

on.or.after(year, month, day, nday)
on.or.before(year, month, day, nday)
nth.of.nday(year, month, nday, nth) 
last.of.nday(year, month, lastday, nday)

sjulian(sdates, origin = 19600101)
sdate(julians, origin = 19600101)
sday.of.week(sdates)
sleap.year(sdates)

## S3 method for class 'sdate':
print(x, ...)

fjulian(fdates, origin = 19600101, order = 'mdy', cc = NULL, swap = 20)
.julian(m, d, y, origin = c(month = 1, day = 1, year = 1960))

month.day.year(jul, origin = c(month = 1, day = 1, year = 1960))
leap.year(y) 
day.of.week(month, day, year)

Arguments

cc, swap [fjulian] -
originally a numeric value denoting the century. Is now obsolete with the introduction of swap. swap is an integer value which determines when we swap from the 19th to 20th century, by default 20, i.e. we swap 1920.
day an integer vector of day numbers, [DD]. [day.of.week] - cr vector of integer day numbers.
fdates [fjulian] -
a character vector of formatted Gregorian dates.
Holiday the unquoted function name of an ecclestial or public holiday in the G7 countries or Switzerland, see the list below.
jul [month.day.year] -
vector of Julian dates (the number of days since origin).
julians a numeric vector of Julian Day Counts.
lastday the last day in the calendar month.
m, d, y [.julian] -
vector of month, day and year numbers. The years should be entered in their full four-digit form; it is assumed that two-digit years refer to the first century.
month an integer vector of month numbers, [MM].
[day.of.week] - cr vector of integer month numbers.
nday an integer vector with entries ranging from 0 (Sunday) to 6 (Saturday).
nth an integer vector numbering the n-th occurence.
order [fjulian] -
a character string, indicating the order of year, month and day.
origin the origin date of the counter, in ISO-8601 date format, [CCYYMMDD]. By default Januar 1st, 1960.
sdates a numeric vector of ISO-8601 formatted Gregorian dates, [CCYYMMDD].
shift a numeric value, the n-day shift. By default the shift is set to zero and the function returns the date of Easter.
x an object of class "sdate". This is an integer value or integer vector formatted as ISO-8601 CCYYMMDD.
year an integer vector of years, [CCYY]. [day.of.week] - cr vector of integer year numbers.
... additional optional arguments to be passed.

Details

Holiday Calendar:

Easter is the central ecclestial holiday. Many other holidays are related to this feast. The function easter computes the dates of easter and related ecclestial holidays for the requested year vector. holiday calculates the dates of ecclestial or publich holidays in the G7 countries, e.g. holiday(2003, "GoodFriday"). holidays.db is our Data Base of World Wide Holidays. The database contains holiday functions automatically loaded by the fBasics library at startup time. The user can add additional holiday functions to this data base. The information for the holiday data base were collected from several web pages about holiday calendars. The following ecclestial and public [HOLIDAY] functions in the G7 countries and Switzerland are available:

Holidays Related to Easter:
Septuagesima, Quinquagesima, AshWednesday, PalmSunday, GoodFriday, EasterSunday, Easter, EasterMonday, RogationSunday, Ascension, Pentecost, PentecostMonday, TrinitySunday CorpusChristi.

Holidays Related to Christmas:
ChristTheKing, Advent1st, Advent1st, Advent3rd, Advent4th, ChristmasEve, ChristmasDay, BoxingDay, NewYearsDay.

Other Ecclestical Feasts:
SolemnityOfMary, Epiphany, PresentationOfLord, Annunciation, TransfigurationOfLord, AssumptionOfMary, AssumptionOfMary, BirthOfVirginMary, CelebrationOfHolyCross, MassOfArchangels, AllSaints, AllSouls.

CHZurich - Public Holidays:
CHBerchtoldsDay, CHSechselaeuten, CHAscension, CHConfederationDay, CHKnabenschiessen.

GBLondon - Public Holidays:
GBMayDay, GBBankHoliday, GBSummerBankHoliday, GBNewYearsEve.

DEFrankfurt - Public Holidays:
DEAscension, DECorpusChristi, DEGermanUnity, DEChristmasEve, DENewYearsEve.

FRParis - Public Holidays:
FRFetDeLaVictoire1945, FRAscension, FRBastilleDay, FRAssumptionVirginMary, FRAllSaints, FRArmisticeDay.

ITMilano - Public Holidays:
ITEpiphany, ITLiberationDay, ITRepublicAnniversary, ITAssumptionOfVirginMary, ITAllSaints, ITWWIVictoryAnniversary, ITStAmrose, ITImmaculateConception.

USNewYork/USChicago - Public Holidays:
USNewYearsDay, USInaugurationDay, USMLKingsBirthday, USLincolnsBirthday, USWashingtonsBirthday, USMemorialDay, USIndependenceDay, USLaborDay, USColumbusDay, USElectionDay, USVeteransDay, USThanksgivingDay, USChristmasDay, USCPulaskisBirthday, USGoodFriday.

CAToronto/CAMontreal - Public Holidays:
CAVictoriaDay, CACanadaDay, CACivicProvincialHoliday, CALabourDay, CAThanksgivingDay, CaRemembranceDay.

JPTokyo/JPOsaka - Public Holidays:
JPNewYearsDay, JPGantan, JPBankHolidayJan2, JPBankHolidayJan3, JPComingOfAgeDay, JPSeijinNoHi, JPNatFoundationDay, JPKenkokuKinenNoHi, JPGreeneryDay, JPMidoriNoHi, JPConstitutionDay, JPKenpouKinenBi, JPNationHoliday, JPKokuminNoKyujitu, JPChildrensDay, JPKodomoNoHi, JPMarineDay, JPUmiNoHi, JPRespectForTheAgedDay, JPKeirouNoHi, JPAutumnalEquinox, JPShuubun-no-hi, JPHealthandSportsDay, JPTaiikuNoHi, JPNationalCultureDay, JPBunkaNoHi, JPThanksgivingDay, JPKinrouKanshaNohi, JPKinrou-kansha-no-hi, JPEmperorsBirthday, JPTennou-tanjyou-bi, JPTennou-tanjyou-bi.

All the holiday functions are listed in the data file holidays.R. Additional holidays, which are not yet available there, can be added to this data base file.

n-Day Functions:

The function on.or.after calculates the date in a given month and year that is a n-day ON OR AFTER a given date.

The function on.or.before calculates the date in a given month and year that is a n-day ON OR BEFORE a given date.

The function nth.of.nday calculates the n-th ocurrance of a n-day in a given month and year.

The function code{last.of.nday} calculates the last n-day in a given month and year.

sdate Class:

"sdates" represents a class of integer formatted CCYYMMDD ISO-8601 calendar dates. Note, that the s* indicates "standard" or "simple" ISO-8601 date format where CC denotes the century, YY the year, MM the month, and DD the day, e.g 20031213. This formated was included to the fbasics library already some years ago. It is likely that this date format will be replaced in the near future by the new R objects of class. "Date".

Value

easter
holiday
holiday.NYSE
return an ISO-8601 formatted calendar date CCYYMMDD, an object of class "sdate" which represents an integer value or vector.

on.or.after
on.or.before
nth.of.nday
last.of.nday
return like the holiday functions an ISO-8601 formatted calendar date integer value or vector.

sjulian
sdates
sday.of.week
sleap.year
the Julian day counter returns a numeric vector of Julian day counts, sdates returns a numeric vector of ISO-8601 formatted dates, i.e [CCYYMMDD], the day of the week function returns a numeric vector with entries between 0 (Sunday) and 6 (Saturday) and the leap year function returns a logical vector with entries TRUE or FALSE, weather the date falls in a leap year or not.

fjulian
returns a numeric vector of Julian Day Counts. When julian is called, a vector of Julian counts corresponding to the input values is returned. If month.day.year is called, a list with members month, day, and year is returned for the given Julian dates.

leap.year
returns a logical vector indicating whether the input years are leap years or not.

day.of.week
returns a number between 0 and 6 that specifies the day of the week of the given date; 0 refers to Sunday.

Note

Most of the functions were written for R Version 1.5. With the new Date Class becoming available in R 1.9.0 these functions will undergo a revision in the near future.

Author(s)

Therry Therneau for the C program used by fjulian,
Diethelm Wuertz for the Rmetrics R-port.

References

ISO-8601 (1988); Data Elements and Interchange Formats - Information Interchange, Representation of Dates and Time, International Organization for Standardization, Reference Number ISO 8601, 14 pages.

Therneau T. (1991); S-plus Date Routines, www.statlib.org

Examples

## SOURCE("fCalendar.25B-HolidayCalendars")

## easter -
   xmpBasics("\nStart: Easter and Easter Related Feasts > ")
   # Dates for Easter and Pentecost from 2000 until 2010:
   easter(2000:2010)
   easter(2000:2010, -2) # This is Good Friday
   holiday(2000:2010, Easter)
   holiday(2000:2010, GoodFriday)  
   
## holidays -   
   xmpBasics("\nNext: Alternatively You can use > ")
   Easter(2000:2010)
   GoodFriday(2000:2010)
  
## holiday.NYSE -
   xmpBasics("\nNext: Holiday Calendar for the New York Stock Exchange > ")
   holiday.NYSE(currentYear)
   
## on.or.after -
   xmpBasics("\nStart: on.or.after > ")
   # What date had the first advent 2001?
   # The first advent is the Sunday on or after November 27th.
   on.or.after(year = 2001, month = 11, day = 27, nday = 0)
   
## on.or.before -
   xmpBasics("\nNext: on.or.before > ")
   # What date had Monday on or after April, 1st, 2001?
   on.or.before(year = 2001, month = 11, day = 27, nday = 1)
   
## nth.of.nday -
   xmpBasics("\nNext: nth.of.nday > ")
   # What date had the second Sunday in October 1980?
   nth.of.nday(year = 1980, month = 10, nday = 0, nth = 2)
  
## last.of.nday -
   xmpBasics("\nNext: last.of.nday > ")   
   # What date had the last Monday in September, 2002?
   last.of.nday(year = 1996, month = 9, lastday = 31, nday = 1)  
   
## fdates - 
## fjulian -
   xmpBasics("\nStart: Convert Formatted Gregorian Dates > ")
   fdates = c("8/11/73", "08-11-73", "August 11 1973", "Aug11/73")
   fdates
   fjulian(fdates) 
   
## fdates - 
## fjulian -
   xmpBasics("\nNext: Convert with 'dmy' Order > ")
   fdates = c("11/8/73", "11-08-73", "11 August 1973", "11Aug73")
   fjulian(fdates, order = 'dmy')
   
## .julian - 
## day.of.week -
   xmpBasics("\nNext: Day of Week > ")
   # The number of days from January 1, 1990 to each of:
   # January 15, 1990, February 15, 1991, March 15, 1992, etc.
   .julian(1:12, rep(15,12), 1990+(0:11), origin = c(1, 1, 1990))
   # November 12, 98, was a Wednesday.
   day.of.week(m = 11, d = 12, y = 98)

[Package fCalendar version 221.10065 Index]