finagg.fundam package

Submodules

finagg.fundam.feat module

Fundamental features aggregated from several sources.

class finagg.fundam.feat.IndustryFundamental

Bases: object

Methods for gathering industry-averaged fundamental data.

The class variable finagg.fundam.feat.Fundamental.industry is an instance of this feature set implementation and is the most popular interface for calling feature methods.

Examples

You can aggregate this feature set using a ticker or an industry code directly.

>>> df1 = finagg.fundam.feat.fundam.industry.from_refined(ticker="MSFT").head(5)
>>> df2 = finagg.fundam.feat.fundam.industry.from_refined(code=73).head(5)
>>> pd.testing.assert_frame_equal(df1, df2, rtol=1e-4)

classmethod from_refined(*, ticker: None | str = None, code: None | str = None, level: Literal[2, 3, 4] = 2, start: None | str = None, end: None | str = None, engine: None | Engine = None) → DataFrame

Get fundamental features from the feature store, aggregated for an entire industry.

The industry can be chosen according to a company or by an industry code directly. If a company is provided, then the first level digits of the company’s SIC code is used for the industry code.

Parameters:

• ticker – Company ticker. Lookup the industry associated with this company. Mutually exclusive with code.

• code – Industry SIC code to use for industry lookup. Mutually exclusive with ticker.

• level –

  Industry level to aggregate features at. The industry used according to ticker or code is subsampled according to this value. Options include:

  • 2 = major group (e.g., furniture and fixtures)

  • 3 = industry group (e.g., office furnitures)

  • 4 = industry (e.g., wood office furniture)

• start – The start date of the observation period. Defaults to the first recorded date.

• end – The end date of the observation period. Defaults to the last recorded date.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

Fundamental data dataframe with each feature as a separate column. Sorted by date.

Raises:

• ValueError – If neither a ticker nor code are provided.

• NoResultFound – If there are no rows for ticker or code in the refined SQL table.

Examples

>>> df = finagg.fundam.feat.fundam.industry.from_refined(ticker="AAPL").head(5)
>>> df["mean"]  
name        PriceBookRatio  PriceEarningsRatio
date
2010-01-29        1.213018           17.020706
2010-02-01        1.166246           16.364503
2010-02-02        1.213047           17.021558
2010-02-03        1.222630           17.156233
2010-02-04        1.213401           17.026466
>>> df["std"]  
name        PriceBookRatio  PriceEarningsRatio
date
2010-01-29        1.469641           20.667755
2010-02-01        1.414144           19.887156
2010-02-02        1.476001           20.756459
2010-02-03        1.490459           20.959443
2010-02-04        1.475500           20.749523

class finagg.fundam.feat.NormalizedFundamental

Bases: object

Fundamental features from quarterly and daily data, normalized according to industry averages and standard deviations.

The class variable finagg.fundam.feat.Fundamental.normalized is an instance of this feature set implementation and is the most popular interface for calling feature methods.

Examples

It doesn’t matter which data source you use to gather features. They all return equivalent dataframes.

>>> df1 = finagg.fundam.feat.fundam.normalized.from_other_refined("AAPL").head(5)
>>> df2 = finagg.fundam.feat.fundam.normalized.from_refined("AAPL").head(5)
>>> pd.testing.assert_frame_equal(df1, df2, rtol=1e-4)

classmethod from_other_refined(ticker: str, /, *, level: Literal[2, 3, 4] = 2, start: None | str = None, end: None | str = None, engine: None | Engine = None) → DataFrame

Get features from other feature SQL tables.

Parameters:

• ticker – Company ticker.

• level –

  Industry level to aggregate relative features at. The industry used according to ticker is subsampled according to this value. Options include:

  • 2 = major group (e.g., furniture and fixtures)

  • 3 = industry group (e.g., office furnitures)

  • 4 = industry (e.g., wood office furniture)

• start – The start date of the observation period. Defaults to the first recorded date.

• end – The end date of the observation period. Defaults to the last recorded date.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

Relative fundamental data dataframe with each feature as a separate column. Sorted by filing date.

Examples

>>> finagg.fundam.feat.fundam.normalized.from_other_refined("AAPL").head(5)  
            NORM(PriceBookRatio)  NORM(PriceEarningsRatio)
date
2010-01-25             -0.706266                 -0.706279
2010-01-26             -0.698805                 -0.698935
2010-01-27             -0.700699                 -0.700799
2010-01-28             -0.701446                 -0.701534
2010-01-29             -0.704558                 -0.704598

classmethod from_refined(ticker: str, /, *, start: None | str = None, end: None | str = None, engine: None | Engine = None) → DataFrame

Get features from the features SQL table.

This is the preferred method for accessing features for offline analysis (assuming data in the local SQL table is current).

Parameters:

• ticker – Company ticker.

• start – The start date of the observation period. Defaults to the first recorded date.

• end – The end date of the observation period. Defaults to the last recorded date.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

Fundamental data dataframe with each feature as a separate column. Sorted by date.

Raises:

NoResultFound – If there are no rows for ticker in the refined SQL table.

Examples

