Type: Package
Title: Single-Case Visual Analysis
Version: 1.3.1
Date: 2019-12-20
Author: Isis Bulte, Tamal Kumar De, Patrick Onghena
Maintainer: Tamal Kumar De <tamalkumar.de@kuleuven.be>
Description: Make graphical representations of single case data and transform graphical displays back to raw data, as discussed in Bulte and Onghena (2013) <doi:10.22237/jmasm/1383280020>. The package also includes tools for visually analyzing single-case data, by displaying central location, variability and trend.
License: GPL-2 | GPL-3 [expanded from: GPL (≥ 2)]
Imports: ggExtra, ggplot2, graphics, plotly, scales, stats, utils
Repository: CRAN
NeedsCompilation: no
Packaged: 2019-12-20 19:35:55 UTC; Tamal
Date/Publication: 2020-01-09 22:50:10 UTC

Single-Case Visual Analysis

Description

Make graphical representations of single case data and transform graphical displays back to raw data. The package also includes tools for visually analyzing single-case data, by displaying central location, variability and trend.

Details

Package: SCVA
Type: Package
Version: 1.3.1
Date: 2019-12-20
License: GPL version 2 or newer

Author(s)

Isis Bulte, Tamal Kumar De, Patrick Onghena

Maintainer: Tamal Kumar De <tamalkumar.de@kuleuven.be>

Hypothetical AB data

Description

Hypothetical data collected in an AB phase design with 27 measurement times.

Usage

data(AB)

Format

A data frame with 27 observations.

References

Bulte, I., & Onghena, P. (2012). When the truth hits you between the eyes: A software tool for the visual analysis of single-case experimental data. Methodology, 8, 104-114.

Examples

data(AB)

Graphical representation of single-case data

Description

The observed single-case data are plotted.

Usage

graph(design,data=read.table(file.choose(new=FALSE)),xlab="Measurement Times",
ylab="Scores",ylim=NULL,legendxy=NULL,labels=c("A","B","A","B"))

Arguments

design

Type of single-case design: "AB", "ABA", "ABAB", "CRD"(completely randomized design), "RBD" (randomized block design), "ATD" (alternating treatments design), "MBD" (multiple-baseline AB design) or "Custom" (user specified design).

data

File in which the data can be found. Default: a window pops up in which the file can be selected.

xlab

Label x axis.

ylab

Label y axis.

ylim

Y axis limits in the form c(min, max).

legendxy

Optional legend location x and y coordinates in the form c(x coordinate, y coordinate). Only used when design is "CRD", "RBD", "ATD" or "Custom".

labels

Optional labels for treatment levels in the form c("A", "B").

Details

When using the default data argument, a window will pop up to ask in what file the data can be found. This text file containing the data should consist of two columns for single-case phase and alternation designs: the first with the condition labels and the second with the obtained scores. For multiple-baseline designs it should consist of these two columns for EACH unit. This way, each row represents one measurement occasion. It is important not to label the rows or columns.

Missing data should be indicated as NA. For calculations, missing data are omitted.

For alternation designs, after the plot is drawn, the location of the legend should be indicated by a left mouse click.

References

Bulte, I., & Onghena, P. (2008). An R package for single-case randomization tests. Behavior Research Methods, 40, 467-478.

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). When the truth hits you between the eyes: A software tool for the visual analysis of single-case experimental data. Methodology, 8, 104-114.

http://ppw.kuleuven.be/home/english/research/mesrg

See Also

graph.CL to plot a measure of central tendency as a line parallel to the abscissa.

graph.VAR to display variability information.

graph.TREND to display a possible trend in the data.

graphly to display an interactive plot.

Examples

data(AB)
graph(design = "AB", data = AB)

Plot a measure of central tendency

Description

A measure of central tendency ((trimmed) mean, (broadened) median, M-estimator) is plotted as a horizontal reference line superimposed on the raw time series data.

Usage

graph.CL(design,CL,tr,data=read.table(file.choose(new=FALSE)),xlab="Measurement Times",
ylab="Scores",ylim=NULL,legendxy=NULL,labels=c("A","B","A","B"))

Arguments

design

Type of single-case design: "AB", "ABA", "ABAB", "CRD"(completely randomized design), "RBD" (randomized block design), "ATD" (alternating treatments design), "MBD" (multiple-baseline AB design) or "Custom" (user specified design).

CL

Measure of central tendency: "mean", "median", "bmed" (broadened median), "trimmean" (trimmed mean), or "mest" (M-estimator of location).

