quantlab.factor.predefined.barra.BarraStyleParameters#

class quantlab.factor.predefined.barra.BarraStyleParameters(price_column='adjClose', market_cap_column='marketcap', risk_free_column='risk_free', risk_free_symbol=None, close_column='close', volume_column='volume', dividend_column='divCash', split_column='splitFactor', book_equity_column='equity', long_term_debt_column='debtnc', total_debt_column='debt', current_liabilities_column='liabilitiesc', assets_column='assets', earnings_column='netinccmn', depreciation_column='depamor', fx_column='fxusd', eps_prefix='eps_fy', sales_prefix='sps_fy', fiscal_year_end_prefix='reportperiod_fy', growth_years=5, min_growth_years=3, industry_column='industry', firm_column='firm', estimation_universe_size=3000, beta_window=252, beta_half_life=63.0, beta_min_observations=63, momentum_window=504, momentum_half_life=126.0, momentum_lag=21, momentum_min_observations=252, dastd_window=252, dastd_half_life=42.0, cmra_months=12, cmra_month_length=21, volatility_min_observations=63, dastd_weight=0.75, cmra_weight=0.15, hsigma_weight=0.1, liquidity_month_length=21, stoq_months=3, stoa_months=12, liquidity_min_fraction=0.5, stom_weight=0.35, stoq_weight=0.35, stoa_weight=0.3, dividend_window=252, dividend_min_observations=126, cetop_weight=0.15, etop_weight=0.1, egro_weight=0.2, sgro_weight=0.1, mlev_weight=0.75, dtoa_weight=0.15, blev_weight=0.1, imputation_regressors=('industry', 'size'), imputation_weighting='sqrt_cap', orthogonalization_weighting='sqrt_cap', data_error_sigma=10.0, clip_sigma=3.0)[source]#

Bases: object

Formula parameters for BarraStyle, read from config.kwargs.

Every field can be set through FactorConfig.kwargs; unknown keys are refused. Windows are counted in bars of the panel the factor runs on, so the defaults assume daily bars. Each field says whether its default is USE4’s published value or a choice of ours where MSCI publishes none.

Parameters:

