BetaStability Quick Start Guide

Yu Gao(gaoyu19920914@gmail.com)

2026-10-09

BetaStability Quick Start Guide

This vignette demonstrates the capabilities of the BetaStability package using the varespec and varechem datasets from the vegan package.

Installation

First, install the package from GitHub:

# Install from GitHub
# install.packages("devtools")
# devtools::install_github("gaoyu19920914/betaStability")

# OR install from BioConductor (in the future when it's available)
# if (!requireNamespace("BiocManager", quietly = TRUE))
#     install.packages("BiocManager")
# BiocManager::install("betaStability")

Loading Required Packages

Load the BetaStability package and the vegan package for test data:

library(betaStability)
library(vegan)
#> Loading required package: permute
library(ggplot2)

Loading Test Data

Load the varespec (community data) and varechem (environmental metadata) datasets from the vegan package:

data(varespec)
data(varechem)

# Inspect the data
head(varespec)
#>    Callvulg Empenigr Rhodtome Vaccmyrt Vaccviti Pinusylv Descflex Betupube
#> 18     0.55    11.13     0.00     0.00    17.80     0.07     0.00        0
#> 15     0.67     0.17     0.00     0.35    12.13     0.12     0.00        0
#> 24     0.10     1.55     0.00     0.00    13.47     0.25     0.00        0
#> 27     0.00    15.13     2.42     5.92    15.97     0.00     3.70        0
#> 23     0.00    12.68     0.00     0.00    23.73     0.03     0.00        0
#> 19     0.00     8.92     0.00     2.42    10.28     0.12     0.02        0
#>    Vacculig Diphcomp Dicrsp Dicrfusc Dicrpoly Hylosple Pleuschr Polypili
#> 18     1.60     2.07   0.00     1.62     0.00      0.0     4.67     0.02
#> 15     0.00     0.00   0.33    10.92     0.02      0.0    37.75     0.02
#> 24     0.00     0.00  23.43     0.00     1.68      0.0    32.92     0.00
#> 27     1.12     0.00   0.00     3.63     0.00      6.7    58.07     0.00
#> 23     0.00     0.00   0.00     3.42     0.02      0.0    19.42     0.02
#> 19     0.00     0.00   0.00     0.32     0.02      0.0    21.03     0.02
#>    Polyjuni Polycomm Pohlnuta Ptilcili Barbhatc Cladarbu Cladrang Cladstel
#> 18     0.13     0.00     0.13     0.12     0.00    21.73    21.47     3.50
#> 15     0.23     0.00     0.03     0.02     0.00    12.05     8.13     0.18
#> 24     0.23     0.00     0.32     0.03     0.00     3.58     5.52     0.07
#> 27     0.00     0.13     0.02     0.08     0.08     1.42     7.63     2.55
#> 23     2.12     0.00     0.17     1.80     0.02     9.08     9.22     0.05
#> 19     1.58     0.18     0.07     0.27     0.02     7.23     4.95    22.08
#>    Cladunci Cladcocc Cladcorn Cladgrac Cladfimb Cladcris Cladchlo Cladbotr
#> 18     0.30     0.18     0.23     0.25     0.25     0.23     0.00     0.00
#> 15     2.65     0.13     0.18     0.23     0.25     1.23     0.00     0.00
#> 24     8.93     0.00     0.20     0.48     0.00     0.07     0.10     0.02
#> 27     0.15     0.00     0.38     0.12     0.10     0.03     0.00     0.02
#> 23     0.73     0.08     1.42     0.50     0.17     1.78     0.05     0.05
#> 19     0.25     0.10     0.25     0.18     0.10     0.12     0.05     0.02
#>    Cladamau Cladsp Cetreric Cetrisla Flavniva Nepharct Stersp Peltapht Icmaeric
#> 18     0.08   0.02     0.02     0.00     0.12     0.02   0.62     0.02        0
#> 15     0.00   0.00     0.15     0.03     0.00     0.00   0.85     0.00        0
#> 24     0.00   0.00     0.78     0.12     0.00     0.00   0.03     0.00        0
#> 27     0.00   0.02     0.00     0.00     0.00     0.00   0.00     0.07        0
#> 23     0.00   0.00     0.00     0.00     0.02     0.00   1.58     0.33        0
#> 19     0.00   0.00     0.00     0.00     0.02     0.00   0.28     0.00        0
#>    Cladcerv Claddefo Cladphyl
#> 18        0     0.25        0
#> 15        0     1.00        0
#> 24        0     0.33        0
#> 27        0     0.15        0
#> 23        0     1.97        0
#> 19        0     0.37        0
head(varechem)
#>       N    P     K    Ca    Mg    S    Al   Fe    Mn   Zn  Mo Baresoil Humdepth
#> 18 19.8 42.1 139.9 519.4  90.0 32.3  39.0 40.9  58.1  4.5 0.3     43.9      2.2
#> 15 13.4 39.1 167.3 356.7  70.7 35.2  88.1 39.0  52.4  5.4 0.3     23.6      2.2
#> 24 20.2 67.7 207.1 973.3 209.1 58.1 138.0 35.4  32.1 16.8 0.8     21.2      2.0
#> 27 20.6 60.8 233.7 834.0 127.2 40.7  15.4  4.4 132.0 10.7 0.2     18.7      2.9
#> 23 23.8 54.5 180.6 777.0 125.8 39.5  24.2  3.0  50.1  6.6 0.3     46.0      3.0
#> 19 22.8 40.9 171.4 691.8 151.4 40.8 104.8 17.6  43.6  9.1 0.4     40.5      3.8
#>     pH
#> 18 2.7
#> 15 2.8
#> 24 3.0
#> 27 2.8
#> 23 2.7
#> 19 2.7

