Crate optionstratlib_visualization

Expand description

§optionstratlib-visualization

Charts for OptionStratLib: backend-neutral chart models, the one visualization::Graph contract, its implementations for the library’s types, and an optional Plotly backend. It is the leaf of the workspace: it depends on optionstratlib-core, optionstratlib-math, optionstratlib-pricing, optionstratlib-simulation, optionstratlib-market, optionstratlib-strategies and optionstratlib-backtest, and no OptionStratLib crate depends on it, so headless consumers never build it.

visualization: the visualization::Graph trait, the chart data (visualization::GraphData, visualization::Series2D, visualization::Surface3D), visualization::GraphConfig and the styles, visualization::PlotBuilder and visualization::Plottable, and the Graph implementations for options, positions, curves, surfaces, random walks, simulators and every concrete strategy.
visualization::terminal: terminal tables for option chains and simulation statistics, the only code in the library that writes to stdout, and only when asked to (visualization::terminal::ChainReport, visualization::terminal::SimulationReport).
error: the error::GraphError type.

§One graph contract

visualization::Graph has the same definition and the same required items on every feature surface: an implementor supplies graph_data and may override graph_config, whatever backend is enabled. The backend features add provided rendering methods to it and never change what an implementor writes:

Surface	Provided by `Graph`
no features	`graph_data`, `graph_config`
`plotly`	the above, plus `to_plot`, `write_html`, `show`, `render`, `to_interactive_html`
`static_export`	the above, plus `write_png`, `write_svg`

visualization::OutputType has the same variants everywhere; asking render for a PNG or SVG without static_export returns error::GraphError::Render rather than doing nothing.

§Adapters

Every chart of a library type is a Graph implementation in this crate. The orphan rule allows impl Graph for T only in the crate of Graph or in the crate of T, and no lower crate may depend on this one, so every adapter lives here: the lower crates name no chart type, and no domain type is wrapped or copied to chart it.

Type	Defining crate	Adapter module	Chart
`Options`, `Position`	core	`model_impls`	payoff at expiry, split into a positive and a negative series
`Curve`, `Vec<Curve>`	math	`curves`	one series per curve
`Surface`	math	`surfaces`	one 3D surface
`RandomWalk`, `Simulator`	simulation	`simulation`	one price series per walk
the 22 concrete strategies	strategies	`strategies` (`impl_graph_for_payoff_strategy!`)	profit and loss over the strategy’s price range, with the break-even, current-price and P&L markers
`visualization::PlotBuilder`	visualization	`plot_builder`	the wrapped value’s data under the builder’s configuration

tests/graph_data_golden_test.rs pins the data and configuration of every row against the output of the same adapters before they moved into this crate.

§Charting a strategy

The strategy contract has no Graph supertrait: a strategy is charted because this crate implements Graph for it, so code that renders names the bound (T: Strategies + Graph) and code that does not never builds this crate. The capability this changes is the boxed strategy: StrategyRequest::get_strategy returns a Box<dyn Strategable>, which has no chart. A consumer that renders a strategy built from positions names the concrete type, through StrategyConstructor, or keeps its own object type with both bounds:

use optionstratlib_core::model::{ExpirationDate, Position, Positive};
use optionstratlib_core::pos_or_panic;
use optionstratlib_strategies::strategies::base::{Positionable, StrategyType};
use optionstratlib_strategies::strategies::{
    BullCallSpread, Strategable, Strategies, StrategyConstructor, StrategyRequest,
};
use optionstratlib_visualization::visualization::{Graph, GraphData};
use rust_decimal::Decimal;

/// A consumer that renders names the bound itself.
fn payoff_series<S: Strategies + Graph>(strategy: &S) -> usize {
    match strategy.graph_data() {
        GraphData::MultiSeries(series) => series.len(),
        GraphData::Series(_) => 1,
        GraphData::GraphSurface(_) => 0,
    }
}

/// An object type for strategies that can be charted.
trait Chartable: Strategable + Graph {}
impl<T: Strategable + Graph> Chartable for T {}

/// Builds the strategy a request names, as a chartable object.
fn build(request: &StrategyRequest) -> Result<Box<dyn Chartable>, Box<dyn std::error::Error>> {
    match &request.strategy_type {
        StrategyType::BullCallSpread => {
            Ok(Box::new(BullCallSpread::get_strategy(&request.positions)?))
        }
        other => Err(format!("{other:?} is not charted here").into()),
    }
}

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let strategy = BullCallSpread::new(
        "AAPL".to_string(),
        pos_or_panic!(100.0),
        pos_or_panic!(95.0),
        pos_or_panic!(105.0),
        ExpirationDate::Days(pos_or_panic!(30.0)),
        pos_or_panic!(0.25),
        Decimal::new(5, 2),   // risk-free rate, 5% per year
        Positive::ZERO,       // dividend yield
        Positive::ONE,        // quantity
        pos_or_panic!(2.50),  // long call premium
        pos_or_panic!(1.20),  // short call premium
        Positive::ZERO,       // open and close fees of each leg
        Positive::ZERO,
        Positive::ZERO,
        Positive::ZERO,
    )?;
    // The payoff chart: profit and loss over the strategy's price range.
    assert!(payoff_series(&strategy) > 0);
    // With `plotly`, the same value renders; `write_html` writes the page.
    #[cfg(feature = "plotly")]
    assert!(!strategy.to_plot().to_json().is_empty());

    // The same strategy as a request carries it, as positions: built back
    // through the builder, it charts the same.
    let positions: Vec<Position> = strategy.get_positions()?.into_iter().cloned().collect();
    let request = StrategyRequest::new(StrategyType::BullCallSpread, positions);
    let rebuilt = build(&request)?;
    assert_eq!(rebuilt.graph_data(), strategy.graph_data());
    Ok(())
}

