HolidayCalendars           package:fBasics           R Documentation

_H_o_l_i_d_a_y _C_a_l_e_n_d_a_r_s _a_n_d _U_t_i_l_i_t_i_e_s

_D_e_s_c_r_i_p_t_i_o_n:

     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.

_U_s_a_g_e:

     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)

_A_r_g_u_m_e_n_t_s:

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 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.      

_D_e_t_a_i_l_s:

     *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"'.

_V_a_l_u_e:

     '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.

_N_o_t_e:

     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.

_A_u_t_h_o_r(_s):

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

_R_e_f_e_r_e_n_c_e_s:

     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

_E_x_a_m_p_l_e_s:

     ## easter -
        xmpBasics("\nStart: Easter and Easter Related Feasts > ")
        # Dates for Easter and Pentecost from 2000 until 2010:
        easter(2000:2010)
        GoodFriday = easter(2000:2010, -2) # Tis is Good Friday
        GoodFriday
        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()
        
     ## 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)
        Continue = xmpBasics("Press any key > ")
       
     ## 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)

