Skip to content

Stripe

daspi.plotlib.plotter.Stripe(label, position, width, orientation='horizontal', color=COLOR.STRIPE, alpha=None, lower_limit=0.0, upper_limit=1.0, zorder=0.7, show_position=False, decimals=None)

Bases: ABC

Abstract base class for drawing a stripe (line or area) on Matplotlib Axes.

A stripe is a visual element used to highlight a specific region or value on a plot, such as a threshold line or a band of interest. This class provides a flexible interface for defining the appearance and behavior of such elements.

PARAMETER DESCRIPTION
label

The label of the stripe as it appears in the legend.

TYPE: str

position

The central position of the stripe on the x- or y-axis.

TYPE: float

width

The width of the stripe.

TYPE: float

orientation

The orientation of the stripe. Defaults to 'horizontal'.

TYPE: (horizontal, vertical) DEFAULT: 'horizontal'

color

The color of the stripe, specified as a named color or hex code. Defaults to COLOR.STRIPE.

TYPE: str DEFAULT: STRIPE

alpha

The transparency level of the stripe, between 0 (fully transparent) and 1 (fully opaque). Defaults to None.

TYPE: float or None DEFAULT: None

lower_limit

The lower bound of the stripe relative to the plotting area, expressed as a proportion between 0 and 1. Defaults to 0.0.

TYPE: float DEFAULT: 0.0

upper_limit

The upper bound of the stripe relative to the plotting area, expressed as a proportion between 0 and 1. Defaults to 1.0.

TYPE: float DEFAULT: 1.0

zorder

The drawing order of the stripe relative to other plot elements. Higher values are drawn on top. Defaults to 0.7.

TYPE: float DEFAULT: 0.7

show_position

Whether to include the position value in the legend label. Defaults to False.

TYPE: bool DEFAULT: False

decimals

Number of decimal places to use when formatting the position value in the label. If None, the number is determined automatically based on the magnitude of the position. Defaults to None.

TYPE: int or None DEFAULT: None

Notes

This is an abstract base class. Subclasses must implement the __call__ method to draw the stripe on a given Axes, and the handle property to return the legend handle.

The label property automatically wraps the label in dollar signs ($) so that it is interpreted as a LaTeX-style math expression in the legend. If show_position is True, the position value is appended to the label.

linestyle instance-attribute

The linestyle of the stripe.

show_position = show_position instance-attribute

Whether position value of the stripe should be displayed the label.

position = position instance-attribute

The position of the stripe on the x- or y-axis.

orientation = orientation instance-attribute

The orientation of the stripe.

width = width instance-attribute

The width of the stripe.

color = color instance-attribute

The color of the stripe as string or hex value.

alpha = alpha instance-attribute

Value used for blending the color.

lower_limit = lower_limit instance-attribute

The lower limit (start) of the stripe relative to the plotting area. Should be between 0 and 1.

upper_limit = upper_limit instance-attribute

The upper limit (end) of the stripe relative to the plotting area. Should be between 0 and 1.

zorder = zorder instance-attribute

The zorder of the stripe.

decimals property writable

Get number of decimals used to format position value in label. If None is given for setting decimals, it is determined based on the size of the position value see determine_decimals method.

label property writable

Get the label of the stripe. The label is always returned with a leading and trailing $ sign so that it is interpreted as a mathematical expression in the legend.

identity property

Get the identity of the strip. Needed so that it only appears once in the legend. The identity is composed of the label and the color (read-only).

handle abstractmethod property

Get the handle of the stripe used for legend.

determine_decimals(value) staticmethod

Determine the number of decimal places to format values for e.g. legend labels. The number of decimal places depends on the size of the provided value.

daspi.plotlib.plotter.StripeSpan(label, lower_position=None, upper_position=None, position=None, width=None, orientation='horizontal', color=COLOR.STRIPE, alpha=COLOR.CI_ALPHA, lower_limit=0.0, upper_limit=1.0, zorder=0.7, border_linewidth=0, **kwds)

Bases: Stripe

Concrete implementation of Stripe for drawing wide spans (bands) on Matplotlib Axes.

This class is used to highlight a continuous region between two positions on a plot, such as confidence intervals, tolerance bands, or shaded areas of interest. It supports both direct specification of the lower and upper bounds, or a central position with width.

PARAMETER DESCRIPTION
label

The label of the stripe as it appears in the legend.

TYPE: str

lower_position

