vicanso go‐charts Migration Guide

This guide explains how to migrate from the archived vicanso/go-charts to go-analyze/charts. Subsequent updates are documented in the go-analyze/charts Version Migration Guide.

Fork Overview

We forked vicanso/go-charts to enhance the flexibility and readability of the charts for a wider range of data sets. Initially, we focused on improving x-axis rendering. Since then, we have expanded unit test coverage, which has helped us find and fix numerous bugs, especially for unusual datasets.

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

---

Updating Your Code to Use go-analyze/charts

Below are the key changes for migrating your code. They are grouped by configuration area to help you find where your code needs changes. 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	Removed in favor of specific types
TrueFlag(), FalseFlag()	Ptr(true) / Ptr(false)	#44	Replaced with generic pointer helper functions
NewFloatPoint(float64)	Ptr(float64)	#44	New name for float-pointer constructor using generics
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
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	Painter.ArrowUp	#27	Renamed for clarity
Painter.ArrowBottom	Painter.ArrowDown	#27	Renamed for clarity
LineChartOption.StrokeWidth	LineStrokeWidth	#27	Renamed for consistency
LineChartOption.SymbolShow	LineChartOption.Symbol	#44	Now accepts multiple symbol types, use SymbolNone to disable symbols
XAxisOption.TextRotation	XAxisOption.LabelRotation	#44	Clarifies the labels are being rotated
LegendOption.Icon	LegendOption.Symbol	#44	Consistent naming with LineChartOption
LegendOption.Data	LegendOption.SeriesNames	#44	To clarify this correlates to the names of the series
XAxisOption.Data	XAxisOption.Labels	#44	Clarifies that this represents axis labels rather than series data
YAxisOption.Data	YAxisOption.Labels	#44	Clarifies that this represents axis labels rather than series data
XAxisDataOptionFunc	XAxisLabelsOptionFunc	#44	Updated to reflect new field name
YAxisDataOptionFunc	YAxisLabelsOptionFunc	#44	Updated to reflect new field name

General Configuration Changes

