portfolios.implement_portfolio_sort()
Implement a portfolio sort.
Usage
portfolios.implement_portfolio_sort(
data,
sorting_variables,
sorting_method,
rebalancing_month=None,
holding_period=1,
skip=0,
portfolio_sort_options=None,
breakpoint_function_main=compute_breakpoints,
breakpoint_function_secondary=compute_breakpoints,
min_portfolio_size=1,
cap_weight=0.8,
cap_weight_exchanges="NYSE",
data_options=None,
quiet=False
)A convenience wrapper that combines sample construction filtering and portfolio return computation into a single call. Equivalent to calling ‘filter_sorting_data’ followed by ‘compute_portfolio_returns’ with the filter and breakpoint specifications bundled in ‘portfolio_sort_options’.
Parameters
data: pl.DataFrame-
Data frame containing the stock-level panel data.
sorting_variables: str or list of str-
One or two column names to sort portfolios on.
sorting_method: str-
Sorting method to use. One of ‘univariate’, ‘bivariate-dependent’, or ‘bivariate-independent’.
rebalancing_month: int = None-
Month in which portfolios are rebalanced annually. None (the default) means monthly rebalancing. Also determines the formation month in which the screens of ‘filter_options’ are applied (see ‘filter_sorting_data’).
holding_period: int = 1 and 0-
Staggered rebalancing: portfolios are formed every period and each cohort is held for ‘holding_period’ periods, starting ‘skip’ periods after formation. See ‘compute_portfolio_returns’. With the default ‘filter_options(timing=“formation”)’, the screens only decide which stocks enter the cohort formed in a period; a stock that fails a screen later stays in its earlier cohorts until their holding period ends.
skip: int = 1 and 0-
Staggered rebalancing: portfolios are formed every period and each cohort is held for ‘holding_period’ periods, starting ‘skip’ periods after formation. See ‘compute_portfolio_returns’. With the default ‘filter_options(timing=“formation”)’, the screens only decide which stocks enter the cohort formed in a period; a stock that fails a screen later stays in its earlier cohorts until their holding period ends.
portfolio_sort_options: dict = None-
Dict produced by ‘portfolio_sort_options’, bundling filter and breakpoint specifications. The accepted entries include ‘filter_options’, ‘breakpoint_options_main’, and ‘breakpoint_options_secondary’. Required.
breakpoint_function_main: callable = compute_breakpoints-
Function used to compute breakpoints for the main sorting variable. Defaults to ‘compute_breakpoints’.
breakpoint_function_secondary: callable = compute_breakpoints-
Function used to compute breakpoints for the secondary sorting variable. Defaults to ‘compute_breakpoints’.
min_portfolio_size: int = 1-
Minimum number of firms in the reported portfolio cross-section on a given date. For univariate sorts that is firms per portfolio-date; for bivariate sorts that is firms per main-portfolio-date summed across the secondary buckets. Cross-sections below the threshold have their returns set to null. Set to 0 to deactivate the check.
cap_weight: float = 0.8-
Quantile of the cross-sectional ‘mktcap_lag’ distribution at which market capitalizations are capped per date when computing the capped value-weighted excess return (‘ret_excess_vw_capped’). Must be in [0, 1].
cap_weight_exchanges: str or list of str = "NYSE"-
Exchange(s) whose stocks determine the cap, or None for all stocks. Defaults to ‘NYSE’. See ‘compute_portfolio_returns’.
data_options: dict = None-
Column-name mapping (see ‘data_options’). All elements are forwarded to ‘filter_sorting_data’ and ‘compute_portfolio_returns’. Uses the ‘data_options’ defaults when None.
quiet: bool = False- Whether informational messages should be suppressed.
Returns
pl.DataFrame- Data frame of portfolio returns as returned by ‘compute_portfolio_returns’.
Examples
import datetime as dt
import numpy as np
import polars as pl
from tidyfinance import (
implement_portfolio_sort,
portfolio_sort_options,
filter_options,
breakpoint_options,
)
rng = np.random.default_rng(123)
dates = pl.date_range(
dt.date(2020, 1, 1), dt.date(2028, 4, 1), '1mo', eager=True
)
data = pl.DataFrame({
'permno': range(1, 501),
'date': dates.to_numpy().repeat(5),
'mktcap_lag': rng.uniform(100, 1000, 500),
'ret_excess': rng.standard_normal(500),
'prc_lag':rng.uniform(0.5, 50, 500),
'size': rng.uniform(50, 150, 500),
})
implement_portfolio_sort(
data=data,
sorting_variables='size',
sorting_method='univariate',
portfolio_sort_options=portfolio_sort_options(
filter_options=filter_options(min_stock_price=1),
breakpoint_options_main=breakpoint_options(n_portfolios=5),
),
)