Skip to main content

Module visualization

optionstratlib_visualization

Module visualization 

Source
Expand description

Chart models, the Graph contract and its implementations.

§Visualization

§Visualization Library Usage Guide

This guide explains how to use the visualization layer to create financial charts and other types of visualizations.

§Setup

The chart data builds with no feature; rendering through plotly.rs needs plotly, and PNG/SVG export needs static_export:

[dependencies]
optionstratlib-visualization = { version = "0.22.1", features = ["plotly"] }

§Core Concepts

The library follows a domain modeling pattern where it separates:

  1. What to visualize (the data to represent)
  2. How to visualize it (styles and configuration)
  3. Where to display it (browser, HTML file, PNG image)

§Main Trait: Graph

The Graph trait is the central component that any object wanting to be visualized must implement:

ⓘ
use optionstratlib_visualization::visualization::{GraphConfig, GraphData};

pub trait Graph {
    fn graph_data(&self) -> GraphData;
     
    fn graph_config(&self) -> GraphConfig {
        GraphConfig::default()
    }
     
    // Rendering methods provided under `plotly` and `static_export`...
}

To create a chart, you only need to implement:

  • graph_data(): to provide the data to visualize
  • Optionally, graph_config(): to customize the appearance

The trait has this one definition on every feature surface; the backend features only add provided rendering methods (to_plot, write_html, show, render, to_interactive_html under plotly, and write_png, write_svg under static_export), so an implementation written without a backend compiles unchanged with one.

§Data Types

The library supports these types of visualizations through the GraphData enum:

use optionstratlib_visualization::visualization::{MultiSeries2D, Series2D, Surface3D};

pub enum GraphData {
    Series(Series2D),              // Line or scatter 2D
    MultiSeries(MultiSeries2D),    // Multiple 2D series
    GraphSurface(Surface3D),       // 3D surface
}

§Example: Simple Line Chart

use std::fs;
use std::path::{Path, PathBuf};
use rust_decimal::Decimal;
use rust_decimal_macros::dec;
use optionstratlib_visualization::visualization::{Graph, GraphData, Series2D, GraphConfig, OutputType};
use optionstratlib_visualization::visualization::{LineStyle, ColorScheme, TraceMode};

struct MyData {
    x: Vec<Decimal>,
    y: Vec<Decimal>,
}

impl Graph for MyData {
    fn graph_data(&self) -> GraphData {
        GraphData::Series(Series2D {
            x: self.x.clone(),
            y: self.y.clone(),
            name: "My series".to_string(),
            mode: TraceMode::Lines,
            line_color: Some("#1f77b4".to_string()),
            line_width: Some(2.0),
        })
    }

    fn graph_config(&self) -> GraphConfig {
        GraphConfig {
            title: "My chart".to_string(),
            width: 800,
            height: 600,
            x_label: Some("X Axis".to_string()),
            y_label: Some("Y Axis".to_string()),
            z_label: None,
            line_style: LineStyle::Solid,
            color_scheme: ColorScheme::Viridis,
            legend: None,
            show_legend: false,
        }
    }
}
#[cfg(feature = "static_export")]
{
    // Using the chart
    let data = MyData {
        x: vec![dec!(1.0), dec!(2.0), dec!(3.0), dec!(4.0), dec!(5.0)],
        y: vec![dec!(2.0), dec!(3.0), dec!(5.0), dec!(7.0), dec!(11.0)],
    };
    // Display in browser
    data.show();
    // Save as PNG
    let filename: PathBuf = PathBuf::from("my_chart.png");
    data.render(OutputType::Png(&filename))?;
    if Path::new(&filename.clone()).exists() {
        fs::remove_file(filename.clone())?;
    }
}

§Example: 3D Surface


use rust_decimal::Decimal;
use optionstratlib_visualization::visualization::{ColorScheme, Graph, GraphConfig, GraphData, LineStyle, Surface3D};

struct SurfaceData {
    x: Vec<Decimal>,
    y: Vec<Decimal>,
    z: Vec<Decimal>,
}

impl Graph for SurfaceData {
    fn graph_data(&self) -> GraphData {
        GraphData::GraphSurface(Surface3D {
            x: self.x.clone(),
            y: self.y.clone(),
            z: self.z.clone(),
            name: "My surface".to_string(),
        })
    }

    fn graph_config(&self) -> GraphConfig {
        GraphConfig {
            title: "3D Surface".to_string(),
            width: 800,
            height: 600,
            x_label: Some("X".to_string()),
            y_label: Some("Y".to_string()),
            z_label: Some("Z".to_string()),
            line_style: LineStyle::Solid,
            color_scheme: ColorScheme::Plasma,
            legend: None,
            show_legend: false,
         }
    }
}

§Color Schemes

The library provides several predefined color schemes:

  • ColorScheme::Default: Uses plotly’s default colors
  • ColorScheme::Viridis: A color palette ranging from violet to yellow
  • ColorScheme::Plasma: A color palette ranging from dark blue to yellow
  • ColorScheme::Custom(Vec<String>): Define your own colors as hexadecimal strings

§Line Styles

You can customize lines with:

  • LineStyle::Solid: Continuous line
  • LineStyle::Dotted: Dotted line
  • LineStyle::Dashed: Dashed line

§Display Modes

For 2D series, you can choose how to display points:

  • TraceMode::Lines: Lines only
  • TraceMode::Markers: Markers (points) only
  • TraceMode::LinesMarkers: Both lines and markers

