outset

Top-level package for outset.

Modules

`mark`	Markers for marquee annotations.
`patched`	External functions patched or extended for outset compatibility.
`stub`	Create margin annotations for data outside axes viewport.
`tweak`	Functors to tweak callout leader layout.
`util`	Utility functions.

Functions

`draw_marquee`(frame_xlim, frame_ylim[, ax, ...])	Mark a rectangular region on a matplotlib axes object, framing it with a zoom-effect callout.
`inset_outsets`(outset_grid[, insets, ...])	Rearrange OutsetGrid figure to superimpose outset axes over source axes.
`marqueeplot`(data, *, x, y[, hue, hue_order, ...])	Plot marquee annotations to contain subsets of data from a pandas DataFrame.

Classes

OutsetGrid

Facilitates co-display of zoomed-in axis regions transplanted across a subplot grid.

draw_marquee(frame_xlim: ~typing.Tuple[float, float], frame_ylim: ~typing.Tuple[float, float], ax: ~matplotlib.axes._axes.Axes | None = None, *, color: str | None = 'blue', clip_on: bool = False, despine: bool = True, frame_edge_kws: ~typing.Dict = frozendict.frozendict({}), frame_face_kws: ~typing.Dict = frozendict.frozendict({}), frame_inner_pad: float | ~typing.Tuple[float, float] = 0.0, frame_outer_pad: float | ~typing.Tuple[float, float] = 0.1, label: str | None = None, leader_edge_kws: ~typing.Dict = frozendict.frozendict({}), leader_face_kws: ~typing.Dict = frozendict.frozendict({}), leader_stretch: float = 0.2, leader_stretch_unit: ~typing.Literal['axes', 'figure', 'inches', 'inchesfrom'] = 'inches', leader_tweak: ~typing.Callable = <function <lambda>>, mark_glyph: ~typing.Callable | None = <function mark_magnifying_glass>, mark_glyph_kws: ~typing.Dict = frozendict.frozendict({}), mark_retract: float = 0.1, zorder: float = 0) → Axes[source]

Mark a rectangular region on a matplotlib axes object, framing it with a zoom-effect callout.

Consists of (1) a rectangular frame (2) a callout leader, and (3) a marked glyph. The rectangular frame consists of an outer of border and an underlaid solid color fill. The leader is a gradient fill clipped to angle to a point up and to to the right of the framed region. The marked glyph (e.g., a numeral, an asterisk, etc.) is drawn at the vertex point of the leader.

The callout is capped by a customizable glyph, default as a magnifying glass.

Parameters:

frame_xlim (Tuple[float, float]) – X-limits (xmin, xmax) of the area to be marked as outset.
frame_ylim (Tuple[float, float]) – Y-limits (ymin, ymax) of the area to be marked as outset.
ax (matplotlib.axes.Axes, optional) – Axes object to draw the outset on. Defaults to plt.gca().
color (str, optional) – Color for the frame’s edge and zoom indication lines.
clip_on (bool, default False) – If True, drawing elements are clipped to the axes bounding box.
despine (bool, default True) – If True, removes top and right spines from the plot.
frame_edge_kws (Dict, default {}) –
Customization arguments for the frame’s edge.

Standard matplotlib styling is supported (linewidth, linestyle, etc.).
frame_face_kws (Dict, default {}) –
Customization arguments for the frame’s face.

Standard matplotlib styling is supported (facecolor, alpha, etc.).
frame_inner_pad (Union[float, Tuple[float, float]], default 0.0) – Padding from data extent to frame boundary, calculated relative to data extent (float) or in absolute units (tuple).
frame_outer_pad (Union[float, Tuple[float, float]], default 0.1) – Padding from frame boundary to axis viewport, calculated relative to data extent (float) or in absolute units (tuple).
label (str, optional) – Label used for legend creation.
leader_edge_kws (Dict, default {}) –
Customization arguments for the leader’s edge.

Standard matplotlib styling is supported (linewidth, linestyle, etc.).
leader_face_kws (Dict, default {}) –
Customization arguments for the leader’s face.

Standard matplotlib styling is supported (facecolor, alpha, etc.).
leader_stretch (float, default 0.1) – Size of callout leader in leader_stretch_unit.
leader_stretch_unit (Literal['axes', 'figure', 'inches', 'inchesfrom'], default 'axes') –
How should callout leader placement be determined?

If ‘axes’ or ‘figure’, stretch is specified as a fraction of the axes or figure size, respectively. If ‘inches’, stretch is specified in inches. If ‘inchesfrom’, stretch is minimum necessary to place the marker leader_stretch inches from the lower left corner of the frame.
leader_tweak (Callable, default identity) – Callable to modify the callout leader vertices before drawing.
mark_glyph (Callable, optional) –
A callable to draw a glyph at the outer vertex of the callout leader.

