Package 'scan'

Add Dummy Variables for Piecewise Linear Models

Description

Adds dummy variables to an scdf for calculating piecewise linear models.

Usage

add_dummy_variables(
  scdf,
  model = c("W", "H-M", "B&L-B"),
  contrast_level = c("first", "preceding"),
  contrast_slope = c("first", "preceding")
)

Arguments

scdf	A single-case data frame. See scdf() to learn about this format.
model	Model used for calculating the dummy parameters (see Huitema & McKean, 2000). Default is model = "W". Possible values are: "B&L-B", "H-M", "W", and deprecated "JW".
contrast_level	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.
contrast_slope	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.

Details

This function creates dummy variables for phase levels and phase slopes according to the specified piecewise regression model. It supports different contrast coding schemes for both level and slope contrasts.

Examples

add_dummy_variables(
 scdf = exampleABC, 
 model = "W", 
 contrast_level = "first", 
 contrast_slope = "first"
)

---

Add level-2 data to an scdf

Description

Merges variables with corresponding case names from a data.frame with an scdf.

Usage

add_l2(scdf, data_l2, cvar = "case")

Arguments

scdf	A single-case data frame. See scdf() to learn about this format.
data_l2	A level 2 dataset.
cvar	Character string with the name of the "case" variable in the L2 dataset (default is 'case').

Details

This function is mostly used in combination with the hplm() function. It adds level-2 variables to each single-case data frame in an scdf based on matching case names.

Value

An scdf with added level-2 variables.

Author(s)

Juergen Wilbert

See Also

hplm()

Other data manipulation functions: as.data.frame.scdf(), as_scdf(), batch_apply(), fill_missing(), moving_median(), print.sc_outlier(), ranks(), rescale(), scdf(), select_cases(), set_vars(), shift(), smooth_cases(), standardize(), truncate_phase()

Examples

## Example with the default case variable name 'case'
Leidig2018 |> add_l2(Leidig2018_l2)
## Example with a different case variable name in the L2 data
Leidig2018_l2_renamed <- Leidig2018_l2
names(Leidig2018_l2_renamed)[2] <- "subject"
Leidig2018 |> add_l2(Leidig2018_l2_renamed, cvar = "subject")

---

ANOVA Table for Piecewise Linear Models

Description

Model comparison for piecewise regression models fitted with plm(), hplm(), or mplm() using likelihood ratio tests.

Usage

## S3 method for class 'sc_plm'
anova(object, ...)

## S3 method for class 'sc_hplm'
anova(object, ...)

## S3 method for class 'sc_mplm'
anova(object, ...)

Arguments

object	An object containing the results returned by plm(), hplm(), or mplm().
...	additional objects for model comparison.

Details

The function performs likelihood ratio tests to compare nested piecewise regression models. It extracts the underlying model from the sc_plm, sc_hplm, or sc_mplm object and passes them to the generic anova() function for model comparison.

Value

An object of class anova containing the results of the model comparison.

Examples

## For glm models with family = "gaussian"
mod1 <- plm(exampleAB$Johanna, level = FALSE, slope = FALSE)
mod2 <- plm(exampleAB$Johanna)
anova(mod1, mod2)
## For glm models with family = "poisson"
mod0 <- plm(example_A24, formula = injuries ~ 1, family = "poisson")
mod1 <- plm(example_A24, trend = FALSE, family = "poisson")
anova(mod0, mod1, mod2)
## For glm with family = "binomial"
mod0 <- plm(
  exampleAB_score$Christiano, 
  formula = values ~ 1, 
  family = "binomial", 
  var_trials = "trials"
)
mod1 <- plm(
  exampleAB_score$Christiano, 
  trend = FALSE, 
  family = "binomial", 
  var_trials = "trials"
)
anova(mod0, mod1)
## For multilevel models:
mod0 <- hplm(Leidig2018, trend = FALSE, slope = FALSE, level = FALSE)
mod1 <- hplm(Leidig2018, trend = FALSE)
mod2 <- hplm(Leidig2018)
anova(mod0, mod1, mod2)
## For mplm
mod0 <- mplm(
  Leidig2018$`1a1`, 
  update = . ~  1, dvar = c("academic_engagement", "disruptive_behavior")
)
mod1 <- mplm(
  Leidig2018$`1a1`, 
  trend = FALSE, 
  dvar = c("academic_engagement", "disruptive_behavior")
)
mod2 <- mplm(
  Leidig2018$`1a1`, 
  dvar = c("academic_engagement", "disruptive_behavior")
)

anova(mod0, mod1, mod2)

---

as_scdf

Description

Converts a data frame to an scdf object.

Usage

as_scdf(
  object,
  cvar = "case",
  pvar = "phase",
  dvar = "values",
  mvar = "mt",
  phase_names = NULL,
  sort_cases = FALSE
)

Arguments

object	A data.frame
cvar	Sets the "case" variable. Defaults to case.
pvar	Sets the "phase" variable. Defaults to phase.
dvar	Sets the "values" variable. Defaults to values.
mvar	Sets the variable name of the "mt" variable. Defaults to mt.
phase_names	A character vector with phase names. Defaults to the phase names provided in the phase variable.
sort_cases	If set TRUE, the resulting list is sorted by label names (alphabetically increasing).

Value

An scdf.

See Also

Other data manipulation functions: add_l2(), as.data.frame.scdf(), batch_apply(), fill_missing(), moving_median(), print.sc_outlier(), ranks(), rescale(), scdf(), select_cases(), set_vars(), shift(), smooth_cases(), standardize(), truncate_phase()

---

Creating a long format data frame from several single-case data frames (scdf).

Description

The as.data.frame function transposes an scdf into one long data frame. Additionally, a data frame can be merged that includes level 2 data of the subjects. This might be helpful to prepare data to be used with other packages than scan.

Usage

## S3 method for class 'scdf'
as.data.frame(x, ..., l2 = NULL, id = "case")

Arguments

x	An scdf object.
...	Not implemented.
l2	A data frame providing additional variables at Level 2. The scdf has to have names for all cases and the Level 2 data frame has to have a column with corresponding case names.
id	Variable name of the Level 2 data frame that contains the case names. Defaults to "case".

Value

Returns one data frame with data of all single-cases structured by the case variable.

Author(s)

Juergen Wilbert

See Also

Other data manipulation functions: add_l2(), as_scdf(), batch_apply(), fill_missing(), moving_median(), print.sc_outlier(), ranks(), rescale(), scdf(), select_cases(), set_vars(), shift(), smooth_cases(), standardize(), truncate_phase()

Examples

## Convert the list of three single-case data frames from Grosche (2011)
### into one long data frame
Grosche2011
Grosche2011_long <- as.data.frame(Grosche2011)
Grosche2011_long

## Combine an scdf with data for l2
Leidig2018_long <- as.data.frame(Leidig2018, l2 = Leidig2018_l2)
names(Leidig2018_long)
summary(Leidig2018_long)

---

Apply a function to each element in an scdf.

Description

This function applies a given function to each case of a multiple case scdf, returning a list of the output of each function call.

Usage

batch_apply(scdf, fn, simplify = FALSE)

Arguments

scdf	A list of inputs to apply the function to.
fn	The function to apply to each element. Use a . as a placeholder for the scdf (e.g. describe(.)).
simplify	If simplify is TRUE and fn returns a vector of values, batch_apply will return a data frame case names.

Details

If simplify is TRUE and the function returns a vector of values, the output is combined into a data frame with case names as additional columns.

This is particularly useful for applying statistical models or summary statistics to each case in an scdf.

Value

A list of the output of each function call.

Author(s)

Juergen Wilbert

See Also

Other data manipulation functions: add_l2(), as.data.frame.scdf(), as_scdf(), fill_missing(), moving_median(), print.sc_outlier(), ranks(), rescale(), scdf(), select_cases(), set_vars(), shift(), smooth_cases(), standardize(), truncate_phase()

Examples

batch_apply(exampleAB, coef(plm(.)))

---

Between-Case Standardized Mean Difference

Description

Calculates a standardized mean difference from a multilevel model as described in Pustejovsky et al. (2014)

Usage

between_smd(
  data,
  method = c("REML", "MCMCglmm"),
  ci = 0.95,
  include_residuals = TRUE,
  ...
)

## S3 method for class 'sc_bcsmd'
print(x, digits = 2, ...)

## S3 method for class 'sc_bcsmd'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  digits = 2,
  round = 2,
  ...
)

Arguments

data	Either an scdf or an object returned from the hplm() or bplm() function.
method	Either "REML" or "⁠MCMglmm"⁠. This indicated which statistical method is applied to calculate the model.
ci	A numeric between 0 and 1 setting the width of the confidence interval (when method is REML) or the credible interval (when method is MCMCglmm). The default is 0.95 for a 95-percent interval.
include_residuals	Logical. See details.
...	Further arguments passed to the hplm() or bplm()function.
x	An object returned by baseline_smd().
digits	The minimum number of significant digits to be use. If set to "auto" (default), values are predefined.
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
round	Integer passed to the digits argument used to round values.

Details

The BC-SMD is calculate as ⁠BC-SMD = Phase difference / sqrt(residual + random_intercept)⁠. This is most closely related to Cohen's d. If you want to have the most exact estimation based on the between case variance, you have to exclude the residual variance by setting the argument include_residuals = FALSE you get ⁠BC-SMD = Phase difference / sqrt(random_intercept)⁠. The 'base' model only includes the phase level as a predictor like originally proposed by Hedges et al. Whereas the 'Full plm' model includes the trend and the phase slope as additional predictors.

Value

An object of class sc_bcsmd. It is a list containing the following elements:

• models: A list of data frames containing the BC-SMD results for each model calculated.

• ci: The width of the confidence/credible interval.

• method: The method used for model estimation.

Functions

• print(sc_bcsmd): Print results

• export(sc_bcsmd): export results

Author(s)

Juergen Wilbert

References

Pustejovsky, J. E., Hedges, L. V., & Shadish, W. R. (2014). Design-Comparable Effect Sizes in Multiple Baseline Designs: A General Modeling Framework. Journal of Educational and Behavioral Statistics, 39(5), 368–393. https://doi.org/10.3102/1076998614547577

Examples

## Create a example scdf:
des <- design(
  n = 150,
  phase_design = list(A1 = 10, B1 = 10, A2 = 10, B2 = 10, C = 10),
  level = list(B1 = 1, A2 = 0, B2 = 1, C = 1),
  rtt = 0.7,
  random_start_value = TRUE
)
study <- random_scdf(des)

## Standard BC-SMD return:
between_smd(study)

## Specify the model and provide an hplm object:
model <- hplm(study, contrast_level = "preceding", slope = FALSE,  trend = FALSE)
between_smd(model)

## excluding the residuals gives a more accurate estimation:
between_smd(model, include_residuals = FALSE)

---

Bayesian Piecewise Linear Model (bplm)

Description

Computes a bayesian (hierarchical) piecewise linear model based on a Markov chain Monte Carlo sampler. The function automatically creates the fixed and random part of the regression model.

Usage

bplm(
  data,
  dvar,
  pvar,
  mvar,
  model = c("W", "H-M", "B&L-B"),
  contrast_level = c("first", "preceding"),
  contrast_slope = c("first", "preceding"),
  trend = TRUE,
  level = TRUE,
  slope = TRUE,
  random_trend = FALSE,
  random_level = FALSE,
  random_slope = FALSE,
  fixed = NULL,
  random = NULL,
  update_fixed = NULL,
  ...
)

## S3 method for class 'sc_bplm'
print(x, digits = 3, ...)

## S3 method for class 'sc_bplm'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  round = 2,
  nice = TRUE,
  ...
)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
model	Model used for calculating the dummy parameters (see Huitema & McKean, 2000). Default is model = "W". Possible values are: "B&L-B", "H-M", "W", and deprecated "JW".
contrast_level	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.
contrast_slope	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.
trend	A logical indicating if a trend parameters is included in the model.
level	A logical indicating if a level parameters is included in the model.
slope	A logical indicating if a slope parameters is included in the model.
random_trend	If TRUE, includes a random trend effect.
random_level	If TRUE, includes a random level effect.
random_slope	If TRUE, includes a random slope effect.
fixed	A formula that overwrites the automatically created fixed part of the regression model that defaults to the standard piecewise regression model. The parameter phase followed by the phase name (e.g., phaseB) indicates the level effect of the corresponding phase. The parameter 'inter' followed by the phase name (e.g., interB) adresses the slope effect based on the method provide in the model argument (e.g., "B&L-B"). The formula can be changed for example to include further L1 or L2 variables into the regression model.
random	A formula that overwrites the automatically created random part of the regression model.
update_fixed	An easier way to change the fixed model part (e.g., . ~ . + newvariable).
...	Further arguments passed to the MCMCglmm::MCMCglmm() function.
x	An object returned by bplm()
digits	The minimum number of significant digits to be use. If set to "auto" (default), values are predefined.
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
round	Integer passed to the digits argument used to round values.
nice	If set TRUE (default) output values are rounded and optimized for publication tables.

