README

Gonum Plot

Build Status Build status Build status codecov.io coveralls.io GoDoc go.dev reference

gonum/plot is the new, official fork of code.google.com/p/plotinum. It provides an API for building and drawing plots in Go. Note that this new API is still in flux and may change. See the wiki for some example plots.

For additional Plotters, see the Community Plotters Wiki page.

There is a discussion list on Google Groups: gonum-dev@googlegroups.com.

gonum/plot is split into a few packages:

  • The plot package provides simple interface for laying out a plot and provides primitives for drawing to it.
  • The plotter package provides a standard set of Plotters which use the primitives provided by the plot package for drawing lines, scatter plots, box plots, error bars, etc. to a plot. You do not need to use the plotter package to make use of gonum/plot, however: see the wiki for a tutorial on making your own custom plotters.
  • The plotutil package contains a few routines that allow some common plot types to be made very easily. This package is quite new so it is not as well tested as the others and it is bound to change.
  • The vg package provides a generic vector graphics API that sits on top of other vector graphics back-ends such as a custom EPS back-end, draw2d, SVGo, X-Window, gopdf, and Gio.

Documentation

Documentation is available at:

https://godoc.org/gonum.org/v1/plot

Installation

You can get gonum/plot using go get:

go get gonum.org/v1/plot/...

If you write a cool plotter that you think others may be interested in using, please post to the list so that we can link to it in the gonum/plot wiki or possibly integrate it into the plotter package.

Expand ▾ Collapse ▴

Documentation