If None, no glyph is drawn.
mark_glyph_kws (Dict, default frozendict.frozendict()) –
Arguments for the mark_glyph callable.

Standard matplotlib styling is supported (markersize, color, etc.).
mark_retract (float, default 0.1) – Fraction to pull back glyph from the outer vertex of the callout.
zorder (float, default 0) – Z-order for layering plot elements.

Returns:

Axes with the outset and annotations added.

Return type:

matplotlib.axes.Axes

Notes

Delegates to _auxlib.draw_callout_.draw_callout and _auslib.draw_callout_.draw_frame for drawing.

See also

outset.marqueeplot: Axes-level tidy data interface for creating marquee annotations.
outset.OutsetGrid: Figure-level interface for creating plots with marquee annotations.

inset_outsets(outset_grid: OutsetGrid, insets: Literal['NE', 'NW', 'SE', 'SW'] | Sequence[Tuple[float, float, float, float]] = 'NE', *, equalize_aspect: bool = True, strip_axes: bool = False, strip_labels: bool = True, strip_spines: bool = False, strip_ticks: bool = True, strip_titles: bool = True) → None[source]

Rearrange OutsetGrid figure to superimpose outset axes over source axes.

Parameters:

outset_grid (OutsetGrid) – OutsetGrid to transform.
insets (Union[Literal["NE", "NW", "SE", "SW"], Sequence[Tuple[float,) –
float –
Where to place outset plots over source plot.

If “NE”, “NW”, “SE”, or “SW”, the outset plots will be inset in the specified corner of the grid. Alternately, inset positioning can be specified directly by providing a sequence of tuples (x0, y0, width, height) for the position of each plot in fractional coordinates of sourceplot.
float –
Where to place outset plots over source plot.

If “NE”, “NW”, “SE”, or “SW”, the outset plots will be inset in the specified corner of the grid. Alternately, inset positioning can be specified directly by providing a sequence of tuples (x0, y0, width, height) for the position of each plot in fractional coordinates of sourceplot.
float]]] –
Where to place outset plots over source plot.

If “NE”, “NW”, “SE”, or “SW”, the outset plots will be inset in the specified corner of the grid. Alternately, inset positioning can be specified directly by providing a sequence of tuples (x0, y0, width, height) for the position of each plot in fractional coordinates of sourceplot.
"NW" (deefault) –
Where to place outset plots over source plot.

If “NE”, “NW”, “SE”, or “SW”, the outset plots will be inset in the specified corner of the grid. Alternately, inset positioning can be specified directly by providing a sequence of tuples (x0, y0, width, height) for the position of each plot in fractional coordinates of sourceplot.
equalize_aspect (bool, default True) – Should the aspect ratio of the inset plots be equalized?
strip_label (bool, default True) – Should x and y labels be stripped from inset plots.
strip_spines (bool, default False) – Should removes the spines of the inset plots.
strip_ticks (bool, default True) – If True, removes the ticks from the inset plots.
strip_titles (bool, default True) – If True, removes the title from the inset plots.

Return type:

None

See also

outset.util.layout_corner_insets: Underlying engine implementing corner inset layout when “NE”, “NW”, “SE”, or “SW” is passed to inset_outsets. The function layout_corner_insets can be called directly to provide the insets kwarg to tweak corner inset layouts.

marqueeplot(data: ~pandas.core.frame.DataFrame, *, x: str, y: str, hue: str | None = None, hue_order: ~typing.Sequence[str] | None = None, outset: str | None = None, outset_order: ~typing.Sequence[str] | None = None, ax: ~matplotlib.axes._axes.Axes | None = None, color: str | None = None, frame_inner_pad: float | ~typing.Tuple[float, float] = 0.1, frame_outer_pad: float | ~typing.Tuple[float, float] = 0.1, frame_outer_pad_unit: ~typing.Literal['axes', 'figure', 'inches'] = 'axes', leader_tweak: ~typing.Callable | ~typing.Type = <function <lambda>>, mark_glyph: ~typing.Callable | ~typing.Type | None = <class 'outset.mark._MarkNumericalBadges.MarkNumericalBadges'>, palette: ~typing.Sequence | None = None, preserve_aspect: bool | None = False, tight_axlim: bool = False, **kwargs) → Axes[source]

Plot marquee annotations to contain subsets of data from a pandas DataFrame.

Provides a seaborn-like axis-level interface for draw_marquee. Details on marquee annotation structure and configuration can be found in that function’s docstring.

