A Holiday Calendar For The Ops Team

A Trading and Settlement Calendar for US Equities

A reliable and easy-to-use holiday calendar (aka a trading & settlement calendar) is an invaluable tool in the arsenal of any ops professional — and this includes both technology operations as well as business ops folks. It’s one of those things you take for granted until you don’t have it.

We looked around and we didn’t see a scriptable command-line tool for this purpose, or really any resource that calculates settlement dates, so we made one. I mean, we didn’t quite make it ourselves — we’ve been known to reinvent the wheel every now and then (see message bus and security master), but that’s not the case here. We took an existing python package, added some settlement logic, and created an operations-focused holiday calendar wrapper.

This is a technical article about this tool. The python source code is available here, free for anyone to use or modify in any way they wish.

Background

For an operations team, especially one that relies on automation, there are a few questions that require a ready answer:

1. Is today a trading holiday?
   - Should we even start the trading system?
   - Should we run the usual end-of-day processes such as clearing, regulatory reporting, etc.?
2. Is today (or was yesterday) a settlement holiday?
   - Should we expect settlement of trades today?
   - Should we run the usual reconciliation processes?
3. What is the settlement date for today’s trades (or for a given trade date)?
   - Conversely, what is the earliest trade date for a given settlement date?
4. Is today a half-day (aka early trading close)?
   - Should we update the closing auction time and the corresponding cutoff times in reference data?
   - Should we be adjusting the volume curves and stats used for algorithmic trading?

We created a python script that can not only answer all of these questions but follows the common conventions of Linux tools (i.e. exit code 0 for yes, 1 for no) to allow usage in scripts.

Trading vs Settlement Holidays

The trading calendar, or more correctly, the trading holidays for US Equities for each year, are typically published on the NYSE website.

For settlement holidays, a useful reference is FINRA’s “Holiday Margin Extensions Schedule”, published annually, which includes all of the trading and settlement holidays. I wish they also published this information in a machine-readable format (e.g. CSV or JSON or XML). The main difference between the two calendars is that there are two bank holidays in the year when the markets are open but the DTCC does not provide settlement services:

• Columbus Day — 2nd Monday in Oct
• Veterans Day — Nov 11 (observed on Monday if it falls on a Sunday, but skipped if it falls on a Saturday)

As far as we know, there is no commonly available tool that provides a settlement calendar (except this, but we prefer a local tool with no dependencies for day-to-day operations).

The Tool

As mentioned before, we didn’t bother to build this thing from scratch, we use python’s exchange-calendars package for the most part. We also considered the pandas-market-calendars package, but we went with the former because it was a tiny bit faster to load at first use (although both are still super slow).

Once again, the source code is here:
https://github.com/prerak-proof/holiday_calendar

holiday_calendar/holiday_calendar.py at main · prerak-proof/holiday_calendar

Usage

$ python holiday_calendar.py --help
usage: holiday_calendar.py [-h] [--settlement | --trading] [--action {is_holiday,is_half_day,t_plus_n}] [DATE] [action_args [action_args ...]]
positional arguments:
  DATE                  Ref date
  action_args           any command args
                        (for t_plus_n, a series of date offsets that 
                         are successively applied to the ref date)
optional arguments:
  -h, --help            show this help message and exit
  --settlement          use settlement days (default: None)
  --trading             use trading days (default: None)
  --action {is_holiday,is_half_day,t_plus_n}
                        action to perform (default: is_holiday)
--settlement is implied when --action is t_plus_n

Use case: is today a holiday?

$ python holiday_calendar.py --action is_holiday
is_holiday() for 2022-03-30: False
$ echo $?   # exit code 1 indicates false
1
$ python calendar/holiday_calendar.py --action is_holiday 20220704
is_holiday() for 2022-07-04: True
$ echo $?   # exit code 0 indicates true
0

Note the exit code of the program when asking a yes/no question. This allows the tool to be scripted as:

$ # the exit code convention allows usage in bash if statements
$ if python holiday_calendar.py --action is_holiday 20220704; then
>     echo "Aborting system start as holiday detected..."
> fi
is_holiday() for 2022-07-04: True
Aborting system start as holiday detected...

Use case: is today a half-day?

# snippet from build_refdata.sh shell script
if python holiday_calendar.py --action is_half_day; then
    echo "Half day detected. Adjusting files..."
    # do stuff here for half day
fi

Use case: when do today’s trades settle?

$ # action t_plus_n automatically uses settlement calendar
$ python holiday_calendar.py --action t_plus_n 20220329 +2
20220331
$ # Note Columbus day holiday skipped on Oct 10 2022
$ python holiday_calendar.py --action t_plus_n 20221007 +2
20221012

Use case: when do the last trading day’s trades settle?

This is a two-part question: when was the last trading day and what is the T+2 settlement date for that trading day. Answering this question is helpful when verifying client affirms in DTCC on T+1.

$ # Note that t_plus_n action can take a series of integers. 
$ # action_args="-1 +2" will find T+2 for the date at T-1 of 7/1
$ # T = 7/1/22, T-1 = 6/30/22, T+2 of 6/30/22 = 7/5/22
$ python holiday_calendar.py --action t_plus_n 20220701 -1 +2
20220705

Use case: what is the earliest trade date for a given settlement date?

This is useful for position reconciliation. Did you know there are some settlement dates where trades from two different trading days settle?

$ # Note: trades for 10/7/22 and 10/10/22 both settle on 10/12/22
$ python holiday_calendar.py --action t_plus_n 20221012 -2
20221007

Closing Thoughts

Unlike my usual posts, this one is short and to the point. I hope this tool makes someone’s life a tiny bit easier, or at least it sparks some ideas. If you have thoughts or comments, please reach out to me on Twitter: @preraksanghvi.