Sources API

High-level functions for fetching OHLCV time series data and structured datasets.

Overview

The chronos_lab.sources module provides unified interfaces for fetching data from:

• Yahoo Finance: Free market data via yfinance
• Intrinio: Institutional-quality financial data (requires API subscription)
• Interactive Brokers: Real-time and historical market data (requires IB Gateway/TWS)
• ArcticDB: Retrieve previously stored time series data
• Datasets: Load structured data (portfolios, watchlists, security metadata)

All functions return data in consistent formats with UTC timezone-aware timestamps.

Time Series Functions

chronos_lab.sources.ohlcv_from_yfinance

ohlcv_from_yfinance(*, symbols: List[str], period: Optional[str] = None, start_date: Optional[str | datetime] = None, end_date: Optional[str | datetime] = None, interval: Optional[str] = '1d', output_dict: Optional[bool] = False, **kwargs) -> Dict[str, pd.DataFrame] | pd.DataFrame | None

Download OHLCV data from Yahoo Finance.

Fetches historical or intraday price data for multiple symbols using the yfinance library. Data is returned with UTC timezone-aware timestamps in a consistent format suitable for analysis or storage.

Parameters:

Name	Type	Description	Default
symbols	List[str]	List of ticker symbols to download (max 100 symbols per call).	required
period	Optional[str]	Relative time period (e.g., '1d', '5d', '1mo', '3mo', '1y', 'max'). Mutually exclusive with start_date/end_date.	None
start_date	Optional[str | datetime]	Start date as 'YYYY-MM-DD' string or datetime object (inclusive). Mutually exclusive with period.	None
end_date	Optional[str | datetime]	End date as 'YYYY-MM-DD' string or datetime object (exclusive). Defaults to current time if start_date is provided without end_date.	None
interval	Optional[str]	Data frequency interval. Options include: - Intraday: '1m', '2m', '5m', '15m', '30m', '60m', '90m', '1h' - Daily+: '1d', '5d', '1wk', '1mo', '3mo' Defaults to '1d' (daily).	'1d'
output_dict	Optional[bool]	If True, returns dict mapping symbols to DataFrames. If False, returns single MultiIndex DataFrame with (date, symbol) levels. Defaults to False.	False
**kwargs		Additional keyword arguments passed to yfinance.download().	{}

Returns:

Type	Description
Dict[str, DataFrame] | DataFrame | None	If output_dict=True: Dictionary mapping symbol strings to DataFrames, where each DataFrame has DatetimeIndex and columns ['open', 'high', 'low', 'close', 'volume', 'symbol', 'interval' (intraday only)].
Dict[str, DataFrame] | DataFrame | None	If output_dict=False: Single DataFrame with MultiIndex (date, symbol) and same columns.
Dict[str, DataFrame] | DataFrame | None	Returns None if no data could be retrieved or on error.

Raises:

Type	Description
None	Errors are logged but not raised. Check return value for None.

Examples:

Basic daily data fetch: >>> prices = ohlcv_from_yfinance( ... symbols=['AAPL', 'MSFT', 'GOOGL'], ... period='1y' ... ) >>> print(prices.head()) >>> # Returns MultiIndex DataFrame with (date, symbol) levels

Fetch specific date range: >>> prices = ohlcv_from_yfinance( ... symbols=['AAPL', 'MSFT'], ... start_date='2024-01-01', ... end_date='2024-12-31', ... interval='1d' ... )

Get 5-minute intraday bars: >>> intraday = ohlcv_from_yfinance( ... symbols=['SPY', 'QQQ'], ... period='1d', ... interval='5m' ... ) >>> # Includes 'interval' column for intraday data

Get data as dictionary by symbol: >>> prices_dict = ohlcv_from_yfinance( ... symbols=['AAPL', 'MSFT'], ... period='6mo', ... output_dict=True ... ) >>> aapl_df = prices_dict['AAPL'] >>> # Work with individual symbol DataFrames

Note

• Yahoo Finance has rate limits; avoid excessive requests
• Intraday data availability is limited (typically last 7-60 days depending on interval)
• Max 100 symbols per call to avoid timeout issues
• All timestamps are converted to UTC timezone