The lower bound of the stripe on the x- or y-axis. Must be provided if position and width are not given. Defaults to None.

TYPE: float or None DEFAULT: None

upper_position

The upper bound of the stripe on the x- or y-axis. Must be provided if position and width are not given. Defaults to None.

TYPE: float or None DEFAULT: None

position

The central position of the stripe. Must be provided if lower_position and upper_position are not given. Defaults to None.

TYPE: float or None DEFAULT: None

width

The width of the stripe. Must be provided if lower_position and upper_position are not given. Defaults to None.

TYPE: float or None DEFAULT: None

orientation

The orientation of the stripe. Defaults to 'horizontal'.

TYPE: (horizontal, vertical) DEFAULT: 'horizontal'

color

The fill color of the stripe. Can be a named color or hex code. Defaults to COLOR.STRIPE.

TYPE: str DEFAULT: STRIPE

alpha

Transparency level of the stripe, between 0 (transparent) and 1 (opaque). Defaults to COLOR.CI_ALPHA.

TYPE: float or None DEFAULT: CI_ALPHA

lower_limit

The lower limit of the stripe relative to the plotting area (0 to 1). Defaults to 0.0.

TYPE: float DEFAULT: 0.0

upper_limit

The upper limit of the stripe relative to the plotting area (0 to 1). Defaults to 1.0.

TYPE: float DEFAULT: 1.0

zorder

Drawing order of the stripe. Higher values are drawn above lower ones. Defaults to 0.7.

TYPE: float DEFAULT: 0.7

border_linewidth

Width of the border line. Can also be set via lw or linewidth in **kwds. Defaults to 0.

TYPE: float DEFAULT: 0

**kwds

Additional keyword arguments for appearance customization. Priority order: - Line width: lw, linewidth, then border_linewidth - Color: c, then color - Style: ls, then linestyle

DEFAULT: {}

Examples:

Apply to an existing Axes object:

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
from daspi import Line, StripeSpan, SpecLimits, COLOR

fig, ax = plt.subplots()
df = pd.DataFrame(dict(x = np.random.weibull(a=1.5, size=100)))
line = Line(source=df, target='x', ax=ax)
line(marker='o')
spec_limits=SpecLimits(lower=0, upper=2.5)
ok_area = StripeSpan(
    label=r'OK',
    lower_position=spec_limits.lower,
    upper_position=spec_limits.upper,
    color=COLOR.GOOD,
    orientation='horizontal')
ok_area(ax=ax)

ax.legend([ok_area.handle], [ok_area.label])

Apply using the plot method of a DaSPi Chart object:

import numpy as np
import daspi as dsp
import pandas as pd

df = pd.DataFrame(dict(x = np.random.weibull(a=1.5, size=100)))
spec_limits=dsp.SpecLimits(lower=0, upper=2.5)
ok_area = StripeSpan(
    label=r'OK',
    lower_position=spec_limits.lower,
    upper_position=spec_limits.upper,
    color=COLOR.GOOD,
    orientation='horizontal')
chart = dsp.SingleChart(
        source=df,
        target='x',
    ).plot(
        dsp.Line,
        kw_call={'marker': 'o'}
    ).stripes(
        [ok_area]
    ).label() # neded to add the legend
Notes

You must specify either: - lower_position and upper_position, or - position and width

but not both. The class will compute the missing values accordingly.

lower_position instance-attribute

Target position of the lower border of the stripe.

upper_position instance-attribute

Target position of the upper border of the stripe.

border_linewidth = kwds.get('lw', kwds.get('linewidth', border_linewidth)) instance-attribute

Width of the border line. Could also be set during initialisation via lw or linewidth.

handle property

Get the handle of the stripe used for legend.

daspi.plotlib.plotter.StripeLine(label, position, width=LINE.WIDTH, orientation='horizontal', color=COLOR.STRIPE, alpha=None, lower_limit=0.0, upper_limit=1.0, zorder=0.7, show_position=False, decimals=None, linestyle=LINE.DASHED, **kwds)

Bases: Stripe

Concrete implementation of Stripe for drawing straight lines on Matplotlib Axes.

This class is used to draw horizontal or vertical lines that highlight specific positions on a plot, such as thresholds, limits, or reference values. It supports customization of line style, color, transparency, and legend labeling.

PARAMETER DESCRIPTION
label

The label of the stripe as it appears in the legend.

TYPE: str

position

The position of the stripe on the x- or y-axis.

