ggplot

The main plotting class.

ggplotly.ggplot.ggplot

__init__(data=None, mapping=None)

Initialize a ggplot object.

Parameters:

Name	Type	Description	Default
data	DataFrame or Series	The dataset to plot. Can be None if geoms provide their own data. Supports automatic index handling: Series: Converted to DataFrame with values as y and index as x DataFrame: Index can be referenced using x='index' in aes()	None
mapping	aes	Aesthetic mappings created by aes(). Supports index references: x='index': Explicitly use the DataFrame/Series index as x-axis If x is omitted but y is specified, x defaults to the index Named indices (df.index.name) are used as axis labels	None

Examples:

Explicit index reference

>>> df = pd.DataFrame({'y': [1, 2, 3]}, index=[10, 20, 30])
>>> ggplot(df, aes(x='index', y='y')) + geom_point()

Auto-populate x from index (same result as above)

>>> ggplot(df, aes(y='y')) + geom_point()

Series input (x=index, y=values automatically)

>>> s = pd.Series([1, 2, 3], index=['a', 'b', 'c'], name='values')
>>> ggplot(s) + geom_point()

Named index becomes axis label

>>> df.index.name = 'time'
>>> ggplot(df, aes(y='y')) + geom_point()  # x-axis labeled 'time'

Explicit x column takes precedence over index

>>> df = pd.DataFrame({'x': [1, 2, 3], 'y': [4, 5, 6]})
>>> ggplot(df, aes(x='x', y='y')) + geom_point()  # uses column 'x'

draw()

Render the plot.

Returns:

Type	Description
	go.Figure: The Plotly figure object.

show()

Show the current plot in the default viewer.

Returns:

Type	Description
	None

save(filepath)

Save the current plot to a file (e.g., HTML, PNG).

Parameters:

Name	Type	Description	Default
filepath	str	The file path where the plot should be saved.	required

Note

HTML files use CDN references for Plotly.js and MathJax, resulting in small file sizes (~8KB) but requiring internet for viewing. MathJax CDN enables LaTeX rendering (e.g., geom_text with parse=True).

aes

Create aesthetic mappings.

ggplotly.aes.aes

Aesthetic mappings for ggplot.

Aesthetic mappings describe how variables in the data are mapped to visual properties (aesthetics) of geoms. This is the fundamental concept in the grammar of graphics.

Parameters:

Name	Type	Description	Default
x	AesValue	Variable for x-axis position.	None
y	AesValue	Variable for y-axis position.	None
z	AesValue	Variable for z-axis position (3D plots).	None
color/colour		Variable for color aesthetic.	required
fill	AesValue	Variable for fill color.	None
size	AesValue	Variable for point/line size.	None
shape	AesValue	Variable for point shape.	None
alpha	AesValue	Variable for transparency.	None
linetype	AesValue	Variable for line type.	None
label	AesValue	Variable for text labels.	None
group	str | None	Variable for grouping.	None
**kwargs	Any	Additional aesthetic mappings.	{}

Examples:

>>> aes(x='mpg', y='hp')
>>> aes(x='mpg', y='hp', color='cyl')
>>> aes(x='x', y=after_stat('density'))
>>> aes(x='x', y=after_stat('count / count.sum()'))

__contains__(key)

Check if aesthetic is mapped.

__getitem__(key)

Get aesthetic mapping by key.

copy()

Create a copy of the aesthetic mapping.

get(key, default=None)

Get an aesthetic mapping value.

items()

Get all aesthetic key-value pairs.

keys()

Get all aesthetic keys.

update(other)

Update mappings from another aes or dict.

values()

Get all aesthetic values.