Utilizing pandas_market_calendars for Efficient Financial Data Analysis

pandas_market_calendars is a Python library that provides you insights into trading markets. This blog covers several aspects of the pandas_market_calendars library.

About pandas_market_calendars

It is a part of the Zipline package of Quantopian. It is totally centered on users in the finance field. Users can utilize this library for the following purposes :

Generate date ranges
Identify holidays
Calculate the number of trading days between two dates.
Details about exchanges and OTC markets

Syntax

Let us have a look at the syntax of pandas_market_calendars

pip install pandas_market_calendars

Using the following statement, you can start using this library:

import pandas_market_calendars as mcal

Recommended Reading | How to Use Robinhood API in Python

Installation with anaconda

To install this library with Anaconda, use the given command. Any of these two will help you out.

conda install -c conda-forge pandas_market_calendars
conda install -c "conda-forge/label/cf202003" pandas_market_calendars

Uses

Other use cases of this library include:

Finance
Time series analysis
Generation of a sequence of data
Creation of custom holiday calendars

Dependencies

The dependencies of pandas_market_calendars are of two types: direct and indirect. It is suggested to check all these dependencies while you are installing this library. The 4 direct dependencies are:

exchange-calendars
pandas
python-dateutil
pytz

The 6 indirect dependencies are:

korean-lunar-calendar
numpy
pyluach
six
toolz
tzdata

Working

Let us now get to know how we can make use of this fantastic package.

import pandas_market_calendars as mcal

# Get a calendar for the New York Stock Exchange (NYSE)
nyse = mcal.get_calendar('NYSE')

# Get a list of all available calendars
print(mcal.get_calendar_names())

# Check if a date is a market holiday
print(nyse.is_holiday('2023-10-23'))

# Get the next business day after a given date
print(nyse.next_open_after('2023-10-23'))

# Generate a range of business dates between two dates
print(mcal.date_range('2023-10-23', '2023-11-03', calendar='NYSE'))

Output

['ASX', 'BATS', 'CME', 'EUREX', 'FXCM', 'GLOBEX', 'HKEX', 'ICE', 'LSE', 'NASDAQ', 'NKY', 'NYSE', 'NYSEARCA', 'OTC', 'SGX', 'SSE', 'TSX'] False 2023-10-24 DatetimeIndex(['2023-10-24', '2023-10-25', '2023-10-26', '2023-10-27', '2023-10-30', '2023-10-31', '2023-11-01', '2023-11-02'], dtype='datetime64[ns]', freq='B')

Regular market times

The regular_market_times function displays if the markets are open for trading or not. This way, one can initialize past data or know about future happenings. regular_market_times is an attribute of the calendar object only.

import pandas_market_calendars as mcal

# Get a calendar for the New York Stock Exchange (NYSE)
nyse = mcal.get_calendar('NYSE')

# Get the regular market times for the NYSE
print(nyse.regular_market_times)

# Get the regular market times for a specific date
print(nyse.schedule('2023-10-24', include_times=True))

Output

{‘market_open’: ((None, time(9, 30)), (‘1902-03-04’, time(9, 30))), ‘market_close’: ((None, time(16, 0)), (‘1901-02-03’, time(16, 0)))} [(‘2023-10-24 09:30:00’, ‘2023-10-24 16:00:00’)]

Data Range with pandas_market_calendars

After obtaining the calendar, you can get to know the specific dates when the market will stay open. This output will make you aware of the days open for trading, basically. The date_range function of pandas_market_calendars aids the user in obtaining this range of dates.

import pandas_market_calendars as mcal

# Get the NYSE calendar
nyse_calendar = mcal.get_calendar('NYSE')

# Get a date range for the next month
next_month = nyse_calendar.date_range('2023-11-01', '2023-11-30')

# Print the date range
print(next_month)

The Output will be:

DatetimeIndex(['2023-11-01', '2023-11-02', '2023-11-03', '2023-11-06',
               '2023-11-07', '2023-11-08', '2023-11-09', '2023-11-10',
               '2023-11-13', '2023-11-14', '2023-11-15', '2023-11-16',
               '2023-11-17', '2023-11-20', '2023-11-21', '2023-11-22',
               '2023-11-27', '2023-11-28', '2023-11-29'],
              dtype='datetime64[ns]', freq='D')

Market Holidays

