Replacing spanner doesn't work and instead adds a second spanner

[szimmer]

Prework

• [ x] Read and agree to the code of conduct and contributing guidelines.
• [x ] If there is already a relevant issue, whether open or closed, comment on the existing thread instead of posting a new issue.

Description

I was working with a gt and trying to change the spanner. When trying this, instead I just got a second spanner.

Reproducible example

• [x ] Post a minimal reproducible example so the maintainer can troubleshoot the problems you identify. A reproducible example is:
  • [x ] Runnable: post enough R code and data so any onlooker can create the error on their own computer.
  • [x ] Minimal: reduce runtime wherever possible and remove complicated details that are irrelevant to the issue at hand.
  • [x ] Readable: format your code according to the tidyverse style guide.

library(gt)

gtcar_df <- gtcars |>
  dplyr::select(
    -mfr, -trim, bdy_style,
    -drivetrain, -trsmn, -ctry_origin
  ) |>
  dplyr::slice(1:8)

try1 <- gtcar_df |>
  gt(rowname_col = "model") |>
  tab_spanner(
    label = "performance",
    columns = c(
      hp, hp_rpm, trq, trq_rpm,
      mpg_c, mpg_h
    )
  )

# Replacing spanner 
try1 %>%
  tab_spanner(
    label = "performance v2",
    columns = c(
      hp, hp_rpm, trq, trq_rpm,
      mpg_c, mpg_h
    ),
    replace = TRUE
  )

			performance v2
	year	bdy_style	performance						msrp
			hp	hp_rpm	trq	trq_rpm	mpg_c	mpg_h
GT	2017	coupe	647	6250	550	5900	11	18	447000
458 Speciale	2015	coupe	597	9000	398	6000	13	17	291744
458 Spider	2015	convertible	562	9000	398	6000	13	17	263553
458 Italia	2014	coupe	562	9000	398	6000	13	17	233509
488 GTB	2016	coupe	661	8000	561	3000	15	22	245400
California	2015	convertible	553	7500	557	4750	16	23	198973
GTC4Lusso	2017	coupe	680	8250	514	5750	12	17	298000
FF	2015	coupe	652	8000	504	6000	11	16	295000

# Expected result
gtcar_df |>
  gt(rowname_col = "model") |>
  tab_spanner(
    label = "performance v2",
    columns = c(
      hp, hp_rpm, trq, trq_rpm,
      mpg_c, mpg_h
    )
  )

	year	bdy_style	performance v2						msrp
			hp	hp_rpm	trq	trq_rpm	mpg_c	mpg_h
GT	2017	coupe	647	6250	550	5900	11	18	447000
458 Speciale	2015	coupe	597	9000	398	6000	13	17	291744
458 Spider	2015	convertible	562	9000	398	6000	13	17	263553
458 Italia	2014	coupe	562	9000	398	6000	13	17	233509
488 GTB	2016	coupe	661	8000	561	3000	15	22	245400
California	2015	convertible	553	7500	557	4750	16	23	198973
GTC4Lusso	2017	coupe	680	8250	514	5750	12	17	298000
FF	2015	coupe	652	8000	504	6000	11	16	295000

sessionInfo()
#> R version 4.3.1 (2023-06-16 ucrt)
#> Platform: x86_64-w64-mingw32/x64 (64-bit)
#> Running under: Windows 11 x64 (build 22621)
#> 
#> Matrix products: default
#> 
#> 
#> locale:
#> [1] LC_COLLATE=English_United States.utf8 
#> [2] LC_CTYPE=English_United States.utf8   
#> [3] LC_MONETARY=English_United States.utf8
#> [4] LC_NUMERIC=C                          
#> [5] LC_TIME=English_United States.utf8    
#> 
#> time zone: America/New_York
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] gt_0.9.0
#> 
#> loaded via a namespace (and not attached):
#>  [1] vctrs_0.6.3      cli_3.6.1        knitr_1.43       rlang_1.1.1     
#>  [5] xfun_0.39        generics_0.1.3   glue_1.6.2       htmltools_0.5.5 
#>  [9] fansi_1.0.4      rmarkdown_2.22   evaluate_0.21    tibble_3.2.1    
#> [13] fastmap_1.1.1    yaml_2.3.7       lifecycle_1.0.3  compiler_4.3.1  
#> [17] dplyr_1.1.2      fs_1.6.2         pkgconfig_2.0.3  rstudioapi_0.14 
#> [21] digest_0.6.31    R6_2.5.1         reprex_2.0.2     tidyselect_1.2.0
#> [25] utf8_1.2.3       pillar_1.9.0     magrittr_2.0.3   tools_4.3.1     
#> [29] withr_2.5.0      xml2_1.3.4

Expected result

Spanner should be replaced instead of adding a second one.

Session info

End the reproducible example with a call to sessionInfo() in the same session (e.g. reprex(session_info = TRUE)) and include the output.

[rich-iannone]

To fully replace that spanner we need to specify the level, so the last statement should instead be:

# Replacing spanner 
try1 %>%
  tab_spanner(
    label = "performance v2",
    columns = c(
      hp, hp_rpm, trq, trq_rpm,
      mpg_c, mpg_h
    ),
    level = 1,
    replace = TRUE
  )

Even with replace = TRUE, the standard behavior of stacking new spanners on top of existing will happen. We really need to specify an explicit level and also ensure that replace = TRUE (without the latter, you'll get an error and message about an already-existing spanner at the location specified). I looked at the documentation for tab_spanner() and none of this is clearly stated at all, so I will add an example on how to do this.

[szimmer]

Thanks! I think clarity in documentation would be great. In my mind, a replace argument would replace the value.

[rich-iannone]

Added the relevant documentation to clarify this in 23bd57c, so, closing this now.