qis.df_to_cross_sectional_score

qis.df_to_cross_sectional_score(df, lower_clip=-5.0, upper_clip=5.0, is_sorted=False)[source]

Compute cross-sectional standardized scores (z-scores) for DataFrame or Series.

Transforms input data into standardized scores by subtracting the mean and dividing by the standard deviation. For DataFrames, standardization is performed row-wise (across columns). For Series, standardization uses the entire series.

Parameters:

  • df (Union[pd.Series, pd.DataFrame]) – Input data to standardize

  • lower_clip (Optional[float], optional) – Lower bound for clipping outliers. Set to None to disable. Defaults to -5.0.

  • upper_clip (Optional[float], optional) – Upper bound for clipping outliers. Set to None to disable. Defaults to 5.0.

  • is_sorted (bool, optional) – If True and input is Series, return results sorted in descending order. Defaults to False.

Returns:

Standardized scores with same shape as input.

Values represent number of standard deviations from the mean.

Return type:

Union[pd.Series, pd.DataFrame]

Examples

>>> # Series example
>>> s = pd.Series([1, 2, 3, 4, 5])
>>> scores = df_to_cross_sectional_score(s)
>>> print(scores)
0   -1.414
1   -0.707
2    0.000
3    0.707
4    1.414
dtype: float64

>>> # DataFrame example (row-wise standardization)
>>> df = pd.DataFrame({'A': [1, 4, 7], 'B': [2, 5, 8], 'C': [3, 6, 9]})
>>> scores = df_to_cross_sectional_score(df)
>>> print(scores)
     A    B    C
0 -1.0  0.0  1.0
1 -1.0  0.0  1.0
2 -1.0  0.0  1.0

>>> # With sorting
>>> sorted_scores = df_to_cross_sectional_score(s, is_sorted=True)
>>> print(sorted_scores)
4    1.414
3    0.707
2    0.000
1   -0.707
0   -1.414
dtype: float64

Notes

  • Uses np.nanmean and np.nanstd to handle NaN values gracefully

  • For DataFrames, standardization is performed across columns (axis=1)

  • Clipping is applied before standardization to reduce outlier impact