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

1"""The :class:`DataPlots` facade combining the plot-family mixins.""" 

2 

3from __future__ import annotations 

4 

5from typing import TYPE_CHECKING, Literal, overload 

6 

7from .._render import render 

8from .._specs import data_snapshot_spec 

9from ._cumulative import _CumulativePlotsMixin 

10from ._distribution import _DistributionPlotsMixin 

11from ._drawdown import _DrawdownPlotsMixin 

12from ._montecarlo import _MonteCarloPlotsMixin 

13from ._periodic import _PeriodicPlotsMixin 

14from ._rolling import _RollingPlotsMixin 

15 

16if TYPE_CHECKING: 

17 from matplotlib.figure import Figure as MplFigure 

18 from plotly.graph_objects import Figure as PlotlyFigure 

19 

20 from jquantstats._protocol import DataLike 

21 

22 from .._backend import Backend 

23 from .._render import Figure 

24 

25 

26class DataPlots( 

27 _CumulativePlotsMixin, 

28 _PeriodicPlotsMixin, 

29 _DistributionPlotsMixin, 

30 _MonteCarloPlotsMixin, 

31 _DrawdownPlotsMixin, 

32 _RollingPlotsMixin, 

33): 

34 """Visualization tools for financial returns data. 

35 

36 This class provides methods for creating various plots and visualizations 

37 of financial returns data, including: 

38 

39 - Returns bar charts 

40 - Portfolio performance snapshots 

41 - Monthly returns heatmaps 

42 

43 The class is designed to work with the _Data class and uses Plotly 

44 for creating interactive visualizations. 

45 """ 

46 

47 __slots__ = ("_data",) 

48 

49 def __init__(self, data: DataLike) -> None: 

50 self._data = data 

51 

52 @property 

53 def assets(self) -> list[str]: 

54 """Asset column names from the underlying data.""" 

55 return self._data.assets 

56 

57 def __repr__(self) -> str: 

58 """Return a string representation of the DataPlots object.""" 

59 return f"DataPlots(assets={self._data.assets})" 

60 

61 @overload 

62 def snapshot( 

63 self, title: str = ..., log_scale: bool = ..., *, backend: Literal["plotly"] | None = ... 

64 ) -> PlotlyFigure: ... 

65 

66 @overload 

67 def snapshot(self, title: str = ..., log_scale: bool = ..., *, backend: Literal["matplotlib"]) -> MplFigure: ... 

68 

69 def snapshot( 

70 self, 

71 title: str = "Portfolio Summary", 

72 log_scale: bool = False, 

73 *, 

74 backend: Backend | None = None, 

75 ) -> Figure: 

76 """Create a comprehensive dashboard with multiple plots for portfolio analysis. 

77 

78 This function generates a three-panel plot showing: 

79 1. Cumulative returns over time 

80 2. Drawdowns over time 

81 3. Monthly returns over time 

82 

83 This provides a complete visual summary of portfolio performance. 

84 

85 Args: 

86 title: Accepted for backward compatibility but not used — the 

87 chart titles itself from the assets it plots. 

88 log_scale: Whether to use logarithmic scale for cumulative returns. 

89 Defaults to False. 

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

91 

92 Returns: 

93 Figure: A three-panel dashboard. 

94 

95 Example: 

96 >>> import polars as pl 

97 >>> from jquantstats import Data 

98 >>> # minimal demo dataset with a Date column and one asset 

99 >>> returns = pl.DataFrame({ 

100 ... "Date": ["2023-01-01", "2023-01-02", "2023-01-03"], 

101 ... "Asset": [0.01, -0.02, 0.03], 

102 ... }).with_columns(pl.col("Date").str.to_date()) 

103 >>> data = Data.from_returns(returns=returns) 

104 >>> fig = data.plots.snapshot(title="My Portfolio Performance") 

105 >>> # Optional: display the interactive figure 

106 >>> fig.show() # doctest: +SKIP 

107 

108 """ 

109 return render(data_snapshot_spec(self._data, log_scale=log_scale), backend)