time_vs_bench: Compare time data to a benchmark
In darrellpenta/uxstats: Common data analysis tools for UX researchers

Description Usage Arguments Details Value See Also Examples

View source: R/time_vs_benchmark-function.R

time_vs_bench() tests a sample mean of time data (e.g., ratings) against a given benchmark using a one-sample t-test.

time_vs_bench(.x, ...)

## S3 method for class 'numeric'
time_vs_bench(
  .x,
  .sd,
  .n,
  .m,
  ...,
  .alt = c("greater", "less", "twotailed"),
  .alpha = 0.05
)

## S3 method for class 'data.frame'
time_vs_bench(
  .x,
  .var,
  .m,
  ...,
  .alt = c("greater", "less", "twotailed"),
  .alpha = 0.05
)

`.x`	A single numeric value, a vector of values, or a long-format data frame with a named column of numeric data corresponding to time values. See Details.
`...`	(Optional) If `.x` is a long-format data frame, you can pass the name of one or more grouping variables as unquoted, comma-separated column names (without naming the `...` argument) to compute stats by groups.
`.sd`	If `.x` is a single numeric value, `.sd` should be a single numeric value indicating the standard deviation of the log-transformed sample means. See Details
`.n`	If `.x` is a single numeric value, `.n` should be a single numeric value indicating the sample size. See Details.
`.m`	The test (benchmark) mean.
`.alt`	(Optional) For test alternatives, one of `c("greater","less","twotailed")`. Defaults to "greater" for a one-sided test.
`.alpha`	(Optional) A positive number (where 0 < `.alpha` < 1) specifying the significance level to be used. Defaults to `.alpha = 0.05`. To set a different significance level, the argument must be named (i.e., `.alpha=0.001`) or else the function may yield unexpected results.
`.var`	If `.x` is a long-format data frame, the (unquoted) name of a data frame column containing task ratings (or values from another continuous metric).

Following Sauro and Lewis (2012),ratings_vs_bench log transforms the time data in calculations when .x is a vector or data frame of raw times.It also log-transforms the benchmark mean in all calculations. If you pass a single numeric value to .x as a mean of sample times, be sure to log transform the mean and provide the standard deviation of the log-transformed times to the .sd argument. ratings_vs_bench assumes that you want to test the hypothesis that the observed outcome does not exceed the benchmark, and therefore, defaults to a one-tailed test. This means that setting .alpha = 0.05 (the default) produces a 90% confidence interval.

If .x is a single numeric value representing the log-transformed sample mean, provide the standard deviation of the log-transformed times and sample size to .sd and .n, respectively.
If .x is a numeric vector of ratings values, you should only specify the test (benchmark) mean.
If .x is a data frame, .var should be the unquoted name of the column containing the time values.
If you're passing a data frame to .x, you can optionally pass one or more grouping variables as unquoted, comma-separated column names (without naming the ... argument) to compute stats by groups.
You can choose from among the test alternatives c("greater","less","twotailed") by providing one of the options to the .alt argument: e.g., .alt = "twotailed". Defaults to "greater" for a one-sided test.
You can modify the alpha level to adjust confidence intervals by including .alpha as a named argument and providing a numeric value: e.g., .aplha = 0.001.

Note that NAs are automatically dropped in all calculations.

A tibble with data summaries and test results

Other benchmark comparison stats: ratings_vs_bench(), success_vs_bench()

# When passing individual values, make sure the mean and sd are log-transformed
.sample_mean <- 45
.sample_sd <- 12
time_vs_bench(.x=log(.sample_mean), .sd=log(.sample_sd), .n=20, .m = 60,.alt="less")

# You can pass a vector of raw (untransformed) times to .x:
time_vs_bench(.x=c(350,255,400,343,330,420), .m=375, .alt="less", .alpha=0.10)


.ux_data <-
data.frame(
 "id" = rep(seq(1,10,1),2),
 "group" = rep(c("A","B"),10),
 "task" = c(rep(1,10),rep(2,10)),
 "time"  = runif(20,200,1000)
)

time_vs_bench(.ux_data, .var=time,.m=600,task,.alt="less", .alpha=0.05 )