Adding a New Plot

When implementing your strategy or exchange classes, you may need to track and visualize various parameters over time. The PlotData object, initiated in the BaseExchange class, provides a flexible and powerful way to define and manage custom plots.

The PlotData object allows you to create multiple time series plots grouped under unique topics. These plots can include both line charts and scatter plots, enabling visualization of diverse data types, such as order locations, performance metrics, and price trends.

Plots created using the PlotData object can be retrieved programmatically via the Plot Topics API or viewed interactively in the ATS Trading UI, making them accessible for analysis and debugging.

Accessing the PlotData Object

The PlotData object is initiated within the BaseExchange class. To access it, use the exchange.get_plot_data() method:

plot_data = exchange.get_plot_data()

This ensures the PlotData object is used in the context of the exchange, maintaining consistency and access to pre-defined topics.

Defining a Plot

Before recording data points, you must define a plot by setting a topic. A topic acts as a unique key for grouping related time series data. Each topic must have a unique name.

Parameters for Defining a Plot

  • topic: A unique string identifying the topic of the plot.

  • color: Color of the plot in hexadecimal (e.g., #FF5733).

  • lines_or_markers:

    • "lines": Creates a line plot.

    • "markers": Creates a scatter plot.

  • pattern:

    • Supported patterns for scatter plots: "circle", "triangle-up", "triangle-down".

    • Supported patterns for line plots: "dashdot", "dash", "dot", "solid".

Example: Defining a Plot

plot_data.set_topic(
    topic="My Custom Metric",
    color="#3498db",
    lines_or_markers="lines",
    pattern="dash"
)

Recording Data Points

After defining a topic, you can record data points using the add() method. Each data point consists of:

  • topic: The topic under which the data is grouped.

  • time: The timestamp for the data point (must be a datetime object).

  • num: The numeric value of the data point.

  • label (optional): A string label displayed for marker plots when hovered over.

Example: Recording a Data Point

from datetime import datetime

plot_data.add(
    topic="My Custom Metric",
    time=datetime.now(),
    num=42,
    label="Custom Label"
)

Plotting Topics

The plot_topics() method allows you to visualize defined topics. You can create multiple subplots, specify rows and columns, and compress the graph to reduce resolution for large datasets.

Parameters for Plotting

  • plots: A list of dictionaries specifying the topic and its subplot location:

    plots = [
        {"topic": "My Custom Metric", "row": 1, "col": 1},
        {"topic": "Another Metric", "row": 1, "col": 2}
    ]
  • rows: Total number of rows in the grid layout.

  • cols: Total number of columns in the grid layout.

  • length: Length of the time window to display (default is the full dataset).

  • plot_compressed: If True, compresses the graph to reduce the number of data points.

  • plot_compressed_size: The resolution of the compressed plot in data points.

Example: Plotting Topics

fig = plot_data.plot_topics(
    plots=[
        {"topic": "My Custom Metric", "row": 1, "col": 1}
    ],
    rows=1,
    cols=1
)
fig.show()

Managing Topics

Check If a Topic Exists

if plot_data.is_topic_exist("My Custom Metric"):
    print("Topic exists!")

List All Topics

topics = plot_data.get_topics()
print("Available topics:", topics)

Example Use Case

Defining and Visualizing a Custom Plot

# Access PlotData object
plot_data = exchange.get_plot_data()

# Define a custom plot
plot_data.set_topic(
    topic="Trade Volume",
    color="#e74c3c",
    lines_or_markers="markers",
    pattern="circle"
)

# Add data points
from datetime import datetime
plot_data.add(topic="Trade Volume", time=datetime.now(), num=150, label="Order ID: 123")

# Plot the topic
fig = plot_data.plot_topics(
    plots=[{"topic": "Trade Volume", "row": 1, "col": 1}],
    rows=1,
    cols=1
)
fig.show()

Summary

The PlotData object offers robust functionality for defining, recording, and visualizing time series data. By leveraging its flexible API, you can easily track and display various parameters in your trading strategies and exchanges.

Last updated