Help us shape the future of Go! Take the 2026 Go Developer Survey

timeserieslinechart

package
v2.8.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 11, 2026 License: MIT Imports: 12 Imported by: 3

Documentation

Overview

Package timeserieslinechart implements a linechart that draws lines for time series data points

Index

Constants

View Source 
const DefaultDataSetName = "default"

Variables

This section is empty.

Functions

func DateNoZoomUpdateHandler 

func DateNoZoomUpdateHandler(i int) linechart.UpdateHandler

DateNoZoomUpdateHandler is used by timeserieslinechart to enable moving the viewing window by using the mouse scroll wheel, holding down mouse button and moving, and moving the viewing window with the arrow keys. There is only movement along the X axis by day increments. Uses linechart Canvas Keymap for keyboard messages.

func DateTimeLabelFormatter 

func DateTimeLabelFormatter() linechart.LabelFormatter

func DateUpdateHandler 

func DateUpdateHandler(i int) linechart.UpdateHandler

DateUpdateHandler is used by timeserieslinechart to enable zooming in and out with the mouse wheel or page up and page down, moving the viewing window by holding down mouse button and moving, and moving the viewing window with the arrow keys. There is only movement along the X axis by day increments. Uses linechart Canvas Keymap for keyboard messages.

func HourNoZoomUpdateHandler 

func HourNoZoomUpdateHandler(i int) linechart.UpdateHandler

HourNoZoomUpdateHandler is used by timeserieslinechart to enable moving the viewing window by using the mouse scroll wheel, holding down mouse button and moving, and moving the viewing window with the arrow keys. There is only movement along the X axis by hour increments. Uses linechart Canvas Keymap for keyboard messages.

func HourTimeLabelFormatter 

func HourTimeLabelFormatter() linechart.LabelFormatter

func HourUpdateHandler 

func HourUpdateHandler(i int) linechart.UpdateHandler

HourUpdateHandler is used by timeserieslinechart to enable zooming in and out with the mouse wheel or page up and page down, moving the viewing window by holding down mouse button and moving, and moving the viewing window with the arrow keys. There is only movement along the X axis by hour increments. Uses linechart Canvas Keymap for keyboard messages.

func SecondNoZoomUpdateHandler 

func SecondNoZoomUpdateHandler(i int) linechart.UpdateHandler

SecondNoZoomUpdateHandler is used by timeserieslinechart to enable moving the viewing window by using the mouse scroll wheel, holding down mouse button and moving, and moving the viewing window with the arrow keys. There is only movement along the X axis by second increments. Uses linechart Canvas Keymap for keyboard messages.

func SecondUpdateHandler 

func SecondUpdateHandler(i int) linechart.UpdateHandler

SecondUpdateHandler is used by timeserieslinechart to enable zooming in and out with the mouse wheel or page up and page down, moving the viewing window by holding down mouse button and moving, and moving the viewing window with the arrow keys. There is only movement along the X axis by second increments. Uses linechart Canvas Keymap for keyboard messages.

Types

type DrawCandleOpts added in v2.7.1 

type DrawCandleOpts struct {
	// Width is the candle body width in columns; < 1 is treated as 1.
	Width int
	// Block renders solid block bodies (█ ▄ ▀) instead of line runes.
	Block bool
}

DrawCandleOpts configures candle drawing.

type FitYOpts added in v2.7.1 

type FitYOpts struct {
	// DataSets selects the data sets to fit. Nil selects all data sets on the left Y axis;
	// an empty, non-nil slice selects none. Unknown names are ignored.
	DataSets []string
	// IncludeZero includes a zero baseline on a linear Y axis.
	// It is ignored on a logarithmic Y axis.
	IncludeZero bool
}

FitYOpts configures fitting the Y viewport to stored points in the time viewport.

type Model 

type Model struct {
	linechart.Model
	// contains filtered or unexported fields
}

Model contains state of a timeserieslinechart with an embedded linechart.Model The X axis contains time.Time values and the Y axis contains float64 values. A data set consists of a sequence TimePoints in chronological order. If multiple TimePoints map to the same column, then average value the time points will be used as the Y value of the column. The X axis contains a time range and the Y axis contains a numeric value range. Uses linechart Model UpdateHandler() for processing keyboard and mouse messages.

