4. HistoryPanel Visualization

The previous chapter, HistoryPanel (Historical Data Panel), introduced how to align historical data from multiple targets and indicators onto the same panel. This chapter explains how to directly plot data using the panel: Compared to “first using to_share_frame and then manually writing matplotlib code”, HistoryPanel.plot() automatically combines views such as candlestick charts, volume, MACD, and line charts based on the current htypes, ensuring consistency between the context of data exploration and the strategy research phase.

4.1. hp.plot(): Recommended unified entry point

In this project, HistoryPanel.plot() is the only recommended entry point for plotting (if the old interface still exists, it should also be semantically delegated to the same pipeline). You only need to ensure that the panel is not empty and contains the columns required for plotting (e.g., a complete OHLC is required to generate a candlestick chart); other chart types will be automatically determined internally based on htypes.

The meanings of commonly used parameters are as follows (see HistoryPanel API for the complete signature):

Parameters

Function Summary

shares

A subset of the targets to be drawn; by default, all targets in the panel are used.

layout

Multi-target layouts: “overlay” (overlaying within the same coordinate system), “stack” (grouping and faceting vertically), “auto” (e.g., two targets tend to be overlayed, more are stacked).

interactive

False uses a static plot from matplotlib; True uses an interactive plot from Plotly (zoom, pan, hover, etc.).

highlight

Highlight extreme values, such as ‘max’ / ‘min’, or pass in a configuration dictionary.

plotly_backend_app

Only valid when interactive=True: 'auto' (prefers FigureWidget, falls back to HTML wrapper if it fails), 'FigureWidget', 'html'.

Note: When the number of requested targets is large, the implementation may limit the number of targets actually drawn and issue a warning to avoid overloading a single graph; the specific behavior is subject to the current version. For details on minor adjustments to the layout of multiple targets and historical fixes, please refer to the relevant entries in RELEASE_HISTORY 2.2.x.

4.2. Static diagrams and interactive diagrams

  • **interactive=False (default): Depends on matplotlib, suitable for batch plotting and generating static files using scripts; does not force the installation of Plotly.

  • interactive=True: Depends on plotly; in Jupyter, if anywidget and ipywidgets are available, you can usually get a FigureWidget, which has more complete interaction between the header and axes; otherwise, it may fall back to the HTML wrapper form, which still has basic interaction, but the experience is slightly different from the Widget path.

Minimalist example (requires existing OHLCV or equivalent columns locally; for demonstration purposes only):

import qteasy as qt

hp = qt.get_history_data(
    htype_names='open, high, low, close, vol',
    shares='000300.SH',
    rows=120,
    as_data_frame=False,
)
fig = hp.plot()                      # 静态
# fig2 = hp.plot(interactive=True)  # 交互（需安装 plotly 等）

When the main chart is a candlestick chart, the static chart will display an OHLC summary on the last candlestick on the timeline; the interactive chart is consistent by default, and clicking on a candlestick will update the summary to that candlestick (the summary text for the user is in English). This summary area will not appear if there is no complete OHLC.

4.3. Layout and multiple targets

  • overlay: Suitable for comparing the price movements of a few targets (such as two stocks) at the same price scale (whether they share the y-axis depends on the current implementation).

  • **stack: Each target (or group) occupies a separate sub-plot, suitable for a large number of targets and to avoid them being crammed into the same coordinate system.

  • auto: When the number of targets is small, it tends to stack them; when the number is large, it tends to split them into facets, reducing manual trial and error.

If the layout semantics are adjusted in a later version, the description in the corresponding version’s RELEASE_HISTORY shall prevail.

4.4. Dependency and Installation Tips

  • Static plots: generally require matplotlib (the same environment commonly used with qteasy).

  • Interactive Graphs: Requires plotly; for a complete Notebook interactive experience, it is recommended to install both ipywidgets and anywidget. The version range of optional dependencies is based on the project’s pyproject.toml or the installation documentation; this document does not list version numbers individually.

The underlying rendering module name and extension point are only for developers to use when reading the source code; the user documentation does not elaborate on the file-level implementation details.

4.5. summary

  • Data preparation is still done using get_history_data, consistent with Previous Chapter; plotting is done using hp.plot().

  • interactive and layout are the two switches that are most frequently modified in daily use; see the API documentation for advanced parameters.

  • For behavior changes and visualization-related fixes, please refer to RELEASE_HISTORY; for hands-on exercises, please refer to the tutorial Using HistoryPanel to Manipulate and Analyze Historical Data.