Details

The function uses the MCMCglmm::MCMCglmm() function to fit the model. The default model includes fixed trend, level, and slope effects as well as a random intercept for each single-case. The fixed part of the model can be changed by providing a custom formula to the fixed argument or by using the update_fixed argument. The random part of the model can be changed by providing a custom formula to the random argument or by setting the random_trend, random_level, or random_slope arguments to TRUE.

Value

An object of class sc_bplm with element:

• model - List containing information about the applied model.

• N - Number of single-cases.

• formula - A list containing the fixed and the random formulas of the hplm model.

• mcmglmm - Object of class MCMglmm.

• contrast - List with contrast definitions.

Functions

• print(sc_bplm): Print results

• export(sc_bplm): Export results as html table (see export())

Author(s)

Juergen Wilbert

See Also

Other regression functions: fetch(), hplm(), mplm(), plm(), print.sc_ac(), print.sc_bctau(), trend()

Examples

# plm regression
bplm(example_A24)

# Multilevel plm regression with random intercept
bplm(exampleAB_50, nitt = 5000)

# Adding a random slope
bplm(exampleAB_50, random_level = TRUE, nitt = 5000)

# Custom fixed formula
bplm(exampleAB_50, update_fixed = values ~ -1 + mt + phaseB +
  interB, nitt = 5000)

---

Extract coefficients from plm/hplm objects

Description

Extract coefficients from plm/hplm objects

Usage

## S3 method for class 'sc_plm'
coef(object, ...)

Arguments

object	plm or hplm object
...	not implemented

Value

data frame with coefficient table

Examples

coefficients(plm(exampleAB$Johanna))

---

Combine single-case data frames into one scdf

Description

Combines several single-case data frames (scdf) into one scdf object.

Usage

combine(..., dvar = NULL, pvar = NULL, mvar = NULL, info = NULL, author = NULL)

## S3 method for class 'scdf'
c(...)

Arguments

...	scdf objects to be combined.
dvar	Character string. Name of the dependent variable. Defaults to the dependent variable of the first case provided.
pvar	Character string. Name of the phase variable. Defaults to the phase variable of the first case provided.
mvar	Character string. Name of the measurement-time variable. Defaults to the measurement-time variable of the first case provided.
info	additional information on the scdf file.
author	author of the data.

Value

A scdf. If not set differently, the attributes of this scdf are copied from the first scdf provided (i.e the first argument of the function).

Author(s)

Juergen Wilbert

---

Convert scdf to R code

Description

Converts an scdf object into R code that can be used to recreate the object.

Usage

convert(
  scdf,
  file = "",
  study_name = "study",
  case_name = "case",
  inline = FALSE,
  indent = 2,
  silent = FALSE
)

Arguments

scdf	A single-case data frame. See scdf() to learn about this format.
file	A filename for exporting the syntax. If an empty string (default), the syntax is not written to a file.
study_name	Character string. Name of the study object.
case_name	Character string. Name of the scdf objects.
inline	If TRUE, phase definition is in an online version.
indent	Integer. Indentation.
silent	If TRUE, syntax is not printed to the console.

Details

This function is useful for exporting scdf objects for sharing or documentation purposes. The generated R code can be sourced to recreate the original scdf object.

Value

Returns a string (invisible).

Author(s)

Juergen Wilbert

See Also

Other io-functions: read_scdf(), write_scdf()

Examples

filename <- tempfile()
convert(exampleABC, file = filename)
source(filename)
all.equal(study, exampleABC)
unlink(filename)

---

Descriptive statistics for single-case data

Description

The describe() function provides common descriptive statistics for single-case data.

Usage

describe(data, dvar, pvar, mvar)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.

Details

It computes the number of measurements, number of missing values, mean, median, standard deviation, median average deviation, minimum, maximum, and trend (slope of dependent variable regressed on measurement-time) for each phase of each single-case included in an scdf.

n = number of measurements; mis = number of missing vaues; m = mean; md = median; sd = standard deviation; mad = median average deviation; min = minimum; max = maximum; trend = weight of depended variable regressed on time (values ~ mt).

Value

A list containing a data frame of descriptive statistics (descriptives); the cse design (design); the number of cases (N).

Author(s)

Juergen Wilbert

See Also

overlap(), plot.scdf()

Examples

## Descriptive statistics for a study of three single-cases
describe(Grosche2011)

## Descriptives of a three phase design
describe(exampleABC)

## Write descriptive statistics to .csv-file
study <- describe(Waddell2011)
write.csv(study$descriptives, file = tempfile())

---

Generate a single-case design matrix for multiple random single-cases

Description

Generates a parameter list used for generating multiple random single-cases. This is used within the random_scdf function and the power_test function and for other Monte-Carlo tasks.

Usage

design(
  n = 1,
  phase_design = list(A = 5, B = 15),
  trend = 0,
  level = list(0),
  slope = list(0),
  start_value = 50,
  s = 10,
  rtt = 0.8,
  extreme_prop = list(0),
  extreme_range = c(-4, -3),
  missing_prop = 0,
  distribution = c("normal", "gaussian", "poisson", "binomial"),
  random_start_value = FALSE,
  n_trials = NULL,
  mt = NULL,
  B_start = NULL,
  m,
  phase.design,
  MT,
  B.start,
  extreme.p,
  extreme.d,
  missing.p
)

Arguments