func New 

func New(w, h int, opts ...Option) Model

New returns a timeserieslinechart Model initialized from width, height, Y value range and various options. By default, the chart will set time.Now() as the minimum time, enable auto set X and Y value ranges, and only allow moving viewport on X axis.

func (*Model) ClearAllData 

func (m *Model) ClearAllData()

ClearAllData will reset stored data values in all data sets.

func (*Model) ClearDataSet 

func (m *Model) ClearDataSet(n string)

ClearDataSet will erase stored data set given by name string.

func (*Model) ClearY2Axis added in v2.8.0 

func (m *Model) ClearY2Axis()

ClearY2Axis removes the right Y axis. Data sets keep their axis assignment, and those on the right are drawn against the left axis until a right axis is set again. Existing data will be rescaled.

func (*Model) Draw 

func (m *Model) Draw()

Draw will draw lines runes displayed from left to right of the graphing area of the canvas. Uses default data set.

func (*Model) DrawAll 

func (m *Model) DrawAll()

DrawAll will draw lines runes for all data sets from left to right of the graphing area of the canvas.

func (*Model) DrawBraille 

func (m *Model) DrawBraille()

DrawBraille will draw braille runes displayed from left to right of the graphing area of the canvas. Uses default data set.

func (*Model) DrawBrailleAll 

func (m *Model) DrawBrailleAll()

DrawBrailleAll will draw braille runes for all data sets from left to right of the graphing area of the canvas.

func (*Model) DrawBrailleDataSets 

func (m *Model) DrawBrailleDataSets(names []string)

DrawBrailleDataSets will draw braille runes from left to right of the graphing area of the canvas for each data set given by name strings.

func (*Model) DrawCandle 

func (m *Model) DrawCandle(openName, highName, lowName, closeName string, bullStyle, bearStyle lipgloss.Style)

DrawCandle draws single-column line-style candles. See DrawCandleWithOpts.

func (*Model) DrawCandleWithOpts added in v2.7.1 

func (m *Model) DrawCandleWithOpts(openName, highName, lowName, closeName string, bullStyle, bearStyle lipgloss.Style, opts DrawCandleOpts)

DrawCandleWithOpts draws candles with the given body width and style. The body spans opts.Width columns centered on the candle's time-scaled column, the wick stays in the center column. Width < 1 is treated as 1.

Side columns are clamped to the graph area: columns at or left of the y-axis (Origin().X when YStep() > 0, or left of Origin().X when YStep() == 0 since there is no axis line) are skipped so wide candles never overdraw the y-axis or its tick labels, both of which live inside the canvas. Values outside the Y viewport are clipped before drawing so candles do not overwrite the x-axis or its labels.

The candle's center column is clamped so its whole body fits in the drawable span (edge inset): edge candles shift inward up to half a body from their true time position instead of rendering half-clipped. This deliberately changes the output for the first and newest candles: at width 1 the inset is zero (half == right == 0) so behavior is unchanged and reduces to the previous newest-candle clamp.

Requires four data sets containing candlestick data open, high, low, close values. Assumes that all data sets have the same number of TimePoints and the TimePoint at the same index of each data set has the same Time value.

func (*Model) DrawDataSets 

func (m *Model) DrawDataSets(names []string)

DrawDataSets will draw lines runes from left to right of the graphing area of the canvas for each data set given by name strings.

func (*Model) FitYToView added in v2.7.1 

func (m *Model) FitYToView() bool

FitYToView fits the displayed Y range to all stored points whose timestamps are inside the current time viewport, including both endpoints. See FitYToViewWithOpts for dataset selection and a zero baseline.

func (*Model) FitYToViewWithOpts added in v2.7.1 

func (m *Model) FitYToViewWithOpts(opts FitYOpts) bool

FitYToViewWithOpts fits the displayed left Y range to the selected data sets. Data sets drawn against the right Y axis are never fitted, even if selected. It ignores non-finite values and values invalid on the Y scale. If there are no eligible points, it returns false and leaves the ranges unchanged. Constant values get a nonzero range (5% or at least 1 on a linear axis, half a decade on either side on a log axis). Expected Y bounds expand if needed but never shrink, so retained history remains available for zooming. AutoMinY and AutoMaxY are unchanged; this explicit fit overrides manual Y zoom. Only stored points are considered, not interpolated boundary values.

