Author: Nathan Chauvel

# Using the MUMARINEX Package

#### Nathan Chauvel

# Introduction

The mumarinex package provides tools for the computation of the MUltivariate MArine Recovery INdEX (MUMARINEX) as described in Chauvel et al. (2026). This index is designed to evaluate community recovery in marine ecosystems by combining three complementary sub-indices:

- Standardized Corrected Shared Richness (SCSR): community richness changes (taxa loss or gain)
- Corrected Bray-Curtis Similarity (CBCS): community structure changes (decrease or increase in abundance)
- Standardized Pielou Index (SPI): community dominance shifts (appearance or changes in dominance)

The package also includes diagnostic and visualization functions to identify which taxa or ecological mechanisms drive the observed variations.

In this vignette, we will observe how to:

1. Install and load the package.
2. Format data.
3. Compute the MUMARINEX index and its sub-indices (SCSR, CBCS and SPI).
4. Visualize sub-indices results with dedicated plotting functions.
5. Generate diagnostics to interpret sub-indices variations.

All examples below use the dataset `Simulated_data`, included in the package.
For details on how this dataset was constructed, please refer to its documentation page (`?Simulated_data`)

# Install and load the package

You can install the development version of mumarinex from CRAN or from GitHub, respectively with:

```r load-data, message=FALSE

install.packages(“mumarinex”) # CRAN devtools::install_github(“Nathan-Chauvel/mumarinex”) # GitHub

    Once you run one of this above command, you can load the package with:

    ``` r
    library(mumarinex)

# Data format

The input data must be provided as a data frame or matrix, with rows representing samples and columns representing species. A reference vector specifying the reference samples must also be supplied. The formatting of Simulated_data can be used as a template for preparing your own dataset. In this example, the reference stations (REF1, REF2) are located in rows 1 to 10. The example dataset can be loaded into the R environment as follows:

    # Load example dataset
    data("Simulated_data")

    # Display the first rows
    head(Simulated_data)
    #>        Sp_A Sp_B Sp_C Sp_D Sp_E Sp_F Sp_G Sp_H Sp_I Sp_J Sp_K Sp_L
    #> REF1.1  496   50  492   59    0    0  929  505  983  491  847  508
    #> REF1.2  473   47  471   52    0    0 1057  528  959  487 1023  438
    #> REF1.3  532   44  439   50    0    0 1018  517 1045  490 1001  643
    #> REF1.4  484   41  550   56    0    0 1003  509  982  495 1056  526
    #> REF1.5  480   38  523   53    0    0  971  501  974  502  986  515
    #> REF2.1  470   48  487   50    0    0  992  496 1001  495 1192  448

    # Definition of the reference position
    ref_idx <- 1:10 # row number of the reference samples

# Compute the MUMARINEX index and its sub-indices (SCSR, CBCS and SPI)

Once the data are properly defined, the MUMARINEX index and its sub-indices can be computed. The function `mumarinex()` calculates the MUMARINEX index, and by setting `subindices = TRUE`, it also returns the three complementary sub-indices.

    # Compute MUMARINEX and sub-indices
    rMUM <- mumarinex(x = Simulated_data, ref = ref_idx, subindices = TRUE, log = FALSE)

    # Extract MUMARINEX
    rMUMARINEX<-rMUM$MUMARINEX

    # Extract sub-indices
    Subind<-rMUM$Subindices

MUMARINEX results can subsequently be examined through graphical representations, such as boxplots.

    stations<-matrix(unlist(strsplit(rownames(Simulated_data),".",fixed=TRUE)),ncol=2,byrow=TRUE)[,1] # get station labels from data rownames

    stations<-factor(stations,levels=unique(stations)) # setting station names as factor to specify in which order it must display it in the boxplot

    boxplot(rMUMARINEX~stations,ylim=c(0,1)) # ylim is set in the interval 0-1 as it is the range of MUMARINEX

# Visualize sub-indices results with dedicated plotting functions

To better understand the variations in MUMARINEX, it is often useful to examine how the sub-indices vary. The `decomplot()` function displays the distribution of these sub-indices (SCSR, CBCS, SPI) across sample groups using boxplots.

    decomplot(x = Simulated_data, g = stations, ref = ref_idx, log = FALSE, main = "Artificial data")

