ScottPlot.NET

ScottPlot 5.0 Cookbook

Introduction
Axis
Plot Types
• Annotation - Annotations are always-visible text labels positioned over the data area.
• Arrow - Arrows point to a location in coordinate space.
• Axis Lines - Axis lines indicate a position on an axis.
• Axis Spans - Axis spans indicate a range of an axis.
• Bar Plot - Bar plots represent values as horizontal or vertical rectangles
• Box Plot - Box plots show a distribution at a glance
• Callout - Callouts display a label and are connected with an arrow that marks a point on the plot.
• Coxcomb Plot - A Coxcomb chart is a pie graph where the angle of slices is constant but the radii are not.
• Crosshair - A Crosshair combines a horizontal axis line and vertical axis line to mark a location in coordinate space.
• Ellipse - Ellipses are curves with a defined center and distinct X and Y radii. A circle is an ellipse with an X radius equal to its Y radius.
• Error Bars - Error Bars communicate the range of possible values for a measurement
• FillY plot - FillY plots display the vertical range between two Y values at defined X positions
• Financial Plot - Finance plots display price data binned into time ranges
• Function - Function plots are a type of line plot where Y positions are defined by a function that depends on X rather than a collection of discrete data points.
• Heatmap - Heatmaps display values from 2D data as an image with cells of different intensities
• Images - Images can be placed on plots in a variety of ways
• Line Plot - Line plots can be placed on the plot in coordinate space using a Start, End, and an optional LineStyle.
• Marker - Markers can be placed on the plot in coordinate space.
• Pie - Pie charts illustrate numerical proportions as slices of a circle.
• Population Plot - Population plots display collections of individual values.
• Radar Plot - Radar charts (also called a spider charts or star charts) represent multi-axis data as a 2D shape on axes arranged circularly around a center point.
• Radial gauge - A radial gauge chart displays scalar data as circular gauges.
• Scatter Plot - Scatter plots display points at X/Y locations in coordinate space.
• Shapes - Basic shapes that can be added to plots
• Signal Plot - Signal plots display evenly-spaced data
• SignalConst - SignalConst is a type of signal plot which contains immutable data points and occupies more memory but offers greater performance for extremely large datasets. It is rarely needed, but best use for plotting data containing millions of points.
• SignalXY Plot - SignalXY are a high performance plot type optimized for X/Y pairs where the X values are always ascending. For large datasets SignalXY plots are much more performant than Scatter plots (which allow unordered X points) but not as performant as Signal plots (which require fixed spacing between X points).
• Text - Text labels can be placed on the plot in coordinate space
• Vector Field - Vector fields display a collection of vectors rooted at points in coordinate space
Statistics
• Regression - Statistical operations to fit lines to data
Miscellaneous
• Advanced Styling - Features for users seeking extensive customization options.
• Internationalization - Using ScottPlot across cultures with different text and numeric requirements.

Introduction

Quickstart

A survey of basic functionality in ScottPlot 5
Display paired X/Y data as a scatter plot.
Functions that add things to plots return the plottables they create. Interact with the properties of plottables to customize their styling and behavior.
Signal plots are optimized for displaying evenly spaced data.
Signal plots can interactively display millions of data points in real time. Double-click the plot to display performance benchmarks.
Axis labels can be extensively customized.
A legend displays plottables in a key along the edge of a plot. Most plottables have a Label property which configures what text appears in the legend.
Although the Plot.Add class has many helpful methods for creating plottable objects and adding them to the plot, users can instantiate plottable objects themselves and use Add.Plottable() to place it on the plot. This stategy allows users to create their own plottables (implementing IPlottable) with custom appearance or behavior.

Axis and Ticks

Examples of common customizations for axis labels and ticks
Axis Limits can be set by the user.
Use GetLimits() to obtain the current axis limits.
The axis limits can be automatically adjusted to fit the data. Optional arguments allow users to define the amount of whitespace around the edges of the data.In older versions of ScottPlot this functionality was achieved by a method named AxisAuto().
How to create a plot containig only the data area and no axes.