tr

If CL="trimmean": the percentage of observations that has to be removed from the end of the distribution before computing the mean. It can be any value from 0 (regular arithmetic mean) to 0.5. Usually 20 percent of the observations is trimmed (so tr=0.2). If CL="mest": the desired value for the constant K. Usually a percentile of the standard normal distribution is chosen. Wilcox (2005) suggests using K=1.28, which corresponds to the 90th percentile of the standard normal distribution and covers 80 percent of the underlying distribution.

data

File in which the data can be found. Default: a window pops up in which the file can be selected.

xlab

Label x axis.

ylab

Label y axis.

ylim

Y axis limits in the form c(min, max).

legendxy

Optional legend location x and y coordinates in the form c(x coordinate, y coordinate). Only used when design is "CRD", "RBD", "ATD" or "Custom".

labels

Optional labels for treatment levels in the form c("A", "B").

Details

When using the default data argument, a window will pop up to ask in what file the data can be found. This text file containing the data should consist of two columns for single-case phase and alternation designs: the first with the condition labels and the second with the obtained scores. For multiple-baseline designs it should consist of these two columns for EACH unit. This way, each row represents one measurement occasion. It is important not to label the rows or columns.

Missing data should be indicated as NA. For calculations, missing data are omitted. Please note that some of the complicated plots may not work if there is missing data.

For alternation designs, after the plot is drawn, the location of the legend should be indicated by a left mouse click.

Note

For the calculation of the M-estimator of location, the function mest(x,bend=1.28) from Wilcox (2005) is used.

Wilcox, R.R. (2005). Introduction to robust estimation and hypothesis testing (2nd ed.). San Diego, CA: Elsevier Academic Press.

References

Bulte, I., & Onghena, P. (2012). When the truth hits you between the eyes: A software tool for the visual analysis of single-case experimental data. Methodology, 8, 104-114.

http://ppw.kuleuven.be/home/english/research/mesrg

See Also

graph to simply plot raw single-case data.

graph.VAR to display variability information.

graph.TREND to display a possible trend in the data.

graphly to display an interactive plot.

Examples

data(AB)
graph.CL(design = "AB", CL = "mean", data = AB)

Plot a trend in central location

Description

Visualizes systematic shifts in central location over time using several methods. A vertical line graph plots the deviations from each data point to a measure of central tendency against time. Regression lines superimpose a linear function on the raw data by means of least squares regression, the split-middle method or the resistant trend line fitting method. The presence of a nonlinear trend can be displayed with running medians.

Usage

graph.TREND(design, TREND, CL, tr, data = read.table(file.choose(new = FALSE)), 
xlab = NULL, ylab = NULL, ylim = NULL, legendxy = NULL, labels = c("A", "B", "A", "B"))

Arguments

design

Type of single-case design: "AB", "ABA", "ABAB", "CRD"(completely randomized design), "RBD" (randomized block design), "ATD" (alternating treatments design), "MBD" (multiple-baseline AB design) or "Custom" (user specified design).

TREND

Trend visualization: vertical line plot ("VLP"); trend lines by means of least squares regression ("LSR"), split-middle method ("SM"), resistant trend line fitting ("RTL"), or running medians ("RM3", "RM5" or "RM42", depending on the desired batch size).

CL

Measure of central tendency: "mean", "median", "bmed" (broadened median), "trimmean" (trimmed mean), or "mest" (M-estimator of location).

tr

If CL="trimmean": the percentage of observations that has to be removed from the end of the distribution before computing the mean. It can be any value from 0 (regular arithmetic mean) to 0.5. Usually 20 percent of the observations is trimmed (so tr=0.2). If CL="mest": the desired value for the constant K. Usually a percentile of the standard normal distribution is chosen. Wilcox (2005) suggests using K=1.28, which corresponds to the 90th percentile of the standard normal distribution and covers 80 percent of the underlying distribution.

data

File in which the data can be found. Default: a window pops up in which the file can be selected.

xlab

Label x axis.

ylab

Label y axis.

ylim

Y axis limits in the form c(min, max).

legendxy

Optional legend location x and y coordinates in the form c(x coordinate, y coordinate). Only used when design is "CRD", "RBD", "ATD" or "Custom".

labels

Optional labels for treatment levels in the form c("A", "B").

Details

When using the default data argument, a window will pop up to ask in what file the data can be found. This text file containing the data should consist of two columns for single-case phase and alternation designs: the first with the condition labels and the second with the obtained scores. For multiple-baseline designs it should consist of these two columns for EACH unit. This way, each row represents one measurement occasion. It is important not to label the rows or columns.

