Facets API Reference

Faceting creates multiple panels (subplots) based on categorical variables, allowing comparison across groups.

Facet Functions

ggplotly.facets.facet_wrap

Bases: Facet

__init__(facet_var, ncol=None, nrow=None, scales='fixed', dir='h', labeller=None, strip_position='top', drop=True, as_table=True)

Initialize a facet_wrap object.

Parameters:

Name	Type	Description	Default
facet_var	str	The column in the dataframe by which to facet the plot.	required
ncol	int	Number of columns to arrange the facets in.	None
nrow	int	Number of rows to arrange the facets in (optional).	None
scales	str	How to handle scales across facets. Options: - 'fixed': All facets share the same scale (default) - 'free': Each facet has its own scale - 'free_x': x-axis is free, y-axis is shared - 'free_y': y-axis is free, x-axis is shared	'fixed'
dir	str	Direction to wrap facets. Options: - 'h': Horizontal (left to right, then down) - default - 'v': Vertical (top to bottom, then right)	'h'
labeller	callable or str	Function to generate facet labels. Options: - None or 'value': Just show the value (default) - 'both': Show "variable: value" - callable: Function that takes (variable, value) and returns label string	None
strip_position	str	Position of facet labels. Options: - 'top': Labels on top (default) - 'bottom': Labels on bottom - 'left': Labels on left - 'right': Labels on right	'top'
drop	bool	If True (default), drop unused factor levels from faceting.	True
as_table	bool	If True (default), arrange facets like a table with highest values at bottom-right. If False, arrange like a plot with highest values at top-right.	True

apply(plot)

Apply facet wrapping to the plot.

Parameters:

Name	Type	Description	Default
plot	ggplot	The ggplot object.	required

Returns:

Name	Type	Description
Figure		A Plotly figure with facets applied.

Raises:

Type	Description
FacetColumnNotFoundError	If the facet variable doesn't exist in the data.

ggplotly.facets.facet_grid

Bases: Facet

__init__(rows, cols, scales='fixed', space='fixed', labeller=None, margins=False, drop=True, switch=None)

Initialize a facet_grid object.

Parameters:

Name	Type	Description	Default
rows	str	The column in the dataframe by which to facet the rows.	required
cols	str	The column in the dataframe by which to facet the columns.	required
scales	str	How to handle scales across facets. Options: - 'fixed': All facets share the same scale (default) - 'free': Each facet has its own scale - 'free_x': x-axis is free, y-axis is shared - 'free_y': y-axis is free, x-axis is shared	'fixed'
space	str	How to allocate space for facets. Options: - 'fixed': All facets have equal size (default) - 'free': Size proportional to data range - 'free_x': Width proportional to x-axis range - 'free_y': Height proportional to y-axis range	'fixed'
labeller	callable or str	Function to generate facet labels. Options: - None or 'value': Just show the value (default) - 'both': Show "variable: value" - callable: Function that takes (variable, value) and returns label string	None
margins	bool or list	If True, add marginal facets showing all data. If a list, specifies which margins to display (e.g., ['rows', 'cols']). Default is False.	False
drop	bool	If True (default), drop unused factor levels from faceting.	True
switch	str	Position to switch strip labels. Options: - None: Default positions (top for cols, right for rows) - 'x': Switch column labels to bottom - 'y': Switch row labels to left - 'both': Switch both	None

apply(plot)

Apply facet grid to the plot.

Parameters:

Name	Type	Description	Default
plot	ggplot	The ggplot object.	required

Returns:

Name	Type	Description
Figure		A Plotly figure with facets applied in a grid.

Raises:

Type	Description
FacetColumnNotFoundError	If row or column variable doesn't exist in the data.

Labeller Functions

ggplotly.facets.label_value(variable, value)

Default labeller - just returns the value as string.

ggplotly.facets.label_both(variable, value)

Labeller that shows both variable name and value.