chronos_lab.sources.ohlcv_from_intrinio

ohlcv_from_intrinio(*, symbols: List[str], period: Optional[str] = None, start_date: Optional[str | datetime] = None, end_date: Optional[str | datetime] = None, interval: Optional[Literal['1m', '5m', '10m', '15m', '30m', '60m', '1h', 'daily', 'weekly', 'monthly', 'quarterly', 'yearly']] = 'daily', api_key: Optional[str] = None, output_dict: Optional[bool] = False, **kwargs) -> Dict[str, pd.DataFrame] | pd.DataFrame | None

Download OHLCV data from Intrinio API.

Fetches institutional-quality historical or intraday price data using the Intrinio financial data platform. Requires an active Intrinio API subscription. Data is returned with UTC timezone-aware timestamps in a consistent format.

Parameters:

Name	Type	Description	Default
symbols	List[str]	List of security identifiers (ticker symbols, CUSIPs, or Intrinio IDs).	required
period	Optional[str]	Relative time period (e.g., '1d', '5d', '1mo', '1y'). Mutually exclusive with start_date/end_date.	None
start_date	Optional[str | datetime]	Start date as 'YYYY-MM-DD' string or datetime object (inclusive). Mutually exclusive with period.	None
end_date	Optional[str | datetime]	End date as 'YYYY-MM-DD' string or datetime object (exclusive). Defaults to current time if start_date is provided without end_date.	None
interval	Optional[Literal['1m', '5m', '10m', '15m', '30m', '60m', '1h', 'daily', 'weekly', 'monthly', 'quarterly', 'yearly']]	Data frequency interval. Options: - Intraday: '1m', '5m', '10m', '15m', '30m', '60m', '1h' - Historical: 'daily', 'weekly', 'monthly', 'quarterly', 'yearly' Defaults to 'daily'.	'daily'
api_key	Optional[str]	Intrinio API key. If None, reads from INTRINIO_API_KEY in ~/.chronos_lab/.env configuration file.	None
output_dict	Optional[bool]	If True, returns dict mapping symbols to DataFrames. If False, returns single MultiIndex DataFrame with (date, id) levels. Defaults to False.	False
**kwargs		Additional keyword arguments passed to Intrinio SDK (e.g., frequency, sort_order).	{}

Returns:

Type	Description
Dict[str, DataFrame] | DataFrame | None	If output_dict=True: Dictionary mapping ticker symbols to DataFrames, where each DataFrame has DatetimeIndex and columns ['id', 'open', 'high', 'low', 'close', 'volume', 'interval' (intraday only), 'symbol' (if ticker differs from id)].
Dict[str, DataFrame] | DataFrame | None	If output_dict=False: Single DataFrame with MultiIndex (date, id) and same columns.
Dict[str, DataFrame] | DataFrame | None	Returns None if no data could be retrieved or on error.

Raises:

Type	Description
None	Errors are logged but not raised. Check return value for None.

Examples:

Fetch daily data with API key: >>> prices = ohlcv_from_intrinio( ... symbols=['AAPL', 'MSFT'], ... start_date='2024-01-01', ... interval='daily', ... api_key='your_api_key_here' ... ) >>> # Returns MultiIndex DataFrame with (date, id) levels

Fetch data using configuration file: >>> # First set INTRINIO_API_KEY in ~/.chronos_lab/.env >>> prices = ohlcv_from_intrinio( ... symbols=['AAPL', 'MSFT'], ... period='1y', ... interval='daily' ... )

Get intraday 5-minute bars: >>> intraday = ohlcv_from_intrinio( ... symbols=['SPY'], ... start_date='2024-01-15', ... end_date='2024-01-16', ... interval='5m' ... ) >>> # Includes 'interval' column for intraday data

Get data as dictionary by symbol: >>> prices_dict = ohlcv_from_intrinio( ... symbols=['AAPL', 'MSFT', 'GOOGL'], ... period='3mo', ... interval='daily', ... output_dict=True ... ) >>> aapl_df = prices_dict['AAPL']