func (*Model) Push 

func (m *Model) Push(t TimePoint)

Push will push a TimePoint data value to the default data set to be displayed with Draw.

func (*Model) PushDataSet 

func (m *Model) PushDataSet(n string, t TimePoint)

Push will push a TimePoint data value to a data set to be displayed with Draw. Using given data set by name string.

func (*Model) Resize 

func (m *Model) Resize(w, h int)

Resize will change timeserieslinechart display width and height. Existing data will be rescaled.

func (*Model) SetColumnBackgroundStyle 

func (m *Model) SetColumnBackgroundStyle(ts time.Time, s lipgloss.Style)

Set column background style to given lipgloss.Style background corresponding to timestamp at given time.Time.

func (*Model) SetDataSetLineStyle 

func (m *Model) SetDataSetLineStyle(n string, ls runes.LineStyle)

SetDataSetLineStyle will set the line style of the given data set by name string.

func (*Model) SetDataSetStyle 

func (m *Model) SetDataSetStyle(n string, s lipgloss.Style)

SetDataSetStyle will set the lipgloss style of the given data set by name string.

func (*Model) SetDataSetYAxis added in v2.8.0 

func (m *Model) SetDataSetYAxis(n string, side linechart.YAxisSide)

SetDataSetYAxis puts the data set given by name string on the left or right Y axis, creating the data set if needed. All data sets start on the left axis. A data set on the right axis is drawn, auto-ranged and fitted as a left one while the chart has no right axis (see SetY2Axis). Data sets drawn together by DrawCandle should share one axis.

func (*Model) SetLineStyle 

func (m *Model) SetLineStyle(ls runes.LineStyle)

SetLineStyle will set the default line styles of data sets.

func (*Model) SetStyle 

func (m *Model) SetStyle(s lipgloss.Style)

SetStyle will set the default lipgloss styles of data sets.

func (*Model) SetTimeRange 

func (m *Model) SetTimeRange(min, max time.Time)

SetTimeRange updates the minimum and maximum expected time values. Existing data will be rescaled.

func (*Model) SetViewTimeAndYRange 

func (m *Model) SetViewTimeAndYRange(minX, maxX time.Time, minY, maxY float64)

SetViewTimeAndYRange updates the displayed minimum and maximum time and Y values. Existing data will be rescaled.

func (*Model) SetViewTimeRange 

func (m *Model) SetViewTimeRange(min, max time.Time)

SetViewTimeRange updates the displayed minimum and maximum time values. Existing data will be rescaled.

func (*Model) SetViewYRange 

func (m *Model) SetViewYRange(min, max float64)

SetViewYRange updates the displayed minimum and maximum Y values. Existing data will be rescaled.

func (*Model) SetY2Axis added in v2.8.0 

func (m *Model) SetY2Axis(a linechart.Axis)

SetY2Axis adds a right Y axis, or replaces it. See linechart.Model.SetY2Axis. Put data sets on it with SetDataSetYAxis. Data pushed to right-assigned sets before this call was auto-ranged against the left axis, and that left range is not undone. Existing data will be rescaled.

func (*Model) SetYAxis added in v2.8.0 

func (m *Model) SetYAxis(a linechart.Axis)

SetYAxis sets the left Y axis. See linechart.Model.SetYAxis. Existing data will be rescaled.

func (*Model) SetYRange 

func (m *Model) SetYRange(min, max float64)

SetYRange updates the minimum and maximum expected Y values. Existing data will be rescaled.

func (*Model) SetYScale added in v2.7.1 

func (m *Model) SetYScale(s linechart.Scale)

SetYScale sets the scale of the Y axis. See linechart.Model.SetYScale. On a log Y axis, values that are not greater than zero are not drawn: lines break around them and their candles are left out. Existing data will be rescaled.

func (*Model) TrimBefore added in v2.7.1 

func (m *Model) TrimBefore(t time.Time) int

