| Type: | Package |
| Title: | Design and Analysis of Factorial Survey (Vignette) Experiments |
| Version: | 0.3.0 |
| Description: | An integrated workflow for factorial survey (vignette) experiments. Constructs D-efficient sets of vignettes from a factorial structure and reports their D- and A-efficiency following Kuhfeld, Tobias and Garratt (1994) <doi:10.1177/002224379403100408>, allocates them to blocks and to respondents in carryover-balanced orders, renders them as prose, and writes them out for survey platforms. Simulates responses to evaluate statistical power before fielding. Estimates beta regression models for bounded ratings and logit models for yes/no responses, with standard errors clustered by respondent, and derives average marginal effects, marginal willingness to pay and the expected willingness to pay for complete policy scenarios. The latter is the mean of willingness to pay truncated at zero, Hanemann (1989) <doi:10.2307/1242685>, applied to factorial surveys as in Tanaka et al. (2027) <doi:10.1016/j.tra.2026.105293>. Efficient designs and optimal blocking use the exchange algorithms of Fedorov (1972, ISBN:0122507509) as implemented in 'AlgDesign'. Presentation orders follow Williams (1949) <doi:10.1071/CH9490149>. Beta regression follows Ferrari and Cribari-Neto (2004) <doi:10.1080/0266476042000214501>. Bounded ratings are mapped to the open unit interval following Smithson and Verkuilen (2006) <doi:10.1037/1082-989X.11.1.54>. |
| License: | MIT + file LICENSE |
| Encoding: | UTF-8 |
| Language: | en-GB |
| LazyData: | true |
| Depends: | R (≥ 4.1) |
| Imports: | stats, tools, utils, AlgDesign, betareg, ggplot2 (≥ 3.4.0), sandwich |
| Suggests: | openxlsx, margins, testthat (≥ 3.0.0), withr, knitr, rmarkdown |
| VignetteBuilder: | knitr |
| Config/testthat/edition: | 3 |
| RoxygenNote: | 7.3.1 |
| URL: | https://github.com/tanakak/FactorialSurvey |
| BugReports: | https://github.com/tanakak/FactorialSurvey/issues |
| NeedsCompilation: | no |
| Packaged: | 2026-11-02 07:41:41 UTC; katsuyat |
| Author: | Katsuya Tanaka |
| Maintainer: | Katsuya Tanaka <katsuyat@gmail.com> |
| Repository: | CRAN |
| Date/Publication: | 2026-11-20 12:10:02 UTC |
FactorialSurvey: Design and Analysis of Factorial Survey Experiments
Description
FactorialSurvey supports the full workflow of a factorial survey
(vignette) experiment. A factorial survey presents respondents with short
descriptions ("vignettes") whose attributes are experimentally varied, and
asks for a rating – typically on a bounded scale such as 0 to 10. Because
the attributes are randomised by design, their effects on the rating can be
given a causal interpretation.
The package is organised around three stages.
1. Design. fs_defficient() selects a D-efficient subset of
vignettes from the full factorial and splits it into blocks;
fs_design_eval() reports level balance and attribute correlations;
set_labels() attaches readable level labels to the resulting data frame.
2. Estimation. fs_betareg() fits a beta regression to bounded
ratings, mapping the observed scale onto the open unit interval and
returning average marginal effects on both the transformed and the original
scale.
3. Post-estimation. fs_mwtp() converts a pair of coefficients
into a marginal willingness to pay, with a delta-method standard error and
confidence interval.
A note on standard errors
In a typical factorial survey each respondent rates several vignettes, so
observations are clustered within respondents. Pass the respondent
identifier to fs_betareg() through its cluster argument: standard
errors, marginal effects and willingness-to-pay intervals are then
cluster-robust. Without it, ratings are treated as independent and the
reported uncertainty is not valid; it is much too small for the effects of
respondent characteristics such as age or gender.
Author(s)
Maintainer: Katsuya Tanaka katsuyat@gmail.com (ORCID) [copyright holder]
References
Ferrari, S. L. P. and Cribari-Neto, F. (2004). Beta regression for modelling rates and proportions. Journal of Applied Statistics, 31(7), 799–815. doi:10.1080/0266476042000214501
Smithson, M. and Verkuilen, J. (2006). A better lemon squeezer? Maximum-likelihood regression with beta-distributed dependent variables. Psychological Methods, 11(1), 54–71. doi:10.1037/1082-989X.11.1.54
Wallander, L. (2009). 25 years of factorial surveys in sociology: A review. Social Science Research, 38(3), 505–520. doi:10.1016/j.ssresearch.2009.03.004
See Also
Useful links:
Report bugs at https://github.com/tanakak/FactorialSurvey/issues
Coerce expected willingness to pay estimates to a data frame
Description
Coerce expected willingness to pay estimates to a data frame
Usage
## S3 method for class 'fs_ewtp'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)
Arguments
x |
An object of class |
row.names |
Passed to |
optional |
Passed to |
... |
Ignored. |
Value
A data frame with columns scenario, index, ewtp,
std_error, conf_low and conf_high.
Examples
set.seed(1)
d <- data.frame(id = rep(1:40, each = 4), q = rbinom(160, 1, 0.5),
cost = sample(c(100, 300, 500), 160, replace = TRUE))
d$y <- rbinom(160, 1, plogis(0.5 + d$q - 0.004 * d$cost))
fit <- fs_logit(y ~ q + cost, data = d, cluster = ~ id, compute_me = FALSE)
as.data.frame(fs_ewtp(fit, data.frame(q = 0:1), price = "cost"))
Coerce marginal willingness to pay estimates to a data frame
Description
Coerce marginal willingness to pay estimates to a data frame
Usage
## S3 method for class 'fs_mwtp'
as.data.frame(x, row.names = NULL, optional = FALSE, ...)
Arguments
x |
An object of class |
row.names |
Passed to |
optional |
Passed to |
... |
Ignored. |
Value
A data frame with columns variable, mwtp, std_error,
conf_low and conf_high.
Examples
set.seed(1)
d <- data.frame(id = rep(1:40, each = 3), x = rnorm(120),
price = runif(120, 100, 900))
d$rating <- 10 * plogis(0.7 * d$x - 0.002 * d$price + rnorm(120, sd = 0.4))
fit <- fs_betareg(rating ~ x + price, data = d, cluster = ~ id,
compute_me = FALSE)
as.data.frame(fs_mwtp(fit, price = "price"))
Ratings of take-away lunch boxes from a classroom factorial survey
Description
Ratings of eight take-away lunch box (bento) vignettes by 48 university students. Each vignette describes a lunch box by its main dish, whether it comes with a side dish, whether nutrition information is shown, and its price; respondents rated how likely they would be to buy it on a 0 to 10 scale. Every respondent rated all eight vignettes.
Usage
bento
Format
A data frame with 384 rows (48 respondents by 8 vignettes) and 7 variables:
- respondent
Respondent identifier, 1 to 48.
- vignette
Vignette identifier, 1 to 8.
- main
Main dish, a factor with levels
"grilled fish"(the reference),"teriyaki chicken"and"tofu hamburger".- side
Side dish included: 1 yes, 0 no.
- info
Nutrition information shown: 1 yes, 0 no.
- price
Price in Japanese yen: 700, 900, 1100 or 1300.
- rating
Purchase intention, from 0 ("would definitely not buy") to 10 ("would definitely buy").
Details
The data are small and were collected for teaching, which makes them convenient for illustrating the workflow: estimating a beta regression with standard errors clustered by respondent, then marginal and expected willingness to pay.
Source
Collected from students in the course "Environmental Data Analysis" at Shiga University in 2025, with their permission to publish the anonymous responses.
Examples
head(bento)
fit <- fs_betareg(rating ~ main + side + info + price, data = bento,
cluster = ~ respondent, compute_me = FALSE)
fs_mwtp(fit, price = "price")
Allocate blocks and presentation orders to respondents
Description
Turns a design into the schedule a survey platform actually needs: one row per respondent per vignette, stating which vignette that respondent sees in which position. Blocks are dealt out evenly across respondents, and the order within a block can be balanced with a Williams design so that position and carryover effects do not confound the attributes.
Usage
fs_assign(
design,
n_respondents,
order = c("williams", "random", "as_is"),
seed = NULL
)
Arguments
design |
An object of class |
n_respondents |
The number of respondents to schedule. |
order |
How the vignettes within a block are ordered for each
respondent. One of |
seed |
A single number making the allocation reproducible, or |
Details
Respondents are assigned to blocks by dealing round: respondent 1 gets block
1, respondent 2 block 2, and so on, wrapping around. When
n_respondents is not a multiple of the number of blocks, the earlier
blocks receive one extra respondent and a message says so.
With order = "williams" the respondents within a block cycle through the
rows of fs_williams(). Carryover balance is only fully achieved once the
number of respondents per block is a multiple of the number of orders, which
is the block size for an even block size and twice it for an odd one; a
message reports the number of orders so this can be checked when choosing
the sample size.
Value
An object of class fs_assignment, which inherits from
data.frame, with one row per respondent per vignette and the columns:
respondentRespondent identifier,
1ton_respondents.blockThe block that respondent was given.
positionPosition in the questionnaire,
1upwards.vignetteRow number of the vignette in
design, so that responses can be matched back to the design.- ...
Every column of
design, including any text column added byfs_vignette_text().
The number of distinct orders used is attached as the n_orders
attribute, and the ordering method as order.
See Also
fs_williams(), fs_defficient(), fs_export()
Examples
d <- fs_defficient(list(damage = c("minor", "severe"),
cost = c(100, 500, 1000)),
n_vignettes = 6, n_blocks = 2,
seed = 1, verbose = FALSE)
schedule <- fs_assign(d, n_respondents = 8, seed = 1)
head(schedule)
# Every respondent sees every vignette in their block exactly once
table(schedule$respondent)
# Across respondents, each vignette appears in each position equally often
with(subset(schedule, block == 1), table(vignette, position))
Beta regression for bounded rating outcomes
Description
Fits a beta regression to the ratings collected in a factorial survey. Beta regression is well suited to responses that are bounded and often skewed, such as a 0 to 10 acceptability score, because it models the mean on a bounded support instead of assuming an unbounded normal error.
The observed scale is mapped onto the open unit interval, the model is
fitted with betareg::betareg(), and – optionally – average marginal
effects are reported on both the unit interval and the original scale.
Usage
fs_betareg(
formula,
data,
scale = c(0, 10),
transform = TRUE,
cluster = NULL,
compute_me = TRUE,
verbose = FALSE,
...
)
Arguments
formula |
A symbolic description of the model, passed to
|
data |
A data frame containing the variables in |
scale |
A numeric vector of length two giving the lower and upper
bound of the observed rating scale. The default |
transform |
A logical value. If |
cluster |
How to account for the fact that each respondent rates
several vignettes. Give the respondent identifier as a one-sided formula
such as |
compute_me |
A logical value. If |
verbose |
A logical value. If |
... |
Further arguments passed to |
Details
The response is mapped onto (0, 1) in two steps. It is first shifted and
scaled to [0, 1] using scale, then pulled away from the endpoints
with the transformation of Smithson and Verkuilen (2006),
(y(N - 1) + 0.5) / N, where N is the number of observations.
Average marginal effects on the unit interval are converted back to the
original scale by multiplying by (u - l) N / (N - 1), where l
and u are the bounds in scale.
Two pseudo R-squared values are reported because they measure different
things and are easy to confuse. pseudo_r2_cox_snell is the
likelihood-ratio measure of Cox and Snell,
1 - \exp(2(\ell_0 - \ell) / n), computed against an intercept-only
model that this function fits for the purpose. pseudo_r2_betareg is the
value betareg itself reports, namely the squared correlation between
the linear predictor and the link-transformed response.
With cluster, the covariance matrix is the cluster-robust sandwich
estimator of sandwich::vcovCL() with the usual G / (G - 1)
small-sample adjustment, where G is the number of respondents. It
allows the ratings of one respondent to be correlated in any way, which is
what a respondent-specific taste or response style produces. With few
respondents (say, fewer than 30) these standard errors are themselves
imprecise.
McFadden's 1 - \ell / \ell_0 is deliberately not reported. It is
designed for discrete outcomes, whose log-likelihoods are always negative.
A beta regression is a continuous density, so its log-likelihood is
frequently positive, and McFadden's ratio then takes values outside
[0, 1] and cannot be interpreted. The Cox and Snell measure is well
behaved regardless of the sign of the log-likelihood.
Value
An object of class fs_betareg, a list with components:
modelThe fitted
betareg::betareg()object.vcovThe covariance matrix of the estimates used for all inference: cluster-robust when
clusteris given, otherwise the model-based matrix.clusterA list describing the clustering (
name,n_clusters), orNULL.marginal_effectsThe
marginsobject, orNULL.marginal_effects_rescaledA data frame of average marginal effects expressed on the original rating scale, or
NULL.gofA named list of goodness-of-fit measures:
logLik,logLik_null,AIC,BIC,lr_stat,lr_df,lr_p_value,pseudo_r2_cox_snell,pseudo_r2_betaregandnobs.scaleThe rating scale supplied.
transformWhether the response was rescaled.
rescale_factorThe factor mapping effects on (0, 1) back to the original scale, or
NAwhentransformisFALSE.callThe matched call.
Clustered data
When each respondent rates several vignettes the ratings of one person are
correlated, and standard errors that assume independence are not valid.
The error is largest for characteristics of the respondent, such as age or
gender, which are constant within a respondent: there, ordinary standard
errors are much too small (in the package's validation simulations,
nominal 95 percent intervals covered the truth only about 80 percent of the
time). For attributes varied within respondents they were close to right
or somewhat too large. Cluster-robust standard errors are valid in both
cases, so use cluster.
References
Ferrari, S. L. P. and Cribari-Neto, F. (2004). Beta regression for modelling rates and proportions. Journal of Applied Statistics, 31(7), 799–815. doi:10.1080/0266476042000214501
Smithson, M. and Verkuilen, J. (2006). A better lemon squeezer? Maximum-likelihood regression with beta-distributed dependent variables. Psychological Methods, 11(1), 54–71. doi:10.1037/1082-989X.11.1.54
See Also
fs_mwtp() for turning the fitted coefficients into a
willingness to pay, fs_defficient() for building the design.
Examples
set.seed(123)
# 50 respondents, each rating 3 vignettes
n <- 150
d <- data.frame(
id = rep(1:50, each = 3),
quality = rnorm(n),
cost = runif(n, 100, 1000)
)
taste <- rnorm(50, sd = 0.4)[d$id] # respondent-specific shift
d$rating <- 10 * plogis(0.6 * d$quality - 0.002 * (d$cost - 500) +
taste + rnorm(n, sd = 0.5))
fit <- fs_betareg(rating ~ quality + cost, data = d, cluster = ~ id,
compute_me = FALSE)
fit
summary(fit)
Extract components from a factorial survey beta regression
Description
Methods that forward to the underlying betareg::betareg() fit, so that
fs_betareg objects can be used with the usual extractor functions.
vcov() returns the covariance matrix used for inference, which is
cluster-robust when the model was fitted with cluster.
Usage
## S3 method for class 'fs_betareg'
coef(object, ...)
## S3 method for class 'fs_betareg'
vcov(object, ...)
## S3 method for class 'fs_betareg'
logLik(object, ...)
## S3 method for class 'fs_betareg'
nobs(object, ...)
## S3 method for class 'fs_betareg'
fitted(object, ...)
Arguments
object |
An object of class |
... |
Passed on to the corresponding method for |
Value
The value returned by the corresponding betareg method: a
named numeric vector for coef(), a matrix for vcov(), an object of
class logLik for logLik(), a single integer for nobs(), and a
numeric vector for fitted().
Examples
set.seed(1)
d <- data.frame(id = rep(1:20, each = 3), x = rnorm(60))
d$rating <- 10 * plogis(0.5 * d$x + rnorm(60, sd = 0.4))
fit <- fs_betareg(rating ~ x, data = d, cluster = ~ id,
compute_me = FALSE)
coef(fit)
nobs(fit)
Generate a D-efficient set of vignettes for a factorial survey
Description
Selects a subset of the full factorial that is efficient for estimating the
effects of the attributes, using the exchange algorithm of
AlgDesign::optFederov(), and splits the selected vignettes into blocks
that can be administered to different respondents.
Usage
fs_defficient(
factors,
n_vignettes,
n_blocks = 1,
model = ~.,
linear = NULL,
restrictions = NULL,
blocking = c("optimal", "random"),
n_repeats = 50,
shuffle_within_blocks = TRUE,
seed = NULL,
max_candidates = 1e+05,
verbose = TRUE
)
Arguments
factors |
A named list defining the attributes and their levels, in
the form accepted by |
n_vignettes |
The number of vignettes to select. Must not exceed the
number of distinct combinations, and must be at least the number of
parameters implied by |
n_blocks |
The number of blocks the vignettes are divided into.
|
model |
A one-sided formula giving the model the design should be
efficient for. The default |
linear |
An optional character vector naming numeric attributes for
which only a linear effect is to be estimated. The design is then made
efficient for a slope rather than for separate level effects, which
pushes the selection towards the extreme levels and may leave
intermediate levels out altogether. Leave it |
restrictions |
An optional one-sided formula, or a list of such
formulas, describing combinations that must not appear. Each formula
is evaluated within the full factorial and rows for which it is |
blocking |
How the selected vignettes are divided into blocks. Either
|
n_repeats |
The number of random starts used by the exchange algorithm. Larger values search harder at the cost of run time. |
shuffle_within_blocks |
A logical value. If |
seed |
A single number used to make the search and the shuffling
reproducible, or |
max_candidates |
The largest candidate set the function will build before giving up, as a guard against an accidentally enormous factorial. |
verbose |
A logical value. If |
Details
The search is carried out with every attribute coded as a factor, so the
design is efficient for estimating a separate effect for each level. This
matters when levels are supplied as numbers: treated as a continuous
variable, a three-level attribute coded 1:3 would be optimised for a
slope, and the middle level would rarely or never be shown. Attributes
named in linear are the deliberate exception. In the returned design the
columns keep the type of the levels supplied: numbers stay numbers.
The reported D- and A-efficiencies follow Kuhfeld, Tobias and Garratt
(1994) and equal 100 for an orthogonal array. See fs_efficiency().
With blocking = "optimal" the selected vignettes are allocated to blocks
by AlgDesign::optBlock(), which searches for an allocation that keeps each
block as informative as possible in its own right. This matters when a
respondent sees only one block and you want each block to support
within-respondent comparisons. With blocking = "random" the vignettes are
shuffled and dealt out; block sizes are still exactly equal, but nothing
guarantees that any individual block is well balanced.
Optimal blocking is the better default, but it is a search: with an awkward number of blocks it can fail to converge, in which case the function falls back to random allocation and says so.
The function does not write files. Use fs_export() to write a design to
disk in a form a survey platform will accept.
Value
An object of class fs_design, which inherits from data.frame.
It has one row per selected vignette, the attribute columns, and a
block column. The following attributes are attached:
factorsThe list of attributes and levels supplied.
d_efficiencyThe D-efficiency in percent, relative to a hypothetical orthogonal design of the same size; see
fs_efficiency().a_efficiencyThe A-efficiency in percent.
linearThe attributes treated as linear.
n_candidatesThe number of candidate combinations searched.
modelThe model formula the design was optimised for.
blockingThe blocking method used.
block_criterionThe raw blocked criterion from
AlgDesign::optBlock(), orNAfor random or absent blocking. It is an internal search criterion, not an efficiency.
References
Fedorov, V. V. (1972). Theory of Optimal Experiments. Academic Press.
Kuhfeld, W. F., Tobias, R. D. and Garratt, M. (1994). Efficient experimental design with marketing research applications. Journal of Marketing Research, 31(4), 545–557. doi:10.1177/002224379403100408
See Also
fs_efficiency() for the efficiency of any design,
fs_design_eval() for level balance and correlation diagnostics,
set_labels() for attaching the wording shown to respondents,
fs_vignette_text() for turning rows into prose, fs_assign() for
allocating blocks and presentation orders to respondents.
Examples
attrs <- list(
damage = c("minor", "moderate", "severe"),
distance = c("near", "far"),
cost = c(100, 500, 1000)
)
d <- fs_defficient(attrs, n_vignettes = 12, n_blocks = 2,
seed = 42, verbose = FALSE)
head(as.data.frame(d))
table(d$block)
# Exclude a combination that would not make sense to a respondent
d2 <- fs_defficient(attrs, n_vignettes = 9,
restrictions = ~ damage == "minor" & cost == 1000,
seed = 42, verbose = FALSE)
any(d2$damage == "minor" & d2$cost == 1000)
Diagnostics for a factorial survey design
Description
Reports how evenly the levels of each attribute appear in a design and how strongly the attributes are correlated with one another. A well-behaved design has near-equal level counts and near-zero correlations; large correlations mean the effects of the attributes involved will be hard to separate.
Usage
fs_design_eval(
design,
by_block = TRUE,
factors = NULL,
model = NULL,
linear = NULL
)
Arguments
design |
An object of class |
by_block |
A logical value. If |
factors, model, linear |
Passed to |
Value
An object of class fs_design_eval, a list with components:
balanceA list of tables of level counts, one per attribute.
balance_by_blockA list of tables of level counts by block, or
NULLwhenby_blockisFALSEor there is a single block.correlationThe correlation matrix of the attributes, computed on their numeric codes.
max_abs_correlationThe largest absolute off-diagonal correlation.
efficiencyThe result of
fs_efficiency(): D- and A-efficiency in percent, estimability and missing levels.n_vignettesThe number of vignettes.
See Also
Examples
d <- fs_defficient(list(damage = c("low", "high"),
distance = c("near", "far"),
cost = c(100, 500, 1000)),
n_vignettes = 12, n_blocks = 2,
seed = 7, verbose = FALSE)
fs_design_eval(d)
D- and A-efficiency of a factorial survey design
Description
Computes the D-efficiency and A-efficiency of a set of vignettes, expressed as a percentage of a hypothetical orthogonal and balanced design with the same number of rows. A value of 100 means the design is as informative as an orthogonal array; an orthogonal array, where one exists, attains 100.
Use it to check a design produced by fs_defficient() or any design built
elsewhere, for example one used in an earlier survey.
Usage
fs_efficiency(design, factors = NULL, model = ~., linear = NULL)
Arguments
design |
A data frame with one row per vignette and one column per
attribute. A |
factors |
An optional named list giving the full set of levels of each
attribute, in the form accepted by |
model |
A one-sided formula giving the model the design is meant to
estimate. The default |
linear |
An optional character vector naming numeric attributes that
enter the model as a single linear term rather than as a set of level
effects. Defaults to |
Details
Each attribute is coded so that, over a full factorial, its columns have
mean zero, unit mean square and are mutually orthogonal: orthogonal
polynomial contrasts scaled by \sqrt{k} for an attribute with
k levels, and the standardised value for an attribute listed in
linear. With this coding an orthogonal and balanced design has
information matrix X'X/N = I, and the efficiencies are
D = 100 \, |X'X/N|^{1/p}, \qquad
A = 100 \, p / \mathrm{tr}\{(X'X/N)^{-1}\},
following Kuhfeld, Tobias and Garratt (1994). Both are zero when the design cannot estimate the model.
The D-efficiency is invariant to the choice of coding only up to this
normalisation, which is why the value reported by some optimisation
routines – for instance the criterion D returned by
AlgDesign::optFederov(), computed on treatment-coded dummies – is not
comparable across designs and is not an efficiency in this sense.
When restrictions exclude some combinations, 100 is usually out of reach; the value then measures the cost of the restrictions as well as the quality of the search.
Value
A list of class fs_efficiency with components:
d_efficiencyD-efficiency in percent.
a_efficiencyA-efficiency in percent.
n_vignettesThe number of rows,
N.n_parametersThe number of model parameters,
p, including the intercept.estimableTRUEwhen every parameter can be estimated, that is, when the information matrix is non-singular.missing_levelsA named list of levels that never appear in
design, with one element per attribute that has any.
References
Kuhfeld, W. F., Tobias, R. D. and Garratt, M. (1994). Efficient experimental design with marketing research applications. Journal of Marketing Research, 31(4), 545–557. doi:10.1177/002224379403100408
See Also
fs_defficient(), fs_design_eval()
Examples
# A 3^4 orthogonal array (L9) is 100 percent efficient
l9 <- data.frame(a = c(1, 1, 1, 2, 2, 2, 3, 3, 3),
b = c(1, 2, 3, 1, 2, 3, 1, 2, 3),
c = c(1, 2, 3, 2, 3, 1, 3, 1, 2),
d = c(1, 2, 3, 3, 1, 2, 2, 3, 1))
fs_efficiency(l9)
# A design that never shows the middle level cannot estimate its effect
bad <- l9
bad$a[bad$a == 2] <- 3
fs_efficiency(bad, factors = list(a = 1:3, b = 1:3, c = 1:3, d = 1:3))
Expected willingness to pay for a policy scenario
Description
Computes the expected willingness to pay (EWTP) for one or more policy
scenarios – complete bundles of attribute levels – from a model with a
logit link and a cost attribute. Where fs_mwtp() values a change in a
single attribute, fs_ewtp() values a whole scenario.
Usage
fs_ewtp(
object,
newdata,
price,
method = c("delta", "krinsky-robb"),
average = FALSE,
level = 0.95,
n_sim = 5000,
seed = NULL
)
Arguments
object |
A fitted model with a logit link: an |
newdata |
A data frame with one row per scenario, giving the level of every attribute (and any respondent covariate) in the model. The price column, if present, is ignored: EWTP is the payment the scenario is worth, not the response at a given price. Row names, when set, are used to label the scenarios. |
price |
The name of the price (cost) variable. It must enter the model as a single numeric term with a negative coefficient. |
method |
How the confidence interval is obtained: |
average |
A logical value. If |
level |
The confidence level of the interval. |
n_sim |
The number of draws used by |
seed |
A single number making the Krinsky-Robb draws reproducible, or
|
Details
Write the model's linear predictor for a scenario x offered at cost
R as x'\beta - \gamma R, where \gamma > 0 is minus the
price coefficient. With a logit link the probability of support (for
fs_logit()) or the expected rating on the unit interval (for
fs_betareg()) is \Lambda(x'\beta - \gamma R). Treating this, as in
the utility-difference model of Hanemann (1984), as the probability that
willingness to pay exceeds R, and willingness to pay as
non-negative, the expected willingness to pay is
E(\mathrm{WTP}) = \int_0^\infty \Lambda(x'\beta - \gamma R)\, dR =
\frac{1}{\gamma} \ln\{1 + \exp(x'\beta)\},
the mean of the distribution truncated at zero (Hanemann 1989). Tanaka (2025) and Tanaka et al. (2027, Eq. 6) apply it to complete policy scenarios in factorial surveys, including ratings analysed by beta regression. It is expressed in the units of the price variable.
The intercept and every attribute enter x'\beta, so EWTP depends on
the full scenario, not only on differences between scenarios, and it is
not additive: the EWTP of a bundle is not the sum of marginal WTPs. For a
beta regression the interpretation rests on reading the mean rating, after
mapping the scale to the unit interval, as a propensity to support the
scenario.
The delta-method standard error uses the gradient
\partial E / \partial \beta = \Lambda(x'\beta)\, x / \gamma and
\partial E / \partial \beta_{price} = E / \gamma. Because EWTP is a
non-linear function with \gamma in the denominator, the
Krinsky-Robb interval is preferable when the price coefficient is
imprecise.
Value
An object of class fs_ewtp, a list with components:
estimatesA data frame with one row per scenario (or a single row when
average = TRUE) and columnsscenario,index(the utility indexx'\betaat zero cost),ewtp,std_error,conf_lowandconf_high.priceThe name of the price variable.
methodThe interval method used.
levelThe confidence level.
drawsThe simulated EWTP values, for
method = "krinsky-robb"; otherwiseNULL.n_invalidThe number of Krinsky-Robb draws discarded because the simulated price coefficient was not negative.
References
Hanemann, W. M. (1984). Welfare evaluations in contingent valuation experiments with discrete responses. American Journal of Agricultural Economics, 66(3), 332–341. doi:10.2307/1240800
Hanemann, W. M. (1989). Welfare evaluations in contingent valuation experiments with discrete response data: Reply. American Journal of Agricultural Economics, 71(4), 1057–1061. doi:10.2307/1242685
Tanaka, K. (2025). A unified framework for estimating willingness to pay using factorial survey experiments. SSRN Working Paper. doi:10.2139/ssrn.5238343
Tanaka, K., Dill, J., McNeil, N., Geller, R. and Kondo, N. (2027). What are safer streets worth? Bridging resident preferences and policy design in traffic calming. Transportation Research Part A, 215, 105293. doi:10.1016/j.tra.2026.105293
See Also
fs_mwtp() for the willingness to pay for a single attribute.
Examples
set.seed(42)
n_resp <- 80
d <- data.frame(
id = rep(seq_len(n_resp), each = 4),
quality = sample(0:1, 4 * n_resp, replace = TRUE),
speed = sample(0:1, 4 * n_resp, replace = TRUE),
cost = sample(c(500, 1000, 2000), 4 * n_resp, replace = TRUE)
)
d$support <- rbinom(nrow(d), 1, plogis(0.5 + 0.8 * d$quality +
0.4 * d$speed - 0.001 * d$cost))
fit <- fs_logit(support ~ quality + speed + cost, data = d,
cluster = ~ id, compute_me = FALSE)
scenarios <- data.frame(quality = c(0, 1, 1), speed = c(0, 0, 1),
row.names = c("status quo", "quality", "both"))
fs_ewtp(fit, scenarios, price = "cost")
Write a design or schedule out for a survey platform
Description
Saves a design from fs_defficient() or a respondent schedule from
fs_assign() in a form a survey tool or a fieldwork agency will accept.
Text is always written as UTF-8, optionally with a byte order mark so that
Excel on Windows opens non-ASCII files correctly instead of showing
mojibake.
Usage
fs_export(
x,
file,
format = c("csv", "tsv", "qualtrics", "xlsx"),
by_block = FALSE,
columns = NULL,
bom = TRUE,
overwrite = FALSE
)
Arguments
x |
An |
file |
The path to write to. When the output is split by block, the
block number is inserted before the file extension, so |
format |
The output format. One of |
by_block |
A logical value. If |
columns |
An optional character vector naming the columns to write, in
the order wanted. The default writes every column except |
bom |
A logical value. If |
overwrite |
A logical value. If |
Details
"csv" and "tsv" write the object as it stands, one row per vignette or
per respondent-position.
"qualtrics" writes a loop table: one row per loop iteration, a leading
Loop column numbering the iterations, and one column per field. This is
the shape the Loop & Merge editor expects, so the file can be opened in a
spreadsheet and pasted in, with field 1 of the loop referring to the first
attribute column. Qualtrics does not publish a documented file-import
specification for Loop & Merge, so this is a table shaped for pasting rather
than a format guaranteed to import unchanged; check the field order once
before fielding. When the design has several blocks, one file per block is
written, since a loop belongs to a single block.
"xlsx" writes a single workbook with one sheet per block, named
block1, block2 and so on. This is the format fieldwork agencies most
often ask for. It requires the openxlsx package.
Value
A character vector of the paths written, invisibly.
See Also
fs_defficient(), fs_assign(), fs_vignette_text()
Examples
d <- fs_defficient(list(damage = c("minor", "severe"),
cost = c(100, 500, 1000)),
n_vignettes = 6, n_blocks = 2,
seed = 1, verbose = FALSE)
d <- fs_vignette_text(d, "Damage is {{damage}}; the cost is {{cost}}.")
# Write into the session's temporary directory
path <- file.path(tempdir(), "design.csv")
fs_export(d, path)
read.csv(path, fileEncoding = "UTF-8-BOM")[1:2, ]
# One Qualtrics loop table per block
files <- fs_export(d, file.path(tempdir(), "loop.csv"), format = "qualtrics")
basename(files)
unlink(c(path, files))
Logit model for binary responses to vignettes
Description
Fits a binary logit model to yes/no responses collected in a factorial
survey – for example, whether a respondent would support the policy
described in a vignette at the stated cost. Together with fs_betareg()
for ratings, it covers the two response formats of the framework of
Tanaka (2025); fs_mwtp() and fs_ewtp() accept either fit.
Usage
fs_logit(
formula,
data,
cluster = NULL,
compute_me = TRUE,
verbose = FALSE,
...
)
Arguments
formula |
A model formula with a binary response on the left: a
numeric 0/1 variable, a logical, or a factor with two levels (the second
level is the "yes" outcome, as in |
data |
A data frame containing the variables in |
cluster |
How to account for repeated responses from the same
respondent, exactly as in |
compute_me |
A logical value. If |
verbose |
A logical value. If |
... |
Further arguments passed to |
Details
For a binary outcome McFadden's pseudo R-squared, 1 - \ell/\ell_0, is
well defined and is reported, together with the share of responses
predicted correctly at a 0.5 threshold. Cluster-robust standard errors are
computed as in fs_betareg().
Value
An object of class fs_logit, a list with components:
modelThe fitted
stats::glm()object.vcovThe covariance matrix used for inference: cluster-robust when
clusteris given, otherwise model-based.clusterA list describing the clustering, or
NULL.marginal_effectsThe
marginsobject, orNULL.gofA named list of fit measures:
logLik,logLik_null,AIC,BIC,lr_stat,lr_df,lr_p_value,pseudo_r2_mcfadden,percent_correctandnobs.callThe matched call.
References
Tanaka, K. (2025). A unified framework for estimating willingness to pay using factorial survey experiments. SSRN Working Paper. doi:10.2139/ssrn.5238343
See Also
fs_ewtp() and fs_mwtp() for willingness to pay,
fs_betareg() for rating responses.
Examples
set.seed(42)
n_resp <- 80
d <- data.frame(
id = rep(seq_len(n_resp), each = 4),
quality = sample(0:1, 4 * n_resp, replace = TRUE),
cost = sample(c(500, 1000, 2000), 4 * n_resp, replace = TRUE)
)
taste <- rnorm(n_resp, sd = 0.5)[d$id]
d$support <- rbinom(nrow(d), 1,
plogis(1 + 0.8 * d$quality - 0.001 * d$cost + taste))
fit <- fs_logit(support ~ quality + cost, data = d, cluster = ~ id,
compute_me = FALSE)
summary(fit)
fs_mwtp(fit, price = "cost")
Extract components from a factorial survey logit model
Description
Methods that forward to the underlying stats::glm() fit. vcov()
returns the covariance matrix used for inference, which is cluster-robust
when the model was fitted with cluster.
Usage
## S3 method for class 'fs_logit'
coef(object, ...)
## S3 method for class 'fs_logit'
vcov(object, ...)
## S3 method for class 'fs_logit'
logLik(object, ...)
## S3 method for class 'fs_logit'
nobs(object, ...)
## S3 method for class 'fs_logit'
fitted(object, ...)
Arguments
object |
An object of class |
... |
Passed on to the corresponding method for |
Value
The value returned by the corresponding glm method.
Examples
set.seed(1)
d <- data.frame(id = rep(1:30, each = 4), x = rnorm(120))
d$y <- rbinom(120, 1, plogis(0.8 * d$x))
fit <- fs_logit(y ~ x, data = d, cluster = ~ id, compute_me = FALSE)
coef(fit)
vcov(fit)
Marginal willingness to pay from a fitted model
Description
Converts a pair of estimated coefficients into a marginal willingness to pay (MWTP), the amount of the price attribute a respondent would trade for a one-unit improvement in another attribute:
MWTP = -\beta_{attribute} / \beta_{price}.
Because MWTP is a ratio of two estimates its sampling distribution is skewed, and more so the closer the price coefficient sits to zero. Three interval methods are therefore offered, and it is worth comparing them before reporting a result.
Usage
fs_mwtp(
object,
variable = NULL,
price,
method = c("delta", "krinsky-robb", "fieller"),
level = 0.95,
n_sim = 5000,
seed = NULL
)
Arguments
object |
A fitted model: an |
variable |
The name of the attribute coefficient, as it appears in
|
price |
The name of the price coefficient. |
method |
The interval method. One of |
level |
The confidence level. Defaults to |
n_sim |
The number of draws used by |
seed |
A single number making the Krinsky-Robb draws reproducible, or
|
Details
The delta method takes a first-order Taylor expansion of the ratio and yields a symmetric interval. It is quick and familiar but understates skewness, and can produce implausible intervals when the price coefficient is imprecisely estimated.
Krinsky and Robb (1986) draw repeatedly from a multivariate normal with the estimated mean and covariance of the coefficients, form the ratio in each draw, and read the interval off the empirical quantiles. This captures the skewness and is the usual recommendation in the stated preference literature.
Fieller's theorem inverts the test that the ratio equals a given value. It
is exact under normality of the coefficients but the resulting region is
unbounded when the price coefficient is not clearly distinguishable from
zero; in that case the interval is returned as NA with a warning.
The coefficients enter on the scale of the linear predictor. For a beta regression with a logit link the ratio is therefore a ratio of effects on the latent scale, which is the conventional definition of MWTP but is not the same as the ratio of average marginal effects on the response scale.
Value
An object of class fs_mwtp, a list with components:
estimatesA data frame with one row per attribute and columns
variable,mwtp,std_error,conf_lowandconf_high.priceThe name of the price coefficient.
methodThe interval method used.
levelThe confidence level.
drawsThe simulated MWTP values, for
method = "krinsky-robb"; otherwiseNULL.
References
Krinsky, I. and Robb, A. L. (1986). On approximating the statistical properties of elasticities. Review of Economics and Statistics, 68(4), 715–719. doi:10.2307/1924536
Fieller, E. C. (1954). Some problems in interval estimation. Journal of the Royal Statistical Society, Series B, 16(2), 175–185. doi:10.1111/j.2517-6161.1954.tb00159.x
See Also
Examples
set.seed(123)
n <- 200 # 50 respondents x 4 vignettes
d <- data.frame(
id = rep(1:50, each = 4),
quality = sample(0:1, n, replace = TRUE),
speed = rnorm(n),
price = runif(n, 100, 1000)
)
d$rating <- 10 * plogis(0.8 * d$quality + 0.3 * d$speed -
0.0015 * d$price + rnorm(n, sd = 0.5))
fit <- fs_betareg(rating ~ quality + speed + price, data = d,
cluster = ~ id, compute_me = FALSE)
# All attributes at once
fs_mwtp(fit, price = "price")
# A single attribute, with a simulation-based interval
fs_mwtp(fit, variable = "quality", price = "price",
method = "krinsky-robb", n_sim = 500, seed = 1)
Plot estimates with confidence intervals
Description
Draws a forest plot – one point and interval per row – of willingness to
pay or of the effects of the attributes. Each method returns a
ggplot2::ggplot() object, so titles, labels and themes can be changed
with the usual + syntax.
Usage
## S3 method for class 'fs_mwtp'
plot(x, ...)
## S3 method for class 'fs_ewtp'
plot(x, ...)
## S3 method for class 'fs_betareg'
plot(x, type = c("auto", "ame", "coef"), level = 0.95, ...)
## S3 method for class 'fs_logit'
plot(x, type = c("auto", "ame", "coef"), level = 0.95, ...)
Arguments
x |
An object of class |
... |
Ignored. |
type |
For model fits only: |
level |
For |
Details
Rows appear from top to bottom in the order of the estimates. A dashed vertical line marks zero. The plots use a single dark colour and no fill, so they reproduce in black and white.
Value
A ggplot object.
Examples
set.seed(1)
n <- 240
d <- data.frame(id = rep(1:60, each = 4),
quality = rbinom(n, 1, 0.5),
speed = rbinom(n, 1, 0.5),
price = sample(c(100, 300, 500), n, replace = TRUE))
d$rating <- round(10 * plogis(0.8 * d$quality + 0.4 * d$speed -
0.004 * d$price + rnorm(n, sd = 0.5)))
fit <- fs_betareg(rating ~ quality + speed + price, data = d,
cluster = ~ id, compute_me = FALSE)
plot(fs_mwtp(fit, price = "price"))
plot(fit, type = "coef")
plot(fs_ewtp(fit, data.frame(quality = c(0, 1, 1), speed = c(0, 0, 1),
row.names = c("none", "quality", "both")),
price = "price")) +
ggplot2::labs(x = "Expected WTP (yen)")
Power and precision of a factorial survey by simulation
Description
Answers the two questions asked when a factorial survey is planned: with
this design and this many respondents, how likely is each attribute effect
to be detected, and how precisely will willingness to pay be estimated?
Data are simulated repeatedly with fs_simulate_ratings() and analysed
exactly as real data would be – fs_betareg() or fs_logit() with
standard errors clustered by respondent – and the results are summarised.
Usage
fs_power(
design,
n_respondents,
coef,
formula,
price = NULL,
response = c("rating", "binary"),
phi = 10,
sd_respondent = 0.5,
scale = c(0, 10),
round = TRUE,
alpha = 0.05,
n_sim = 200,
seed = NULL,
verbose = TRUE
)
Arguments
design |
Either an |
n_respondents |
A vector of sample sizes to evaluate. |
coef |
A named numeric vector of coefficients on the logit scale. The
names must match the columns of the model matrix implied by |
formula |
A one-sided formula giving the systematic part of the
model, such as |
price |
Optional name of the price variable. When given, the precision of the marginal willingness to pay for each other attribute is also reported. |
response |
The kind of response to generate: |
phi |
The precision of the beta distribution for ratings. Larger values give less noise around the mean. Ignored for binary responses. |
sd_respondent |
The standard deviation of a normally distributed
respondent-specific shift on the logit scale. It makes the ratings of one
respondent correlated, as they are in real data. Use |
scale |
A numeric vector of length two giving the bounds of the rating scale. |
round |
A logical value. If |
alpha |
The significance level of the two-sided tests. |
n_sim |
The number of simulated surveys per sample size. |
seed |
A single number making the simulation reproducible, or |
verbose |
A logical value. If |
Details
Each simulated survey uses the same design and allocation rules as
fs_assign(). Effects are tested with cluster-robust Wald tests, so the
respondent-level correlation introduced by sd_respondent is taken into
account, as it would be in the real analysis.
Because coefficients estimated without a respondent effect are attenuated
when sd_respondent > 0, power refers to detecting the effect that the
analysis actually estimates. The true MWTP is the ratio of the supplied
coefficients, which the attenuation leaves almost unchanged.
Choosing coef is the hard part. Values from a pilot study or a similar
published survey are best. Run time grows with n_sim times the number of
sample sizes; 200 to 500 simulations are usually enough to compare
designs.
Value
An object of class fs_power, a data frame with one row per
sample size and model term, and the columns:
n_respondentsThe sample size.
termThe model term (a column of the model matrix).
coefThe true coefficient on the logit scale.
powerThe share of simulated surveys in which the term was significant at level
alpha.mwtpThe true marginal willingness to pay, when
priceis given.mwtp_halfwidthThe average half-width of the delta-method confidence interval for the MWTP, in units of the price variable.
mwtp_relativeThat half-width as a share of the true MWTP: 0.2 means the interval is roughly the estimate plus or minus 20 percent.
The settings, the number of failed fits and n_sim are attached as
attributes.
See Also
fs_simulate_ratings(), fs_defficient()
Examples
design <- fs_defficient(
list(damage = c("minor", "severe"), cost = c(100, 300, 500)),
n_vignettes = 6, n_blocks = 2, seed = 1, verbose = FALSE
)
pw <- fs_power(design, n_respondents = c(50, 150),
coef = c("(Intercept)" = 1, damagesevere = 0.4,
cost = -0.003),
formula = ~ damage + cost, price = "cost",
n_sim = 20, seed = 1, verbose = FALSE)
pw
plot(pw)
Simulate responses to a factorial survey
Description
Generates artificial responses to a design from a model whose coefficients
you choose. Because the true values are known, the result is useful for
checking that an analysis recovers them, for teaching, and – through
fs_power() – for deciding how many respondents a survey needs.
Usage
fs_simulate_ratings(
design,
n_respondents = NULL,
coef,
formula,
response = c("rating", "binary"),
phi = 10,
sd_respondent = 0.5,
scale = c(0, 10),
round = TRUE,
name = if (response == "rating") {
"rating"
} else {
"response"
},
seed = NULL
)
Arguments
design |
Either an |
n_respondents |
The number of respondents. Required when |
coef |
A named numeric vector of coefficients on the logit scale. The
names must match the columns of the model matrix implied by |
formula |
A one-sided formula giving the systematic part of the
model, such as |
response |
The kind of response to generate: |
phi |
The precision of the beta distribution for ratings. Larger values give less noise around the mean. Ignored for binary responses. |
sd_respondent |
The standard deviation of a normally distributed
respondent-specific shift on the logit scale. It makes the ratings of one
respondent correlated, as they are in real data. Use |
scale |
A numeric vector of length two giving the bounds of the rating scale. |
round |
A logical value. If |
name |
The name of the response column. |
seed |
A single number making the simulation reproducible, or |
Details
For respondent i and vignette j the linear predictor is
\eta_{ij} = x_{ij}'\beta + u_i with
u_i \sim N(0, \sigma_u^2), and \mu_{ij} = \Lambda(\eta_{ij}).
A rating is drawn from a beta distribution with mean \mu_{ij} and
precision \phi and mapped onto scale; a binary response is drawn
from a Bernoulli distribution with probability \mu_{ij}.
Because of the respondent shift, coefficients estimated by fs_betareg()
or fs_logit(), which do not model it, are attenuated towards zero
relative to coef; ratios such as willingness to pay are much less
affected.
Value
The schedule as a data frame (class fs_assignment retained) with
the response column added. The coefficients, phi, sd_respondent and
scale used are attached as the truth attribute.
See Also
fs_power(), which repeats the simulation to estimate power.
Examples
design <- fs_defficient(
list(damage = c("minor", "severe"), cost = c(100, 300, 500)),
n_vignettes = 6, n_blocks = 2, seed = 1, verbose = FALSE
)
sim <- fs_simulate_ratings(
design, n_respondents = 60,
coef = c("(Intercept)" = 1, damagesevere = 0.8, cost = -0.004),
formula = ~ damage + cost, seed = 1
)
head(sim)
fit <- fs_betareg(rating ~ damage + cost, data = sim,
cluster = ~ respondent, compute_me = FALSE)
fs_mwtp(fit, price = "cost") # true value: 0.8 / 0.004 = 200
Turn design rows into vignette prose
Description
Fills a sentence template with the attribute levels of each row, producing
the text that will be shown to respondents. Placeholders are written
{{attribute}}, and optional formatting functions let numbers be rendered
as currency, dates, or anything else, without changing the design itself.
Usage
fs_vignette_text(
design,
template,
column = "vignette_text",
format = NULL,
na_text = ""
)
Arguments
design |
An object of class |
template |
A single character string containing the sentence, with
|
column |
The name of the column to add. Defaults to |
format |
An optional named list of functions, one per attribute, each taking the column's values and returning a character vector of the same length. Use this to render numbers the way respondents should read them. |
na_text |
The text substituted for missing values. |
Details
Substitution is literal: whatever the formatting function returns is placed
in the sentence unchanged. Word order, particles and agreement are the
template author's responsibility, which keeps the behaviour predictable in
any language. Where a level needs different wording in different sentences,
the usual approach is to apply set_labels() first, or to pass a formatting
function here.
Value
The input data frame with the text column added, keeping its class
and attributes. The template is attached as the template attribute.
See Also
set_labels() for attaching level labels, fs_export() for
writing the result out.
Examples
d <- fs_defficient(list(damage = c("minor", "severe"),
cost = c(100, 1000)),
n_vignettes = 4, seed = 1, verbose = FALSE)
d <- fs_vignette_text(
d,
"This building suffered {{damage}} damage. Repair costs {{cost}}."
)
d$vignette_text
# Render the cost as currency without altering the design column
d2 <- fs_vignette_text(
d,
"Repairs cost {{cost}} per year.",
column = "cost_sentence",
format = list(cost = function(x) paste0("$", formatC(x, big.mark = ",")))
)
d2$cost_sentence
Construct a Williams design
Description
Builds a set of presentation orders in which every item appears equally often in every position and every ordered pair of items appears equally often as immediate neighbours. The second property is what distinguishes a Williams design from an ordinary Latin square: it balances first-order carryover, so that the effect of having just seen one vignette on the rating of the next does not confound any attribute.
Usage
fs_williams(k)
Arguments
k |
The number of items to be ordered – in a factorial survey, the number of vignettes one respondent sees. |
Details
The first order is built as 1, 2, k, 3, k-1, 4, \ldots, and the
remaining orders are cyclic shifts of it. For even k this single square is
already balanced. For odd k no single square can be, so the square is
paired with its mirror image, and each ordered pair of neighbours then
occurs exactly twice.
Value
An integer matrix with k columns. Each row is one presentation
order, giving the item shown in each position. There are k rows when k
is even and 2 * k rows when k is odd, which is the smallest number of
orders that achieves carryover balance.
References
Williams, E. J. (1949). Experimental designs balanced for the estimation of residual effects of treatments. Australian Journal of Scientific Research, Series A, 2(2), 149–168. doi:10.1071/CH9490149
See Also
fs_assign(), which uses this to allocate orders to respondents.
Examples
# Even k: one square is enough
fs_williams(4)
# Odd k: the square is paired with its mirror image
fs_williams(3)
# Every item appears once in every position
table(fs_williams(4)[, 1])
Plot a power analysis
Description
Draws power against the number of respondents, one panel per model term, with a dashed line at 0.8.
Usage
## S3 method for class 'fs_power'
plot(x, ...)
Arguments
x |
An object of class |
... |
Ignored. |
Value
A ggplot object.
Examples
design <- fs_defficient(list(a = c("x", "y"), cost = c(1, 2, 3)),
n_vignettes = 6, seed = 1, verbose = FALSE)
pw <- fs_power(design, c(20, 60), coef = c("(Intercept)" = 0, ay = 0.5,
cost = -0.3),
formula = ~ a + cost, n_sim = 10, seed = 1,
verbose = FALSE)
plot(pw)
Print a respondent schedule
Description
Print a respondent schedule
Usage
## S3 method for class 'fs_assignment'
print(x, n = 10L, ...)
Arguments
x |
An object of class |
n |
The number of rows to show. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
d <- fs_defficient(list(a = 1:2, b = 1:3), n_vignettes = 6,
seed = 1, verbose = FALSE)
print(fs_assign(d, n_respondents = 4, seed = 1))
Print a fitted factorial survey beta regression
Description
Print a fitted factorial survey beta regression
Usage
## S3 method for class 'fs_betareg'
print(x, digits = 4, ...)
Arguments
x |
An object of class |
digits |
Number of significant digits. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
set.seed(1)
d <- data.frame(id = rep(1:20, each = 3), x = rnorm(60))
d$rating <- 10 * plogis(0.5 * d$x + rnorm(60, sd = 0.4))
print(fs_betareg(rating ~ x, data = d, cluster = ~ id,
compute_me = FALSE))
Print a factorial survey design
Description
Print a factorial survey design
Usage
## S3 method for class 'fs_design'
print(x, n = 10L, ...)
Arguments
x |
An object of class |
n |
The number of rows to show. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
d <- fs_defficient(list(a = 1:2, b = 1:3), n_vignettes = 6,
seed = 1, verbose = FALSE)
print(d)
Print design diagnostics
Description
Print design diagnostics
Usage
## S3 method for class 'fs_design_eval'
print(x, digits = 3, ...)
Arguments
x |
An object of class |
digits |
Number of digits used for the correlation matrix. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
d <- fs_defficient(list(a = 1:2, b = 1:3), n_vignettes = 6,
seed = 1, verbose = FALSE)
print(fs_design_eval(d))
Print design efficiencies
Description
Print design efficiencies
Usage
## S3 method for class 'fs_efficiency'
print(x, ...)
Arguments
x |
An object of class |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
print(fs_efficiency(expand.grid(a = 1:2, b = 1:3)))
Print expected willingness to pay estimates
Description
Print expected willingness to pay estimates
Usage
## S3 method for class 'fs_ewtp'
print(x, digits = 4, ...)
Arguments
x |
An object of class |
digits |
Number of significant digits. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
set.seed(1)
d <- data.frame(id = rep(1:40, each = 4), q = rbinom(160, 1, 0.5),
cost = sample(c(100, 300, 500), 160, replace = TRUE))
d$y <- rbinom(160, 1, plogis(0.5 + d$q - 0.004 * d$cost))
fit <- fs_logit(y ~ q + cost, data = d, cluster = ~ id, compute_me = FALSE)
print(fs_ewtp(fit, data.frame(q = 0:1), price = "cost"))
Print a fitted factorial survey logit model
Description
Print a fitted factorial survey logit model
Usage
## S3 method for class 'fs_logit'
print(x, digits = 4, ...)
Arguments
x |
An object of class |
digits |
Number of significant digits. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
set.seed(1)
d <- data.frame(id = rep(1:30, each = 4), x = rnorm(120))
d$y <- rbinom(120, 1, plogis(0.8 * d$x))
print(fs_logit(y ~ x, data = d, cluster = ~ id, compute_me = FALSE))
Print marginal willingness to pay estimates
Description
Print marginal willingness to pay estimates
Usage
## S3 method for class 'fs_mwtp'
print(x, digits = 4, ...)
Arguments
x |
An object of class |
digits |
Number of significant digits. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
set.seed(1)
d <- data.frame(id = rep(1:40, each = 3), x = rnorm(120),
price = runif(120, 100, 900))
d$rating <- 10 * plogis(0.7 * d$x - 0.002 * d$price + rnorm(120, sd = 0.4))
fit <- fs_betareg(rating ~ x + price, data = d, cluster = ~ id,
compute_me = FALSE)
print(fs_mwtp(fit, price = "price"))
Print a power analysis
Description
Print a power analysis
Usage
## S3 method for class 'fs_power'
print(x, digits = 2, ...)
Arguments
x |
An object of class |
digits |
Number of digits. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
design <- fs_defficient(list(a = c("x", "y"), cost = c(1, 2, 3)),
n_vignettes = 6, seed = 1, verbose = FALSE)
print(fs_power(design, 40, coef = c("(Intercept)" = 0, ay = 0.5,
cost = -0.3),
formula = ~ a + cost, n_sim = 10, seed = 1,
verbose = FALSE))
Print the summary of a factorial survey beta regression
Description
Print the summary of a factorial survey beta regression
Usage
## S3 method for class 'summary.fs_betareg'
print(x, digits = 4, ...)
Arguments
x |
An object of class |
digits |
Number of significant digits. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
set.seed(1)
d <- data.frame(id = rep(1:20, each = 3), x = rnorm(60))
d$rating <- 10 * plogis(0.5 * d$x + rnorm(60, sd = 0.4))
print(summary(fs_betareg(rating ~ x, data = d, cluster = ~ id,
compute_me = FALSE)))
Print the summary of a factorial survey logit model
Description
Print the summary of a factorial survey logit model
Usage
## S3 method for class 'summary.fs_logit'
print(x, digits = 4, ...)
Arguments
x |
An object of class |
digits |
Number of significant digits. |
... |
Ignored. |
Value
x, invisibly. Called for the side effect of printing.
Examples
set.seed(1)
d <- data.frame(id = rep(1:30, each = 4), x = rnorm(120))
d$y <- rbinom(120, 1, plogis(0.8 * d$x))
print(summary(fs_logit(y ~ x, data = d, cluster = ~ id,
compute_me = FALSE)))
Attach readable level labels to design or survey variables
Description
Converts one or more columns of a data frame into factors with explicit
labels. This is normally applied to a design produced by
fs_defficient(), whose columns carry the level codes used in the
questionnaire rather than the wording shown to respondents, or to a returned
data set in which the attributes are stored as integer codes.
Usage
set_labels(df, label_list, levels_list = NULL, strict = TRUE)
Arguments
df |
A data frame. |
label_list |
A named list of character vectors. Each name must match a
column of |
levels_list |
An optional named list giving, for each variable, the
values in |
strict |
A logical value. If |
Value
The input data frame, with the named columns replaced by labelled
factors. Other columns and all attributes of df are left unchanged.
See Also
fs_defficient() for generating the design these labels describe.
Examples
d <- data.frame(alert = c(1, 2, 1), timing = c(2, 1, 2), rating = c(7, 3, 8))
# Numeric codes 1, 2 are matched to labels in order
set_labels(d, list(alert = c("Low", "High"),
timing = c("Morning", "Evening")))
# Codes that do not start at 1 are given explicitly
d0 <- data.frame(alert = c(0, 1, 0))
set_labels(d0, list(alert = c("Absent", "Present")),
levels_list = list(alert = c(0, 1)))
Summarise a fitted factorial survey beta regression
Description
Summarise a fitted factorial survey beta regression
Usage
## S3 method for class 'fs_betareg'
summary(object, ...)
Arguments
object |
An object of class |
... |
Ignored. |
Value
An object of class summary.fs_betareg, a list holding the
betareg summary, the fit measures and the rescaled marginal
effects.
Examples
set.seed(1)
d <- data.frame(id = rep(1:20, each = 3), x = rnorm(60))
d$rating <- 10 * plogis(0.5 * d$x + rnorm(60, sd = 0.4))
summary(fs_betareg(rating ~ x, data = d, cluster = ~ id,
compute_me = FALSE))
Summarise a fitted factorial survey logit model
Description
Summarise a fitted factorial survey logit model
Usage
## S3 method for class 'fs_logit'
summary(object, ...)
Arguments
object |
An object of class |
... |
Ignored. |
Value
An object of class summary.fs_logit, a list holding the
coefficient table (with cluster-robust standard errors when the model was
fitted with cluster), the fit measures and the marginal effects.
Examples
set.seed(1)
d <- data.frame(id = rep(1:30, each = 4), x = rnorm(120))
d$y <- rbinom(120, 1, plogis(0.8 * d$x))
summary(fs_logit(y ~ x, data = d, cluster = ~ id, compute_me = FALSE))
A plain theme for factorial survey plots
Description
The theme used by the package's plot methods: white background, light horizontal guides, no minor grid and no vertical grid. Add it to your own plots for a consistent look.
Usage
theme_fs(base_size = 11, base_family = "")
Arguments
base_size |
Base font size, in points. |
base_family |
Base font family. |
Value
A ggplot2::theme() object.
Examples
library(ggplot2)
ggplot(mtcars, aes(wt, mpg)) + geom_point() + theme_fs()