patch: Get Patch representation

In ggalign: A 'ggplot2' Extension for Composable Visualization

Get Patch representation

Description

ggalign::Patch represents the layout manager for a single subplot within a composite plot. The Patch object provides the interface for aligning the subplot, managing panel sizes, and handling guide legends.

Usage

patch(x)

Arguments

x	Any objects has a Patch representation

Details

In alignpatches(), each subplot is regarded as a patch, and a corresponding Patch object is required for proper alignment and layout operations. Patch is a ggproto() object that provides the core methods for arranging and aligning subplots.

Value

A ggalign::Patch object.

Fields

guides

Description

(Optional method) Determines which sides of the guide legends should be collected by the parent alignpatches() object.

This per-plot method allows each subplot to modify the guides passed to the self$decompose_guides() method, ensuring that plots along the border collect their guide legends correctly. Such fine-grained control cannot be achieved when relying on only a single self$decompose_guides() method.

Arguments

• guides: The guides argument passed from the parent alignpatches() object, specifying how legends should be combined or positioned. Possible values include "top", "left", "bottom", and "right".

Value A modified guides object indicating which sides of the guide legends should be collected by the parent alignpatches() object.

gtable

Description

(Required method) Constructs a standardized gtable object.

Arguments

• theme: The global theme of the parent alignpatches() object.

• guides: Specifies which sides of guide legends should be collected by the parent alignpatches() object. In most cases, this is the value returned by the subplot's self$guides() method. For plots along the border, any guide legends on that side will always be collected if any legends on that side of any subplot are being collected.

• tagger: Either NULL (no tagging) or a LayoutTagger object that provides a ⁠$tag_table⁠ method (accepting the gtable and theme) used to add tag.

Value A standardized gtable object representing the plot layout.

decompose_guides

Description

(Optional method) Collects guide legends and optionally removes the space they occupy.

This method extracts guide legends based on the sides specified in the guides argument. After collecting the guides, the corresponding space in the the gt is removed to free up space, except for guides placed inside the panel.

Arguments

• gt: A gtable object, usually returned by self$gtable().

• guides: Specifies which sides of guide legends should be collected by the parent alignpatches() object. In most cases, this is the value returned by the subplot's self$guides() method. For plots along the border, any guide legends on that side will always be collected if any legends on that side of any subplot are being collected.

Value A list with:

• gt: The updated gtable with guide legends removed (if applicable).

• guides: A named list of collected guide grobs corresponding to the sides specified in guides (or NULL if absent).

align_panel

Description

(Optional method) In most cases, panel sizes do not need to be manually adjusted when aligning panels, as long as their border sizes are consistent. However, for gtables with a fixed aspect ratio, this method adjusts the panel width and height based on user input and the dimensions of the underlying gtable (gt) to ensure proper alignment.

When the internal numeric value of either panel_width or panel_height is NA (i.e., is.na(as.numeric(...))), that dimension is inferred from the gtable while maintaining the aspect ratio for single-panel layouts when respect = TRUE.

Arguments

• gt: A gtable object, usually returned by self$decompose_guides().

• panel_width/panel_height: Unit objects specifying the desired panel size. If the internal numeric value of either is NA, the size is computed from the gtable (gt).

Value A list with components:

• width: Final panel width as a unit object

• height: Final panel height as a unit object

• respect: If TRUE, the aspect ratio was enforced

border_sizes

Description

(Optional method) retrieve the border sizes of a gtable.

Arguments

• gt: A gtable object, usually returned by self$decompose_guides().

• free: Optional. Borders to exclude when calculating sizes. Possible values include "top", "left", "bottom", and "right".

Value A list with components:

• top: unit values for the top borders.

• left: unit values for the left borders.

• bottom: unit values for the bottom borders.

• right: unit values for the right borders.

align_border

Description

(Optional method) This method modifies the top, left, bottom, and right border sizes of the underlying gtable (gt) by replacing corresponding entries in its heights and widths vectors..

Arguments

• gt: A gtable object, usually returned by self$decompose_guides().

• t, l, b, r: Optional numeric vectors specifying new sizes for the top, left, bottom, and right borders, respectively. Each vector replaces the corresponding entries in gt$heights or gt$widths.

Value A modified gtable object.

place

Description (Optional method) Inserts the patch's gtable (including optional background) into the target canvas gtable.

This method places the patch's gtable into a specified location of another gtable, preserving the background and plot layers separately if a background exists. The t, l, b, r arguments specify the position in the target gtable, and bg_z / plot_z define the stacking order (z-order) for background and plot.

Arguments

• gtable: the target canvas gtable into which the patch will be inserted.

• gt: A gtable object, usually returned by self$align_border().

• t, l, b, r: Integer positions (top, left, bottom, right) specifying where to insert the patch in the target gtable.

• i: Index of the current patch, used to generate unique grob names.

• bg_z: Z-order for the background grob (default 1L).

• plot_z: Z-order for the plot grob (default 2L).

Details

• If the patch includes a grob named "background", it is separated from the main plot and inserted independently from the plot grob.

• If no background is present, the entire gtable is inserted as the plot grob.

Value The modified target canvas gtable with the patch's gtable added.

decompose_bg

Description Separates the background grob (if present) from the main gtable.

Value A list with:

• bg: The background grob (or NULL if absent)

• gt: The gtable with background removed

place_bg

Description Adds the background grob into the target gtable.

place_gt

Description Adds the main plot gtable into the target gtable.

is_alignpatches

Description

Checks whether the object inherits from the alignpatches() Patch representation.

If TRUE, the fields self$patches, self$gt_list, and self$borders_list are expected to exist in the ⁠$align_border()⁠ and ⁠$place()⁠ methods. See the patch.ggalign_free_lab function in the alignpatch-free-lab.R script for an example of usage.

Value Logical value (TRUE or FALSE) indicating whether self is a PatchAlignpatches object.

See Also

alignpatches()/align_plots()

Examples

patch(ggplot())

ggalign documentation built on Nov. 5, 2025, 7:16 p.m.