n	Number of cases to be designed (Default is n = 1).
phase_design, phase.design	A list defining the length and label of each phase. E.g., phase_design = list(A1 = 10, B1 = 10, A2 = 10, B2 = 10). Use vectors if you want to define different values for each case ⁠phase_design = list(A = c(10, 15), B = c(10, 15)⁠.
trend	Defines the effect size of a trend added incrementally to each measurement across the whole data-set. To assign different trends to several single-cases, use a vector of values (e.g. trend = c(.1, .3, .5)). If the number of cases exceeds the length of the vector, values are recycled. When using a 'gaussian' distribution, the trend parameters indicate effect size d changes. When using a binomial or poisson distribution, trend indicates an increase in points / counts per measurement.
level	A list that defines the level increase (effect size d) at the beginning of each phase relative to the previous phase (e.g. list(A = 0, B = 1)). The first element must be zero as the first phase of a single-case has no level effect (if you have one less list element than the number of phases, scan will add a leading element with 0 values). Use vectors to define variable level effects for each case (e.g. list(A = c(0, 0), B = c(1, 2))). When using a 'gaussian' distribution, the level parameters indicate effect size d changes. When using a binomial or poisson distribution, level indicates an increase in points / counts with the onset of each phase.
slope	A list that defines the increase per measurement for each phase compared to the previous phase. slope = list(A = 0, B = .1) generates an incremental increase of 0.1 per measurement starting at the B phase. The first list element must be zero as the first phase of a single-case has no slope effect (if you have one less list element than the number of phases, scan will add a leading element with 0 values). Use vectors to define variable slope effects for each case (e.g. list(A = c(0, 0), B = c(0.1, 0.2))). If the number of cases exceeds the length of the vector, values are recycled. When using a 'gaussian' distribution, the slope parameters indicate effect size d changes per measurement. When using a binomial or poisson distribution, slope indicates an increase in points / counts per measurement.
start_value, m	Starting value at the first measurement. Default is 50. When distribution = "poission" the start_value represents frequency. When distribution = "binomial" start_value must range between 0 and 1 and they represent the probability of on event. To assign different start values to several single-cases, use a vector of values (e.g. c(50, 42, 56)). If the number of cases exceeds the length of the vector, values are recycled. The m argument is deprecated.
s	Standard deviation used to calculate absolute values from level, slope, trend effects and to calculate and error distribution from the rtt values. Set to 10 by default. To assign different variances to several single-cases, use a vector of values (e.g. s = c(5, 10, 15)). If the number of cases exceeds the length of the vector, values are recycled. if the distribution is 'poisson' or 'binomial' s is not applied.
rtt	Reliability of the underlying simulated measurements. Set rtt = .8 by default. To assign different reliabilities to several single-cases, use a vector of values (e.g. rtt = c(.6, .7, .8)). If the number of cases exceeds the length of the vector, values are repeated. rtt has no effect when you're using binomial or poisson distributions.
extreme_prop, extreme.p	Probability of extreme values. extreme.p = .05 gives a five percent probability of an extreme value. A vector of values assigns different probabilities to multiple cases. If the number of cases exceeds the length of the vector, values are recycled.
extreme_range, extreme.d	Range for extreme values. extreme_range = c(-7,-6) uses extreme values within a range of -7 and -6 . In case of a binomial or poisson distribution, extreme_range indicates frequencies. In case of a gaussian (or normal) distribution it indicates effect size d. Caution: the first value must be smaller than the second, otherwise the procedure will fail.
missing_prop, missing.p	Portion of missing values. missing_prop = 0.1 creates 10\ different probabilities to multiple cases. If the number of cases exceeds the length of the vector, values are repeated.
distribution	Distribution of the criteria varible. Default is "normal". Possible values are "normal", "binomial", and "poisson".
random_start_value	If TRUE, the start_values are randomized based on the distribution.
n_trials	If distribution (see below) is "binomial", n_trials is the number of trials/observations/items. E.g., if you simulate accuracy data with 10 items per measurement, set n_trials = 10. To assign different n_trials to several single-cases, use a vector of values (e.g. n_trials = c(10, 15, 20)). If the number of cases exceeds the length of the vector, values are recycled.
mt, MT	Number of measurements (in each study). Default is mt = 20.
B_start, B.start	Phase B starting point. The default setting B_start = 6 would assign the first five scores (of each case) to phase A, and all following scores to phase B. To assign different starting points for a set of multiple single-cases, use a vector of starting values (e.g., B_start = c(6, 7, 8)). If the number of cases exceeds the length of the vector, values will be recycled.

Value

An object of class sc_design.

Author(s)

Juergen Wibert

Examples

## Create random single-case data and inspect it
 design <- design(
   n = 3, rtt = 0.75, slope = 0.1, extreme_prop = 0.1,
   missing_prop = 0.1
 )
 dat <- random_scdf(design, round = 1, random.names = TRUE, seed = 123)
 describe(dat)

 ## And now have a look at poisson-distributed data
 design <- design(
   n = 3, B_start = c(6, 10, 14), mt = c(12, 20, 22), start_value = 10,
   distribution = "poisson", level = -5, missing_prop = 0.1
 )
 dat <- random_scdf(design, seed = 1234)
 pand(dat, decreasing = TRUE)

---

Estimate single-case design

Description

This functions takes an scdf and extracts design parameters. The resulting object can be used to randomly create new scdf files with the same underlying parameters. This is useful for Monte-Carlo studies and bootstrapping procedures.

Usage

estimate_design(
  data,
  dvar,
  pvar,
  mvar,
  s = NULL,
  rtt = NULL,
  overall_effects = FALSE,
  overall_rtt = TRUE,
  model = "JW",
  ...
)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
s	The standard deviation depicting the between case variance of the overall performance. If more than two single-cases are included in the scdf, the variance is estimated if s is set to NULL. If s is provided, this value is used.
rtt	The reliability of the measurements. The reliability is estimated when rtt = NULL. If rtt is provided, this value is used for all single-cases.
overall_effects	If TRUE, trend, level, and slope effect estimations will be identical for each case. If FALSE, effects are estimated for each case separately. Default is FALSE.
overall_rtt	Ignored when rtt is set. If TRUE, rtt estimations will be based on all cases and identical for each case. If FALSE rtt is estimated for each case separately. Default is TRUE.
model	Model used for calculating the dummy parameters (see Huitema & McKean, 2000). Default is model = "W". Possible values are: "B&L-B", "H-M", "W", and deprecated "JW".
...	Further arguments passed to the plm function used for parameter estimation. For example, the model argument can be used to select different piecewise regression models. See plm for details.

Details

The function uses the plm function to estimate parameters for each single-case. If more than two single-cases are included in the scdf, the between case variance depicting the overall performance (s) is estimated unless s is provided. The reliability of the measurements (rtt) is estimated for each case unless rtt is provided. If overall_rtt is set to TRUE, rtt estimations will be based on all cases and identical for each case. If overall_effects is set to TRUE, trend, level, and slope effect estimations will be identical for each case.

The resulting design object can be used as input for the random_scdf function to create new random scdf files based on the estimated parameters. This allows to create bootstrap samples or Monte-Carlo datasets based on the characteristics of an existing dataset.

Value

A list of parameters for each single-case. Parameters include name, length, and starting measurement time of each phase, trend, level, and slope effects for each phase, start value, standard deviation, and reliability for each case. This list can be used as input for the random_scdf function to create new random scdf files based on the estimated parameters.

Author(s)

Juergen Wilbert

Examples

# create a random scdf with predefined parameters
set.seed(1234)
design <- design(
  n = 10, trend = -0.02,
  level = list(0, 1), rtt = 0.8,
  s = 1
)
scdf<- random_scdf(design)

# Estimate the parameters based on the scdf and create a new random scdf
# based on these estimations
design_est <- estimate_design(scdf, rtt = 0.8)
scdf_est <- random_scdf(design_est)

# Analyze both datasets with an hplm model. See how similar the estimations
# are:
hplm(scdf, slope = FALSE)
hplm(scdf_est, slope = FALSE)

# Also similar results for pand and randomization tests:
pand(scdf)
pand(scdf_est)
rand_test(scdf)
rand_test(scdf_est)

---

Single-case example data sets

Description

The scan package comes with a set of fictitious and authentic single-case study data. These data sets can be used to practice single-case data analysis and to reproduce results from the respective publications.

• Beretvas2008 — Fictitious single-case intervention study from Beretvas & Chung, 2008.

• Borckardt2014 — Fictitious daily pain ratings evaluating a psychological treatment from Borckardt & Nash, 2014.

• byHeart2011 — Multiple-baseline (11 cases) flash card vocabulary learning (Wilbert, unpublished).

• example_A24 — Number of injuries on a German autobahn before and after implementation of a speedlimit (130km/h) (Ministerium fuer Infrastruktur und Landesplanung. Land Brandenburg).

• exampleA1B1A2B2 — Fictitious A1-B1-A2-B2 example dataset.

• exampleA1B1A2B2_zvt — Non-fictitious A1-B1-A2-B2 example with ZVT (intelligence measure) and D2 (concentration measure) scores.

• exampleAB — Fictitious AB example dataset with three cases.

• exampleAB_50 — Fictitious AB example dataset (50 cases)s.

• exampleAB_50.l2 — Level-2 data for exampleAB_50.

• exampleAB_add — Fictitious AB example with added covariates.

• exampleAB_decreasing — Fictitious AB example with an expected decreasing effect in the intervention phase.

• exampleAB_mpd — Fictitious example with different phase structures for each case.

• exampleAB_score — Fictitious AB example with binomial distributed score outcome.

• exampleAB_simple — Simple fictitious AB example with three cases.

• exampleABAB — Fictitious ABAB reversal design example.

• exampleABC — Fictitious ABC example dataset.

• exampleABC_150 — Fictitious ABC example (150 cases).

• exampleABC_50 — Fictitious ABC example (50 cases).

• exampleABC_outlier — Fictitious ABC example with outlier.

• example_atd — Fictitious AB alternating treatment design.

• example_stranger - Example for screen time of Stranger Things characters.

• Grosche2011 — Multiple-baseline (three cases) from a direct-instructive reading intervention (Grosche, 2011).

• Grosche2014 — Multiple-baseline (3×3 materials) reading intervention (Grosche, Lueke, & Wilbert, unpublished).

• GruenkeWilbert2014 — Multiple-baseline (six cases) from a story mapping reading intervention (Gruenke, Wilbert, & Stegemann-Calder, 2013).

• Huber2014 — Multiple-baseline (four cases) with DBR ratings from a behavioral compliance intervention (Huber, unpublished).

• Huitema2000 — Fictitious single-case intervention study (Huitema & McKean, 2000).

• Lenz2013 — Fictitious example (Lenz, 2013).

• Leidig2018 — Multiple-baseline good behavior game intervention (Leidig et al., 2022).

• Leidig2018_l2 — Level-2 data for Leidig2018 (Leidig et al., 2022).

• Parker2007 — Example dataset after Parker et al. (2007).

• Parker2009 — Example dataset after Parker et al. (2009).

• Parker2009b — Example dataset after Parker & Vannest (2009).

• Parker2011 — Example dataset after Parker et al. (2011).

• Parker2011b — Example from Parker, Vannest, & Davis (2011).

• SSDforR2017 — Example from the R package SSDforR.

• Tarlow2017 — Fictitious single-case intervention study (Tarlow, 2017).

• Waddell2011 — Fictitious single-case intervention study (Waddell, Nassar, & Gustafson, 2011).

Usage

data(exampleAB, package = "scan")

Author(s)

Juergen Wilbert

References

Beretvas, S., & Chung, H. (2008). An evaluation of modified R2-change effect size indices for single-subject experimental designs. Evidence-Based Communication Assessment and Intervention, 2, 120–128.

Borckardt, J. J., & Nash, M. R. (2014). Simulation modelling analysis for small sets of single-subject data collected over time. Neuropsychological Rehabilitation, 24, 492–506.

Gruenke, M., Wilbert, J., & Stegemann-Calder, K. (2013). Analyzing the effects of story mapping on the reading comprehension of children with low intellectual abilities. Learning Disabilities: A Contemporary Journal, 11, 51–64.

Grosche, M. (2011). Effekte einer direkt-instruktiven Foerderung der Lesegenauigkeit. Empirische Sonderpaedagogik, 3, 147–161.

Huitema, B. E., & McKean, J. W. (2000). Design specification issues in time-series intervention models. Educational and Psychological Measurement, 60, 38–58.

Lenz, A. S. (2013). Calculating Effect Size in Single-Case Research: A Comparison of Nonoverlap Methods. Measurement and Evaluation in Counseling and Development, 46(1), 64–73.

Leidig, T., Casale, G., Wilbert, J., Hennemann, T., Volpe, R. J., Briesch, A., & Grosche, M. (2022). Individual, generalized, and moderated effects of the good behavior game on at-risk primary school students: A multilevel multiple baseline study using behavioral progress monitoring. Frontiers in Education, 7. https://www.frontiersin.org/articles/10.3389/feduc.2022.917138

Parker, R. I., Hagan-Burke, S., & Vannest, K. (2007). Percentage of All Non-Overlapping Data (PAND) An Alternative to PND. The Journal of Special Education, 40(4), 194-204.

Parker, R. I., Vannest, K. J., & Brown, L. (2009). The improvement rate difference for single-case research. Exceptional Children, 75(2), 135-150.

Parker, R. I., & Vannest, K. (2009). An improved effect size for single-case research: Nonoverlap of all pairs. Behavior Therapy, 40(4), 357-367.

Parker, R. I., Vannest, K. J., Davis, J. L., & Sauber, S. B. (2011). Combining Nonoverlap and Trend for Single-Case Research: Tau-U. Behavior Therapy, 42(2), 284–299. https://doi.org/10.1016/j.beth.2010.08.006

Parker, R. I., Vannest, K. J., & Davis, J. L. (2011). Effect Size in Single-Case Research: A Review of Nine Nonoverlap Techniques. Behavior Modification, 35(4), 303-322. https://doi.org/10.1177/0145445511399147

Tarlow, K. R. (2017). An Improved Rank Correlation Effect Size Statistic for Single-Case Designs: Baseline Corrected Tau. Behavior Modification, 41(4), 427–467. https://doi.org/10.1177/0145445516676750

Waddell, D. E., Nassar, S. L., & Gustafson, S. A. (2011). Single-Case Design in Psychophysiological Research: Part II: Statistical Analytic Approaches. Journal of Neurotherapy, 15, 160–169.

---

Export scan objects to html or latex

Description

Export creates html files of tables or displays them directly in the viewer pane of rstudio. When applied in rmarkdown/quarto, tables can also be created for pdf/latex output.

Usage

export(object, ...)

## S3 method for class 'sc_desc'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  flip = FALSE,
  round = 2,
  ...
)

## S3 method for class 'sc_nap'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  select = c("Case", "NAP", "NAP Rescaled", "w", "p", "d", "R²"),
  round = 2,
  ...
)

## S3 method for class 'sc_overlap'
export(
  object,
  caption = NA,
  footnote = NULL,
  filename = NA,
  round = 2,
  decimals = 2,
  flip = FALSE,
  ...
)

## S3 method for class 'sc_pem'
export(object, caption = NA, footnote = NA, filename = NA, round = 2, ...)

## S3 method for class 'sc_pet'
export(object, caption = NA, footnote = NA, filename = NA, round = 1, ...)

## S3 method for class 'sc_pnd'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  select = c("Case", "PND", "Total", "Exceeds"),
  round = 2,
  ...
)

## S3 method for class 'sc_power'
export(object, caption = NA, footnote = NA, filename = NA, round = 3, ...)

## S3 method for class 'sc_smd'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  select = c("Case", `Mean A` = "mA", `Mean B` = "mB", `SD A` = "sdA", `SD B` = "sdB",
    `SD Cohen` = "sd cohen", `SD Hedges` = "sd hedges", "Glass' delta", "Hedges' g",
    "Hedges' g correction", "Hedges' g durlak correction", "Cohen's d"),
  round = 2,
  decimals = 2,
  flip = FALSE,
  ...
)

## S3 method for class 'sc_trend'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  round = 3,
  decimals = NULL,
  ...
)

## S3 method for class 'scdf'
export(
  object,
  summary = FALSE,
  caption = NA,
  footnote = NA,
  filename = NA,
  cols,
  round = 2,
  ...
)

## S3 method for class 'scdf_summary'
export(object, caption = NA, footnote = NA, filename = NA, round = 2, ...)

Arguments

object	An scdf or an object exported from a scan function.
...	Further Arguments passed to internal functions.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
flip	If TRUE, some objects are exported with rows and columns flipped.
round	Integer passed to the digits argument used to round values.
select	A character vector containing the names of the variables to be included. If the vector is named, the variables will be renamed accordingly.
decimals	Decimal places that are reported.
summary	If TRUE, exports the summary of an scdf.
cols	Defines which columns are included when exporting an scdf. It is either a vector of variable names or the string "main" will select the central variables.

Details

The function uses either the kableExtra or the gt package to create the tables. The default engine can be set via the option scan.export.engine. Additional options for kable and kable_styling can be set via the options scan.export.kable and scan.export.kable_styling. The default options can be viewed and modified via options("scan.export.kable") and options("scan.export.kable_styling").

Value

Returns or displays a specially formatted html (or latex) file.

---

Fetches elements from scan objects

Description

The fetch function is a getter function for scan objects returned from regression functions such as plm(), hplm(), bplm(), and mplm(). It allows users to extract specific elements from these objects, such as the fitted model.

Usage

fetch(object, what, ...)

Arguments

object	Object returned from a scan function.
what	Element/part to be extracted. Currently, only "model" is supported to extract the fitted regression model.
...	Further parameters passed to the function.

Value

An object of the respective regression model class.

Author(s)

Juergen Wilbert

See Also

Other regression functions: bplm(), hplm(), mplm(), plm(), print.sc_ac(), print.sc_bctau(), trend()

Examples

# plm regression
model1 <- plm(example_A24)
fetch(model1, what = "model") |> summary()
# Multilevel plm regression
model2 <- hplm(exampleAB_50)
fetch(model2, what = "model") |> summary()
# Bayesian plm regression
model3 <- bplm(exampleAB_50, nitt = 5000)
fetch(model3, what = "model") |> summary()

---

Replacing missing measurement points in single-case data

Description

The fillmissing() function replaces missing measurements in single-case data. It linearly interpolates missing data points between two existing measurements for all variables except the measurement time and phase. The measurement time variable is filled with the missing time points. The phase variable is copied from the previous measurement time point. If mt values are missing (NA), they are also interpolated if interpolate_na = TRUE.

Usage

fill_missing(data, dvar, mvar, pvar, interpolate_na = TRUE)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
interpolate_na	If set TRUE, NA values in the measurement time variable are also interpolated. Default is TRUE.

Details

The fill_missing() function is designed to handle single-case data with missing measurement points. It performs linear interpolation to estimate the missing values based on the existing data points. The function iterates through each single-case in the provided single-case data frame (scdf) and identifies gaps in the measurement time variable. For each gap, it calculates the step size for linear interpolation and fills in the missing values for all target variables (i.e., all variables except the measurement time and phase). The interpolated data points are then added to the single-case data frame, and the final result is sorted by measurement time. This function is particularly useful for preparing single-case data for further analysis, such as calculating overlap indices or conducting randomization tests, where continuous measurement times are required. It ensures that the data is complete by filling in the missing measurement points in a systematic manner.

