Skip to content

texts

Helper functions for plotting text.

text(x, y, s, *, contour=None, ax=None, **kwargs)

Generate text object at (x,y).

Wrapper around pyplot.text. The default alignment is changed to centered.

Parameters:

  • x (scalars) –

    The position to place the text. By default, this is in data coordinates. The coordinate system can be changed using the transform parameter.

  • y (scalars) –

    The position to place the text. By default, this is in data coordinates. The coordinate system can be changed using the transform parameter.

  • s (str) –

    The text.

  • contour (bool or tuple(scalar, color), default: None ) –

    Add a contour to the text. Either use a boolean for default values, or give a tuple with linewidth and linecolor.

  • ax (matplotlib axes, default: None ) –

    Matplotlib axes to plot in.

  • kwargs –

    Text properties of matplotlib.pyplot.text

Source code in src/prettypyplot/texts.py 
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
def text(
    x: float,
    y: float,
    s: str,
    *,
    contour: bool | tuple[float, ColorType] | None = None,
    ax: Axes | None = None,
    **kwargs,
) -> Text:
    """Generate text object at (x,y).

    Wrapper around pyplot.text. The default alignment is changed to centered.

    Parameters
    ----------
    x, y : scalars
        The position to place the text. By default, this is in data
        coordinates. The coordinate system can be changed using the
        *transform* parameter.
    s : str
        The text.
    contour : bool or tuple(scalar, color)
        Add a contour to the text. Either use a boolean for default values,
        or give a tuple with linewidth and linecolor.
    ax : matplotlib axes
        Matplotlib axes to plot in.
    kwargs
        Text properties of [matplotlib.pyplot.text][]

    """
    # parse axes
    ax = tools.gca(ax)

    # change default alignment
    if 'va' not in kwargs and 'verticalalignment' not in kwargs:
        kwargs['va'] = 'center'
    if 'ha' not in kwargs and 'horizontalalignment' not in kwargs:
        kwargs['ha'] = 'center'

    # plot text
    txt = ax.text(x=x, y=y, s=s, **kwargs)

    # generate contour
    if contour is not None:
        contour_kwargs = _parse_contour(contour)
        if contour_kwargs is not None:
            add_contour(txt, **contour_kwargs)

    return txt

figtext(x, y, s, *, contour=None, **kwargs)

Generate text object at figure position (x,y).

Wrapper around pyplot.figtext. The default alignment is changed to centered.

Parameters:

  • x (scalars) –

    The position to place the text in figure coordinates, so (0, 0) is the bottom left and (1, 1) the top right of the figure.

  • y (scalars) –

    The position to place the text in figure coordinates, so (0, 0) is the bottom left and (1, 1) the top right of the figure.

  • s (str) –

    The text.

  • contour (bool or tuple(scalar, color), default: None ) –

    Add a contour to the text. Either use a boolean for default values, or give a tuple with linewidth and linecolor.

  • kwargs –

    Text properties of matplotlib.pyplot.figtext

Source code in src/prettypyplot/texts.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
def figtext(
    x: float,
    y: float,
    s: str,
    *,
    contour: bool | tuple[float, ColorType] | None = None,
    **kwargs,
) -> Text:
    """Generate text object at figure position (x,y).

    Wrapper around pyplot.figtext. The default alignment is changed to
    centered.

    Parameters
    ----------
    x, y : scalars
        The position to place the text in figure coordinates, so (0, 0) is
        the bottom left and (1, 1) the top right of the figure.
    s : str
        The text.
    contour : bool or tuple(scalar, color)
        Add a contour to the text. Either use a boolean for default values,
        or give a tuple with linewidth and linecolor.
    kwargs
        Text properties of [matplotlib.pyplot.figtext][]

    """
    # change default alignment
    if 'va' not in kwargs and 'verticalalignment' not in kwargs:
        kwargs['va'] = 'center'
    if 'ha' not in kwargs and 'horizontalalignment' not in kwargs:
        kwargs['ha'] = 'center'

    # plot text
    txt = plt.figtext(x=x, y=y, s=s, **kwargs)

    # generate contour
    if contour is not None:
        contour_kwargs = _parse_contour(contour)
        if contour_kwargs is not None:
            add_contour(txt, **contour_kwargs)

    return txt

add_contour(txt, contourwidth, contourcolor='w')

Draw contour around txt.

Parameters:

  • txt (mpl Text) –

    Instance of matplotlib.text.Text. Can be obtained by, e.g., txt = plt.text() or txt = plt.figtext().

  • contourwidth (scalar) –

    Width of contour.

  • contourcolor (RGB color or matplotlib predefined color, default: 'w' ) –

    Color of contour, default is white.

Source code in src/prettypyplot/texts.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
def add_contour(
    txt: Text,
    contourwidth: float,
    contourcolor: ColorType = 'w',
) -> None:
    r"""Draw contour around txt.

    Parameters
    ----------
    txt : mpl Text
        Instance of [matplotlib.text.Text][]. Can be obtained by, e.g.,
        `txt = plt.text()` or `txt = plt.figtext()`.
    contourwidth : scalar
        Width of contour.
    contourcolor : RGB color or matplotlib predefined color, optional
        Color of contour, default is white.

    """
    # check if is text object
    if not isinstance(txt, mpl.text.Text):
        raise TypeError(
            'txt needs to be "matplotlib.text.Text", but ' + 'is {t}'.format(t=txt),
        )
    # check if number
    if not tools.is_number(contourwidth):
        raise TypeError(
            'contourwidth={w} needs to be a number.'.format(w=contourwidth),
        )

    # check if color
    if not clr.is_color_like(contourcolor):
        raise TypeError(
            'contourcolor={c} can not be '.format(c=contourcolor)
            + 'interpreted as color.',
        )

    path_args = [
        path_effects.withStroke(
            linewidth=contourwidth,
            foreground=contourcolor,
        )
    ]
    txt.set_path_effects(path_args)