Note

• Requires active Intrinio subscription with appropriate data access
• API rate limits apply based on subscription tier
• Intraday data availability depends on subscription level
• All timestamps are converted to UTC timezone
• Symbol identifiers can be tickers, CUSIPs, or Intrinio composite IDs

chronos_lab.sources.ohlcv_from_ib

ohlcv_from_ib(*, symbols: Optional[List[str]] = None, contracts: Optional[List] = None, period: Optional[str] = None, start_date: Optional[str | datetime | date] = None, end_date: Optional[str | datetime | date] = None, interval: Optional[str] = '1d', what_to_show: Optional[str] = 'ADJUSTED_LAST', use_rth: Optional[bool] = True, output_dict: Optional[bool] = False) -> Dict[str, pd.DataFrame] | pd.DataFrame | None

Download OHLCV data from Interactive Brokers (synchronous version).

Fetches historical price data for multiple symbols or contracts using the Interactive Brokers API via ib_async. Automatically calculates IB API parameters and handles contract qualification. This is the synchronous version - use ohlcv_from_ib_async for async contexts with better performance for multiple symbols.

Two mutually exclusive modes for specifying the data window

Period mode: Relative lookback from now (e.g., '1d', '7d', '1mo', '1y') Datetime range mode: Absolute start date (and optional end date)

Parameters:

Name	Type	Description	Default
symbols	Optional[List[str]]	List of ticker symbols to download. Mutually exclusive with contracts. If provided, contracts are created and qualified automatically.	None
contracts	Optional[List]	List of ib_async Contract objects. Mutually exclusive with symbols.	None
period	Optional[str]	Chronos-lab period string (e.g., '1d', '7d', '1mo', '1y'). Used as a relative lookback from now. Mutually exclusive with start_date/end_date.	None
start_date	Optional[str | datetime | date]	Absolute start date as 'YYYY-MM-DD' string, datetime, or date object (inclusive). If provided, duration is calculated from this date to now (or to end_date if specified). Mutually exclusive with period.	None
end_date	Optional[str | datetime | date]	End date as 'YYYY-MM-DD' string, datetime, or date object (exclusive). Only used in datetime range mode with start_date. Defaults to current UTC time if start_date provided without end_date. Cannot be used with what_to_show='ADJUSTED_LAST'.	None
interval	Optional[str]	Chronos-lab interval string. Options include: - Seconds: '1s', '5s', '10s', '15s', '30s' - Minutes: '1m', '2m', '3m', '5m', '10m', '15m', '20m', '30m' - Hours: '1h', '2h', '3h', '4h', '8h' - Days: '1d' - Weeks: '1w', '1wk' - Months: '1mo' Defaults to '1d' (daily). Mapped to IB bar size via map_interval_to_barsize().	'1d'
what_to_show	Optional[str]	IB data type string. Options: - 'ADJUSTED_LAST': Split/dividend adjusted (default, no end_date allowed) - 'TRADES': Actual traded prices - 'MIDPOINT': Bid/ask midpoint - 'BID', 'ASK', 'BID_ASK': Bid, ask, or both	'ADJUSTED_LAST'
use_rth	Optional[bool]	If True (default), return only Regular Trading Hours data. If False, include extended hours.	True
output_dict	Optional[bool]	If True, returns dict mapping symbols to DataFrames. If False (default), returns single MultiIndex DataFrame with (date, symbol) levels.	False

Returns:

Type	Description
Dict[str, DataFrame] | DataFrame | None	If output_dict=True: Dictionary mapping symbol strings to DataFrames, where each DataFrame has DatetimeIndex and columns ['open', 'high', 'low', 'close', 'volume', 'symbol', 'conId'].
Dict[str, DataFrame] | DataFrame | None	If output_dict=False: Single DataFrame with MultiIndex (date, symbol) and same columns.
Dict[str, DataFrame] | DataFrame | None	Returns None if no data could be retrieved or on error.

Raises:

Type	Description
None	Errors are logged but not raised. Check return value for None.

Examples:

Fetch using period (relative lookback): >>> from chronos_lab.sources import ohlcv_from_ib >>> >>> prices = ohlcv_from_ib( ... symbols=['AAPL', 'MSFT'], ... period='1mo', ... interval='1d' ... ) >>> # Returns last 1 month of daily data

Fetch using absolute start date: >>> prices = ohlcv_from_ib( ... symbols=['AAPL', 'MSFT'], ... start_date='2024-01-01', ... interval='1d', ... what_to_show='TRADES' ... ) >>> # Returns data from 2024-01-01 to now

Fetch with date range and as dictionary: >>> prices = ohlcv_from_ib( ... symbols=['AAPL', 'MSFT', 'GOOGL'], ... start_date='2024-01-01', ... end_date='2024-12-31', ... interval='1d', ... what_to_show='TRADES', ... output_dict=True ... ) >>> aapl_df = prices['AAPL']

Fetch intraday data: >>> intraday = ohlcv_from_ib( ... symbols=['SPY'], ... period='1d', ... interval='5m', ... what_to_show='TRADES' ... )

Note

• Requires active IB Gateway/TWS connection (configured in ~/.chronos_lab/.env)
• Uses calculate_ib_params() to convert period/dates to IB API parameters
• Either period OR start_date must be provided (mutually exclusive)
• For datetime ranges spanning >= 365 days with daily+ bars, may overfetch due to IB API year-based duration constraints. Results are automatically filtered to the requested date range.
• All timestamps are UTC timezone-aware
• Creates and qualifies contracts automatically if symbols provided
• For async version with concurrent requests, use ohlcv_from_ib_async()

chronos_lab.sources.ohlcv_from_ib_async async

ohlcv_from_ib_async(*, symbols: Optional[List[str]] = None, contracts: Optional[List] = None, period: Optional[str] = None, start_date: Optional[str | datetime | date] = None, end_date: Optional[str | datetime | date] = None, interval: Optional[str] = '1d', what_to_show: Optional[str] = 'ADJUSTED_LAST', use_rth: Optional[bool] = True, output_dict: Optional[bool] = False) -> Dict[str, pd.DataFrame] | pd.DataFrame | None

Download OHLCV data from Interactive Brokers (asynchronous version).

Asynchronous version of ohlcv_from_ib. Fetches historical price data for multiple symbols or contracts using the Interactive Brokers API with concurrent requests for better performance. Automatically calculates IB API parameters and handles contract qualification asynchronously.

Two mutually exclusive modes for specifying the data window

Period mode: Relative lookback from now (e.g., '1d', '7d', '1mo', '1y') Datetime range mode: Absolute start date (and optional end date)

Parameters:

Name	Type	Description	Default
symbols	Optional[List[str]]	List of ticker symbols to download. Mutually exclusive with contracts. If provided, contracts are created and qualified asynchronously for better performance.	None
contracts	Optional[List]	List of ib_async Contract objects. Mutually exclusive with symbols.	None
period	Optional[str]	Chronos-lab period string (e.g., '1d', '7d', '1mo', '1y'). Used as a relative lookback from now. Mutually exclusive with start_date/end_date.	None
start_date	Optional[str | datetime | date]	Absolute start date as 'YYYY-MM-DD' string, datetime, or date object (inclusive). If provided, duration is calculated from this date to now (or to end_date if specified). Mutually exclusive with period.	None
end_date	Optional[str | datetime | date]	End date as 'YYYY-MM-DD' string, datetime, or date object (exclusive). Only used in datetime range mode with start_date. Defaults to current UTC time if start_date provided without end_date. Cannot be used with what_to_show='ADJUSTED_LAST'.	None
interval	Optional[str]	Chronos-lab interval string. Options include: - Seconds: '1s', '5s', '10s', '15s', '30s' - Minutes: '1m', '2m', '3m', '5m', '10m', '15m', '20m', '30m' - Hours: '1h', '2h', '3h', '4h', '8h' - Days: '1d' - Weeks: '1w', '1wk' - Months: '1mo' Defaults to '1d' (daily). Mapped to IB bar size via map_interval_to_barsize().	'1d'
what_to_show	Optional[str]	IB data type string. Options: - 'ADJUSTED_LAST': Split/dividend adjusted (default, no end_date allowed) - 'TRADES': Actual traded prices - 'MIDPOINT': Bid/ask midpoint - 'BID', 'ASK', 'BID_ASK': Bid, ask, or both	'ADJUSTED_LAST'
use_rth	Optional[bool]	If True (default), return only Regular Trading Hours data. If False, include extended hours.	True
output_dict	Optional[bool]	If True, returns dict mapping symbols to DataFrames. If False (default), returns single MultiIndex DataFrame with (date, symbol) levels.	False