Value

A single-case data frame with interpolated missing data points.

Author(s)

Juergen Wilbert

See Also

Other data manipulation functions: add_l2(), as.data.frame.scdf(), as_scdf(), batch_apply(), moving_median(), print.sc_outlier(), ranks(), rescale(), scdf(), select_cases(), set_vars(), shift(), smooth_cases(), standardize(), truncate_phase()

Examples

## In his study, Grosche (2011) could not realize measurements each
## single week for all participants. During the course of 100 weeks,
## about 20 measurements per person at different times were administered.

## Fill missing values in a single-case dataset with discontinuous
## measurement times
Grosche2011filled <- fill_missing(Grosche2011)
study <- c(Grosche2011[2], Grosche2011filled[2])
names(study) <- c("Original", "Filled")
study

## An example with multiple interpolated variables

rolf_n <- exampleAB_add
rolf_n[[1]] <- rolf_n[[1]][-c(3,7,8),]
rolf_f <- fill_missing(rolf_n)
study1 <- c("original" = exampleAB_add, "interpolated" = rolf_f)
study1

## Example with missing NAs in measurement time
Maggie2 <- random_scdf(design(level = list(0,1)), seed = 123)
Maggie2_n <- Maggie2
Maggie2_n[[1]][c(5,12:14,20), "mt"] <- NA
Maggie2_f <- fill_missing(Maggie2_n)
study2 <- c("original" = Maggie2, "interpolated" = Maggie2_f)
study2

---

Hierarchical piecewise linear model / piecewise regression for multiple cases

Description

The hplm() function computes a hierarchical piecewise regression model. It extends the standard piecewise regression model to multiple cases by estimating fixed and random effects. The function uses the lme function of the nlme package to fit linear mixed-effects models. The model can include random intercepts and random slopes for level, trend, and treatment effects. Additionally, it allows for the inclusion of autoregressive structures and unequal variances across phases. The function also provides options for likelihood ratio tests to compare models with and without random slope effects, as well as the calculation of intraclass correlations (ICC) to assess the proportion of variance attributable to between-case differences. This function is particularly useful for analyzing data from multiple single-case experimental designs (SCEDs) where observations are nested within cases.

Usage

hplm(
  data,
  dvar,
  pvar,
  mvar,
  model = c("W", "H-M", "B&L-B", "JW"),
  contrast = c("first", "preceding"),
  contrast_level = NA,
  contrast_slope = NA,
  method = c("ML", "REML"),
  control = list(opt = "optim"),
  random.slopes = FALSE,
  lr.test = FALSE,
  ICC = TRUE,
  trend = TRUE,
  level = TRUE,
  slope = TRUE,
  random_trend = FALSE,
  random_level = FALSE,
  random_slope = FALSE,
  fixed = NULL,
  random = NULL,
  ar = 0,
  unequal_variances = FALSE,
  update.fixed = NULL,
  data.l2 = NULL,
  ...
)

## S3 method for class 'sc_hplm'
print(x, digits = 3, bcsmd = FALSE, casewise = FALSE, ...)

## S3 method for class 'sc_hplm'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  round = 2,
  nice = TRUE,
  casewise = FALSE,
  ...
)

## S3 method for class 'sc_hplm'
coef(object, casewise = FALSE, ...)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
model	Model used for calculating the dummy parameters (see Huitema & McKean, 2000). Default is model = "W". Possible values are: "B&L-B", "H-M", "W", and deprecated "JW".
contrast	Sets contrast_level and contrast_slope. Either "first", "preceding" or a contrast matrix. If NA contrast is ignored.
contrast_level	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.
contrast_slope	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.
method	Method used to fit your model. Pass "REML" to maximize the restricted log-likelihood or "ML" for maximized log-likelihood. Default is "ML".
control	A list of settings for the estimation algorithm, replacing the default values passed to the function lmeControl of the nlme package.
random.slopes	If random.slopes = TRUE random slope effects of the level, trend, and treatment parameter are estimated.
lr.test	If set TRUE likelihood ratio tests are calculated comparing model with vs. without random slope parameters.
ICC	If ICC = TRUE an intraclass-correlation is estimated.
trend	A logical indicating if a trend parameters is included in the model.
level	A logical indicating if a level parameters is included in the model.
slope	A logical indicating if a slope parameters is included in the model.
random_trend	If TRUE, includes a random trend trend effect.
random_level	If TRUE, includes a random level trend effect.
random_slope	If TRUE, includes a random slope trend effect.
fixed	Defaults to the fixed part of the standard piecewise regression model. The parameter phase followed by the phase name (e.g., phaseB) indicates the level effect of the corresponding phase. The parameter 'inter' followed by the phase name (e.g., interB) adresses the slope effect based on the method provide in the model argument (e.g., "B&L-B"). The formula can be changed for example to include further L1 or L2 variables into the regression model.
random	The random part of the model. Defaults to a random intercept model. The formula can be changed to include random slope effects for level, trend, and treatment effects.
ar	Maximal lag of autoregression. Modelled based on the Autoregressive-Moving Average (ARMA) function.
unequal_variances	Logical. If set TRUE, estimations are weighted by phase variances.
update.fixed	An easier way to change the fixed model part (e.g., . ~ . + newvariable).
data.l2	A data frame providing additional variables at Level 2. The scdf File has to have names for all cases and the Level 2 data frame has to have a column named 'cases' with the names of the cases the Level 2 variables belong to.
...	Further arguments passed to the lme function.
x	An object returned by hplm()
digits	The minimum number of significant digits to be use. If set to "auto" (default), values are predefined.
bcsmd	If TRUE, reports between-case standardized mean differences.
casewise	Returns the estimations for each case separately
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
round	Integer passed to the digits argument used to round values.
nice	If set TRUE (default) output values are rounded and optimized for publication tables.

Value

An object of class sc_hplm.

• model | List containing infromation about

• N | Number of single-cases.

• formula | A list containing the fixed and the random formulas of the hplm model.

• hplm | Object of class lme contaning the multilevel model.

• model.0 | Object of class lme containing the zero model.

• ICC | List containing intraclass correlation and test parameters.

• model.without | Object of class gls containing the fixed effect model.

• contrast | List with contrast definitions.

Functions

• print(sc_hplm): Print results

• export(sc_hplm): Export results as html table (see export())

• coef(sc_hplm): Extract model coefficients

Model specification

The fixed effects part of the model can be specified using the fixed argument, while the random effects part can be specified using the random argument. If not provided, default formulas based on the specified model type (e.g., "B&L-B") are created. The function also allows for the inclusion of autoregressive structures through the ar argument and unequal variances across phases through the unequal_variances argument.

Random slopes

By setting the random.slopes argument to TRUE, the model will include random slope effects for level, trend, and treatment effects. This allows for individual differences in how cases respond to these effects.

Likelihood ratio tests

If the lr.test argument is set to TRUE, the function will perform likelihood ratio tests to compare models with and without random slope effects. This helps to determine whether including random slopes significantly improves model fit.

Intraclass correlation

If the ICC argument is set to TRUE, the function will calculate the intraclass correlation coefficient (ICC) to assess the proportion of variance attributable to between-case differences. This provides insight into the degree of similarity among observations within the same case.

Author(s)

Juergen Wilbert

See Also

Other regression functions: bplm(), fetch(), mplm(), plm(), print.sc_ac(), print.sc_bctau(), trend()

Examples

## Compute hplm model on a MBD over fifty cases (restricted log-likelihood)
hplm(exampleAB_50, method = "REML", random.slopes = FALSE)

## Analyzing with additional L2 variables
Leidig2018 |>
  add_l2(Leidig2018_l2) |>
  hplm(update.fixed = .~. + gender + migration + ITRF_TOTAL*phaseB,
       slope = FALSE, random.slopes = FALSE, lr.test = FALSE
  )

---

Import scdf – RStudio Addin

Description

Import scdf – RStudio Addin

Usage

import_scdf()

---

IRD - Improvement rate difference

Description

ird() calculates the robust improvement rate difference as proposed by Parker and colleagues (2011).

Usage

ird(data, dvar, pvar, decreasing = FALSE, phases = c(1, 2))

## S3 method for class 'sc_ird'
print(x, digits = 3, ...)

## S3 method for class 'sc_ird'
export(object, caption = NA, footnote = NA, filename = NA, round = 3, ...)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
decreasing	If you expect data to be lower in the B phase, set decreasing = TRUE. Default is decreasing = FALSE.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).
x	An object returned by ird()
digits	The minimum number of significant digits to be use.
...	Further arguments passed to the function.
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
round	Integer passed to the digits argument used to round values.

Details

The adaptation of the improvement rate difference for single-case phase comparisons was developed by Parker and colleagues (2009). A variation called robust improvement rate difference was proposed by Parker and colleagues in 2011. This function calculates the robust improvement rate difference. It follows the formula suggested by Pustejovsky (2019). For a multiple case design, ird is based on the overall improvement rate of all cases which is the average of the irds for each case.

Functions

• print(sc_ird): Print results

• export(sc_ird): Export results to html

References

Parker, R. I., Vannest, K. J., & Brown, L. (2009). The improvement rate difference for single-case research. Exceptional Children, 75(2), 135-150.

Parker, R. I., Vannest, K. J., & Davis, J. L. (2011). Effect Size in Single-Case Research: A Review of Nine Nonoverlap Techniques. Behavior Modification, 35(4), 303-322. https://doi.org/10.1177/0145445511399147

Pustejovsky, J. E. (2019). Procedural sensitivities of effect sizes for single-case designs with directly observed behavioral outcome measures. Psychological Methods, 24(2), 217-235. https://doi.org/10.1037/met0000179

See Also

Other overlap functions: nap(), overlap(), pand(), pem(), pet(), pnd(), print.sc_cdc(), select_phases(), tau_u()

---

Test for scdf objects

Description

Tests for objects of type "scdf".

Usage

is.scdf(x)

Arguments

x	An object to be tested.

Value

Returns TRUE or FALSE depending on whether its argument is of scdf type or not.

Author(s)

Juergen Wilbert

---

Transform every single case of a single case data frame

Description

Takes an scdf and applies transformations to each individual case. This is useful to calculate or modify new variables.

Usage

moving_median(x, lag = 1)

moving_mean(x, lag = 1)

local_regression(x, mt = 1:length(x), f = 0.2)

set_na_at(x, first_of, positions = 0)

center_at(x, at = TRUE, shift = 0, part = 0)

first_of(x, positions = 0)

across_cases(...)

all_cases(...)

rowwise(...)

## S3 method for class 'scdf'
transform(`_data`, ...)

Arguments

x	A logical vector.
lag	Number of values surrounding a value to calculate the average
mt	A vector with measurement times.
f	the proportion of surrounding data influencing each data point.
first_of	A logical vector
positions	A numeric vector with relative positions to the first appearance of a TRUE value in x.
at	A logical vector. E.g. phase == "A". The first TRUE value of that vector is the target position for centring. By default, this is the first position.
shift	A value indicating a shift in measurement times for centring. E.g. shift = 4 will centre four measurement-times after the position defined by the at and part arguments.
part	A numeric value between 0 and 1. 0 refers to the first TRUE in the at vector, 1 to the last, and 0.5 to the midpoint of the sequence of TRUE values. E.g. if you want to centre at the middle of phase A, set ⁠at = phase == A, part = 0.5⁠. Note: decimals are rounded to integers.
...	Expressions.
_data	An scdf.

Details

This function is a method of the generic transform() function. Unlike the generic version, expressions are evaluated serially: the result of one expression is used as the basis for subsequent computations.

Several helper functions can be used inside expressions:

• n(): returns the number of measurements in a case.

• all_cases(): extracts the values of a variable across all cases. Takes an expression as argument. For example:

  • mean(all_cases(values)) calculates the mean of values across all cases.

  • mean(all_cases(values[phase == "A"])) calculates the mean of all values where phase == "A".

• rowwise(): applies a calculation separately to each row. Example: rowwise(sum(values, mt, na.rm = TRUE)).

• across_cases(): creates new variables or replaces existing ones across all cases. Example: across_cases(values_ranked = rank(values, na.last = "keep")) ranks the values variable across all cases and creates a new variable values_ranked.

Value

An scdf.

Author(s)

Juergen Wilbert

See Also

Other data manipulation functions: add_l2(), as.data.frame.scdf(), as_scdf(), batch_apply(), fill_missing(), print.sc_outlier(), ranks(), rescale(), scdf(), select_cases(), set_vars(), shift(), smooth_cases(), standardize(), truncate_phase()

Examples

