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 

6 

7import plotly.graph_objects as go 

8 

9from ._cumulative import _CumulativePlotsMixin 

10from ._dashboard import _plot_performance_dashboard 

11from ._distribution import _DistributionPlotsMixin 

12from ._drawdown import _DrawdownPlotsMixin 

13from ._montecarlo import _MonteCarloPlotsMixin 

14from ._periodic import _PeriodicPlotsMixin 

15from ._rolling import _RollingPlotsMixin 

16 

17if TYPE_CHECKING: 

18 from jquantstats._protocol import DataLike 

19 

20 

21class DataPlots( 

22 _CumulativePlotsMixin, 

23 _PeriodicPlotsMixin, 

24 _DistributionPlotsMixin, 

25 _MonteCarloPlotsMixin, 

26 _DrawdownPlotsMixin, 

27 _RollingPlotsMixin, 

28): 

29 """Visualization tools for financial returns data. 

30 

31 This class provides methods for creating various plots and visualizations 

32 of financial returns data, including: 

33 

34 - Returns bar charts 

35 - Portfolio performance snapshots 

36 - Monthly returns heatmaps 

37 

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

39 for creating interactive visualizations. 

40 """ 

41 

42 __slots__ = ("_data",) 

43 

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

45 self._data = data 

46 

47 @property 

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

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

50 return self._data.assets 

51 

52 def __repr__(self) -> str: 

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

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

55 

56 def snapshot(self, title: str = "Portfolio Summary", log_scale: bool = False) -> go.Figure: 

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

58 

59 This function generates a three-panel plot showing: 

60 1. Cumulative returns over time 

61 2. Drawdowns over time 

62 3. Daily returns over time 

63 

64 This provides a complete visual summary of portfolio performance. 

65 

66 Args: 

67 title (str, optional): Title of the plot. Defaults to "Portfolio Summary". 

68 compounded (bool, optional): Whether to use compounded returns. Defaults to True. 

69 log_scale (bool, optional): Whether to use logarithmic scale for cumulative returns. 

70 Defaults to False. 

71 

72 Returns: 

73 go.Figure: A Plotly figure object containing the dashboard. 

74 

75 Example: 

76 >>> import polars as pl 

77 >>> from jquantstats import Data 

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

79 >>> returns = pl.DataFrame({ 

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

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

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

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

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

85 >>> # Optional: display the interactive figure 

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

87 

88 """ 

89 fig = _plot_performance_dashboard(returns=self._data.all, log_scale=log_scale) 

90 return fig