# Generate diagnostics to interpret sub-indices variations

Once the sub-index variations underlying the final MUMARINEX value have been examined, the `diagnostic_tool()` function can be used to identify the species that best account for these changes.

    diagnostic_tool(x = Simulated_data, g = stations, ref = ref_idx, log = FALSE)
    #>
    #> |-----------------------------------------------------------------------------------|
    #> |--------------------------------- SCSR  diagnostic --------------------------------|
    #> |-----------------------------------------------------------------------------------|
    #> > Raw: Raw taxa difference between sample and reference pool
    #> > Mean: Mean taxa difference between sample and reference pool
    #> > Missing_species: Top 5 diff_taxa species (sorted by IndVal of the reference)
    #> > New_species: Top 5 new species (sorted by IndVal of the sample)
    #>
    #>
    #> Table: SCSR diagnostic
    #>
    #> Sample   Raw      Mean     Missing_species          New_species
    #> -------  -------  -------  -----------------------  -----------------------
    #> RD       ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #>                            /                        Sp_E
    #>                            /                        Sp_F
    #> RI       2        2        /                        /
    #>                            /                        /
    #>                            /                        /
    #> ------   ------   ------   ----------------------   ----------------------
    #>                            Sp_C                     Sp_E
    #>                            Sp_D                     Sp_F
    #> RDI      4        4        /                        /
    #>                            /                        /
    #>                            /                        /
    #> ------   ------   ------   ----------------------   ----------------------
    #>                            /                        /
    #>                            /                        /
    #> AD       0        0        /                        /
    #>                            /                        /
    #>                            /                        /
    #> ------   ------   ------   ----------------------   ----------------------
    #>                            /                        /
    #>                            /                        /
    #> AI       0        0        /                        /
    #>                            /                        /
    #>                            /                        /
    #> ------   ------   ------   ----------------------   ----------------------
    #> ADI      ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #> D        ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #> M        ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #>
    #> |-----------------------------------------------------------------------------------|
    #> |--------------------------------- CBCS diagnostic ---------------------------------|
    #> |-----------------------------------------------------------------------------------|
    #> > Lower_abundance: Important reference taxa which present lower abundances
    #> > Decrease: Mean decrease (vs reference) of the corresponding taxa
    #> > Relative_D: Relative mean decrease (vs reference) of the corresponding taxa (%)
    #> > Higher_abundance: Important reference taxa which present higher abundances
    #> > Increase: Mean increase (vs reference) of the corresponding taxa
    #> > Relative_I: Relative mean increase (vs reference) of the corresponding taxa (%)
    #>
    #>
    #> Sample   Lower_abundance          Decrease   Relative_D   Higher_abundance         Increase   Relative_I
    #> -------  -----------------------  ---------  -----------  -----------------------  ---------  -----------
    #>          Sp_L                     -36.1      -7           Sp_B                     2.5        5.3
    #>          Sp_H                     -16.8      -3.3         Sp_A                     20.9       4.2
    #> RD       Sp_G                     -5.5       -0.6         Sp_I                     16.3       1.6
    #>          /                        /          /            Sp_K                     10         1
    #>          /                        /          /            Sp_J                     4.2        0.8
    #> ------   ----------------------   ------     ------       ----------------------   ------     ------
    #>          Sp_L                     -28.9      -10.2        Sp_A                     34.1       6.9
    #>          Sp_I                     -17.3      -5.6         Sp_B                     2.9        6.2
    #> RI       Sp_H                     -11.6      -2.3         Sp_C                     26.3       5.7
    #>          Sp_D                     -5.4       -1.7         Sp_J                     2.6        0.5
    #>          /                        /          /            Sp_G                     3.3        0.3
    #> ------   ----------------------   ------     ------       ----------------------   ------     ------
    #>          Sp_L                     -15.5      -3           Sp_B                     1.7        3.6
    #>          Sp_H                     -10        -2           Sp_K                     21.2       2.1
    #> RDI      Sp_A                     -8.7       -1.8         Sp_I                     10.1       1
    #>          Sp_J                     -4.2       -0.8         Sp_G                     4.3        0.4
    #>          /                        /          /            /                        /          /
    #> ------   ----------------------   ------     ------       ----------------------   ------     ------
    #>          Sp_G                     -490.3     -50.6        Sp_C                     40.9       8.8
    #>          Sp_H                     -256.2     -49.5        Sp_B                     3.3        7
    #> AD       Sp_K                     -69.6      -16.5        Sp_A                     15.9       3.2
    #>          Sp_L                     -44.7      -8.6         /                        /          /
    #>          Sp_D                     -8.8       -7.1         /                        /          /
    #> ------   ----------------------   ------     ------       ----------------------   ------     ------
    #>          Sp_H                     -10.4      -8.3         Sp_J                     256.4      51.2
    #>          Sp_K                     -6.6       -2.1         Sp_I                     483.5      48.5
    #> AI       Sp_D                     -4.4       -0.7         Sp_B                     6.1        13
    #>          /                        /          /            Sp_C                     53.5       11.6
    #>          /                        /          /            Sp_L                     43.1       8.3
    #> ------   ----------------------   ------     ------       ----------------------   ------     ------
    #>          Sp_G                     -489.7     -50.8        Sp_I                     521.1      52.3
    #>          Sp_H                     -257.2     -49.5        Sp_J                     249        49.8
    #> ADI      Sp_A                     -10.3      -3           Sp_C                     52.5       11.3
    #>          Sp_K                     -4.4       -2.1         Sp_B                     2.9        6.2
    #>          Sp_D                     -1.6       -0.4         Sp_L                     6.1        1.2
    #> ------   ----------------------   ------     ------       ----------------------   ------     ------
    #>          Sp_A                     -11.1      -2.3         Sp_K                     5344.6     541.5
    #>          Sp_H                     -10.6      -2.1         Sp_L                     2216.7     428.8
    #> D        Sp_J                     -6.4       -1.9         Sp_B                     4.7        10
    #>          Sp_D                     -1         -1.3         Sp_C                     15.7       3.4
    #>          Sp_I                     -0.7       -0.1         Sp_G                     26.3       2.7
    #> ------   ----------------------   ------     ------       ----------------------   ------     ------
    #>          Sp_G                     -491.3     -50.5        Sp_K                     5292.6     536.2
    #>          Sp_H                     -256       -49.6        Sp_L                     2567.5     496.7
    #> M        /                        /          /            Sp_I                     532.5      53.5
    #>          /                        /          /            Sp_J                     249.4      49.8
    #>          /                        /          /            Sp_B                     4.9        10.4
    #> ------   ----------------------   ------     ------       ----------------------   ------     ------
    #>
    #> |-----------------------------------------------------------------------------------|
    #> |--------------------------------- SPI  diagnostic ---------------------------------|
    #> |-----------------------------------------------------------------------------------|
    #> > Dominant_species: most abundant species (corrected by reference)
    #> > Contribution: Taxa contribution (%) to total abundance (corrected by reference)
    #>
    #>
    #> Table: SPI diagnostic
    #>
    #> Sample   Dominant_species         Contribution
    #> -------  -----------------------  -------------
    #>          Sp_K                     52.9
    #>          Sp_A                     21.9
    #> RD       Sp_I                     15.6
    #>          Sp_J                     3.7
    #>          Sp_B                     3.7
    #> ------   ----------------------   ------
    #>          Sp_E                     73.5
    #>          Sp_F                     7.4
    #> RI       Sp_K                     6.4
    #>          Sp_A                     5.6
    #>          Sp_C                     4.1
    #> ------   ----------------------   ------
    #> RDI      ns                       ns
    #> ------   ----------------------   ------
    #>          Sp_C                     50.9
    #>          Sp_A                     31.3
    #> AD       Sp_I                     5.9
    #>          Sp_J                     5.9
    #>          Sp_B                     3.6
    #> ------   ----------------------   ------
    #> AI       ns                       ns
    #> ------   ----------------------   ------
    #> ADI      ns                       ns
    #> ------   ----------------------   ------
    #>          Sp_K                     69.9
    #>          Sp_L                     29
    #> D        Sp_G                     0.3
    #>          Sp_C                     0.2
    #>          Sp_A                     0.2
    #> ------   ----------------------   ------
    #>          Sp_K                     57.2
    #>          Sp_L                     27.8
    #> M        Sp_I                     5.8
    #>          Sp_E                     5.4
    #>          Sp_J                     2.7
    #> ------   ----------------------   ------