VSL Plot Module 📊

This library implements high-level plotting functions for scientific data visualization using a Plotly-inspired API. Create interactive, publication-quality plots with minimal code while maintaining full customization control.

🚀 Features

Plot Types

• Scatter Plots: Points, lines, or combined with extensive marker customization
• Bar Charts: Vertical and horizontal bars with grouping support
• Heatmaps: 2D data visualization with color mapping
• Histograms: Distribution visualization with binning control
• Pie Charts: Proportion visualization with labels and annotations
• 3D Scatter: Three-dimensional data visualization
• Surface Plots: 3D surface rendering for mathematical functions

Interactive Features

• Zoom & Pan: Mouse-driven plot navigation
• Hover Information: Dynamic data point details
• Legend Control: Show/hide data series
• Export Options: Save as PNG, SVG, or HTML
• Responsive Design: Automatic layout adjustment

📖 Quick Start

Basic Scatter Plot

import vsl.plot
import vsl.util

// Generate data
x := util.arange(10).map(f64(it))
y := x.map(it * it)  // y = x²

// Create plot
mut plt := plot.Plot.new()
plt.scatter(x: x, y: y, mode: 'lines+markers')
plt.layout(title: 'Quadratic Function')
plt.show()!

Bar Chart

import vsl.plot

categories := ['A', 'B', 'C', 'D']
values := [23.0, 45.0, 56.0, 78.0]

mut plt := plot.Plot.new()
plt.bar(x: categories, y: values)
plt.layout(title: 'Category Comparison')
plt.show()!

Heatmap

import vsl.plot

// 2D data matrix
z := [[1.0, 20.0, 30.0],
      [20.0, 1.0, 60.0],
      [30.0, 60.0, 1.0]]

mut plt := plot.Plot.new()
plt.heatmap(z: z)
plt.layout(title: 'Correlation Matrix')
plt.show()!

🎨 Customization Guide

Styling Options

