Skip Header

Win Genhol Documentation

Version 1.0, Build 3
Nikki Czaplicki and Brian Monsell


1. Introduction

Win Genhol is a Windows interface for the Genhol utility (U.S. Census Bureau, 2015). Genhol creates moving holiday regressors that can be incorporated into regARIMA models in X-13ARIMA-SEATS (U.S. Census Bureau, 2020). Genhol can create regressors for effects before holidays, after holidays or an intermediate effect around the holiday. For more information on the Genhol utility, see the Genhol documentation here.

This version of the program is Version 1.0, Build 3. The only change made is to improve performance in Windows 10.

This program will:

  • Create input files necessary for creating moving holiday regressors with Genhol.
  • Run Genhol.
  • Display Genhol input and output files.

2. Requirements

Win Genhol has been tested on Windows XP, Windows 7, and Windows 10. This program requires the .NET Framework 3.5 installed on the computer, which can be downloaded here.

3. Getting Started

To install Win Genhol:

  1. Download WinGenhol_V1.0_B3.zip to a local drive (e.g. C:\WinGenhol_V1.0_B2.zip)
  2. Unzip WinGenhol_V1.0_B3.zip to that same directory (i.e. Extract to here).
  3. Open the wingenhol folder. This folder contains all of the necessary files for Win Genhol.
  4. Double click on WinGenhol.exe to launch. This will display the Win Genhol main screen.

4. Win Genhol Main Screen

Keyboard Shortcuts:

  • Create Input File - Ctrl + I
  • Refresh Files - Ctrl + R
  • File View Settings - Ctrl + S
  • Exit - Ctrl + E
  • Win Genhol Documentation - Ctrl + D
  • Genhol Website - Ctrl + G

Use the Win Genhol main screen to open and run Genhol input files and open Genhol output files. Genhol input files have a .inp extension and have syntax very similar to X-13ARIMA-SEATS spec files. An example of a Genhol input file is given below

    global{
        outfile = 'newholiday.dat'
        outspec = 'newholiday.reg'
        period = 12
        type = ratio
        first = 1990
    }

    holiday1{
        name = aNewHoliday
        infile = 'holidayDates.txt'
        center=calendar
        begbefore = -8
        endbefore = -1
    }

Use the folder browser on the left side to select the folder where the Genhol input files are stored. To open a Genhol input file, select it in the Genhol Input Files list and press the Edit button. To run Genhol, select an input file in the Genhol Input Files list and either press the Run Genhol button or double click the file name.

There are two types of output files produced by Genhol, regressor files and regression spec files. A regressor file is created for every successful Genhol run. It contains the regression matrix in datevalue format for the user-defined holiday regressors generated by Genhol. This file has a .dat extension. The first two years of a regressor file are given below.

        1990 1 0.0
        1990 2 0.0
        1990 3 -0.3832335329341318
        1990 4 0.3832335329341318
        1990 5 0.0
        1990 6 0.0
        1990 7 0.0
        1990 8 0.0
        1990 9 0.0
        1990 10 0.0
        1990 11 0.0
        1990 12 0.0
        1991 1 0.0
        1991 2 0.0
        1991 3 0.6167664670658682
        1991 4 -0.6167664670658682
        1991 5 0.0
        1991 6 0.0
        1991 7 0.0
        1991 8 0.0
        1991 9 0.0
        1991 10 0.0

The regression spec file is a text file containing the regression spec that uses the user-defined regression varaiables generated by Genhol. This file has a .reg extension and is created only when requested. Below is an example of the contents of a regression spec file.

    regression{
        user=(aNewHoliday)
        file="newholiday.dat"
        format="datevalue"
        # start=1990.1
        usertype=holiday
    }

To open a file of either of these types, select the file name in the list and click on the open button below the list or simply double click on the file name. By default these files will be opened with the text editor included with Win Genhol. You can open these text files with the text editor of your choice by selecting File -> File View Settings from the menu or pressing Ctrl + S to open the File View Settings Box, unchecking the Use default viewer box and specifying the executable of the text editor you would like to use.

