Skip to content

vicanso go‐charts Migration Guide

Jump to bottom
Mike Jensen edited this page Jan 12, 2025 · 7 revisions

This guide serves as the migration guide for updating from vicanso/go-charts to the current version of go-analyze/charts. Once completed, subsequent updates will be documented in the go-analyze/charts Version Migration Guide.

Fork Overview

Our fork of vicanso/go-charts was motivated by a desire to enhance the flexibility and readability of the already beautiful charts for a wider range of data sets. This initially focused on significant improvements to how the x-axis is rendered. Since then, we have focused on expanding unit test coverage, which has allowed us to identify and correct a wide range of bugs, particularly for unusual datasets.

We are committed to continue to explore new use cases and make rendering graphs in Go easy and intuitive.

Updating Your Code to Use go-analyze/charts

Below are the key changes you need to know to migrate your existing code. They are grouped by configuration aspect to make it easier to pinpoint where your code might need adjustments. If you need deeper technical details, check the corresponding pull request (PR) or open an issue if you’re still unsure.

Quick Reference: Renamed Fields and Functions

Old Name New Name PR Notes
Type (in ChartOption) OutputFormat #5 Output format for charts (e.g. "png", "svg").
SVGTypeOption() SVGOutputOptionFunc() #27 Renamed for consistency.
PNGTypeOption() PNGOutputOptionFunc() #27 Renamed for consistency.
TypeOptionFunc SVGOutputOptionFunc(), PNGOutputOptionFunc() #27 Reduced public API.
TrueFlag(), FalseFlag() True(), False() #5 Simpler boolean pointer helpers.
NewFloatPoint(float64) FloatPointer(float64) #5 New name for float-pointer constructor.
YAxisOptions (field/struct) YAxis #5 Removes “Options” suffix for consistency.
FirstAxis DataStartIndex #5 Indicates zero-based index for axis Data.
SplitNumber Removed #3 Replaced by new label config (Unit, LabelCount, etc.).
StrokeColor, SplitLineColor Removed #5 Use theme or WithAxisColor(...) for custom axis color.
Opacity (Line charts) FillOpacity #5 Clarifies that opacity is for the fill area.
Column, Row (in grids) Columns, Rows #5 More descriptive naming.
Padding (in Table) CellPadding #5 Avoids confusion with chart-level padding.
Orient (Title/Legend) Vertical (*bool) #20 OrientationHorizontal / OrientationVertical removed.
Title.Top / Title.Left Title.Offset.Top / Offset.Left #20 For clearer offset usage. Similar for Legend.Top/Left.
Box offsets for labels OffsetInt #9 Struct with only Top and Left is more intuitive.
WidthOptionFunc, HeightOptionFunc DimensionsOptionFunc #27 Dimensions now set together.
SetDefaultWidth, SetDefaultHeight SetDefaultChartDimensions #27 Dimensions now set together.
Painter.ArrowTop ArrowUp #27 Renamed for clarity.
Painter.ArrowBottom ArrowDown #27 Renamed for clarity.
LineChartOption.StrokeWidth LineStrokeWidth #27 Renamed for consistency.

