turnbull {DCchoice}

The Kaplan-Meier-Turnbull nonparametric approach to analyze dichotomous choice contingent valuation data

Description

This function analyzes single-, one-and-one-half-, or double-bounded dichotomous choice contingent valuation (CV) data on the basis of the Kaplan-Meier-Turnbull method.

Usage

## for the single-bounded data
turnbull.sb(formula, data, subset, conf.int = FALSE, B = 200, 
            conf.level = 0.95, timeMessage = FALSE, seed = 19439101, ...)

## for the one-and-one-half-bound data
turnbull.oohb(formula, data, subset, conf.int = FALSE, B = 200, 
              conf.level = 0.95, timeMessage = FALSE, seed = 19439101, ...)


## for the double-bounded data
turnbull.db(formula, data, subset, conf.int = FALSE, B = 200, 
            conf.level = 0.95, timeMessage = FALSE, seed = 19439101, ...)

## S3 method for class 'turnbull'
print(x, digits = max(3, getOption("digits") - 1), ...)

Arguments

formula

a formula specifying the model structure.

data

a data frame containing the variables in the model formula.

subset

an optional vector specifying a subset of observations.

x

an object of class "turnbull".

conf.int

logical. If TRUE, the confidence intervals are computed.

B

number of bootstrap resampling for confidence interval estimation. Defaulted to 200.

conf.level

a confidence coefficient. Defaulted to 0.95.

timeMessage

logical. If TRUE, the estimated time for bootstrapping is displayed.

digits

a number of digits to display.

seed

a seed for a random number generator.

...

optional arguments. Currently not in use.

Details

The functions turnbull.sb(), turnbull.oohb(), and turnbull.db() analyze single-, one-and-one-half-, and double-bounded dichotomous choice contingent valuation (CV) data, respectively, on the basis of the modified Kaplan-Meier-Turnbull method (Carson and Steinberg, 1990).

For single-bounded dichotomous choice data
Most of the details of turnbull.sb() is the same as those of turnbull.db(). See the subsequent section for details.

A difference between turnbull.sb() and turnbull.db() appears in the definition of the model formula. In turnbull.sb(), the first part contains only one response variable (e.g., R1) and the other part contains only one bid variable (e.g., BD1) because respondents are requested to answer a CV question in the single-bounded dichotomous choice CV. A typical structure of the formula is given by

R1 ~ BD1

kristrom is an alternative nonparametric method for analyzing single-bounded dichotomous choice data. A parametric analysis can be done by sbchoice.

For one-and-one-half-bound dichotomous choice data
The details of turnbull.oohb() is the same as those of turnbull.db(). See the the subsequent section for details.

A difference between turnbull.oohb() and turnbull.db() appears in the definition of variables. See oohbchoice and oohbsyn for the details of creating response and bid variables.

For double-bounded dichotomous choice data
A generic call to turnbull.db() is given by

turnbull.db(formula, data)

The argument formula defines the response variables and bid variables. The argument data is set as a data frame containing the variables in the model.

A typical structure of the formula for turnbull.db() is defined as follows:

R1 + R2 ~ BD1 + BD2

The formula consists of two parts. The first part, the left-hand side of the tilde sign (~), must contain the response variables for the suggested prices in the first and the second stage of CV questions. In the above example, R1 denotes a binary or two-level factor response variable for a bid in the first stage and R2 for a bid in the second stage. Each of R1 and R2 contains "Yes" or "No" to the bid or 1 for "Yes" and 0 for "No". The two variables are connected with the arithmetic operator (+). The other part, which starts after the tilde sign, must contain bid variables (BD1, BD2) containing suggested prices in the first and second stage of double-bounded dichotomous choice CV question. The two variables are also connected with the arithmetic operator (+).

A parametric approach for analyzing double-bounded dichotomous choice data can be carried out by dbchoice.

The structure of data set which assigned to the argument data is the same as that of dbchoice(). See dbchoice for details in the data set structure.

The confidence intervals are computed by the bootstrap method in icfit of the interval (Fay and Shaw, 2010) package. The arguments conf.int, B, conf.level and timeMessage are passed to icfit(). The bootstrap can be time consuming, so that it is in general not advisable to increase the number of bootstrap resamplint B. See the help of icfit for futher detail.

The generic function print() is available for a fitted model object of class "turnbull" and displays simply estimated probabilities of the distribution: this is the same as the element pf in the function icfit of the interval (Fay and Shaw, 2010) package.