Configuring Legends

A legend is a key typically displayed in the corner of a plot
Many plottables have a Label property that can be set so they appear in the legend.
Legends may be constructed manually.
Access the Legend object directly for advanced customization options.
Legend items may be arranged horizontally instead of vertically
Legend items may wrap to improve display for a large number of items
Multiple legends may be added to a plot
Use the ShowLegend() overload that accepts an Edge to display the legend outside the data area.

Styling Plots

How to customize appearance of plots
Plots contain many objects which can be customized individually by assigning to their public properties, but helper methods exist in the Plot's Style object that make it easier to customize many items at once using a simpler API.
Axis labels, tick marks, and frame can all be customized.
A palette is a set of colors, and the Plot's palette defines the default colors to use when adding new plottables. ScottPlot comes with many standard palettes, but users may also create their own.
Many standard arrow shapes are available
Many plot types have a LineStyle which can be customized.
All components of an image can be scaled up or down in size by adjusting the ScaleFactor property. This is very useful for creating images that look nice on high DPI displays with display scaling enabled.
Hairline mode allows axis frames, tick marks, and grid lines to always be rendered a single pixel wide regardless of scale factor. Enable hairline mode to allow interactive plots to feel smoother when a large scale factor is in use.
Plots can be created using dark mode by setting the colors of major plot components to ones consistent with a dark theme.
Colormaps can be used to generate a collection of discrete colors that can be applied to plottable objects.

Axis

How to further customize axes
Users can display data on an inverted axis by setting axis limits setting the lower edge to a value more positive than the upper edge.
Customize the logic for the automatic axis scaler to ensure that axis limits for a particular axis are always inverted when autoscaled.
Axis rules can be put in place which force the vertical scale (units per pixel) to match the horizontal scale so circles always appear as circles and not stretched ellipses.
Users can create their own fully custom axes to replace the default ones (as demonstrated in the demo app). Some experimental axes are available for users who may be interested in alternative axis display styles.
To improve crispness of straight vertical and horizontal lines, Anti-aliasing is disabled by default for axis frames, tick marks, and grid lines. Anti-aliasing can be enabled for all these objects by calling the AntiAlias helper method.

Customizing Grids

Grid lines can be hidden.
Grid lines can be customized. Custom grid systems can be created to give developers full control of grid rendering, but the default grid can be interacted with to customize its appearance.
Axis-specific styling properties are available for extensive axis-specific customization of grid line styling.
Grid lines are typically drawn beneath data, but grids can be configured to render on top of plottables too.
Grid lines use the bottom and left axes by default, but this behavior can be customized for plots which use other axes.

Customizing Ticks

Advanced customization of tick marks and tick labels
Users can customize the logic used to create tick labels from tick positions. Old versions of ScottPlot achieved this using a ManualTickPositions method.
Users can customize the logic used to create datetime tick labels from tick positions.
Tick generators determine where ticks are to be placed and also contain logic for generating tick labels from tick positions. Alternative tick generators can be created and assigned to axes. Some common tick generators are provided with ScottPlot, and users also have the option create their own.
The default axes have a SetTicks() helper method which replaces the default tick generator with a manual tick generator pre-loaded with the provided ticks.
Users desiring more control over major and minor tick positions and labels can instantiate a manual tick generator, set it up as desired, then assign it to the axis being customized
Users can customize tick label rotation.
The axis size can be increased to accommodate rotated or long tick labels.
Users can disable grid lines for specific axes.
Space between ticks can be increased by setting a value to indicate the minimum distance between tick labels (in pixels).
Tick density can be adjusted as a fraction of the default value. Unlike MinimumTickSpacing, this strategy is aware of the size of tick labels and adjusts accordingly.
A target number of ticks can be provided and the automatic tick generator will attempt to place that number of ticks. This strategy allows tick density to decrease as the image size increases.
Minor tick marks are automatically generated at intervals between major tick marks. By default they are evenly spaced, but their density may be customized.
The appearance of logarithmic scaling can be achieved by log-scaling the data to be displayed then customizing the minor ticks and grid.