1. Type → OutputFormat
   • Clarifies that the field sets the output format (e.g., "png", "svg"). (see PR #5)

• TypeOptionFunc has been replaced by SVGOutputOptionFunc() and PNGOutputOptionFunc() for clarity. (see PR #27)

2. Option Helper Functions Replaced with charts.Ptr

   • More concise API, and allows better struct construction readability (see PR #44).
   • TrueFlag(), FalseFlag(), BoolPointer(bool), and FloatPointer(float64) replaced with the generic charts.Ptr().
   • Example: NewFloatPointer(1.5) → Ptr(1.5)

3. “Option” Suffix Removed from Field Names

   • Fields and types ending in Options or Option have been renamed. For example, YAxisOptions is now YAxis. (see PR #5)

4. Fonts and Themes Removed From Global Registry

   • Themes and Fonts are now set directly on the chart configuration instead of being looked up from a global registry. You can still load built-in themes by name (e.g., GetTheme(...)), but it is no longer required. (see PR #4)
   • Many color fields were removed in favor of themes. For specific overrides, use theme modifiers like WithAxisColor(...).

5. Font Configuration with FontStyle

   • Instead of separate top-level properties like FontSize and FontColor, each component (title, legend, axis) now has a FontStyle struct to configure font properties.

6. Dimensions Now Set Together

   • WidthOptionFunc and HeightOptionFunc are now consolidated into DimensionsOptionFunc. Similarly, SetDefaultWidth and SetDefaultHeight are replaced by SetDefaultChartDimensions. (see PR #27)

Axis Configuration

1. YAxisOptions → YAxis

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

2. Field Renaming

   • Data → Labels - Clarifies that this field represents axis labels, not series data (see PR #44).
   • FirstAxis → DataStartIndex - To clarify it is the zero-based index from which Labels should begin (see PR #5).
   • TextRotation → LabelRotation - To clarify that the axis labels are being rotated (see PR #44).

3. FirstAxis → DataStartIndex

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

4. Removed Color Fields

   • StrokeColor and SplitLineColor have been removed; rely on the theme (see PR #5).
   • YAxis.Color has been removed; use themes to set the y-axis color (see PR #44)

5. Axis Label Configuration (see PR #3)

   • Unit: Suggests the increment for axis labels. The minimum and maximum values are always shown.
   • LabelCount: Sets the exact number of labels to render, overriding Unit if both are set.
   • LabelCountAdjustment: Relative tweak to the auto-determined label count (negative yields fewer labels, positive yields more).
   • LabelSkipCount: Skips rendering every Nth label.
   • RangeValuePaddingScale: Suggests extra padding for the y-axis range. No padding is added if Min or Max are set explicitly (unless needed to satisfy Unit).
   • SplitNumber: REMOVED. Use the properties described above instead.

Legend Configuration

1. Field Renaming
   • Icon → Symbol - For consistency with LineChartOption; now accepts more symbol types.
   • Data → SeriesNames - To clarify this correlates to the names of the series.

Positioning of Titles, Legends, and 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.
   • The previous PositionLeft, PositionCenter, and PositionRight are now OffsetLeft, OffsetCenter, and OffsetRight.

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)

• When a legend is present without a title, vicanso/go‐charts would overlap the legend with the chart data. We now space the chart below the legend. To restore the old behavior, set LegendOption.OverlayChart to *true.

Series Changes

1. SeriesList construction is now type-specific. NewSeriesListDataFromValues and NewSeriesFromValues have been removed. Use type-specific constructors like NewSeriesListX instead (where X is the chart type). Though Options structs can be more easily created with helpers like NewXChartOptionWithData, reducing the need for manual SeriesList construction.

2. The SeriesData struct has been removed. Series values are now stored directly as a float64 slice.

3. Chart-Specific Series Types

   • The SeriesList type is now specific to each chart type (see PR #44):
     • ChartOption → GenericSeriesList
     • LineChartOption → LineSeriesList
     • BarChartOption → BarSeriesList
     • HorizontalBarChartOption → HorizontalBarSeriesList
     • FunnelChartOption → FunnelSeriesList
     • PieChartOption → PieSeriesList
     • RadarChartOption → RadarSeriesList
   • Fields have been renamed for consistency:
     • Data → Values (or Value for single-value charts like Pie and Funnel)
   • Example: NewSeriesListLine replaces previous generic series list creation (see PR #45).

4. Series Labeling

   • Formatter → replaced with FormatTemplate
   • Position → moved to chart Options struct as SeriesLabelPosition for bar and horizontal bar charts

Painter Changes

The Painter is now more flexible. You can create one with NewPainter, build chart configuration structs, and render them to the Painter. Public functions are available to add annotations like text, lines, arrows and additional elements to your charts.

1. The Renderer type and its New* constructor functions have been removed. To render charts, call the corresponding methods on a Painter instance:

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

2. The Painter is no longer stateful. Style attributes (e.g., fill color, stroke width) are now passed as arguments to its functions. The Painter API has been revised to be more user-friendly.

3. ValueFormatter has been removed from the Painter configuration. It should now be specified on the chart Options struct or other relevant configurations, allowing for more precise format control.

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{
      Labels:       data,
      BoundaryGap: charts.Ptr(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 is now FillOpacity to clarify that it applies to the fill area.
   • FillArea is now a boolean pointer, set using charts.Ptr(true).
   • ShowSymbol is replaced with Symbol, accepting multiple symbol types. To hide symbols, use SymbolNone.

2. Table Charts

   • Padding is now CellPadding to avoid confusion with chart-level padding.
   • A CellModifier callback can now be used to override cell styles before rendering.
   • TableChartOption now uses a FontStyle struct for text styling, replacing top-level properties like FontSize and FontColor.

3. Bar Charts

   • YAxisOptions replaced with YAxis.

4. Horizontal Bar Charts

   • YAxis is now a single struct instead of a slice.

---

Something Missing or Need Help?

To make the API easier to understand, we have made many functions and structs internal (see PR #27).

If you rely on functionality that is no longer public or need help migrating, please open an issue. We watch issues closely and welcome your feedback.