5. Creating New Input Files

A Genhol input file contains two types of specs, one global spec and one or more holiday specs. The global spec specifies global options and appears first in the input file. The holiday specs give information about each holiday regressor including the name of the file that contains the dates of the holiday and the length of the holiday window.

To create a new Genhol input file, select File - > Create Input File from the menu or press Ctrl + I. This will open the Global Spec window.

Global Spec Window

Global Spec Arguments

  • Save spec as: The full path and filename (with extension) of the location you would like to save the input file.
  • Save regressor as: The filename (with extension) where the holiday regression matrix will be stored.
  • Number of holidays: The number of holidays to be created. The default is 1.
  • Period: The period of the holiday regressor. Choose 12 to create a regressor for a monthly time series, 6 for a bimonthly series and 4 for a quarterly series. The default is 12.
  • Type: The type of holiday regressor that will be produced. For "count", the number of days found in a holiday window for a given observation is output. For "ratio", the proportion of the holiday window occuring in a given observation is output. The default is ratio.
  • Save output spec as: The filename (with extension) where the regression spec will be stored.
  • First year: A four-digit year that will be the first year saved in the output file. The default is the first year common to all data files supplied by the infile argument for each holiday spec. This argument is optional.
  • Last year: A four-digit year that will be the last year saved in the output file. The default is the last year common to all data files supplied by the infile argument for each holiday spec. This argument is optional
  • First mean year: A four-digit year that denotes the first year used in the calculation of the means of the holiday regressors. This argument is optional.
  • Last mean year: A four-digit year that denotes the last year used in the calculation of the means of the holiday regressors. This argument is optional.
  • Stock day: The stock day for an inventory series, that is, the day of the month when inventory is taken. This option should only be set when creating holiday regressors for stock series.

After selecting the global spec options, press the Next button to move to the Holiday Spec window. The Holiday Spec window has a tab for each holiday to be created as specified in the global spec.

Holiday Spec Arguments

  • Holiday dates file: The full path and filename (with extension) of a text file containing the holiday dates. The holiday dates must be stored in month day year format. See the Genhol Examples for an example.
  • Holiday name: The name of the holiday. The holiday name cannot contain spaces, and must be less than 17 characters long. The names entered for each holiday must be unique.
  • Center: Specifies the removal of the sample mean or the seasonal means from the user-defined regression variables. For center = mean, the overall mean(sample mean)of the user-defined regressor is subtracted from the regressor. For center = calendar, the mean of each calendar month, bimonth or quarter (depending on the period selected) is subtracted from the user-defined regressor. When center=none, the regressor is not modified.
  • Zero before: A four-digit year before which the user-defined regressor equals zero.
  • Zero after: A four-digit year after which the user-defined regressor equals zero.
  • Holiday effect details: Use the drop down boxes in this section to choose when the holiday effect occurs. Use the check boxes to activate the drop down boxes for the three possible holiday effect windows, before, during, or after the holiday. You can select more than one holiday effect window for each holiday. All of the holiday windows are inclusive.

Press the Back button to return to the Global Spec window. Press the Create spec button to create the Genhol input file with the selected parameters. This will display the newly created Genhol input file and return to the Win Genhol main screen.

Example 1: Generating an Easter holiday regressor

This example will use Win Genhol to create a user-defined regressor for Easter from 1990 to 2015. This file will have values very close to those of the default regressor generated by X-13ARIMA-SEATS for Easter with a window length of 8 (easter[8]).

First set the options for the global spec including the name of output files to be saved, the first and last years of the regressor, the period, the number of holidays and the type of the regressor. Many of these options are the default values supplied by Win Genhol.

Next set the options for the holiday spec including the holiday dates file, the type of centering (calendar), and the holiday effect window (8 days before the holiday to 1 day before).

