Package 'msaFACE' reference manual

Title:	Moving Subset Analysis FACE
Description:	The new methodology "moving subset analysis" provides functions to investigate the effect of environmental conditions on the CO2 fertilization effect within longterm free air carbon enrichment (FACE) experiments. In general, the functionality is applicable to derive the influence of a third variable (forcing experiment-support variable) on the relation between a dependent and an independent variable.
Authors:	Wolfgang A. Obermeier [cre, aut], Lukas W. Lehnert [cre, aut], Joerg Bendix [aut]
Maintainer:	Lukas W. Lehnert <[email protected]>
License:	GPL
Version:	0.1.0
Built:	2025-03-08 02:43:41 UTC
Source:	https://github.com/cran/msaFACE

Moving Subset Analysis GiFACE

Description

The package msaFACE provides a new methodology called "moving subset analysis" to investigate the effect of environmental conditions on the CO2 fertilization effect within longterm free air carbon enrichment experiments. More generally, the functionality is applicable to derive the influence of a third variable (forcing experiment-support variable) on the relation between a dependent and an independent variable.

Details

The main part of the package is the function moving_subset_analysis which derives the CO2-fertilization effect (CFE) and relates it to the variable environmental conditions. The CFE is calculated by the regression between a dependent variable such as total aboveground biomass and the CO2 concentration in the air. Please note that the value of the function moving_subset_analysis is of class 'MSA_coef' for which several methods are available to plot and print the results.

Each experiment-support variable can be used as forcing variable, for which the influence on the CFE is analyzed through the following steps:

In the first step, the dataset is rearranged in ascending order of the forcing experiment-support variable. The total dataset is then partitioned into subsets where each contains observations featuring similar environmental characteristics. Taking the rainfall as an example, the first subset will encompass the driest years. For the second one, the year with the lowest rainfall sum is dropped and replaced by the year with the next lowest rainfall sum. This is repeated until the last subset is reached which encompasses the wettest years. For the GiFACE dataset with 16 years (1998-2013) of available data, 12 subsets are created for a window size of 30 observations (each subset encompassing six rings and five years).
The CFE is then derived as the slope of the regression model between the CO2 concentration of the air and the selected dependent variable, which is calculated separately within each of the subsets defined above.
By presenting the slope and its significance against the average of the forcing experiment-support variable in the subset, the influence of the respective variable on the CFE is revealed. However, situated in natural environments, most of the experiment-support variables will be highly correlated and, thus, the influence of the forcing variable has to be interpreted carefully. Therefore, the msaFACE contains the possibility to plot the averages of the accompanying experiment-support variables in the subsets, enabling a comprehensive picture of the prevailing environmental conditions. All this can easily be achieved by the function plot.MSA_coef.

To see the preferable citation of the package, type citation("msaFACE").

Author(s)

Wolfgang A. Obermeier, Lukas W. Lehnert, Joerg Bendix

References

W. A. Obermeier, L. W. Lehnert, C. I. Kammann, C. Mueller, L. Gruenhage, J. Luterbacher, M. Erbs, G. Moser, R. Seibert, N. Yuan, J. Bendix (under review) Reduced CO2 fertilization in temperate C3 grasslands under more extreme weather conditions. Nature Climate Change

Longterm time series of a Free Air Carbon Enrichment experiment (FACE)

Description

The dataset contains aggregated data from one of the globally longest time series (1998-2013) from a Free Air Carbon Enrichment experiment, settled in Giessen, Germany (GiFACE).

Usage

data(GiFACE)
data(GiFACE)

Format

list

Details

Within the experiment, a permanent temperate grassland is treated with elevated CO2 (~20% during daylight hours). In three rings the air is enriched with CO2 (-> elevated) while other three rings act under atmospheric CO2 (-> ambient). The late-summer yields as well as the CO2 concentrations (averaged in the three months before harvest) were measured ring-wise and can be used as dependent and independent variables within the Moving Subset Analysis. Experiment-support variables describing the environmental conditions were aggregated to their average in the three months preceding harvest (respectively sum for solar radiation and precipitation). These environmental variables can be used (1) as forcing variables to derive the subsets (where regression within the moving subset is performed) and (2) be plotted as accompanying variables to get a clear picture of the environmental conditions within the respective subset.

Author(s)

Wolfgang A. Obermeier, Lukas W. Lehnert, Joerg Bendix

References

Examples

## Not run: 
## Workaround to import the data from the DOI (10.5678\LCRS\DAT.265)

## Load data from http://dx.doi.org/10.5678/LCRS/DAT.265 and extract csv-file
## Define variable 'filename' so that it points to the csv-file
filename <- ""

## Import data
import <- read.csv(filename,
                   stringsAsFactors = FALSE)

