prettypyplot

Prettypyplot

This package provides helper functions to easen the usage of matplotlib.

The module is structured into the following submodules:

• pyplot: This submodule contains all methods related to plotting inside a single axes, so basically related to matplotlib.pyplot.

• style: This module provides only method to load and alter the current style.

• subplots: This module provides methods to simplify dealing with matplotlib.pyplot.subplots grids.

• texts: This module provides methods to plot text with the possibility to add a contour.

• tools: This module provides utility methods to.

GrayTones

Bases: namedtuple('GrayTones', 'dark light')

Class for holding light and dark gray tone.

is_number(number, *, dtype=float)

Check if argument can be interpreated as number.

Parameters:

• number ((string, float, int)) –

  Variable to be check if it can be casted to float.

• dtype (dtype, default: float ) –

  Check for different dtypes, so if is float or if it is int.

Returns:

• is_number ( bool ) –

  Return if argument can be casted to float.

Source code in src/prettypyplot/tools.py

def is_number(number, *, dtype=float):
    """Check if argument can be interpreated as number.

    Parameters
    ----------
    number : string, float, int
        Variable to be check if it can be casted to float.
    dtype : dtype, optional
        Check for different dtypes, so if is float or if it is int.

    Returns
    -------
    is_number : bool
        Return if argument can be casted to float.

    """
    try:
        float(number)
    except (ValueError, TypeError):
        return False
    return float(number) == dtype(number)

load_cmaps()

Load and include custom colormaps to matplotlib.

Add sequential colormaps pastel5, pastel6, cbf4, cbf5, cbf8, and ufcd as an corporate design. Except of ufcd all palettes should be 'color-blind-friendly'.

Add continuous colormaps macaw, Turbo. The Copyright of those are given on top of the data.

See

Choosing an cmaps.

Source code in src/prettypyplot/colors.py

def load_cmaps():
    """Load and include custom colormaps to matplotlib.

    Add sequential colormaps `pastel5`, `pastel6`, `cbf4`, `cbf5`, `cbf8`,
    and `ufcd` as an corporate design. Except of `ufcd` all palettes should be
    'color-blind-friendly'.

    Add continuous colormaps macaw, Turbo. The Copyright of those are given on
    top of the data.

    !!! see
        Choosing an [cmaps](../../gallery/cmaps).

    """
    colormaps = (
        _argon(),
        _pastel5(),
        _pastel6(),
        _cbf4(),
        _cbf5(),
        _cbf8(),
        _pastel_autumn(),
        _pastel_rainbow(),
        _pastel_spring(),
        _paula(),
        _summertimes(),
        _tol_bright(),
        _tol_high_contrast(),
        _tol_light(),
        _tol_medium_contrast(),
        _tol_muted(),
        _tol_vibrant(),
        _ufcd(),
        _turbo(),
        _macaw(),
        _bownair(),
    )
    # register own continuous and discrete cmaps
    for colormap in colormaps:
        # add cmap and reverse cmap
        for cmap in (colormap, colormap.reversed()):
            try:
                _get_cmap(cmap.name)
            except ValueError:
                _register_cmap(cmap=cmap)

load_colors()

Load and include custom colors to matplotlib.

Add colors of pastel5 which can be accessed via pplt:blue, pplt:red, pplt:green, pplt:orange, pplt:lightblue, pplt:gray and pplt:lightgray. Further, the current colors will be added pplt:axes, pplt:text, pplt:grid.

See

Choosing an cmaps.

Source code in src/prettypyplot/colors.py

