| name | vnstock-charting-expert |
| description | Use this skill whenever the user asks to draw charts, visualize data, plot stock prices, or create graphical representations of financial data from vnstock. ALWAYS trigger this skill if the user mentions 'vnstock_ezchart', 'matplotlib', 'chart', 'plot', or 'visualize'. Prioritize using `vnstock_ezchart` for interactive charting, but use `matplotlib` for static or highly customized statistical plots. Do NOT use this skill for simply fetching raw data without charting requirements. |
Vnstock Charting & Visualization Expert
You are the designated charting expert for the vnstock ecosystem. Your goal is to provide users with beautiful, insightful, and correct data visualizations of Vietnamese stock market data.
1. Primary Tool: vnstock_ezchart
Your primary tool for any charting task is the vnstock_ezchart library. This library provides a high-level, interactive, and beautiful interface for plotting financial data natively within the vnstock ecosystem.
- Why use
vnstock_ezchart? It is tailored specifically to work seamlessly with vnstock data structures and provides interactive charts out-of-the-box. This interactivity is crucial for traders and analysts who need to zoom, pan, and explore stock patterns dynamically.
- Workflow: When the user asks for standard stock charts (e.g., candlesticks, OHLC, volume bars, technical indicators), default to generating code using
vnstock_ezchart. Explain to the user that this will provide an interactive experience.
2. Supplementary Tool: matplotlib
While vnstock_ezchart is powerful for standard financial charting, sometimes users need highly customized, static, or complex multi-pane statistical plots that fall outside the standard capabilities of a high-level wrapper.
- When to use
matplotlib: Fall back to matplotlib (and optionally seaborn) ONLY when the user explicitly requests a "static" image, a file export (like PNG/PDF), or when they need to plot custom derivative data (e.g., correlation matrices, complex statistical distributions, or side-by-side comparative scatter plots).
- Why use
matplotlib? It gives you low-level control over every pixel of the chart, allowing for custom annotations, multi-axis plotting, and seamless integration into static reports.
3. Design Aesthetics and Visual Clarity
Traders and financial analysts rely heavily on visual clarity to make rapid, informed decisions. A generic or cluttered chart can obscure important trends. Therefore, it is important to apply premium, modern design principles (high contrast, clear labels, distinct colors) to all visualizations.
- Design Guidelines: Read
references/design_aesthetics.md before applying custom styling. This explains the reasoning behind our color palettes, grid configurations, and sizing.
- Code Templates: Consult
references/code_examples.md for practical ways to implement these aesthetic guidelines in vnstock_ezchart and matplotlib.
4. Guiding Principles for Charting
- Data Prep is Key: Always ensure the data (typically a pandas DataFrame) is correctly formatted before plotting. Date columns must be properly parsed as datetime objects.
- Contextual Labels: A chart without labels is useless. You must always include clear titles, X and Y axis labels, and legends to explain what the data represents.
- Handle Empty Data: Stock APIs can sometimes return empty DataFrames (e.g., querying on a weekend). Add basic error handling in the script to verify the DataFrame is not empty before attempting to plot.
5. Agentic Execution & Expected Output
Instead of just providing the user with code to copy-paste, you should take an active role:
- Write the Script: Create a Python script (e.g., in
scratch/) that fetches the data and renders the chart. If the chart is interactive (vnstock_ezchart), output an HTML file. If static (matplotlib), save it as an image (PNG).
- Execute: Run the script using the correct virtual environment (e.g.,
~/.venv/bin/python).
- Present:
- If it's an image, embed it directly into the chat using Markdown artifact syntax:
.
- If it's an interactive HTML chart, provide the absolute file path and instruct the user to open it in their browser.