TYPE: float

width

The line width of the stripe. Can be overridden by lw or linewidth in **kwds. Defaults to LINE.WIDTH.

TYPE: float DEFAULT: WIDTH

orientation

The orientation of the stripe. Defaults to 'horizontal'.

TYPE: (horizontal, vertical) DEFAULT: 'horizontal'

color

The color of the stripe, specified as a named color or hex code. Can be overridden by c in **kwds. Defaults to COLOR.STRIPE.

TYPE: str DEFAULT: STRIPE

alpha

Transparency level of the stripe, between 0 (transparent) and 1 (opaque). Defaults to None.

TYPE: float or None DEFAULT: None

lower_limit

The lower bound of the stripe relative to the plotting area (0 to 1). Defaults to 0.0.

TYPE: float DEFAULT: 0.0

upper_limit

The upper bound of the stripe relative to the plotting area (0 to 1). Defaults to 1.0.

TYPE: float DEFAULT: 1.0

zorder

Drawing order of the stripe. Higher values are drawn above lower ones. Defaults to 0.7.

TYPE: float DEFAULT: 0.7

show_position

Whether to include the position value in the legend label. Defaults to False.

TYPE: bool DEFAULT: False

decimals

Number of decimal places to use when formatting the position in the label. If None, the number is determined automatically based on the value.

TYPE: int or None DEFAULT: None

linestyle

The line style of the stripe (e.g., solid, dashed). Can be overridden by ls in **kwds. Defaults to LINE.DASHED.

TYPE: LineStyle DEFAULT: DASHED

**kwds

Additional keyword arguments for fine-tuning appearance. Priority order: - Line width: lw, linewidth, then width - Color: c, then color - Style: ls, then linestyle

DEFAULT: {}

Examples:

Apply to an existing Axes object:

import numpy as np
import pandas as pd
import matplotlib.pyplot as plt
from daspi import GaussianKDE, StripeLine, LocationDispersionEstimator

fig, ax = plt.subplots()
df = pd.DataFrame(dict(x = np.random.weibull(a=1.5, size=1000)))
kde = GaussianKDE(source=df, target='x', target_on_y=False)
kde()
x = LocationDispersionEstimator(df.x)
mean = StripeLine(
    label=r'ar x = 'f'{x.mean:.2f}',
    position=x.mean,
    color="#145a5aa0",
    upper_limit=0.9,
    orientation='vertical')
mean(ax=ax)
median = StripeLine(
    label=r'        ilde x = 'f'{x.median:.2f}',
    position=x.median,
    color="#5a47149f",
    upper_limit=0.9,
    orientation='vertical')
median(ax=ax)
ax.set(ylim=(0, None))
ax.legend([mean.handle, median.handle], [mean.label, median.label])

Apply using the plot method of a DaSPi Chart object:

import numpy as np
import daspi as dsp
import pandas as pd

df = pd.DataFrame(dict(x = np.random.weibull(a=1.5, size=1000)))
x = LocationDispersionEstimator(df.x)
mean = StripeLine(
    label=r'ar x = 'f'{x.mean:.2f}',
    position=x.mean,
    color="#145a5aa0",
    upper_limit=0.9,
    orientation='vertical')
median = StripeLine(
    label=r'        ilde x = 'f'{x.median:.2f}',
    position=x.median,
    color="#5a47149f",
    upper_limit=0.9,
    orientation='vertical')
chart = dsp.SingleChart(
        source=df,
        target='x',
        target_on_y=False
    ).plot(dsp.GaussianKDE,
    ).stripes([mean, median]
    ).label() # neded to add the legend

The last example only serves to demonstrate how custom lines can be added. The median and mean are already predefined and can be easily plotted by setting the appropriate flag. With the following example, we get a similar result:

import numpy as np
import daspi as dsp
import pandas as pd

df = pd.DataFrame(dict(x = np.random.weibull(a=1.5, size=1000)))
chart = dsp.SingleChart(
        source=df,
        target='x',
        target_on_y=False
    ).plot(dsp.GaussianKDE,
    ).stripes(
        mean=True,
        median=True,
    ).label() # neded to add the legend
Notes

This class is part of the DaSPi visualization toolkit and is designed to integrate seamlessly with other chart components. It ensures that each stripe is only drawn once per Axes instance.

linestyle = kwds.get('ls', linestyle) instance-attribute

The linestyle of the stripe.

handle property

Get the handle of the stripe used for legend.