§Error Handling

The library provides a GraphError type that encapsulates graph-specific errors and I/O errors. All methods that can fail return Result<(), GraphError>.

§Advanced Tips

§Serialization and Deserialization

All main types implement serde::Serialize and serde::Deserialize, allowing you to save and load chart configurations in JSON or other compatible formats.

§Multiple Series

For charts with multiple series, use the GraphData::MultiSeries type:

use rust_decimal_macros::dec;
use optionstratlib_visualization::visualization::{GraphData, Series2D, TraceMode};
let series1 = Series2D {
    x: vec![dec!(1.0), dec!(2.0), dec!(3.0)],
    y: vec![dec!(4.0), dec!(5.0), dec!(6.0)],
    name: "Series 1".to_string(),
    mode: TraceMode::Lines,
    line_color: Some("#1f77b4".to_string()),
    line_width: Some(2.0),
};

let series2 = Series2D {
    x: vec![dec!(1.0), dec!(2.0), dec!(3.0)],
    y: vec![dec!(7.0), dec!(8.0), dec!(9.0)],
    name: "Series 2".to_string(),
    mode: TraceMode::Markers,
    line_color: Some("#ff7f0e".to_string()),
    line_width: Some(2.0),
};

let graph_data = GraphData::MultiSeries(vec![series1, series2]);

§Interactive HTML Generation

If you need interactive HTML with advanced hover and tooltip functions, use the to_interactive_html method:

use optionstratlib_visualization::visualization::{Graph, GraphData, Series2D, TraceMode, GraphConfig};
use optionstratlib_visualization::error::GraphError;
use std::path::PathBuf;
use tracing::info;
use rust_decimal_macros::dec;
struct SimpleChart {
    series: Series2D
}

impl Graph for SimpleChart {
    fn graph_data(&self) -> GraphData {
        GraphData::Series(self.series.clone())
    }
     
    fn graph_config(&self) -> GraphConfig {
        GraphConfig {
            title: "Interactive Chart Example".into(),
            width: 800,
            height: 600,
            x_label: Some("X Axis".into()),
            y_label: Some("Y Axis".into()),
            ..GraphConfig::default()
        }
    }
}

fn main() -> Result<(), GraphError> {
    use std::fs;
use std::path::Path;
let series = Series2D {
        x: vec![dec!(1.0), dec!(2.0), dec!(3.0)],
        y: vec![dec!(4.0), dec!(5.0), dec!(6.0)],
        name: "Series 1".to_string(),
        mode: TraceMode::Lines,
        line_color: Some("#1f77b4".to_string()),
        line_width: Some(2.0),
    };
     
    #[cfg(feature = "static_export")]
    {
    let chart = SimpleChart { series };
    let filename: PathBuf = PathBuf::from("interactive_chart.html");
    chart.to_interactive_html(&filename)?;
    info!("Interactive HTML chart created successfully!");
    if Path::new(&filename.clone()).exists() {
            fs::remove_file(filename.clone())?;
        }
    }
    Ok(())
}

§Complete Examples

Check the examples/ directory for practical examples, including:

  • Stock price charts with moving averages
  • Volatility surfaces for options
  • Scatter plots with multiple series

§Adaptation to Your Needs

GraphData is a closed enum, so a downstream crate cannot add variants to it. To chart a new type, implement Graph for it: build one of the existing GraphData variants in graph_data() and style it through graph_config(). A new kind of chart (a variant, or a change to to_plot) is a change to this crate.

Enjoy visualizing your financial data!

Modules§

terminal
Terminal tables for chain and simulation reports: the explicit adapter that writes them to stdout (M6-05). Terminal tables for chain and simulation reports.

Structs§

GraphConfig
Represents the configuration parameters for a graph or chart visualization.
Label2D
A text label attached to a 2D point for displaying information on a 2D plot.
Label3D
A text label attached to a 3D point for displaying information on a 3D plot.
PlotBuilder
A builder for creating and configuring data visualizations.
Series2D
Represents a two-dimensional data series for plotting.
Surface3D
A struct representing a 3D surface plot.
VisPoint2D
A 2D point representation for plotting in a 2D coordinate system.
VisPoint3D
A 3D point representation for plotting in a 3D coordinate system.

Enums§

ColorScheme
Represents the color scheme used for visualizations.
GraphData
Represents different types of graph data for visualization.
LineStyle
Represents the visual style of a line in graphical elements.
OutputType
Represents the different output types for saving or displaying plots.
PlotType
Represents different types of plots that can be generated.
TraceMode
Defines the visual appearance of traces in plots.

Traits§

Graph
Chart contract of every type the library can draw: strategies, option chains’ curves and surfaces, options, positions and simulations.
GraphType
A trait defining the type of graph or plot used for visualization purposes.
Plottable
Trait for defining objects that can be visualized as plots.

Functions§

get_color_from_scheme
Get color from a color scheme based on index
make_scatter
Creates a Scatter trace from a Series2D and configuration
make_surface
Creates a 3D surface representation wrapped in a Box, based on the input Surface3D structure.
pick_color
Pick a color from config based on index
prepare_file_path
Prepares a path for writing by removing any existing file and creating necessary directories.
to_plotly_mode
Utility function to convert TraceMode to Mode

Type Aliases§

MultiSeries2D
A type alias representing a collection of 2D series.