def load_colors():
    """Load and include custom colors to matplotlib.

    Add colors of `pastel5` which can be accessed via `pplt:blue`, `pplt:red`,
    `pplt:green`, `pplt:orange`, `pplt:lightblue`, `pplt:gray` and
    `pplt:lightgray`. Further, the current colors will be added `pplt:axes`,
    `pplt:text`, `pplt:grid`.

    !!! see
        Choosing an [cmaps](../../gallery/cmaps).

    """
    # register own colors
    pplt_colors = {
        'pplt:blue': _pastel5().colors[0],
        'pplt:red': _pastel5().colors[1],
        'pplt:green': _pastel5().colors[2],
        'pplt:orange': _pastel5().colors[3],
        'pplt:lightblue': _pastel5().colors[4],
        'pplt:gray': default_grays.dark,
        'pplt:grey': default_grays.dark,
        'pplt:lightgray': default_grays.light,
        'pplt:lightgrey': default_grays.light,
        'pplt:axes': plt.rcParams['axes.edgecolor'],
        'pplt:text': plt.rcParams['text.color'],
        'pplt:grid': plt.rcParams['grid.color'],
    }
    clr._colors_full_map.update(pplt_colors)  # noqa: WPS437

categorical_cmap(nc, nsc, *, cmap=None, return_colors=False)

Generate categorical colors of given cmap.

Exract from a predefined colormap colors and generate for each the desired number of shades.

Parameters:

• nc (int) –

  Number of colors

• nsc (int) –

  Number of shades per colors

• cmap (`matplotlib.colors.Colormap` or str, default: None ) –

  Matplotlib colormap to take colors from. The default is the active color cycle.

• return_colors (bool, default: False ) –

  Return an array of rgb colors. Each color together with its shades are in an own row.

Returns:

• scolors ( `matplotlib.colors.Colormap` or np.ndarray ) –

  Return discrete colormap. If return_colors, a 2d representation will be returned instead.

Source code in src/prettypyplot/colors.py

def categorical_cmap(nc, nsc, *, cmap=None, return_colors=False):
    """Generate categorical colors of given cmap.

    Exract from a predefined colormap colors and generate for each the desired
    number of shades.

    Parameters
    ----------
    nc : int
        Number of colors
    nsc : int
        Number of shades per colors
    cmap : `matplotlib.colors.Colormap` or str, optional
        Matplotlib colormap to take colors from. The default is the active
        color cycle.
    return_colors : bool, optional
        Return an array of rgb colors. Each color together with its shades are
        in an own row.

    Returns
    -------
    scolors : `matplotlib.colors.Colormap` or np.ndarray
        Return discrete colormap. If return_colors, a 2d representation will
        be returned instead.

    """
    # check correct data type
    _is_number_in_range(
        nc, name='nc', dtype=int, low=1, high=np.iinfo(int).max,
    )
    _is_number_in_range(
        nsc, name='nsc', dtype=int, low=1, high=np.iinfo(int).max,
    )
    nc, nsc = int(nc), int(nsc)

    # get cmap
    if cmap is not None:
        cmap = plt.get_cmap(cmap)
    else:
        cmap = clr.ListedColormap(
            plt.rcParams['axes.prop_cycle'].by_key()['color'],
        )
    if nc > cmap.N:
        raise ValueError('Too many categories for colormap.')

    # extract colors from cmap
    if isinstance(cmap, clr.LinearSegmentedColormap):
        colors = cmap(np.linspace(0, 1, nc))
    elif isinstance(cmap, clr.ListedColormap):
        colors = cmap(np.arange(nc, dtype=int))

    # get shades of colors
    scolors = np.empty((nc, nsc, 3))
    for idx, color in enumerate(colors):
        scolors[idx] = categorical_color(nsc, color)

    if return_colors:
        return scolors
    return clr.ListedColormap(np.concatenate(scolors))

categorical_color(nsc, color, *, return_hex=False)

Generate categorical shades of given colors.

Generate for each provided color the number of specified shades. The shaded colors are interpolated linearly in HSV colorspace. This function is based on following post: https://stackoverflow.com/a/47232942

Parameters:

• nsc (int) –

  Number of shades per color.

• color (RGB color or matplotlib predefined color) –

  Color used for generating shades.

• return_hex (bool, default: False ) –

  Return colors in hex format instead of rgb.

Returns:

• colors_rgb ( list of RGB colors ) –

  A list containing shaded colors. Where the list is sorted from the original color at the beginning to the most shaded one at the end. The default color encoding is rgb and hex if specified.

Source code in src/prettypyplot/colors.py

def categorical_color(nsc, color, *, return_hex=False):
    """Generate categorical shades of given colors.

    Generate for each provided color the number of specified shades. The shaded
    colors are interpolated linearly in HSV colorspace. This function is based
    on following post: https://stackoverflow.com/a/47232942

    Parameters
    ----------
    nsc : int
        Number of shades per color.
    color : RGB color or matplotlib predefined color
        Color used for generating shades.
    return_hex : bool, optional
        Return colors in hex format instead of rgb.

    Returns
    -------
    colors_rgb : list of RGB colors
        A list containing shaded colors. Where the list is sorted from the
        original color at the beginning to the most shaded one at the end.
        The default color encoding is rgb and hex if specified.

    """
    # check correct data type
    color = clr.to_rgb(color)
    _is_number_in_range(
        nsc, name='nsc', dtype=int, low=1, high=np.iinfo(int).max,
    )
    nsc = int(nsc)

    # genrate shades of colors
    color_hsv = clr.rgb_to_hsv(color)
    colors_hsv = np.tile(color_hsv, nsc).reshape(nsc, 3)
    colors_hsv[:, 1] = np.linspace(color_hsv[1], 1 / 4, nsc)
    colors_hsv[:, 2] = np.linspace(color_hsv[2], 1, nsc)
    colors_rgb = clr.hsv_to_rgb(colors_hsv)

    # check if color is greyscale value, need to fix arbitrary hue value of 0
    if is_greyshade(color):
        colors_rgb[:, 0] = colors_rgb[:, 1]

    if return_hex:
        return [clr.to_hex(color) for color in colors_rgb]
    return colors_rgb

text_color(bgcolor, colors=('#000000', '#ffffff'))

Select textcolor with maximal contrast on background.

All parameters needs to be colors accepted by matplotlib, see matplotlib.colors. The formulas are taken from W3C WCAG 2.1 (Web Content Accessibility Guidelines).

Parameters:

• bgcolor (matplotlib color) –

  Background color to which the contrast is maximized.

• colors (list of matplotlib colors, default: ('#000000', '#ffffff') ) –

  Selection of textcolors to choose from.

Returns:

• color ( matplotlib color ) –

  Color of colors which has the highest contrast on the given bgcolor.

Source code in src/prettypyplot/colors.py

def text_color(bgcolor, colors=('#000000', '#ffffff')):
    """Select textcolor with maximal contrast on background.

    All parameters needs to be colors accepted by matplotlib, see
    [matplotlib.colors](https://matplotlib.org/api/colors_api.html).
    The formulas are taken from W3C [WCAG 2.1](https://www.w3.org/TR/WCAG21)
    (Web Content Accessibility Guidelines).

    Parameters
    ----------
    bgcolor : matplotlib color
        Background color to which the contrast is maximized.
    colors : list of matplotlib colors, optional
        Selection of textcolors to choose from.

    Returns
    -------
    color : matplotlib color
        Color of colors which has the highest contrast on the given bgcolor.

    """
    # check input by casting to matplotlib colors
    bgcolor = clr.to_rgb(bgcolor)
    colors_rgb = [clr.to_rgb(color) for color in colors]

    # calculate the (luminances)
    bgL = _relative_luminance(bgcolor)
    Ls = [_relative_luminance(color) for color in colors_rgb]

    # calculate contrast between bgcolor and all colors
    contrast = [_contrast(bgL, Luminance) for Luminance in Ls]

    # return color corresponding to greatest contrast
    idx = contrast.index(max(contrast))
    return colors[idx]

is_greyshade(color)

Check if color is a greyscale value including bw.

Source code in src/prettypyplot/colors.py