DateTime Axes

Plot data values on a DataTime axes
Axis tick labels can be displayed using a time format.
DateTime axes are achieved using Microsoft's DateTime.ToOADate() and DateTime.FromOADate() methods to convert between dates and numeric values. Advanced users who wish to display data on DateTime axes may prefer to work with collections of doubles rather than collections of DateTimes.
Users can provide their own logic for customizing DateTime tick labels
Make ticks render at fixed intervals. Optionally make the ticks render from a custom start date, rather than using the start date of the plot (e.g. to draw ticks on the hour every hour, or on the first of every month, etc).

Multiple Axes

Tick mark customization and creation of multi-Axis plots
New plots have one axis on every side. Axes on the right and top are invisible by default. To use the right axis, make it visible, then tell a plottable to use it.
Additional axes may be added to plots. Plottables are displayed using the coordinate system of the primary axes by default, but any plottable can be displayed using any X and Y axis.

Plot Types

Annotation

Annotations are always-visible text labels positioned over the data area.
Annotations are labels you can place on the data area of a plot. Unlike Text added to the plot (which is placed in coordinate units on the axes), Annotations are positioned relative to the data area (in pixel units) and do not move as the plot is panned and zoomed.
Annotations can be extensively customized.
Annotations are aligned with the data area.

Arrow

Arrows point to a location in coordinate space.
Arrows can be placed on plots to point to a location in coordinate space and extensively customized.

Axis Lines

Axis lines indicate a position on an axis.
Axis lines are vertical or horizontal lines that span an entire axis.
Axis lines have labels that can be used to display arbitrary text on the axes they are attached to.
Axis line labels can have custom positioning, including rotation and alignment.
Axis lines have extensive customization options.
Axis lines will be added to the legend if their Text property is set unless their ExcludeFromLegend property is true.

Axis Spans

Axis spans indicate a range of an axis.
Axis spans label a range of an axis. Vertical spans shade the full width of a vertical range, and horizontal spans shade the full height of a horizontal range.
Axis spans can be extensively customized.

Bar Plot

Bar plots represent values as horizontal or vertical rectangles
Bar plots can be added from a series of values.
A collection of bars can appear in the legend as a single item.
Set the `Label` property of bars to have text displayed above each bar.
Set the `Label` property of bars to have text displayed beside (left or right) of each bar.
The exact position and size of each bar may be customized.
Bars can have errorbars.
Bars can be labeled by manually specifying axis tick mark positions and labels.
Bars can be positioned on top of each other.
Bars can be grouped by position and color.
Bar plots can be displayed horizontally.
Bars can be stacked to present data in groups.

Box Plot

Box plots show a distribution at a glance
Box plots can be created individually and added to the plot.
Each collection of boxes added to the plot gets styled the same and appears as a single item in the legend. Add multiple bar series plots with defined X positions to give the appearance of grouped data.

Callout

Callouts display a label and are connected with an arrow that marks a point on the plot.
Callouts display a label and are connected with an arrow that marks a point on the plot.

Coxcomb Plot

A Coxcomb chart is a pie graph where the angle of slices is constant but the radii are not.
A Coxcomb chart is a pie graph where the angle of slices is constant but the radii are not.

Crosshair

A Crosshair combines a horizontal axis line and vertical axis line to mark a location in coordinate space.
A Crosshair combines a horizontal axis line and vertical axis line to mark a location in coordinate space.
Crosshairs can be extensively customized.

Ellipse

Ellipses are curves with a defined center and distinct X and Y radii. A circle is an ellipse with an X radius equal to its Y radius.
Ellipses can be added to plots
Circles can be added to plots. Circles are really Ellipses with the same X and Y radius. Note that circles appear as ellipses unless the plot has a square coordinate system.
For circles to always appear circular, the coordinate system must be forced to always display square-shaped pixels. This can be achieved by enabling the axis scale lock.
Ellipses styles can be extensively customized
Ellipses can also be rotated