>>> finagg.fundam.feat.fundam.normalized.from_refined("AAPL").head(5)  
            NORM(PriceBookRatio)  NORM(PriceEarningsRatio)
date
2010-01-25             -0.706266                 -0.706279
2010-01-26             -0.698805                 -0.698935
2010-01-27             -0.700699                 -0.700799
2010-01-28             -0.701446                 -0.701534
2010-01-29             -0.704558                 -0.704598

classmethod get_candidate_ticker_set(lb: int = 1, *, start: None | str = None, end: None | str = None, engine: None | Engine = None) → set[str]

Get all unique tickers in the fundamental SQL table that MAY BE ELIGIBLE to be in the feature’s SQL table.

This is just an alias for finagg.fundam.feat.Fundamental.get_ticker_set().

Parameters:

• lb – Minimum number of rows required to include a ticker in the returned set.

• start – The start date of the observation period to include when searching for tickers. Defaults to the first recorded date.

• end – The end date of the observation period to include when searching for tickers. Defaults to the last recorded date.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

All unique tickers that may be valid for creating industry-normalized fundamental features that also have at least lb rows for each tag used for constructing the features.

Examples

>>> "AAPL" in finagg.fundam.feat.fundam.normalized.get_candidate_ticker_set()  
True

classmethod get_ticker_set(lb: int = 1, *, start: None | str = None, end: None | str = None, engine: None | Engine = None) → set[str]

Get all unique tickers in the feature’s SQL table.

Parameters:

• lb – Minimum number of rows required to include a ticker in the returned set.

• start – The start date of the observation period to include when searching for tickers. Defaults to the first recorded date.

• end – The end date of the observation period to include when searching for tickers. Defaults to the last recorded date.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

All unique tickers that contain all the columns for creating fundamental features that also have at least lb rows.

Examples

>>> "AAPL" in finagg.fundam.feat.fundam.normalized.get_ticker_set()  
True

classmethod get_tickers_sorted_by(column: str, /, *, ascending: bool = True, date: int | str = 0, engine: None | Engine = None) → list[str]

Get all tickers in the feature’s SQL table sorted by a particular column for a date.

Parameters:

• column – Feature column to sort by.

• ascending – Whether to return results in ascending order according to the values in column.

• date – Date to select from. Defaults to the most recent date with available data. If a string, should be in “%Y-%m-%d” format. If an integer, should be days before the current date (e.g, -2 indicates two days before today).

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

Tickers sorted by a feature column for a particular date.

Raises:

ValueError – If the integer date is positive.

Examples

>>> ts = finagg.fundam.feat.fundam.normalized.get_tickers_sorted_by(
...         "NORM(PriceEarningsRatio)",
...         date="2019-01-04"
... )
>>> "AMD" == ts[0]  
True

classmethod install(tickers: None | set[str] = None, *, processes: int = 3, engine: None | Engine = None, recreate_tables: bool = False) → int

Install data associated with tickers by pulling data from the refined SQL tables, transforming them into normalized features, and then writing to the refined normalized fundamental SQL table.

Tables associated with this method are created if they don’t already exist.

Parameters:

• tickers – Set of tickers to install features for. Defaults to all the tickers from finagg.fundam.feat.Fundamental.get_ticker_set().

• processes – Number of background processes to run in parallel when processing tickers.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

• recreate_tables – Whether to drop and recreate tables, wiping all previously installed data.

Returns:

Number of rows written to the feature’s SQL table.

classmethod to_refined(ticker: str, df: DataFrame, /, *, engine: None | Engine = None) → int

Write the dataframe to the feature store for ticker.

Parameters:

• ticker – Company ticker.

• df – Dataframe to store completely as rows in a local SQL table.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

Number of rows written to the SQL table.

Raises:

ValueError – If the given dataframe’s columns do not match this feature’s columns.

class finagg.fundam.feat.Fundamental

Bases: object

Method for gathering fundamental data on a stock using several sources.

The module variable finagg.fundam.feat.fundam is an instance of this feature set implementation and is the most popular interface for calling feature methods.

Examples

It doesn’t matter which data source you use to gather features. They all return equivalent dataframes.

>>> df1 = finagg.fundam.feat.fundam.from_api("AAPL").head(5)
>>> df2 = finagg.fundam.feat.fundam.from_raw("AAPL").head(5)
>>> df3 = finagg.fundam.feat.fundam.from_refined("AAPL").head(5)
>>> pd.testing.assert_frame_equal(df1, df2, rtol=1e-4)
>>> pd.testing.assert_frame_equal(df1, df3, rtol=1e-4)

industry

Fundamental features aggregated for an entire industry. The most popular way for accessing the IndustryFundamental feature set.

normalized

A company’s fundamental features normalized by its industry. The most popular way for accessing the NormalizedFundamental feature set.

classmethod from_api(ticker: str, /, *, start: None | str = None, end: None | str = None) → DataFrame

Get features directly from APIs.

Parameters:

• ticker – Company ticker.

• start – The start date of the observation period. Defaults to the first recorded date.

• end – The end date of the observation period. Defaults to the last recorded date.

Returns:

Combined quarterly and daily feature dataframe. Sorted by date.

Examples