Returns:

Type	Description
Dict[str, DataFrame] | DataFrame | None	If output_dict=True: Dictionary mapping symbol strings to DataFrames, where each DataFrame has DatetimeIndex and columns ['open', 'high', 'low', 'close', 'volume', 'symbol', 'conId'].
Dict[str, DataFrame] | DataFrame | None	If output_dict=False: Single DataFrame with MultiIndex (date, symbol) and same columns.
Dict[str, DataFrame] | DataFrame | None	Returns None if no data could be retrieved or on error.

Raises:

Type	Description
None	Errors are logged but not raised. Check return value for None.

Examples:

Fetch using period (relative lookback): >>> import asyncio >>> from chronos_lab.sources import ohlcv_from_ib_async >>> >>> prices = asyncio.run(ohlcv_from_ib_async( ... symbols=['AAPL', 'MSFT', 'GOOGL', 'AMZN'], ... period='1mo', ... interval='1d' ... )) >>> # Fetches data for all symbols concurrently

Fetch using absolute start date: >>> prices = asyncio.run(ohlcv_from_ib_async( ... symbols=['AAPL', 'MSFT'], ... start_date='2024-01-01', ... interval='1d', ... what_to_show='TRADES' ... )) >>> # Returns data from 2024-01-01 to now

Fetch with date range and as dictionary: >>> prices = asyncio.run(ohlcv_from_ib_async( ... symbols=['AAPL', 'MSFT', 'GOOGL'], ... start_date='2024-01-01', ... end_date='2024-12-31', ... interval='1d', ... what_to_show='TRADES', ... output_dict=True ... )) >>> aapl_df = prices['AAPL']

Fetch intraday data: >>> intraday = asyncio.run(ohlcv_from_ib_async( ... symbols=['SPY', 'QQQ', 'IWM'], ... period='1d', ... interval='5m', ... what_to_show='TRADES' ... ))

Note

• Requires active IB Gateway/TWS connection (configured in ~/.chronos_lab/.env)
• Uses asyncio.TaskGroup for concurrent contract qualification and data fetching
• Concurrency controlled by IB_HISTORICAL_DATA_CONCURRENCY setting (default: 10)
• Uses calculate_ib_params() to convert period/dates to IB API parameters
• Either period OR start_date must be provided (mutually exclusive)
• For datetime ranges spanning >= 365 days with daily+ bars, may overfetch due to IB API year-based duration constraints. Results are automatically filtered to the requested date range.
• All timestamps are UTC timezone-aware
• Creates and qualifies contracts asynchronously if symbols provided
• For synchronous version, use ohlcv_from_ib()

chronos_lab.sources.ohlcv_from_arcticdb

ohlcv_from_arcticdb(symbols: List[str], start_date: Optional[Union[str, Timestamp]] = None, end_date: Optional[Union[str, Timestamp]] = None, period: Optional[str] = None, columns: Optional[List[str]] = None, backend: Optional[str] = None, library_name: Optional[str] = None, pivot: bool = False, group_by: Optional[Literal['column', 'symbol']] = 'column') -> Optional[pd.DataFrame]

Retrieve historical or intraday OHLCV data from ArcticDB storage.

Queries previously stored time series data from ArcticDB with flexible date filtering and output formatting options. Supports both long format (MultiIndex) and wide format (pivoted) for different analysis workflows.

Parameters:

Name	Type	Description	Default
symbols	List[str]	List of ticker symbols to retrieve (e.g., ['AAPL', 'MSFT', 'GOOGL']).	required
start_date	Optional[Union[str, Timestamp]]	Start date as 'YYYY-MM-DD' string or pd.Timestamp (inclusive). Mutually exclusive with period.	None
end_date	Optional[Union[str, Timestamp]]	End date as 'YYYY-MM-DD' string or pd.Timestamp (exclusive). Defaults to current UTC time if not specified.	None
period	Optional[str]	Relative time period (e.g., '5d', '3m', '1y'). Mutually exclusive with start_date/end_date.	None
columns	Optional[List[str]]	List of specific columns to retrieve (e.g., ['close', 'volume']). The 'symbol' column is always included automatically. If None, all columns are retrieved.	None
backend	Optional[str]	Storage backend type ('s3', 'lmdb', or 'mem', case-insensitive). If None, uses ARCTICDB_DEFAULT_BACKEND from ~/.chronos_lab/.env configuration. Overrides the default backend setting for this operation.	None
library_name	Optional[str]	ArcticDB library name to query. If None, uses ARCTICDB_DEFAULT_LIBRARY_NAME from ~/.chronos_lab/.env configuration.	None
pivot	bool	If True, reshape to wide format with symbols as columns. If False (default), return long format with MultiIndex (date, symbol).	False
group_by	Optional[Literal['column', 'symbol']]	When pivot=True, controls column ordering in MultiIndex: - 'column' (default): Creates (column, symbol) ordering (e.g., close_AAPL, close_MSFT) - 'symbol': Creates (symbol, column) ordering (e.g., AAPL_close, AAPL_high)	'column'

Returns:

Type	Description
Optional[DataFrame]	If pivot=False: DataFrame with MultiIndex (date, symbol) and columns ['open', 'high', 'low', 'close', 'volume', ...].
Optional[DataFrame]	If pivot=True: DataFrame with DatetimeIndex and MultiIndex columns organized by group_by parameter.
Optional[DataFrame]	Returns None if no data found, invalid parameters, or on error.

Raises:

Type	Description
None	Errors are logged but not raised. Check return value for None.

Examples:

Basic retrieval with relative period: >>> from chronos_lab.sources import ohlcv_from_arcticdb >>> >>> # Retrieve from default backend >>> prices = ohlcv_from_arcticdb( ... symbols=['AAPL', 'MSFT', 'GOOGL'], ... period='3m', ... library_name='yfinance' ... ) >>> print(prices.head()) >>> # Returns MultiIndex (date, symbol) DataFrame

Specify exact date range: >>> prices = ohlcv_from_arcticdb( ... symbols=['AAPL', 'MSFT'], ... start_date='2024-01-01', ... end_date='2024-12-31', ... library_name='yfinance' ... )

Retrieve from specific backend: >>> # Retrieve from S3 backend explicitly >>> prices = ohlcv_from_arcticdb( ... symbols=['AAPL', 'MSFT'], ... period='1y', ... backend='s3', ... library_name='yfinance' ... ) >>> >>> # Retrieve from local LMDB backend explicitly >>> prices = ohlcv_from_arcticdb( ... symbols=['AAPL', 'MSFT'], ... period='1y', ... backend='lmdb', ... library_name='yfinance' ... )

Retrieve only specific columns: >>> closes = ohlcv_from_arcticdb( ... symbols=['AAPL', 'MSFT', 'GOOGL'], ... period='1y', ... columns=['close'], ... library_name='yfinance' ... ) >>> # Returns only 'close' and 'symbol' columns

Pivot to wide format for correlation analysis: >>> wide_prices = ohlcv_from_arcticdb( ... symbols=['AAPL', 'MSFT', 'GOOGL', 'AMZN'], ... period='1y', ... columns=['close'], ... library_name='yfinance', ... pivot=True, ... group_by='column' ... ) >>> # Creates columns: close_AAPL, close_MSFT, etc. >>> returns = wide_prices.pct_change() >>> correlation_matrix = returns.corr()

