Data Sources#

Data Source#

class lumibot.data_sources.data_source.DataSource(api_key: str | None = None, delay: int | None = None, tzinfo=None, **kwargs)#

Bases: ABC

DEFAULT_PYTZ = <DstTzInfo 'America/New_York' LMT-1 day, 19:04:00 STD>#
DEFAULT_TIMEZONE = 'America/New_York'#
IS_BACKTESTING_DATA_SOURCE = False#
MIN_TIMESTEP = 'minute'#
SOURCE = ''#
TIMESTEP_MAPPING = []#
calculate_greeks(asset, asset_price: float, underlying_price: float, risk_free_rate: float)#

Returns Greeks in backtesting.

static convert_timestep_str_to_timedelta(timestep)#

Convert a timestep string to a timedelta object. For example, “1minute” will be converted to a timedelta of 1 minute.

Parameters:

timestep (str) – The timestep string to convert. For example, “1minute” or “1hour” or “1day”.

Returns:

  • timedelta – A timedelta object representing the timestep.

  • unit (str) – The unit of the timestep. For example, “minute” or “hour” or “day”.

get_bars(assets, length, timestep='minute', timeshift=None, chunk_size=2, max_workers=2, quote=None, exchange=None, include_after_hours=True, sleep_time=0.1)#

Get bars for the list of assets

get_chain_full_info(asset: ~lumibot.entities.asset.Asset, expiry: ~datetime.date | ~datetime.datetime, chains=None, underlying_price=<class 'float'>, risk_free_rate=<class 'float'>, strike_min=None, strike_max=None) → DataFrame#

Get the full chain information for an option asset, including: greeks, bid/ask, open_interest, etc. For brokers that do not support this, greeks will be calculated locally. For brokers like Tradier this function is much faster as only a single API call can be done to return the data for all options simultaneously.

Parameters:

  • asset (Asset) – The option asset to get the chain information for.

  • expiry (datetime.date | datetime.datetime) – The expiry date of the option chain.

  • chains (dict) – The chains dictionary created by get_chains method. This is used to get the list of strikes needed to calculate the greeks.

  • underlying_price (float) – Price of the underlying asset.

  • risk_free_rate (float) – The risk-free rate used in interest calculations.

  • strike_min (float) – The minimum strike price to return in the chain. If None, will return all strikes. Providing this will speed up execution by limiting the number of strikes queried.

  • strike_max (float) – The maximum strike price to return in the chain. If None, will return all strikes. Providing this will speed up execution by limiting the number of strikes queried.

Returns:

A DataFrame containing the full chain information for the option asset. Greeks columns will be named as ‘greeks.delta’, ‘greeks.theta’, etc.

Return type:

pd.DataFrame

abstract get_chains(asset: Asset, quote: Asset = None) → dict#

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

  • asset (Asset) – The asset to get the option chains for

  • quote (Asset | None) – The quote asset to get the option chains for

Returns:

Mapping with keys such as Multiplier (e.g. "100") and Chains. Chains is a nested dictionary where expiration dates map to strike lists, e.g. chains['Chains']['CALL']['2023-07-31'] = [strike1, strike2, ...].

Return type:

dict

get_datetime(adjust_for_delay=False)#

Returns the current datetime in the default timezone

Parameters:

adjust_for_delay (bool) – Whether to adjust the current time for the delay. This is useful for paper trading data sources that provide delayed data.

Return type:

datetime

get_datetime_range(length, timestep='minute', timeshift=None)#
abstract get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True, return_polars=False) → Bars#

Get bars for a given asset, going back in time from now, getting length number of bars by timestep. For example, with a length of 10 and a timestep of “day”, and no timeshift, this would return the last 10 daily bars.

  • Higher-level method that returns a Bars object

  • Handles timezone conversions automatically

  • Includes additional metadata and processing

  • Preferred for strategy development and backtesting

  • Returns normalized data with consistent format across data sources

