smooth_labels#

class smooth_labels(variables: List[str] = None)#

Configure annotations for geom_smooth() layers.

This class extends layer_labels() and provides additional options for displaying statistics produced by the smooth stat, such as \(R^2\), adjusted \(R^2\), and the fitted model equation.

It allows placing a multi-line annotation near the smooth curve and mixing custom text, computed variables (e.g. ..r2..), and a generated equation block. If created without any additional configuration the annotation displays a single line with \(R^2\).

Notes

  • Supported smooth-stat variables and markers that can be used in line() templates:

    • ..r2.. - \(R^2\).

    • ..adjr2.. - adjusted \(R^2\).

    • ..aic.. - Akaike Information Criterion (AIC) of the fitted model.

    • ..bic.. - Bayesian Information Criterion (BIC) of the fitted model.

    • ..f.. - F-statistic for the overall model significance test.

    • ..df1.. - numerator degrees of freedom for the F-test.

    • ..df2.. - denominator degrees of freedom for the F-test.

    • ..p.. - p-value for the overall model F-test.

    • ..method.. - smoothing method label (for example, lm or loess).

    • ..n.. - number of observations used in model fitting.

    • ..cilevel.. - confidence level used for the \(R^2\) confidence interval.

    • ..cilow.. - lower bound of the confidence interval for \(R^2\).

    • ..cihigh.. - upper bound of the confidence interval for \(R^2\).

    • ~eq - equation block marker. When a line equals '~eq', an equation for the fitted model is rendered (can be configured with eq()).

  • smooth_labels inherits all features of layer_labels. Methods such as format(), line(), size(), and inherit_color() work exactly the same.

By default, annotation text color is automatically selected for good readability.

Use theme(label_text=element_text(...)) to customize the appearance of annotation text. See also element_text().

Alternatively, the inherit_color() method can be used to make annotation text use the geometry’s color aesthetic, overriding both the automatically selected text color and any color specified via theme(label_text=element_text(...)).

Examples

1import numpy as np
2from lets_plot import *
3LetsPlot.setup_html()
4np.random.seed(42)
5n = 100
6x = np.linspace(-2, 2, n)
7y = x**2 + np.random.normal(size=n)
8ggplot({'x': x, 'y': y}, aes('x', 'y')) + geom_point() + \
9    geom_smooth(deg=2, labels=smooth_labels())
__init__(variables: List[str] = None)#

Initialize self.

Parameters:
variableslist of str

Variable names to place in the annotation with default formatting.

eq(lhs=None, rhs=None, format=None, threshold=None) → smooth_labels#

Configure the equation block for the smooth annotation.

The equation block is typically inserted into the label using a line containing the special marker '~eq'. When present, the backend will render a fitted model equation (and may also include related statistics depending on configuration).

Parameters:
lhsstr, optional

Left-hand side label for the equation (default 'y').

rhsstr, optional

Right-hand side variable representation (default 'x').

formatstr or list of str, optional

Formatting specification(s) for displaying numeric coefficients in the equation. Each item can be either a number format (e.g. '.1f'). If a single format is provided, it is applied to all coefficients.

thresholdfloat, optional

A threshold value that can be used to control presentation of small coefficients (e.g. hide or simplify terms below the threshold).

Returns:
smooth_labels

Annotations specification.

Notes

For more info see Formatting.

Examples

 1import numpy as np
 2from lets_plot import *
 3LetsPlot.setup_html()
 4np.random.seed(42)
 5x = np.linspace(-2, 2, 50)
 6y = x**2 + np.random.normal(size=len(x))
 7ggplot({'x': x, 'y': y}, aes('x', 'y')) + geom_point() + \
 8    geom_smooth(deg=2, labels=smooth_labels()
 9        .line('~eq')
10        .eq(lhs='f(x)', rhs='x', format='.2f', threshold=0.1))
label_x(position=None) → smooth_labels#

Set horizontal positioning of the smooth annotation.

Parameters:
positionstr or float or list, optional

Horizontal position for the annotation label.

  • String values set an anchor position: 'left', 'center', 'right'.

  • A numeric value sets an exact x-coordinate in plot data units.

  • A list can be used to control the position of each group separately. Each list item can be either a string anchor or a numeric coordinate.

Returns:
smooth_labels

Annotations specification.

Notes

By default, the annotation is placed in the top-left corner. When multiple groups are present, annotations are arranged in a vertical stack by default; passing a list to label_x() and/or label_y() allows positioning each group’s annotation independently.

Examples

1from lets_plot import *
2LetsPlot.setup_html()
3ggplot({'x': [0, 1, 2], 'y': [0, 1, 4]}, aes('x', 'y')) + geom_point() + \
4    geom_smooth(deg=2, labels=smooth_labels().line('~eq').label_x('center'))
label_y(position=None) → smooth_labels#

