15 Links

Code

library(ggalign)
#> Loading required package: ggplot2
#> ========================================
#> ggalign version 1.1.0.9000
#> 
#> If you use it in published research, please cite: 
#> Peng, Y.; Jiang, S.; Song, Y.; et al. ggalign: Bridging the Grammar of Graphics and Biological Multilayered Complexity. Advanced Science. 2025. doi:10.1002/advs.202507799
#> ========================================

ggalign provides a linking mechanism that allows you to select observations and either:

annotate them with additional plots, or
visually connect them using lines, polygons, or other elements.

The pair_links() function is used to define pairs of connected observations. In the formula, the left side (before the ~) represents hand1—the observations on the left (for a horizontal stack layout) or top (for a vertical stack layout). The right side (after the ~) represents hand2—the observations on the right (for horizontal stack) or bottom (for vertical stack).

These defined pairs will either be linked together, or each group in the pair will be linked separately within the same plot area.

Both sides of the formula can be specified using integer or character indices of the original data (before reordering).

pair_links(1:2 ~ c("c", "d"), c("a", "b") ~ 3:4)
#> <ggalign_pair_links>
#> A total of 2 pairs of link groups
#> 
#>             hand1 ~ hand2      
#>   1:          1:2 ~ c("c", "d")
#>   2:  c("a", "b") ~ 3:4        
#> 
#> A total of 4 link groups

The print method showed various informations:

The object class and the number of paired groups.
The specific groups in each pair.
The total number of groups (rather than the number of paired groups). For example, in this case, there are 4 groups in total since each pair consists of 2 groups.

If only the left-hand side of the formula exists, you can input it directly.

pair_links(1:2, c("a", "b"))
#> <ggalign_pair_links>
#> A total of 2 pairs of link groups
#> 
#>             hand1 ~ hand2
#>   1:          1:2 ~      
#>   2:  c("a", "b") ~      
#> 
#> A total of 2 link groups

To specify links in the right only, you must use formula:

pair_links(~ 1:2, ~ c("a", "b"))
#> <ggalign_pair_links>
#> A total of 2 pairs of link groups
#> 
#>       hand1 ~ hand2      
#>   1:        ~ 1:2        
#>   2:        ~ c("a", "b")
#> 
#> A total of 2 link groups

For integer indices, wrap them with I() to follow ordering from the layout.

pair_links(I(1:2))
#> <ggalign_pair_links>
#> A total of 1 pair of link groups
#> 
#>        hand1 ~ hand2
#>   1:  I(1:2) ~      
#> 
#> A total of 1 link group

You can wrap the whole formula.

pair_links(I(1:2 ~ 3:4))
#> <ggalign_pair_links>
#> A total of 1 pair of link groups
#> 
#>        hand1 ~ hand2 
#>   1:  I(1:2) ~ I(3:4)
#> 
#> A total of 2 link groups

15.1 range_link()

range_link() function can be used to define a range of observations, which accepts two argument that specify the lower and upper bounds of the range. These bounds should be defined as a single integer or character.

pair_links(range_link(1, "a"))
#> <ggalign_pair_links>
#> A total of 1 pair of link groups
#> 
#>                    hand1 ~ hand2
#>   1:  range_link(1, "a") ~      
#> 
#> A total of 1 link group

In this case, the left-hand is defined as the range between the 1st observation and the observation named "a".

15.2 Using waiver()

You can also use waiver() to inherit values from the opposite group.

pair_links(range_link(1, "a") ~ waiver())
#> <ggalign_pair_links>
#> A total of 1 pair of link groups
#> 
#>                    hand1 ~ hand2   
#>   1:  range_link(1, "a") ~ waiver()
#> 
#> A total of 2 link groups

1: inherit values from the left hand

pair_links(waiver() ~ range_link(1, "a"))
#> <ggalign_pair_links>
#> A total of 1 pair of link groups
#> 
#>          hand1 ~ hand2             
#>   1:  waiver() ~ range_link(1, "a")
#> 
#> A total of 2 link groups

1: inherit values from the right hand

15.3 Combining Components

You can combine any of these into a list.

pair_links(list(range_link(1, "a"), waiver()) ~ list(4:5, c("b", "c")))
#> <ggalign_pair_links>
#> A total of 1 pair of link groups
#> 
#>                                    hand1 ~ hand2                 
#>   1:  list(range_link(1, "a"), waiver()) ~ list(4:5, c("b", "c"))
#> 
#> A total of 2 link groups

In this example, the left side combines the range between the 1st observation and “a” with the observations 4 and 5, and the observations “b” and “c”.