Quick Start¶

This guide will help you create your first chart with GoCharts in just a few minutes.

Your First Chart¶

Let's create a simple line chart:

import gocharts as go
import pandas as pd

# Create sample data
data = pd.DataFrame({
    'time': range(1, 11),
    'temperature': [15, 16, 18, 20, 22, 24, 23, 21, 19, 17]
})

# Create the chart
chart = (
    go.Chart(data)
    .map(x='time', y='temperature')
    .geom('line')
)

# Display the chart
chart.display()

Understanding the Syntax¶

GoCharts uses a method chaining approach:

1. Initialize with Data¶

go.Chart(data)

Chart() initializes the chart with your data (pandas or polars DataFrame)

2. Map Aesthetics¶

.map(x='time', y='temperature', color='category')

.map() defines aesthetic mappings (which columns map to x, y, color, size, etc.)

3. Add Geometry Layers¶

.geom('line')

.geom() adds visual representations
Common geometries: 'line', 'bar', 'point', 'area', 'tile'

4. Additional Customization¶

.title(title='Temperature Over Time', subtitle='Hourly measurements')
.theme(go.Theme())
.axis('y', limits=[0, 50])

More Examples¶

Bar Chart¶

import gocharts as go
import pandas as pd

sales_data = pd.DataFrame({
    'product': ['A', 'B', 'C', 'D'],
    'revenue': [23000, 45000, 32000, 51000]
})

chart = (
    go.Chart(sales_data)
    .map(x='product', y='revenue')
    .geom('bar')
    .title(title='Product Revenue')
    .axis('y', name='Revenue ($)')
)

chart.display()

Scatter Plot¶

import gocharts as go
import pandas as pd

scatter_data = pd.DataFrame({
    'x': [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
    'y': [2.3, 3.1, 3.8, 5.2, 6.1, 6.8, 7.5, 8.2, 8.9, 9.5],
    'category': ['A', 'B', 'A', 'B', 'A', 'B', 'A', 'B', 'A', 'B']
})

chart = (
    go.Chart(scatter_data)
    .map(x='x', y='y', color='category')
    .geom('point', symbolSize=10)
)

chart.display()

Multiple Layers¶

import gocharts as go

chart = (
    go.Chart(data)
    .map(x='time', y='temperature')
    .geom('line')
    .geom('point', symbolSize=8)
    .title(
        title='Temperature Monitoring',
        subtitle='Hourly measurements'
    )
    .axis('x', name='Time (hours)')
    .axis('y', name='Temperature (°C)')
)

chart.display()

Display Options¶

In Jupyter Notebooks¶

Display charts inline in Jupyter:

chart.display()  # Default size: 600px x 400px
chart.display(width='800px', height='600px')  # Custom size

Save to File¶

chart.save('my_chart.html')
chart.save('my_chart.html', width='800px', height='600px')

Get as Text¶

html_string = chart.print()  # Returns HTML as string

Customization¶

Themes¶

import gocharts as go

# Create and apply custom theme
my_theme = (
    go.Theme()
    .axis.label(color='#44ee44', font='Arial')
    .axis.line(color='#44ee44')
    .axis.ticks.x(color='#44ee44')
)

chart.theme(my_theme)

Colors¶

# Color by category (mapped to data column)
.map(x='x', y='y', color='category')

# Custom symbol properties
.geom('point', symbol='diamond', symbolSize=12)

Titles and Labels¶

chart.title(
    title='Main Title',
    subtitle='Subtitle text'
)

chart.axis('x', name='X-axis label')
chart.axis('y', name='Y-axis label')

What's Next?¶

Explore the Gallery for more inspiration
Check out Basic Charts for detailed examples
Learn about Advanced Charts for complex visualizations
Dive into the API Reference for complete documentation

Common Patterns¶

Loading Data¶

GoCharts works with pandas DataFrames:

import pandas as pd

# From CSV
data = pd.read_csv('data.csv')

# From dict
data = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]})

# From API/JSON
data = pd.read_json('https://api.example.com/data')

Chaining Operations¶

Build complex charts step by step:

chart = go.Chart(data)
chart = chart.map(x='x', y='y')
chart = chart.geom('point')
chart = chart.geom('line')
chart.display()

Or use the fluent/chained syntax:

(
    go.Chart(data)
    .map(x='x', y='y')
    .geom('point')
    .geom('line')
    .theme(go.Theme())
).display()