Parameters:

  • asset (Asset) – The asset to get the bars for.

  • length (int) – The number of bars to get.

  • timestep (str) – The timestep to get the bars at. Accepts “day” “hour” or “minute”.

  • timeshift (datetime.timedelta) – The amount of time to shift the bars by. For example, if you want the bars from 1 hour ago to now, you would set timeshift to 1 hour.

  • quote (Asset) – The quote asset to get the bars for.

  • exchange (str) – The exchange to get the bars for.

  • include_after_hours (bool) – Whether to include after hours data.

  • return_polars (bool) – If True, return Bars with Polars DataFrame for better performance. Default is False (returns pandas).

Returns:

The bars for the asset.

Return type:

Bars

get_last_day()#
get_last_minute()#
abstract get_last_price(asset, quote=None, exchange=None) → float | Decimal | None#

Takes an asset and returns the last known price

Parameters:

  • asset (Asset) – The asset to get the price of.

  • quote (Asset) – The quote asset to get the price of.

  • exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_last_prices(assets, quote=None, exchange=None)#

Takes a list of assets and returns the last known prices

get_quote(asset: Asset, quote: Asset = None, exchange: str = None) → Quote#

Get the latest quote for an asset (stock, option, or crypto). Returns a Quote object with bid, ask, last, and other fields if available.

Parameters:

  • asset (Asset object) – The asset for which the quote is needed.

  • quote (Asset object, optional) – The quote asset for cryptocurrency pairs.

  • exchange (str, optional) – The exchange to get the quote from.

Returns:

A Quote object with the quote information, eg. bid, ask, etc.

Return type:

Quote

get_round_day(timeshift=0)#

Returns the current datetime rounded to the day and applies a timeshift in days :param timeshift: The number of days to shift the datetime by :type timeshift: int

Returns:

Rounded datetime with the timeshift applied

Return type:

datetime

get_round_minute(timeshift=0)#

Returns the current datetime rounded to the minute and applies a timeshift in minutes :param timeshift: The number of minutes to shift the datetime by :type timeshift: int

Returns:

Rounded datetime with the timeshift applied

Return type:

datetime

get_strikes(asset) → list#

Return a set of strikes for a given asset

get_timestamp()#

Returns the current timestamp in the default timezone :rtype: float

get_timestep()#
get_yesterday_dividend(asset, quote=None)#

Return dividend per share for a given asset for the day before

get_yesterday_dividends(assets, quote=None)#

Return dividend per share for a list of assets for the day before

localize_datetime(dt)#
query_greeks(asset)#

Query for the Greeks as it can be more accurate than calculating locally.

to_default_timezone(dt)#

Pandas#

class lumibot.data_sources.pandas_data.PandasData(*args, pandas_data=None, auto_adjust=True, **kwargs)#

Bases: DataSourceBacktesting

PandasData is a Backtesting-only DataSource that uses a Pandas DataFrame (read from CSV) as the source of data for a backtest run. It is not possible to use this class to run a live trading strategy.

SOURCE = 'PANDAS'#
TIMESTEP_MAPPING = [{'representations': ['1D', 'day'], 'timestep': 'day'}, {'representations': ['1M', 'minute'], 'timestep': 'minute'}]#
clean_trading_times(dt_index, pcal)#

Fill gaps within trading days using the supplied market calendar.

Parameters:

  • dt_index (pandas.DatetimeIndex) – Original datetime index.

  • pcal (pandas.DataFrame) – Calendar with market_open and market_close columns indexed by date.

Returns:

Cleaned index with one-minute frequency during market hours.

Return type:

pandas.DatetimeIndex

find_asset_in_data_store(asset, quote=None)#
get_asset_by_name(name)#
get_asset_by_symbol(symbol, asset_type=None)#

Finds the assets that match the symbol. If type is specified finds the assets matching symbol and type.

Parameters:

  • symbol (str) – The symbol of the asset.

  • asset_type (str) – Asset type. One of: - stock - future - option - forex

