0
# Data Visualization
1

2
The chart_wrapper function and Chart class provide integrated charting and visualization capabilities supporting multiple chart types with pandas DataFrame integration through the vnstock_ezchart library.
3

4
## Capabilities
5

6
### Chart Wrapper Class Alias
7

8
The chart_wrapper is an alias for the Chart class imported from vnstock_ezchart, providing direct access to Chart functionality.
9

10
```python { .api }
11
# chart_wrapper is an alias for the Chart class
12
chart_wrapper = Chart
13

14
# Usage: Create Chart instance directly
15
chart = chart_wrapper(data)  # Same as: chart = Chart(data)
16
```
17

18
### Chart Class
19

20
Comprehensive charting class with multiple visualization types and pandas integration.
21

22
```python { .api }
23
class Chart:
24
    """
25
    Chart class for creating various visualization types.
26
    """
27
    
28
    def __init__(self, data: Union[pd.DataFrame, pd.Series]):
29
        """
30
        Initialize Chart with data.
31
        
32
        Args:
33
            data (Union[pd.DataFrame, pd.Series]): Data for visualization
34
        """
35
    
36
    def help(self, func_name: str):
37
        """Display function docstring for specified chart method."""
38
```
39

40
### Chart Types
41

42
Comprehensive set of chart types for financial data visualization.
43

44
```python { .api }
45
def bar(self, **kwargs):
46
    """Create bar chart visualization."""
47

48
def hist(self, **kwargs):
49
    """Create histogram visualization."""
50

51
def pie(self, labels=None, values=None, **kwargs):
52
    """
53
    Create pie chart visualization.
54
    
55
    Args:
56
        labels: Labels for pie segments
57
        values: Values for pie segments
58
    """
59

60
def timeseries(self, **kwargs):
61
    """Create time series line chart - ideal for price data."""
62

63
def heatmap(self, **kwargs):
64
    """Create heatmap visualization for correlation matrices."""
65

66
def scatter(self, x: str, y: str, **kwargs):
67
    """
68
    Create scatter plot.
69
    
70
    Args:
71
        x (str): Column name for X-axis
72
        y (str): Column name for Y-axis
73
    """
74

75
def treemap(self, values, labels, **kwargs):
76
    """
77
    Create treemap visualization.
78
    
79
    Args:
80
        values: Values for treemap sizing
81
        labels: Labels for treemap segments
82
    """
83

84
def boxplot(self, **kwargs):
85
    """Create box plot for distribution analysis."""
86

87
def pairplot(self, **kwargs):
88
    """Create pairwise relationship plots."""
89

90
def wordcloud(self, show_log=False, **kwargs):
91
    """
92
    Create word cloud visualization.
93
    
94
    Args:
95
        show_log (bool): Enable logging, defaults to False
96
    """
97

98
def table(self, **kwargs):
99
    """Create formatted table display."""
100

101
def combo(self, bar_data, line_data, **kwargs):
102
    """
103
    Create combination chart with bar and line elements.
104
    
105
    Args:
106
        bar_data: Data for bar chart component
107
        line_data: Data for line chart component
108
    """
109
```
110

111
### Pandas Integration
112

113
Seamless integration with pandas DataFrames and Series through the `viz` property.
114

115
```python { .api }
116
# Pandas extensions added by vnstock
117
pd.DataFrame.viz  # Chart instance for DataFrame
118
pd.Series.viz     # Chart instance for Series
119
```
120

121
## Usage Examples
122

123
### Basic Chart Creation
124

125
```python
126
import pandas as pd
127
from vnstock import chart_wrapper, Vnstock
128

129
# Get some stock data
130
stock = Vnstock()
131
tcb_data = stock.stock(symbol="TCB", source="VCI")
132
price_data = tcb_data.quote.history(start="2023-01-01", end="2023-12-31")
133

134
# Create charts using chart_wrapper
135
chart = chart_wrapper(price_data)
136

137
# Time series chart for stock prices
138
chart.timeseries()
139

140
# Volume bar chart  
141
chart.bar()
142

143
# Price distribution histogram
144
chart.hist()
145
```
146

147
### Using Pandas Integration
148

149
```python
150
# Direct pandas integration via .viz property
151
price_data.viz.timeseries()
152
price_data['volume'].viz.bar()
153
price_data['close'].viz.hist()
154

155
# Correlation heatmap
156
correlation_matrix = price_data[['open', 'high', 'low', 'close']].corr()
157
correlation_matrix.viz.heatmap()
158
```
159

160
### Advanced Visualizations
161

162
```python
163
# Scatter plot for price vs volume analysis
164
chart.scatter(x='volume', y='close')
165

166
# Combo chart - volume bars with price line
167
chart.combo(
168
    bar_data=price_data['volume'],
169
    line_data=price_data['close']
170
)
171

172
# Box plot for price distribution analysis
173
chart.boxplot()
174

175
# Pie chart for portfolio allocation
176
portfolio_data = pd.Series([30, 25, 20, 15, 10], 
177
                          index=['TCB', 'VCB', 'BID', 'HPG', 'FPT'])
178
portfolio_chart = chart_wrapper(portfolio_data)
179
portfolio_chart.pie()
180
```
181

182
### Financial Data Specific Examples
183

184
```python
185
# Stock price time series with multiple companies
186
multi_stock_data = pd.DataFrame({
187
    'TCB': tcb_price_data['close'],
188
    'VCB': vcb_price_data['close'],
189
    'BID': bid_price_data['close']
190
})
191

192
multi_chart = chart_wrapper(multi_stock_data)
193
multi_chart.timeseries()
194

195
# Trading volume analysis
196
volume_data = price_data['volume']
197
volume_chart = chart_wrapper(volume_data)
198
volume_chart.bar()
199
volume_chart.hist()
200

201
# Price correlation analysis
202
price_corr = multi_stock_data.corr()
203
price_corr.viz.heatmap()
204

205
# Financial ratio comparison
206
ratio_data = pd.DataFrame({
207
    'ROE': [15.2, 18.5, 12.8],
208
    'ROA': [1.2, 1.8, 1.1], 
209
    'NPM': [25.5, 30.2, 22.1]
210
}, index=['TCB', 'VCB', 'BID'])
211

212
ratio_chart = chart_wrapper(ratio_data)
213
ratio_chart.bar()
214
```
215

216
### Interactive Help
217

218
```python
219
# Get help for specific chart methods
220
chart.help('timeseries')
221
chart.help('combo')
222
chart.help('heatmap')
223
```
224

225
## Integration with VNStock Data
226

227
The visualization capabilities are designed to work seamlessly with all VNStock data sources:
228

229
- **Quote Data**: Time series charts for price and volume
230
- **Financial Data**: Bar charts for financial metrics comparison  
231
- **Company Data**: Pie charts for shareholder distribution
232
- **Trading Data**: Heatmaps for trading flow analysis
233
- **Fund Data**: Treemaps for portfolio allocation
234
- **Screening Results**: Scatter plots for ratio analysis
235

236
The Chart class automatically handles data formatting and provides appropriate visualization defaults for financial data types.