General Configuration Changes

  1. Type → OutputFormat
    • Clarifies that the field sets the output format (e.g., "png" or "svg"). (see PR #5)
  • TypeOptionFunc has been replaced by separate functions: SVGOutputOptionFunc() or PNGOutputOptionFunc(). (see PR #27)

  1. TrueFlag() / FalseFlag() → True() / False()

    • Naming is shorter but the functionality (returning bool pointers) is unchanged (see PR #5).

  2. NewFloatPoint(float64) → FloatPointer(float64)

    • Minor naming change for consistency (see PR #5).

  3. Dropping “Option” Suffix

    • Fields and types named *Options or *Option have dropped that suffix. E.g., YAxisOptions → YAxis. (see PR #5)

  4. Fonts and Themes Moved Out of Global Registry

    • Themes and Fonts are now set directly on your chart config rather than looked up from a global store. You can still load built-in themes by name with a helper like GetTheme(...), but you’re not required to. (see PR #4)
    • Many color fields were removed in favor of theme usage. For specific overrides, use helpers on the theme like WithAxisColor(...).

  5. Font Configuration with FontStyle

    • Instead of various top-level FontSize, FontColor, etc., each component (title, legend, axis) has a FontStyle struct for specifying the font properties.

  6. Dimensions provided together

    • WidthOptionFunc and HeightOptionFunc have been consolidated into DimensionsOptionFunc. Similarly, SetDefaultWidth and SetDefaultHeight were replaced with SetDefaultChartDimensions. (see PR #27)

Axis Configuration

  1. YAxisOptions → YAxis

    • Reflects the removal of “Options” suffix (see PR #5).

  2. FirstAxis → DataStartIndex

    • Clarifies that it’s the zero-based index from which your Data should begin (see PR #5).

  3. Removed Color Fields

    • StrokeColor and SplitLineColor have been removed; rely on the theme (see PR #5).
    • YAxis.Color → YAxis.AxisColor (see PR #5)

  4. Axis Label Frequency & Padding (see PR #3)

    • Unit: Suggests the increment for axis labels. Min and max are always shown.
    • LabelCount: Directly sets how many labels to render (takes priority over Unit if both are set).
    • LabelCountAdjustment: Relative tweak to the auto-determined label count (negative yields fewer labels, positive yields more).
    • LabelSkipCount: Allows skipping rendering every Nth label.
    • RangeValuePaddingScale: Suggests extra padding on the min/max of the y-axis. If Max or Min are set, no extra padding is added (unless needed to satisfy Unit).
    • SplitNumber: REMOVED, use the values described above.

Positioning (Titles, Legends, Offsets)

  1. Title & Legend (see PR #20)

    • Title.Top / Title.Left → Title.Offset.Top / Title.Offset.Left.
    • Legend.Top / Legend.Left → Legend.Offset.Top / Legend.Offset.Left.
    • Orient (horizontal/vertical) is replaced by a simple Vertical bool.
    • If you used PositionLeft, PositionCenter, or PositionRight, you can now use OffsetLeft, OffsetCenter, OffsetRight to set the same.

  2. LabelOffset

    • LabelOffset was a Box that only respected Top and Left. Now it’s a more intuitive OffsetInt struct, reflecting only the fields actually used (Top, Left) (see PR #9).

  3. Horizontal Legend Without Title Behavior (see PR #25)

  • If there is a legend but no title, vicanso/go‐charts would overlap the legend with the chart data. By default we now space the chart below the legend, unless the LegendOption.OverlayChart is set to *true. If you preferred the prior behavior you should set this option.

Series Changes

  1. SeriesList are now constructed in a more consistent way with a function specific to the type. This removes from the public API NewSeriesListDataFromValues and NewSeriesFromValues. Instead of optionally passing in a chart type it's now expected to call a function specific to the chart type: NewSeriesListX (with X being the chart type). Though manual SeriesList construction is less needed, in general chart Options structs are easier to construct by using NewXChartOptionWithData (for example: TestNewLineChartOptionWithData).

  2. SeriesData struct has been removed, instead we just use a float64 slice in Series to reference the values directly.

Painter Changes

The Painter is designed to be much more useful directly. It can be constructed easily using NewPainter, and then charts config structs can be built and rendered to the Painter. Additional public functions allow you to annotate text, lines, and other additional elements you may want to render on to your charts.

  1. Renderer type has been made private, and New functions to create these structs has been removed. For rendering charts using the Painter API, these functions are now invoked on a Painter instance, for example:

    • NewBarChart -> Painter.BarChart
    • NewHorizontalBarChart -> Painter.HorizontalBarChart
    • NewFunnelChart -> Painter.FunnelChart
    • NewLineChart -> Painter.LineChart
    • NewPieChart -> Painter.PieChart
    • NewRadarChart -> Painter.RadarChart
    • NewTableChart -> Painter.TableChart

  2. The style in Painter (ie fill color, stroke color, stroke width, etc) is no longer stateful, instead these style attributes are accepted as function arguments. In general functions have changed on the Painter to make it more obvious what is useful for external users.

  3. ValueFormatter has been removed as configuration on the Painter. Instead this should now be specified on the charts which make use of this field.

Helper Constructors

  • The functions NewLegendOption, NewXAxisOption, and NewYAxisOptions have been removed (see PR #20). Structs are now created directly: 
    // Old
opt.XAxis = NewXAxisOption(data, charts.True())

// New
opt.XAxis = XAxis{
    Data:        data,
    BoundaryGap: charts.True(),
}

The exception to this is the chart specific configs, which can be constructed using NewBarChartOptionWithData, NewHorizontalBarChartOptionWithData, NewLineChartOptionWithData, etc.

Chart-Specific Tweaks

  1. Line Charts

    • Opacity → FillOpacity (clarify that it’s the fill area opacity).

  2. Grid & Table Charts

    • Column / Row → Columns / Rows
    • Padding → CellPadding to avoid confusion with chart-level padding.

  3. Table Cells

    • A CellModifier callback can now override cell styles before rendering.
    • TableChartOption uses FontStyle for text, top-level FontSize, FontColor, etc., are moved to to this struct.

  4. Bar Charts

    • YAxisOptions replaced with YAxis.

Something Missing or Need Help?

A focus of our fork has been to make the API easier to understand. As part of that we have made many public functions and structs internal (see PR #27).

If you rely directly on functionality we’ve hidden or need help migrating, please open an Issue. We watch them closely and welcome your feedback to make the library better for everyone.

Clone this wiki locally