price_columnstr, default “adjClose”: Panel variable holding the split- and dividend-adjusted close; the return of bar t is price[t] / price[t-1] - 1.
market_cap_columnstr, default “marketcap”: Panel variable holding the market capitalization (Sharadar DAILY’s marketcap, in USD).
risk_free_columnstr, default “risk_free”: Panel variable holding the risk-free rate as a decimal return per bar, the same on every symbol. It is lagged one bar before use, because the rate of a day is published the next business day.
risk_free_symbolstr or None, default None: When set, the risk-free rate is the risk_free_column of this one symbol (FredRateDataset’s "DTB3", merged in as is) and the factor broadcasts it across the other symbols: the symbol is dropped, the bars kept are those where any other symbol has a price_column, and a bar without a published rate (a bond-market holiday on a trading day) takes the last rate before it (our choice). None reads the column on every symbol, already broadcast.
close_columnstr, default “close”: Panel variable holding the raw (unadjusted) close, the price Dividend Yield divides by and turnover’s dollar volume uses.
volume_columnstr, default “volume”: Panel variable holding the raw share volume, in the same share basis as close_column on each bar.
dividend_columnstr, default “divCash”: Panel variable holding the cash dividend per share on its ex-date, in that day’s share basis, 0 on other bars.
split_columnstr, default “splitFactor”: Panel variable holding a split’s new shares per old share on its effective date, 1 on other bars; it converts earlier dividends to the current share basis.
book_equity_columnstr, default “equity”: Book value of common equity (SF1, reporting currency).
long_term_debt_columnstr, default “debtnc”: Long-term (non-current) debt (SF1, reporting currency).
total_debt_columnstr, default “debt”: Total debt (SF1), taken as the long-term debt of a company whose balance sheet does not split current from non-current (a bank). Our choice.
current_liabilities_columnstr, default “liabilitiesc”: Current liabilities (SF1, reporting currency).
assets_columnstr, default “assets”: Total assets (SF1, reporting currency).
earnings_columnstr, default “netinccmn”: Trailing twelve months’ net income to common (SF1 ART).
depreciation_columnstr, default “depamor”: Trailing twelve months’ depreciation and amortization (SF1 ART).
fx_columnstr, default “fxusd”: Reporting currency per USD (SF1 fxusd): an amount in USD is the amount divided by it.
eps_prefix, sales_prefixstr, default “eps_fy”, “sps_fy”: Prefixes of the fiscal-year history variables (SharadarFiscalYearsDataset): <prefix>0 is the latest fiscal year’s EPS or sales per share, <prefix>1 the year before.
fiscal_year_end_prefixstr, default “reportperiod_fy”: Prefix of the fiscal-year history’s fiscal year ends, the time axis EGRO and SGRO regress on.
growth_yearsint, default 5: Fiscal years EGRO and SGRO regress on, the slots 0 .. growth_years - 1 (USE4: five).
min_growth_yearsint, default 3: Fewest known fiscal years for EGRO or SGRO to be computed. Our choice.
industry_columnstr, default “industry”: Panel variable holding the point-in-time industry code, a non-negative integer (SharadarIndustryDataset’s Fama-French 48 code); passed through as the industry output.
firm_columnstr, default “firm”: Panel variable holding the symbol whose market cap and fundamentals are this symbol’s firm values (SharadarShareClassDataset): the symbol itself, or for a secondary share class its firm’s primary class. A secondary class takes the firm’s market cap, fundamentals and fiscal-year history (firm_value_columns) and is never in the estimation universe, so the firm is counted once (USE4’s LNCAP is the firm’s total market cap, Empirical Notes p.51). NaN, or a symbol not on the panel, leaves the symbol as its own firm. The symbol axis must be integers (permatickers).
estimation_universe_sizeint, default 3000: Number of largest companies, by the previous bar’s market cap, in the estimation universe. Our choice: USE4 uses the MSCI USA IMI, which this approximates; there is no buffer band.
beta_windowint, default 252: Bars in the BETA regression window (USE4).
beta_half_lifefloat, default 63.0: Half-life, in bars, of the BETA regression weights (USE4).
beta_min_observationsint, default 63: Fewest bars with both a stock and a market return in the BETA window for BETA and HSIGMA to be computed; with fewer they are NaN. Our choice.
momentum_windowint, default 504: Bars in the RSTR window (USE4).
momentum_half_lifefloat, default 126.0: Half-life, in bars, of the RSTR weights (USE4).
momentum_lagint, default 21: Bars RSTR skips before its window, so the latest month is left out (USE4).
momentum_min_observationsint, default 252: Fewest returns in the RSTR window for RSTR to be computed. Our choice.
dastd_windowint, default 252: Bars in the DASTD window (USE4).
dastd_half_lifefloat, default 42.0: Half-life, in bars, of the DASTD weights (USE4).
cmra_monthsint, default 12: Months in CMRA’s cumulative range (USE4).
cmra_month_lengthint, default 21: Bars in one CMRA month (USE4).
volatility_min_observationsint, default 63: Fewest returns in the DASTD or CMRA window for that descriptor to be computed. Our choice.
dastd_weight, cmra_weight, hsigma_weightfloat, default 0.75, 0.15, 0.10: Weights of DASTD, CMRA and HSIGMA in Residual Volatility (USE4).
liquidity_month_lengthint, default 21: Bars in one Liquidity month (USE4).
stoq_months, stoa_monthsint, default 3, 12: Months averaged by STOQ and STOA (USE4).
liquidity_min_fractionfloat, default 0.5: Fraction of a Liquidity window’s bars that must have a turnover for that descriptor to be computed. Our choice.
stom_weight, stoq_weight, stoa_weightfloat, default 0.35, 0.35, 0.30: Weights of STOM, STOQ and STOA in Liquidity (USE4).
dividend_windowint, default 252: Bars of dividends summed by YILD, a trailing year (USE4).
dividend_min_observationsint, default 126: Fewest raw closes in the YILD window for YILD to be computed. Our choice.
cetop_weight, etop_weightfloat, default 0.15, 0.10: Weights of CETOP and ETOP in Earnings Yield (USE4; EPFWD’s 0.75 is dropped and the two renormalized).
egro_weight, sgro_weightfloat, default 0.20, 0.10: Weights of EGRO and SGRO in Growth (USE4; EGRLF’s 0.70 is dropped and the two renormalized).
mlev_weight, dtoa_weight, blev_weightfloat, default 0.75, 0.15, 0.10: Weights of MLEV, DTOA and BLEV in Leverage (USE4).
imputation_regressorstuple of str, default (“industry”, “size”): Regressors a missing style is imputed from: "industry" (one intercept per industry), "size" (the Size exposure), both, or neither ((): no imputation). Size itself is imputed from the industry alone. Our choice: USE4 names industry membership and market cap as examples of the factors it uses but publishes no set.
imputation_weightingstr, default “sqrt_cap”: Regression weights of the imputation, one of ORTHOGONALIZATION_WEIGHTINGS. Our choice.
orthogonalization_weightingstr, default “sqrt_cap”: Regression weights of the orthogonalizations: "sqrt_cap" (the square root of the previous bar’s market cap), "cap" or "equal". The default follows USE4: NLSIZE and NLBETA are orthogonalized “on a regression-weighted basis” (Empirical Notes p.55), and the regression weight is the square root of cap (Appendix B, p.56).
data_error_sigmafloat, default 10.0: Distance from a descriptor’s mean over the estimation universe, in its standard deviations there (both equally weighted), beyond which a value is treated as a data error and dropped. Our choice: USE4 drops data errors (Methodology Notes §2.2, p.8) but does not publish the threshold.
clip_sigmafloat, default 3.0: Distance from the same mean, in the same standard deviations, a value beyond it is trimmed to, before standardizing (USE4: “three standard deviations from the mean”, §2.2, p.8).