## Creates a single-case with frequency distributions. The proportion and
## percentage of the frequencies are calculated with transform:
design <- design(
 n = 3,
 level = 5,
 distribution = "binomial",
 n_trials = 20,
 start_value = 0.5
)
study <- random_scdf(design)
transform(study, proportion = values/trials, percentage = proportion * 100)

## Z standardize the dependent variable and add two new variables:
exampleAB |>
  transform(
    values = scale(values),
    mean_values = mean(values),
    sd_values = sd(values)
  )

## Use `all` to calculate global variables.
exampleAB |>
  transform(
    values_center_case = values - mean(values[phase == "A"]),
    values_center_global = values - mean(all(values[phase == "A"])),
    value_dif = values_center_case - values_center_global
  )

## Use `across_cases` to calculate or replace a variable with values from
## all cases. E.g., standardize the dependent variable:
exampleABC |>
  transform(
    across_cases(values = scale(values))
  )

## Rank transform the values based on all cases vs. within each case:
exampleABC |>
  transform(
    across_cases(values_across = rank(values, na.last="keep")),
    value_within = rank(values, na.last="keep")
  )

## Three helper functions to smooth the data
Huber2014$Berta |>
transform(
  "compliance (moving median)" = moving_median(compliance),
  "compliance (moving mean)" = moving_mean(compliance),
  "compliance (local regression)" = local_regression(compliance, mt)
)

## Function first_of() helps to set NAs for specific phases.
## E.g., you want to replace the first two values of phase A and the first
## value of phase B and its preceding value.

byHeart2011 |>
  transform(
    values = set_na_at(values, phase == "A", 0:1),
    values = set_na_at(values, phase == "B", -1:0)
  )

---

Multivariate Piecewise linear model / piecewise regression

Description

The mplm() function computes a multivariate piecewise regression model. The function automatically creates the regression formula based on the provided data and the selected options. The default model includes trend, level, and slope effects for each dependent variable. The regression formula can be changed by providing a custom formula to the update argument.

Usage

mplm(
  data,
  dvar,
  mvar,
  pvar,
  model = c("W", "H-M", "B&L-B", "JW"),
  contrast = c("first", "preceding"),
  contrast_level = c(NA, "first", "preceding"),
  contrast_slope = c(NA, "first", "preceding"),
  trend = TRUE,
  level = TRUE,
  slope = TRUE,
  formula = NULL,
  update = NULL,
  na.action = na.omit,
  ...
)

## S3 method for class 'sc_mplm'
print(x, digits = "auto", std = FALSE, ...)

## S3 method for class 'sc_mplm'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  nice = TRUE,
  std = FALSE,
  decimals = 2,
  ...
)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
model	Model used for calculating the dummy parameters (see Huitema & McKean, 2000). Default is model = "W". Possible values are: "B&L-B", "H-M", "W", and deprecated "JW".
contrast	Sets contrast_level and contrast_slope. Either "first", "preceding" or a contrast matrix. If NA contrast is ignored.
contrast_level	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.
contrast_slope	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.
trend	A logical indicating if a trend parameters is included in the model.
level	A logical indicating if a level parameters is included in the model.
slope	A logical indicating if a slope parameters is included in the model.
formula	Defaults to the standard piecewise regression model. The parameter phase followed by the phase name (e.g., phaseB) indicates the level effect of the corresponding phase. The parameter 'inter' followed by the phase name (e.g., interB) adresses the slope effect based on the method provide in the model argument (e.g., "B&L-B"). The formula can be changed for example to include further variables into the regression model.
update	An easier way to change the regression formula (e.g., . ~ . + newvariable).
na.action	Defines how to deal with missing values.
...	Further arguments passed to the lm() function.
x	Object returned from mplm().
digits	The minimum number of significant digits to be use. If set to "auto" (default), values are predefined.
std	If TRUE, a table with standardized estimates is included.
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
nice	If set TRUE (default) output values are rounded and optimized for publication tables.
decimals	Decimal places that are reported.

Details

The function currently only supports single-case data (i.e., one case per dataset). For multilevel piecewise regression models, please use the hplm function.

Value

model	Character string from function call (see arguments above).
contrast	List with contrast definitions.
full.model	Full regression model list.
formula	Formula of the mplm model.

Functions

• print(sc_mplm): Print results

• export(sc_mplm): Export results as html

Author(s)

Juergen Wilbert

See Also

Other regression functions: bplm(), fetch(), hplm(), plm(), print.sc_ac(), print.sc_bctau(), trend()

Examples

res <- mplm(Leidig2018$`1a1`,
  dvar = c("academic_engagement", "disruptive_behavior")
)
print(res)
## also report standardized coefficients:
print(res, std = TRUE)

---

Remove missing values from scdf

Description

Removes any row with a missing value from each single-case data frame in an scdf.

Usage

## S3 method for class 'scdf'
na.omit(object, ...)

Arguments

object	A scdf.
...	not implemented yet.

Value

A scdf object.

Author(s)

Juergen Wilbert

---

Nonoverlap of all Pairs (NAP)

Description

The nap() function calculates the nonoverlap of all pairs (NAP; Parker & Vannest, 2009). NAP summarizes the overlap between all pairs of phase A and phase B data points. If an increase of phase B scores is expected, a non-overlapping pair has a higher phase B data point. The NAP equals number of pairs showing no overlap / number of pairs where ties are counted as half non-overlaps. Because NAP can take values between 0 and 100 percent where values below 50 percent indicate an inverse effect, an nap rescaled from -100 to 100 percent where negative values indicate an inverse effect is also displayed ($nap_{rescaled} = 2 * nap - 100$).

Usage

nap(data, dvar, pvar, decreasing = FALSE, phases = c(1, 2))

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
decreasing	If you expect data to be lower in the B phase, set decreasing = TRUE. Default is decreasing = FALSE.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).

Details

If a decrease of phase B scores is expected, set the argument decreasing = TRUE.

Value

nap	A data frame with NAP and additional values for each case.
N	Number of cases.

Author(s)

Juergen Wilbert

References

Parker, R. I., & Vannest, K. (2009). An improved effect size for single-case research: Nonoverlap of all pairs. Behavior Therapy, 40, 357-367.

See Also

Other overlap functions: ird(), overlap(), pand(), pem(), pet(), pnd(), print.sc_cdc(), select_phases(), tau_u()

Examples

## Calculate NAP for a study with  lower expected phase B scores
## (e.g. aggressive behavior)
gretchen <- scdf(c(A = 12, 14, 9, 10, B = 10, 6, 4, 5, 3, 4))
nap(gretchen, decreasing = TRUE)

## Request NAP for all cases from the Grosche2011 scdf
nap(Grosche2011)

## Calculate NAP for phase 1 and phase 3 of an ABAB design
nap(exampleABAB, phases = c(1, 3))

---

Overlap indices for single-case data

Description

The overlap function provides the most common overlap indices for single-case data and some additional statistics.

Usage

overlap(data, dvar, pvar, mvar, decreasing = FALSE, phases = c(1, 2))

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
decreasing	If you expect data to be lower in the B phase, set decreasing = TRUE. Default is decreasing = FALSE.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).

Details

It computes PND, PEM, PET, NAP, PAND, IRD, Tau-U, mean difference, difference in trend, SMD, and Hedges-g for each single-case included in an scdf.

See corresponding functions of PND, PEM, PET, NAP, PAND for calculation. Tau_U(A) reports "A vs. B - Trend A" whereas Tau_U(BA) reports "A vs. B + Trend B - Trend A". Base_Tau is baseline corrected tau (correction applied when autocorrelation in phase A is significant). Diff_mean is the mean difference. Diff_trend is the difference in the regression estimation of the dependent variable on measurement-time (x ~ mt) for each phase. SMD is the mean difference divided by the standard deviation of phase A. Hedges_g is the mean difference divided by the pooled standard deviation: $\sqrt{ (n_A - 1)sd_A^2 + (n_B - 1)sd_B^2 \over n_A + n_B - 2 }$ with a hedges correction applied: $Hedges_g * (1 - \frac{3}{4n - 9} ) )$.

Value

overlap	A data frame consisting of the following indices for each single-case for all cases: PND, PEM, PET, NAP, PAND, IRD, Tau-U (A vs. B - Trend A), Diff_mean, Diff_trend, SMD, Hedges-g.
phases.A	Selection for A phase.
phases.B	Selection for B phase.
design	Phase design.

Author(s)

Juergen Wilbert

See Also

pnd(), pem(), pet(), nap(), pand(), ird(), tau_u(), corrected_tau()

Other overlap functions: ird(), nap(), pand(), pem(), pet(), pnd(), print.sc_cdc(), select_phases(), tau_u()

Examples

## Display overlap indices for one single-case
overlap(Huitema2000, decreasing = TRUE)

## Display overlap indices for six single-cases
overlap(GruenkeWilbert2014)

## Combining phases for analyszing designs with more than two phases
overlap(exampleA1B1A2B2, phases = list(c("A1","A2"), c("B1","B2")))

---

Percentage of all non-overlapping data

Description

The pand() function calculates the percentage of all non-overlapping data (PAND; Parker, Hagan-Burke, & Vannest, 2007), an index to quantify a level increase (or decrease) in performance after the onset of an intervention.

Usage

pand(
  data,
  dvar,
  pvar,
  decreasing = FALSE,
  phases = c(1, 2),
  method = c("sort", "minimum")
)

## S3 method for class 'sc_pand'
print(x, ...)

## S3 method for class 'sc_pand'
export(object, caption = NA, footnote = NA, filename = NA, round = 1, ...)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
decreasing	If you expect data to be lower in the B phase, set decreasing = TRUE. Default is decreasing = FALSE.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).
method	Either "sort"" or "minimum". See details.
x	An object returned by pand()
...	Further arguments passed to the function.
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
round	Integer passed to the digits argument used to round values.

Details

PAND was proposed by Parker, Hagan-Burke, and Vannest in 2007. The authors emphasize that PAND is designed for application in a multiple case design with a substantial number of measurements, technically at least 20 to 25, but preferably 60 or more. PAND is defined as 100% minus the percentage of data points that need to be removed from either phase in order to ensure nonoverlap between the phases. Several approaches have been suggested to calculate PAND, leading to potentially different outcomes. In their 2007 paper, Parker and colleagues present an algorithm for computing PAND. The algorithm involves sorting the scores of a time series, including the associated phases, and comparing the resulting phase order with the original phase order using a contingency table. To account for ties, the algorithm includes a randomization process where ties are randomly assigned to one of the two phases. Consequently, executing the algorithm multiple times could yield different results. It is important to note that this algorithm does not produce the same results as the PAND definition provided earlier in the same paper. However, it offers the advantage of allowing the calculation of an effect size measure phi, and the application of statistical tests for frequency distributions. Pustejovsky (2019) presented a mathematical formulation of Parker's original definition for comparing two phases of a single case:

$PAND = \frac{1}{m+n}max\{(i+j)I(y^A_{i}<y^B_{n+1-j}\}$

This formulation provides accurate results for PAND, but the original definition has the drawback of an unknown distribution under the null hypothesis, making a statistical test difficult. The pand() function enables the calculation of PAND using both methods. The first approach (method = "sort") follows the algorithm described above, with the exclusion of randomization before sorting to avoid ambiguity. It calculates a phi measure and provides the results of a chi-squared test and a Fisher exact test. The second approach (method = "minimum") applies the aforementioned formula. The code of this function is based on the code of the SingleCaseES package (function calc_PAND). For a multiple case design, overlaps are calculated for each case, summed, and then divided by the total number of measurements. No statistical test is conducted for this method.

Value

pand	Percentage of all non-overlapping data.
method	Calculation method.
phi	Effect size Phi based on expected and observed values.
perc_overlap	Percentage of overlapping data points.
overlaps	Number of overlapping data points.
n	Number of data points.
N	Number of cases.
n_a	Number of data points in phase A.
n_b	Number of data points in phase B.
matrix	2x2 frequency matrix of phase A and B comparisons.
matrix_counts	2x2 counts matrix of phase A and B comparisons.
chi_test	A Chi-squared analysis of expected and observed data (chisq.test()).
fisher_test	A Fisher exact test analysis of expected and observed data (fisher.test()).

Functions

• print(sc_pand): Print results

• export(sc_pand): Export results as html table (see export())

Author(s)

Juergen Wilbert

References

Parker, R. I., Hagan-Burke, S., & Vannest, K. (2007). Percentage of All Non-Overlapping Data (PAND): An Alternative to PND. The Journal of Special Education, 40, 194-204.

Parker, R. I., & Vannest, K. (2009). An Improved Effect Size for Single-Case Research: Nonoverlap of All Pairs. Behavior Therapy, 40, 357-367.

Pustejovsky, J. E. (2019). Procedural sensitivities of effect sizes for single-case designs with directly observed behavioral outcome measures. Psychological Methods, 24(2), 217-235. https://doi.org/10.1037/met0000179

Pustejovsky JE, Chen M, Swan DM (2023). SingleCaseES: A Calculator for Single-Case Effect Sizes. R package version 0.7.1.9999, https://jepusto.github.io/SingleCaseES/.

See Also

Other overlap functions: ird(), nap(), overlap(), pem(), pet(), pnd(), print.sc_cdc(), select_phases(), tau_u()

Examples

## REplication of the Parker et al. 2007 example
pand(Parker2007)

## Calculate the PAND with an expected decrease of phase B scores
cubs <- scdf(c(20,22,24,17,21,13,10,9,20,9,18), B_start = 5)
pand(cubs, decreasing = TRUE)

---

Percent exceeding the median (PEM)

Description

The pem function returns the percentage of phase B data exceeding the phase A median. Additionally, a chi square test against a 50/50 distribution is computed. Different measures of central tendency can be addressed for alternative analyses.

Usage

pem(
  data,
  dvar,
  pvar,
  decreasing = FALSE,
  binom.test = TRUE,
  chi.test = FALSE,
  FUN = median,
  phases = c(1, 2),
  ...
)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
decreasing	If you expect data to be lower in the B phase, set decreasing = TRUE. Default is decreasing = FALSE.
binom.test	Computes a binomial test for a 50/50 distribution. Default is binom.test = TRUE.
chi.test	Computes a Chi-square test. The default setting chi.test = FALSE skips the Chi-square test.
FUN	Data points are compared with the phase A median. Use this argument to implement alternative measures of central tendency. Default is FUN = median.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).
...	Additional arguments for the FUN parameter (e.g. FUN = mean, trim = 0.1 will use the 10 percent trimmed arithmetic mean instead of the median for comparisons). The function must take a vector of numeric values and the na.rm argument and return a numeric value.

Details

The Percent Exceeding the Median is calculated as the percentage of data points in phase B that exceed the median of phase A. If the decreasing argument is set to TRUE, the percentage of data points in phase B that are below the median of phase A is calculated. The PEM is expressed as a percentage ranging from 0 to 100. Higher values indicate a greater degree of improvement from phase A to phase B.

Author(s)

Juergen Wilbert

See Also

Other overlap functions: ird(), nap(), overlap(), pand(), pet(), pnd(), print.sc_cdc(), select_phases(), tau_u()

Examples

## Calculate the PEM including the Binomial and Chi-square tests for a single-case
dat <- random_scdf(5, level = 0.5)
pem(dat, chi.test = TRUE)

---

Percent exceeding the trend (PET)

Description

The pet function returns the percentage of Phase B data points that exceed the prediction based on the Phase A trend. A binomial test against a 50/50 distribution is calculated. It also calculates the percentage of Phase B data points that exceed the upper (or lower) 95 percent confidence interval of the predicted progression.

Usage

pet(data, dvar, pvar, mvar, ci = 0.95, decreasing = FALSE, phases = c(1, 2))

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
ci	Width of the confidence interval. Default is ci = 0.95.
decreasing	If you expect data to be lower in the B phase, set decreasing = TRUE. Default is decreasing = FALSE.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).

Details

The PET is calculated by first fitting a linear model to the Phase A data to estimate the trend. Then, for each data point in Phase B, it is determined whether it exceeds the predicted value from the Phase A trend. The PET is the percentage of Phase B data points that exceed this predicted value. Additionally, a binomial test is performed to assess whether the observed PET is significantly greater than what would be expected by chance (i.e., 50%).

Value

PET	Percent exceeding the trend.
ci	Width of confidence interval.
decreasing	Logical argument from function call (see Arguments above).

Author(s)

Juergen Wilbert

See Also

Other overlap functions: ird(), nap(), overlap(), pand(), pem(), pnd(), print.sc_cdc(), select_phases(), tau_u()

Examples

## Calculate the PET and use a 99%-CI for the additional calculation
# create random example data
design <- design(n = 5, slope = 0.2)
dat <- random_scdf(design, seed = 23)
pet(dat, ci = .99)

---

Piecewise linear model / piecewise regression

Description

The plm function computes a piecewise regression model (see Huitema & McKean, 2000) for one case. The function automatically creates the default model which includes trend, level, and slope effects. The model can be changed with trend, level, and slope arguments or by providing a custom formula.

Usage

plm(
  data,
  dvar,
  pvar,
  mvar,
  AR = 0,
  model = c("W", "H-M", "B&L-B", "JW"),
  family = "gaussian",
  trend = TRUE,
  level = TRUE,
  slope = TRUE,
  contrast = c("first", "preceding"),
  contrast_level = c(NA, "first", "preceding"),
  contrast_slope = c(NA, "first", "preceding"),
  formula = NULL,
  update = NULL,
  na.action = na.omit,
  r_squared = TRUE,
  var_trials = NULL,
  dvar_percentage = FALSE,
  ...
)

## S3 method for class 'sc_plm'
print(
  x,
  lag_max = 3,
  ci = 0.95,
  q = FALSE,
  r_squared = getOption("scan.rsquared"),
  ...
)

## S3 method for class 'sc_plm'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  nice = TRUE,
  ci = 0.95,
  q = FALSE,
  round = 2,
  r_squared = getOption("scan.rsquared"),
  ...
)

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
AR	Maximal lag of autoregression. Modelled based on the Autoregressive-Moving Average (ARMA) function. When AR is set, the family argument must be set to family = "gaussian".
model	Model used for calculating the dummy parameters (see Huitema & McKean, 2000). Default is model = "W". Possible values are: "B&L-B", "H-M", "W", and deprecated "JW".
family	Set the distribution family. Defaults to a gaussian distribution. See the family function for more details.
trend	A logical indicating if a trend parameters is included in the model.
level	A logical indicating if a level parameters is included in the model.
slope	A logical indicating if a slope parameters is included in the model.
contrast	Sets contrast_level and contrast_slope. Either "first", "preceding" or a contrast matrix. If NA contrast is ignored.
contrast_level	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.
contrast_slope	Either "first", "preceding" or a contrast matrix. If NA contrast_level is a copy of contrast.
formula	Defaults to the standard piecewise regression model. The parameter phase followed by the phase name (e.g., phaseB) indicates the level effect of the corresponding phase. The parameter 'inter' followed by the phase name (e.g., interB) adresses the slope effect based on the method provide in the model argument (e.g., "B&L-B"). The formula can be changed for example to include further variables into the regression model.
update	An easier way to change the regression formula (e.g., . ~ . + newvariable).
na.action	Defines how to deal with missing values.
r_squared	Either "delta", "partial", or "none".
var_trials	Name of the variable containing the number of trials (only for binomial regressions). If a single integer is provided this is considered to be a the constant number of trials across all measurements.
dvar_percentage	Only for binomial distribution. If set TRUE, the dependent variable is assumed to represent proportions ⁠[0,1]⁠. Otherwise dvar is assumed to represent counts.
...	Further arguments passed to the stats::glm() or nlme::gls() function.
x	Object
lag_max	Maximum lag to be reported for autocorrelation of residuals. Default is 3. Set FALSE for no report of autocorrelations.
ci	Print confidence intervals. Either FALSE, TRUE or a number between 0 and 1 (0.90 for a 90% intervals).
q	Logical. If set TRUE, Yule's Q is reported.
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
nice	If set TRUE (default) output values are rounded and optimized for publication tables.
round	Integer passed to the digits argument used to round values.

Details

The function uses the glm function of the stats package or the gls function of the nlme package (for auto-regression models).

Value

An object of class sc_plm.

formula	plm formula. Uselful if you want to use the update or formula argument and you don't know the names of the parameters.
model	Character string from function call (see Arguments above).
F.test	F-test values of modelfit.
r.squares	Explained variance R squared for each model parameter.
ar	Autoregression lag from function call (see Arguments above).
family	Distribution family from function call (see Arguments above).
full.model	Full regression model list from the gls or glm function.

Functions

• print(sc_plm): Print

• export(sc_plm): Export results as html table (see export())

Author(s)

Juergen Wilbert

References

Beretvas, S., & Chung, H. (2008). An evaluation of modified R2-change effect size indices for single-subject experimental designs. Evidence-Based Communication Assessment and Intervention, 2, 120-128.

Huitema, B. E., & McKean, J. W. (2000). Design specification issues in time-series intervention models. Educational and Psychological Measurement, 60, 38-58.

See Also

Other regression functions: bplm(), fetch(), hplm(), mplm(), print.sc_ac(), print.sc_bctau(), trend()

Examples

## Compute a piecewise regression model for a random single-case
set.seed(123)
AB <- design(
  phase_design = list(A = 10, B = 20),
  level = list(A = 0, B = 1), slope = list(A = 0, B = 0.05),
  trend = 0.05
)
dat <- random_scdf(design = AB)
plm(dat, AR = 3)

## Another example with a more complex design
A1B1A2B2 <- design(
  phase_design = list(A1 = 15, B1 = 20, A2 = 15, B2 = 20),
  level = list(A1 = 0, B1 = 1, A2 = -1, B2 = 1),
  slope = list(A1 = 0, B1 = 0.0, A2 = 0, B2 = 0.0),
  trend = 0.0)
dat <- random_scdf(design = A1B1A2B2, seed = 123)
plm(dat, contrast = "preceding")

## no slope effects were found. Therefore, you might want to the drop slope
## estimation:
plm(dat, slope = FALSE, contrast = "preceding")

## and now drop the trend estimation as well
plm(dat, slope = FALSE, trend = FALSE, contrast = "preceding")

## A poisson regression
example_A24 |>
  plm(family = "poisson")

## A binomial regression (frequencies as dependent variable)
plm(exampleAB_score$Christiano, family = "binomial", var_trials = "trials")

## A binomial regression (percentage as dependent variable)
exampleAB_score$Christiano |>
  transform(percentage = values/trials) |>
  set_dvar("percentage") |>
  plm(family = "binomial", var_trials = "trials", dvar_percentage = TRUE)
## Print
plm(exampleAB$Johanna) |> 
  print(ci = 0.9, r_squared = c("delta", "partial"))
## Export
plm(exampleAB$Johanna) |> export()

---

Plot random distribution

Description

This function takes the return of the rand_test function and creates a histogram with the distribution of the rand sample statistics.

Usage

plot_rand(
  object,
  type = "hist",
  xlab = NULL,
  ylab = NULL,
  title = NULL,
  text_observed = "observed",
  color = "lightgrey",
  ...
)

Arguments

object	Object returned from the rand_test() function
type	'hist' or 'xy'.
xlab	Label for the x-axis.
ylab	Label for the y-axis.
title	Plot title.
text_observed	Text for marking the number of observed statistic.
color	Bar color.
...	Further arguments passed to the plot function.

---

(Deprecated) Plot single-case data

Description

This function provides a plot of a single-case or multiple single-cases.

Usage

## S3 method for class 'scdf'
plot(...)

plotSC(
  data,
  dvar,
  pvar,
  mvar,
  ylim = NULL,
  xlim = NULL,
  xinc = 1,
  lines = NULL,
  marks = NULL,
  phase.names = NULL,
  xlab = NULL,
  ylab = NULL,
  main = "",
  case.names = NULL,
  style = getOption("scan.plot.style"),
  ...
)

Arguments