Parameters:

data (pd.DataFrame) – DataFrame containing the data to be marquee-annotated.
x (str) – Column name in data for x-coordinate values of data positions.
y (str) – Column name in data for y-coordinate values of data positions.
hue (str, optional) –
Column name in data for grouping data by color.

If provided, colors are chosen according to palette.
hue_order (Sequence[str], optional) – Order for plotting the categorical levels of hue.
outset (str, optional) – Column name in data for producing different-colored annotated subsets.
outset_order (Sequence[str], optional) – Order for plotting the categorical levels of outset.
ax (mpl_axes.Axes, optional) – Matplotlib Axes object to draw the plot on.
color (str, optional) – Color for all elements in the plot, overriding the palette.
frame_inner_pad (Union[float, Tuple[float, float]], default 0.1) – Padding from data range to rectangular boundary.
frame_outer_pad (Union[float, Tuple[float, float]], default 0.1) – Padding from frame boundary to axis viewport.
frame_outer_pad_unit (Literal["axes", "figure", "inches"], default "axes") –
How should outer padding be specified?

If ‘axes’ or ‘figure’, padding is specified as a fraction of the axes or figure size, respectively. If ‘inches’, padding is specified in inches.
leader_tweak (Callable, default identity) – Callable or functor type to modify the callout leader vertices before drawing.
mark_glyph (Union[Callable, Type, None], optional) – Callable or functor type to draw a glyph at the end of the callout.
palette (Sequence, optional) – Color palette for plotting elements.
preserve_aspect (bool, default False) – If True, finalizing by applying initial axes aspect. If None, restore initial axes aspect unless axes are unset.
tight_axlim (bool, default False) – Whether to shrink axes limits to fit data range.
**kwargs (dict) –
Keyword arguments to adjust marquee sizing and styling.

See outset.draw_marquee for available options.

Returns:

The Matplotlib axes containing the plot with annotated regions.

Return type:

matplotlib.axes.Axes

See also

outset.OutsetGrid: Figure-level interface for creating plots with marquee annotations.
outset.draw_marquee: Low-level function for drawing marquee annotations.

class OutsetGrid[source]

Facilitates co-display of zoomed-in axis regions transplanted across a subplot grid.

Corresponding regions in the original (“source”) plot and the zoomed-in, “outset” regions are marked with corresponding “marquee” annotations. The OutsetGrid may be configured to include the source plot on the first subplot axis, or to only display outset regions on subplot axes.

Marquee annotation creation must be dispatched manually through marqueeplot, marqueeplot_outset, and/or marqueeplot_source. This mechanism allows for end-user control over plot sequencing (i.e., layering order) and for adjustment of axis sizing prior to marquee rendering. (Marquee layout dimensions are sensitive to axis rescaling.)

Inherits from seaborn’s FacetGrid, so FacetGrad API components are available, see <https://seaborn.pydata.org/generated/seaborn.FacetGrid.html>.

source_axes

The axes object for the source plot, if present.

Type:: Optional[mpl_axes.Axes]

outset_axes

The axes objects for the outset plots.

Type:: Sequence[mpl_axes.Axes]

See also

outset.draw_marquee: Low-level function for drawing marquee annotations.
outset.marqueeplot: Axes-level tidy data interface for creating marquee annotations.

add_legend(*args, **kwargs) → None[source]

Draw a legend, maybe placing it outside axes and resizing the figure.

Parameters:

legend_data (dict) – Dictionary mapping label names (or two-element tuples where the second element is a label name) to matplotlib artist handles. The default reads from self._legend_data.
title (string) – Title for the legend. The default reads from self._hue_var.
label_order (list of labels) – The order that the legend entries should appear in. The default reads from self.hue_names.
adjust_subtitles (bool) – If True, modify entries with invisible artists to left-align the labels and set the font size to that of a title.
kwargs (key, value pairings) – Other keyword arguments are passed to the underlying legend methods on the Figure or Axes object.

Returns:

self – Returns self for easy chaining.

Return type:

Grid instance

tight_layout() → None[source]: Call fig.tight_layout within rect that exclude the legend.

_finalize_grid(axlabels: Sequence[str] | None = None) → None[source]: Finalize the annotations and layout.

_is_inset() → bool[source]: Are outset axes inset over source axes?

__init__(data: DataFrame | Sequence[Tuple[float, float, float, float]] | NamedFrames | int, *, x: str | None = None, y: str | None = None, col: str | bool | None = None, col_order: Sequence[str] | None = None, col_wrap: int | None = None, hue: str | bool | None = None, hue_order: Sequence[str] | None = None, color: str | None = None, include_sourceplot: bool = True, marqueeplot_kws: Dict = frozendict.frozendict({}), marqueeplot_outset_kws: Dict = frozendict.frozendict({}), marqueeplot_source_kws: Dict = frozendict.frozendict({}), palette: Sequence | None = None, zorder: float = 0.0, **kwargs) → None[source]

