Title:	Additive and Multiplicative Null Models for Multiple Stressor Data
Version:	0.1.1
Date:	2021-10-10
Description:	An implementation of the additive (Gurevitch et al., 2000 <doi:10.1086/303337>) and multiplicative (Lajeunesse, 2011 <doi:10.1890/11-0423.1>) factorial null models for multiple stressor data (Burgess et al., 2021 <doi:10.1101/2021.07.21.453207>). Effect sizes are able to be calculated for either null model, and subsequently classified into one of four different interaction classifications (e.g., antagonistic or synergistic interactions). Analyses can be conducted on data for single experiments through to large meta-analytical datasets. Minimal input (or statistical knowledge) is required, with any output easily understood. Summary figures are also able to be easily generated.
URL:	https://benjburgess.github.io/multiplestressR/
Imports:	ggplot2, patchwork, viridis
License:	GPL (≥ 3)
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.1.2
Depends:	R (≥ 2.10)
Suggests:	testthat (≥ 3.0.0), spelling
Config/testthat/edition:	3
Language:	en-US
NeedsCompilation:	no
Packaged:	2021-10-22 11:07:57 UTC; Burgess
Author:	Benjamin Burgess [aut, cre], David Murrell [aut]
Maintainer:	Benjamin Burgess <benjamin.joshua.burgess@gmail.com>
Repository:	CRAN
Date/Publication:	2021-10-26 07:30:02 UTC

Classify Interactions (for either null model)

Description

Using the output from either the effect_size_additive or effect_size_multiplicative functions, interactions can be assigned classifications (e.g., antagonisms or synergisms) based on the frameworks used by Burgess et al. (2021), or Jackson et al. (2016).

Usage

classify_interactions(
  effect_size_dataframe,
  assign_reversals,
  remove_directionality
)

Arguments

Value

The function returns a dataset containing i) the same results as from either the effect_size_additive or effect_size_multiplicative functions.

ii) the classification of any interactions (see below)

iii) if remove_directionality = TRUE; effect sizes, and confidence intervals will be adjusted (see below)

—

—

For ii), interactions are classified in the following method.

a) if the confidence intervals for any effect size overlap zero then the interaction is assigned a null classification.

This is analogous to the classification of additive which other studies (e.g., Jackson et al. (2016)) may use.

Note that this is given precedence over the process described in b).

—

b) if the confidence intervals for any effect size do not overlap zero then Expected and Observed effects are calculated.

Where the additive null model has been used:

Expected = X_a + X_b - 2 * X_c

Observed = X_i - X_c

Where the multiplicative null model has been used:

Expected = ln(X_a) + ln(X_b) - 2 * ln(X_c)

Observed = ln(X_i) - ln(X_c)

Here X_c, X_a, X_b, and X_i correspond to the means of the control, stressor A, stressor B, and stressors A and B treatments respectively.

—

A synergistic classification is assigned where:

an effect size is positive and Expected is greater than zero.

or

an effect size is negative and Expected is less than zero.

—

An antagonistic classification is assigned where:

an effect size is negative and both Expected and Observed are greater than zero.

or

an effect size is positive and both Expected and Observed are less than zero.

—

A reversal classification is assigned where:

an effect size is negative and Expected is greater than zero but Observed is less than zero.

or

an effect size is positive and Expected is less than zero but Observed is greater than zero.

If assign_reversals = FALSE, then where a reversal would be assigned using the above method, it is simply assigned an antagonistic classification instead.

—

—

If remove_directionality = TRUE, then the following method is implemented.

Where an interaction has an Expected value <0, the corresponding effect size for this interaction has its polarity changed (i.e., ES = -ES).

Confidence intervals for these altered effect sizes are likewise updated.

The remove of directionality is only likely to be of concern for meta-analyses.

References

Burgess, B. J., Purves, D., Mace, G., & Murrell, D. J. (2021). Classifying ecosystem stressor interactions: Theory highlights the data limitations of the additive null model and the difficulty in revealing ecological surprises. Global Change Biology.