def is_greyshade(color):
    """Check if color is a greyscale value including bw."""
    # check if color is greyscale value, need to fix arbitrary hue value
    color = clr.to_rgb(color)
    if np.min(color) == np.max(color):
        return True
    return False

update_style(interactive=None, colors=None, cmap=None, ncs=None, figsize=None, figratio=None, mode=None, style=None, ipython=None, true_black=None, latex=None, sf=None)

Update alternative matplotlib style.

This function updates specified parameters of use_style without changing other.

Parameters:

• interactive (bool, default: None ) –

  Set interactive mode.

• colors (string, default: None ) –

  Set the default color cycler from continuous or discrete maps. Use any of matplotlibs defaults or specified in the colors submodule.

• cmap (string, default: None ) –

  Set the default colormap.

• ncs (int, default: None ) –

  Number of colors if continuous cmap is selected.

• figsize (int or int tuple, default: None ) –

  Give size of default figure in inches, either as tuple (x, y) or a single float for the x-axis. The y-axis will be determined by figratio.

• figratio (str or float, default: None ) –

  Set ratio of figsize x:y to 1:1/'option', where 'option' is one of ['sqrt(2)', 'golden', 'sqrt(3)'] or any number. Golden stands for the golden ratio (1.618). This option is ignored if figsize is used with tuple.

• mode (str, default: None ) –

  One of the following modes: 'default': use matplotlib defaults 'beamer': extra large fontsize 'print': default sizes 'poster': for Din A0 posters

• style (str, default: None ) –

  One of the following styles: 'default': enables grid and upper and right spines 'minimal': removes all unneeded lines 'none': no changes to style

• ipython (bool, default: None ) –

  Deactivate high-res in jpg/png for compatibility with IPyhton, e.g. jupyter notebook/lab.

• true_black (bool, default: None ) –

  If true black will be used for labels and co., else a dark grey.

• latex (bool, default: None ) –

  If true LaTeX font will be used.

• sf (bool, default: None ) –

  Use sans-serif font for text and latex math environment.

Source code in src/prettypyplot/style.py