Error Bars

Error Bars communicate the range of possible values for a measurement
Error Bars go well with scatter plots.
Error size can be set for all dimensions.

FillY plot

FillY plots display the vertical range between two Y values at defined X positions
FillY plots can be created from X, Y1, and Y2 arrays.
FillY plots can be created from two scatter plots that share the same X values.
FillY plots can be created from data of any type if a conversion function is supplied.
FillY plots can be customized using public properties.

Financial Plot

Finance plots display price data binned into time ranges
Candlestick charts use symbols to display price data. The rectangle indicates open and close prices, and the center line indicates minimum and maximum price for the given time period. Color indicates whether the price increased or decreased between open and close.
OHLC charts use symbols to display price data (open, high, low, and close) for specific time ranges.
Finance charts can display price range information over arbitrary time scales.
Finance charts can be created which display price information on the right axis.
Tools exist for creating simple moving average (SMA) curves and displaying them next to finanial data.
Tools exist for creating Bollinger Bands which display weighted moving mean and variance for time series financial data.
When the DateTimes stored in OHLC objects are used to determine the horizontal position of candlesticks, periods without data like weekends and holidays appear as gaps in the plot. Enabling sequential mode causes the plot to ignore the OHLC DateTimes and display candles at integer positions starting from zero. Users can customize the tick generator to display dates instead of numbers on the horizontal axis if desired.
When the DateTimes stored in OHLC objects are used to determine the horizontal position, periods without data like weekends and holidays appear as gaps in the plot. Enabling sequential mode causes the plot to ignore the OHLC DateTimes and place OHLCs at integer positions starting from zero. Users can customize the tick generator to display dates instead of numbers on the horizontal axis if desired.

Function

Function plots are a type of line plot where Y positions are defined by a function that depends on X rather than a collection of discrete data points.
Create a function plot from a formula.
A function can be limited to a range of X values.

Heatmap

Heatmaps display values from 2D data as an image with cells of different intensities
Heatmaps can be created from 2D arrays
Heatmaps can be inverted by reversing the order of colors in the colormap
A heatmap's Colormap is the logic used to convert from cell value to cell color and they can set by the user. ScottPlot comes with many common colormaps, but users may implement IColormap and apply their own. A colorbar can be added to indicate which colors map to which values.
Multiple colorbars may be added to plots.
A colorbar displays a colormap on an edge of the plot, and it has an optional label which can be customized to display a title.
Colorbars have an optional custom tick formatter that allows users to control the string format of tick labels.
Heatmaps can be flipped horizontally and/or vertically
Enable the `Smooth` property for anti-aliased rendering
Assign double.NaN to a heatmap cell to make it transparent.
The transparency of the entire heatmap can be adjusted.
An alpha map (a 2d array of byte values) can be used to apply custom transparency to each cell of a heatmap.
A frameless heatmap can be achieved by disabling axis labels and ticks, then setting the margins to 0 so the data area tightly fits the data.
Heatmap cells are aligned in their centers by default. This means that the bottom left cell will be centered at (0, 0), and its lower left corner will be to the lower left of the origin. Setting sell alignment to lower left causes the lower left of the heatmap to be exactly at (0, 0).
Dimensions of a heatmap may be set by specifying how large a cell should be in pixel units.
The user can define the range of values to represent with colors in the colormap. Values outside that range will be clipped to the nearest color in the colormap.

Images

Images can be placed on plots in a variety of ways
An image can be drawn inside a rectangle defined in coordinate units.

Line Plot

Line plots can be placed on the plot in coordinate space using a Start, End, and an optional LineStyle.
Line plots are placed with a start and end location in coordinate space. Their styles can be customized.
Line plots can be styled using a LineStyle.
Line plots with labels appear in the legend.

Marker