Jackson, M. C., Loewen, C. J., Vinebrooke, R. D., & Chimimba, C. T. (2016). Net effects of multiple stressors in freshwater ecosystems: a meta-analysis. Global Change Biology, 22(1), 180-189.

Examples

#loading up an example dataset from the multiplestressR package
df <- multiplestressR::survival

#calculating effect sizes
df <- effect_size_additive(Control_N         = df$Sample_Size_Control,
                           Control_SD        = df$Standard_Deviation_Control,
                           Control_Mean      = df$Mean_Control,
                           StressorA_N       = df$Sample_Size_Temperature,
                           StressorA_SD      = df$Standard_Deviation_Temperature,
                           StressorA_Mean    = df$Mean_Temperature,
                           StressorB_N       = df$Sample_Size_pH,
                           StressorB_SD      = df$Standard_Deviation_pH,
                           StressorB_Mean    = df$Mean_pH,
                           StressorsAB_N     = df$Sample_Size_Temperature_pH,
                           StressorsAB_SD    = df$Standard_Deviation_Temperature_pH,
                           StressorsAB_Mean  = df$Mean_Temperature_pH,
                           Significance_Level = 0.05);

#classifying interactions
df <- classify_interactions(effect_size_dataframe = df,
                   assign_reversals = TRUE,
                   remove_directionality = TRUE)

Critical Effect Sizes (for the additive null model)

Description

The critical effect size for a given experimental design (i.e., number of replicates per treatment).

Usage

critical_effect_size_additive(
  Control_N,
  StressorA_N,
  StressorB_N,
  StressorsAB_N,
  Small_Sample_Correction,
  Significance_Level
)

Arguments

Details

The critical effect size represents the minimum effect size required for a significant result to be returned (see Burgess et al. (2021)).

For the additive null model, the critical effect size is directly related to treatment sample sizes.

Value

The function returns the critical effect size (for the additive null model; see effect_size_additive) for a given experimental design.

References

Burgess, B. J., Jackson, M. C., & Murrell, D. J. (2021). Multiple stressor null models frequently fail to detect most interactions due to low statistical power. bioRxiv.

Examples

critical_effect_size_additive(Control_N     = 4,
                             StressorA_N   = 4,
                             StressorB_N   = 4,
                             StressorsAB_N = 4)

critical_effect_size_additive(Control_N     = 3,
                             StressorA_N   = 3,
                             StressorB_N   = 3,
                             StressorsAB_N = 3,
                             Small_Sample_Correction = FALSE,
                             Significance_Level = 0.10)

Additive Null Model

Description

Calculate the additive null model for one, or more, experiments.

Usage

effect_size_additive(
  Control_N,
  Control_SD,
  Control_Mean,
  StressorA_N,
  StressorA_SD,
  StressorA_Mean,
  StressorB_N,
  StressorB_SD,
  StressorB_Mean,
  StressorsAB_N,
  StressorsAB_SD,
  StressorsAB_Mean,
  Small_Sample_Correction,
  Significance_Level
)

Arguments

Details

The form of the additive null model used here is taken from Gurevitch et al. (2000).

Interaction effect sizes, variances, and confidence intervals are calculated.

Here, the factorial form of Hedges' d is calculated.

Value

The function returns a dataframe containing

i. effect sizes

ii. effect size variances

iii. upper and lower confidence intervals

iv. user specified numeric parameters

The equations used to calculate effect sizes, effect size variances, and confidence intervals are described in Burgess et al. (2021).

Note that the parameter Small_Sample_Correction determines whether the correction for sample sizes is to be used within the function. This correction (see Borenstein et al. (2009)) tends towards 1 as sample sizes increase. Hence it is most applicable where small sample sizes are used.

References

Borenstein, M., Cooper, H., Hedges, L., & Valentine, J. (2009). Effect sizes for continuous data. The Handbook of Research Synthesis and Meta-Analysis, 2, 221-235.

Burgess, B. J., Jackson, M. C., & Murrell, D. J. (2021). Multiple stressor null models frequently fail to detect most interactions due to low statistical power. bioRxiv.