Create an OutsetGrid with specified configuration.

The arguments data, x, y, col, hue, and outset follow seaborn-like tidy data API convention. Note that the same value may be specified for more than one of col, hue, and `outset. Marquee annotations are created to contain each subset of x, y values with identical col, hue, and outset values.

Marquee frame coordinates may also be specified directly as a sequence of four-element tuples as “extents” (x0, y0, x1, y1) or “boundary points” ((x0, y0), (x1, y1)). In this case, each frame will get its own hue and outset plot. For more elaborate manually-specified frame layouts, prepare a DataFrame with columns for x, y, hue, and col with two rows per frame (i.e., one row per boundary point) and pass the frame_inner_pad=0 as a marqueeplot kwarg.

Marquee annotation creation must be dispatched manually after initialization through marqueeplot, marqueeplot_outset, and/or marqueeplot_source.

Parameters:

data (pd.DataFrame or Sequence of Tuple[float, float, float, float] or) –
int (outset.util.NamedFrames or) –
A DataFrame containing the data for plotting, or as a sequence of “extents” (x0, y0, x1, y1) or “boundary points” ((x0, y0), (x1, y1)) specifying the bounds of outset frames.

If NamedFrames, underlying data should map frame names to frame coordinates. If an int n is provided, n outset frames with extents (0, 0, 1, 1) will be created.
x (Optional[str], default None) –
Column name to be used for x-axis values.

If data specifies outset frames directly, this kwarg is not required. If provided in this case, it will be used as an axis label.
y (Optional[str], default None) –
Column name to be used for y-axis values.

If data specifies outset frames directly, this kwarg is not required. If provided in this case, it will be used as an axis label.
col (Union[str, bool, None], default None) –
Column name for categorical variable to facet across subaxes.

If None or True, set to match hue if provided. If False, no faceting is performed.

If data specifies outset frames directly, this kwarg is not required. If provided in this case, it will be used to title subplots label.
col_order (Optional[Sequence[str]], default None) – The order to arrange the columns in the grid.
col_wrap (Optional[int], default None) – Number of columns where axes grid should wrap to a new row.
hue (Optional[str], default None) –
Column name for categorical variable to determine rendered color of data’s rendered marquee annotations.

Will also facet across subaxes if col is not set False.

If data specifies outset frames directly, this kwarg is not required. If provided in this case, it will be used to title legend created by .add_legend(), if any.
hue_order (Optional[Sequence[str]], default None) –
The to assign palette colors to hue categorical values.

May contain all or a subset of data[hue] values.
color (Optional[str], default None) – Color for all outset annotations. Overrides the palette.
include_sourceplot (bool, default True) – Whether to include the original source plot in the grid.
marqueeplot_kws (Dict, default frozendict()) –
Keyword arguments to adjust marquee placement and styling over all plots.

See outset.marqueeplot for available options.
marqueeplot_outset_kws (Dict, default frozendict()) –
Keyword arguments to adjust marquee placement and styling over outset plots.

See outset.marqueeplot for available options.
marqueeplot_source_kws (Dict, default frozendict()) –
Keyword arguments to adjust marquee placement and styling over source plot, if present.

See outset.marqueeplot for available options.
palette (Optional[Sequence], default None) – Color palette for the outset hue sequence.
zorder (float, default 0.0) – The z-order for plotting elements.
**kwargs (dict) –
Additional keyword arguments forward to seaborn’s FacetGrid.

See <https://seaborn.pydata.org/generated/seaborn.FacetGrid.html> for details.

source_axes: Axes | None

outset_axes: Sequence[Axes]

equalize_aspect() → OutsetGrid[source]

Adjust axes {x,y}lims to ensure an equal xlim-to-ylim ratio across all axes.

Returns:: Returns self.
Return type:: OutsetGrid

marqueeplot(equalize_aspect: bool = True, preserve_aspect: bool = False) → OutsetGrid[source]

Dispatch marquee annotation rendering for all subplots — outset as well as source, if included.

Parameters:

equalize_aspect (bool, optional, default: True) – If True, adjusts axes limits to enforce equal ylim height to xlim width ratio.
preserve_aspect (bool, optional, default: False) – If True, restore initial aspect ratio after plotting..

Returns:

Returns self.

Return type:

OutsetGrid

marqueeplot_outset(*, equalize_aspect: bool = True, preserve_aspect: bool = False) → OutsetGrid[source]

Dispatch marquee annotation rendering for outset plots only

Parameters:

equalize_aspect (bool, optional, default: True) – If True, adjusts axes limits to enforce equal ylim height to xlim width ratio.
preserve_aspect (bool, optional, default: False) – If True, restore initial aspect ratio after plotting..

Returns:

Returns self.

Return type:

OutsetGrid

marqueeplot_source(*, equalize_aspect: bool = True, preserve_aspect: bool = False) → OutsetGrid[source]

Dispatch marquee annotation rendering for the source plot only, if included.

Parameters:

equalize_aspect (bool, optional, default: True) – If True, adjusts axes limits to enforce equal ylim height to xlim width ratio.
preserve_aspect (bool, optional, default: False) – If True, restore initial aspect ratio after plotting..

Returns:

Returns self.

Return type:

OutsetGrid

map() → None[source]: Placeholder, raises NotImplementedError.

map_outset() → None[source]: Placeholder, raises NotImplementedError.

map_source() → None[source]: Placeholder, raises NotImplementedError.

map_dataframe(plotter: Callable, *args, **kwargs) → OutsetGrid[source]

Map a plotting function over all axes, including source plot axes (if present).

Uses data stored at initialization, passed as a first data= kwarg. To plot other data, use broadcast. Complete dataset is used for source axes and faceted subsets are used for each outset axes.

Parameters:

plotter (Callable) – The plotting function to be applied to each axis.
*args (tuple) – Positional arguments passed to the plotting function.
**kwargs (dict) – Keyword arguments passed to the plotting function.

Returns:

Returns self.

Return type:

OutsetGrid

map_dataframe_outset(plotter: Callable, *args, **kwargs) → OutsetGrid[source]

Map a plotting function over outset axes only.

Uses data stored at initialization, passed as a first data= kwarg and faceted per subplot axes. To plot other data, use broadcast_outset.

Parameters:

plotter (Callable) – The plotting function to be applied to each axis.
*args (tuple) – Positional arguments passed to the plotting function.
**kwargs (dict) – Keyword arguments passed to the plotting function.

Returns:

Returns self.

Return type:

OutsetGrid

map_dataframe_source(plotter: Callable, *args, **kwargs) → OutsetGrid[source]

Map a plotting function over the source plot axes only.

If source plot axes are not enabled, performs no-op.

Uses data stored at initialization, passed as a first data= kwarg. To plot other data, use broadcast_source.

Parameters:

plotter (Callable) – The plotting function to be applied to each axis.
*args (tuple) – Positional arguments passed to the plotting function.
**kwargs (dict) – Keyword arguments passed to the plotting function.

Returns:

Returns self.

Return type:

OutsetGrid

broadcast(plotter: Callable, *args, **kwargs) → OutsetGrid[source]

Map a plotting function over all axes, including the source plot axis (if present).

Performs call with same data and arguments for all axes. To use faceted data stored at initialization, refer to map_dataframe.

Parameters:

plotter (Callable) – The plotting function to be applied to each axis.
*args (tuple) – Positional arguments passed to the plotting function.
**kwargs (dict) – Keyword arguments passed to the plotting function.

Returns:

Returns self.

Return type:

OutsetGrid

Notes

Does not use data stored from initialization. Data should be provided via argument to this method.

Preserves axis limits for all axes except the source plot, if present.

broadcast_outset(plotter: Callable, *args, **kwargs) → OutsetGrid[source]

Map a plotting function over only outset axes.

Performs call with same data and arguments for all axes. To use faceted data stored at initialization, refer to map_dataframe.

Parameters:

plotter (Callable) – The plotting function to be applied to each axis.
*args (tuple) – Positional arguments passed to the plotting function.
**kwargs (dict) – Keyword arguments passed to the plotting function.

Returns:

Returns self.

Return type:

OutsetGrid

Notes

Does not use data stored from initialization. Data should be provided via argument to this method.

Preserves axis limits.

broadcast_source(plotter: Callable, *args, **kwargs) → OutsetGrid[source]

Map a plotting function over source plot axes, if present.

Performs call with same data and arguments for all axes. To use faceted data stored at initialization, refer to map_dataframe.

Parameters:

plotter (Callable) – The plotting function to be applied to each axis.
*args (tuple) – Positional arguments passed to the plotting function.
**kwargs (dict) – Keyword arguments passed to the plotting function.

Returns:

Returns self.

Return type:

OutsetGrid

Notes

Does not use data stored from initialization. Data should be provided via argument to this method.

Doesn’t preserve axis limits.