# Dimensions of the datasets
cat("Dimensions of varespec:", dim(varespec), "\n")
#> Dimensions of varespec: 24 44
cat("Dimensions of varechem:", dim(varechem), "\n")
#> Dimensions of varechem: 24 14

Calculating Stability with Single Method

Calculate stability using a single prediction method (linearPred):

# Calculate stability with linearPred
result_linear <- betaStability(
    comtable = varespec,
    envmeta = varechem,
    method = "linearPred"
)

# Inspect the result
length(result_linear$stability_Linear)
#> [1] 24

# Calculate stability with linearPred with symmetric algorithm
result_linear_symmetric <- betaStability(
    comtable = varespec,
    envmeta = varechem,
    method = "linearPred",
    symmetric = TRUE
)

# Calculate the correlations between the results
corr_pearson <- cor.test(result_linear$stability_Linear, 
                         result_linear_symmetric$stability_Linear, 
                         method = c("pearson"))
corr_spearman <- cor.test(result_linear$stability_Linear, 
                          result_linear_symmetric$stability_Linear, 
                          method = c("spearman"))
corr_pearson
#> 
#>  Pearson's product-moment correlation
#> 
#> data:  result_linear$stability_Linear and result_linear_symmetric$stability_Linear
#> t = 23.908, df = 22, p-value < 2.2e-16
#> alternative hypothesis: true correlation is not equal to 0
#> 95 percent confidence interval:
#>  0.9565481 0.9920050
#> sample estimates:
#>       cor 
#> 0.9812944
corr_spearman
#> 
#>  Spearman's rank correlation rho
#> 
#> data:  result_linear$stability_Linear and result_linear_symmetric$stability_Linear
#> S = 2.5535e-13, p-value = 7.269e-07
#> alternative hypothesis: true rho is not equal to 0
#> sample estimates:
#> rho 
#>   1

Calculating Stability with Multiple Methods

Calculate stability using multiple prediction methods:

# Calculate stability with multiple methods
results_multi <- betaStability(
    comtable = varespec,
    envmeta = varechem,
    method = c("linearPred", "mlPred", "glmPred")
)

# Inspect the result
head(results_multi)
#>    linearPred      mlPred     glmPred
#> 18 0.10957916  0.10697541  0.09541857
#> 15 0.04122119  0.04948000  0.01628894
#> 24 0.03322119 -0.48026478 -0.21307628
#> 27 0.01357100  0.03842571  0.01940252
#> 23 0.10483057  0.12130661  0.09877083
#> 19 0.15983875  0.26114780  0.20125162
dim(results_multi)
#> [1] 24  3

Calculating Stability with All Methods

Calculate stability using all available prediction methods:

# Calculate stability with all methods
results_all <- betaStability(
    comtable = varespec,
    envmeta = varechem,
    method = "all"
)

# Inspect the result
head(results_all)
#>    linearPred      mlPred     glmPred     gamPred     gdmPred      rfPred
#> 18 0.10957916  0.10697541  0.09423179  0.01719127  0.12600785  0.10018222
#> 15 0.04122119  0.04948000  0.01799775 -0.02551985  0.05920659  0.01628172
#> 24 0.03322119 -0.48026478 -0.21251261 -0.13782392 -0.13878658 -0.21489886
#> 27 0.01357100  0.03842571  0.02542089 -0.03525648  0.07550562  0.01931343
#> 23 0.10483057  0.12130661  0.09886321  0.03382381  0.08270438  0.09435799
#> 19 0.15983875  0.26114780  0.20125632  0.09397862  0.16207300  0.18880189
#>    xgboostPred
#> 18  0.09206358
#> 15  0.02510648
#> 24 -0.25652045
#> 27  0.02518945
#> 23  0.06493194
#> 19  0.20346170
dim(results_all)
#> [1] 24  7
colnames(results_all)
#> [1] "linearPred"  "mlPred"      "glmPred"     "gamPred"     "gdmPred"    
#> [6] "rfPred"      "xgboostPred"

