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:
- Install and load the package.
- Format data.
- Compute the MUMARINEX index and its sub-indices (CSR, CBCD and
CPI).
- Visualize sub-indices results with dedicated plotting
functions.
- 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)
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
#> ------ ---------------------- ------