def update_style(
    interactive=None,
    colors=None,
    cmap=None,
    ncs=None,
    figsize=None,
    figratio=None,
    mode=None,
    style=None,
    ipython=None,
    true_black=None,
    latex=None,
    sf=None,
):
    """Update alternative matplotlib style.

    This function updates specified parameters of `use_style` without changing
    other.

    Parameters
    ----------
    interactive : bool, optional
        Set interactive mode.
    colors : string, optional
        Set the default color cycler from continuous or discrete maps. Use any
        of matplotlibs defaults or specified in the colors submodule.
    cmap : string, optional
        Set the default colormap.
    ncs : int, optional
        Number of colors if continuous cmap is selected.
    figsize : int or int tuple, optional
        Give size of default figure in inches, either as tuple (x, y) or a
        single float for the x-axis. The y-axis will be determined by figratio.
    figratio : str or float, optional
        Set ratio of figsize x:y to 1:1/'option', where 'option' is one
        of `['sqrt(2)', 'golden', 'sqrt(3)']` or any number. Golden stands for
        the golden ratio (1.618). This option is ignored if figsize is used
        with tuple.
    mode : str, optional
        One of the following modes:
        `'default'`: use matplotlib defaults
        `'beamer'`: extra large fontsize
        `'print'`: default sizes
        `'poster'`: for Din A0 posters
    style : str, optional
        One of the following styles:
        `'default'`: enables grid and upper and right spines
        `'minimal'`: removes all unneeded lines
        `'none'`: no changes to style
    ipython : bool, optional
        Deactivate high-res in jpg/png for compatibility with IPyhton, e.g.
        jupyter notebook/lab.
    true_black : bool, optional
        If true black will be used for labels and co., else a dark grey.
    latex : bool, optional
        If true LaTeX font will be used.
    sf : bool, optional
        Use sans-serif font for text and latex math environment.

    """
    # set selected mode and style
    if style is not None:
        if isinstance(style, Style):
            pass
        elif isinstance(style, str) and style.upper() in Style.keys_list():
            style = Style[style.upper()]
        else:
            raise ValueError(
                'Style "{st}" is not supported, use one of {sts}.'.format(
                    st=style,
                    sts=Style.keys_list(),
                ),
            )
        _pplt.STYLE = style

    if mode is not None:
        if isinstance(mode, Mode):
            pass
        elif isinstance(mode, str) and mode.upper() in Mode.keys_list():
            mode = Mode[mode.upper()]
        else:
            raise ValueError(
                'Mode "{mode}" is not supported, use one of {modes}.'.format(
                    mode=mode,
                    modes=Mode.keys_list(),
                ),
            )

        _pplt.MODE = mode

    # set style variables in dictionary
    for key, val in (
        ('interactive', interactive),
        ('colors', colors),
        ('cmap', cmap),
        ('ncs', ncs),
        ('figsize', figsize),
        ('figratio', figratio),
        ('ipython', ipython),
        ('true_black', true_black),
        ('latex', latex),
        ('sf', sf),
    ):
        if val is not None:
            _pplt.STYLE_DICT[key] = val

    if _pplt.STYLE is Style.NONE:
        _reset_style()
    else:
        # load static rcParams
        _apply_style('stylelib/default.mplstyle')
        if _pplt.STYLE is Style.MINIMAL:
            _apply_style('stylelib/minimal.mplstyle')

        # set color cycle and cmap
        _set_rc_colors(
            colors=colors, cmap=cmap, ncs=ncs, true_black=true_black,
        )

        # set figsize
        if figsize is not None:
            _set_rc_figsize(figratio=figratio, figsize=figsize)

        # increase dpi if not in iypthon
        _set_rc_dpi(ipython)

        # set interactive mode
        _set_ineractive_mode(interactive=interactive)

        # setup LaTeX font if latex is available
        # plt.style.use can not be used.
        if latex and shutil.which('latex'):
            _apply_style('stylelib/latex.mplstyle')

        if sf:
            _set_rc_sansserif()

    if mode is not None:
        # change widths and fontsize depending on MODE
        _set_rc_widths(mode)

use_style(interactive=None, colors='pastel5', cmap='macaw', ncs=10, figsize=(3), figratio='golden', mode=_pplt.MODE, style=_pplt.STYLE, ipython=False, true_black=False, latex=True, sf=False)

Define alternative matplotlib style.

This function restores first the matplolib default values and finally changes depicted values to achieve a more appealing appearence. It additionally loads pplts colormaps and colors in matplolib.

See update_style for parameters.

Source code in src/prettypyplot/style.py

@copy_doc_params(update_style)
def use_style(
    interactive=None,
    colors='pastel5',
    cmap='macaw',
    ncs=10,
    figsize=(3,),
    figratio='golden',
    mode=_pplt.MODE,
    style=_pplt.STYLE,
    ipython=False,
    true_black=False,
    latex=True,
    sf=False,
):
    """Define alternative matplotlib style.

    This function restores first the matplolib default values and finally
    changes depicted values to achieve a more appealing appearence.
    It additionally loads pplts colormaps and colors in matplolib.

    See [update_style][prettypyplot.update_style] for parameters.

    """
    # restore matplotlib defaults
    _reset_style()

    # register own continuous and discrete cmaps
    pclr.load_cmaps()

    # update style
    update_style(
        interactive=interactive,
        colors=colors,
        cmap=cmap,
        ncs=ncs,
        figsize=figsize,
        figratio=figratio,
        mode=mode,
        style=style,
        ipython=ipython,
        true_black=true_black,
        latex=latex,
        sf=sf,
    )

    # register used colors
    pclr.load_colors()

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

def add_contour(txt, contourwidth, contourcolor='w'):
    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)

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. 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) –

  Matplotlib axes to plot in.

• kwargs –

  Text properties of matplotlib.pyplot.figtext

