Operators API
Complete parameter documentation for all operator functions. Usage: from phandas import *
Cross-sectional Operators
- phandas.rank(factor: Factor) Factor
Rank values from 0 to 1 across all assets at each time.
Highest value gets 1.0, lowest gets close to 0.
- Parameters:
factor (Factor) – Input factor
- Returns:
Percentile rank (0-1) at each timestamp
- Return type:
Factor
- phandas.mean(factor: Factor) Factor
Average across all assets at each time.
- Parameters:
factor (Factor) – Input factor
- Returns:
Average value at each timestamp
- Return type:
Factor
- phandas.median(factor: Factor) Factor
Middle value across all assets at each time.
- Parameters:
factor (Factor) – Input factor
- Returns:
Median value at each timestamp
- Return type:
Factor
- phandas.normalize(factor: Factor, use_std: bool = False, limit: float = 0.0) Factor
Subtract average, optionally divide by spread.
Formula: (x - mean) or (x - mean) / std
- Parameters:
factor (Factor) – Input factor
use_std (bool, default False) – If True, also divide by standard deviation
limit (float, default 0.0) – If > 0, clip values to [-limit, +limit]
- Returns:
Normalized factor centered at 0
- Return type:
Factor
- phandas.zscore(factor: Factor) Factor
Standardize to mean=0 and std=1 at each time.
Formula: (x - mean) / std
- Parameters:
factor (Factor) – Input factor
- Returns:
Standardized factor
- Return type:
Factor
- phandas.quantile(factor: Factor, driver: str = 'gaussian', sigma: float = 1.0) Factor
Transform ranks to follow a target distribution shape.
- Parameters:
factor (Factor) – Input factor
driver ({'gaussian', 'uniform', 'cauchy'}, default 'gaussian') – Target distribution (gaussian = bell curve)
sigma (float, default 1.0) – Spread of the distribution
- Returns:
Values reshaped to target distribution
- Return type:
Factor
- phandas.scale(factor: Factor, scale: float = 1.0, longscale: float | None = None, shortscale: float | None = None) Factor
Resize values so their absolute sum equals a target.
- Parameters:
factor (Factor) – Input factor
scale (float, default 1.0) – Target for sum of absolute values
longscale (float, optional) – Separate target for positive values
shortscale (float, optional) – Separate target for negative values
- Returns:
Rescaled factor
- Return type:
Factor
- phandas.spread(factor: Factor, pct: float = 0.5) Factor
Simple long/short: go long top X%, short bottom X%.
- Parameters:
factor (Factor) – Input factor
pct (float, default 0.5) – Percentage to include (top pct% gets +0.5, bottom pct% gets -0.5)
- Returns:
Binary long/short weights
- Return type:
Factor
- phandas.signal(factor: Factor) Factor
Convert to trading weights (long +0.5, short -0.5, net zero).
Subtracts mean then scales so positive values sum to 0.5 and negative values sum to -0.5.
- Parameters:
factor (Factor) – Input factor
- Returns:
Trading weights that sum to zero
- Return type:
Factor
Time Series Operators
Basic Statistics
- phandas.ts_delay(factor: Factor, window: int) Factor
Get the value from N days ago.
- Parameters:
factor (Factor) – Input factor
window (int) – How many days back to look
- Returns:
Value from N days ago
- Return type:
Factor
- phandas.ts_delta(factor: Factor, window: int) Factor
Change since N days ago.
Formula: today - N_days_ago
- Parameters:
factor (Factor) – Input factor
window (int) – How many days back to compare
- Returns:
Difference from N days ago
- Return type:
Factor
- phandas.ts_mean(factor: Factor, window: int) Factor
Average of the last N days.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days to average
- Returns:
Rolling average
- Return type:
Factor
- phandas.ts_median(factor: Factor, window: int) Factor
Middle value of the last N days.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Rolling median
- Return type:
Factor
- phandas.ts_sum(factor: Factor, window: int) Factor
Add up all values in the last N days.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Rolling sum
- Return type:
Factor
- phandas.ts_product(factor: Factor, window: int) Factor
Multiply all values in the last N days.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Rolling product
- Return type:
Factor
- phandas.ts_std_dev(factor: Factor, window: int) Factor
How spread out are values in the last N days?
Higher = more volatile, lower = more stable.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Rolling standard deviation
- Return type:
Factor
Ranking and Extrema
- phandas.ts_rank(factor: Factor, window: int) Factor
Where does today’s value rank in the last N days? (0-1)
1.0 = highest in window, 0 = lowest in window.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days to look at
- Returns:
Percentile rank within the window
- Return type:
Factor
- phandas.ts_max(factor: Factor, window: int) Factor
Highest value in the last N days.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Rolling maximum
- Return type:
Factor
- phandas.ts_min(factor: Factor, window: int) Factor
Lowest value in the last N days.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Rolling minimum
- Return type:
Factor
- phandas.ts_arg_max(factor: Factor, window: int) Factor
When did the highest value occur in the last N days?
Returns position: 0=oldest day, N-1=today.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Position of maximum value
- Return type:
Factor
- phandas.ts_arg_min(factor: Factor, window: int) Factor
When did the lowest value occur in the last N days?
Returns position: 0=oldest day, N-1=today.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Position of minimum value
- Return type:
Factor
Higher-order Statistics
- phandas.ts_skewness(factor: Factor, window: int) Factor
Is the distribution lopsided in the last N days?
Positive = more extreme high values, negative = more extreme low values. Zero = symmetric distribution.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Rolling skewness
- Return type:
Factor
- phandas.ts_kurtosis(factor: Factor, window: int) Factor
Are there extreme values in the last N days? (tail heaviness)
High = frequent extreme moves, low = mostly normal moves. Normal distribution has kurtosis = 0.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Rolling kurtosis (0 = normal, >0 = fat tails)
- Return type:
Factor
- phandas.ts_cv(factor: Factor, window: int) Factor
Relative volatility: std / abs(mean) over rolling window.
Higher = more volatile relative to average level.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Coefficient of variation
- Return type:
Factor
- phandas.ts_jumpiness(factor: Factor, window: int) Factor
How choppy is the price movement? (frequent small jumps vs smooth trend)
Formula: sum of daily changes / total range Higher = more choppy, lower = smoother trend.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Jumpiness ratio
- Return type:
Factor
- phandas.ts_trend_strength(factor: Factor, window: int) Factor
How strong is the trend direction? (0=no trend, 1=perfect trend)
Uses R-squared from fitting a line through time.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Trend strength (0 to 1)
- Return type:
Factor
- phandas.ts_vr(factor: Factor, window: int, k: int = 2) Factor
Compare volatility at different time scales.
Ratio of k-day variance to 1-day variance. >1 suggests trending, <1 suggests mean-reverting.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
k (int, default 2) – Compare k-day changes to 1-day changes
- Returns:
Variance ratio
- Return type:
Factor
- phandas.ts_autocorr(factor: Factor, window: int, lag: int = 1) Factor
How similar is today’s value to N days ago?
+1 = very similar, -1 = opposite, 0 = no pattern.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
lag (int, default 1) – Compare to value from lag days ago
- Returns:
Autocorrelation
- Return type:
Factor
- phandas.ts_reversal_count(factor: Factor, window: int) Factor
How often does direction change? (up to down or down to up)
Higher = more choppy, lower = more consistent direction.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Reversal frequency (0 to 1)
- Return type:
Factor
Standardization
- phandas.ts_zscore(factor: Factor, window: int) Factor
How unusual is today’s value compared to recent history?
Formula: (today - average) / std_dev Higher absolute value = more unusual.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days for comparison
- Returns:
Rolling z-score
- Return type:
Factor
- phandas.ts_scale(factor: Factor, window: int, constant: float = 0) Factor
Scale values to 0-1 range based on last N days min/max.
Formula: (today - min) / (max - min) + constant
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
constant (float, default 0) – Add this to the scaled value
- Returns:
Scaled to 0-1 range
- Return type:
Factor
- phandas.ts_quantile(factor: Factor, window: int, driver: str = 'gaussian') Factor
Transform rolling ranks to a target distribution shape.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
driver ({'gaussian', 'uniform', 'cauchy'}, default 'gaussian') – Target distribution (gaussian = bell curve)
- Returns:
Rolling quantile-transformed values
- Return type:
Factor
- phandas.ts_av_diff(factor: Factor, window: int) Factor
How far is today’s value from the N-day average?
Formula: today - average(last N days)
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days for average
- Returns:
Distance from rolling average
- Return type:
Factor
Decay Weighting
- phandas.ts_decay_linear(factor: Factor, window: int, dense: bool = False) Factor
Weighted average where recent values count more (linear weights).
Most recent day has weight N, oldest has weight 1.
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
dense (bool, default False) – If True, skip missing values when weighting
- Returns:
Linearly weighted average
- Return type:
Factor
- phandas.ts_decay_exp_window(factor: Factor, window: int, factor_arg: float = 1.0, nan: bool = True) Factor
Weighted average where recent values count more (exponential weights).
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
factor_arg (float, default 1.0) – Decay rate (smaller = faster decay)
nan (bool, default True) – Skip missing values if True
- Returns:
Exponentially weighted average
- Return type:
Factor
Correlation and Regression
- phandas.ts_corr(factor1: Factor, factor2: Factor, window: int) Factor
How closely do two factors move together over the last N days?
+1 = move together, -1 = move opposite, 0 = no relationship.
- Parameters:
factor1 (Factor) – First factor
factor2 (Factor) – Second factor
window (int) – Number of past days
- Returns:
Rolling correlation (-1 to +1)
- Return type:
Factor
- phandas.ts_covariance(factor1: Factor, factor2: Factor, window: int) Factor
How do two factors vary together over the last N days?
Positive = move in same direction, negative = opposite.
- Parameters:
factor1 (Factor) – First factor
factor2 (Factor) – Second factor
window (int) – Number of past days
- Returns:
Rolling covariance
- Return type:
Factor
- phandas.ts_regression(y: Factor, x: Factor, window: int, lag: int = 0, rettype: int = 0) Factor
Fit a line y = a + b*x over rolling window.
Can return different parts of the regression result.
- Parameters:
y (Factor) – Value to predict
x (Factor) – Value used for prediction
window (int) – Number of past days
lag (int, default 0) – Shift x by this many days
rettype (int, default 0) – What to return: 0=residual, 1=intercept, 2=slope, 3=predicted, 4=sum squared error, 5=total variance, 6=R-squared, 7=mean squared error
- Returns:
Regression result
- Return type:
Factor
Other
- phandas.ts_step(factor: Factor, start: int = 1) Factor
Day counter for each asset (1, 2, 3, …).
- Parameters:
factor (Factor) – Input factor
start (int, default 1) – First day’s number
- Returns:
Day number for each row
- Return type:
Factor
- phandas.ts_count_nans(factor: Factor, window: int) Factor
How many missing values in the last N days?
- Parameters:
factor (Factor) – Input factor
window (int) – Number of past days
- Returns:
Count of missing values
- Return type:
Factor
- phandas.ts_backfill(factor: Factor, window: int, k: int = 1) Factor
Fill missing values with recent valid values.
- Parameters:
factor (Factor) – Input factor
window (int) – How far back to look for valid values
k (int, default 1) – Use k-th most recent valid value (1=latest, 2=second-latest)
- Returns:
Factor with missing values filled
- Return type:
Factor
Neutralization Operators
- phandas.vector_neut(x: Factor, y: Factor) Factor
Remove y’s influence from x, keeping only the independent part.
Formula: x - (x dot y / y dot y) * y
- Parameters:
x (Factor) – Factor to process
y (Factor) – Factor whose influence to remove
- Returns:
x with y’s influence removed
- Return type:
Factor
- phandas.regression_neut(y: Factor, x: Factor) Factor
Remove x’s influence from y using linear regression.
Fits a line y = a + b*x, returns the residuals (actual - predicted).
- Parameters:
y (Factor) – Factor to process
x (Factor) – Factor whose influence to remove
- Returns:
Residuals after removing x’s linear effect
- Return type:
Factor
Group Operators
- phandas.group(factor: Factor, mapping: dict) Factor
Map symbol to group ID using a custom dict.
- Parameters:
factor (Factor) – Base factor providing timestamp/symbol index
mapping (dict) – Symbol to group ID mapping, e.g. {‘ETH’: 1, ‘SOL’: 1, ‘ARB’: 2}
- Returns:
Group ID factor
- Return type:
Factor
- phandas.group_neutralize(x: Factor, group: Factor) Factor
Subtract group average from each value.
Formula: x - mean(x within same group)
- Parameters:
x (Factor) – Factor to neutralize
group (Factor) – Group ID for each asset
- Returns:
Values relative to group average
- Return type:
Factor
- phandas.group_mean(x: Factor, group: Factor) Factor
Calculate group mean for each asset.
- Parameters:
x (Factor) – Factor to calculate mean for
group (Factor) – Factor defining the group for each asset
- Returns:
Mean value of the group the asset belongs to
- Return type:
Factor
- phandas.group_median(x: Factor, group: Factor) Factor
Calculate group median for each asset.
- Parameters:
x (Factor) – Factor to calculate median for
group (Factor) – Factor defining the group for each asset
- Returns:
Median value of the group the asset belongs to
- Return type:
Factor
- phandas.group_rank(x: Factor, group: Factor) Factor
Calculate percentile rank within each group.
- Parameters:
x (Factor) – Factor to rank
group (Factor) – Factor defining the group for each asset
- Returns:
Percentile rank (0-1) within the group
- Return type:
Factor
- phandas.group_scale(x: Factor, group: Factor) Factor
Scale values within each group to 0-1 range.
- Parameters:
x (Factor) – Factor to scale
group (Factor) – Factor defining the group for each asset
- Returns:
Scaled values: (x - min) / (max - min)
- Return type:
Factor
- phandas.group_zscore(x: Factor, group: Factor) Factor
Calculate Z-score within each group.
- Parameters:
x (Factor) – Factor to calculate zscore for
group (Factor) – Factor defining the group for each asset
- Returns:
Z-score: (x - mean) / std
- Return type:
Factor
- phandas.group_normalize(x: Factor, group: Factor, scale: float = 1.0) Factor
Normalize such that each group’s absolute sum equals scale.
- Parameters:
x (Factor) – Factor to normalize
group (Factor) – Factor defining the group for each asset
scale (float, default 1.0) – Target sum of absolute values for each group
- Returns:
Normalized values: x / sum(|x|_group) * scale
- Return type:
Factor
Math Operators
Elementary Functions
- phandas.log(factor: Factor, base: float | None = None) Factor
Logarithm with optional base.
- Parameters:
factor (Factor) – Input factor
base (float, optional) – Logarithm base (None → natural logarithm)
- Returns:
Logarithm of factor
- Return type:
Factor
- phandas.ln(factor: Factor) Factor
Natural logarithm.
- Parameters:
factor (Factor) – Input factor
- Returns:
Natural logarithm of factor
- Return type:
Factor
- phandas.sqrt(factor: Factor) Factor
Square root.
- Parameters:
factor (Factor) – Input factor
- Returns:
Square root (x<0 → NaN)
- Return type:
Factor
- phandas.s_log_1p(factor: Factor) Factor
Sign-preserving logarithm.
- Parameters:
factor (Factor) – Input factor
- Returns:
Sign-preserving log: sign(x)·ln(1+|x|)
- Return type:
Factor
- phandas.sign(factor: Factor) Factor
Sign of values.
- Parameters:
factor (Factor) – Input factor
- Returns:
Sign: -1, 0, or +1
- Return type:
Factor
- phandas.inverse(factor: Factor) Factor
Reciprocal (1/x).
- Parameters:
factor (Factor) – Input factor
- Returns:
Reciprocal (x=0 → NaN)
- Return type:
Factor
Power Functions
- phandas.power(base: Factor, exponent: Factor | float) Factor
Element-wise power.
- Parameters:
base (Factor) – Base factor
exponent (Factor or float) – Exponent
- Returns:
Element-wise power
- Return type:
Factor
Comparison and Conditional
- phandas.maximum(factor1: Factor, factor2: Factor | float) Factor
Element-wise maximum.
- Parameters:
factor1 (Factor) – First factor
factor2 (Factor or float) – Second factor or scalar
- Returns:
Element-wise maximum
- Return type:
Factor
- phandas.minimum(factor1: Factor, factor2: Factor | float) Factor
Element-wise minimum.
- Parameters:
factor1 (Factor) – First factor
factor2 (Factor or float) – Second factor or scalar
- Returns:
Element-wise minimum
- Return type:
Factor
- phandas.where(condition: Factor, x: Factor | float, y: Factor | float) Factor
If-else selection: pick x when condition is true, otherwise y.
- Parameters:
condition (Factor) – True/False values for each cell
x (Factor or float) – Value to use when True
y (Factor or float) – Value to use when False
- Returns:
Selected values
- Return type:
Factor
Arithmetic Operations
- phandas.add(factor1: Factor, factor2: Factor | float) Factor
Element-wise addition.
- Parameters:
factor1 (Factor) – First factor
factor2 (Factor or float) – Second factor or scalar
- Returns:
Element-wise sum
- Return type:
Factor
- phandas.subtract(factor1: Factor, factor2: Factor | float) Factor
Element-wise subtraction.
- Parameters:
factor1 (Factor) – First factor
factor2 (Factor or float) – Second factor or scalar
- Returns:
Element-wise difference
- Return type:
Factor
- phandas.multiply(factor1: Factor, factor2: Factor | float) Factor
Element-wise multiplication.
- Parameters:
factor1 (Factor) – First factor
factor2 (Factor or float) – Second factor or scalar
- Returns:
Element-wise product
- Return type:
Factor
- phandas.divide(factor1: Factor, factor2: Factor | float) Factor
Element-wise division.
- Parameters:
factor1 (Factor) – Numerator
factor2 (Factor or float) – Denominator
- Returns:
Element-wise quotient (div by 0 → NaN)
- Return type:
Factor
- phandas.reverse(factor: Factor) Factor
Negate factor values.
- Parameters:
factor (Factor) – Input factor
- Returns:
Negated factor (-x)
- Return type:
Factor