menu
Markets

RelativeDates

RelativeDates are objects which provide utilities for getting dates given a relative date rule. Some rules require a business day calendar.

Get a Date Relative from Today

Getting a Python date object from a RelativeDate object is simple:

from gs_quant.datetime.relative_date import RelativeDate

my_date: date = RelativeDate('-1d').apply_rule()
print(my_date)  # Previous day

Get a Date Relative from a Base Date

Getting a date from a different base date rather than today can also be accomplished by specifying a base_date.

from datetime import date, timedelta
from gs_quant.datetime.relative_date import RelativeDate

yesterday = date.today() - timedelta(days=1)
my_date = RelativeDate('-1d', base_date=yesterday).apply_rule()
print(my_date) # 2 days ago

Get a Date Relative using Pricing Context

Similarly than using base_date you can also use a GS Quant Pricing Context to set a base date:

from datetime import date
from datetime import timedelta
from gs_quant.datetime.relative_date import RelativeDate
from gs_quant.markets import PricingContext

yesterday = date.today() - timedelta(days=1)
with PricingContext(pricing_date=yesterday):
    my_date = RelativeDate('-1d').apply_rule()
print(my_date) # 2 days ago

Get a Date Using a Business Day Calendar

info

Note

Internal users should initialize a GS Quant session to automatically use holiday calendars. External users must pass their own holiday calendar for rules that use business date logic using the `holiday_calendar` keyword argument.

Some RelativeDate options require a business day calendar to calculate the date. Pass in the exchanges and/or currencies for the calendar you wish to use for business day logic.

from gs_quant.target.common import Currency
from gs_quant.datetime.relative_date import RelativeDate
from gs_quant.markets.securities import ExchangeCode
from gs_quant.session import GsSession, Environment

# external users should substitute their client id and secret
GsSession.use(Environment.PROD, client_id=None, client_secret=None, scopes=('read_product_data'))

date_a = RelativeDate('-1b').apply_rule(exchanges=[ExchangeCode.NYSE])  # Previous business day base on NYSE calendar
date_b = RelativeDate('-1b').apply_rule(currencies=[Currency.BRL])  # Previous business day base on BRL Currency
print(date_a, date_b)

Chaining RelativeDate Rules

For more advanced rules, you can chain them together using the + or -. + means add the relative value and - means substract the relative value.

from datetime import date

from gs_quant.datetime.relative_date import RelativeDate
from gs_quant.markets.securities import ExchangeCode
from gs_quant.session import GsSession, Environment


# external users should substitute their client id and secret
GsSession.use(Environment.PROD, client_id=None, client_secret=None, scopes=('read_product_data'))

# Four business days after the first business day on or after the 15th calendar day of the month
my_date = RelativeDate('J+14d+0u+4u').apply_rule(exchanges=[ExchangeCode.NYSE])
print(my_date)

Passing Your Own Holiday Calendar

Users can use their own holiday calendar by simply passing the calendar to the holiday_calendar keyword argument. This is required for external users for any rule that requires business date logic.

from datetime import date

from gs_quant.datetime.relative_date import RelativeDate

holiday_calendar = [date(2020, 12, 15)]
my_date: date = RelativeDate('-1b', base_date=date(2020, 12, 16)).apply_rule(holiday_calendar=holiday_calendar)
print(my_date)  # Returns 2020-12-14 since we specified 2020-12-15 was a holiday.

Relative String Options

Below is an overview of the various relative date rules supported at the moment.

Relative Date String FormatDescription
AFirst day of a relative year
bRelative business days with implied USD holiday calendar as well as the given exchange or currency holidays. If no calendar is given, only "0" days specified in the weekmask are treated as holidays
dRelative days
eEnd of the month ignoring any relative value
JFirst Julian day of month ignoring relative value
M,T,W,R,F,V,Znth Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday of month respectively
gRelative weeks, without USD holiday calendar
N,U,X,S,G,I,PRelative nth Monday, Tuesday, Wednesday, Thursday, Friday, Saturday, and Sunday respectively
kRelative years without implicit USD calendar
rRelative end of year
uRelative business days without implicit USD holidays
vRelative month getting the last business day of the month without implicit USD holiday calendar
wRelative weeks applying specified holiday calenders
xEnd of the month ignoring holidays
yRelative years with the result moved to the next week day if the day falls on a weekend specified by the weekmask