Coverage for src/jquantstats/_plots/_data/_drawdown.py: 100%

1"""Drawdown charts (underwater curve and worst-period shading).""" 

2 

3from __future__ import annotations 

4 

5from typing import TYPE_CHECKING, Literal, overload 

6 

7from .._render import render 

8from .._specs import drawdown_spec, drawdowns_periods_spec 

9 

10if TYPE_CHECKING: 

11 from matplotlib.figure import Figure as MplFigure 

12 from plotly.graph_objects import Figure as PlotlyFigure 

13 

14 from jquantstats._protocol import DataLike 

15 

16 from .._backend import Backend 

17 from .._render import Figure 

18 

19 

20class _DrawdownPlotsMixin: 

21 """Drawdown plots for :class:`DataPlots`.""" 

22 

23 __slots__ = () 

24 

25 _data: DataLike 

26 

27 @overload 

28 def drawdown(self, title: str = ..., *, backend: Literal["plotly"] | None = ...) -> PlotlyFigure: ... 

29 

30 @overload 

31 def drawdown(self, title: str = ..., *, backend: Literal["matplotlib"]) -> MplFigure: ... 

32 

33 def drawdown(self, title: str = "Drawdowns", *, backend: Backend | None = None) -> Figure: 

34 """Underwater equity curve (drawdown) chart. 

35 

36 Shows the percentage decline from the running peak for every column 

37 in the dataset (assets and benchmark where present). 

38 

39 Args: 

40 title: Chart title. Defaults to ``"Drawdowns"``. 

41 backend: Renderer to use. Defaults to the ambient selection. 

42 

43 Returns: 

44 Figure: A filled-area chart. 

45 

46 """ 

47 return render(drawdown_spec(self._data, title=title), backend) 

48 

49 @overload 

50 def drawdowns_periods( 

51 self, 

52 n: int = ..., 

53 title: str = ..., 

54 asset: str | None = ..., 

55 *, 

56 backend: Literal["plotly"] | None = ..., 

57 ) -> PlotlyFigure: ... 

58 

59 @overload 

60 def drawdowns_periods( 

61 self, 

62 n: int = ..., 

63 title: str = ..., 

64 asset: str | None = ..., 

65 *, 

66 backend: Literal["matplotlib"], 

67 ) -> MplFigure: ... 

68 

69 def drawdowns_periods( 

70 self, 

71 n: int = 5, 

72 title: str = "Top Drawdown Periods", 

73 asset: str | None = None, 

74 *, 

75 backend: Backend | None = None, 

76 ) -> Figure: 

77 """Cumulative returns chart with the worst *n* drawdown periods shaded. 

78 

79 Identifies the *n* deepest drawdown periods and overlays coloured 

80 rectangular shading on the cumulative returns line. One asset is 

81 shown per call. 

82 

83 Args: 

84 n: Number of worst drawdown periods to highlight. Defaults to 5. 

85 title: Chart title. Defaults to ``"Top Drawdown Periods"``. 

86 asset: Asset column name. Defaults to the first non-date column. 

87 backend: Renderer to use. Defaults to the ambient selection. 

88 

89 Returns: 

90 Figure: An equity curve with the worst episodes shaded. 

91 

92 """ 

93 return render(drawdowns_periods_spec(self._data, n=n, title=title, asset=asset), backend)