| Version: | 0.1.2 |
| Date: | 2023-08-23 |
| Title: | Behavioral Economic Easy Demand |
| Author: | Brent Kaplan [aut, cre, cph], Shawn Gilroy [ctb] |
| Maintainer: | Brent Kaplan <bkaplan.ku@gmail.com> |
| Description: | Facilitates many of the analyses performed in studies of behavioral economic demand. The package supports commonly-used options for modeling operant demand including (1) data screening proposed by Stein, Koffarnus, Snider, Quisenberry, & Bickel (2015; <doi:10.1037/pha0000020>), (2) fitting models of demand such as linear (Hursh, Raslear, Bauman, & Black, 1989, <doi:10.1007/978-94-009-2470-3_22>), exponential (Hursh & Silberberg, 2008, <doi:10.1037/0033-295X.115.1.186>) and modified exponential (Koffarnus, Franck, Stein, & Bickel, 2015, <doi:10.1037/pha0000045>), and (3) calculating numerous measures relevant to applied behavioral economists (Intensity, Pmax, Omax). Also supports plotting and comparing data. |
| Depends: | R (≥ 2.5) |
| Imports: | nlsr, nlstools, nls2, ggplot2, reshape2, stats, optimx |
| Suggests: | openxlsx, knitr, dplyr, tidyr, tidyverse, rmarkdown |
| License: | GPL-2 | file LICENSE |
| URL: | https://github.com/brentkaplan/beezdemand |
| Encoding: | UTF-8 |
| LazyData: | true |
| RoxygenNote: | 7.2.3 |
| VignetteBuilder: | knitr |
| NeedsCompilation: | no |
| Packaged: | 2023-08-26 21:11:10 UTC; brent |
| Repository: | CRAN |
| Date/Publication: | 2023-08-26 21:30:02 UTC |
ChangeData
Description
Changes demand data
Usage
ChangeData(
dat,
nrepl = 1,
replnum = 0.01,
rem0 = FALSE,
remq0e = FALSE,
replfree = NULL,
xcol = "x",
ycol = "y",
idcol = "id"
)
Arguments
dat |
A long form dataframe |
nrepl |
Number of zeros to replace with replacement value (replnum). Can accept either a number or "all" if all zeros should be replaced. Default is to replace the first zero only |
replnum |
Value to replace zeros. Default is .01 |
rem0 |
If TRUE, removes all 0s in consumption data prior to analysis. Default value is FALSE |
remq0e |
If TRUE, removes consumption and price where price == 0. Default value is FALSE |
replfree |
Optionally replaces price == 0 with specified value. |
xcol |
Column name in dataframe that signifies x values (usually price or the IV) |
ycol |
Column name in dataframe that signifies y values (usually consumption or the DV) |
idcol |
Column name in dataframe that signifies identifying id grouping |
Details
Change demand data in various ways. Ways include replacing any number of 0 values with a replacement number (or remove them completely), removing price and consumption at free, replacing free with some number. This will soon replace ReplaceZeros and certain arguments in FitCurves.
Value
Long form dataframe resembling the originally provided dataframe
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
## Change just the first instance of 0 within each unique value of id with .1
ChangeData(apt, nrepl = 1, replnum = .1)
Check Column Names
Description
Checks to ensure column names are specified
Usage
CheckCols(dat, xcol, ycol, idcol, groupcol = NULL)
Arguments
dat |
Dataframe |
xcol |
Name of x column |
ycol |
Name of y column |
idcol |
Name of id column |
groupcol |
Name of group column |
Details
Check column names
Value
Dataframe
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Systematic Purchase Task Data Checker
Description
Applies Stein, Koffarnus, Snider, Quisenberry, & Bickel's (2015) criteria for identification of nonsystematic purchase task data.
Usage
CheckUnsystematic(dat, deltaq = 0.025, bounce = 0.1, reversals = 0, ncons0 = 2)
Arguments
dat |
Dataframe in long form. Colums are id, x, y. |
deltaq |
Numeric vector of length equal to one. The criterion by which the relative change in quantity purchased will be compared. Relative changes in quantity purchased below this criterion will be flagged. Default value is 0.025. |
bounce |
Numeric vector of length equal to one. The criterion by which the number of price-to-price increases in consumption that exceed 25% of initial consumption at the lowest price, expressed relative to the total number of price increments, will be compared. The relative number of price-to-price increases above this criterion will be flagged. Default value is 0.10. |
reversals |
Numeric vector of length equal to one. The criterion by which the number of reversals from number of consecutive (see ncons0) 0s will be compared. Number of reversals above this criterion will be flagged. Default value is 0. |
ncons0 |
Numer of consecutive 0s prior to a positive value is used to flag for a reversal. Value can be either 1 (relatively more conservative) or 2 (default; as recommended by Stein et al., (2015). |
Details
This function applies the 3 criteria proposed by Stein et al., (2015) for identification of nonsystematic purchase task data. The three criteria include trend (deltaq), bounce, and reversals from 0. Also reports number of positive consumption values.
Value
Dataframe
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
## Using all default values
CheckUnsystematic(apt, deltaq = 0.025, bounce = 0.10, reversals = 0, ncons0 = 2)
## Specifying just 1 zero to flag as reversal
CheckUnsystematic(apt, deltaq = 0.025, bounce = 0.10, reversals = 0, ncons0 = 1)
ExtraF
Description
Extra Sum of Squares F-test
Usage
ExtraF(
dat,
equation = "hs",
groups = NULL,
verbose = FALSE,
k,
compare = "alpha",
idcol = "id",
xcol = "x",
ycol = "y",
groupcol = NULL,
start_alpha = 0.001
)
Arguments
dat |
Long form data frame |
equation |
"hs" |
groups |
NULL for all. Character vector matching groups in groupcol |
verbose |
If TRUE, prints all output including models |
k |
User-defined k value; if missing will attempt to find shared k and then mean emprirical range (in log units) |
compare |
Specify whether to compare alpha or Q0. Default is alpha |
idcol |
The column name that should be treated as dataset identifier |
xcol |
The column name that should be treated as "x" data |
ycol |
The column name that should be treated as "y" data |
groupcol |
The column name that should be treated as the groups |
start_alpha |
Optional numeric to inform starting value for alpha |
Details
One alpha better than individual alphas?
Value
List of results and models
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
## Compare two groups using equation by Koffarnus et al., 2015 and a fixed k of 2
apt$group <- NA
apt[apt$id %in% sample(unique(apt$id), length(unique(apt$id))/2), "group"] <- "a"
apt$group[is.na(apt$group)] <- "b"
ExtraF(apt, "koff", k = 2, groupcol = "group")
FitCurves
Description
Analyzes purchase task data
Usage
FitCurves(
dat,
equation,
k,
agg = NULL,
detailed = FALSE,
xcol = "x",
ycol = "y",
idcol = "id",
groupcol = NULL,
lobound,
hibound,
constrainq0 = NULL,
startq0 = NULL,
startalpha = NULL
)
Arguments
dat |
data frame (long form) of purchase task data. |
equation |
Character vector of length one. Accepts either "hs" for Hursh and Silberberg (2008) or "koff" for Koffarnus, Franck, Stein, and Bickel (2015). |
k |
A numeric (or character) vector of length one. Reflects the range of consumption in log10 units. If none provided, k will be calculated based on the max/min of the entire sample + .5. If k = "ind", k will be calculated per individual using max/min + .5. If k = "fit", k will be a free parameter on an individual basis. If k = "range", k will be calculated based on the max/min of the entire sample + .5. |
agg |
Character vector of length one accepts either "Mean" or "Pooled". If not NULL (default), data will be aggregrated appropriately and analyzed in the specified way. |
detailed |
If TRUE, output will be a 3 element list including (1) dataframe of results, (2) list of model objects, (3) list of individual dataframes used in fitting. Default value is FALSE, which returns only the dataframe of results. |
xcol |
The column name that should be treated as "x" data |
ycol |
The column name that should be treated as "y" data |
idcol |
The column name that should be treated as dataset identifier |
groupcol |
The column name that should be treated as the groups |
lobound |
Optional. A named vector of length 2 ("q0", "alpha") or 3 ("q0", "k", "alpha"), the latter length if k = "fit", specifying the lower bounds. |
hibound |
Optional. A named vector of length 2 ("q0", "alpha") or 3 ("q0", "k", "alpha"), the latter length if k = "fit", specifying the upper bounds. |
constrainq0 |
Optional. A number that will be used to constrain Q0 in the fitting process. Currently experimental and only works with a fixed k value. |
startq0 |
Optional. A number that will be used to start Q0 in the fitting process. Currently experimental. |
startalpha |
Optional. A number that will be used to start Alpha in the fitting process. Currently experimental. |
Value
If detailed == FALSE (default), a dataframe of results. If detailed == TRUE, a 3 element list consisting of (1) dataframe of results, (2) list of model objects, (3) list of individual dataframes used in fitting
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com> Shawn Gilroy <shawn.gilroy@temple.edu>
Examples
## Analyze using Hursh & Silberberg, 2008 equation with a k fixed to 2
FitCurves(apt[sample(apt$id, 5), ], "hs", k = 2)
Fit Pooled Curves
Description
Fits curve to pooled data
Usage
FitMeanCurves(
dat,
equation,
k,
remq0e = FALSE,
replfree = NULL,
rem0 = FALSE,
nrepl = NULL,
replnum = NULL,
plotcurves = FALSE,
method = NULL,
indpoints = TRUE,
vartext = NULL
)
Arguments
dat |
data frame (long form) of purchase task data. |
equation |
Character vector of length one. Accepts either "hs" for Hursh and Silberberg (2008) or "koff" for Koffarnus, Franck, Stein, and Bickel (2015). |
k |
A numeric vector of length one. Reflects the range of consumption in log10 units. If none provided, k will be calculated based on the max/min of the entire sample. If k = "fit", k will be a free parameter |
remq0e |
If TRUE, removes consumption and price where price == 0. Default value is FALSE |
replfree |
Optionally replaces price == 0 with specified value. Note, if fitting using equation == "hs", and 0 is first price, 0 gets replaced by replfree. Default value is .01 |
rem0 |
If TRUE, removes all 0s in consumption data prior to analysis. Default value is FALSE. |
nrepl |
Number of zeros to replace with replacement value (replnum). Can accept either a number or "all" if all zeros should be replaced. Default is to replace the first zero only. |
replnum |
Value to replace zeros. Default is .01 |
plotcurves |
Boolean whether to create plot. If TRUE, a "plots/" directory is created one level above working directory. Default is FALSE. |
method |
Character string of length 1. Accepts "Mean" to fit to mean data or "Pooled" to fit to pooled data |
indpoints |
Boolean whether to plot individual points in gray. Default is TRUE. |
vartext |
Character vector specifying indices to report on plots. Valid indices include "Q0d", "Alpha", "Q0e", "EV", "Pmaxe", "Omaxe", "Pmaxd", "Omaxd", "K", "Q0se", "Alphase", "R2", "AbsSS" |
Value
Data frame
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
## Fit aggregated data (mean only) using Hursh & Silberberg, 2008 equation with a k fixed at 2
FitMeanCurves(apt[sample(apt$id, 5), ], "hs", k = 2, method = "Mean")
Get pmax
Description
...
Usage
GetAnalyticPmax(Alpha, K, Q0)
Arguments
Alpha |
alpha parameter |
K |
k parameter ( > lower limit ) |
Q0 |
Q0 |
Details
...
Value
Numeric
Author(s)
Shawn Gilroy <sgilroy1@lsu.edu>
Analytic Pmax Fallback
Description
Fallback method for Analytic Pmax
Usage
GetAnalyticPmaxFallback(K_, A_, Q0_)
Arguments
K_ |
k parameter |
A_ |
alpha parameter |
Q0_ |
q0 parameter |
Details
Derivative-based optimization strategy
Value
numeric
Author(s)
Shawn Gilroy <sgilroy1@lsu.edu>
Get Purchase Task Descriptive Summary
Description
Calculates descriptive statistics from purchase task data.
Usage
GetDescriptives(
dat,
bwplot = FALSE,
outdir = "../plots/",
device = "png",
filename = "bwplot"
)
Arguments
dat |
Dataframe (long form) |
bwplot |
Boolean. If TRUE, a ggplot2 box and whisker plot is saved. Default is FALSE. |
outdir |
Character. Directory where plot will be saved. Be sure to include trailing '/'. Default location is one level up in "../plots/". |
device |
Character. Type of file. Default is "png". Can be "pdf". |
filename |
Character. Specify filename. Defualt is "bwplot". |
Details
Provides the following descriptive statistics from purchase task data at each price: mean consumption, median consumption, standard deviation of consumption, proportion of 0 values, number of NAs, minimum consumption, and maximum consumption.
Value
Dataframe with descriptive statistics
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
GetDescriptives(apt)
GetEmpirical
Description
Calculates empirical measures for purchase task data
Usage
GetEmpirical(dat, xcol = "x", ycol = "y", idcol = "id")
Arguments
dat |
data frame (long form) of purchase task data. |
xcol |
The column name that should be treated as "x" data |
ycol |
The column name that should be treated as "y" data |
idcol |
The column name that should be treated as dataset identifier |
Details
Will calculate and return the following empirical measures: Intensity, BP0, BP1, Omax, and Pmax
Value
Data frame of empirical measures
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
## Obtain empirical measures
GetEmpirical(apt)
Get K
Description
Calculates a k value by looking for the max/min consumption across entire dataset and adds .5 to that range
Usage
GetK(dat, mnrange = TRUE)
Arguments
dat |
Dataframe (long form) |
mnrange |
Boolean for whether k should be calculated based on the mean range + .5 |
Details
Will look for maximum/minimum greater zero
Value
Numeric
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
GetK(apt)
Get Shared K
Description
Finds shared k among selected datasets using global regression
Usage
GetSharedK(dat, equation, sharecol = "group")
Arguments
dat |
Dataframe (longform) |
equation |
Character vector. Accepts either "hs" or "koff" |
sharecol |
Character for column to find shared k. Default to "group" but can loop based on id. |
Details
Uses global regression to fit a shared k among datasets. Assumes the dataset is in its final form. Used within FitCurves
Value
Numeric value of shared k
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com> Shawn P Gilroy <shawn.gilroy@temple.edu>
Examples
## Find a shared k value across datasets indicated by id
GetSharedK(apt, "hs", sharecol = "id")
Get Values for SimulateDemand
Description
Gets values used in SimulateDemand
Usage
GetValsForSim(dat)
Arguments
dat |
Dataframe (long form) |
Details
Gets values used in SimulateDemand
Value
List of 3: setaparams, sdindex, x
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
GetValsForSim(apt)
Plot Curve
Description
Creates a single plot object
Usage
PlotCurve(adf, dfrow, newdats, yscale = "log")
Arguments
adf |
Data frame (long form) of purchase task data. |
dfrow |
A row of results from FitCurves |
newdats |
A newdat dataframe from FitCurves |
yscale |
Scaling of y axis. Default is "log". Can also take "linear" |
Details
Creates individual demand curves
Value
ggplot2 graphical object
Author(s)
Shawn Gilroy <shawn.gilroy@temple.edu>
Examples
## Creates a single plot from elements of an object created by FitCurves
fc <- FitCurves(apt, "hs", k = 2, detailed = TRUE)
PlotCurve(fc$adfs[[1]], fc$dfres[1, ], fc$newdats[[1]])
Plot Curves
Description
Creates plots
Usage
PlotCurves(dat, outdir = NULL, device = "png", ending = NULL, ask = T, ...)
Arguments
dat |
FitCurves object with 4 elements (dfres, newdats, adfs, fits) |
outdir |
Directory where plots are saved |
device |
Type of file. Default is "png". Can be "pdf" |
ending |
Optional. Can specify to only plot through a certain number of datasets |
ask |
Can view plots one by one. If TRUE, plots will not save |
... |
Pass arguments to PlotCurve (for example yscale = c("log", "linear")) |
Details
Creates and saves plots of individual demand curves
Value
Nothing
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>, Shawn Gilroy <shawn.gilroy@temple.edu>
Examples
## Interactively view plots from output from FitCurves
fc <- FitCurves(apt, "hs", k = 2, detailed = TRUE)
PlotCurves(fc, ask = TRUE)
Recode Outliers
Description
Recodes outliers
Usage
RecodeOutliers(df, outval = 3.29, unitshigher = 0)
Arguments
df |
A dataframe of consumption values |
outval |
Values greater/less than or equal to this number (specified in standard deviations) will be recoded. Default is 3.29SD as specified by Tabachnick and Fidell (2013) |
unitshigher |
Outliers identified by outval will be coded to a certain number of units higher/lower than the greatest nonoutlier value. Default is 0 units. |
Details
Recodes outliers using Tabachnick and Fidell's (2013) criteria. A variable is standardized and values that are greater/less than or equal to a specified outlier value (specified in standard deviations; default 3.29SD) are recoded to a certain number of units (default 0) higher/lower than the greatest nonoutlier value. Disregards 'NA' values.
Value
Invisibly, a dataframe with original and recoded (if any) values
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
## If any outliers are detected, they would be coded as 1 unit higher
emp <- GetEmpirical(apt)
RecodeOutliers(emp[, c(2:6)], unitshigher = 1)
Replace Zeros
Description
Replaces 0 values
Usage
ReplaceZeros(dat, nrepl = 1, replnum = 0.01)
Arguments
dat |
Dataframe (long form) |
nrepl |
Number of zeros to replace with replacement value (replnum). Can accept either a number or "all" if all zeros should be replaced. Default is to replace the first zero only. |
replnum |
Value to replace zeros. Default is .01 |
Details
Replaces specified number of 0s with replacement value.
Value
Dataframe (long form)
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
## Replace all zeros with .01
ReplaceZeros(apt, nrepl = "all", replnum = .01)
Simulate Demand Data
Description
Simulate demand data
Usage
SimulateDemand(nruns = 10, setparams, sdindex, x, outdir = NULL, fn = NULL)
Arguments
nruns |
Number of runs. Default value is 10 |
setparams |
A 6x1 matrix (or 6 element vector) containing (in order) mean log10alpha, sd log10alpha, mean log10q0, sd log10q0, k, sd of consumption values across all prices |
sdindex |
A vector of n length of sd consumption values for n prices |
x |
A vector of n prices |
outdir |
Optional. Directory to save results. Must end with a "/" |
fn |
Optional. Filename of saved RData object |
Details
Generates and saves simulated datasets in the manner specified in Koffarnus, Franck, Stein, & Bickel (2015).
Value
Invisibly a list consisting of: rounded consumption values, unrounded consumption values, simulation parameters, and inState and outState of seeds.
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
## set values
setparams <- vector(length = 4)
setparams <- c(-2.5547, .702521, 1.239893, .320221, 3.096, 1.438231)
names(setparams) <- c("alphalm", "alphalsd", "q0lm", "q0lsd", "k", "yvalssd")
sdindex <- c(2.1978, 1.9243, 1.5804, 1.2465, 0.8104, 0.1751, 0.0380, 0.0270)
x <- c(.1, 1, 3, 10, 30, 100, 300, 1000)
set.seed(1234)
sim <- SimulateDemand(nruns = 1, setparams = setparams, sdindex = sdindex, x = x)
sim
annotation_logticks2
Description
Creates annotation layer
Usage
annotation_logticks2(
base = 10,
sides = "bl",
scaled = TRUE,
short = unit(0.1, "cm"),
mid = unit(0.2, "cm"),
long = unit(0.3, "cm"),
colour = "black",
size = 0.5,
linetype = 1,
alpha = 1,
data = data.frame(x = NA),
color = NULL,
...
)
Arguments
base |
base for drawing in scale |
sides |
sides to draw, by default bottom and left |
scaled |
true by default |
short |
short tick settings |
mid |
mid tick settings |
long |
long tick settings |
colour |
default to black colour |
size |
size for labels |
linetype |
default linetype |
alpha |
default alpha level |
data |
data to include |
color |
colors to include |
... |
additional arguments |
Details
Inherit and extend layer for use in ggplot draw
Value
ggplot2 layer
Author(s)
Shawn Gilroy <shawn.gilroy@temple.edu>
Example alcohol purchase task data
Description
A dataset containing alcohol purchase task data for a small number of participants
Usage
apt
Format
Long-form data.frame with columns: id, x, y. Participants were asked how many standard sized alcoholic beverages they would buy at various prices.
Lambert W
Description
Ben Bolker's port of Lambert W from GNU Scientific Library (GPLV3)
Usage
lambertW(z, b = 0, maxiter = 10, eps = .Machine$double.eps, min.imag = 1e-09)
Arguments
z |
input value |
b |
branch, set to principal by default |
maxiter |
Halley iteration count |
eps |
error precision |
min.imag |
minimum for imaginary solution |
Details
Ben Bolker's port of Lambert W from GNU Scientific Library
Value
numeric
Author(s)
Benjamin Bolker (port)
Pull
Description
Pull vector from data frame
Usage
pull(x, y)
Arguments
x |
A data frame |
y |
Name of column |
Details
Pulls a single vector from a data frame. Good to use with dplyr. From http://stackoverflow.com/questions/21618423/extract-a-dplyr-tbl-column-as-a-vector
Value
Vector
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
APA Theme
Description
APA theme for ggplot
Usage
theme_apa(plot.box = FALSE)
Arguments
plot.box |
Boolean for a box around the plot |
Details
Theme for ggplot graphics that closely align with APA formatting
Value
ggplot theme
Author(s)
Brent Kaplan <bkaplan.ku@gmail.com>
Examples
p <- ggplot2::ggplot(apt, ggplot2::aes(x = x, y = y)) +
ggplot2::geom_point()
p + theme_apa()