Business Calendars, Schedules and Periods

Business calendars are used in Deephaven to state when a business entity is operational (or not), including the hours, days and years of regular operations, as well as holidays.

For example, one of the business calendars installed with Deephaven presents temporal information pertaining to the New York Stock Exchange (NYSE), which is open Monday through Friday, from 9:30 a.m. to 4 p.m. Eastern time. The calendar also includes information about the exchange's nine full-day holidays and its partial holidays, which vary from year to year.

A collection of 12 business calendars are included when Deephaven is installed. However, you can also create and install your own custom Business Calendar.

Creating Custom Business Calendars

Business calendars are stored in files that use XML formatting to specify the aspects of the calendar, including the timezone, hours and days of the week the business is operational, as well as holidays.

The root element of the XML file is <calendar>, and there are four children elements.

<name> is the name of the business calendar (required)
<timeZone> provides the time zone used for the calendar (required)
<default> provides information about regular hours and days the business is and is not operational
<holiday> provides information about individual holidays (special days/times for which the business is non-operational)

name

In the following example, "Colorado" is the name of the calendar:

<name>Colorado</name>

timeZone

The timeZone element provides the timezone used for the calendar in Deephaven. For our example calendar, TZ_MT is the timezone used (U.S. Mountain Time), as shown below.

default

There are two components included in the default element.

businessPeriod - provides the hours of the day that business operations are conducted. The values listed are the opening time and closing time separated by a comma, using a 24-hour clock in the timezone noted in the timeZone element. Note: More than one businessPeriod can be included in the default element. For example, if a business closes regularly for lunch, there could be two businessPeriod components in the default element - one for the period before lunch and one for the period after lunch.
weekend - provides the day of the week that business operations are not operational. Each weekend day is presented individually. This is an optional component. If there are no weekends included in the default element, Deephaven will assume the business is operational seven days per week. For our example calendar, we will assume that business in Colorado is operational from 9 a.m. to 6 p.m., Monday through Friday, as shown below:

<default>
    <businessPeriod>09:00,18:00</businessPeriod>
    <weekend>Saturday</weekend>
    <weekend>Sunday</weekend>
</default>

holiday

There are two components included in the holiday element.

date - provides the year, month and date of the holiday in the format YYYYMMDD. Each individual holiday must be presented by itself, including a separate record for each year in which it is celebrated. If date is not included in the holiday element, Deephaven will assume there are no holidays.
businessPeriod - provides the hours of the day that business operations are conducted. The values listed are the starting time and ending time separated by a comma, using a 24-hour clock in the timezone noted above. If business operations are closed for the entire day, this element is not required.

For our example calendar, we will assume Colorado has full-day holidays for Zebulon Pike's birthday on January 5, Colorado Gold Rush Day on July 11, the anniversary of Colorado statehood on August 1 and Stephen Long's birthday on December 30. We will also specify a partial holiday for Dr. Edwin James' birthday on August 27. These holidays (as celebrated in 2017) are shown below:

The entire XML file for a Business Calendar named "Colorado" follows:

Installing Custom Business Calendars

Once a new custom Business Calendar is saved with the .calendar suffix, your system administrator will need to install the file(s) to the Deephaven server(s). Instructions for the system administrator are included in the Installing Custom Calendars and Custom Plotting Themes.

Business Calendar Methods

As shown below, there are many methods specific to Business Calendars that are available to help users obtain information about the times and dates in which a business operates.

Note: Just like Calendar methods, the Business Calendar methods that take no date parameter act on the current date, e.g., nextBusinessDay(5) is equivalent to nextBusinessDay(currentDay(), 5).

In addition to the Business Calendar methods there are also methods for Business Schedules and Business Periods.