Missing data should be indicated as NA. For calculations, missing data are omitted. Please note that some of the complicated plots may not work if there is missing data.

For alternation designs, after the plot is drawn, the location of the legend should be indicated by a left mouse click.

Note

For the calculation of the M-estimator of location, the function mest(x,bend=1.28) from Wilcox (2005) is used.

Wilcox, R.R. (2005). Introduction to robust estimation and hypothesis testing (2nd ed.). San Diego, CA: Elsevier Academic Press.

References

Bulte, I., & Onghena, P. (2012). When the truth hits you between the eyes: A software tool for the visual analysis of single-case experimental data. Methodology, 8, 104-114.

http://ppw.kuleuven.be/home/english/research/mesrg

See Also

graph to simply plot raw single-case data.

graph.CL to plot a measure of central tendency as a line parallel to the abscissa.

graph.VAR to display variability information.

graphly to display an interactive plot.

Examples

data(AB)
graph.TREND(design = "AB", TREND = "VLP", CL = "mean", data = AB)
graph.TREND(design = "AB", TREND = "LSR", data = AB)
graph.TREND(design = "AB", TREND = "SM", data = AB)
graph.TREND(design = "AB", TREND = "RTL", data = AB)
graph.TREND(design = "AB", TREND = "RM3", data = AB)
graph.TREND(design = "AB", TREND = "RM5", data = AB)
graph.TREND(design = "AB", TREND = "RM42", data = AB)

Plot an estimate of variability

Description

Information about variability in the data is displayed by three methods. Range bar graphs consist of a vertical line for each phase, created by connecting three points: an estimate of central tendency ((trimmed) mean, (broadened) median, M-estimator), the minimum and the maximum. Range lines consist of a pair of lines parallel to the X-axis, passing through the lowest and highest values for each phase, and superimposed on the raw data. Trended ranges display changes in variability within phases. For all these methods, the influence of outliers may be lessend by using a trimmed range, in which only a sample of the data set is used.

Usage

graph.VAR(design, VAR, dataset = "regular", CL, tr, 
data = read.table(file.choose(new = FALSE)), xlab = NULL, ylab = NULL, 
ylim = NULL, legendxy = NULL, labels = c("A", "B", "A", "B"))

Arguments

design

Type of single-case design: "AB", "ABA", "ABAB", "CRD"(completely randomized design), "RBD" (randomized block design), "ATD" (alternating treatments design), "MBD" (multiple-baseline AB design) or "Custom" (user specified design).

VAR

Estimate of variability: range bar graph ("RB"), range lines ("RL"), or trended range ("TR").

dataset

Use the whole dataset ("regular") or reduce the influence of outliers by removing the 10-20 percent extreme values from each phase ("trimmed"). Default: the whole dataset is used.

CL

Measure of central tendency: "mean", "median", "bmed" (broadened median), "trimmean" (trimmed mean), or "mest" (M-estimator of location).

tr

If CL="trimmean": the percentage of observations that has to be removed from the end of the distribution before computing the mean. It can be any value from 0 (regular arithmetic mean) to 0.5. Usually 20 percent of the observations is trimmed (so tr=0.2). If CL="mest": the desired value for the constant K. Usually a percentile of the standard normal distribution is chosen. Wilcox (2005) suggests using K=1.28, which corresponds to the 90th percentile of the standard normal distribution and covers 80 percent of the underlying distribution.

data

File in which the data can be found. Default: a window pops up in which the file can be selected.

xlab

Label x axis.

ylab

Label y axis.

ylim

Y axis limits in the form c(min, max).

legendxy

Optional legend location x and y coordinates in the form c(x coordinate, y coordinate). Only used when design is "CRD", "RBD", "ATD" or "Custom".

labels

Optional labels for treatment levels in the form c("A", "B").

Details

When using the default data argument, a window will pop up to ask in what file the data can be found. This text file containing the data should consist of two columns for single-case phase and alternation designs: the first with the condition labels and the second with the obtained scores. For multiple-baseline designs it should consist of these two columns for EACH unit. This way, each row represents one measurement occasion. It is important not to label the rows or columns.

Missing data should be indicated as NA. For calculations, missing data are omitted. Please note that some of the complicated plots may not work if there is missing data.

For alternation designs, after the plot is drawn, the location of the legend should be indicated by a left mouse click.

Note

For the calculation of the M-estimator of location, the function mest(x,bend=1.28) from Wilcox (2005) is used.