Source code in src/prettypyplot/texts.py

def 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, 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.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

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

def 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, 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

hide_empty_axes(axs=None)

Hide empty axes.

Loop over all axes and hide empty ones.

Parameters:

• axs (mpl.axes.Axes or list of, default: None ) –

  Specify matplotlib.axes.Axes to check for empty state. Default use all of current figure.

Source code in src/prettypyplot/subplots.py

def hide_empty_axes(axs=None):
    """Hide empty axes.

    Loop over all axes and hide empty ones.

    Parameters
    ----------
    axs : mpl.axes.Axes or list of
        Specify [matplotlib.axes.Axes][] to check for empty state. Default use
        all of current figure.

    """
    # check for single axes
    axs = tools.get_axes(axs)

    # loop over all axes and hide empty ones
    for ax in axs:
        if _is_empty_axes(ax):
            ax.axis('off')

    # in case of shared axes, activate outer tick labels
    _activate_outer_ticks(axs)

label_outer(axs=None)

Only show outer labels and tick labels.

This checks for outest visible axes only. Works only with single Gridspec.

Parameters:

• axs (mpl.axes.AxesSubplot or list of, default: None ) –

  Specify matplotlib.axes.Axes to check for labeling only outer. Default use all of current figure.

Source code in src/prettypyplot/subplots.py

def label_outer(axs=None):
    """Only show outer labels and tick labels.

    This checks for outest visible axes only. Works only with single Gridspec.

    Parameters
    ----------
    axs : mpl.axes.AxesSubplot or list of
        Specify [matplotlib.axes.Axes][] to check for labeling only outer.
        Default use all of current figure.

    """
    # check for single axes
    if axs is not None:
        axs = tools.get_axes(axs)
        if not all((_is_subplot_axes(arg) for arg in axs)):
            raise TypeError(
                'axs needs to be of type matplotlib.axes.AxesSuplot.',
            )
    else:
        axs = [ax for ax in plt.gcf().get_axes() if _is_subplot_axes(ax)]

    for ax in axs:
        ss = ax.get_subplotspec()
        if hasattr(ss, 'is_last_row'):  # pragma: no cover # noqa: WPS421
            # for mpl >= 3.4
            lastrow = ss.is_last_row()
            firstcol = ss.is_first_col()
        elif hasattr(ax, 'is_last_row'):  # pragma: no cover # noqa: WPS421
            lastrow = ax.is_last_row()
            firstcol = ax.is_first_col()
        else:
            raise TypeError(f'{ax!r} is not a valid axes.')

        # check if axes below, left is hidden
        left_empty, bottom_empty = _is_outer_hidden(axs, ax)
        _label_outer(ax, lastrow or bottom_empty, firstcol or left_empty)

subplot_labels(*, fig=None, xlabel=None, ylabel=None)

Add global labels for subplots.

This method adds shared x- and y-labels for a grid of subplots. These can be created by, e.g. fig, axs = plt.subplots(...).

Parameters:

• fig (matplotlib figure, default: None ) –

  If None the current figure will be used instead.

• xlabel (str, default: None ) –

  String of x label.

• ylabel (str, default: None ) –

  String of y label.

Source code in src/prettypyplot/subplots.py

def subplot_labels(*, fig=None, xlabel=None, ylabel=None):
    """Add global labels for subplots.

    This method adds shared x- and y-labels for a grid of subplots. These can
    be created by, e.g. `fig, axs = plt.subplots(...)`.

    Parameters
    ----------
    fig : matplotlib figure, optional
        If `None` the current figure will be used instead.
    xlabel : str, optional
        String of x label.
    ylabel : str, optional
        String of y label.

    """
    # if no label passed, nothing to do
    if xlabel is None and ylabel is None:
        return

    # get active axes to restore it later on
    ca = plt.gca()

    if fig is None:
        fig = plt.gcf()

    _subplot_labels(fig, xlabel, ylabel)

    # reset current axes
    plt.sca(ca)