Coverage for src / jquantstats / _stats / stats.py: 100%

1"""Statistical analysis tools for financial returns data. 

2 

3This module provides the :class:`Stats` dataclass, which is the public-facing 

4class that combines four mixin classes: 

5 

6- :class:`~jquantstats._stats._basic._BasicStatsMixin` — basic statistics, 

7 volatility, win/loss metrics, and risk metrics (VaR, Sharpe inputs, Kelly). 

8- :class:`~jquantstats._stats._performance._PerformanceStatsMixin` — Sharpe, 

9 Sortino, drawdown, benchmark/factor analytics (R², alpha, beta). 

10- :class:`~jquantstats._stats._reporting._ReportingStatsMixin` — temporal 

11 reporting, Calmar, recovery factor, capture ratios, annual breakdown, and 

12 summary. 

13- :class:`~jquantstats._stats._rolling._RollingStatsMixin` — rolling-window 

14 time-series metrics (rolling Sharpe, Sortino, and volatility). 

15 

16Module-level helpers and the ``columnwise_stat`` / ``to_frame`` decorators are 

17defined in :mod:`jquantstats._stats._core` and re-exported here for backwards 

18compatibility. 

19""" 

20 

21from __future__ import annotations 

22 

23import dataclasses 

24from typing import TYPE_CHECKING 

25 

26import polars as pl 

27 

28from ._basic import _BasicStatsMixin 

29from ._core import ( 

30 _drawdown_series, 

31 _to_float, 

32 columnwise_stat, 

33 to_frame, 

34) 

35from ._performance import _PerformanceStatsMixin 

36from ._reporting import _ReportingStatsMixin 

37from ._rolling import _RollingStatsMixin 

38 

39if TYPE_CHECKING: 

40 from ..data import Data 

41 

42__all__ = [ 

43 "Stats", 

44 "_drawdown_series", 

45 "_to_float", 

46 "columnwise_stat", 

47 "to_frame", 

48] 

49 

50 

51@dataclasses.dataclass(frozen=True) 

52class Stats(_BasicStatsMixin, _PerformanceStatsMixin, _ReportingStatsMixin, _RollingStatsMixin): 

53 """Statistical analysis tools for financial returns data. 

54 

55 Provides a comprehensive set of methods for calculating various financial 

56 metrics and statistics on returns data, including: 

57 

58 - Basic statistics (mean, skew, kurtosis) 

59 - Risk metrics (volatility, value-at-risk, drawdown) 

60 - Performance ratios (Sharpe, Sortino, information ratio) 

61 - Win/loss metrics (win rate, profit factor, payoff ratio) 

62 - Rolling calculations (rolling volatility, rolling Sharpe) 

63 - Factor analysis (alpha, beta, R-squared) 

64 

65 Metrics are organised into focused modules: 

66 

67 - :class:`~jquantstats._stats._basic._BasicStatsMixin` 

68 - :class:`~jquantstats._stats._performance._PerformanceStatsMixin` 

69 - :class:`~jquantstats._stats._reporting._ReportingStatsMixin` 

70 - :class:`~jquantstats._stats._rolling._RollingStatsMixin` 

71 

72 Attributes: 

73 data: The :class:`~jquantstats._data.Data` object containing returns 

74 and benchmark data. 

75 all: A DataFrame combining all data (index, returns, benchmark) for 

76 easy column selection. 

77 """ 

78 

79 data: Data 

80 all: pl.DataFrame | None = None # Default is None; will be set in __post_init__ 

81 

82 def __post_init__(self) -> None: 

83 object.__setattr__(self, "all", self.data.all) 

84 

85 def __repr__(self) -> str: 

86 """Return a string representation of the Stats object.""" 

87 return f"Stats(assets={self.data.assets})"