Wilcox, R.R. (2005). Introduction to robust estimation and hypothesis testing (2nd ed.). San Diego, CA: Elsevier Academic Press.

References

Bulte, I., & Onghena, P. (2012). When the truth hits you between the eyes: A software tool for the visual analysis of single-case experimental data. Methodology, 8, 104-114.

http://ppw.kuleuven.be/home/english/research/mesrg

See Also

graph to simply plot raw single-case data.

graph.CL to plot a measure of central tendency as a line parallel to the abscissa.

graph.TREND to display a possible trend in the data.

graphly to display an interactive plot.

Examples

data(AB)
graph.VAR(design = "AB", VAR = "RB", CL = "mean", data = AB)
graph.VAR(design = "AB", VAR = "RL", data = AB)
graph.VAR(design = "AB", VAR = "TR", data = AB)
graph.VAR(design = "AB", VAR = "RL", dataset = "trimmed", data = AB)

Extract raw data from graphs

Description

Extract data values from existing graphs in jpeg format.

Usage

graph.extract(MT, refX, refY, save = "no", image = read.jpeg(file.choose()))

Arguments

MT

Measurement times: number of observations

refX

2 reference values for the X scale (e.g., refX=c(2,14)).

refY

2 reference values for the Y scale (e.g., refY=c(10,16)).

save

Save the extracted data points to a file (save="yes") or just see them as output in the R console (default: save="no").

image

Jpeg file in which the graph can be found. Default: a window pops up in which the file can be selected.

Details

When using the default image argument, a window will pop up to ask in what jpeg file the graph can be found.

Then the reference values should be located on the graph by clicking with the left mouse button: first the X values and then the Y values. The marked reference points are indicated with a blue cross.

Then each data point should be located sequentially. The marked data points are indicated with a red circle.

When finished, the calibrated true data points are displayed as output in the R console and plotted in a new graph, as a quick visual check.

When choosing to save these data values to a file (save="yes"), another window will pop up to ask where to save them. Here one can creat a new txt file in the folder of choice.

Note

This function is an adaptation of: Timothee. (2010, March 5). Data visualization (in R). Getting data from an image (introductory post). [Web log message]. Retrieved from http://rdataviz.wordpress.com/2010/03/05/getting-data-from-an-image-introductory-post/.

We would like to thank David Howell for pointing us to this function.

The function based on functions adopted from the ReadImages package, which has been orphaned and archived by CRAN.

References

Bulte, I., & Onghena, P. (2012). When the truth hits you between the eyes: A software tool for the visual analysis of single-case experimental data. Methodology, 8, 104-114.

http://ppw.kuleuven.be/home/english/research/mesrg

Interactive plot of single-case data

Description

The observed single-case data are plotted using plotly, a web-based interactive charting library.

Usage

graphly(design,data=read.table(file.choose(new=FALSE)),xlab="Measurement Times",
ylab="Scores",ylim=NULL,labels=c("A","B","A","B"))

Arguments

design

Type of single-case design: "AB", "ABA", "ABAB", "CRD"(completely randomized design), "RBD" (randomized block design), "ATD" (alternating treatments design), "MBD" (multiple-baseline AB design) or "Custom" (user specified design).

data

File in which the data can be found. Default: a window pops up in which the file can be selected.

xlab

Label x axis.

ylab

Label y axis.

ylim

Y axis limits in the form c(min, max).

labels

Optional labels for treatment levels in the form c("A", "B").

Details

When using the default data argument, a window will pop up to ask in what file the data can be found. This text file containing the data should consist of two columns for single-case phase and alternation designs: the first with the condition labels and the second with the obtained scores. For multiple-baseline designs it should consist of these two columns for EACH unit. This way, each row represents one measurement occasion. It is important not to label the rows or columns.

Missing data should be indicated as NA. For calculations, missing data are omitted.

References

Bulte, I., & Onghena, P. (2008). An R package for single-case randomization tests. Behavior Research Methods, 40, 467-478.

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). When the truth hits you between the eyes: A software tool for the visual analysis of single-case experimental data. Methodology, 8, 104-114.

http://ppw.kuleuven.be/home/english/research/mesrg

https://plotly-r.com/overview.html

See Also

graph to simply plot raw single-case data.

graph.CL to plot a measure of central tendency as a line parallel to the abscissa.

graph.VAR to display variability information.

graph.TREND to display a possible trend in the data.

Examples

data(AB)
graphly(design = "AB", data = AB)