Examples

>>> params = BarraStyleParameters(estimation_universe_size=500)
>>> params.panel_columns[:7]
('adjClose', 'marketcap', 'risk_free', 'close', 'volume', 'divCash', 'splitFactor')
>>> len(params.panel_columns)
32
>>> params.warmup_bars
526

property firm_value_columns#

Panel variables a secondary share class takes from its firm.

The market cap, the SF1 fundamentals and the fiscal-year history; prices, volume, dividends, splits and the industry stay its own.

Examples

>>> BarraStyleParameters().firm_value_columns[:3]
('marketcap', 'equity', 'debtnc')

classmethod from_config(config)[source]#

Build and validate parameters from config.kwargs.

Parameters:

configFactorConfig: The factor config whose kwargs holds the overrides.

Returns:

BarraStyleParameters: The validated parameters.

Raises:

ValueError: If config.kwargs holds an unknown key or a value that fails validate().

Examples

>>> from dataclasses import replace
>>> config = replace(config, kwargs={"beta_window": 126})
>>> BarraStyleParameters.from_config(config).beta_window
126

history_columns(prefix)[source]#

Return the fiscal-year history variables of one prefix, newest first.

Examples

>>> BarraStyleParameters(growth_years=3).history_columns("eps_fy")
('eps_fy0', 'eps_fy1', 'eps_fy2')

property panel_columns#

Panel variables the factor reads, what config.data_columns must name.

Examples

>>> BarraStyleParameters().panel_columns[7:16]
('equity', 'debtnc', 'debt', 'liabilitiesc', 'assets', 'netinccmn', 'depamor', 'fxusd', 'eps_fy0')

validate()[source]#

Raise if a window, a threshold or a column name cannot work.

Raises:

ValueError: If a window or count is too small, the thresholds are out of order, or the column names are empty or repeated.

Examples

>>> BarraStyleParameters(beta_min_observations=1).validate()
Traceback (most recent call last):
    ...
ValueError: beta_min_observations must be between 2 and beta_window (252), got 1

property warmup_bars#

Bars of history the first exposure needs: the longest window plus one return.

The longest is RSTR’s, its window plus its lag. Set FactorConfig.warmup_bars to at least this; with risk_free_symbol the factor counts them in bars with a price.

Examples

>>> BarraStyleParameters().warmup_bars
526