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. (2025). This index is designed to evaluate community recovery in marine ecosystems by combining three complementary sub-indices:

- Corrected Shared Richness (CSR): community richness changes (taxa loss or gain)
- Corrected Bray Curtis Distance: community structure changes (decrease or increase in abundance)
- Corrected Pielou Index: 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 (CSR, CBCD and CPI).
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

The package comes with a simulated dataset (`Simulated_data`) designed to illustrate different ecological impact scenarios.

    # Install from CRAN
    # install.packages("mumarinex") # run the first time only
    # Load the package
    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 41 to 50. 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
    #> R1.1   51   11    0    0    0    0   39   10   56   10   56   10
    #> R1.2   46    8    0    0    0    0   49   11   55   10   54    8
    #> R1.3   55   10    0    0    0    0   45    9   48    8   57    9
    #> R1.4   44   11    0    0    0    0   50   11   49   11   53    9
    #> R1.5   47    7    0    0    0    0   51   11   51   10   45    9
    #> R2.1   52   10   51    9   47    8   46    8   54   10   44    8

    # Definition of the reference position
    ref_idx <- 41:50 # row number of the reference samples

# Compute the MUMARINEX index and its sub-indices (CSR, CBCD and CPI)

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)

    # 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 maximum 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 (CSR, CBCD, CPI) across sample groups using boxplots.

    decomplot(x = Simulated_data, g = stations, ref = ref_idx, 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)
    #>
    #> |-----------------------------------------------------------------------------------|
    #> |--------------------------------- CSR  diagnostic ---------------------------------|
    #> |-----------------------------------------------------------------------------------|
    #> > Raw: Raw taxa difference between sample and reference pool
    #> > Mean: Mean taxa difference between sample and reference pool
    #> > Missing_species: Top 5 missing species (sorted by IndVal of the reference)
    #> > New_species: Top 5 new species (sorted by IndVal of the sample)
    #>
    #>
    #> Table: CSR diagnostic
    #>
    #> Sample   Raw      Mean     Missing_species          New_species
    #> -------  -------  -------  -----------------------  -----------------------
    #>                            Sp_C                     /
    #>                            Sp_D                     /
    #> R1       2        2        /                        /
    #>                            /                        /
    #>                            /                        /
    #> ------   ------   ------   ----------------------   ----------------------
    #>                            /                        Sp_E
    #>                            /                        Sp_F
    #> R2       0        0        /                        /
    #>                            /                        /
    #>                            /                        /
    #> ------   ------   ------   ----------------------   ----------------------
    #> R3       ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #> S1       ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #> S2       ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #> S3       ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #> D1       ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #> M1       ns       ns       ns                       ns
    #> ------   ------   ------   ----------------------   ----------------------
    #>
    #> |-----------------------------------------------------------------------------------|
    #> |--------------------------------- CBCD diagnostic ---------------------------------|
    #> |-----------------------------------------------------------------------------------|
    #> > Lower_abundance: Important reference taxa which present lower abundances
    #> > Decrease: 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
    #>
    #>
    #> Sample   Lower_abundance          Decrease   Higher_abundance         Increase
    #> -------  -----------------------  ---------  -----------------------  ---------
    #>          Sp_C                     -49.8      Sp_K                     3.4
    #>          Sp_D                     -9.3       Sp_I                     1.3
    #> R1       Sp_G                     -3.5       Sp_H                     0.6
    #>          Sp_B                     -0.8       /                        /
    #>          Sp_L                     -0.7       /                        /
    #> ------   ----------------------   ------     ----------------------   ------
    #>          Sp_K                     -4.4       Sp_E                     48
    #>          Sp_G                     -3.5       Sp_F                     8.6
    #> R2       Sp_C                     -1.8       Sp_A                     1.2
    #>          Sp_L                     -0.9       Sp_D                     0.3
    #>          Sp_H                     -0.8       /                        /
    #> ------   ----------------------   ------     ----------------------   ------
    #>          Sp_C                     -49.8      Sp_E                     47.6
    #>          Sp_D                     -9.3       Sp_F                     8.8
    #> R3       Sp_I                     -1.9       Sp_G                     1.1
    #>          Sp_B                     -1.4       Sp_A                     0.8
    #>          Sp_J                     -0.8       Sp_H                     0.6
    #> ------   ----------------------   ------     ----------------------   ------
    #>          Sp_G                     -45.9      Sp_A                     2.2
    #>          Sp_H                     -5.4       Sp_C                     0.6
    #> S1       Sp_K                     -4         Sp_D                     0.1
    #>          Sp_I                     -2.5       /                        /
    #>          Sp_B                     -1.2       /                        /
    #> ------   ----------------------   ------     ----------------------   ------
    #>          Sp_B                     -1.6       Sp_I                     188.7
    #>          Sp_L                     -0.3       Sp_J                     84.6
    #> S2       /                        /          Sp_A                     4.8
    #>          /                        /          Sp_C                     2.2
    #>          /                        /          Sp_G                     1.3
    #> ------   ----------------------   ------     ----------------------   ------
    #>          Sp_G                     -46.1      Sp_I                     193.5
    #>          Sp_H                     -5.2       Sp_J                     83
    #> S3       Sp_C                     -2         Sp_A                     5.8
    #>          Sp_K                     -1.2       /                        /
    #>          Sp_B                     -1         /                        /
    #> ------   ----------------------   ------     ----------------------   ------
    #>          Sp_A                     -3.8       Sp_K                     182.6
    #>          Sp_I                     -1.5       Sp_L                     91.9
    #> D1       Sp_J                     -1.4       Sp_C                     2.8
    #>          Sp_G                     -0.7       Sp_D                     0.9
    #>          Sp_H                     -0.6       /                        /
    #> ------   ----------------------   ------     ----------------------   ------
    #>          Sp_C                     -49.8      Sp_K                     196.2
    #>          Sp_G                     -46.3      Sp_L                     86.5
    #> M1       Sp_D                     -9.3       Sp_I                     49.1
    #>          Sp_H                     -5.6       Sp_E                     49
    #>          Sp_B                     -0.4       Sp_F                     9.4
    #> ------   ----------------------   ------     ----------------------   ------
    #>
    #> |-----------------------------------------------------------------------------------|
    #> |--------------------------------- CPI  diagnostic ---------------------------------|
    #> |-----------------------------------------------------------------------------------|
    #> > Dominant_species: most abundant species (corrected by reference)
    #> > Contribution: Taxa contribution (%) to total abundance (corrected by reference)
    #>
    #>
    #> Table: CPI diagnostic
    #>
    #> Sample   Dominant_species         Contribution
    #> -------  -----------------------  ------------------
    #>          Sp_K                     45.2830188679245
    #>          Sp_I                     22.0125786163522
    #> R1       Sp_A                     17.6100628930818
    #>          Sp_H                     7.96645702306079
    #>          Sp_B                     3.35429769392034
    #> ------   ----------------------   ------
    #> R2       ns                       ns
    #> ------   ----------------------   ------
    #> R3       ns                       ns
    #> ------   ----------------------   ------
    #>          Sp_C                     44.9579831932773
    #>          Sp_A                     28.9915966386555
    #> S1       Sp_K                     10.0840336134454
    #>          Sp_I                     7.35294117647059
    #>          Sp_D                     3.57142857142857
    #> ------   ----------------------   ------
    #>          Sp_I                     65.5344863513232
    #>          Sp_J                     29.3811210668889
    #> S2       Sp_A                     1.79204000833507
    #>          Sp_K                     1.08355907480725
    #>          Sp_C                     0.944641244703758
    #> ------   ----------------------   ------
    #>          Sp_I                     67.9615060410228
    #>          Sp_J                     29.1514470356842
    #> S3       Sp_A                     2.03708906996347
    #>          Sp_K                     0.590053385782523
    #>          Sp_D                     0.119415566170273
    #> ------   ----------------------   ------
    #>          Sp_K                     65.0192280301951
    #>          Sp_L                     32.7232587950434
    #> D1       Sp_C                     1.05398091439966
    #>          Sp_D                     0.36319612590799
    #>          Sp_I                     0.356074633243128
    #> ------   ----------------------   ------
    #>          Sp_K                     48.7914055505819
    #>          Sp_L                     21.5109917437581
    #> M1       Sp_I                     12.2102854869193
    #>          Sp_E                     12.1854172883716
    #>          Sp_F                     2.33761066348354
    #> ------   ----------------------   ------