## Delete every second column (quality flag of database)
data <- import[,seq(1, ncol(import), 2)]

## Create a vector containing the years of data acquistion 
year_vec <- substr(data[,1],1,4)

## Delete further unnecessary columns
data <- data[,-c(1,2,13)]

## Perform Moving Subset Analysis for all forcing experiment support variables (default) with
## independent variable CO2 Concentration (CO2), dependent variable biomass (BY_T), 30 observations
## within each subset and the years as grouping factor
MSA_GiFACE <- moving_subset_analysis(data, "CO2", "BY_T", 30, group =  year_vec)

## Show summary
summary(MSA_GiFACE)

## End(Not run)
## Not run: 
## Workaround to import the data from the DOI (10.5678\LCRS\DAT.265)

## Load data from http://dx.doi.org/10.5678/LCRS/DAT.265 and extract csv-file
## Define variable 'filename' so that it points to the csv-file
filename <- ""

## Import data
import <- read.csv(filename,
                   stringsAsFactors = FALSE)

## Delete every second column (quality flag of database)
data <- import[,seq(1, ncol(import), 2)]

## Create a vector containing the years of data acquistion 
year_vec <- substr(data[,1],1,4)

## Delete further unnecessary columns
data <- data[,-c(1,2,13)]

## Perform Moving Subset Analysis for all forcing experiment support variables (default) with
## independent variable CO2 Concentration (CO2), dependent variable biomass (BY_T), 30 observations
## within each subset and the years as grouping factor
MSA_GiFACE <- moving_subset_analysis(data, "CO2", "BY_T", 30, group =  year_vec)

## Show summary
summary(MSA_GiFACE)

## End(Not run)

Moving subset analysis

Description

The moving subset analysis quantifies the influence of a third variable (forcing experiment-support variable) on the relation between a dependent and an independent variable.

Usage

moving_subset_analysis(x, treatment_var, response_var, window_size,
                       group = 1:nrow(x), ...)
moving_subset_analysis(x, treatment_var, response_var, window_size,
                       group = 1:nrow(x), ...)

Arguments

`x`	Matrix or dataframe with dependent, independent and any experiment-support variables
`treatment_var`	Name of treatment variable. All but treatment and response variable are defined as experiment-support variables.
`response_var`	Name of response variable
`window_size`	Number of observations within one subset. Must be a multiple of the number of observations within one group.
`group`	Group factor identifying independent observations. Note that the number of observations within each group must be identical.
`...`	Further arguments (currently ignored)

Details

The function derives the CO2-fertilization effect (CFE) and relates it to the variable environmental conditions. The CFE is calculated by the regression between a dependent variable such as total aboveground biomass and the CO2 concentration in the air. Please note the the value of the function moving_subset_analysis is of class 'MSA_coef' for which several methods are available to plot and print the results.

Each experiment-support variable can be used as forcing variable, for which the influence on the CFE is analyzed through the following steps:

In the first step, the dataset is rearranged in ascending order of the forcing experiment-support variable. The total dataset is then partitioned into subsets where each contains observations featuring similar environmental characteristics. Taking the rainfall as an example, the first subset will encompass the driest years. For the second one, the year with the lowest rainfall sum is dropped and replaced by the year with the next lowest rainfall sum. This is repeated until the last subset is reached which encompasses the wettest years. For the GiFACE dataset with 16 years (1998-2013) of available data, 12 subsets are created for a window size of 30 observations (each subset encompassing six rings and five years).
The CFE is then derived as the slope of the regression model between the CO2 concentration of the air and the selected dependent variable, which is calculated separately within each of the subsets defined above.
By presenting the slope and its significance against the average of the forcing experiment-support variable in the subset, the influence of the respective variable on the CFE is revealed. However, situated in natural environments, most of the experiment-support variables will be highly correlated and, thus, the influence of the forcing variable has to be interpreted carefully. Therefore, the msaFACE contains the possibility to plot the averages of the accompanying experiment-support variables in the subsets, enabling a comprehensive picture of the prevailing environmental conditions. All this can easily be achieved by the function plot.MSA_coef.

Value

Object of class MSA_coef. Internally stored as a list. This object contains one element for each experiment-support variable. Those elements are data.frames with the subset-wise outputs:

CFE: Slope of linear model in subset
Pval: Significance value of linear model in subset
Mean of the dependent variable in subset
MEAN_"i-th_exp_var": Mean of the i-th experiment-support variable in subset
...
Min_"i-th_var": Minimum of the forcing variable in subset
Max_"i-th_var": Maximum of the forcing variable in subset

Author(s)

Wolfgang A. Obermeier, Lukas W. Lehnert, Joerg Bendix

References

Examples

data(GiFACE)

msa_data <- moving_subset_analysis(GiFACE$data, "CO2A_Mean", "BYT", 30, group = GiFACE$year)