Set vertical positioning of the smooth annotation.

Parameters:
positionstr or float or list, optional

Vertical position for the annotation label.

  • String values set an anchor position: 'top', 'center', 'bottom'.

  • A numeric value sets an exact y-coordinate in plot data units.

  • A list can be used to control the position of each group separately. Each list item can be either a string anchor or a numeric coordinate.

Returns:
smooth_labels

Annotations specification.

Notes

By default, the annotation is placed in the top-left corner. When multiple groups are present, annotations are arranged in a vertical stack by default; passing a list to label_x() and/or label_y() allows positioning each group’s annotation independently.

Examples

1from lets_plot import *
2LetsPlot.setup_html()
3ggplot({'x': [0, 1, 2], 'y': [0, 1, 4]}, aes('x', 'y')) + geom_point() + \
4    geom_smooth(deg=2, labels=smooth_labels().line('~eq').label_y('center'))
as_dict()#

Return a dictionary of all properties of the object.

In addition to the fields provided by layer_labels.as_dict, this method includes: - kind='smooth_stat_summary_annotation' - options (may contain label_x, label_y, and eq)

Returns:
dict

Dictionary of properties.

format(field=None, format=None)#

Define the format for displaying the value. This format will be applied to the corresponding value specified in the ‘line’ template.

Parameters:
fieldstr

Name of an aesthetic or variable that would be formatted. The field name starts with a ‘^’ prefix for aesthetics, the variable name starts with a ‘@’ prefix or without any prefix.

formatstr

Formatting specification. The format contains a number format (‘1.f’), a string template (‘{.1f}’) or a date/time format (‘%d.%m.%y’). The numeric format for non-numeric value will be ignored. If you need to include a brace character in the literal text, it can be escaped by doubling: {{ and }}.

Returns:
smooth_labels

Annotations specification.

Notes

For more info see Formatting.

Examples

 1import numpy as np
 2from lets_plot import *
 3LetsPlot.setup_html()
 4np.random.seed(42)
 5x = np.linspace(-2, 2, 50)
 6y = x**2 + np.random.normal(size=len(x))
 7ggplot({'x': x, 'y': y}, aes('x', 'y')) + \
 8    geom_point() + \
 9    geom_smooth(deg=2, labels=smooth_labels()\
10                              .line(r'\(R\^2=\)@..r2..')\
11                              .format('..r2..', '.3f')\
12                              .label_x('center'))
line(value)#

Add a line of text to the multiline label annotation.

This method configures one line of text that will be displayed in a multiline label. Multiple calls to this method can be chained to build up a complete multiline annotation.

Parameters:
valuestr

The text content for this line of the annotation. Can include variable and aesthetic references.

Returns:
smooth_labels

Annotations specification.

Notes

Variables and aesthetics can be accessed via special syntax:

  • ^color for aesthetics,

  • @x for variable,

  • @{x + 1} for variable with spaces in the name,

  • @{x^2 + 1} for variable with spaces and ‘^’ symbol in the name,

  • @x^2 for variable with ‘^’ symbol in its name.

Special characters can be escaped:

  • ‘x\^2’ -> “x^2” (escape ^ with backslash)

  • ‘{{x}}’ -> “{x}” (escape braces by doubling)

Examples

1from lets_plot import *
2LetsPlot.setup_html()
3ggplot({'x': [0, 1, 2], 'y': [0, 1, 4]}, aes('x', 'y')) + geom_point() + \
4    geom_smooth(deg=2, labels=smooth_labels()\
5                              .line(r'\(R\^2=\)@..r2..')\
6                              .line('~eq'))
size(value)#

Set the text size for the annotation.

Parameters:
valuefloat

The text size value for the annotation.

Returns:
smooth_labels

Annotations specification.

Examples

1from lets_plot import *
2LetsPlot.setup_html()
3ggplot({'x': [0, 1, 2], 'y': [0, 1, 4]}, aes('x', 'y')) + geom_point() + \
4    geom_smooth(deg=2, labels=smooth_labels().line('~eq').size(25))
inherit_color()#

Use the layer’s color for the annotation text.

When enabled, the annotation text will inherit the color from the layer it’s associated with, rather than using a default or explicitly set color.

Returns:
smooth_labels

Annotations specification.

Examples

 1import numpy as np
 2from lets_plot import *
 3LetsPlot.setup_html()
 4np.random.seed(42)
 5x = np.linspace(-2, 2, 50)
 6y = x**2 + np.random.normal(size=len(x))
 7g = np.random.choice(['A', 'B'], size=len(x))
 8data = {'x': x, 'y': y, 'g': g}
 9ggplot(data, aes('x', 'y', color='g')) + \
10    geom_point() + \
11    geom_smooth(deg=2, labels=smooth_labels()
12        .line('~eq')
13        .eq(format='.2f')
14        .inherit_color())