genlog: Generalized Logistic Analysis

Description Usage Arguments Details Value Author(s) References See Also Examples

View source: R/genlog.R

Description

This function implements the generalized logistic analysis introduced in Verboon & Peters (2017). This analysis fits a logistic function (i.e. a sigmoid) to a data series. This is useful when analysing single case designs. The function enables easy customization of the main plot elements and easy saving of the plot with anti-aliasing. ggGenLogPlot does most of the plotting, and can be useful when trying to figure out sensible starting and boundary/constraint values. genlogCompleteStartValues tries to compute sensible starting and boundary/constraint values based on the data.

Usage

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
genlog(data,
       timeVar = 1,
       yVar = 2,
       phaseVar = NULL,
       baselineMeasurements = NULL,
       yRange = NULL,
       startInflection = NULL,
       startBase = NULL,
       startTop = NULL,
       startGrowthRate = NULL,
       startV = 1,
       inflectionPointBounds = NULL,
       growthRateBounds = c(-2, 2),
       baseMargin = c(0, 3),
       topMargin = c(-3, 0),
       baseBounds = NULL,
       topBounds = NULL,
       vBounds = c(1, 1),
       changeDelay = 4,
       colors = list(bottomBound = viridis(4)[4],
                     topBound = viridis(40)[37],
                     curve = viridis(4)[3],
                     mid = viridis(4)[2],
                     intervention = viridis(4)[1],
                     points = "black",
                     outsideRange = "black"),
       alphas = list(outsideRange = .2,
                     bounds = 0,
                     points = .5,
                     mid = 0),
       theme = theme_minimal(),
       pointSize = 2,
       lineSize = 0.5,
       yBreaks = NULL,
       initialValuesLineType = "blank",
       curveSizeMultiplier = 2,
       showPlot = TRUE,
       plotLabs = NULL,
       outputFile = NULL,
       outputWidth = 16,
       outputHeight = 16,
       ggsaveParams = list(units = "cm",
                           dpi = 300,
                           type = "cairo"),
       maxiter = NULL)

Arguments

data

The dataframe containing the variables for the analysis.

timeVar

The name of the variable containing the measurement moments (or an index of measurement moments). An index can also be specified, and assumed to be 1 if omitted.

yVar

The name of the dependent variable. An index can also be specified, and assumed to be 2 if omitted.

phaseVar

The variable containing the phase of each measurement. Note that this normally should only have two possible values.

baselineMeasurements

If no phaseVar is specified, baselineMeasurements can be used to specify the number of baseline measurements, which is then used to construct the phaseVar dummy variable.

yRange

This can be used to manually specify the possible values that the dependent variable can take. If no startBase and startTop are specified, the range of the dependent variable is used instead.

startInflection, startBase, startTop, startGrowthRate, startV

The starting values used when estimating the sigmoid using minpack.lm's nlsLM function. startX specifies the starting value to use for the measurement moment when the change is fastest (i.e. the slope of the sigmoid has the largest value); startBase and startTop specify the starting values to use for the base (floor) and top (ceiling), the plateaus of relative stability between which the sigmoid described the shift; startGrowthRate specifies the starting value for the growth rate; and startV specifies the starting value for the v parameter.

inflectionPointBounds, growthRateBounds, baseMargin, topMargin, baseBounds, topBounds, vBounds

These values specify constraints to respect when estimating the parameters of the sigmoid function using minpack.lm's nlsLM. changeInitiationBounds specifies between which values the initiation of the shift must occur; growthRateBounds describes the bounds constraining the possible values for the growth rate; baseBounds and topBounds specify the constraints for possible values for the base (floor) and top (ceiling), the plateaus of relative stability between which the sigmoid described the shift; and if these are not specified, baseMargin and topMargin are used in combination with the range of the dependent variable to set these bounds (also see yRange); and finally, vBounds specifies the possible values that constrain the v parameter.

changeDelay

The number of measurements to add to the intervention moment when setting the initial value for the inflection point.

colors

The colors to use for the different plot elements.

alphas

The alpha values (transparency, or rather, 'obliqueness', with 0 indicating full transparency and 1 indicating full visibility) to use for the different plot elements.

theme

The theme to use in the plot.

pointSize,lineSize

The sizes of points and lines in the plot.

yBreaks

If NULL, the pretty function is used to estimate the best breaks for the Y axis. If a value is supplied, this value is used as the size of intervals between the (floored) minimum and (ceilinged) maximum of yRange (e.g. if yBreaks is 1, a break point every integer; if 2 and the minimum is 1 and the maximum is 7, breaks at 1, 3, 5 and 7; etc).

initialValuesLineType

The line type to use for the initial values; by default set to "blank" for genlog, to hide them, and to "dashed" for ggGenLogPlot.

curveSizeMultiplier

A multiplyer for the curve size compared to the other lines (e.g. specify '2' to have a curve of twice the size).

showPlot

Whether to show the plot or not.

plotLabs

A list with arguments to the ggplot2 labs function, which can be used to conveniently set plot labels.

outputFile

If not NULL, the path and filename specifying where to save the plot.

outputWidth, outputHeight

The dimensions of the plot when saving it (in units specified in ggsaveParams).

ggsaveParams

The parameters to use when saving the plot, passed on to ggsave.

maxiter

The maximum number of iterations used by nlsLM.

Details

For details, see Verboon & Peters (2017).

Value

Mainly, this function prints its results, but it also returns them in an object containing three lists:

input

The arguments specified when calling the function

intermediate

Intermediat objects and values

output

The results such as the plot.

Author(s)

Peter Verboon & Gjalt-Jorn Peters (both at the Open University of the Netherlands)

Maintainer: Gjalt-Jorn Peters <gjalt-jorn@userfriendlyscience.com>

References

Verboon, P. & Peters, G.-J. Y. (2018) Applying the generalised logistic model in single case designs: modelling treatment-induced shifts. PsyArXiv https://doi.org/10.17605/osf.io/ad5eh

See Also

genlogFunction

Examples

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
### Load dataset
data(Singh);

### Extract Jason
dat <- Singh[Singh$tier==1, ];

### Conduct piecewise regression analysis
genlog(dat,
       timeVar='time',
       yVar='score_physical',
       phaseVar='phase');

userfriendlyscience documentation built on May 2, 2019, 1:09 p.m.