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 ._internals import ( 

36 _annualization_factor, 

37 _comp_return, 

38 _downside_deviation, 

39 _nav_series, 

40) 

41from ._performance import _PerformanceStatsMixin 

42from ._reporting import _ReportingStatsMixin 

43from ._rolling import _RollingStatsMixin 

44 

45if TYPE_CHECKING: 

46 from ..data import Data 

47 

48__all__ = [ 

49 "Stats", 

50 "_annualization_factor", 

51 "_comp_return", 

52 "_downside_deviation", 

53 "_drawdown_series", 

54 "_nav_series", 

55 "_to_float", 

56 "columnwise_stat", 

57 "to_frame", 

58] 

59 

60 

61@dataclasses.dataclass(frozen=True) 

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

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

64 

65 Provides a comprehensive set of methods for calculating various financial 

66 metrics and statistics on returns data, including: 

67 

68 - Basic statistics (mean, skew, kurtosis) 

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

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

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

72 - Rolling calculations (rolling volatility, rolling Sharpe) 

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

74 

75 Metrics are organised into focused modules: 

76 

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

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

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

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

81 

82 Attributes: 

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

84 and benchmark data. 

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

86 easy column selection. 

87 """ 

88 

89 data: Data 

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

91 

92 def __post_init__(self) -> None: 

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

94 

95 def __repr__(self) -> str: 

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

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