,
David Murrell [aut]| Title: | Additive and Multiplicative Null Models for Multiple Stressor Data |
|---|---|
| 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. |
| Authors: | Benjamin Burgess [aut, cre] ,
David Murrell [aut] |
| Maintainer: | Benjamin Burgess <[email protected]> |
| License: | GPL (>= 3) |
| Version: | 0.1.1 |
| Built: | 2024-11-16 04:34:50 UTC |
| Source: | https://github.com/benjburgess/multiplestressr |
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).
classify_interactions( effect_size_dataframe, assign_reversals, remove_directionality )classify_interactions( effect_size_dataframe, assign_reversals, remove_directionality )
effect_size_dataframe |
Output from either the |
assign_reversals |
Specify whether reversals should be distinguished from antagonisms (see Jackson et al. (2016) (TRUE or FALSE; default = TRUE) |
remove_directionality |
Specify whether directionality should be removed from the effect sizes. This is most pertinent where subsequent analyses will involve conducting a formal meta-analysis (set value to TRUE). (TRUE or FALSE; default = FALSE) |
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:
Where the multiplicative null model has been used:
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.
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.
#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)#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)
The critical effect size for a given experimental design (i.e., number of replicates per treatment).
critical_effect_size_additive( Control_N, StressorA_N, StressorB_N, StressorsAB_N, Small_Sample_Correction, Significance_Level )critical_effect_size_additive( Control_N, StressorA_N, StressorB_N, StressorsAB_N, Small_Sample_Correction, Significance_Level )
Control_N |
Sample size of the control treatment (numeric) |
StressorA_N |
Sample size of stressor A treatment (numeric) |
StressorB_N |
Sample size of stressor B treatment (numeric) |
StressorsAB_N |
Sample size of stressors A and B treatment (numeric) |
Small_Sample_Correction |
Whether the correction for small sample sizes should be enacted (TRUE or FALSE; default is TRUE) |
Significance_Level |
The value of alpha for which confidence intervals are calculated (numeric, between 0 and 1; default is 0.05) |
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.
The function returns the critical effect size (for the additive null model; see effect_size_additive)
for a given experimental design.
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.
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)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)
Calculate the additive null model for one, or more, experiments.
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 )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 )
Control_N |
Sample size of the control treatment (numeric) |
Control_SD |
Standard deviation of the control treatment (numeric) |
Control_Mean |
Mean value of the control treatment (numeric) |
StressorA_N |
Sample size of stressor A treatment (numeric) |
StressorA_SD |
Standard deviation of stressor A treatment (numeric) |
StressorA_Mean |
Mean value of stressor A treatment (numeric) |
StressorB_N |
Sample size of stressor B treatment (numeric) |
StressorB_SD |
Standard deviation of stressor B treatment (numeric) |
StressorB_Mean |
Mean value of stressor B treatment (numeric) |
StressorsAB_N |
Sample size of stressors A and B treatment (numeric) |
StressorsAB_SD |
Standard deviation of stressors A and B treatment (numeric) |
StressorsAB_Mean |
Mean value of stressors A and B treatment (numeric) |
Small_Sample_Correction |
Whether the correction for small sample sizes should be enacted (TRUE or FALSE; default is TRUE) |
Significance_Level |
The value of alpha for which confidence intervals are calculated (numeric, between 0 and 1; default is 0.05) |
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.
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.
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.
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);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);
Calculate the multiplicative null model for one, or more, experiments.
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 )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 )
Control_N |
Sample size of the control treatment (numeric) |
Control_SD |
Standard deviation of the control treatment (numeric) |
Control_Mean |
Mean value of the control treatment (numeric) |
StressorA_N |
Sample size of stressor A treatment (numeric) |
StressorA_SD |
Standard deviation of stressor A treatment (numeric) |
StressorA_Mean |
Mean value of stressor A treatment (numeric) |
StressorB_N |
Sample size of stressor B treatment (numeric) |
StressorB_SD |
Standard deviation of stressor B treatment (numeric) |
StressorB_Mean |
Mean value of stressor B treatment (numeric) |
StressorsAB_N |
Sample size of stressors A and B treatment (numeric) |
StressorsAB_SD |
Standard deviation of stressors A and B treatment (numeric) |
StressorsAB_Mean |
Mean value of stressors A and B treatment (numeric) |
Significance_Level |
The value of alpha for which confidence intervals are calculated (numeric, between 0 and 1; default is 0.05) |
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.
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).
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.
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)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)
Using the output from classify_interactions function, summary figures can be created using this function.
summary_plots( effect_size_dataframe, Small_Sample_Correction, Significance_Level )summary_plots( effect_size_dataframe, Small_Sample_Correction, Significance_Level )
effect_size_dataframe |
Output from the |
Small_Sample_Correction |
Whether the correction for small sample sizes should be enacted
(TRUE or FALSE; default is TRUE) Note that if the multiplicative null model (see |
Significance_Level |
The value of alpha for which confidence intervals are calculated
(numeric, between 0 and 1; default is 0.05) Note that if the multiplicative null model (see |
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.
The function returns a series of figures each of which is outlined above.
#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)#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)
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.
survivalsurvival
A data frame with 250 rows and 12 variables:
Number of samples for the control treatment
standard deviation for mean survival of the control treatment
mean survival (as a proportion) for the control treatment
Number of samples for the temperature treatment
standard deviation for mean survival of the temperature treatment
mean survival (as a proportion) for the temperature treatment
Number of samples for the pH treatment
standard deviation for mean survival of the pH treatment
mean survival (as a proportion) for the pH treatment
Number of samples for the combined temperature and pH treatment
standard deviation for mean survival of the combined temperature and pH treatment
mean survival (as a proportion) for the combined temperature and pH treatment