§Imports

There is no prelude, as in the other component crates (ADR-0001 D7): the module roots re-export each capability, and the optionstratlib facade prelude serves broad imports.

§Place in the workspace

Depends on optionstratlib-core, -math, -pricing, -simulation, -market, -strategies and -backtest.
Must not be a dependency of any other OptionStratLib crate: it is the leaf of the layering, and only the optionstratlib facade depends on it; make check-graph enforces the layering (ADR-0001 D9).
In the facade: optionstratlib::visualization, GraphError and the aggregate Error in optionstratlib::error and the root impl_graph_for_payoff_strategy!, under the facade feature visualization; the facade’s plotly and static_export forward to the features below. The facade paths are the same types as the paths here; the ownership map lists every one with its feature.

Moving from 0.22? PNG and SVG export changed in 0.23: see the 0.23 migration guide and the “Static export” section below.

Moving from 0.21? The 0.22 architecture and adoption guide maps each redesign to its replacement workflow; 0.22 keeps no compatibility with 0.21.

§Example

A runnable program that depends on this crate directly, with the smallest dependency set and no facade, is osl-example-direct-visualization; make tree-example-direct-visualization asserts its resolved graph.

§Features

plotly (off by default): Plotly rendering and the trace builders (visualization::make_scatter, visualization::make_surface). Resolves no image-export, WebDriver or async runtime package.
static_export (off by default, implies plotly): PNG and SVG export, drawn natively with Plotters since 0.23: no browser, WebDriver, network or installed font. SVG text is drawn as glyph outlines of the bundled Open Sans (SIL OFL 1.1, assets/OFL.txt).

§Static export

static_export adds Graph::write_png and Graph::write_svg, and render(OutputType::Png | Svg) through them. Since 0.23 they draw natively with Plotters: no browser, WebDriver, network access or installed font is involved, exports in threads or processes are independent, and the bundled font and its licence ship in this crate. static_export still implies plotly, so the Plotly Rust crate is a dependency for the HTML methods; it plays no part in the images.

Build	Chart data, `Graph`, terminal tables	`to_plot`, HTML, `show`, Plotly helpers	`write_png`, `write_svg`
no feature	yes
`plotly`	yes	yes
`static_export`	yes	yes (implied `plotly`)	yes

show() and render(OutputType::Browser) still hand an HTML chart to the default browser; that is the interactive workflow, unchanged.

What the images are, and how they differ from the Plotly chart:

Source. The images are drawn from graph_data() and graph_config(). An override of Graph::to_plot changes the HTML outputs, not the images; put image customisations in GraphConfig.
Text. Every label uses the bundled Open Sans Regular (SIL OFL 1.1, assets/OFL.txt), read with skrifa, at Plotly’s default sizes. A character the font has no glyph for (CJK, for example) is GraphError::MissingGlyph; tab, line feed and carriage return advance like a space. Labels are single lines with no kerning (the font’s kerning table is not applied), no ligatures and no right-to-left shaping.
SVG text is outlines. Each label is drawn as glyph paths, so the file looks the same in every viewer and needs no font. The label’s text is kept as its accessible name (<g role="img" aria-label>), and the document carries a <title> and a <desc> naming the series and axes. The text cannot be selected, copied, found or edited as text. In Chrome’s accessibility tree, checked when the design was chosen, each label is an image node named by its text, and the document is named by its title; how WebKit or a screen reader presents them was not checked. Use write_html for a text-searchable, interactive chart.
Surfaces. A 3D surface is drawn from a fixed viewpoint with flat-shaded cells, no lighting and a Viridis colour bar (a ColorScheme does not apply to surfaces), and shows its three axis titles. It must be a complete grid: a missing point is GraphError::IncompleteSurface, a repeated one GraphError::DuplicateSurfacePoint.
Colours. Colour strings follow CSS Color 4 (named colours, hex with or without alpha, rgb(), rgba(), hsl(), hsla()); a spelling only plotly.js tolerates is GraphError::InvalidColor.
Sizes. Width and height must each be 1 to 16384 pixels.
Files. The image is written next to its destination and renamed over it once complete, so a failed export leaves no partial file.

Data the export cannot draw faithfully is a typed GraphError rather than a repaired chart. GraphError is #[non_exhaustive]: keep a wildcard arm.

The crate README shows such a match as a compiled example.

Modules§

error: Errors raised by the visualization layer. Errors owned by the visualization layer.
visualization: Chart models, the Graph contract and its implementations.

Macros§

impl_graph_for_payoff_strategy: Macro impl_graph_for_payoff_strategy generates implementations of the Graph trait for one or more given types. This is specifically designed for types that represent payoff strategies, enabling them to produce graph data and configurations for financial visualizations, such as profit/loss graphs based on an underlying price range.

Constants§

VERSION: Version of the optionstratlib-visualization crate.