OutsetGrid

class OutsetGrid

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.

__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

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.

Methods

Attributes

ax	The matplotlib.axes.Axes when no faceting variables are assigned.
axes	An array of the matplotlib.axes.Axes objects in the grid.
axes_dict	A mapping of facet names to corresponding matplotlib.axes.Axes.
fig	prefer the figure property.
figure	Access the matplotlib.figure.Figure object underlying the grid.
legend	The matplotlib.legend.Legend object, if present.
source_axes
outset_axes

add_legend(*args, **kwargs) → None

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

Call fig.tight_layout within rect that exclude the legend.

_finalize_grid(axlabels: Sequence[str] | None = None) → None

Finalize the annotations and layout.

_is_inset() → bool

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

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

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

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

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

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

Placeholder, raises NotImplementedError.

map_outset() → None

Placeholder, raises NotImplementedError.

map_source() → None

Placeholder, raises NotImplementedError.

map_dataframe(plotter: Callable, *args, **kwargs) → OutsetGrid

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

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

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

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

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

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.