Gurevitch, J., Morrison, J. A., & Hedges, L. V. (2000). The interaction between competition and predation: a meta-analysis of field experiments. The American Naturalist, 155(4), 435-453.

Examples

df <- effect_size_additive(Control_N = 4,
                    Control_SD = 0.114,
                    Control_Mean = 0.90,
                    StressorA_N = 4,
                    StressorA_SD = 0.11,
                    StressorA_Mean = 0.77,
                    StressorB_N = 3,
                    StressorB_SD = 0.143,
                    StressorB_Mean = 0.72,
                    StressorsAB_N = 4,
                    StressorsAB_SD = 0.088,
                    StressorsAB_Mean = 0.55,
                    Small_Sample_Correction = TRUE,
                    Significance_Level = 0.05)

#loading up an example dataset from the multiplestressR package
df <- multiplestressR::survival

#calculating effect sizes
df <- effect_size_additive(Control_N         = df$Sample_Size_Control,
                           Control_SD        = df$Standard_Deviation_Control,
                           Control_Mean      = df$Mean_Control,
                           StressorA_N       = df$Sample_Size_Temperature,
                           StressorA_SD      = df$Standard_Deviation_Temperature,
                           StressorA_Mean    = df$Mean_Temperature,
                           StressorB_N       = df$Sample_Size_pH,
                           StressorB_SD      = df$Standard_Deviation_pH,
                           StressorB_Mean    = df$Mean_pH,
                           StressorsAB_N     = df$Sample_Size_Temperature_pH,
                           StressorsAB_SD    = df$Standard_Deviation_Temperature_pH,
                           StressorsAB_Mean  = df$Mean_Temperature_pH,
                           Significance_Level = 0.05);

Multiplicative Null Model

Description

Calculate the multiplicative null model for one, or more, experiments.

Usage

effect_size_multiplicative(
  Control_N,
  Control_SD,
  Control_Mean,
  StressorA_N,
  StressorA_SD,
  StressorA_Mean,
  StressorB_N,
  StressorB_SD,
  StressorB_Mean,
  StressorsAB_N,
  StressorsAB_SD,
  StressorsAB_Mean,
  Significance_Level
)

Arguments

Details

The form of the multiplicative null model used here is taken from Lajeunesse (2011).

Interaction effect sizes, variances, and confidence intervals are calculated.

Here, the factorial form of the response ratio is calculated.

Value

The function returns a dataframe containing

i. effect sizes

ii. effect size variances

iii. upper and lower confidence intervals

iv. user specified numeric parameters

The equations used to calculate effect sizes, effect size variances, and confidence intervals are described in Burgess et al. (2021).

References

Burgess, B. J., Jackson, M. C., & Murrell, D. J. (2021). Multiple stressor null models frequently fail to detect most interactions due to low statistical power. bioRxiv.

Lajeunesse, M. J. (2011). On the meta-analysis of response ratios for studies with correlated and multi-group designs. Ecology, 92(11), 2049-2055.

Examples

effect_size_multiplicative(Control_N = 4,
                          Control_SD = 0.114,
                          Control_Mean = 0.90,
                          StressorA_N = 4,
                          StressorA_SD = 0.11,
                          StressorA_Mean = 0.77,
                          StressorB_N = 3,
                          StressorB_SD = 0.143,
                          StressorB_Mean = 0.72,
                          StressorsAB_N = 4,
                          StressorsAB_SD = 0.088,
                          StressorsAB_Mean = 0.55,
                          Significance_Level = 0.05)

#loading up an example dataset from the multiplestressR package
df <- multiplestressR::survival

#calculating effect sizes
df <- effect_size_multiplicative(Control_N         = df$Sample_Size_Control,
                                Control_SD        = df$Standard_Deviation_Control,
                                Control_Mean      = df$Mean_Control,
                                StressorA_N       = df$Sample_Size_Temperature,
                                StressorA_SD      = df$Standard_Deviation_Temperature,
                                StressorA_Mean    = df$Mean_Temperature,
                                StressorB_N       = df$Sample_Size_pH,
                                StressorB_SD      = df$Standard_Deviation_pH,
                                StressorB_Mean    = df$Mean_pH,
                                StressorsAB_N     = df$Sample_Size_Temperature_pH,
                                StressorsAB_SD    = df$Standard_Deviation_Temperature_pH,
                                StressorsAB_Mean  = df$Mean_Temperature_pH,
                                Significance_Level = 0.05);