Alternative pivot grouping by symbol: >>> wide_prices = ohlcv_from_arcticdb( ... symbols=['AAPL', 'MSFT'], ... period='6mo', ... pivot=True, ... group_by='symbol' ... ) >>> # Creates MultiIndex: (AAPL, close), (AAPL, high), (MSFT, close), etc.

Note

• Period strings: '7d' (days), '4w' (weeks), '3mo'/'3m' (months), '1y' (years)
• All timestamps are UTC timezone-aware
• Data must have been previously stored using ohlcv_to_arcticdb()
• Backend parameter allows querying different storage backends (S3, LMDB, MEM)
• Empty result returns None with warning logged

chronos_lab.sources.securities_from_intrinio

securities_from_intrinio(*, api_key: Optional[str] = None, composite_mic: str = 'USCOMP', codes: List[Literal['EQS', 'ETF', 'DR', 'PRF', 'WAR', 'RTS', 'UNT', 'CEF', 'ETN', 'ETC']] = ['EQS']) -> pd.DataFrame | None

Retrieve securities list from Intrinio API.

Parameters:

Name	Type	Description	Default
api_key	Optional[str]	Intrinio API key. If None, uses default from Intrinio class.	None
composite_mic	str	Composite MIC code for the exchange. Defaults to 'USCOMP'.	'USCOMP'
codes	List[Literal['EQS', 'ETF', 'DR', 'PRF', 'WAR', 'RTS', 'UNT', 'CEF', 'ETN', 'ETC']]	List of security type codes. Common codes include: - 'EQS': Equity Shares (common stocks) - 'ETF': Exchange Traded Funds - 'DR': Depository Receipts (ADRs, GDRs, etc.) - 'PRF': Preference Shares (preferred stock) - 'WAR': Warrants - 'RTS': Rights - 'UNT': Units - 'CEF': Closed-Ended Funds - 'ETN': Exchange Traded Notes - 'ETC': Exchange Traded Commodities Defaults to ['EQS'] if None.	['EQS']

Returns:

Type	Description
DataFrame | None	DataFrame with securities indexed by 'id', or None on error.

Dataset Functions

chronos_lab.sources.from_dataset

from_dataset(*, dataset_name: str, output_dict: Optional[bool] = False) -> Dict[str, pd.DataFrame] | pd.DataFrame | None

Retrieve a dataset from local JSON file or DynamoDB table.

Loads structured datasets stored locally or in DynamoDB. Returns data as either a pandas DataFrame (with automatic type inference) or as a dictionary.

Parameters:

Name	Type	Description	Default
dataset_name	str	Dataset identifier. Use 'ddb_' prefix for DynamoDB datasets, no prefix for local JSON files.	required
output_dict	Optional[bool]	If True, returns dictionary format. If False (default), returns pandas DataFrame with type inference.	False

Returns:

Type	Description
Dict[str, DataFrame] | DataFrame | None	If output_dict=False: pandas DataFrame with inferred datetime and numeric types
Dict[str, DataFrame] | DataFrame | None	If output_dict=True: Dictionary mapping keys to item attribute dicts
Dict[str, DataFrame] | DataFrame | None	Returns None on error.

Examples:

Load local dataset as DataFrame: >>> from chronos_lab.sources import from_dataset >>> >>> df = from_dataset(dataset_name='example') >>> print(df.head()) >>> print(df.dtypes)

Load DynamoDB dataset as DataFrame: >>> df = from_dataset(dataset_name='ddb_securities') >>> # Automatically infers datetime and numeric types

Load as dictionary: >>> data_dict = from_dataset( ... dataset_name='example', ... output_dict=True ... ) >>> for key, item in data_dict.items(): ... print(f"{key}: {item}")

Note

• Local datasets: Loaded from {DATASET_LOCAL_PATH}/{name}.json
• DynamoDB datasets: Require DATASET_DDB_TABLE_NAME and DATASET_DDB_MAP configuration
• DataFrame index is the dataset keys (local) or sort keys (DynamoDB)
• Datetime strings matching ISO format automatically converted to pandas datetime
• Numeric strings automatically converted to numeric types