visualise_effects_data {DImodelsVis} | R Documentation |
Prepare data for effects plots for compositional data
Description
The helper function to create the underlying data for visualising the effect
of increasing or decreasing (or both) the proportion of a variable from a
set of compositional variables. This is a special case of the
simplex_path
function where the end points are either the
monoculture (i.e. variable of interest = 1, while all others equal 0) of the
variable of interest (when increasing the proportion) or a community without
the variable of interest (when decreasing the proportion). The observations
specified in 'data' are connected to the respective communities (monoculture of
the variable of interest or the community without the variable of interest) by a
straight line across the simplex; This has the effect of changing the proportion of
the variable of interest whilst adjusting the proportion of the other variables
but keeping the ratio of their relative proportions unchanged, thereby preserving
the compositional nature of the data. See examples for more information.
The output of this function can be passed to the
visualise_effects_plot
function to visualise the results.
Usage
visualise_effects_data(
data,
prop,
var_interest = NULL,
effect = c("increase", "decrease", "both"),
add_var = list(),
prediction = TRUE,
...
)
Arguments
data |
A dataframe specifying the initial communities of interest for which to visualise the effect of increasing/decreasing a variable. If a model object is specified then this data should contain all the variables present in the model object including any additional variables not part of the simplex design. If a coefficient vector is specified then data should contain same number of columns as the number of elements in the coefficient vector and a one-to-one positional mapping would be assumed between the data columns and the elements of the coefficient vector. |
prop |
A vector of column names or indices identifying the columns containing the variable proportions (i.e., compositional columns) in the data. |
var_interest |
A character vector specifying the variable for which to visualise the effect of change on the response. If left blank, all variables would be assumed to be of interest. |
effect |
One of "increase", "decrease" or "both" to indicate whether to look at the effect of increasing the proportion, decreasing the proportion or doing both simultaneously, respectively on the response. The default in "increasing". |
add_var |
A list specifying values for additional variables in the model other than the proportions (i.e. not part of the simplex design). This would be useful to compare the predictions across different values for a categorical variable. One plot will be generated for each unique combination of values specified here. |
prediction |
A logical value indicating whether to pass the final data to
'add_prediction' and add predictions to the data.
Default value is |
... |
Arguments passed on to
|
Value
A data frame with the following columns appended at the end
- .Sp
An identifier column to discern the variable of interest being modified in each curve.
- .Proportion
The value of the variable of interest within the community.
- .Group
An identifier column to discern between the different curves.
- .add_str_ID
An identifier column for grouping the cartesian product of all additional columns specified in 'add_var' parameter (if 'add_var' is specified).
- .Pred
The predicted response for each observation.
- .Lower
The lower limit of the prediction/confidence interval for each observation.
- .Upper
The upper limit of the prediction/confidence interval for each observation.
- .Marginal
The marginal change in the response (first derivative) with respect to the gradual change in the proportion of the species of interest.
- .Threshold
A numeric value indicating the maximum proportion of the species of interest within a particular community which has a positive marginal effect on the response.
- .MarEffect
A character string entailing whether the increase/decrease of the species of interest from the particular community would result in a positive or negative marginal effect on the response.
- .Effect
An identifier column signifying whether considering the effect of species addition or species decrease.
Examples
library(DImodels)
## Load data
data(sim1)
## Fit model
mod <- glm(response ~ p1 + p2 + p3 + p4 + 0, data = sim1)
## Create data for visualising effect of increasing the proportion of
## variable p1 in data
## Notice how the proportion of `p1` increases while the proportion of
## the other variables decreases whilst maintaining their relative proportions
head(visualise_effects_data(data = sim1, prop = c("p1", "p2", "p3", "p4"),
var_interest = "p1", effect = "increase",
model = mod))
## Create data for visualising the effect of decreasing the proportion
## variable p1 in data using `effect = "decrease"`
head(visualise_effects_data(data = sim1, prop = c("p1", "p2", "p3", "p4"),
var_interest = "p1", effect = "decrease",
model = mod))
## Create data for visualising the effect of increasing and decreasing the
## proportion variable p3 in data using `effect = "both"`
head(visualise_effects_data(data = sim1, prop = c("p1", "p2", "p3", "p4"),
var_interest = "p3", effect = "decrease",
model = mod))
## Getting prediction intervals at a 99% confidence level
head(visualise_effects_data(data = sim1, prop = c("p1", "p2", "p3", "p4"),
var_interest = "p1", effect = "decrease",
model = mod, conf.level = 0.99,
interval = "prediction"))
## Adding additional variables to the data using `add_var`
## Notice the new .add_str_ID column in the output
sim1$block <- as.numeric(sim1$block)
new_mod <- update(mod, ~ . + block, data = sim1)
head(visualise_effects_data(data = sim1[, 3:6], prop = c("p1", "p2", "p3", "p4"),
var_interest = "p1", effect = "both",
model = new_mod,
add_var = list("block" = c(1, 2))))
## Create data for visualising effect of decreasing variable p2 from
## the original communities in the data but using model coefficients
## When specifying coefficients the data should have a one-to-one
## positional mapping with specified coefficients.
init_comms <- sim1[, c("p1", "p2", "p3", "p4")]
head(visualise_effects_data(data = init_comms, prop = 1:4,
var_interest = "p2",
effect = "decrease",
interval = "none",
coefficients = mod$coefficients))
## Note that to get confidence interval when specifying
## model coefficients we'd also need to provide a variance covariance
## matrix using the `vcov` argument
head(visualise_effects_data(data = init_comms, prop = 1:4,
var_interest = "p2",
effect = "decrease",
interval = "confidence",
coefficients = mod$coefficients,
vcov = vcov(mod)))
## Can also create only the intermediary communities without predictions
## by specifying prediction = FALSE.
## Any additional columns can then be added and the `add_prediction` function
## can be manually called.
## Note: If calling the `add_prediction` function manually, the data would
## not contain information about the marginal effect of changing the species
## interest
effects_data <- visualise_effects_data(data = init_comms, prop = 1:4,
var_interest = "p2",
effect = "decrease",
prediction = FALSE)
head(effects_data)
## Prediction using model object
head(add_prediction(data = effects_data, model = mod, interval = "prediction"))
## Prediction using regression coefficients
head(add_prediction(data = effects_data, coefficients = mod$coefficients))