#classifying interactions
df <- classify_interactions(effect_size_dataframe = df,
                   assign_reversals = TRUE,
                   remove_directionality = TRUE)

Generate Summary Figures

Description

Using the output from classify_interactions function, summary figures can be created using this function.

Usage

summary_plots(
  effect_size_dataframe,
  Small_Sample_Correction,
  Significance_Level
)

Arguments

Details

The figures include:

a) The proportions of the different interaction classifications from the dataset

b) Median sample sizes plotted against effect size (different interaction classifications are highlighted). Where the additive null model was used in the analysis, lines for critical effect sizes are plotted (see critical_effect_size_additive function).

c) Density of different median sample sizes.

d) Inverse of effect size variance plotted against effect size (i.e., one iteration of a funnel plot).

e) Effect size standard error (i.e., the square root of the effect size variance) plotted against effect size (i.e., one iteration of a funnel plot)).

Note that c - e) are most useful for researchers conducting a meta-analysis.

Value

The function returns a series of figures each of which is outlined above.

Examples

#loading up an example dataset from the multiplestressR package
df <- multiplestressR::survival

#calculating effect sizes
df <- effect_size_additive(Control_N         = df$Sample_Size_Control,
                           Control_SD        = df$Standard_Deviation_Control,
                           Control_Mean      = df$Mean_Control,
                           StressorA_N       = df$Sample_Size_Temperature,
                           StressorA_SD      = df$Standard_Deviation_Temperature,
                           StressorA_Mean    = df$Mean_Temperature,
                           StressorB_N       = df$Sample_Size_pH,
                           StressorB_SD      = df$Standard_Deviation_pH,
                           StressorB_Mean    = df$Mean_pH,
                           StressorsAB_N     = df$Sample_Size_Temperature_pH,
                           StressorsAB_SD    = df$Standard_Deviation_Temperature_pH,
                           StressorsAB_Mean  = df$Mean_Temperature_pH,
                           Significance_Level = 0.05);

#classifying interactions
df <- classify_interactions(effect_size_dataframe = df,
                   assign_reversals = TRUE,
                   remove_directionality = TRUE);

#generate summary plots
df_plots <- summary_plots(effect_size_dataframe = df,
                   Significance_Level = 0.05)

Survival data for 250 populations exposed to the stressors of temperature and pH.

Description

A generated dataset on the survival rates of 250 populations (each composed of 100 individuals) exposed to the stressors of temperature and pH. The dataset uses a factorial design comprising four treatments: i) Control conditions; ii) Exposed to temperature; iii) Exposed to pH; iv) Exposed to both temperature and pH. This generated dataset is used in the examples for each function in the multiplestressR package. Please note that this is a generated dataset and does not reflect data from actual ecological experiments.

Usage

survival

Format

A data frame with 250 rows and 12 variables:

Sample_Size_Control

Number of samples for the control treatment

Standard_Deviation_Control

standard deviation for mean survival of the control treatment

Mean_Control

mean survival (as a proportion) for the control treatment

Sample_Size_Temperature

Number of samples for the temperature treatment

Standard_Deviation_Temperature

standard deviation for mean survival of the temperature treatment

Mean_Temperature

mean survival (as a proportion) for the temperature treatment

Sample_Size_pH

Number of samples for the pH treatment

Standard_Deviation_pH

standard deviation for mean survival of the pH treatment

Mean_pH

mean survival (as a proportion) for the pH treatment

Sample_Size_Temperature_pH

Number of samples for the combined temperature and pH treatment

Standard_Deviation_Temperature_pH

standard deviation for mean survival of the combined temperature and pH treatment

Mean_Temperature_pH

mean survival (as a proportion) for the combined temperature and pH treatment