Skip to contents

Create a New align Object

Source: R/align-.R
align.Rd

[Experimental]

An align object interacts with the layout object to reorder or split observations and, in some cases, add plot components to the layout.

Usage

align(
  align_class,
  params,
  data,
  size = NULL,
  controls = NULL,
  limits = TRUE,
  facet = TRUE,
  no_axes = NULL,
  active = NULL,
  free_guides = deprecated(),
  free_spaces = deprecated(),
  plot_data = deprecated(),
  theme = deprecated(),
  free_labs = deprecated(),
  check.param = TRUE,
  call = caller_call()
)

Arguments

align_class

A Align object.

params

A list of parameters for align_class.

data

Options for data:

  • A matrix, data frame, or atomic vector.

  • waiver(): Uses the layout matrix.

  • NULL: No data is set.

  • A function (including purrr-like lambda syntax) applied to the layout matrix.

size

The relative size of the plot, can be specified as a unit.

controls

Options for controls:

  • NULL: Used when align_*() functions do not add a plot.

  • waiver(): Try to infer controls based on data.

limits

Logical; if TRUE, sets layout limits for the plot.

facet

Logical; if TRUE, applies facets to the layout. If FALSE, limits will also be set to FALSE.

no_axes

[Experimental] Logical; if TRUE, removes axes elements for the alignment axis using theme_no_axes(). By default, will controled by the option- "ggalign.align_no_axes".

active

A active() object that defines the context settings when added to a layout.

free_guides

[Superseded] Please use plot_align() function instead.

free_spaces

[Deprecated] Please use plot_align() function instead.

plot_data

[Deprecated] Please use plot_data() function instead.

theme

[Deprecated] Please use plot_theme() function instead.

free_labs

[Deprecated] Please use plot_align() function instead.

check.param

Logical; if TRUE, checks parameters and provides warnings as necessary.

call

The call used to construct the Align object, for reporting messages.

Value

A new align object.

Details

Each of the Align* objects is just a ggproto() object, descended from the top-level Align, and each implements various methods and fields.

To create a new type of Align* object, you typically will want to override one or more of the following:

  • setup_params: Prepare parameter or check parameters used by this plot.

  • setup_data: Prepare data used by this plot.

  • compute: A method used to compute statistics.

  • layout: A method used to group observations into panel or reorder observations.

  • draw: A method used to draw the plot. Must return a ggplot object.

Axis Alignment for Observations

It is important to note that we consider rows as observations, meaning vec_size(data)/NROW(data) must match the number of observations along the axis used for alignment (x-axis for a vertical stack layout, y-axis for a horizontal stack layout).

  • quad_layout()/ggheatmap(): For column annotation, the layout matrix will be transposed before use (if data is a function, it is applied to the transposed matrix), as column annotation uses columns as observations but alignment requires rows.

  • stack_layout(): The layout matrix is used as is, aligning all plots along a single axis.

Examples

align_gg()
#> $Object
#> <ggproto object: Class AlignGG, Align, gg>
#>     call: call
#>     compute: function
#>     data: NULL
#>     direction: NULL
#>     draw: function
#>     extra_params: 
#>     ggplot: function
#>     input_data: waiver
#>     input_params: list
#>     isLock: FALSE
#>     labels: NULL
#>     layout: function
#>     lock: function
#>     nobs: function
#>     parameters: function
#>     params: NULL
#>     position: NULL
#>     setup_data: function
#>     setup_params: function
#>     statistics: NULL
#>     unlock: function
#>     super:  <ggproto object: Class AlignGG, Align, gg>
#> 
#> $no_axes
#> [1] TRUE
#> 
#> $controls
#> $controls$plot_data
#> $data
#> list()
#> attr(,"class")
#> [1] "waiver"
#> 
#> $inherit
#> [1] FALSE
#> 
#> attr(,"__ggalign.option_name__")
#> [1] "plot_data"
#> attr(,"class")
#> [1] "plot_data"      "ggalign_option"
#> 
#> $controls$plot_theme
#>  Named list()
#>  - attr(*, "class")= chr [1:4] "plot_theme" "theme" "gg" "ggalign_option"
#>  - attr(*, "complete")= logi FALSE
#>  - attr(*, "validate")= logi TRUE
#>  - attr(*, "__ggalign.option_name__")= chr "plot_theme"
#> 
#> $controls$plot_align
#> $free_spaces
#> list()
#> attr(,"class")
#> [1] "waiver"
#> 
#> $free_labs
#> list()
#> attr(,"class")
#> [1] "waiver"
#> 
#> $guides
#> list()
#> attr(,"class")
#> [1] "waiver"
#> 
#> attr(,"__ggalign.option_name__")
#> [1] "plot_align"
#> attr(,"class")
#> [1] "plot_align"     "ggalign_option"
#> 
#> 
#> $facet
#> [1] TRUE
#> 
#> $limits
#> [1] TRUE
#> 
#> $size
#> [1] NAnull
#> 
#> $active
#> $order
#> [1] NA
#> 
#> $use
#> [1] TRUE
#> 
#> $name
#> [1] NA
#> 
#> attr(,"class")
#> [1] "ggalign_active"
#> 
#> $plot
#> NULL
#> 
#> attr(,"class")
#> [1] "align"
align_dendro()
#> $Object
#> <ggproto object: Class AlignDendro, Align, gg>
#>     call: call
#>     compute: function
#>     data: NULL
#>     direction: NULL
#>     draw: function
#>     extra_params: 
#>     ggplot: function
#>     input_data: waiver
#>     input_params: list
#>     isLock: FALSE
#>     labels: NULL
#>     layout: function
#>     lock: function
#>     nobs: function
#>     parameters: function
#>     params: NULL
#>     position: NULL
#>     setup_data: function
#>     setup_params: function
#>     statistics: NULL
#>     unlock: function
#>     super:  <ggproto object: Class AlignDendro, Align, gg>
#> 
#> $no_axes
#> [1] TRUE
#> 
#> $controls
#> $controls$plot_data
#> $data
#> NULL
#> 
#> $inherit
#> [1] FALSE
#> 
#> attr(,"__ggalign.option_name__")
#> [1] "plot_data"
#> attr(,"class")
#> [1] "plot_data"      "ggalign_option"
#> 
#> $controls$plot_theme
#>  Named list()
#>  - attr(*, "class")= chr [1:4] "plot_theme" "theme" "gg" "ggalign_option"
#>  - attr(*, "complete")= logi FALSE
#>  - attr(*, "validate")= logi TRUE
#>  - attr(*, "__ggalign.option_name__")= chr "plot_theme"
#> 
#> $controls$plot_align
#> $free_spaces
#> list()
#> attr(,"class")
#> [1] "waiver"
#> 
#> $free_labs
#> list()
#> attr(,"class")
#> [1] "waiver"
#> 
#> $guides
#> list()
#> attr(,"class")
#> [1] "waiver"
#> 
#> attr(,"__ggalign.option_name__")
#> [1] "plot_align"
#> attr(,"class")
#> [1] "plot_align"     "ggalign_option"
#> 
#> 
#> $facet
#> [1] TRUE
#> 
#> $limits
#> [1] TRUE
#> 
#> $size
#> [1] NAnull
#> 
#> $active
#> $order
#> [1] NA
#> 
#> $use
#> [1] TRUE
#> 
#> $name
#> [1] NA
#> 
#> attr(,"class")
#> [1] "ggalign_active"
#> 
#> $plot
#> NULL
#> 
#> attr(,"class")
#> [1] "align"