Author: Yu Gao(gaoyu19920914@gmail.com)
Date: 2026-06-01

# BetaStability Quick Start Guide

#### Yu Gao(gaoyu19920914@gmail.com)

#### 2026-06-01

# 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
    head(result_linear)
    #>    stability_Linear
    #> 18       0.10957916
    #> 15       0.04122119
    #> 24       0.03322119
    #> 27       0.01357100
    #> 23       0.10483057
    #> 19       0.15983875
    length(result_linear)
    #> [1] 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.09500812
    #> 15 0.04122119  0.04948000  0.01748590
    #> 24 0.03322119 -0.48026478 -0.21070746
    #> 27 0.01357100  0.03842571  0.02109734
    #> 23 0.10483057  0.12130661  0.09886321
    #> 19 0.15983875  0.26114780  0.20125290
    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.09937490  0.01719127  0.12600785  0.10018222
    #> 15 0.04122119  0.04948000  0.01617294 -0.02551985  0.05920659  0.01628172
    #> 24 0.03322119 -0.48026478 -0.21337998 -0.13782392 -0.13878658 -0.21489886
    #> 27 0.01357100  0.03842571  0.02109734 -0.03525648  0.07550562  0.01931343
    #> 23 0.10483057  0.12130661  0.09862410  0.03382381  0.08270438  0.09435799
    #> 19 0.15983875  0.26114780  0.20126436  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

## 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
    p4 <- plotStability(results_multi, sitenames = custom_sitenames)
    p4

## 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.5.3 (2026-03-11 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.2       vegan_2.7-3         permute_0.9-10
    #> [4] betaStability_0.0.4
    #>
    #> loaded via a namespace (and not attached):
    #>  [1] sass_0.4.10          generics_0.1.4       shape_1.4.6.1
    #>  [4] stringi_1.8.7        lattice_0.22-9       usedist_0.4.0
    #>  [7] digest_0.6.39        magrittr_2.0.4       evaluate_1.0.5
    #> [10] grid_4.5.3           RColorBrewer_1.1-3   BBmisc_1.13.1
    #> [13] iterators_1.0.14     fastmap_1.2.0        xgboost_3.2.1.1
    #> [16] glmnet_4.1-10        Matrix_1.7-5         foreach_1.5.2
    #> [19] doParallel_1.0.17    plyr_1.8.9           jsonlite_2.0.0
    #> [22] backports_1.5.0      survival_3.8-6       mgcv_1.9-4
    #> [25] scales_1.4.0         pbapply_1.7-4        codetools_0.2-20
    #> [28] jquerylib_0.1.4      cli_3.6.5            rlang_1.1.7
    #> [31] splines_4.5.3        withr_3.0.2          cachem_1.1.0
    #> [34] yaml_2.3.12          otel_0.2.0           tools_4.5.3
    #> [37] parallel_4.5.3       reshape2_1.4.5       checkmate_2.3.4
    #> [40] dplyr_1.2.0          gdm_1.6.0-7          vctrs_0.7.2
    #> [43] R6_2.6.1             lifecycle_1.0.5      randomForest_4.7-1.2
    #> [46] stringr_1.6.0        MASS_7.3-65          cluster_2.1.8.2
    #> [49] pkgconfig_2.0.3      pillar_1.11.1        bslib_0.10.0
    #> [52] gtable_0.3.6         data.table_1.18.2.1  glue_1.8.0
    #> [55] Rcpp_1.1.1           xfun_0.57            tibble_3.3.1
    #> [58] tidyselect_1.2.1     rstudioapi_0.18.0    knitr_1.51
    #> [61] farver_2.1.2         nlme_3.1-169         htmltools_0.5.9
    #> [64] labeling_0.4.3       rmarkdown_2.31       compiler_4.5.3
    #> [67] S7_0.2.1