Overview

    Package plot provides an API for setting up plots, and primitives for drawing on plots.

    Plot is the basic type for creating a plot, setting the title, axis labels, legend, tick marks, etc. Types implementing the Plotter interface can draw to the data area of a plot using the primitives made available by this package. Some standard implementations of the Plotter interface can be found in the gonum.org/v1/plot/plotter package which is documented here: https://godoc.org/gonum.org/v1/plot/plotter

    Index

    Examples

    Constants

    This section is empty.

    Variables

    View Source
    var (
    	// DefaultFont is the name of the default font for plot text.
    	DefaultFont = font.Font{
    		Typeface: "Liberation",
    		Variant:  "Serif",
    	}
    
    	// DefaultTextHandler is the default text handler used for text processing.
    	DefaultTextHandler text.Handler
    )
    View Source
    var UTCUnixTime = UnixTimeIn(time.UTC)

      UTCUnixTime is the default time conversion for TimeTicks.

      Functions

      func Align

      func Align(plots [][]*Plot, t draw.Tiles, dc draw.Canvas) [][]draw.Canvas

        Align returns a two-dimensional row-major array of Canvases which will produce tiled plots with DataCanvases that are evenly sized and spaced. The arguments to the function are a two-dimensional row-major array of plots, a tile configuration, and the canvas to which the tiled plots are to be drawn.

        Example
        Output:
        
        

        func UnixTimeIn

        func UnixTimeIn(loc *time.Location) func(t float64) time.Time

          UnixTimeIn returns a time conversion function for the given location.

          func Version

          func Version() (version, sum string)

            Version returns the version of Gonum/plot and its checksum. The returned values are only valid in binaries built with module support.

            If a replace directive exists in the Gonum/plot go.mod, the replace will be reported in the version in the following format:

            "version=>[replace-path] [replace-version]"
            

            and the replace sum will be returned in place of the original sum.

            The exact version format returned by Version may change in future.

            Types

            type Axis

            type Axis struct {
            	// Min and Max are the minimum and maximum data
            	// values represented by the axis.
            	Min, Max float64
            
            	Label struct {
            		// Text is the axis label string.
            		Text string
            
            		// Padding is the distance between the label and the axis.
            		Padding vg.Length
            
            		// TextStyle is the style of the axis label text.
            		// For the vertical axis, one quarter turn
            		// counterclockwise will be added to the label
            		// text before drawing.
            		TextStyle text.Style
            
            		// Position is where the axis label string should be drawn.
            		// The default value is draw.PosCenter, displaying the label
            		// at the center of the axis.
            		// Valid values are [-1,+1], with +1 being the far right/top
            		// of the axis, and -1 the far left/bottom of the axis.
            		Position float64
            	}
            
            	// LineStyle is the style of the axis line.
            	draw.LineStyle
            
            	// Padding between the axis line and the data.  Having
            	// non-zero padding ensures that the data is never drawn
            	// on the axis, thus making it easier to see.
            	Padding vg.Length
            
            	Tick struct {
            		// Label is the TextStyle on the tick labels.
            		Label text.Style
            
            		// LineStyle is the LineStyle of the tick lines.
            		draw.LineStyle
            
            		// Length is the length of a major tick mark.
            		// Minor tick marks are half of the length of major
            		// tick marks.
            		Length vg.Length
            
            		// Marker returns the tick marks.  Any tick marks
            		// returned by the Marker function that are not in
            		// range of the axis are not drawn.
            		Marker Ticker
            	}
            
            	// Scale transforms a value given in the data coordinate system
            	// to the normalized coordinate system of the axis—its distance
            	// along the axis as a fraction of the axis range.
            	Scale Normalizer
            }

              An Axis represents either a horizontal or vertical axis of a plot.

              Example (LabelsPosition)
              Output:
              
              

              func (Axis) Norm

              func (a Axis) Norm(x float64) float64

                Norm returns the value of x, given in the data coordinate system, normalized to its distance as a fraction of the range of this axis. For example, if x is a.Min then the return value is 0, and if x is a.Max then the return value is 1.

                type ConstantTicks

                type ConstantTicks []Tick

                  ConstantTicks is suitable for the Tick.Marker field of an Axis. This function returns the given set of ticks.

                  func (ConstantTicks) Ticks

                  func (ts ConstantTicks) Ticks(float64, float64) []Tick

                    Ticks returns Ticks in a specified range

                    type DataRanger

                    type DataRanger interface {
                    	// DataRange returns the range of X and Y values.
                    	DataRange() (xmin, xmax, ymin, ymax float64)
                    }

                      DataRanger wraps the DataRange method.

                      type DefaultTicks

                      type DefaultTicks struct{}

                        DefaultTicks is suitable for the Tick.Marker field of an Axis, it returns a reasonable default set of tick marks.

                        func (DefaultTicks) Ticks

                        func (DefaultTicks) Ticks(min, max float64) []Tick

                          Ticks returns Ticks in the specified range.

                          type GlyphBox

                          type GlyphBox struct {
                          	// The glyph location in normalized coordinates.
                          	X, Y float64
                          
                          	// Rectangle is the offset of the glyph's minimum drawing
                          	// point relative to the glyph location and its size.
                          	vg.Rectangle
                          }

                            A GlyphBox describes the location of a glyph and the offset/size of its bounding box.

                            If the Rectangle.Size().X is non-positive (<= 0) then the GlyphBox is ignored when computing the horizontal padding, and likewise with Rectangle.Size().Y and the vertical padding.

                            type GlyphBoxer

                            type GlyphBoxer interface {
                            	GlyphBoxes(*Plot) []GlyphBox
                            }

                              GlyphBoxer wraps the GlyphBoxes method. It should be implemented by things that meet the Plotter interface that draw glyphs so that their glyphs are not clipped if drawn near the edge of the draw.Canvas.

                              When computing padding, the plot ignores GlyphBoxes as follows: If the Size.X > 0 and the X value is not in range of the X axis then the box is ignored. If Size.Y > 0 and the Y value is not in range of the Y axis then the box is ignored.

                              Also, GlyphBoxes with Size.X <= 0 are ignored when computing horizontal padding and GlyphBoxes with Size.Y <= 0 are ignored when computing vertical padding. This is useful for things like box plots and bar charts where the boxes and bars are considered to be glyphs in the X direction (and thus need padding), but may be clipped in the Y direction (and do not need padding).

                              type InvertedScale

                              type InvertedScale struct{ Normalizer }

                                InvertedScale can be used as the value of an Axis.Scale function to invert the axis using any Normalizer.

                                func (InvertedScale) Normalize

                                func (is InvertedScale) Normalize(min, max, x float64) float64

                                  Normalize returns a normalized [0, 1] value for the position of x.

                                  type Legend

                                  type Legend struct {
                                  	// TextStyle is the style given to the legend
                                  	// entry texts.
                                  	TextStyle text.Style
                                  
                                  	// Padding is the amount of padding to add
                                  	// between each entry in the legend.  If Padding
                                  	// is zero then entries are spaced based on the
                                  	// font size.
                                  	Padding vg.Length
                                  
                                  	// Top and Left specify the location of the legend.
                                  	// If Top is true the legend is located along the top
                                  	// edge of the plot, otherwise it is located along
                                  	// the bottom edge.  If Left is true then the legend
                                  	// is located along the left edge of the plot, and the
                                  	// text is positioned after the icons, otherwise it is
                                  	// located along the right edge and the text is
                                  	// positioned before the icons.
                                  	Top, Left bool
                                  
                                  	// XOffs and YOffs are added to the legend's
                                  	// final position.
                                  	XOffs, YOffs vg.Length
                                  
                                  	// YPosition specifies the vertical position of a legend entry.
                                  	// Valid values are [-1,+1], with +1 being the top of the
                                  	// entry vertical space, and -1 the bottom.
                                  	YPosition float64
                                  
                                  	// ThumbnailWidth is the width of legend thumbnails.
                                  	ThumbnailWidth vg.Length
                                  	// contains filtered or unexported fields
                                  }

                                    A Legend gives a description of the meaning of different data elements of the plot. Each legend entry has a name and a thumbnail, where the thumbnail shows a small sample of the display style of the corresponding data.

                                    Example (Standalone)

                                      This example creates a some standalone legends with borders around them.

                                      Output:
                                      
                                      

                                      func NewLegend

                                      func NewLegend() Legend

                                        NewLegend returns a legend with the default parameter settings.

                                        func (*Legend) Add

                                        func (l *Legend) Add(name string, thumbs ...Thumbnailer)

                                          Add adds an entry to the legend with the given name. The entry's thumbnail is drawn as the composite of all of the thumbnails.

                                          func (*Legend) Draw

                                          func (l *Legend) Draw(c draw.Canvas)

                                            Draw draws the legend to the given draw.Canvas.

                                            func (*Legend) Rectangle

                                            func (l *Legend) Rectangle(c draw.Canvas) vg.Rectangle

                                              Rectangle returns the extent of the Legend.

                                              type LinearScale

                                              type LinearScale struct{}

                                                LinearScale an be used as the value of an Axis.Scale function to set the axis to a standard linear scale.

                                                func (LinearScale) Normalize

                                                func (LinearScale) Normalize(min, max, x float64) float64

                                                  Normalize returns the fractional distance of x between min and max.

                                                  type LogScale

                                                  type LogScale struct{}

                                                    LogScale can be used as the value of an Axis.Scale function to set the axis to a log scale.

                                                    func (LogScale) Normalize

                                                    func (LogScale) Normalize(min, max, x float64) float64

                                                      Normalize returns the fractional logarithmic distance of x between min and max.

                                                      type LogTicks

                                                      type LogTicks struct{}

                                                        LogTicks is suitable for the Tick.Marker field of an Axis, it returns tick marks suitable for a log-scale axis.

                                                        func (LogTicks) Ticks

                                                        func (LogTicks) Ticks(min, max float64) []Tick

                                                          Ticks returns Ticks in a specified range

                                                          type Normalizer

                                                          type Normalizer interface {
                                                          	// Normalize transforms a value x in the data coordinate system to
                                                          	// the normalized coordinate system.
                                                          	Normalize(min, max, x float64) float64
                                                          }

                                                            Normalizer rescales values from the data coordinate system to the normalized coordinate system.

                                                            type Plot

                                                            type Plot struct {
                                                            	Title struct {
                                                            		// Text is the text of the plot title.  If
                                                            		// Text is the empty string then the plot
                                                            		// will not have a title.
                                                            		Text string
                                                            
                                                            		// Padding is the amount of padding
                                                            		// between the bottom of the title and
                                                            		// the top of the plot.
                                                            		Padding vg.Length
                                                            
                                                            		// TextStyle specifies how the plot title text should be displayed.
                                                            		TextStyle text.Style
                                                            	}
                                                            
                                                            	// BackgroundColor is the background color of the plot.
                                                            	// The default is White.
                                                            	BackgroundColor color.Color
                                                            
                                                            	// X and Y are the horizontal and vertical axes
                                                            	// of the plot respectively.
                                                            	X, Y Axis
                                                            
                                                            	// Legend is the plot's legend.
                                                            	Legend Legend
                                                            
                                                            	// TextHandler parses and formats text according to a given
                                                            	// dialect (Markdown, LaTeX, plain, ...)
                                                            	// The default is a plain text handler.
                                                            	TextHandler text.Handler
                                                            	// contains filtered or unexported fields
                                                            }

                                                              Plot is the basic type representing a plot.

                                                              func New

                                                              func New() *Plot

                                                                New returns a new plot with some reasonable default settings.

                                                                func (*Plot) Add

                                                                func (p *Plot) Add(ps ...Plotter)

                                                                  Add adds a Plotters to the plot.

                                                                  If the plotters implements DataRanger then the minimum and maximum values of the X and Y axes are changed if necessary to fit the range of the data.

                                                                  When drawing the plot, Plotters are drawn in the order in which they were added to the plot.

                                                                  func (*Plot) DataCanvas

                                                                  func (p *Plot) DataCanvas(da draw.Canvas) draw.Canvas

                                                                    DataCanvas returns a new draw.Canvas that is the subset of the given draw area into which the plot data will be drawn.

                                                                    func (*Plot) Draw

                                                                    func (p *Plot) Draw(c draw.Canvas)

                                                                      Draw draws a plot to a draw.Canvas.

                                                                      Plotters are drawn in the order in which they were added to the plot. Plotters that implement the GlyphBoxer interface will have their GlyphBoxes taken into account when padding the plot so that none of their glyphs are clipped.

                                                                      func (*Plot) DrawGlyphBoxes

                                                                      func (p *Plot) DrawGlyphBoxes(c *draw.Canvas)

                                                                        DrawGlyphBoxes draws red outlines around the plot's GlyphBoxes. This is intended for debugging.

                                                                        func (*Plot) GlyphBoxes

                                                                        func (p *Plot) GlyphBoxes(*Plot) (boxes []GlyphBox)

                                                                          GlyphBoxes returns the GlyphBoxes for all plot data that meet the GlyphBoxer interface.

                                                                          func (*Plot) HideAxes

                                                                          func (p *Plot) HideAxes()

                                                                            HideAxes hides the X and Y axes.

                                                                            func (*Plot) HideX

                                                                            func (p *Plot) HideX()

                                                                              HideX configures the X axis so that it will not be drawn.

                                                                              func (*Plot) HideY

                                                                              func (p *Plot) HideY()

                                                                                HideY configures the Y axis so that it will not be drawn.

                                                                                func (*Plot) NominalX

                                                                                func (p *Plot) NominalX(names ...string)

                                                                                  NominalX configures the plot to have a nominal X axis—an X axis with names instead of numbers. The X location corresponding to each name are the integers, e.g., the x value 0 is centered above the first name and 1 is above the second name, etc. Labels for x values that do not end up in range of the X axis will not have tick marks.

                                                                                  func (*Plot) NominalY

                                                                                  func (p *Plot) NominalY(names ...string)

                                                                                    NominalY is like NominalX, but for the Y axis.

                                                                                    func (*Plot) Save

                                                                                    func (p *Plot) Save(w, h vg.Length, file string) (err error)

                                                                                      Save saves the plot to an image file. The file format is determined by the extension.

                                                                                      Supported extensions are:

                                                                                      .eps, .jpg, .jpeg, .pdf, .png, .svg, .tex, .tif and .tiff.
                                                                                      

                                                                                      func (*Plot) Transforms

                                                                                      func (p *Plot) Transforms(c *draw.Canvas) (x, y func(float64) vg.Length)

                                                                                        Transforms returns functions to transfrom from the x and y data coordinate system to the draw coordinate system of the given draw area.

                                                                                        func (*Plot) WriterTo

                                                                                        func (p *Plot) WriterTo(w, h vg.Length, format string) (io.WriterTo, error)

                                                                                          WriterTo returns an io.WriterTo that will write the plot as the specified image format.

                                                                                          Supported formats are:

                                                                                          eps, jpg|jpeg, pdf, png, svg, tex and tif|tiff.
                                                                                          

                                                                                          type Plotter

                                                                                          type Plotter interface {
                                                                                          	// Plot draws the data to a draw.Canvas.
                                                                                          	Plot(draw.Canvas, *Plot)
                                                                                          }

                                                                                            Plotter is an interface that wraps the Plot method. Some standard implementations of Plotter can be found in the gonum.org/v1/plot/plotter package, documented here: https://godoc.org/gonum.org/v1/plot/plotter

                                                                                            type Thumbnailer

                                                                                            type Thumbnailer interface {
                                                                                            	// Thumbnail draws an thumbnail representing
                                                                                            	// a legend entry.  The thumbnail will usually show
                                                                                            	// a smaller representation of the style used
                                                                                            	// to plot the corresponding data.
                                                                                            	Thumbnail(c *draw.Canvas)
                                                                                            }

                                                                                              Thumbnailer wraps the Thumbnail method, which draws the small image in a legend representing the style of data.

                                                                                              type Tick

                                                                                              type Tick struct {
                                                                                              	// Value is the data value marked by this Tick.
                                                                                              	Value float64
                                                                                              
                                                                                              	// Label is the text to display at the tick mark.
                                                                                              	// If Label is an empty string then this is a minor
                                                                                              	// tick mark.
                                                                                              	Label string
                                                                                              }

                                                                                                A Tick is a single tick mark on an axis.

                                                                                                func (Tick) IsMinor

                                                                                                func (t Tick) IsMinor() bool

                                                                                                  IsMinor returns true if this is a minor tick mark.

                                                                                                  type Ticker

                                                                                                  type Ticker interface {
                                                                                                  	// Ticks returns Ticks in a specified range
                                                                                                  	Ticks(min, max float64) []Tick
                                                                                                  }

                                                                                                    Ticker creates Ticks in a specified range

                                                                                                    type TickerFunc

                                                                                                    type TickerFunc func(min, max float64) []Tick

                                                                                                      TickerFunc is suitable for the Tick.Marker field of an Axis. It is an adapter which allows to quickly setup a Ticker using a function with an appropriate signature.

                                                                                                      func (TickerFunc) Ticks

                                                                                                      func (f TickerFunc) Ticks(min, max float64) []Tick

                                                                                                        Ticks implements plot.Ticker.

                                                                                                        type TimeTicks

                                                                                                        type TimeTicks struct {
                                                                                                        	// Ticker is used to generate a set of ticks.
                                                                                                        	// If nil, DefaultTicks will be used.
                                                                                                        	Ticker Ticker
                                                                                                        
                                                                                                        	// Format is the textual representation of the time value.
                                                                                                        	// If empty, time.RFC3339 will be used
                                                                                                        	Format string
                                                                                                        
                                                                                                        	// Time takes a float64 value and converts it into a time.Time.
                                                                                                        	// If nil, UTCUnixTime is used.
                                                                                                        	Time func(t float64) time.Time
                                                                                                        }

                                                                                                          TimeTicks is suitable for axes representing time values.

                                                                                                          func (TimeTicks) Ticks

                                                                                                          func (t TimeTicks) Ticks(min, max float64) []Tick

                                                                                                            Ticks implements plot.Ticker.

                                                                                                            Directories

                                                                                                            Path Synopsis
                                                                                                            Package cmpimg compares the raw representation of images taking into account idiosyncracies related to their underlying format (SVG, PDF, PNG, ...).
                                                                                                            Package cmpimg compares the raw representation of images taking into account idiosyncracies related to their underlying format (SVG, PDF, PNG, ...).
                                                                                                            Package font provides types to describe and select text font faces.
                                                                                                            Package font provides types to describe and select text font faces.
                                                                                                            liberation
                                                                                                            Package liberation exports the Liberation fonts as a font.Collection.
                                                                                                            Package liberation exports the Liberation fonts as a font.Collection.
                                                                                                            Package palette provides basic color palette handling.
                                                                                                            Package palette provides basic color palette handling.
                                                                                                            brewer
                                                                                                            Package brewer provides Brewer Palettes for informative graphics.
                                                                                                            Package brewer provides Brewer Palettes for informative graphics.
                                                                                                            moreland
                                                                                                            Package moreland provides color maps for pseudocoloring scalar fields.
                                                                                                            Package moreland provides color maps for pseudocoloring scalar fields.
                                                                                                            Package plotter defines a variety of standard Plotters for the plot package.
                                                                                                            Package plotter defines a variety of standard Plotters for the plot package.
                                                                                                            Package plotutil contains a small number of utilites for creating plots.
                                                                                                            Package plotutil contains a small number of utilites for creating plots.
                                                                                                            Package text provides types and functions to parse, format and render text.
                                                                                                            Package text provides types and functions to parse, format and render text.
                                                                                                            tools
                                                                                                            bezier
                                                                                                            Package bezier implements 2D Bézier curve calculation.
                                                                                                            Package bezier implements 2D Bézier curve calculation.
                                                                                                            vg
                                                                                                            Package vg defines an interface for drawing 2D vector graphics.
                                                                                                            Package vg defines an interface for drawing 2D vector graphics.
                                                                                                            draw
                                                                                                            Package draw provides types and functions to draw shapes on a vg.Canvas.
                                                                                                            Package draw provides types and functions to draw shapes on a vg.Canvas.
                                                                                                            fonts
                                                                                                            Package fonts provides the Liberation fonts from https://fedorahosted.org/liberation-fonts/
                                                                                                            Package fonts provides the Liberation fonts from https://fedorahosted.org/liberation-fonts/
                                                                                                            recorder
                                                                                                            Package recorder provides support for vector graphics serialization.
                                                                                                            Package recorder provides support for vector graphics serialization.
                                                                                                            vgeps
                                                                                                            Package vgeps implements the vg.Canvas interface using encapsulated postscript.
                                                                                                            Package vgeps implements the vg.Canvas interface using encapsulated postscript.
                                                                                                            vggio
                                                                                                            Package vggio provides a vg.Canvas implementation backed by Gio, a toolkit that implements portable immediate GUI mode in Go.
                                                                                                            Package vggio provides a vg.Canvas implementation backed by Gio, a toolkit that implements portable immediate GUI mode in Go.
                                                                                                            vgimg
                                                                                                            Package vgimg implements the vg.Canvas interface using github.com/fogleman/gg as a backend to output raster images.
                                                                                                            Package vgimg implements the vg.Canvas interface using github.com/fogleman/gg as a backend to output raster images.
                                                                                                            vgpdf
                                                                                                            Package vgpdf implements the vg.Canvas interface using gofpdf (github.com/phpdave11/gofpdf).
                                                                                                            Package vgpdf implements the vg.Canvas interface using gofpdf (github.com/phpdave11/gofpdf).
                                                                                                            vgsvg
                                                                                                            Package vgsvg uses svgo (github.com/ajstarks/svgo) as a backend for vg.
                                                                                                            Package vgsvg uses svgo (github.com/ajstarks/svgo) as a backend for vg.
                                                                                                            vgtex
                                                                                                            Package vgtex provides a vg.Canvas implementation for LaTeX, targeted at the TikZ/PGF LaTeX package: https://sourceforge.net/projects/pgf vgtex generates PGF instructions that will be interpreted and rendered by LaTeX. vgtex allows to put any valid LaTeX notation inside plot's strings.
                                                                                                            Package vgtex provides a vg.Canvas implementation for LaTeX, targeted at the TikZ/PGF LaTeX package: https://sourceforge.net/projects/pgf vgtex generates PGF instructions that will be interpreted and rendered by LaTeX. vgtex allows to put any valid LaTeX notation inside plot's strings.