Chart¶

The main class for creating and configuring charts.

Main class for creating and configuring charts.

Provides a fluent API for mapping data columns to chart attributes, adding geometric layers, faceting, theming, displaying, and exporting charts. Supports pandas DataFrame, polars DataFrame, and numpy ndarray as input.

Example

import gocharts as go
import pandas as pd

df = pd.DataFrame({'x': [1, 2, 3], 'y': [10, 20, 30]})
chart = (go.Chart(df)
    .map(x='x', y='y')
    .geom('line')
)
chart.display()

`init(data=None, map=None)` ¶

Initialize a Chart with optional data and column mapping.

Parameters:

Name	Type	Description	Default
`data`	`DataFrame \| DataFrame \| ndarray \| None`	Input data as a pandas DataFrame, polars DataFrame, or numpy ndarray.	`None`
`map`	`dict \| None`	Dictionary mapping chart attributes to data column names (e.g., `{'x': 'col_a', 'y': 'col_b'}`).	`None`

Raises:

Type	Description
`TypeError`	If the provided data is not a supported type.

`map(**kwargs)` ¶

Map data columns to chart visual attributes.

Parameters:

Name	Type	Description	Default
`**kwargs`	`str`	Chart attribute to column name mappings. Common keys: `x`, `y`, `color`, `size`.	`{}`

Returns:

Name	Type	Description
`Chart`		The chart instance for method chaining.

Raises:

Type	Description
`ValueError`	If the mapping is invalid or columns don't exist in the data.

Example

chart.map(x='Category', y='Value', color='Group')

`title(title, subtitle=None)` ¶

Set the chart title and optional subtitle.

Parameters:

Name	Type	Description	Default
`title`	`str`	The main title text.	required
`subtitle`	`str \| None`	Optional subtitle text displayed below the title.	`None`

Returns:

Name	Type	Description
`Chart`		The chart instance for method chaining.

Raises:

Type	Description
`TypeError`	If title or subtitle is not a string.

`geom(type, **kwargs)` ¶

Add a geometric layer to the chart.

Parameters:

Name	Type	Description	Default
`type`	`str`	Chart type — `'bar'`, `'line'`, `'scatter'`/`'point'`, `'heatmap'`/`'tile'`.	required
`**kwargs`		Optional overrides: map (dict): Column mapping for this layer only. data (pandas.DataFrame \| polars.DataFrame): Data source for this layer only. symbol (str): Point symbol — `'circle'`, `'rect'`, `'roundRect'`, `'triangle'`, `'diamond'`, `'pin'`, `'arrow'`, `'none'`, `'emptyCircle'`. symbolSize (int \| float): Size of the point symbol.	`{}`

Returns:

Name	Type	Description
`Chart`		The chart instance for method chaining.

Raises:

Type	Description
`ValueError`	If the chart type or mapping is invalid.

Example

chart.geom('bar')
chart.geom('scatter', symbol='diamond', symbolSize=10)

`axis(axis=None, type=None, name=None, n_breaks=5, breaks=None, minor_breaks=None, breaks_labels=None, limits=None, expand=[0.05, 0], inverse=False)` ¶

Configure an axis.

Parameters:

Name	Type	Description	Default
`axis`	`str`	Which axis to configure — `'x'` or `'y'`.	`None`
`type`	`str \| None`	Axis scale type — `'category'`, `'value'`, `'time'`, or `'log'`.	`None`
`name`	`str \| None`	Axis label text.	`None`
`n_breaks`	`int`	Target number of major tick marks.	`5`
`breaks`	`list \| None`	Explicit positions for major ticks.	`None`
`minor_breaks`	`list \| None`	Explicit positions for minor ticks.	`None`
`breaks_labels`	`list \| None`	Custom labels for major ticks.	`None`
`limits`	`list \| None`	Axis range as `[min, max]`.	`None`
`expand`	`list`	Expansion factor as `[multiplicative, additive]`.	`[0.05, 0]`
`inverse`	`bool`	Whether to invert the axis direction.	`False`

Returns:

Name	Type	Description
`Chart`		The chart instance for method chaining.

Raises:

Type	Description
`ValueError`	If axis is not `'x'` or `'y'`, or type is unrecognised.

`matrix(col=None, row=None)` ¶

Configure a matrix grid layout.

Parameters:

Name	Type	Description	Default
`col`	`list[str] \| None`	Column names to display in the matrix.	`None`
`row`	`list[str] \| None`	Row names to display in the matrix.	`None`

Returns:

Name	Type	Description
`Chart`		The chart instance for method chaining.

`facet(col=None, row=None, scales='fixed', space=0.1)` ¶

Split the chart into a grid of subplots by data variables.

Parameters:

Name	Type	Description	Default
`col`	`str \| None`	Column name to facet by (creates columns of subplots).	`None`
`row`	`str \| None`	Column name to facet by (creates rows of subplots).	`None`
`scales`	`str`	How axes are shared across facets — `'fixed'`, `'free'`, `'free_x'`, or `'free_y'`.	`'fixed'`
`space`	`float`	Relative spacing between facets, between 0 and 1.	`0.1`

Returns:

Name	Type	Description
`Chart`		The chart instance for method chaining.

Raises:

Type	Description
`ValueError`	If neither `col` nor `row` is provided.

Example

chart.facet(col='Region', row='Year', scales='free_y')

`theme(theme=None)` ¶

Apply a theme to the chart.

Parameters:

Name	Type	Description	Default
`theme`	`Theme`	A `Theme` instance with styling configuration.	`None`

Returns:

Name	Type	Description
`Chart`		The chart instance for method chaining.

Example

my_theme = (go.Theme()
    .axis.title(color='#0000ff')
    .axis.ticks.x(color='#ff0000')
    .facet.label.col(color='#00ff00')
    .grid.margin(bottom='15%')
)
chart.theme(my_theme)

`display(width='600px', height='400px')` ¶

Display the chart in a Jupyter notebook.

Parameters:

Name	Type	Description	Default
`width`	`str`	Chart width as a CSS value (e.g., `'600px'`, `'100%'`).	`'600px'`
`height`	`str`	Chart height as a CSS value (e.g., `'400px'`).	`'400px'`

`print(width='600px', height='400px')` ¶

Return the chart configuration as a JSON text string.

Parameters:

Name	Type	Description	Default
`width`	`str`	Chart width as a CSS value (e.g., `'600px'`).	`'600px'`
`height`	`str`	Chart height as a CSS value (e.g., `'400px'`).	`'400px'`

Returns:

Name	Type	Description
`str`		JSON string of the chart options.

`save(file_name, type='html', width='600px', height='400px')` ¶

Save the chart to a file.

Parameters:

Name	Type	Description	Default
`file_name`	`str`	Output file path.	required
`type`	`str`	Export format — `'html'` or `'text'`.	`'html'`
`width`	`str`	Chart width as a CSS value (e.g., `'600px'`).	`'600px'`
`height`	`str`	Chart height as a CSS value (e.g., `'400px'`).	`'400px'`

Returns:

Name	Type	Description
`str`		JSON string of chart options when `type='text'`.

Raises:

Type	Description
`ValueError`	If type is not `'text'` or `'html'`.

Example

chart.save('output.html', width='800px', height='500px')

Chart¶

__init__(data=None, map=None) ¶

map(**kwargs) ¶

title(title, subtitle=None) ¶

geom(type, **kwargs) ¶

axis(axis=None, type=None, name=None, n_breaks=5, breaks=None, minor_breaks=None, breaks_labels=None, limits=None, expand=[0.05, 0], inverse=False) ¶

matrix(col=None, row=None) ¶

facet(col=None, row=None, scales='fixed', space=0.1) ¶

theme(theme=None) ¶

display(width='600px', height='400px') ¶

print(width='600px', height='400px') ¶

save(file_name, type='html', width='600px', height='400px') ¶

`init(data=None, map=None)` ¶

`map(**kwargs)` ¶

`title(title, subtitle=None)` ¶

`geom(type, **kwargs)` ¶

`axis(axis=None, type=None, name=None, n_breaks=5, breaks=None, minor_breaks=None, breaks_labels=None, limits=None, expand=[0.05, 0], inverse=False)` ¶

`matrix(col=None, row=None)` ¶

`facet(col=None, row=None, scales='fixed', space=0.1)` ¶

`theme(theme=None)` ¶

`display(width='600px', height='400px')` ¶

`print(width='600px', height='400px')` ¶

`save(file_name, type='html', width='600px', height='400px')` ¶