logR: Calculate logarithmic response ratio from a long table

In MikkoVihtakari/MarineDatabase: Export data to Norwegian Polar Institute's marine database

Description

Calculates logarithmic response ratio from a long table where each row represents one measurement.

Usage

logR(
  X,
  response,
  levels,
  groups,
  control,
  ci.type = NULL,
  ci.conf = 0.95,
  base = "e",
  paired_tests = FALSE,
  unlog = FALSE,
  all.data = FALSE,
  signif = 2,
  sqrt_transform = FALSE
)

Arguments

X	data frame
response	character vector specifying the names of the columns for which the response ratio should be calculated.
levels	Name of the column that contains factor which should be used to separate response ratios.
groups	character vector specifying the names of the columns, which should used as grouping factors.
control	the name of the control/base factor level in levels column.
ci.type	indicates the distribution to be used for confidence intervals. 'z' refers to normal distribution and 't' to t distribution. The default (NULL) is to decide the distribution based on the lowest √(n)*mean(response)/sd(response) (from Hedges et al. 1999). If over 10% of values are less than 3, t-distribution is used. Otherwise normal. Note that Hedges et al. (1999) adviced for using normal distribution and that the t-distribution is an experimental addition, but I have used it in publications. The CIs will be wider (i.e. less "significant" results) when t-distribution is used. Consider using paired_tests to confirm your CIs.
ci.conf	the confidence level for the confidence interval. Defaults to 0.95 (95%).
base	either "e" (default), 2 or 10 defining the base for the log response ratio. While "e" (i.e. ln) is the most used variant (see Hedges et al. 1999), 2 and 10 based logarithms are easier to read. Experimental. DO NOT USE in publications.
paired_tests	Logical indicating whether wilcox.test should be used to "confirm" the results indicated by the confidence intervals for the response ratios.
unlog	logical indicating whether the output should be unlogged. Defaults to FALSE. Read the page 1152 under eq. 9 and what follows on the next page from Hedges et al. (1999) before you switch this to TRUE in publications. The unlogging is done by simply exponentiating for confidence intervals, while the response ratio (mean) is calculated as \exp(LnR + var/2) after Greenacre (2016). Currently untested for response ratios.
all.data	logical indicating whether all data used in calculations should be returned instead of a concise table of relevant results. Defaults to FALSE.
signif	number of significant digits in output. Defaults to 2. If 'all' output will not be rounded.
sqrt_transform	Logical indicating whether values should be square root transformed prior calculation of means. This option makes the distributions more normally distributed, but might change the outcome. Highly experimental. DO NOT USE in publications.

Details

The calculations are based on Hedges et al. (1999), with the exception that t-distribution is used to acquire confidence intervals instead of normal distribution. The difference is minimal for sample sizes > 20, but the confidence intervals will be a lot more conservative for small sample sizes leading to fewer false positives. Use ci.type = "z" to use normal distribution for CI estimation as described in the original source.

Note that the function does not currently calculate dependent sample response ratios, as the pooled variance needs to be penalized by the correlation term for such analyses. See Lajeunesse (2011) and CrossValidated for further information.

The square root transformation routine is experimental and little tested, but seems to produce slightly less nonconforming test results against wilcox.test for non-normal data.

It is recommended to plot your raw values to confirm any results given by this function.

Value

Returns a list where $data element contains the calculated response ratios for each response in a separate list named by the response's column name. $info contains information how the response ratios were calculated and, if paired_tests = TRUE, the $tests element gives wilcox.test results to "confirm" significance of the confidence intervals for the response ratios. Nonconforming tests are listed under $nonconforming.

Author(s)

Mikko Vihtakari

References

Hedges, L. V, Gurevitch, J., & Curtis, P.S. (1999) The meta-analysis of response ratios in experimental ecology. Ecology, 80, 1150–1156.

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

Greenacre, M., (2016). Data reporting and visualization in ecology. Polar Biology 39, 2189–2205. doi:10.1007/s00300-016-2047-2

MikkoVihtakari/MarineDatabase documentation built on July 7, 2020, 2:16 a.m.