The extractor function summary() is also available for a fitted model object of class "turnbull" and the generic function print.summary() displays the survival probability and three types of WTP estimates (a Kaplan-Meier mean, a Spearman-Karber mean, and median WTPs). In estimating the two types of mean WTP, the area under the survivor function is truncated at the maximum bid because there seems no unified approach to determine an ending point of bids at which the acceptance probability is zero. Therefore, we leave the decision of how the area is treated to the user. In practice, once the ending point, $bid_end$, is found, it is straightforward to compute the triangular area by $0.5(bid_end - bid_max)P_max$ where $bid_max$ is the maximum bid and $P_max$ is the acceptance probability for $bid_max$, both of which are reported in the summarized output.

Furthermore, the generic function plot() is available for a fitted model object of class "turnbull" and displays the empirical survival function. See plot.turnbull for details.

Value

Both turnbull.db() and turnbull.sb() return an object of S3 class "turnbull" that is a list with the following components.

left

a vector of left endpoints of censored interval. The vector is internally assigned to the argument L in icfit() of the interval package.

right

a vector of right endpoints of censored interval. The vector is internally assigned to the argument R in icfit() of the interval package.

turnbull

a list of components returned from icfit().

unq.dib

a vector of unique bids including Inf.

CI

estimates for confidence intervals from icfit().

References

Croissant Y (2011). Ecdat: Data Sets for Econometrics, R package version 0.1-6.1, https://CRAN.R-project.org/package=Ecdat.

Fay MP, Shaw PA (2010). “Exact and Asymptotic Weighted Logrank Tests for Interval Censored Data: The interval R Package”, Journal of Statistical Software, 36(2), 1-34. https://www.jstatsoft.org/v36/i02/.

Krinsky I, Robb AL (1986). “On Approximating the Statistical Properties of Elasticities.” The Review of Economics and Statistics, 68, 715–719.

Krinsky I, Robb AL (1990). “On Approximating the Statistical Properties of Elasticities: A Correction.” The Review of Economics and Statistics, 72, 189–190.

Turnbull BW (1976). “The Empirical Distribution Function with Arbitrarily Grouped, Censored and Truncated Data.” Journal of the Royal Statistical Society. Series B, 38(3), 290–295.

See Also

summary.turnbull, plot.turnbull, kristrom, sbchoice, dbchoice, NaturalPark, glm, icfit

Examples

## Examples are based on turnbull.db(). turnbull.sb() is similarly 
## implemented. A difference appears in the definition of the model 
## formula. See "Details" section of the help.

## A data set used here is NaturalPark in the package Ecdat (Croissant, 
## 2011): double-bounded dichotomous choice CV style question for 
## measuring willingness to pay for the preservation of the Alentejo 
## Natural Park. The data frame contains seven variables: bid1 (bid in 
## the initial question), bidh (higher bid in the follow-up question), 
## bidl (lower bid in the follow-up question), answers (response 
## outcomes in a factor format with four levels of "nn", "ny", "yn", "yy"), 
## respondents' characteristic variables such as age, sex and income (see 
## NaturalPark for details).
data(NaturalPark, package = "Ecdat")

## The variable answers are converted into a format that is suitable for 
## the function turnbull.db() as follows:
NaturalPark$R1 <- ifelse(substr(NaturalPark$answers, 1, 1) == "y", 1, 0)
NaturalPark$R2 <- ifelse(substr(NaturalPark$answers, 2, 2) == "y", 1, 0)

## The variables bidh and bidl are integrated into one variable (bid2) 
## as follows:
NaturalPark$bid2 <- ifelse(NaturalPark$R1 == 1, NaturalPark$bidh, NaturalPark$bidl)

## The formula for turnbull.sb and turnbull.db are defined respectively as follows:
fmts <- R1 ~ bid1
fmtd <- R1 + R2 ~ bid1 + bid2

## The function turnbull.db() with the formula fmtd and the data frame 
## NaturalPark is executed as follows:
NPts <- turnbull.sb(fmts, data = NaturalPark)
NPts
NPtss <- summary(NPts)
NPtss
plot(NPts)


## The function turnbull.db() with the formula fmtd and the data frame 
## NaturalPark is executed as follows:
NPtd <- turnbull.db(fmtd, data = NaturalPark)
NPtd
NPtds <- summary(NPtd)
NPtds
plot(NPtd)