data(GiFACE)

msa_data <- moving_subset_analysis(GiFACE$data, "CO2A_Mean", "BYT", 30, group = GiFACE$year)

Plot function for moving subset analysis

Description

Create main or accompanying plot(s) of the moving subset analysis

Usage

## S3 method for class 'MSA_coef'
plot(x, i_var = 1:length(x), main_plot = TRUE, i_acc = 1, 
     axis.param = list(), label.param = list(), ...)
## S3 method for class 'MSA_coef'
plot(x, i_var = 1:length(x), main_plot = TRUE, i_acc = 1, 
     axis.param = list(), label.param = list(), ...)

Arguments

`x`	Object of class `MSA_coef`. Output of `moving_subset_analysis`.
`i_var`	Column number or name of the forcing variable used to define the subset which will be plotted. Default is to plot all available variables.
`main_plot`	Flag to determine whether to plot the main plot(s) (default) or the accompanying plot(s)
`i_acc`	If main_plot = FALSE, column number(s) of the experiment-support variable(s) to be plotted as accompanying variable(s)
`axis.param`	List containing the axis parameters (e.g. lty, col, tck). By default for main plots, first entry represents x-axis (forcing variable), second entry represents first y-axis (regression result), and third entry the second y-axis (dependent variable). See example section.
`label.param`	List containing the label parameters (e.g. line, cex). For order of the list refer to axis.param. See example section.
`...`	Parameters passed to generic plot function

Author(s)

Wolfgang A. Obermeier, Lukas W. Lehnert, Joerg Bendix

Examples

data(GiFACE)

### Perform Moving Subset Analysis
msa_data <- moving_subset_analysis(GiFACE$data, "CO2A_Mean", "BYT", 30, group = GiFACE$year)

## Plot all final plots
plot(msa_data)

## Not run: 
## Example to produce similar plots as in article
pdf("Plot_NCC_1.pdf", width = 15, height = 20)
par(mfcol = c(9,4), mar = c(4,4,1,4), las = 0)
for(i in 1:4){
  plot(msa_data, i_var = i, ylim = list(c(0,2.5), c(200,350)), 
       legend = i == 1)
  plot(msa_data, i_var = i, main_plot = F, i_acc = 1:8)
}
dev.off()

## End(Not run)

## Not run: 
## Example to adjust axis and label parameters
par(mar = c(3.2,3.5,1,3), mfrow = c(2,1))
## Plot default for comparison
plot(msa_data, i_var = 2)     

## Change default axis (all parameters are passed to internal function "axis")
## Define x-axis specifications
xaxt_spec  <- list(tck = -0.02, padj = -0.3, cex.axis = 1.5, lwd = 2)
## Define 1st y-axis specifications 
yaxt1_spec <- list(at = c(0,1,2), tck = -0.02, padj = 0.5, cex.axis = 1.5, lwd = 2)
## Define 2nd y-axis specifications 
yaxt2_spec <- list(tck = -0.02, padj = -0.3, col = "gray50", col.axis = "gray50",
                   cex.axis = 1.5, lwd = 2)

## Change default labeling (all parameters are passed to internal function "mtext")
## Define x-axis label specifications 
xlab_spec <- list(side = 1, line = 2, cex = 1.5)
## Define 1st y-axis label specifications
ylab1_spec <- list(side = 2, line = 2, cex = 1.5)
## Define 2nd y-axis label specifications 
ylab2_spec <- list(side = 4, line = 2, cex = 1.5, col = "gray50")
                   
                   
## Define variable to be plotted, y-axis limits
plot(msa_data, i_var = 2, ylim = list(c(0,2.5), c(200,350)),                                     
     axis.param = list(xaxt_spec, yaxt1_spec, yaxt2_spec),
     label.param = list(xlab_spec, ylab1_spec, ylab2_spec),
     ## Define line width for horizontal lines (1) and the dependent variable (2)
     lwd = c(1,2),       
     ## Define point symbol
     pch = 20)                                                                                   
dev.off()

## End(Not run)
data(GiFACE)

### Perform Moving Subset Analysis
msa_data <- moving_subset_analysis(GiFACE$data, "CO2A_Mean", "BYT", 30, group = GiFACE$year)

## Plot all final plots
plot(msa_data)

## Not run: 
## Example to produce similar plots as in article
pdf("Plot_NCC_1.pdf", width = 15, height = 20)
par(mfcol = c(9,4), mar = c(4,4,1,4), las = 0)
for(i in 1:4){
  plot(msa_data, i_var = i, ylim = list(c(0,2.5), c(200,350)), 
       legend = i == 1)
  plot(msa_data, i_var = i, main_plot = F, i_acc = 1:8)
}
dev.off()

## End(Not run)

