Skip to content

Latest commit

 

History

History
201 lines (136 loc) · 8.38 KB

README.md

File metadata and controls

201 lines (136 loc) · 8.38 KB
Raw

Go Report Card godoc

go-plotly

Inspired by Python Plotly

The goal of the go-plotly package is to provide a pleasant Go interface for creating figure specifications which are displayed by the plotly.js JavaScript graphing library.

In the context of the plotly.js library, a figure is specified by a declarative JSON data structure.

Therefore, you should always keep in mind as you are creating and updating figures using the go-plotly package that its ultimate goal is to help users produce Go structures that can be automatically serialized into the JSON data structure that the plotly.js graphing library understands.

Yes, that text is a copy paste from Python description.

The good thing about this package is that it's automatically generated based on the schema described here so It will be easy to keep it up to date or to generate different versions of it.

Just a reminder from semver: Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

Example

package main

import (
	grob "github.com/MetalBlueberry/go-plotly/generated/v2.31.1/graph_objects"
	"github.com/MetalBlueberry/go-plotly/pkg/offline"
	"github.com/MetalBlueberry/go-plotly/pkg/types"
)

func main() {
	/*
	   fig = dict({
	       "data": [{"type": "bar",
	                 "x": [1, 2, 3],
	                 "y": [1, 3, 2]}],
	       "layout": {"title": {"text": "A Figure Specified By Python Dictionary"}}
	   })
	*/
	fig := &grob.Fig{
		Data: []types.Trace{
			&grob.Bar{
				X: types.DataArray([]float64{1, 2, 3}),
				Y: types.DataArray([]float64{1, 2, 3}),
			},
		},
		Layout: &grob.Layout{
			Title: &grob.LayoutTitle{
				Text: "A Figure Specified By Go Struct",
			},
		},
	}

	offline.Show(fig)
}

This will open your browser and display the following plot

Bar

And that's it.

See the examples dir for more examples.

Structure

Auto completion is your best friend on this package. It will get the right type (almost) every time!

To keep the plotly.js independent of the version of this package, the generated directory contains a directory per plotly version supported. The plan is to support all minor releases and update as patches are released. But because I can not do it myself, I will accept PRs if anyone wants any specific version.

Updates to the package will affect all schemas. This will be done as we improve the generator.

Each trace type has its own file on graph_objecs (grob) package. The file contains the main structure and all the needed nested objects. Files ending with _gen are automatically generated files running go generate. This is executing the code in generator package to generate the structures from the plotly schema. The types are documented, but you can find more examples and extended documentation at Plotly's documentation.

Types that can have single values or lists, are defined as types.ArrayOK types. You can use the helper methods types.ArrayOKArray and types.ArrayOKValue depending on which value you want to set.

Basic types have been defined to follow plotly specs. Than means you will find types for strings, bools, numbers and integers. Those types are basically pointers to the equivalent value in Go, as plotly supports null values on any of those fields. To make it easier to work with the library, you can find utility functions to build such types. For example. types.N() will create a types.Number value from a float64 value. types.NS() attempts to parse a string as a number to follow what plotly specifications says about Number type. types.NA() converts []float64 into []types.Number. Equivalent functions can be found for other types.

Nested Properties, are defined as new types. This is great for auto completion using vscode because you can write all the boilerplate with ctrl+space. For example, the field Title.Text is accessed by the property Title of type {{Type}}Title that contains the property Text. The Type is always the struct that contains the field. For Layout It is LayoutTitle.

Flaglist and Enumerated fields are defined with a type and its constant values. This provides useful autocompletion. Keep in mind that you can compose multiple values for a Flaglist like Mode: grob.ScatterModeMarkers + "+" + grob.ScatterModeLines,. You can read de inline documentation to see the default value.

Progress

The main focus is to have the structures to hold the data and provide auto competition. Once we get there, we will be on v1.0.0.

Currently, most common use cases should be already covered. Feel free to create an issue if you find something that it's not working.

  • Basic types
    • Traces
    • Layout
    • Config
    • Animation
    • Frames
  • Type definitions
    • defs valobjects
      • angle needs validations
      • any
      • boolean
      • color
      • colorlist
      • colorscale
      • data_array
      • enumerated
      • flaglist
      • info_array
      • integer
      • number
      • string
      • subplotid
    • defs_modifier
      • arrayOK
      • min/max validations
      • dflt This is not needed in the output, as plotly will do it. But it would be nice to have a method to fetch it
      • noBlank validation
      • strict validation
      • values list validation

FAQ

Is this cross platform?

YES*

*The output of the package is usually a webpage that renders the figure using plotly.js. That means it will work on almost any browser. For further details, check plotly.js docs

Why this library and not go-echarts

go-echarts is an amazing library! It is the exact same idea as this library but for Apache ECharts.

To make a meaningful choice, you should compare plotly.js features ve ECharts,

Why this library and not gonum/plot

gonum/plot is focus on building static images while go-plotly has al the interactive features plotly.js provides.

If you want interactive dashboards, this library is way better.

What's the meaning of "grob"?

In python, the component is called graph_objects, like in this package, but that's too long to write it over and over again. In Python, usually it's called "go" from Graph_Objects but in Go... that's not possible for a conflict with a keyword. as an alternative, I've decided to use "grob" from GRaph_OBjects.

What are the usecases?

  1. Quickly visualize data using only Go

  2. Send plotly figures to the frontend ready to be drawn, avoiding possible mistakes in JS thanks to types!

  3. Generate an awesome dynamic plot in a local file with offline package.

  4. I don't know, just do something awesome and let me know it.

Go Plotly Update to any json schema version

Example PR

Update the config to add a new version

  1. To add a new version, add a new entry in: schemas.yaml

    The documentation for each field can be found in schema.go

    Example entry:

      -  Name: Plotly 2.31.1
     Tag: v2.31.1
     URL: https://raw.githubusercontent.com/plotly/plotly.js/v2.31.1/test/plot-schema.json
     # relative to the project root.
     Path: schemas/v2.31.1/plot-schema.json
     Generated: generated/v2.31.1
     CDN: https://cdn.plot.ly/plotly-2.31.1.min.js

Run download and regeneration

  1. Download all the schemas:

    go run generator/cmd/downloader/main.go --config="schemas.yaml"

  2. Then run the generator:

    go generate ./...

Star History

Star History Chart

Other tools and information links

Plotly online editor sandbox

http://plotly-json-editor.getforge.io/

Official Plotly Release Notes

For detailed changes please follow the release notes of the original JS repo: https://github.com/plotly/plotly.js/releases