>>> finagg.fundam.feat.fundam.from_api("AAPL").head(5)  
            PriceBookRatio  PriceEarningsRatio
date
2010-01-25        0.175061            2.423509
2010-01-26        0.178035            2.464677
2010-01-27        0.178813            2.475447
2010-01-28        0.177153            2.452471
2010-01-29        0.173825            2.406396

classmethod from_raw(ticker: str, /, *, start: None | str = None, end: None | str = None, engine: None | Engine = None) → DataFrame

Get features directly from other raw SQL tables.

Parameters:

• ticker – Company ticker.

• start – The start date of the observation period. Defaults to the first recorded date.

• end – The end date of the observation period. Defaults to the last recorded date.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

Combined quarterly and daily feature dataframe. Sorted by date.

Examples

>>> finagg.fundam.feat.fundam.from_raw("AAPL").head(5)  
            PriceBookRatio  PriceEarningsRatio
date
2010-01-25        0.175061            2.423509
2010-01-26        0.178035            2.464677
2010-01-27        0.178813            2.475447
2010-01-28        0.177153            2.452471
2010-01-29        0.173825            2.406396

classmethod from_refined(ticker: str, /, *, start: None | str = None, end: None | str = None, engine: None | Engine = None) → DataFrame

Get features from the feature-dedicated local SQL tables.

This is the preferred method for accessing features for offline analysis (assuming data in the local SQL tables is current).

Parameters:

• ticker – Company ticker.

• start – The start date of the observation period. Defaults to the first recorded date.

• end – The end date of the observation period. Defaults to the last recorded date.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

Combined quarterly and daily feature dataframe. Sorted by date.

Raises:

NoResultFound – If there are no rows for ticker in the refined SQL table.

Examples

>>> finagg.fundam.feat.fundam.from_refined("AAPL").head(5)  
            PriceBookRatio  PriceEarningsRatio
date
2010-01-25        0.175061            2.423509
2010-01-26        0.178035            2.464677
2010-01-27        0.178813            2.475447
2010-01-28        0.177153            2.452471
2010-01-29        0.173825            2.406396

classmethod get_candidate_ticker_set(lb: int = 1, *, start: None | str = None, end: None | str = None, engine: None | Engine = None) → set[str]

Get all unique tickers in the raw SQL table that MAY BE ELIGIBLE to be in the feature’s SQL table.

Parameters:

• lb – Minimum number of rows required to include a ticker in the returned set.

• start – The start date of the observation period to include when searching for tickers. Defaults to the first recorded date.

• end – The end date of the observation period to include when searching for tickers. Defaults to the last recorded date.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

All unique tickers that may be valid for both quarterly and daily features that also have at least lb rows used for constructing the features.

Examples

>>> "AAPL" in finagg.fundam.feat.fundam.get_candidate_ticker_set()  
True

classmethod get_ticker_set(lb: int = 1, *, start: None | str = None, end: None | str = None, engine: None | Engine = None) → set[str]

Get all unique tickers in the feature’s SQL table.

Parameters:

• lb – Minimum number of rows required to include a ticker in the returned set.

• start – The start date of the observation period to include when searching for tickers. Defaults to the first recorded date.

• end – The end date of the observation period to include when searching for tickers. Defaults to the last recorded date.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

All unique tickers that contain all the columns for creating fundamental features that also have at least lb rows.

Examples

>>> "AAPL" in finagg.fundam.feat.fundam.get_ticker_set()  
True

classmethod install(tickers: None | set[str] = None, *, processes: int = 3, engine: None | Engine = None, recreate_tables: bool = False) → int

Install data associated with tickers by pulling data from other refined SQL tables, transforming them into fundamental features, and then writing to the refined fundamental features SQL table.

Tables associated with this method are created if they don’t already exist.

Parameters:

• tickers – Set of tickers to install features for. Defaults to all the tickers from finagg.sec.feat.Quarterly.get_ticker_set().

• processes – Number of background processes to run in parallel when processing tickers.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

• recreate_tables – Whether to drop and recreate tables, wiping all previously installed data.

Returns:

Number of rows written to the feature’s SQL table.

classmethod to_refined(ticker: str, df: DataFrame, /, *, engine: None | Engine = None) → int

Write the dataframe to the feature store for ticker.

Parameters:

• ticker – Company ticker.

• df – Dataframe to store completely as rows in a local SQL table.

• engine – Feature store database engine. Defaults to the engine at finagg.backend.engine.

Returns:

Number of rows written to the SQL table.

finagg.fundam.feat.fundam

The most popular way for accessing finagg.fundam.feat.Fundamental.

finagg.fundam.sql module

SQLAlchemy interfaces for fundamental features.

finagg.fundam.sql.metadata

The metadata associated with all SQL tables defined in this module.

finagg.fundam.sql.fundam

SQL table for storing refined data as managed by finagg.fundam.feat.fundam (an alias for finagg.fundam.feat.Fundamental).

finagg.fundam.sql.normalized_fundam

SQL table for storing refined data as managed by finagg.fundam.feat.Fundamental.normalized (an alias for finagg.fundam.feat.NormalizedFundamental).

Module contents

Top-level fundamentals interface.