## Not run: 
## Example to adjust axis and label parameters
par(mar = c(3.2,3.5,1,3), mfrow = c(2,1))
## Plot default for comparison
plot(msa_data, i_var = 2)     

## Change default axis (all parameters are passed to internal function "axis")
## Define x-axis specifications
xaxt_spec  <- list(tck = -0.02, padj = -0.3, cex.axis = 1.5, lwd = 2)
## Define 1st y-axis specifications 
yaxt1_spec <- list(at = c(0,1,2), tck = -0.02, padj = 0.5, cex.axis = 1.5, lwd = 2)
## Define 2nd y-axis specifications 
yaxt2_spec <- list(tck = -0.02, padj = -0.3, col = "gray50", col.axis = "gray50",
                   cex.axis = 1.5, lwd = 2)

## Change default labeling (all parameters are passed to internal function "mtext")
## Define x-axis label specifications 
xlab_spec <- list(side = 1, line = 2, cex = 1.5)
## Define 1st y-axis label specifications
ylab1_spec <- list(side = 2, line = 2, cex = 1.5)
## Define 2nd y-axis label specifications 
ylab2_spec <- list(side = 4, line = 2, cex = 1.5, col = "gray50")
                   
                   
## Define variable to be plotted, y-axis limits
plot(msa_data, i_var = 2, ylim = list(c(0,2.5), c(200,350)),                                     
     axis.param = list(xaxt_spec, yaxt1_spec, yaxt2_spec),
     label.param = list(xlab_spec, ylab1_spec, ylab2_spec),
     ## Define line width for horizontal lines (1) and the dependent variable (2)
     lwd = c(1,2),       
     ## Define point symbol
     pch = 20)                                                                                   
dev.off()

## End(Not run)

Print MSA_coef

Description

Print function for output of moving subset analysis

Usage

## S3 method for class 'MSA_coef'
print(x, ...)
## S3 method for class 'MSA_coef'
show(object, ...)
## S3 method for class 'MSA_coef'
print(x, ...)
## S3 method for class 'MSA_coef'
show(object, ...)

Arguments

`x`, `object`	List of class `MSA_coef`
`...`	Parameters passed to generic functions (currently ignored)

Details

This function prints the column numbers for each experiment-support variable

Author(s)

Wolfgang A. Obermeier, Lukas W. Lehnert, Joerg Bendix

Examples

data(GiFACE)

## Perform Moving Subset Analysis
msa_data <- moving_subset_analysis(GiFACE$data, "CO2A_Mean", "BYT", 30, group = GiFACE$year)

msa_data

data(GiFACE)

## Perform Moving Subset Analysis
msa_data <- moving_subset_analysis(GiFACE$data, "CO2A_Mean", "BYT", 30, group = GiFACE$year)

msa_data

Summary for MSA_coef

Description

Summary function for output of moving subset analysis

Usage

## S3 method for class 'MSA_coef'
summary(object, ...)
## S3 method for class 'MSA_coef'
summary(object, ...)

Arguments

`object`	List of class `MSA_coef`
`...`	Parameters passed to generic summary function

Details

Variable: Name of the forcing experiment-support variable
CFEmax: Maximum CO2 fertilization effect
CFEmin: Minimum CO2 fertilization effect
Cond_for_CFEmax: Forcing variable at maximum CO2 fertilization effect
Cond_for_CFEmin: Forcing variable at minimum CO2 fertilization effect
Dependent_Max: Maximum of dependent variable
Dependent_Min: Minimum of dependent variable

Author(s)

Wolfgang A. Obermeier, Lukas W. Lehnert, Joerg Bendix

Examples


## Load data
data(GiFACE)

## Perform Moving Subset Analysis
msa_data <- moving_subset_analysis(GiFACE$data, "CO2A_Mean", "BYT", 30, group = GiFACE$year)

## Show summary
summary(msa_data)
## Load data
data(GiFACE)

## Perform Moving Subset Analysis
msa_data <- moving_subset_analysis(GiFACE$data, "CO2A_Mean", "BYT", 30, group = GiFACE$year)

## Show summary
summary(msa_data)

Package 'msaFACE'

Help Index

Moving Subset Analysis GiFACE

Description

Details

Author(s)

References

See Also

Longterm time series of a Free Air Carbon Enrichment experiment (FACE)

Description

Usage

Format

Details

Author(s)

References

Examples

Moving subset analysis

Description

Usage

Arguments

Details

Value

Author(s)

References

See Also

Examples

Plot function for moving subset analysis

Description

Usage

Arguments

Author(s)

See Also

Examples

Print MSA_coef

Description

Usage

Arguments

Details

Author(s)

See Also

Examples

Summary for MSA_coef

Description

Usage

Arguments

Details

Author(s)

See Also

Examples