toraniko

Use factor_mom to estimate rolling symbol-by-symbol momentum factor scores based on asset returns. The function applies exponential weighting to returns over a trailing period and applies a lag to the observations.

Important: This function does not handle NaN or null values, nor does it account for pathological data distributions. You must ensure your input data is clean using the math and utils modules before calling this function.

Input Requirements: returns_df must be a Polars DataFrame or LazyFrame containing the following columns:

• date
• symbol
• asset_returns

Parameters:

• returns_df: The input Polars DataFrame/LazyFrame.
• trailing_days (int, default 504): Look-back period for momentum measurement.
• half_life (int, default 126): Decay rate for exponential weighting (in days).
• lag (int, default 20): Number of days to lag the current day's return (e.g., 20 trading days for one month).
• winsor_factor (float, default 0.01): Percentile used for winsorization.

Returns: A Polars LazyFrame containing:

• date
• symbol
• mom_score

import polars as pl
from toraniko.styles import factor_mom

# Example usage with a Polars DataFrame
df = pl.DataFrame({
    "date": ["2023-01-01", "2023-01-02"],
    "symbol": ["AAPL", "AAPL"],
    "asset_returns": [0.01, -0.005]
})

mom_scores = factor_mom(df, trailing_days=252, lag=20)

The smooth_features() function applies a rolling mean to specified columns to reduce noise.

Process:

1. Sorts the data by sort_col.
2. Calculates a rolling mean for each column in features using a trailing window of window_size.
3. The calculation is partitioned by over_col to ensure smoothing stays within specific groups.

Parameters:

• df: A pl.DataFrame or pl.LazyFrame.
• features: A tuple[str, ...] of column names to smooth.
• sort_col: The column name used to sort the data (typically a timestamp or sequence).
• over_col: The column name used to partition the data (e.g., a user ID or sensor ID).
• window_size: An int representing the number of trailing periods for the moving average window.

Returns: A pl.LazyFrame where the features columns have been replaced by their moving average values.

Errors:

• Raises TypeError if df is not a Polars DataFrame or LazyFrame.
• Raises ValueError if any of the features, sort_col, or over_col are missing from the input DataFrame.

import polars as pl
from toraniko.utils import smooth_features

# Example usage
df = pl.DataFrame({
    "id": [1, 1, 1, 1, 2, 2, 2, 2],
    "time": [1, 2, 3, 4, 1, 2, 3, 4],
    "val": [1.0, 2.0, 3.0, 4.0, 10.0, 20.0, 30.0, 40.0]
})

smoothed_lf = smooth_features(
    df=df, 
    features=("val",), 
    sort_col="time", 
    over_col="id", 
    window_size=2
)

The top_n_by_group() function identifies the highest-ranking rows within specific groups based on a ranking variable.

Parameters:

• df: A pl.DataFrame or pl.LazyFrame.
• n: An int specifying how many top rows to select per group.
• rank_var: The column name used to determine the rank (descending order).
• group_var: A tuple[str, ...] of column names used to define the groups.
• filter: A bool (default True).
  • If True: Returns only the top n rows per group. The rank column is dropped.
  • If False: Returns all original rows, but adds a rank_mask column (1 if the row is in the top n, 0 otherwise).

Returns: A pl.LazyFrame containing the processed data.

Errors:

• Raises TypeError if df is not a Polars DataFrame or LazyFrame.
• Raises ValueError if rank_var or any of the group_var columns are missing.

import polars as pl
from toraniko.utils import top_n_by_group

# Example usage: Get top 2 values per group
df = pl.DataFrame({
    "group": ["A", "A", "A", "B", "B", "B"],
    "score": [10, 50, 30, 5, 100, 20]
})

# Returns only the top 2 rows per group
top_rows_lf = top_n_by_group(
    df=df, 
    n=2, 
    rank_var="score", 
    group_var=("group",),
    filter=True
)

# Returns all rows with a 'rank_mask' column
masked_lf = top_n_by_group(
    df=df, 
    n=2, 
    rank_var="score", 
    group_var=("group",),
    filter=False
)

Use factor_sze to estimate rolling symbol-by-symbol size factor scores using market capitalization. The implementation follows the Fama-French SMB (Small Minus Big) logic, meaning it multiplies the log of market cap by -1 to capture the size risk premium associated with smaller firms.

Input Requirements: mkt_cap_df must be a Polars DataFrame or LazyFrame containing:

• date
• symbol
• market_cap

Parameters:

• mkt_cap_df: The input Polars DataFrame/LazyFrame.
• lower_decile (float, default 0.2): Lower bound for percentile calculation.
• upper_decile (float, default 0.8): Upper bound for percentile calculation.

Returns: A Polars LazyFrame containing:

• date
• symbol
• sze_score

import polars as pl
from toraniko.styles import factor_sze

# Example usage
mkt_cap_df = pl.DataFrame({
    "date": ["2023-01-01", "2023-01-01"],
    "symbol": ["AAPL", "MSFT"],
    "market_cap": [3e12, 2e12]
})

sze_scores = factor_sze(mkt_cap_df)