Colors: Use hex codes (#FF0000), RGB (rgb(255,0,0)), or named colors (red)

Markers: Control size, color, symbol, and opacity

marker: plot.Marker{
    size: []f64{len: data.len, init: 12.0}
    color: ['#FF0000', '#00FF00', '#0000FF']
    symbol: 'circle'  // Options: circle, square, diamond, triangle, etc.
}

Lines: Customize thickness, style, and color

line: plot.Line{
    color: '#FF0000'
    width: 3.0
    dash: 'solid'  // Options: solid, dash, dot, dashdot
}

Layout Configuration

plt.layout(
    title: 'My Plot Title'
    xaxis: plot.Axis{
        title: plot.AxisTitle{text: 'X-axis Label'}
        range: [0.0, 10.0]  // Set axis range
    }
    yaxis: plot.Axis{
        title: plot.AxisTitle{text: 'Y-axis Label'}
        type: 'log'  // Linear or logarithmic scale
    }
    width: 800
    height: 600
)

🔧 Annotations & Text

Adding Annotations (Fixed Arrow Issue)

The most important fix for annotation arrows:

// ✅ CORRECT: No unwanted arrows
annotation := plot.Annotation{
    text: 'Important Point'
    x: 5.0
    y: 25.0
    showarrow: false  // This prevents unwanted arrows!
    font: plot.Font{
        size: 14
        color: '#000000'
    }
}

plt.layout(
    title: 'Plot with Clean Annotations'
    annotations: [annotation]
)

Text Styling

font: plot.Font{
    family: 'Arial, sans-serif'
    size: 16
    color: '#333333'
}

Arrow Customization

annotation := plot.Annotation{
    text: 'Point with Arrow'
    x: 5.0
    y: 10.0
    showarrow: true
    arrowhead: 2           // Arrow style (0-8)
    arrowcolor: '#FF0000'  // Red arrow color
}

🐛 Common Issues & Solutions

Annotation Arrows Appearing Unexpectedly

Problem: Unwanted arrows show up with annotations Solution: Always set showarrow: false unless arrows are specifically needed

// ❌ WRONG: May show unwanted arrows
annotation := plot.Annotation{
    text: 'My annotation'
    x: 1.0
    y: 2.0
    // Missing showarrow property
}

// ✅ CORRECT: Clean text annotation
annotation := plot.Annotation{
    text: 'My annotation'
    x: 1.0
    y: 2.0
    showarrow: false  // Explicitly prevent arrows
}

Plot Not Displaying

Common causes:

• Missing plt.show()! call
• Browser not opening HTML file
• Invalid data format (ensure f64 for numeric data)

Performance Issues

Large datasets:

• Consider data sampling for >10,000 points
• Use appropriate plot types (heatmap for dense 2D data)
• Optimize marker sizes and line widths

📚 Advanced Examples

Multiple Data Series

mut plt := plot.Plot.new()

// First series
plt.scatter(
    x: x1, y: y1
    name: 'Dataset 1'
    marker: plot.Marker{color: ['#FF0000']}
)

// Second series
plt.scatter(
    x: x2, y: y2
    name: 'Dataset 2'
    marker: plot.Marker{color: ['#0000FF']}
)

Subplots (Coming Soon)

The VSL plot module is actively developed. Subplot functionality is planned for future releases.

🎯 Examples Directory

Explore complete examples:

• plot_scatter - Basic scatter plotting
• plot_scatter_annotations_fixed - Annotations without arrows
• plot_bar - Bar chart examples
• plot_heatmap_golden_ratio - Advanced heatmap styling
• plot_surface - 3D surface visualization

🔗 API Reference

Core Functions

• Plot.new() - Create new plot instance
• plt.scatter() - Add scatter/line traces
• plt.bar() - Add bar charts
• plt.heatmap() - Add heatmap visualization
• plt.layout() - Configure plot appearance
• plt.show() - Render and display plot

Data Types

• Plot - Main plotting object
• Marker - Point styling configuration
• Line - Line styling configuration
• Axis - Axis configuration
• Annotation - Text annotation settings

Create beautiful, interactive visualizations with VSL Plot! 🚀

Based on Plotly's graph_objects API design.

fn Plot.new() &Plot

type Trace = BarTrace
	| HeatmapTrace
	| HistogramTrace
	| PieTrace
	| Scatter3DTrace
	| ScatterTrace
	| SurfaceTrace

Trace is a sum type for representing different trace types

fn (t Trace) trace_type() string

type XType = []f64 | []int | []string

XType is a type for x-axis data

type YType = []f64 | []int | []string

YType is a type for y-axis data

type ZType = [][]f64 | [][]int | []f64 | []int

ZType is a type for z-axis data

enum TraceType {
	scatter
	pie
	heatmap
	surface
	scatter3d
	bar
	histogram
}

Enum for trace types

struct Annotation {
pub mut:
	x          f64    @[omitempty]
	y          f64    @[omitempty]
	text       string @[required]
	showarrow  bool
	arrowhead  int    @[omitempty]
	arrowcolor string @[omitempty]
	align      string @[omitempty]
	font       Font
}

Annotation handles all the information needed to annotate plots

struct Axis {
pub mut:
	title    AxisTitle
	tickmode string = 'auto'
	tick0    f64      @[omitempty]
	dtick    f64      @[omitempty]
	tickvals []f64    @[omitempty]
	ticktext []string @[omitempty]
	range    []f64    @[omitempty]
}

Axis handles axis data

struct AxisTitle {
pub mut:
	text string
}

AxisTitle handles needed data to render an axis title

struct BarTrace {
	CommonTrace
}

BarTrace is a struct for Bar trace type

struct Bins {
pub mut:
	start f64
	end   f64
	size  f64
}

Bins is a struct for bin limits in a histogram trace

struct CommonTrace {
pub mut:
	x          XType
	xbins      map[string]f32
	y          YType      @[omitempty]
	z          ZType      @[omitempty]
	name       string     @[omitempty]
	mode       string     @[omitempty]
	marker     Marker     @[omitempty]
	line       Line       @[omitempty]
	pull       []f64      @[omitempty]
	hole       f64        @[omitempty]
	fill       string     @[omitempty]
	fillcolor  string     @[omitempty]
	customdata [][]string @[omitempty]
	colorscale string = 'Viridis'     @[omitempty]
	textinfo   string     @[omitempty]
	text       []string   @[omitempty]
}

CommonTrace is a struct for common trace properties

struct Font {
pub mut:
	color  string = 'black'
	family string = 'monospace'
	size   f64    = 16.0
}

Font handles data to customize fonts

struct HeatmapTrace {
	CommonTrace
pub mut:
	hovertemplate string @[omitempty]
	zsmooth       string @[omitempty]
}

HeatmapTrace is a struct for Heatmap trace type

struct HistogramTrace {
	CommonTrace
pub mut:
	nbinsx   int    @[omitempty]
	nbinsy   int    @[omitempty]
	xbins    Bins   @[omitempty]
	histfunc string @[omitempty]
	marker   Marker @[omitempty]
}

HistogramTrace is a struct for Histogram trace type

struct Layout {
pub mut:
	title       string
	title_x     f64
	autosize    bool
	width       int = 550
	height      int = 550
	xaxis       Axis
	yaxis       Axis
	annotations []Annotation
}

Layout

struct Line {
pub mut:
	color string @[omitempty]
	width f64    = 2.0    @[omitempty]
	dash  string = 'solid' @[omitempty]
}

Line is a struct for line properties in a trace

struct Marker {
pub mut:
	size       []f64    @[omitempty]
	color      []string @[omitempty]
	opacity    f64    = 0.8      @[omitempty]
	colorscale string = 'Viridis'   @[omitempty]
}

Marker is a struct for marker properties in a trace

struct PieTrace {
	CommonTrace
pub mut:
	values []f64    @[omitempty]
	labels []string @[omitempty]
}

PieTrace is a struct for Pie trace type

struct Plot {
pub mut:
	traces []Trace
	layout Layout
}

Plot is the main structure that contains layout and traces to generate plots

fn (mut p Plot) annotation(annotation Annotation) Plot

box adds a box trace to the plot

fn (mut p Plot) bar(trace BarTrace) Plot

bar adds a bar trace to the plot

fn (p Plot) get_plotly_script(element_id string, config PlotlyScriptConfig) &html.Tag

get_plotly_script returns the plot script as an html tag.

fn (mut p Plot) heatmap(trace HeatmapTrace) Plot

heatmap adds a heatmap trace to the plot

fn (mut p Plot) histogram(trace HistogramTrace) Plot

histogram adds a histogram trace to the plot

fn (mut p Plot) layout(layout Layout) Plot

layout sets the layout of the plot

fn (mut p Plot) pie(trace PieTrace) Plot

pie adds a pie trace to the plot

fn (mut p Plot) scatter(trace ScatterTrace) Plot

scatter adds a scatter trace to the plot

fn (mut p Plot) scatter3d(trace Scatter3DTrace) Plot

scatter3d adds a scatter3d trace to the plot. If the z value is a 2D array, it is flattened to a 1D array

fn (p Plot) show(config PlotConfig) !

show starts a web server and opens a browser window to display the plot.

fn (mut p Plot) surface(trace SurfaceTrace) Plot

surface adds a surface trace to the plot

struct PlotConfig {
	net.ListenOptions
pub:
	timeout time.Duration = 1 * time.second
	use_cdn bool
	saddr   string = ':0'
}

PlotConfig is a configuration for the Plotly plot. It includes the configuration for the web server that serves the plot.

struct PlotlyScriptConfig {
	PlotConfig
}

PlotlyScriptConfig is a configuration for the Plotly plot script.

struct Scatter3DTrace {
	CommonTrace
}

Scatter3DTrace is a struct for Scatter3D trace type

struct ScatterTrace {
	CommonTrace
}

ScatterTrace is a struct for Scatter trace type

struct SurfaceTrace {
	CommonTrace
pub mut:
	hovertemplate string @[omitempty]
}

SurfaceTrace is a struct for Surface trace type