Win Genhol creates the following input file.

    global{
        numhol = 1
        outfile = "easter8.dat"
        outspec = "easter8.reg"
        first = 1990
        last = 2015
        period = 12
    }
    holiday1{
        name = easter8
        begbefore = -8
        endbefore = -1
        infile = "easter500.txt"
        center = calendar
    }

Note that the dates of Easter holiday is provided in the file easter500.txt. The first 15 lines of the file are given below:

    4       2       1600
    4       22     1601
    4       7       1602
    3       30     1603
    4       18     1604
    4       10     1605
    3       26     1606
    4       15     1607
    4       6       1608
    4       19     1609
    4       11     1610
    4       3       1611
    4       22     1612
    4       7       1613
    3       30     1614
    4       19     1615

To create the Easter8 regressor, simply select Easter8.inp from the list of input files and press the Run Genhol button or just double click on Easter8.inp.

This will generate one holiday regressor for the Easter holiday, stored in easter8.dat. The regression variable is stored in X-13ARIMA-SEATS's datevalue format; the first 18 lines of the file are given below:

    1990       1        0.0
    1990       2        0.0
    1990       3        -0.382
    1990       4        0.382
    1990       5        0.0
    1990       6        0.0
    1990       7        0.0
    1990       8        0.0
    1990       9        0.0
    1990       10      0.0
    1990       11      0.0
    1990       12      0.0
    1991       1        0.0
    1991       2        0.0
    1991       3        0.618
    1991       4        -0.618
    1991       5        0.0
    1991       6        0.0

X-13ARIMA-SEATS commands to incorporate these regressors into a regARIMA model will also be stored into a file named easter8.reg. The contents of this file are given below:

    regression{
        user=(
                Beforeeaster8
        )
        file="easter8.dat"
        format="datevalue"
        # start=1990.1
        usertype=holiday
    }

Example 2: Generating a 2-part Easter holiday regressor

Zhang, McLaren, and Leung (2003) developed an alternate Easter regressor for Australian series at the Australian Bureau of Statistics (henceforth ABS). Their model consisted of two regressors, one which modeled an assumed increase in the level of the series before Good Friday, and another to handle the period between Good Friday and Easter Monday, a national holiday in Australia, where a decrease in level is expected.

This example will show how to create user-defined regressors for the ABS Easter regressor. Start with a global spec and name the input file abseaster.inp. The two output files will automatically be named abseaster as well.

Next set the options for the holiday spec for the two part easter regressor by selecting the easter dates file again and then identifying the two holiday effect windows. The first window is from 8 days before Easter to 3 days before Easter and the second window is from 2 days before Easter (Good Friday) to 1 day after Easter (Easter Monday).

A sample input file (abseaster.inp) is given below:

    global{
            numhol = 1
            outfile = "abseaster.dat"
            outspec = "abseaster.reg"
            first = 1990
            last = 2015
            period = 12
    }
    holiday1{
            name = abseaster
            begbefore = -8
            endbefore = -3
            begafter = 2
            infile = "easter500.txt"
            center = calendar
    }

To run this file, select abseaster.inp from the Genhol Input Files list and press the Run Genhol button.

This will generate two (2) holiday regressors in the file abseaster.dat - a regressor for the period before Good Friday, and another regressor for the period between Good Friday and Easter Monday, inclusive.

X-13ARIMA-SEATS commands to incorporate these regressors into a regARIMA model will also be stored as a file named abseaster.reg. The contents of this file are given below:

    regression{
        user=(
                Beforeabseaster Betweenabseaster
        )
        file="abseaster.dat"
        format="datevalue"
        # start=1990.1
        usertype=holiday
    }

Example 3: Generating a stock Easter holiday regressor

This utility uses the method outlined in Findley (2009) to generate stock holiday regressors. To generate an end-of-month stock Easter regressor approximately like that specified in X-13ARIMA-SEATS as easterstock[8] (see Monsell (2009) for more details), an input file like the following is needed:

    global{
            numhol = 1
            outfile = "stockeaster8.dat"
            outspec = "stockeaster8.reg"
            first = 1990
            last = 2015
            period = 12
            stockday = 31
    }
    holiday1{
            name = stockeaster8
            begbefore = -8
            endbefore = -1
            infile = "easter500.txt"
            center = calendar
    }

