Stats¶

Point and Distribution Stats¶

stat_pointdensity¶

class plotnine_extra.stat_pointdensity(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Compute density estimation for each point

Usage

stat_pointdensity(
mapping=None, data=None, *, geom=”point”, position=”identity”, na_rm=False, package=”statsmodels”, kde_params=None, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– —————————- x y color `after_stat(‘density’)`{.py}

The bold aesthetics are required.

Options for computed aesthetics

`python "density" # Computed density at a point `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="point") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
package (Literal["statsmodels", "scipy", "sklearn"], default="statsmodels") – Package whose kernel density estimation to use.
kde_params (dict, default=None) – Keyword arguments to pass on to the kde class.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_point: The default geom for this stat.

statsmodels.nonparametric.kde.KDEMultivariate, scipy.stats.gaussian_kde, sklearn.neighbors.KernelDensity

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_AES = {'color': after_stat('density')}¶: Default aesthetics for the stat

DEFAULT_PARAMS = {'geom': 'point', 'kde_params': None, 'na_rm': False, 'package': 'statsmodels', 'position': 'identity'}¶: Required parameters for the stat

CREATES = {'density'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

setup_params(data)[source]¶

Override this to verify and/or adjust parameters

Parameters:: data – Data
Returns:: Parameters used by the stats.
Return type:: out

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_mean¶

class plotnine_extra.stat_mean(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Compute group mean points

Calculates the mean x and y coordinates for each group, producing a single centroid point per group.

Usage

stat_mean(
mapping=None, data=None, *, geom=”point”, position=”identity”, na_rm=False, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="point") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_point: The default geom for this stat.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'geom': 'point', 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_centroid¶

class plotnine_extra.stat_centroid(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Compute the centroid of each group.

Usage

stat_centroid(
mapping=None, data=None, *, geom=”point”, position=”identity”, na_rm=False, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="point") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
**kwargs (Any) – Aesthetics or parameters used by the geom.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'geom': 'point', 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_midpoint¶

class plotnine_extra.stat_midpoint(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Compute the midpoint of each group’s x / y range.

Usage

stat_midpoint(
mapping=None, data=None, *, geom=”point”, position=”identity”, na_rm=False, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="point") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
**kwargs (Any) – Aesthetics or parameters used by the geom.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'geom': 'point', 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_chull¶

class plotnine_extra.stat_chull(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Compute the convex hull of a set of points

Calculates the convex hull for each group and returns the subset of points that form the hull boundary.

{usage}

Parameters:

{common_parameters}
mapping (aes | None)
data (DataLike | None)
kwargs (Any)

See also

plotnine.geom_path: The default geom for this stat.
plotnine.geom_polygon: Alternative geom for filled hulls.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'geom': 'path', 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_stars¶

class plotnine_extra.stat_stars(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Draw star segments from centroid to each point

Computes line segments from the group centroid (mean x, y) to each individual data point, creating a star-shaped pattern.

Usage

stat_stars(
mapping=None, data=None, *, geom=”segment”, position=”identity”, na_rm=False, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y

The bold aesthetics are required.

Options for computed aesthetics

`python "xend" # x-coordinate of segment endpoint "yend" # y-coordinate of segment endpoint `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="segment") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_segment: The default geom for this stat.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'geom': 'segment', 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

CREATES = {'xend', 'yend'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_central_tendency¶

class plotnine_extra.stat_central_tendency(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Add central tendency measure to a density plot

Computes the mean, median, or mode of the data and returns coordinates for a vertical line at that position.

Usage

stat_central_tendency(
mapping=None, data=None, *, geom=”line”, position=”identity”, na_rm=False, type=”mean”, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="line") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
type (str, default="mean") – Type of central tendency measure. One of "mean", "median", or "mode".
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_line: The default geom for this stat.

REQUIRED_AES = {'x'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'geom': 'line', 'na_rm': False, 'position': 'identity', 'type': 'mean'}¶: Required parameters for the stat

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_conf_ellipse¶

class plotnine_extra.stat_conf_ellipse(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Compute confidence ellipses around group barycenters

Draws a confidence ellipse based on the covariance structure of the bivariate data within each group.

Usage

stat_conf_ellipse(
mapping=None, data=None, *, geom=”path”, position=”identity”, na_rm=False, level=0.95, npoint=100, bary=True, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="path") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
level (float, default=0.95) – Confidence level for the ellipse.
npoint (int, default=100) – Number of points used to draw the ellipse.
bary (bool, default=True) – If True, compute the ellipse around the barycenter (mean). If False, compute the ellipse around the data cloud.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_path: The default geom for this stat.
plotnine.geom_polygon: Alternative geom for filled ellipses.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'bary': True, 'geom': 'path', 'level': 0.95, 'na_rm': False, 'npoint': 100, 'position': 'identity'}¶: Required parameters for the stat

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_overlay_normal_density¶

class plotnine_extra.stat_overlay_normal_density(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Overlay a normal density curve on a histogram or density plot

Computes a theoretical normal distribution with the same mean and standard deviation as the data, useful for checking normality assumptions.

Usage

stat_overlay_normal_density(
mapping=None, data=None, *, geom=”line”, position=”identity”, na_rm=False, n=512, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x

The bold aesthetics are required.

Options for computed aesthetics

`python "density" # Normal density at each point `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="line") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
n (int, default=512) – Number of points at which to evaluate the density.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_line: The default geom for this stat.
plotnine.stat_density: For kernel density estimation.

REQUIRED_AES = {'x'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'geom': 'line', 'n': 512, 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

CREATES = {'density'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_theodensity¶

class plotnine_extra.stat_theodensity(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Fit a parametric distribution and return its density curve.

Usage

stat_theodensity(
mapping=None, data=None, *, geom=”line”, position=”identity”, na_rm=False, distri=”norm”, n=256, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="line") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
distri (str, default "norm") – Name of the distribution to fit. Anything in _DIST_MAP.
n (int, default 256) – Number of grid points along the x range.
**kwargs (Any) – Aesthetics or parameters used by the geom.

REQUIRED_AES = {'x'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'distri': 'norm', 'geom': 'line', 'n': 256, 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_difference¶

class plotnine_extra.stat_difference(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Compute the signed-difference ribbon between two y series.

Usage

stat_difference(
mapping=None, data=None, *, geom=”ribbon”, position=”identity”, na_rm=False, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x ymax ymin

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="ribbon") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
**kwargs (Any) – Aesthetics or parameters used by the geom.

Notes

The sign aesthetic in the output frame can be mapped to fill to colour positive and negative differences differently:

ggplot(d, aes("x", ymin="lo", ymax="hi"))
    + stat_difference(aes(fill="after_stat('sign')"))

REQUIRED_AES = {'x', 'ymax', 'ymin'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'geom': 'ribbon', 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

CREATES = {'sign'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

pd.DataFrame

stat_funxy¶

class plotnine_extra.stat_funxy(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Reduce each group’s x and y to scalar values via callables.

Usage

stat_funxy(
mapping=None, data=None, *, geom=”point”, position=”identity”, na_rm=False, funx=<function mean at 0x7f240a49fd80>, funy=<function mean at 0x7f240a49fd80>, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="point") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
funx (callable, default numpy.mean()) – Reduction applied to x.
funy (callable, default numpy.mean()) – Reduction applied to y.
**kwargs (Any) – Aesthetics or parameters used by the geom.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'funx': <function mean>, 'funy': <function mean>, 'geom': 'point', 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_rle¶

class plotnine_extra.stat_rle(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Compute run-length encoded segments of a categorical aes.

Usage

stat_rle(
mapping=None, data=None, *, geom=”rect”, position=”identity”, na_rm=False, align=”center”, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— label x

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="rect") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
align (str, default "center") – Where to anchor the segment. One of "center", "start" or "end".
**kwargs (Any) – Aesthetics or parameters used by the geom.

REQUIRED_AES = {'label', 'x'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'align': 'center', 'geom': 'rect', 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

CREATES = {'end', 'run_id', 'run_length', 'runvalue', 'start', 'xmax', 'xmin'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_panel(data, scales)[source]¶

Calculate the statistics for all the groups

Return the results in a single dataframe.

This is a default function that can be overridden by individual stats

Parameters:

data – data for the computing
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – The parameters for the stat. It includes default values if user did not set a particular parameter.

Return type:

DataFrame

stat_rollingkernel¶

class plotnine_extra.stat_rollingkernel(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Smooth a series with a rolling kernel.

Usage

stat_rollingkernel(
mapping=None, data=None, *, geom=”line”, position=”identity”, na_rm=False, bw=1.0, kernel=”gaussian”, n=100, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————— x y

The bold aesthetics are required.
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="line") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
bw (float, default 1.0) – Kernel bandwidth (in x units).
kernel (str, default "gaussian") – One of "gaussian", "triangular", "epanechnikov" or "uniform".
n (int, default 100) – Number of evaluation points along the x range.
**kwargs (Any) – Aesthetics or parameters used by the geom.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_PARAMS = {'bw': 1.0, 'geom': 'line', 'kernel': 'gaussian', 'n': 100, 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

Model and Test Annotation Stats¶

stat_cor¶

class plotnine_extra.stat_cor(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Add correlation coefficients with p-values to a scatter plot

Computes correlation coefficients (Pearson, Spearman, or Kendall) and formats them as text labels including p-values.

Usage

stat_cor(
mapping=None, data=None, *, geom=”text”, position=”identity”, na_rm=False, method=”pearson”, alternative=”two-sided”, label_x_npc=”left”, label_y_npc=”top”, r_accuracy=0.01, p_accuracy=0.001, label_sep=”, “, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————————– x y label `after_stat(‘label’)`{.py}

The bold aesthetics are required.

Options for computed aesthetics

`python "label" # Formatted correlation label "r" # Correlation coefficient "rr" # R-squared "p" # P-value `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="text") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
method (str, default="pearson") – Correlation method. One of "pearson", "spearman", or "kendall".
alternative (str, default="two-sided") – Alternative hypothesis. One of "two-sided", "greater", or "less".
label_x_npc (float or str, default="left") – Normalized x position for the label. Float in [0, 1] or one of "left", "center", "right".
label_y_npc (float or str, default="top") – Normalized y position for the label. Float in [0, 1] or one of "top", "center", "bottom".
r_accuracy (float, default=0.01) – Decimal accuracy for the correlation coefficient.
p_accuracy (float, default=0.001) – Decimal accuracy for the p-value.
label_sep (str, default=", ") – Separator between the correlation and p-value labels.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_text: The default geom for this stat.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_AES = {'label': after_stat('label')}¶: Default aesthetics for the stat

DEFAULT_PARAMS = {'alternative': 'two-sided', 'geom': 'text', 'label_sep': ', ', 'label_x_npc': 'left', 'label_y_npc': 'top', 'method': 'pearson', 'na_rm': False, 'p_accuracy': 0.001, 'position': 'identity', 'r_accuracy': 0.01}¶: Required parameters for the stat

CREATES = {'label', 'p', 'r', 'rr'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_regline_equation¶

class plotnine_extra.stat_regline_equation(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Add regression line equation and R-squared to a plot

Fits a polynomial regression and formats the equation and goodness-of-fit statistics as a text label.

Usage

stat_regline_equation(
mapping=None, data=None, *, geom=”text”, position=”identity”, na_rm=False, formula=”y ~ x”, label_x_npc=”left”, label_y_npc=”top”, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————————– x y label `after_stat(‘label’)`{.py}

The bold aesthetics are required.

Options for computed aesthetics

`python "label" # Formatted equation label "eq" # Equation string "rr" # R-squared "adj_rr" # Adjusted R-squared "aic" # Akaike information criterion "bic" # Bayesian information criterion `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="text") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
formula (str, default="y ~ x") –
Regression formula. Supported forms:
- "y ~ x": simple linear regression
- "y ~ poly(x, n)": polynomial of degree n
label_x_npc (float or str, default="left") – Normalized x position for the label.
label_y_npc (float or str, default="top") – Normalized y position for the label.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_text: The default geom for this stat.
plotnine.stat_smooth: For the regression line itself.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_AES = {'label': after_stat('label')}¶: Default aesthetics for the stat

DEFAULT_PARAMS = {'formula': 'y ~ x', 'geom': 'text', 'label_x_npc': 'left', 'label_y_npc': 'top', 'na_rm': False, 'position': 'identity'}¶: Required parameters for the stat

CREATES = {'adj_rr', 'aic', 'bic', 'eq', 'label', 'rr'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_group(data, scales)[source]¶

Calculate statistics for the group

All stats should implement this method

Parameters:

data – Data for a group
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – Parameters

Return type:

DataFrame

stat_compare¶

class plotnine_extra.stat_compare(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Add group-mean comparison brackets to a plot.

Usage

stat_compare(
mapping=None, data=None, *, geom=”bracket”, position=”identity”, na_rm=False, nudge=0, start=None, breaks=None, labels=None, cutoff=None, method=None, overall=False, ref_group=None, tip_length=0.02, parametric=False, correction=”none”, panel_indep=False, method_args=None, comparisons=None, step_increase=0.1, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————————– x y label `after_stat(‘label’)`{.py}

The bold aesthetics are required.

Computed variables

`python "p" # raw p-value "q" # adjusted p-value "label" # display label (depends on breaks/labels/cutoff) "method" # test method name "xmin" # bracket left edge "xmax" # bracket right edge "y" # bracket top `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="bracket") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
nudge (float, default 0) – Vertical nudge of the bracket start position, as a fraction of the panel y-range.
start (float, optional) – Bracket start (top) position. Defaults to the maximum of the panel y-range.
breaks (sequence of float, optional) – Cutpoints for converting p-values to significance labels (e.g. [0, 0.001, 0.01, 0.05, 1]).
labels (sequence of str, optional) – Labels matching breaks. Defaults to the "***"/"**"/"*"/"ns" family.
cutoff (float, optional) – Hide labels with adjusted p-values above this value.
method (callable, optional) – Custom test function. Must accept two 1-D arrays (x, y) and return an object with a .pvalue attribute (e.g. a scipy HypothesisResult). When omitted, the test is selected automatically based on parametric and the number of groups.
overall (bool, default False) – If True, compare each group on the axis against the combined remaining groups (each x against “the rest”). Ignored when ref_group or comparisons is set.
ref_group (str or int, optional) – Reference x-axis group; every other group is compared against this one.
tip_length (float, default 0.02) – Bracket tip length as a fraction of the panel y-range.
parametric (bool, default False) – If True, use parametric tests (t-test for 2 groups, one-way ANOVA for more). Otherwise use the non-parametric counterparts (Wilcoxon, Kruskal-Wallis).
correction (str, default "none") – Multiple-testing correction method, one of "none", "bonferroni", "holm", "hochberg", "hommel", "BH"/"fdr", "BY".
panel_indep (bool, default False) – If True, p-value correction is applied within each panel (matching ggpubr); otherwise it is applied at the layer level (across all panels).
method_args (dict, optional) – Additional keyword arguments forwarded to the test function.
comparisons (list of tuple, optional) – Explicit pairs of x-axis groups to compare, e.g. [("compact", "midsize"), ("pickup", "suv")].
step_increase (float, default 0.1) – Vertical spacing between consecutive brackets, as a fraction of the panel y-range.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine_extra.geoms.geom_bracket: default geom.
plotnine_extra.stats.stat_pwc: pairwise comparisons with manual configuration.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_AES = {'label': after_stat('label')}¶: Default aesthetics for the stat

DEFAULT_PARAMS = {'breaks': None, 'comparisons': None, 'correction': 'none', 'cutoff': None, 'geom': 'bracket', 'labels': None, 'method': None, 'method_args': None, 'na_rm': False, 'nudge': 0, 'overall': False, 'panel_indep': False, 'parametric': False, 'position': 'identity', 'ref_group': None, 'start': None, 'step_increase': 0.1, 'tip_length': 0.02}¶: Required parameters for the stat

CREATES = {'label', 'method', 'p', 'q', 'xmax', 'xmin', 'y'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_panel(data, scales)[source]¶

Calculate the statistics for all the groups

Return the results in a single dataframe.

This is a default function that can be overridden by individual stats

Parameters:

data – data for the computing
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – The parameters for the stat. It includes default values if user did not set a particular parameter.

Return type:

DataFrame

compute_layer(data, layout)[source]¶

Calculate statistics for this layers

This is the top-most computation method for the stat. It does not do any computations, but it knows how to verify the data, partition it call the next computation method and merge results.

stats should not override this method.

Parameters:

data – Data points for all objects in a layer.
layout – Panel layout information

Return type:

DataFrame

stat_compare_means¶

class plotnine_extra.stat_compare_means(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Add mean comparison p-values to a plot

Performs statistical tests comparing groups and displays the results as text annotations. Supports t-test, Wilcoxon, ANOVA, and Kruskal-Wallis tests.

{usage}

Parameters:

{common_parameters}
method (str, default="wilcox.test") – Statistical test method. One of "t.test", "wilcox.test", "anova", "kruskal.test".
paired (bool, default=False) – Whether to perform a paired test.
comparisons (list of tuple, default=None) – List of group pairs to compare, e.g. [("A", "B"), ("A", "C")]. If None, performs a global test across all groups.
ref_group (str, default=None) – Reference group for pairwise comparisons. Each group is compared against this reference.
hide_ns (bool, default=False) – If True, hide non-significant results.
label (str, default="p.format") – Label format. One of "p.format", "p.signif", "p.format.signif".
label_x_npc (float or str, default="center") – Normalized x position for global test label.
label_y_npc (float or str, default="top") – Normalized y position for global test label.
p_digits (int, default=3) – Number of digits for p-value formatting.
step_increase (float, default=0.1) – Fraction of y-range to step between comparison brackets.

See also

plotnine.geom_text: The default geom for this stat.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_AES = {'label': after_stat('label'), 'wid': None}¶: Default aesthetics for the stat

DEFAULT_PARAMS = {'comparisons': None, 'geom': 'text', 'hide_ns': False, 'label': 'p.format', 'label_x_npc': 'center', 'label_y_npc': 'top', 'method': 'wilcox.test', 'na_rm': False, 'p_digits': 3, 'paired': False, 'position': 'identity', 'ref_group': None, 'step_increase': 0.1, 'wid': None}¶: Required parameters for the stat

CREATES = {'label', 'method', 'p', 'p_signif'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_panel(data, scales)[source]¶

Calculate the statistics for all the groups

Return the results in a single dataframe.

This is a default function that can be overridden by individual stats

Parameters:

data – data for the computing
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – The parameters for the stat. It includes default values if user did not set a particular parameter.

Return type:

DataFrame

stat_anova_test¶

class plotnine_extra.stat_anova_test(mapping=None, data=None, **kwargs)[source]¶

Bases: _base_stat_test

Add ANOVA test p-values to a plot

Performs one-way ANOVA and displays the result as a text annotation including F-statistic, degrees of freedom, and p-value.

Usage

stat_anova_test(
mapping=None, data=None, *, geom=”text”, position=”identity”, na_rm=False, method=”one_way”, effect_size=”ges”, label_x_npc=”center”, label_y_npc=”top”, p_digits=3, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————————– x y label `after_stat(‘label’)`{.py}

The bold aesthetics are required.

Options for computed aesthetics

`python "label" # Formatted test result label "p" # P-value "p_signif" # Significance symbol "f" # F-statistic "df" # Numerator degrees of freedom "df_residual" # Denominator degrees of freedom "effect_size" # Effect size (eta-squared) "method" # Name of the test `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="text") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
method (str, default="one_way") – ANOVA method. Currently supports "one_way".
effect_size (str, default="ges") – Type of effect size. One of "ges" (generalized eta-squared) or "pes" (partial eta-squared).
label_x_npc (float or str, default="center") – Normalized x position for the label.
label_y_npc (float or str, default="top") – Normalized y position for the label.
p_digits (int, default=3) – Number of digits for p-value formatting.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_text: The default geom for this stat.

DEFAULT_PARAMS = {'effect_size': 'ges', 'geom': 'text', 'label_x_npc': 'center', 'label_y_npc': 'top', 'method': 'one_way', 'na_rm': False, 'p_digits': 3, 'position': 'identity'}¶: Required parameters for the stat

CREATES = {'df', 'df_residual', 'effect_size', 'f', 'label', 'method', 'p', 'p_signif'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

stat_kruskal_test¶

class plotnine_extra.stat_kruskal_test(mapping=None, data=None, **kwargs)[source]¶

Bases: _base_stat_test

Add Kruskal-Wallis test p-values to a plot

Performs a Kruskal-Wallis rank sum test and displays the result as a text annotation. This is a non-parametric alternative to one-way ANOVA.

Usage

stat_kruskal_test(
mapping=None, data=None, *, geom=”text”, position=”identity”, na_rm=False, label_x_npc=”center”, label_y_npc=”top”, p_digits=3, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————————– x y label `after_stat(‘label’)`{.py}

The bold aesthetics are required.

Options for computed aesthetics

`python "label" # Formatted test result label "p" # P-value "p_signif" # Significance symbol "statistic" # Test statistic (H) "df" # Degrees of freedom "method" # Name of the test `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="text") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
label_x_npc (float or str, default="center") – Normalized x position for the label.
label_y_npc (float or str, default="top") – Normalized y position for the label.
p_digits (int, default=3) – Number of digits for p-value formatting.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_text: The default geom for this stat.

DEFAULT_PARAMS = {'geom': 'text', 'label_x_npc': 'center', 'label_y_npc': 'top', 'na_rm': False, 'p_digits': 3, 'position': 'identity'}¶: Required parameters for the stat

CREATES = {'df', 'label', 'method', 'p', 'p_signif', 'statistic'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

stat_welch_anova_test¶

class plotnine_extra.stat_welch_anova_test(mapping=None, data=None, **kwargs)[source]¶

Bases: _base_stat_test

Add Welch’s ANOVA test p-values to a plot

Performs Welch’s one-way ANOVA, which does not assume equal variances across groups, and displays the result as a text annotation.

Usage

stat_welch_anova_test(
mapping=None, data=None, *, geom=”text”, position=”identity”, na_rm=False, label_x_npc=”center”, label_y_npc=”top”, p_digits=3, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————————– x y label `after_stat(‘label’)`{.py}

The bold aesthetics are required.

Options for computed aesthetics

`python "label" # Formatted test result label "p" # P-value "p_signif" # Significance symbol "f" # F-statistic "df1" # Numerator degrees of freedom "df2" # Denominator degrees of freedom "method" # Name of the test `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="text") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
label_x_npc (float or str, default="center") – Normalized x position for the label.
label_y_npc (float or str, default="top") – Normalized y position for the label.
p_digits (int, default=3) – Number of digits for p-value formatting.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_text: The default geom for this stat.

DEFAULT_PARAMS = {'geom': 'text', 'label_x_npc': 'center', 'label_y_npc': 'top', 'na_rm': False, 'p_digits': 3, 'position': 'identity'}¶: Required parameters for the stat

CREATES = {'df1', 'df2', 'f', 'label', 'method', 'p', 'p_signif'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

stat_friedman_test¶

class plotnine_extra.stat_friedman_test(mapping=None, data=None, **kwargs)[source]¶

Bases: _base_stat_test

Add Friedman test p-values to a plot

Performs the Friedman test, a non-parametric test for repeated measures (alternative to repeated-measures ANOVA), and displays the result as a text annotation.

Usage

stat_friedman_test(
mapping=None, data=None, *, geom=”text”, position=”identity”, na_rm=False, wid=None, label_x_npc=”center”, label_y_npc=”top”, p_digits=3, **kwargs

)

Parameters:

mapping (plotnine.aes, default=None) –
Aesthetic mappings created with [aes](plotnine.aes). If specified and `inherit_aes=True`{.py}, it is combined with the default mapping for the plot. You must supply mapping if there is no plot mapping.

Aesthetic Default value

———– ————————– x y label `after_stat(‘label’)`{.py} wid `None`{.py}

The bold aesthetics are required.

Options for computed aesthetics

`python "label" # Formatted test result label "p" # P-value "p_signif" # Significance symbol "statistic" # Test statistic (chi-squared) "df" # Degrees of freedom "method" # Name of the test `
data (DataFrame, default=None) – The data to be displayed in this layer. If `None`{.py}, the data from from the `ggplot()`{.py} call is used. If specified, it overrides the data from the `ggplot()`{.py} call.
geom (str | geom, default="text") – The statistical transformation to use on the data for this layer. If it is a string, it must be the registered and known to Plotnine.
position (str | position, default="identity") – Position adjustment. If it is a string, it must be registered and known to Plotnine.
na_rm (bool, default=False) – If `False`{.py}, removes missing values with a warning. If `True`{.py} silently removes missing values.
wid (str, default=None) – Column name identifying subjects/individuals. Required for reshaping the data into the wide format needed by the Friedman test.
label_x_npc (float or str, default="center") – Normalized x position for the label.
label_y_npc (float or str, default="top") – Normalized y position for the label.
p_digits (int, default=3) – Number of digits for p-value formatting.
**kwargs (Any) – Aesthetics or parameters used by the geom.

See also

plotnine.geom_text: The default geom for this stat.

DEFAULT_PARAMS = {'geom': 'text', 'label_x_npc': 'center', 'label_y_npc': 'top', 'na_rm': False, 'p_digits': 3, 'position': 'identity', 'wid': None}¶: Required parameters for the stat

DEFAULT_AES = {'label': after_stat('label'), 'wid': None}¶: Default aesthetics for the stat

CREATES = {'df', 'label', 'method', 'p', 'p_signif', 'statistic'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_panel(data, scales)[source]¶

Template method for omnibus test stats.

Parameters:: data (pd.DataFrame)
Return type:: pd.DataFrame

stat_pvalue_manual¶

plotnine_extra.stat_pvalue_manual(data, label=None, y_position=None, xmin='group1', xmax='group2', tip_length=0.02, step_increase=0.05, step_group_by=None, hide_ns=False, remove_bracket=False, bracket_nudge_y=0, label_size=8, vjust=-0.5, color='black', x_levels=None, **kwargs)[source]¶

Add manually specified p-values to a plot with brackets.

Parameters:

data (DataFrame) – Data frame containing at minimum columns for group positions and p-values. Expected columns include group1, group2, and p or p.adj.
label (str, optional) – Column name to use for the label, or "p.signif" to auto-convert p-values to significance symbols. If None, uses "p" column formatted.
y_position (str or float, optional) – Column name for y-coordinates of brackets, or a single float value. If None, uses "y.position" or "y_position" column.
xmin (str, default="group1") – Column name for the left x-coordinate of brackets.
xmax (str, default="group2") – Column name for the right x-coordinate of brackets.
tip_length (float, default=0.02) – Length of bracket tips as fraction of y range.
step_increase (float, default=0.05) – Step increase between brackets as fraction of y range.
step_group_by (str, optional) – Column to group comparisons for stacking.
hide_ns (bool, default=False) – If True, hide non-significant results.
remove_bracket (bool, default=False) – If True, show only labels without brackets.
bracket_nudge_y (float, default=0) – Vertical nudge for brackets.
label_size (float, default=8) – Font size for labels.
vjust (float, default=-0.5) – Vertical justification of labels.
color (str, default="black") – Color for brackets and labels.
**kwargs (Any) – Additional aesthetic parameters.
x_levels (list | tuple | None)
**kwargs

Returns:

List of plotnine layers (geom_segment + geom_text) that can be added to a ggplot.

Return type:

list

stat_pwc¶

class plotnine_extra.stat_pwc(mapping=None, data=None, **kwargs)[source]¶

Bases: stat

Add pairwise comparison p-values to a plot

Performs pairwise statistical tests between groups and displays the results as bracket annotations. Supports t-test and Wilcoxon (Mann-Whitney U) tests. The default geom is geom_bracket.

{usage}

Parameters:

{common_parameters}
method (str, default="wilcox.test") – Statistical test method for pairwise comparisons. One of "t.test" or "wilcox.test".
paired (bool, default=False) – Whether to perform a paired test.
ref_group (str or int, default=None) – Reference group for pairwise comparisons. Each group is compared against this reference. If None, all pairwise combinations are tested.
comparisons (list of tuple, default=None) – Explicit list of group pairs to compare, e.g. [("A", "B"), ("A", "C")]. Overrides ref_group when specified.
p_adjust_method (str, default="holm") – Method for adjusting p-values for multiple comparisons. One of "bonferroni", "holm", "hochberg", "hommel", "BH", "BY", "fdr", "none".
label (str, default="p.format") – Label format. One of "p.format", "p.signif", "p.adj.format", "p.adj.signif", "p.format.signif", "p.adj.format.signif".
hide_ns (bool, default=False) – If True, hide non-significant comparisons.
p_digits (int, default=3) – Number of digits for p-value formatting.
step_increase (float, default=0.12) – Fraction of y-range to step between comparison brackets to minimize overlap.
bracket_nudge_y (float, default=0.05) – Vertical offset for brackets as a fraction of the y-range.
tip_length (float, default=0.03) – Length of bracket tips as a fraction of y-range, passed to geom_bracket.
bracket_shorten (float, default=0) – Amount to shorten brackets from each end.
remove_bracket (bool, default=False) – If True, remove brackets and only show labels (uses geom_text instead of geom_bracket).

See also

plotnine_extra.geom_bracket: The default geom for this stat.
plotnine_extra.stat_compare_means: Mean comparison with support for global tests.

REQUIRED_AES = {'x', 'y'}¶: Required aesthetics for the stat

DEFAULT_AES = {'label': after_stat('label'), 'wid': None}¶: Default aesthetics for the stat

DEFAULT_PARAMS = {'bracket_nudge_y': 0.05, 'bracket_shorten': 0, 'comparisons': None, 'geom': 'bracket', 'hide_ns': False, 'label': 'p.format', 'method': 'wilcox.test', 'na_rm': False, 'p_adjust_method': 'holm', 'p_digits': 3, 'paired': False, 'position': 'identity', 'ref_group': None, 'remove_bracket': False, 'step_increase': 0.12, 'tip_length': 0.03, 'wid': None}¶: Required parameters for the stat

CREATES = {'group1', 'group2', 'label', 'method', 'p', 'p_adj', 'p_adj_signif', 'p_signif', 'xmax', 'xmin', 'y'}¶

Stats may modify existing columns or create extra columns.

Any extra columns that may be created by the stat should be specified in this set see: stat_bin

Documentation for the aesthetics. It ie added under the documentation for mapping parameter. Use {aesthetics_table} placeholder to insert a table for all the aesthetics and their default values.

compute_panel(data, scales)[source]¶

Calculate the statistics for all the groups

Return the results in a single dataframe.

This is a default function that can be overridden by individual stats

Parameters:

data – data for the computing
scales –
x (scales.x) and y (scales.y) scale objects. The most likely reason to use scale information is to find out the physical size of a scale. e.g.

`python range_x = scales.x.dimension() `
params – The parameters for the stat. It includes default values if user did not set a particular parameter.

P-value Helpers¶

format_p_value¶

plotnine_extra.format_p_value(p, digits=3, style='default', accuracy=None, leading_zero=True)[source]¶

Format a p-value for display.

Parameters:

p (float) – P-value to format.
digits (int, default 3) – Number of decimal digits (default style only).
style (str, default "default") – Name of the format style. See list_p_format_styles().
accuracy (float, optional) – If provided, p-values smaller than this threshold are rendered as "p < <accuracy>".
leading_zero (bool, default True) – Whether to keep the leading 0..

Return type:

str

create_p_label¶

plotnine_extra.create_p_label(p, cutpoints=None, symbols=None)[source]¶

Convert one or more p-values to significance symbols.

Parameters:

p (float or array-like) – P-values.
cutpoints (sequence of float, optional) – Upper bounds for each significance level. Defaults to (0.0001, 0.001, 0.01, 0.05, 1.0).
symbols (sequence of str, optional) – Symbols matching cutpoints. Defaults to ("****", "***", "**", "*", "ns").

Returns:

Significance label(s).

Return type:

str or list of str

list_p_format_styles¶

plotnine_extra.list_p_format_styles()[source]¶

Return all known p-value format style names.

Return type:: list[str]

get_p_format_style¶

plotnine_extra.get_p_format_style(style='default')[source]¶

Return the formatting callable registered for style.

Parameters:: style (str)

ggadjust_pvalue¶

plotnine_extra.ggadjust_pvalue(plot, p_adjust_method='holm', label=None)[source]¶

Re-adjust p-values displayed on an existing plot.

Walks plot.layers and updates the p_adjust_method parameter of any stat_pwc / stat_compare_means / stat_pvalue_manual layer in place. The plot is then returned for chaining.

Parameters:

plot (ggplot) – The plot to mutate.
p_adjust_method (str, default "holm") – New adjustment method. One of "bonferroni", "holm", "hochberg", "hommel", "BH", "BY", "fdr", "none".
label (str, optional) – New label format (e.g. "p.adj.signif").