Return type:

list of Asset

get_assets()#
get_chains(asset: Asset, quote: Asset = None, exchange: str = None)#

Returns option chains.

Obtains option chain information for the asset (stock) from each of the exchanges the options trade on and returns a dictionary for each exchange.

Parameters:

  • asset (Asset object) – The stock whose option chain is being fetched. Represented as an asset object.

  • quote (Asset object, optional) – The quote asset. Default is None.

  • exchange (str, optional) – The exchange to fetch the option chains from. For PandasData, will only use “SMART”.

Returns:

Mapping with keys such as Multiplier (e.g. "100") and Chains. Chains is a nested dictionary where expiration dates map to strike lists, e.g. chains['Chains']['CALL']['2023-07-31'] = [strike1, strike2, ...].

Return type:

dict

get_historical_prices(asset: Asset, length: int, timestep: str = None, timeshift: int = None, quote: Asset = None, exchange: str = None, include_after_hours: bool = True, return_polars: bool = False)#

Get bars for a given asset

get_last_price(asset, quote=None, exchange=None) → float | Decimal | None#

Takes an asset and returns the last known price

Parameters:

  • asset (Asset) – The asset to get the price of.

  • quote (Asset) – The quote asset to get the price of.

  • exchange (str) – The exchange to get the price of.

Returns:

The last known price of the asset.

Return type:

float or Decimal or None

get_last_prices(assets, quote=None, exchange=None, **kwargs)#

Takes a list of assets and returns the last known prices

get_quote(asset, quote=None, exchange=None) → Quote#

Get the latest quote for an asset. Returns a Quote object with bid, ask, last, and other fields if available.

Parameters:

  • asset (Asset object) – The asset for which the quote is needed.

  • quote (Asset object, optional) – The quote asset for cryptocurrency pairs.

  • exchange (str, optional) – The exchange to get the quote from.

Returns:

A Quote object with the quote information.

Return type:

Quote

get_start_datetime_and_ts_unit(length, timestep, start_dt=None, start_buffer=datetime.timedelta(days=5))#

Get the start datetime for the data.

Parameters:

  • length (int) – The number of data points to get.

  • timestep (str) – The timestep to use. For example, “1minute” or “1hour” or “1day”.

Returns:

  • datetime – The start datetime.

  • str – The timestep unit.

get_trading_days_pandas()#
get_yesterday_dividend(asset, quote=None)#

Return dividend per share for a given asset for the day before

get_yesterday_dividends(assets, quote=None)#

Return dividend per share for a list of assets for the day before

load_data()#
update_date_index()#

Yahoo#

class lumibot.data_sources.yahoo_data.YahooData(auto_adjust=False, datetime_start=None, datetime_end=None, **kwargs)#

Bases: DataSourceBacktesting

MIN_TIMESTEP = 'day'#
SOURCE = 'YAHOO'#
TIMESTEP_MAPPING = [{'representations': ['1d', 'day'], 'timestep': 'day'}, {'representations': ['15m', '15 minutes'], 'timestep': '15 minutes'}, {'representations': ['1m', '1 minute'], 'timestep': 'minute'}]#
get_chains(asset: Asset, quote: Asset = None, exchange: str = None)#

Get the chains for a given asset. This is not implemented for YahooData becuase Yahoo does not support historical options data.

yfinance module does support getting some of the info for current options chains, but it is not implemented. See yf methods: >>> import yfinance as yf >>> spy = yf.Ticker(“SPY”) >>> expirations = spy.options >>> chain_data = spy.option_chain()

get_historical_prices(asset, length, timestep='', timeshift=None, quote=None, exchange=None, include_after_hours=True)#

Get bars for a given asset

get_last_price(asset, timestep=None, quote=None, exchange=None, **kwargs) → float | Decimal | None#

Takes an asset and returns the last known price

get_strikes(asset)#

Return a set of strikes for a given asset

Module contents#