Now, once you have got access to a calendar of your choice, you may want to know the days when there’s a market holiday or any other form of market closure for that matter. For this purpose, pandas_market_calendars has the holidays function. Here, you just need to state the dates as parameters of the function and you will understand the holidays this market has for the dates you have provided.

# Get the US Federal Reserve calendar
us_federal_reserve_calendar = mcal.get_calendar('USFederalReserve')

# Get a list of all holidays and other market closures in the next month
holidays = us_federal_reserve_calendar.holidays('2023-11-01', '2023-11-30')

# Print the list of holidays
print(holidays)

So the Output for this calendar is:

['Thanksgiving Day']

Count of trading days

Python’s pandas_market_calendars has the feature of letting an investor know the number of trading days. Count of trading days provides an integer format of the total trading days between two dates that the user needs to state. It is really useful for people who pre-plan the trading revenue, keeping such factors in mind.

# Get the NYSE calendar
nyse_calendar = mcal.get_calendar('NYSE')

# Calculate the number of trading days between 2023-11-01 and 2023-11-30
num_trading_days = nyse_calendar.business_days('2023-11-01', '2023-11-30')

# Print the number of trading days
print(num_trading_days)

Output:

The date limit with pandas_market_calendars

The pandas_market_calendars provides you the option of knowing date limit of a particular market. The data limit for the market can be due to the following reasons:

the market might be discontinued
the company may be acquired
the data provider no longer provides support for that particular security or exchange.

The start_date and end_date help a user in knowing the date limit. Have a look at the following code to understand its usage.

import pandas_market_calendars as mcal

nyse_calendar = mcal.get_calendar('NYSE')

start_date = nyse_calendar.start_date
end_date = nyse_calendar.end_date

print('Start date:', start_date)
print('End date:', end_date)

So in the Output you will get the date when this calendar started functioning and till when it will be functional. The output will be in this format:

Start date: 1875-05-17 00:00:00
End date: 2203-12-31 00:00:00

You can use the extend() function to know of trading days beyond your date limit, but there is no guarantee of factually correct information. It is better to check for dates that are provided by the calendar for the given time range. However, if you still wish to know it’s working, here it is.

import pandas_market_calendars as mcal

nyse_calendar = mcal.get_calendar('NYSE')

next_year = nyse_calendar.extend('2024-01-01', '2024-12-31')

print('Next year:', next_year)

The Output will have dates beyond the range.

Next year: DatetimeIndex(['2023-12-31', '2024-01-01', '2024-01-02', '2024-01-03', '2024-01-04', '2024-01-05', '2024-01-06', '2024-01-07', '2024-01-08', '2024-01-09', '2024-01-10', '2024-01-11', '2024-01-12', '2024-01-13', '2024-01-14', '2024-01-15', '2024-01-16', '2024-01-17', '2024-01-18', '2024-01-19', '2024-01-20', '2024-01-21', '2024-01-22', '2024-01-23', '2024-01-24', '2024-01-25', '2024-01-26', '2024-01-27', '2024-01-28', '2024-01-29', '2024-01-30', '2024-01-31', '2024-02-01'], dtype='datetime64[ns]', freq='D')

Setting timezones

If you want to set a particular timezone with pandas_market_calendars, you are free to use any of the two methhods:

timezone argument of the schedule() method
timezone attribute of the market calendar object

Using `timezone` argument of the `schedule()` method

The working is extremely easy to understand. You can use the given code. The schedule() method has the the timezone argument. This argument accepts your specific timezone as the argument. In case you don’t provide a timezone, you will get the output in UTC format.

import pandas_market_calendars as mcal
import pytz

nyse_calendar = mcal.get_calendar('NYSE')
pacific_timezone = pytz.timezone('America/Los_Angeles')

# Get the market open and close times for the NYSE in PT
nyse_business_days = nyse_calendar.schedule(timezone=pacific_timezone)

print(nyse_business_days)

As you can see the Output has the trading dates along with market open and close times.

   market_open  market_close
2023-10-31     06:30:00     13:00:00
2023-11-01     06:30:00     13:00:00
2023-11-02     06:30:00     13:00:00
...

Using the `timezone` the attribute of the market calendar object

With this method, you can work in different time zones. It can provide you with the open and closing timings of the market. It has fewer function calls as compared to the schedule() method. So, for example, if you are working on the NYSE calendar and wish to set the timezone to Pacific Time, you can go through the following code:

import pandas_market_calendars as mcal
import pytz

nyse_calendar = mcal.get_calendar('NYSE')
pacific_timezone = pytz.timezone('America/Los_Angeles')

# Set the default timezone for the NYSE calendar to Pacific Time
nyse_calendar.timezone = pacific_timezone

# Get the market open and close times for the NYSE
nyse_business_days = nyse_calendar.schedule()

print(nyse_business_days)

The Output will be in this format:

   market_open  market_close
2023-10-31     06:30:00     13:00:00
2023-11-01     06:30:00     13:00:00
2023-11-02     06:30:00     13:00:00
...

Next trading date using pandas_market_calendars

The pandas_market_calendars library provides users with two methods to get the next trading date. These are:

next_trading_day() method
next_trading_days() method

`next_trading_day()` method

Let’s observe the working of the next_trading_day() method. It generates the next trading date. It is used when you want just one date for trading with reference to the current date.

import pandas_market_calendars as mcal

# Get the NYSE calendar
nyse_calendar = mcal.get_calendar('NYSE')

# Get the current date
current_date = pd.to_datetime('2023-10-31')

# Get the next trading day
next_trading_day = nyse_calendar.next_trading_day(current_date)

# Print the next trading day
print(next_trading_day)

So the Output will be like this:

2023-11-01

`next_trading_days()` method

This function is useful when you want multiple dates when the market will be up for trading. It generates the next n trading dates. Here, n a have any value as per your choice. You may set the value of n as per your convenience.

import pandas_market_calendars as mcal

# Get the NYSE calendar
nyse_calendar = mcal.get_calendar('NYSE')

# Get the current date
current_date = pd.to_datetime('2023-10-31')

# Get the next 5 trading days
next_5_trading_days = nyse_calendar.next_trading_days(current_date, n=5)

# Print the next 5 trading days
print(next_5_trading_days)

You will get an Output similar to this:

Index(['2023-11-01', '2023-11-02', '2023-11-03', '2023-11-06',
       '2023-11-07'], dtype='datetime64[ns]')

Trading schedule in pandas_market_calendars

In order to gauge the trading schedule, you have another function of pandas_market_calendars, which is called the schedule() method. Here, you need to input the start date along with the end date. The method will fetch all trading days within this start date and end date. Now, if you are working on the NYSE calendar and want to know the trading schedule for the month of November 2023, you can get help from this code:

import pandas_market_calendars as mcal

# Get the NYSE calendar
nyse_calendar = mcal.get_calendar('NYSE')

# Get the trading schedule for the month of November 2023
trading_schedule = nyse_calendar.schedule(start_date='2023-11-01', end_date='2023-11-30')

# Print the trading schedule
print(trading_schedule)

So you will get to know the open and close time of the chosen market along with the dates of given month in this format. The Output is :

   market_open  market_close
2023-11-01     06:30:00     13:00:00
2023-11-02     06:30:00     13:00:00
2023-11-03     06:30:00     13:00:00
2023-11-06     06:30:00     13:00:00
2023-11-07     06:30:00     13:00:00
2023-11-08     06:30:00     13:00:00
2023-11-09     06:30:00     13:00:00
2023-11-10     06:30:00     13:00:00
2023-11-13     06:30:00     13:00:00
2023-11-14     06:30:00     13:00:00
2023-11-15     06:30:00     13:00:00
2023-11-16     06:30:00     13:00:00
2023-11-17     06:30:00     13:00:00
2023-11-20     06:30:00     13:00:00
2023-11-21     06:30:00     13:00:00
2023-11-22     06:30:00     13:00:00
2023-11-27     06:30:00     13:00:00
2023-11-28     06:30:00     13:00:00
2023-11-29     06:30:00     13:00:00

FAQs on pandas_market_calendars

What are the benefits of using pandas_market_calendars?

Accuracy, Flexibility, and ease of use are its top benefits.

How can I get the trading hours for a specific stock exchange using pandas_market_calendars?

To get the trading hours for a specific exchange, you first need to import pandas_market_calendars and then create an instance of the desired exchange calendar. For example, to get the New York Stock Exchange (NYSE) calendar, you would use get_calendar('NYSE'). You can then use methods like schedule() to get detailed trading hours and dates for your specified period.