TrimBefore removes points strictly before t from every data set and returns the number removed. Points exactly at t are retained. Like Push, timestamps are compared at millisecond resolution, and data must be chronological. Surviving points are copied to new buffers so discarded storage is released. Styles, expected ranges and viewports are unchanged; call FitYToView to refit Y afterwards. To preserve interpolation at the left edge, trim at an earlier timestamp than the viewport's start to keep a preceding sample.

func (Model) Update 

func (m Model) Update(msg tea.Msg) (Model, tea.Cmd)

Update processes bubbletea Msg by invoking UpdateHandlerFunc callback if linechart is focused.

type Option 

type Option func(*Model)

Option is used to set options when initializing a timeserieslinechart. Example: 

tslc := New(width, height, minX, maxX, minY, maxY, WithStyles(someLineStyle, someLipglossStyle))

func WithAxesStyles 

func WithAxesStyles(as lipgloss.Style, ls lipgloss.Style) Option

WithAxesStyles sets the axes line and line label styles.

func WithDataSetLineStyle 

func WithDataSetLineStyle(n string, ls runes.LineStyle) Option

WithDataSetLineStyle sets the line style of the data set given by name.

func WithDataSetStyle 

func WithDataSetStyle(n string, s lipgloss.Style) Option

WithDataSetStyle sets the lipgloss style of the data set given by name.

func WithDataSetTimeSeries 

func WithDataSetTimeSeries(n string, p []TimePoint) Option

WithDataSetTimeSeries adds []TimePoint data points to the data set given by name.

func WithDataSetYAxis added in v2.8.0 

func WithDataSetYAxis(n string, side linechart.YAxisSide) Option

WithDataSetYAxis puts the data set given by name on the left or right Y axis. See Model.SetDataSetYAxis. Give it and WithY2Axis before the data set's data (WithDataSetTimeSeries) so that data auto-ranges the right axis.

func WithLineChart 

func WithLineChart(lc *linechart.Model) Option

WithLineChart sets internal linechart to given linechart.

func WithLineStyle 

func WithLineStyle(ls runes.LineStyle) Option

WithLineStyle sets the default line style of data sets.

func WithStyle 

func WithStyle(s lipgloss.Style) Option

WithStyle sets the default lipgloss style of data sets.

func WithTimeRange 

func WithTimeRange(min, max time.Time) Option

WithTimeRange sets expected and displayed minimun and maximum time values range on the X axis.

func WithTimeSeries 

func WithTimeSeries(p []TimePoint) Option

WithTimeSeries adds []TimePoint values to the default data set.

func WithUpdateHandler 

func WithUpdateHandler(h linechart.UpdateHandler) Option

WithUpdateHandler sets the UpdateHandler used when processing bubbletea Msg events in Update().

func WithXLabelFormatter 

func WithXLabelFormatter(fmter linechart.LabelFormatter) Option

WithXLabelFormatter sets the default X label formatter for displaying X values as strings.

func WithXYSteps 

func WithXYSteps(x, y int) Option

WithXYSteps sets the number of steps when drawing X and Y axes values. If X steps 0, then X axis will be hidden. If Y steps 0, then Y axis will be hidden.

func WithY2Axis added in v2.8.0 

func WithY2Axis(a linechart.Axis) Option

WithY2Axis adds a right Y axis. See Model.SetY2Axis.

func WithYLabelFormatter 

func WithYLabelFormatter(fmter linechart.LabelFormatter) Option

WithYLabelFormatter sets the default Y label formatter for displaying Y values as strings.

func WithYRange 

func WithYRange(min, max float64) Option

WithYRange sets expected and displayed minimum and maximum Y value range.

func WithYScale added in v2.7.1 

func WithYScale(s linechart.Scale) Option

WithYScale sets the scale of the Y axis: linechart.ScaleLinear (the default) or linechart.ScaleLog. See Model.SetYScale. The X axis is time and is always linear.

func WithZoneManager 

func WithZoneManager(zm *zone.Manager) Option

WithZoneManager sets the bubblezone Manager used when processing bubbletea Msg mouse events in Update().

type TimePoint 

type TimePoint struct {
	Time  time.Time
	Value float64
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.