...	Further arguments passed to the plot command.
data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
ylim	Lower and upper limits of the y-axis (e.g., ylim = c(0, 20) sets the y-axis to a scale from 0 to 20). With multiple single-cases you can use ylim = c(0, NA) to scale the y-axis from 0 to the maximum of each case. ylim is not set by default, which makes scan set a proper scale based on the given data.
xlim	Lower and upper limits of the x-axis (e.g., xlim = c(0, 20) sets the x-axis to a scale from 0 to 20). With multiple single-cases you can use ylim = c(0, NA) to scale the x-axis from 0 to the maximum of each case. xlim is not set by default, which makes scan set a proper scale based on the given data.
xinc	An integer. Increment of the x-axis. 1 :each mt value will be printed, 2 : every other value, 3 : every third values etc.
lines	A list defining one or multiple lines or curves to be plotted. The argument is passed as a list (e.g., list(type = "median")). Some of the procedures can be refined with an additional argument (e.g., lines = list(type = "mean", trim = 0.2) adds a 20\ line. For multiple lines, provide a list element for each line (e.g., list( list(type = "median", col = "red"), list(type = "trend", col = "blue")). Possible lines are: "median" Separate lines for phase A and B medians. "mean" Separate lines for phase A and B means. By default it is 10\ lines = list(type = "mean", trim = 0.2) draws a 20\ "trend" Separate lines for phase A and B trends. "trendA" OLS trend line for phase A, extrapolated throughout phase B. "trendA_bisplit" Split middle (bi-split) trend line for phase A, extrapolated throughout phase B. "trendA_trisplit" Tukey tri-split trend line for phase A, extrapolated throughout phase B. "maxA/minA" Line at the level of the highest or lowest phase A score. "medianA" Line at the phase A median score. "meanA" Line at the phase A 10\ using the additional argument (e.g., lines = list(type = "meanA", trim = 0.2)). "plm" Regression lines for piecewise linear regression model. "plm.ar" Regression lines for piecewise autoregression model. The lag is specified like this: lines = list(type = "plm.ar", ar = 2). Default lag is set to 2. "movingMean" Draws a moving mean curve, with a specified lag: lines = list(type = "movingMean", lag = 2). Default is a lag 1 curve. "movingMedian" Draws a moving median curve, with a specified lag: lines = list(type = "movingMedian", lag = 3). Default is a lag 1 curve. "loreg" Draws a non-parametric local regression line. The proportion of data influencing each data point can be specified using lines = list(type = "loreg"m f = 0.66). The default is 0.5. "lty" Use this argument to define the line type. Examples are: "solid", "dashed", "dotted". "lwd" Use this argument to define the line's thickness, e.g., lwd = 4. "col" Use this argument to define the line's color, e.g., col = "red".
marks	A list of parameters defining markings of certain data points. "positions" A vector or a list of vectors indicating measurement-times to be highlighted. In case of a vector, the marked measurement-times are the same for all plotted cases. In case of a list of vectors, marks are set differently for each case. The list must have the same length as there are cases in the data file. "col" Color of the marks. "cex" Size of the marks. Use for example marks = list(positions = c(1, 8, 15), col = "red", cex = 3) to make the MTs one, eight and 18 appear big and red.
phase.names	By default phases are labeled based on the levels of the phase variable. Use this argument to specify different labels: phase.names = c("Baseline", "Intervention").
xlab	The label of the x-axis. Default is xlab = "Measurement time".
ylab	The labels of the y-axis. Default is ylab = "Score".
main	Main title of the plot.
case.names	Case names. If not provided, names are taken from the scdf. Set case.names = "" if you don't like to include case names.
style	Either a character with the name of a pre-implemented style or a style object. See style_plot to learn about this format.

Value

Returns a plot of one or multiple single-cases.

Author(s)

Juergen Wilbert

Examples

## Request the default plot of the data from Borckhardt (2014)
plot(Borckardt2014)

## Plot the three cases from Grosche (2011) and visualize the phase A trend
plot(Grosche2011, style = "grid", lines = "trendA")

## Request the local regression line for Georg from that data set and customize the plot
plot(Grosche2011$Georg, style = "sienna", ylim = c(0,NA),
       xlab = "Training session", ylab = "Words per minute",
       phase.names = c("Baseline", "Intervention"), xinc = 5,
       lines = list(type = "loreg", f = 0.2, lty = "solid", col = "black", lwd = 3))

## Plot a random MBD over three cases and mark interesting MTs
dat <- random_scdf(design = design(3))
plot(dat, marks = list(positions = list(c(2,4,5),c(1,2,3),c(7,8,9)), col = "blue",
       cex = 1.4), style = c("grid", "annotate", "tiny"))

---

Percentage of non-overlapping data (PND)

Description

This function returns the percentage of non-overlapping data. Due to its error-proneness the PND should not be used, but nap or pand instead (see Parker & Vannest, 2009).

Usage

pnd(data, dvar, pvar, decreasing = FALSE, phases = c(1, 2))

Arguments

data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
decreasing	If you expect data to be lower in the B phase, set decreasing = TRUE. Default is decreasing = FALSE.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).

Details

PND is calculated by determining the number of data points in phase B that exceed the highest data point in phase A (or are lower than the lowest data point in phase A for decreasing data) divided by the total number of data points in phase B. This value is then multiplied by 100 to get a percentage value.

Value

PND	Percentage of non-overlapping data.

Author(s)

Juergen Wilbert

See Also

Other overlap functions: ird(), nap(), overlap(), pand(), pem(), pet(), print.sc_cdc(), select_phases(), tau_u()

Examples

## Calculate the PND for multiple single-case data
pnd(GruenkeWilbert2014)

---

Empirical power analysis for single-case data

Description

Conducts a Monte-Carlo study on the test-power and alpha-error probability of a statistical function.

Usage

power_test(
  design,
  method = c("plm_level", "rand", "tauU"),
  effect = "level",
  n_sim = 100,
  design_is_one_study = TRUE,
  alpha_test = TRUE,
  power_test = TRUE,
  binom_test = FALSE,
  binom_test_alpha = FALSE,
  binom_test_power = FALSE,
  binom_test_correct = FALSE,
  ci = FALSE,
  alpha_level = 0.05
)

Arguments

design	An object returned from the design function.
method	A (named) list that defines the methods the power analysis is based on. Each element can contain a function (that takes an scdf file and returns a p value) or a character string (the name of predefined functions). default method = list("plm_level", "rand", "tauU") computes a power analysis based on tau_u(), rand_test() and plm() analyses. (Further predefined functions are: "plm_slope", "plm_poisson_level", "plm_poisson_slope", "hplm_level", "hplm_slope", "base_tau".
effect	Either "level" or "slope". The respective effect of the provided design is set to 0 when computing the alpha-error proportion.
n_sim	Number of sample studies created for the the Monte-Carlo study. Default is n = 100. Ignored if design_is_one_study = FALSE.
design_is_one_study	If TRUE, the design is assumed to define all cases of one study that is repeatedly randomly created n_sim times. If FALSE, the design is assumed to contain all cases from which a random sample is generated. This is useful for very specific complex simulation studies. In this case, n_sim indicates how many random samples are drawn from the provided design. Default is TRUE.
alpha_test	Logical. If TRUE, alpha error is calculated.
power_test	Logical. If TRUE, power is calculated.
binom_test	Shortcut. When set TRUE, binom_test_power is set to 0.80, binom_test_alpha is set to 0.05, and binom_test_correct is set to 0.875.
binom_test_alpha	Either FALSE or a value. If a value is provided, a binomial test is calculated testing if the alpha error proportion is less than the provided value.
binom_test_power	Either FALSE or a value. If a value is provided, a binomial test is calculated testing if the power is greater than the provided value.
binom_test_correct	Either FALSE or a value. If a value is provided, a binomial test is calculated testing if the correct proportion is greater than the provided value.
ci	Either FALSE or a value. If a value is provided, confidence intervals at the provided level are calculated for power, alpha error, and correct proportions.
alpha_level	Alpha level used to calculate the proportion of significant tests. Default is alpha_level = 0.05.

Details

Based on a design() object, a large number of single-cases are generated and re-analysed with a provided statistical function. The proportion of significant analyses is the test power. In a second step, a specified effect of the design object is set to 0 and again single-cases are generated and re-analysed. The proportion of significant analyses is the alpha error probability.

Value

A data frame with the power, alpha error, and correct proportions for each provided method. If binomial tests are requested, p values for these tests are also provided. If confidence intervals are requested, these are also provided.

Author(s)

Juergen Wilbert

See Also

random_scdf(), design()

Examples

## Assume you want to conduct a single-case study with 15 measurements
## (phases: A = 6 and B = 9) using a highly reliable test and
## an expected level effect of d = 1.4.
## A (strong) trend effect is trend = 0.05. What is the power?
## (Note: n_sims is set to 10. Set n_sims to 1000 for a serious calculation.)
design <- design(
  n = 1, phase_design = list(A = 6, B = 9),
  rtt = 0.8, level = 1.4, trend = 0.05
)
power_test(design, n_sim = 10)

## Would you achieve higher power by setting up a MBD with three cases?
design <- design(
  n = 3, phase_design = list(A = 6, B = 9),
  rtt = 0.8, level = 1.4, trend = 0.05
)
power_test(design, n_sim=10, method=list("hplm_level", "rand", "tauU_meta"))

---

Autocorrelation within and across phases

Description

The autocorr function calculates autocorrelations within each phase and across all phases.

Usage

## S3 method for class 'sc_ac'
print(x, digits = "auto", ...)

## S3 method for class 'sc_ac'
export(object, caption = NA, footnote = NA, filename = NA, round = 3, ...)

autocorr(data, dvar, pvar, mvar, lag_max = 3, lag.max, ...)

Arguments

x	An object returned by autocorr()
digits	The minimum number of significant digits to be use. If set to "auto" (default), values are predefined.
...	Further arguments passed to the acf() function.
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
round	Integer passed to the digits argument used to round values.
data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
lag_max, lag.max	The lag up to which autocorrelations will be computed.

Details

Autocorrelations are computed using the acf() function from the stats package. For each single-case in the scdf object, a data frame is returned containing the autocorrelations for each phase and for all phases up to the specified lag.

Value

A data frame containing separate autocorrelations for each phase and for all phases (for each single-case). If lag_max exceeds the length of a phase minus one, NA is returned for this cell.

Functions

• print(sc_ac): Print method

• export(sc_ac): Export results to html

Author(s)

Juergen Wilbert

See Also

acf()

Other regression functions: bplm(), fetch(), hplm(), mplm(), plm(), print.sc_bctau(), trend()

Examples

## Compute autocorrelations for a list of four single-cases up to lag 2.
autocorr(Huber2014, lag_max = 2)

---

Baseline corrected tau

Description

Kendall's tau correlation for the dependent variable and the phase variable is calculated after correcting for a baseline trend.

Usage

## S3 method for class 'sc_bctau'
print(x, nice = TRUE, digits = "auto", ...)

## S3 method for class 'sc_bctau'
export(
  object,
  caption = NA,
  footnote = NA,
  filename = NA,
  nice = TRUE,
  round = 2,
  ...
)

corrected_tau(
  data,
  dvar,
  pvar,
  mvar,
  phases = c(1, 2),
  alpha = 0.05,
  continuity = FALSE,
  tau_method = c("b", "a")
)

Arguments

x	An object returned by corrected_tau()
nice	If set TRUE (default) output values are rounded and optimized for publication tables.
digits	The minimum number of significant digits to be use. If set to "auto" (default), values are predefined.
...	Further parameters passed to the print function
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
round	Integer passed to the digits argument used to round values.
data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).
alpha	Sets the p-value at and below which a baseline correction is applied.
continuity	If TRUE applies a continuity correction for calculating p
tau_method	Character with values "a" or "b" (default) indicating whether Kendall Tau A or Kendall Tau B is applied.

Details

This method has been proposed by Tarlow (2016). The baseline data are checked for a significant autocorrelation (based on Kendall's Tau). If so, a non-parametric Theil-Sen regression is applied for the baseline data where the dependent values are regressed on the measurement time. The resulting slope information is then used to predict data of the B-phase. The dependent variable is now corrected for this baseline trend and the residuals of the Theil-Sen regression are taken for further calculations. Finally, Kendall's tau is calculated for the dependent variable and the dichotomous phase variable. The function here provides two extensions to this procedure: The more accurate continuity correction is applied when continuity = TRUE.

Functions

• print(sc_bctau): Print results

• export(sc_bctau): Export results as html

References

Tarlow, K. R. (2016). An Improved Rank Correlation Effect Size Statistic for Single-Case Designs: Baseline Corrected Tau. Behavior Modification, 41(4), 427–467. https://doi.org/10.1177/0145445516676750

See Also

Other regression functions: bplm(), fetch(), hplm(), mplm(), plm(), print.sc_ac(), trend()

Examples

dat <- scdf(c(A = 33,25,17,25,14,13,15, B = 15,16,16,5,7,9,6,5,3,3,8,11,7))
corrected_tau(dat)

---

Conservative Dual-Criterion Method

Description

The cdc() function applies the Conservative Dual-Criterion Method (Fisher, Kelley, & Lomas, 2003) to scdf objects. It compares phase B data points to both phase A mean and trend (OLS, bi-split, tri-split) with an additional increase/decrease of .25 SD. A binomial test against a 50/50 distribution is computed and p-values below .05 are labelled "systematic change".

Usage

## S3 method for class 'sc_cdc'
print(x, nice = TRUE, ...)

## S3 method for class 'sc_cdc'
export(object, caption = NA, footnote = NA, filename = NA, nice = TRUE, ...)

cdc(
  data,
  dvar,
  pvar,
  mvar,
  decreasing = FALSE,
  trend_method = c("OLS", "bisplit", "trisplit"),
  conservative = 0.25,
  phases = c(1, 2)
)

Arguments

x	Object
nice	If set TRUE (default) output values are rounded and optimized for publication tables.
...	Further parameters passed to the print function
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
decreasing	If you expect data to be lower in the B phase, set decreasing = TRUE. Default is decreasing = FALSE.
trend_method	Method used to calculate the trend line. Default is trend_method = "OLS". Possible values are: "OLS", "bisplit", and "trisplit". "bisplit", and "trisplit" should only be used for cases with at least five data-points in both relevant phases.
conservative	The CDC method adjusts the original mean and trend lines by adding (expected increase) or subtracting (expected decrease) an additional .25 SD before evaluating phase B data. Default is the CDC method with conservative = .25. To apply the Dual-Criterion (DC) method, set conservative = 0.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).

Value

cdc	CDC Evaluation based on a p-value below .05.
cdc_exc	Number of phase B datapoints indicating expected change.
cdc_nb	Number of phase B datapoints.
cdc_p	P value of Binomial Test.
cdc_all	Overall CDC Evaluation based on all instances/cases of a Multiple Baseline Design.
N	Number of cases.
decreasing	Logical argument from function call (see Arguments above).
conservative	Numeric argument from function call (see Arguments above).
case_names	Assigned name of single-case.
phases	-

Functions

• print(sc_cdc): Print results

• export(sc_cdc): Export html results

Author(s)

Timo Lueke

References

Fisher, W. W., Kelley, M. E., & Lomas, J. E. (2003). Visual Aids and Structured Criteria for Improving Visual Inspection and Interpretation of Single-Case Designs. Journal of Applied Behavior Analysis, 36, 387-406. https://doi.org/10.1901/jaba.2003.36-387

See Also

Other overlap functions: ird(), nap(), overlap(), pand(), pem(), pet(), pnd(), select_phases(), tau_u()

Examples

## Apply the CDC method (standard OLS line)
design <- design(n = 1, slope = 0.2)
dat <- random_scdf(design, seed = 42)
cdc(dat)

## Apply the CDC with Koenig's bi-split and an expected decrease in phase B.
cdc(exampleAB_decreasing, decreasing = TRUE, trend_method = "bisplit")

## Apply the CDC with Tukey's tri-split, comparing the first and fourth phase
cdc(exampleABAB, trend_method = "trisplit", phases = c(1,4))

## Apply the Dual-Criterion (DC) method (i.e., mean and trend without
##shifting).
cdc(
 exampleAB_decreasing,
 decreasing = TRUE,
 trend_method = "bisplit",
 conservative = 0
)

---

Handling outliers in single-case data

Description

Identifies and drops outliers within a single-case data frame (scdf). Outliers can be identified based on mean average deviation (MAD), standard deviation (SD), confidence intervals (CI), or Cook's Distance from a Piecewise Linear Regression Model.

Usage

## S3 method for class 'sc_outlier'
print(x, digits = "auto", ...)

## S3 method for class 'sc_outlier'
export(object, caption = NA, footnote = NA, filename = NA, ...)

outlier(
  data,
  dvar,
  pvar,
  mvar,
  method = c("MAD", "Cook", "SD", "CI"),
  criteria = 3.5
)

Arguments

x	An object returned by outlier()
digits	The minimum number of significant digits to be use. If set to "auto" (default), values are predefined.
...	Further parameters passed to the print function
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
mvar	Character string with the name of the measurement time variable. Defaults to the attributes in the scdf file.
method	Specifies the method for outlier identification. Set method = "MAD" for mean average deiviation, method = "SD" for standard deviations, method = "CI" for confidence intervals, method = "Cook" for Cook's Distance based on the Piecewise Linear Regression Model.
criteria	Specifies the criteria for outlier identification. Based on the method setting.

Details

For method = "SD", criteria = 2 would refer t0 two standard deviations. For method = "MAD", criteria = 3.5 would refer to 3.5 times the mean average deviation. For method = "CI", criteria = 0.99 would refer to a 99 percent confidence interval. For method = "cook", criteria = "4/n" would refer to a Cook's Distance greater than 4/n.

Value

data	A single-case data frame with substituted outliers.
dropped.n	A list with the number of dropped data points for each single-case.
dropped.mt	A list with the measurement-times of dropped data points for each single-case (values are based on the mt variable of each single-case data frame).
sd.matrix	A list with a matrix for each case with values for the upper and lower boundaries based on the standard deviation.
ci.matrix	A list with a matrix for each single-case with values for the upper and lower boundaries based on the confidence interval.
cook	A list of Cook's Distances for each measurement of each single-case.
criteria	Criteria used for outlier analysis.
N	Number of single-cases.
case.names	Case identifier.

Functions

• print(sc_outlier): Print results

• export(sc_outlier): Export html results

Author(s)

Juergen Wilbert

See Also

Other data manipulation functions: add_l2(), as.data.frame.scdf(), as_scdf(), batch_apply(), fill_missing(), moving_median(), ranks(), rescale(), scdf(), select_cases(), set_vars(), shift(), smooth_cases(), standardize(), truncate_phase()

Examples

## Identify outliers using 1.5 standard deviations as criterion
susanne <- random_scdf(level = 1.0)
res_outlier <- outlier(susanne, method = "SD", criteria = 1.5)
res_outlier

## Identify outliers in the original data from Grosche (2011)
## using Cook's Distance greater than 4/n as criterion
res_outlier <- outlier(Grosche2011, method = "Cook", criteria = "4/n")
res_outlier

---

Randomization Tests for single-case data

Description

The rand_test function computes a randomization test for single or multiple baseline single-case data. The function is based on an algorithm from the SCRT package (Bulte & Onghena, 2009, 2012), but rewritten and extended for the use in AB designs.

Usage

## S3 method for class 'sc_rand'
print(x, ...)

## S3 method for class 'sc_rand'
export(object, caption = NA, footnote = NA, filename = NA, ...)

rand_test(
  data,
  dvar,
  pvar,
  statistic = c("Mean B-A", "Mean A-B", "Median B-A", "Median A-B", "Mean |A-B|",
    "Median |A-B|", "SMD hedges", "SMD glass", "W-test", "T-test", "NAP",
    "NAP decreasing", "Slope B-A", "Slope A-B"),
  statistic_function = NULL,
  number = 500,
  complete = FALSE,
  limit = 5,
  startpoints = NA,
  exclude.equal = FALSE,
  phases = c(1, 2),
  graph = FALSE,
  output = NULL,
  seed = NULL
)

Arguments

x	An object returned by rand_test()
...	Further parameters passed to the print function
object	An scdf or an object exported from a scan function.
caption	Character string with table caption. If left NA (default) a caption will be created based on the exported object.
footnote	Character string with table footnote. If left NA (default) a footnote will be created based on the exported object.
filename	String containing the file name. If a filename is given the output will be written to that file.
data	A single-case data frame. See scdf() to learn about this format.
dvar	Character string with the name of the dependent variable. Defaults to the attributes in the scdf file.
pvar	Character string with the name of the phase variable. Defaults to the attributes in the scdf file.
statistic	Defines the statistic on which the comparison of phases A and B is based on. Default setting is statistic = "Mean B-A". See details.
statistic_function	A list with a user defined function to calculate the statistic. When set, overwrites the statistic argument. See details.
number	Sample size of the randomization distribution. The exactness of the p-value can not exceed $1/number$ (i.e., number = 100 results in p-values with an exactness of one percent). Default is number = 500. For faster processing use number = 100. For more precise p-values set number = 1000).
complete	If TRUE, the distribution is based on a complete permutation of all possible starting combinations. This setting overwrites the number Argument. The default setting is FALSE.
limit	Minimal number of data points per phase in the sample. The first number refers to the A-phase and the second to the B-phase (e.g., limit = c(5,3)). If only one number is given, this number is applied to both phases. Default is limit = 5.
startpoints	Alternative to the limit-parameter startpoints exactly defines the possible start points of phase B (e.g., startpoints = 4:9 restricts the phase B start points to measurements 4 to 9. startpoints overruns the limit-parameter. If a list of start points is provided, each single-case can have different start points (e.g., startpoints = list(4:9, 5:10) for a two-case design). Default is startpoints = NA, which uses the limit-parameter to define possible start points.
exclude.equal	If set to exclude.equal = FALSE, which is the default, random distribution values equal to the observed distribution are counted as null-hypothesis conform. That is, they decrease the probability of rejecting the null-hypothesis (increase the p-value). exclude.equal should be set to TRUE if you analyse one single-case design (not a multiple baseline data set) to reach a sufficient power. But be aware, that it increases the chance of an alpha-error. If exclude.equal = "auto" is used, the function automatically sets exclude.equal = TRUE for single-case designs and to FALSE for multiple-case designs.
phases	A vector of two characters or numbers indicating the two phases that should be compared. E.g., phases = c("A","C") or phases = c(2,4) for comparing the second to the fourth phase. Phases could be combined by providing a list with two elements. E.g., phases = list(A = c(1,3), B = c(2,4)) will compare phases 1 and 3 (as A) against 2 and 4 (as B). Default is phases = c(1,2).
graph	If graph = TRUE, a histogram of the resulting distribution is plotted. It is FALSE by default. Note: use the more versatile plot_rand() function instead.
output	(deprecated and not implemented)
seed	A seed number for the random generator. Default is NULL.

Value

An object of class sc_rand. It is a list containing the following elements:

statistic	Character string from function call (see Arguments above).
N	Number of single-cases.
n1	Number of data points in phase A.
n2	Number of data points in phase B.
limit	Numeric from function call (see Arguments above).
startpoints	A vector defining the start points passed from the function call (see Arguments above).
p.value	P-value of the randomization test for the given data.
number	Sample size of randomization distribution from function call (see Arguments above).
complete	Logical argument from function call (see Arguments above).
observed.statistic	Test statistic observed for the given single-case data. (see statistic in the Arguments above.)
Z	Z-value of observed test statistic.
p.z.single	Probability of z-value.
distribution	Test statistic distribution from randomized data sets.
possible.combinations	Number of possible combinations under the given restrictions.
auto.corrected.number	TRUE indicates that a corrected number of combinations was used. This happens, if the number of possible combinations (under the given restrictions) undercuts the requested number of combinations.
ecxlude.equal	see argument above
testdirection	Indicates the direction of the test ("greater" or "less").

Functions

• print(sc_rand): Print results

• export(sc_rand): Export html results

Details

Predefinded statisic

Use the statistic argument to choose a predefnied statistic. The following comparisons are possible:

• ⁠Mean A-B⁠: Uses the difference between the mean of phase A and the mean of phase B. This is appropriate if a decrease of scores was expected for phase B.

• ⁠Mean B-A⁠: Uses the difference between the mean of phase B and the mean of phase A. This is appropriate if an increase of scores was expected for phase B.

• ⁠Mean |A-B|⁠: Uses the absolute value of the difference between the means of phases A and B.

• ⁠Median A-B⁠: The same as ⁠Mean A-B⁠, but based on the median.

• ⁠Median B-A⁠: The same as ⁠Mean B-A⁠, but based on the median.

• ⁠SMD hedges / SMD glass⁠: Standardizes mean difference of B-A as Hedges's g or Glass' delta.

• NAP: Non-overlap of all pairs.

• W-test: Wilcoxon-test statistic W.

• T-test: T-test statistic t.

Create own statistic function

Use the statistic_function argument to proved your own function in a list. This list must have an element named statistic with a function that takes two arguments a and b and returns a single numeric value. E.g. ⁠list(statistic = function(a, b) mean(a) - mean(b)⁠. A second element of the list is named aggregate which takes a function with one numeric argument that returns a numeric argument. This function is used to aggregate the values of a multiple case design. If you do not provide this element, it uses the default function(x) sum(x)/length(x). The third optional argument is name which provides a name for your user function.

Author(s)

Juergen Wilbert

References

Bulte, I., & Onghena, P. (2009). Randomization tests for multiple-baseline designs: An extension of the SCRT-R package. Behavior Research Methods, 41, 477-485.

Bulte, I., & Onghena, P. (2012). SCRT: Single-Case Randomization Tests. Available from: https://CRAN.R-project.org/package=SCRT

Examples

## Compute a randomization test on the first case of the byHeart2011 data and include a graph
rand_test(byHeart2011[1], statistic = "Median B-A", graph = TRUE, seed = 123)

## Compute a randomization test on the Grosche2011 data using complete permutation
rand_test(Grosche2011, statistic = "Median B-A", complete = TRUE, limit = 4, seed = 123)

---