Method	Description
businessDaysInRange(DBDateTime start, DBDateTime end) businessDaysInRange(java.lang.String start, java.lang.String end)	Returns the business days between start and end, inclusive.
diffBusinessDay(DBDateTime start, DBDateTime end)	Returns the amount of business time in standard business days between start and end.
diffBusinessNanos(DBDateTime start, DBDateTime end)	Returns the amount of business time in nanoseconds between start and end.
diffBusinessYear(DBDateTime start, DBDateTime end)	Returns the number of business years between start and end.
diffNonBusinessDay(DBDateTime start, DBDateTime end)	Returns the amount of non-business time in standard business days between start and end.
diffNonBusinessNanos(DBDateTime start, DBDateTime end)	Returns the amount of non-business time in nanoseconds between start and end.
fractionOfBusinessDayComplete(DBDateTime time)	Returns the fraction of the business day complete by the given time.
fractionOfBusinessDayRemaining(DBDateTime time)	Returns the fraction of the business day remaining after the given time.
fractionOfStandardBusinessDay(DBDateTime time) fractionOfStandardBusinessDay(java.lang.String date)	For the given date, returns the ratio of the business day length and the standard business day length.
`getBusinessSchedule(DBDateTime time)` `getBusinessSchedule(String date)` `getBusinessSchedule(LocalDate date)`	Gets the indicated business schedule.
isBusinessDay(DBDateTime time)	Does time occur on a business day?
isBusinessDay() isBusinessDay(java.time.LocalDate date) isBusinessDay(java.lang.String date)	Is the date a business day?
isBusinessTime(DBDateTime time)	Determines if the specified time is a business time.
isLastBusinessDayOfMonth() isLastBusinessDayOfMonth(DBDateTime time) isLastBusinessDayOfMonth(java.lang.String date)	Is the time listed the last day of the month, and is there time left in the business day?
isLastBusinessDayOfWeek() isLastBusinessDayOfWeek(DBDateTime time) isLastBusinessDayOfWeek(java.lang.String date)	Is the time listed the last day of the week, and is there time left in the business day?
nextBusinessDay() nextBusinessDay(DBDateTime time) nextBusinessDay(java.lang.String date)	Gets the next business day.
nextBusinessDay(int n) nextBusinessDay(DBDateTime time, int n) nextBusinessDay(java.lang.String date, int n)	Gets the next business date that is `n` business days after input time.
nextBusinessSchedule() nextBusinessSchedule(DBDateTime time) nextBusinessSchedule(java.lang.String date)	Gets the next business schedule. A business schedule is both the date and the hours the business is open on that date.
nextBusinessSchedule(int n) nextBusinessSchedule(DBDateTime time, int n) nextBusinessSchedule(java.lang.String date, int n)	Gets the next business schedule that is `n` business days before input time.
nextNonBusinessDay() nextNonBusinessDay(DBDateTime time) nextNonBusinessDay(java.lang.String date)	Gets the next non-business day.
nextNonBusinessDay(int n) nextNonBusinessDay(DBDateTime time, int n) nextNonBusinessDay(java.lang.String date, int n)	Gets the next non-business date that is `n` non-business days after input time.
nonBusinessDaysInRange(DBDateTime start, DBDateTime end) nonBusinessDaysInRange(java.lang.String start, java.lang.String end)	Returns the non-business days between start and end, inclusive.
numberOfBusinessDays(DBDateTime start, DBDateTime end) numberOfBusinessDays(java.lang.String start, java.lang.String end) numberOfBusinessDays(DBDateTime start, DBDateTime end, boolean endInclusive) numberOfBusinessDays(java.lang.String start, java.lang.String end, boolean endInclusive)	Returns the number of business days between start and end.
numberOfNonBusinessDays(DBDateTime start, DBDateTime end) numberOfNonBusinessDays(DBDateTime start, DBDateTime end, boolean endInclusive) numberOfNonBusinessDays(java.lang.String start, java.lang.String end) numberOfNonBusinessDays(java.lang.String start, java.lang.String end, boolean endInclusive)	Returns the number of non-business days between start and end.
previousBusinessDay() previousBusinessDay(DBDateTime time) previousBusinessDay(java.lang.String date)	Gets the previous business day.
previousBusinessDay(int n) previousBusinessDay(DBDateTime time, int n) previousBusinessDay(java.lang.String date, int n)	Gets the next business date that is `n` business days before input time.
previousBusinessSchedule() previousBusinessSchedule(DBDateTime time) previousBusinessSchedule(java.lang.String date)	Gets the previous business schedule.
previousBusinessSchedule(int n) previousBusinessSchedule(DBDateTime time, int n) previousBusinessSchedule(java.lang.String date, int n)	Gets the next business schedule that is `n` business days before input time.
previousNonBusinessDay() previousNonBusinessDay(DBDateTime time) previousNonBusinessDay(java.lang.String date)	Gets the previous non-business day.
previousNonBusinessDay(int n) previousNonBusinessDay(DBDateTime time, int n) previousNonBusinessDay(java.lang.String date, int n)	Gets the next non-business date that is `n` non-business days before input time.
standardBusinessDayLengthNanos()	Returns the length of a standard business day in nanoseconds.

Business Schedule Methods

A Business Schedule is the collection of periods within a 24-hour day when a business is open. Business Schedules may have multiple periods. If a business is open continuously from 8 a.m. to 9 p.m., it would be open for one period. However, if the business is closed daily for lunch, it would have two periods.

For example, on August 21, 2017, using the USNYSE calendar, the BusinessSchedule would look like this:

2017-08-21 9:30 NY to 2017-08-21 16:00 NY

Method	Description
getBusinessPeriods()	Gets the business periods for the day.
getSOBD() getStartOfBusinessDay()	Gets the starting time of the business day.
getEOBD() getEndOfBusinessDay()	Gets the end time of the business day.
getLOBD() getLengthOfBusinessDay()	Gets the length of the business day in nanoseconds. If the business day has multiple periods, only the time during the periods is counted.
isBusinessDay()	Is this day a business day? Returns true if yes; false otherwise.
isBusinessTime(final DBDateTime time)	Determines if the specified time is a business time for the day. Returns true if yes; false otherwise.
businessTimeElapsed(final DBDateTime time)	Returns the amount of business time in nanoseconds that has elapsed on the given day by the specified time.

Business Period Methods

A Business Period is a continuous block of time in which the business is open. Available methods give the start, end, and length of a Business Period, as well as whether a time occurs during the period.

Method	Description
getStartTime()	Returns the start of the period.
getEndTime()	Returns the end of the period.
getLength()	Returns the length of the period in nanoseconds.
contains(final DBDateTime time)	Determines if the specified time is within the business period.

Last Updated: 16 February 2021 18:07 -04:00 UTC Deephaven v.1.20200928 (See other versions)