Markers can be placed on the plot in coordinate space.
Markers are symbols placed at a location in coordinate space. Their shape, size, and color can be customized.
Standard marker shapes are provided, but advanced users are able to create their own as well.
Markers with labels appear in the legend.
Collections of markers that are all styled the same may be added to the plot
An ImageMarker can be placed on the plot to display an image centered at a location in coordinate space.

Pie

Pie charts illustrate numerical proportions as slices of a circle.
A pie chart can be created from a few values.
A pie chart can be created from a collection of slices.
A donut chart is a pie chart with an open center. Donut charts can be created from a collection of slices.
Slice labels can be displayed centered with the slice at a customizable distance from the center of the pie.

Population Plot

Population plots display collections of individual values.
A Population can be created from a collection of values, styled as desired, and placed anywhere on the plot.
Population statistics can be displayed using box plots.
The values displayed by the box midline, body, and whisker can be configured by assigning a static function to the box value configuration property.
The bar symbol in population plots can be extensively styled.
The box symbol in population plots can be extensively styled.
The data markers in population plots can be extensively styled.
The user may customize where data is drawn relative to the bar or box. Centering everything can be used to achieve an effect where data points are drawn over the bar or box.
Groups of populations can be achieved by customizing position, color, axis labels, and legend items.

Radar charts (also called a spider charts or star charts) represent multi-axis data as a 2D shape on axes arranged circularly around a center point.
Radar charts (also called a spider charts or star charts) represent multi-axis data as a 2D shape on axes arranged circularly around a center point.

A radial gauge chart displays scalar data as circular gauges.
A radial gauge chart can be created from a few values.
Gauge colors can be customized by changing the default palette.
Radial gauge plots support positive and negative values.
Sequential gauge mode indicates that the base of each gauge starts at the tip of the previous gauge.
Gauges are displayed from the center outward by default but the order can be customized.
The SingleGauge mode draws all gauges stacked together as a single gauge. This is useful for showing a progress gauges composed of many individual smaller gauges.
The direction of gauges can be customized. Clockwise is used by default.
The empty space between gauges can be adjusted as a fraction of their width.
The starting angle for gauges can be customized. 270 for North (default value), 0 for East, 90 for South, 180 for West, etc.
By default gauges are full circles (360 degrees) but smaller gauges can be created by customizing the gauge size.
The value of each gauge is displayed as text by default but this behavior can be overridden. Note that this is different than the labels fiels which is what appears in the legened.
Gauge level text is positioned at the tip of each gauge by default, but this position can be adjusted by the user.
Size of the gauge level text as a fraction of the gauge width.
Level text fonts may be customized.
Radial gauge labels will appear in the legend if they are assigned.
By default the full range of each gauge is drawn as a semitransparent ring. The amount of transparency can be adjusted as desired.
Gauge backgrounds are drawn as full circles by default. This behavior can be disabled to draw partial backgrounds for non-circular gauges.

Scatter Plot

Scatter plots display points at X/Y locations in coordinate space.
Scatter plots can be created from two arrays containing X and Y values.
Scatter plots can be created from a collection of Coordinates.
Scatter plots can be created from any numeric data type, not just double.
Scatter plots can be created from Lists, but be very cafeful not to add or remove items while a render is occurring or you may throw an index exception. See documentation about the Render Lock system for details.
The `ScatterLine()` method can be used to create a scatter plot with a line only (marker size is set to 0).
The `ScatterPoints()` method can be used to create a scatter plot with markers only (line width is set to 0).
Scatter plots can be extensively styled by interacting with the object that is returned after a scatter plot is added. Assign text to a scatter plot's Label property to allow it to appear in the legend.
Several line patterns are available
Scatter plots support generic data types, although double is typically the most performant.
A scatter plot may use DateTime units but be sure to setup the respective axis to display using DateTime format.
Scatter plots can be created using a step plot display where points are connected with right angles instead of diagnal lines. The direction of the steps can be customized.
NaN values in a scatter plot's data will appear as gaps in the line.
Scatter plots draw straight lines between points by default, but setting the Smooth property allows the scatter plot to connect points with smooth lines. Lines are smoothed using cubic spline interpolation.
Tension of smooth lines can be adjusted for some smoothing strategies. Low tensions lead to 'overshoot' and high tensions produce curveswhich appear more like straight lines.
The quadratic half point path strategy allows scatter plots to be displayed with smooth lines connecting points, but lines are eased in and out of points so they never 'overshoot' the values vertically.
Although a scatter plot may contain a very large amount of data, much of it may be unpopulated. The user can define min and max render indexes, and only values within that range will be displayed when the scatter plot is rendered.
The area beneath a scatter plot can be filled.
The base of the fill can be defined.
Filled areas above and below the FillY value can be individually customized
Scatter plot points can be multiplied by custom X and Y scale factors, or shifted horizontally or vertically using X and Y offset values.
A stacked filled line plot effect can be achieved by overlapping ScatterLines that fill area.