To create this input file with Win Genhol, identify the names of the input and output files and first and last year as before, but now check the Stock series box and set the Stock day box to 31.

The holiday spec is the same as the first example, we just change the name of the regressor to stockeaster8.

To generate a stock Easter regressor for another sample day, such as the 28th day of the month, select 28 from the Stock day drop down box in the Global Spec window.

Example 4: Generating a set of regressors for more than one holiday

This example will create a file containing user-defined regressors for Chinese New Year and Idul Fitri, an Islamic holiday that marks the end of Ramadan. For this example, both the Chinese New Year holiday effect and the Idul Fitri holiday effect will be comprised of three parts each for a total of 6 regressors.

For the Global Spec, name the input file "indhol" and change the number of holidays to two.

Notice that the Holiday Spec window now has two tabs. In the first tab set up the Chinese New Year regressors. Here we will define the three part Chinese New Year effect over three windows:

  • 10 days before to the holiday to 1 day before
  • the day of the holiday to 4 days after the holiday
  • 5 days after the holiday to 14 days after.

In the second tab set up the Idul Fitri regressors. Since Idul Fitri moves through all of the months, we set the centering to "Mean". All of the holidays we have looked at so far have had centering set to "Calendar" because they can only occur in a couple of months. The three part Idul Fitri effect for this example consists of the following three effect windows

  • 42 days before the holiday to 21 days before
  • 20 days before the holiday to the day of the holiday
  • 1 day after the holiday to 7 days after the holiday.

These options will create the input file (indhol.inp) given below:

    global{
            numhol = 2
            outfile = "indhol.dat"
            outspec = "indhol.reg"
            period = 12
            type = ratio
    }
    holiday1{
            name = CNY
            begbefore = -10
            endbefore = -1
            begafter = 5
            endafter = 14
            infile = "cnyInd.dat"
            center = calendar
    }
    holiday2{
            name = IdulFitri
            begbefore = -42
            endbefore = -21
            begafter = 1
            endafter = 7
            infile = "IFHolInd.dat"
            center = mean
    }

This will generate six (6) holiday regressors in the file indhol.reg - three Chinese New Year regressors (for before, after and intermediate holiday effects), and Idul Fitri regressors (for before, after and intermediate holiday effects). X-13ARIMA-SEATS commands to incorporate these regressors into a regARIMA model will be stored as a file named indhol.reg. The contents of this file are given below:

    regression{
        user=(
                BeforeCNY         BetweenCNY         AfterCNY
                BeforeIdulFitri         BetweenIdulFitri         AfterIdulFitri
        )
        file="indhol.dat"
        format="datevalue"
        # start=1970.1
        usertype=holiday
    }

7. Contact Information

Demetra Lytras
U.S. Census Bureau
Email: demetra.p.lytras@census.gov
Phone: (301) 763-7426

8. References

Findley, D. F. (2009), Stock Series Holiday Regressors Generated By Flow Series Holiday Regressors, Center for Statistical Research and Methodology Research Report Series (Statistics No. 2009-04). U.S. Census Bureau [Online]. Available: https://www.census.gov/content/dam/Census/library/working-papers/2009/adrm/rrs2009-04.pdf.

Monsell, B. C. (2009), Update on the Development of X-13ARIMA-SEATS, JSM Proceedings, Business and Economic Statistics Section. Alexandria, VA: American Statistical Association. Available: https://www.census.gov/content/dam/Census/library/working-papers/2009/adrm/jsm09bcm.pdf.

U.S. Census Bureau (2020). Genhol Documentation.

U.S. Census Bureau (2020). X-13ARIMA-SEATS Reference Manual.

Zhang, X., McLaren, C. H., and Leung, C. C. S. (2003), An Easter proximity effect: Modelling and adjustment, Australian and New Zealand Journal of Statistics, 43, 269-280.

Top

Back to Header