Visualizing Stability Results

Visualize the stability results using the plotStability function:

# Plot stability results for single method
p1 <- plotStability(result_linear)
p1

# Plot stability results for multiple methods
p2 <- plotStability(results_multi)
p2

# Plot stability results for all methods
p3 <- plotStability(results_all)
p3

Visualize the correlations between different stability quantifying methods using the plotCorrelation function:

# Plot stability correlations between all pairs of methods
p4 <- plotCorrelation(results_all)
p4

Customizing Site Names

You can also customize the site names in the plot:

# Create custom site names
custom_sitenames <- paste("Site", seq_len(nrow(varespec)))

# Plot with custom site names
p5 <- plotStability(results_multi, sitenames = custom_sitenames)
p5

Conclusion

The betaStability package provides a comprehensive framework for calculating and visualizing site stability using various prediction methods. Key features include:

  1. Multiple prediction methods: Choose from linear, multiple linear model, generalized linear model, generalized additive model, generalized dissimilarity model, random forest, and xgboost models.
  2. Flexible input options: Use precomputed distance matrices or let the package compute them automatically.
  3. Easy visualization: The plotStability function creates informative plots of stability results.
  4. Convenient “all” method: Run all prediction methods with a single parameter setting and receive a summary of results.

This package is designed to help researchers and ecologists assess site stability based on the beta stability of communities, providing valuable insights for ecosystem management.

print(sessionInfo())
#> R version 4.6.1 (2026-06-24 ucrt)
#> Platform: x86_64-w64-mingw32/x64
#> Running under: Windows 11 x64 (build 26200)
#> 
#> Matrix products: default
#>   LAPACK version 3.12.1
#> 
#> locale:
#> [1] LC_COLLATE=C                          
#> [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: Asia/Shanghai
#> tzcode source: internal
#> 
#> attached base packages:
#> [1] stats     graphics  grDevices utils     datasets  methods   base     
#> 
#> other attached packages:
#> [1] ggplot2_4.0.3       vegan_2.7-6         permute_0.9-10     
#> [4] betaStability_0.1.0
#> 
#> loaded via a namespace (and not attached):
#>  [1] gtable_0.3.6         shape_1.4.6.1        xfun_0.61           
#>  [4] bslib_0.12.0         raster_3.6-32        BBmisc_1.13.1       
#>  [7] lattice_0.23-1       vctrs_0.7.3          tools_4.6.1         
#> [10] generics_0.1.4       parallel_4.6.1       tibble_3.3.1        
#> [13] cluster_2.1.8.3      pkgconfig_2.0.3      Matrix_1.7-6        
#> [16] data.table_1.18.6.1  checkmate_2.3.4      RColorBrewer_1.1-3  
#> [19] S7_0.2.2             lifecycle_1.0.5      compiler_4.6.1      
#> [22] farver_2.1.2         stringr_1.6.0        terra_1.9-50        
#> [25] codetools_0.2-20     htmltools_0.5.9      sass_0.4.10         
#> [28] yaml_2.3.12          glmnet_5.0           pillar_1.11.1       
#> [31] jquerylib_0.1.4      MASS_7.3-66          gdm_1.6.0-7         
#> [34] cachem_1.1.0         elevatr_0.99.1       iterators_1.0.14    
#> [37] foreach_1.5.2        nlme_3.1-171         tidyselect_1.2.1    
#> [40] digest_0.6.39        stringi_1.8.9        dplyr_1.2.1         
#> [43] reshape2_1.4.5       purrr_1.2.2          labeling_0.4.3      
#> [46] splines_4.6.1        fastmap_1.2.0        grid_4.6.1          
#> [49] cli_3.6.6            magrittr_2.0.5       randomForest_4.7-1.2
#> [52] survival_3.8-12      withr_3.0.3          scales_1.4.0        
#> [55] backports_1.5.1      xgboost_3.2.1.1      sp_2.2-3            
#> [58] usedist_0.4.0        rmarkdown_2.32       otel_0.2.0          
#> [61] progressr_1.0.0      pbapply_1.7-5        evaluate_1.0.5      
#> [64] knitr_1.52           doParallel_1.0.17    mgcv_1.9-4          
#> [67] rlang_1.3.0          Rcpp_1.1.2           glue_1.8.1          
#> [70] rstudioapi_0.19.0    jsonlite_2.0.0       R6_2.6.1            
#> [73] plyr_1.8.9