Shapes

Basic shapes that can be added to plots
A rectangle can be added to the plot and styled as desired.
A circle can be placed on the plot and styled as desired.
An ellipse can be placed on the plot and styled as desired.
Polygon plots can be added from a series of vertices, and must be in clockwise order.
Polygon plots can be fully customized.

Signal Plot

Signal plots display evenly-spaced data
Signal plots are best for extremely large datasets. They use render using special optimizations that allow highspeed interactivity with plots containing millions of data points.
Signal plots can be styled in a variety of ways.
Signal plots can be offset by a given X and Y value.
Signal plots can be scaled vertically according to a user-defined amount.
Signal plots can have markers displayed at each point which are only visible when the plot is zoomed in.
Even if a signal plot references a large array of data, rendering can be limited to a range of values. If set,only the range of data between the minimum and maximum render indexes will be displayed.
Signal plots support generic data types, although double is typically the most performant.
A signal plot may use DateTime units but be sure to setup the respective axis to display using DateTime format.

SignalConst

SignalConst is a type of signal plot which contains immutable data points and occupies more memory but offers greater performance for extremely large datasets. It is rarely needed, but best use for plotting data containing millions of points.
SignalConst can display data with millions of points at high framerates, ideal for interactive manipulation of large datasets.

SignalXY Plot

SignalXY are a high performance plot type optimized for X/Y pairs where the X values are always ascending. For large datasets SignalXY plots are much more performant than Scatter plots (which allow unordered X points) but not as performant as Signal plots (which require fixed spacing between X points).
SignalXY plots are a high performance plot type for X/Y data where the X values are always ascending.
SignalXY plots support generic data types, although double is typically the most performant.
Even if a SignalXY plot references a large array of data, rendering can be limited to a range of values. If set,only the range of data between the minimum and maximum render indexes will be displayed.
A fixed offset can be applied to SignalXY plots.
SignalXY plots can be scaled vertically according to a user-defined amount.
Although SignalXY plots typically display data left-to-right, it is possible to use this plot type to display data bottom-to-top.
Demonstrates how to display a rotated SignalXY plot (so it goes from bottom to top) which is also displayed on an inverted horizontal axis (where positive values are on the left).
Demonstrates how to display a rotated SignalXY plot on an inverted vertical axis so data goes from top to bottom.
Users can enable a marker to be displayedat each data point. However, this can reduce performance for extremely large datasets.

Text

Text labels can be placed on the plot in coordinate space
Text can be placed anywhere in coordinate space.
Text formatting can be extensively customized.
Multiline labels have a default line height estimated from the typeface and font size, however line height may be manually defined by the user.
The offset properties can be used to fine-tune text position in pixel units

Vector Field

Vector fields display a collection of vectors rooted at points in coordinate space
Vectors (representing a magnitude and direction) can be placed at specific points in coordinate space to display as a vector field.
Vector field arrows can be colored according to their magnitude.

Statistics

Regression

Statistical operations to fit lines to data
Fit a line to a collection of X/Y data points.