Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 15
RanCh
June 14, 2019
Title Tools for abstract discrete Random Choice
URL http://github.com/mccauslw/RanCh
BugReports http://github.com/mccauslw/RanCh/issues
Version 0.0.0.9000
Description This package provides tools for a research project whose purpose is to help us
better understand the foundations of stochastic discrete choice. It includes datasets
compiled from the literature on context effects and stochastic intransitivity and from
some recent experiments. It provides graphical tools to display likelihood function and
posterior density contours, as well as regions, in the space of choice probabilities,
defined by various stochastic choice axioms, context effects and other conditions.
Imports klaR,
MASS,
bitops,
Smisc,
ggtern
Depends R (>= 3.6.0)
License CC0
Encoding UTF-8
LazyData true
RoxygenNote 6.1.1
Suggests knitr,
rmarkdown
VignetteBuilder knitr
Rtopics documented:
create_P........................................... 2
dDir ............................................. 3
dDir3_quantile ....................................... 3
dDir_max .......................................... 4
dDir_moments ....................................... 4
Dir3_HD_region ...................................... 5
Dir_mult_ML........................................ 5
Ind_Dir_mult_ML ..................................... 6
marginalize ......................................... 6
1
2create_P
multiplicative_X3...................................... 7
PC_counts.......................................... 7
PC_demographics...................................... 8
PC_raw ........................................... 8
PC_trials .......................................... 9
plot_HD_Dir3........................................ 9
plot_P3 ........................................... 10
proportions ......................................... 10
RanCh............................................ 11
RCD_prior_1 ........................................ 11
regularity_X3 ........................................ 11
YG_counts ......................................... 12
YG_demographics ..................................... 12
YG_raw........................................... 13
YG_trials .......................................... 14
Index 15
create_P Random Choice Structure for a three-object universe
Description
create_P creates a random choice structure for a three-object universe from
Usage
create_P(p12, p23, p13, P1, P2, names = c("x", "y", "z"))
Arguments
p12 Probability of chosing object 1 when presented with objects 1 and 2
p23 Probability of chosing object 2 when presented with objects 2 and 3
P1 Probability of chosing object 1 when presented with objects 1, 2 and 3
P2 Probability of chosing object 2 when presented with objects 1, 2 and 3
P13 Probability of chosing object 1 when presented with objects 1 and 3
Value
A Random Choice Structure
Examples
P = create_P(21/40, 37/40, 28/40, 19/40, 15/40, names=c('Red','Purple','Pink'))
P
dDir 3
dDir Dirichlet density
Description
dDir computes the Dirichlet density at a point pin the regular simplex, for a vector alpha of
Dirichlet parameters.
Usage
dDir(p, alpha, log = TRUE)
Arguments
pvector of probabilities on the regular simplex
alpha vector of Dirichlet parameters
log logical; if TRUE, the log density is returned
Value
density or log density value
dDir3_quantile Quantile of third order Dirichlet density value
Description
dDir3_quantile computes an approximation of the given quantile of a third order Dirichlet density
value, under that Dirichlet distribution.
Usage
dDir3_quantile(quantile, alpha, normalized = FALSE)
Arguments
quantile the quantile of the desired density value
alpha a vector of Dirichlet parameters
normalized binary; if TRUE, return the quantile as a fraction of the maximum density value;
if FALSE, return the unnormalized quantile.
Value
The value of the quantile, normalized or not
4dDir_moments
dDir_max Maximum density of a Dirichlet distribution
Description
max_dDir computes the maximum density of a Dirichlet distribution as a function of the parameter
vector alpha.
Usage
dDir_max(alpha, log = TRUE)
Arguments
alpha vector of Dirichlet parameters.
log logical; if TRUE, the log maximum density is returned.
Value
Density or log density value.
dDir_moments Moments of Dirichlet density values
Description
moments_dDi computes a vector of the first n raw moments of Dirichlet density values, under that
Dirichlet distribution.
Usage
dDir_moments(beta, n_mu, log = FALSE)
Arguments
n_mu number of moments to compute.
log logical; if true return log moments.
alpha vector of Dirichlet parameters.
Value
vector of moments
Dir3_HD_region 5
Dir3_HD_region Compute highest density (HD) region for a third order Dirichlet dis-
tribution
Description
This function computes a polygon approximating the highest density region of a third order Dirich-
let distribution. This can be used to compute highest prior density and highest posterior density
(HPD) regions.
Usage
Dir3_HD_region(alpha, HD_probability)
Arguments
alpha a vector of three (positive) Dirichlet parameters.
HD_probability probability of region to construct
Value
polygon approximation of HD region.
Dir_mult_ML Marginal likelihood for Dirichlet-multinomial model
Description
Dir_mult_ML computes the marginal likelihood for a Dirichlet prior and multinomial data generat-
ing process.
Usage
Dir_mult_ML(alpha, N, log = TRUE)
Arguments
alpha vector of Dirichlet parameters
Nvector of multinomial counts
log logical; if TRUE, return the log Bayes factor.
Value
Marginal likelihood or log marginal likelihood
6marginalize
Ind_Dir_mult_ML Marginal likelihood for independent Dirichlet-multinomial model
Description
Ind_Dir_mult_ML computes the marginal likelihood for a model where rows of a count matrix
are independent multinomial and the rows of the unknown random choice structure are a priori
independent Dirichlet.
Usage
Ind_Dir_mult_ML(A, N, log = TRUE)
Arguments
Amatrix of Dirichlet parameters, each row giving the Dirichlet distribution of the
corresponding row of a random choice structure.
Ncount matrix for a universe of objects.
log logical; if TRUE, return the log Bayes factor
marginalize Routines for simple manipulations of count matrices and random
choice structures.
Description
Marginalize a count matrix or random choice structure
Usage
marginalize(input_N, objects)
Arguments
input_N A count matrix
objects A vector of objects to retain
Details
This function takes as input a count matrix or random choice structure on a universe of objects and
returns a marginalization of it to a universe that is a subset of the original universe.
Value
A count matrix
Examples
N_bce = marginalize(PC_counts, c(2,3,5))
P_abd = marginalize()
N
multiplicative_X3 7
multiplicative_X3 Compute a cross section of the multiplicative inequality region
Description
multiplicative_X3 computes the region (a triangle) of ternary probabilities consistent with given
binary probabilities and the multiplicative inequality.
Usage
multiplicative_X3(P)
Arguments
PA random choice structure
Value
A 3x3 matrix where each row gives one of the three vertices, in barycentric coordinates, of the
triangular region where the multiplicative inequality holds.
Examples
P = create_P(0.7, 0.6, 0.8, 0.6, 0.3, 0.1, names = c('x','y','z'))
multiplicative_X3(P)
PC_counts Counts
Description
A 32x26x5 matrix with count data.
Usage
PC_counts
Format
An object of class array of dimension 32 x 31 x 5.
8PC_raw
PC_demographics Demographic information for subjects
Description
Demographic information for subjects
Usage
PC_demographics
Format
A data frame with demographic information on subjects
sex Sex of subject
age Age of subject in years
location Province or territory in Canada
PC_raw Population Choice experiment data
Description
Record of every choice made by every respondant.
Usage
PC_raw
Format
A data frame with 17 variables:
design
gender Sex of respondant: 1 for male, 2 for female
PC_trials 9
PC_trials Record of all choice trials
Description
Record of all choice trials
Usage
PC_trials
Format
A data frame with 14 variables
subj Subject identifier
domain Factor indicating choice domain
trial Trial identifier (gives the order in which a subject sees choice sets)
subs Factor indicating the choice subset presented: ’ab’, ’cde’, etc., objects always in alphabetical
order
choice Factor indicating the choice made: ’a’, ’b’, ’c’, ’d’ or ’e’
subs_conf Subset configuration, the order objects appear on the screen: ’ba’, ’ecd’, etc., objects
not necessarily in alphabetical order
subs_bin Code for subset where digits of binary representation indicate object membership
choice_int Integer code for chosen object
ab Revealed preference indicator: 1 for a revealed preferred to b, -1 for b revealed preferred to a, 0
otherwise. This is the first of ten revealed preference columns, each pertaining to a particular
doubleton set.
plot_HD_Dir3 Plot highest density region for a third order Dirichlet distribution
Description
This function plots the Dirichlet highest density region in barycentric coordinates.
Usage
plot_HD_Dir3(A, HD_probability)
Arguments
HD_probability probability of highest density region
alpha vector of Dirichlet parameters
Examples
plot_HD_Dir_3(0.95, c(23, 13, 4))
10 proportions
plot_P3 Plot a Random Choice Structure in barycentric coordinates
Description
plot_P3 plots four points specifying a Random Choice Structure for a universe of three objects.
Usage
plot_P3(P, perm = c(1, 2, 3), binary_pch = 1, ternary_pch = 20)
Arguments
PA random choice structure for a universe of three objects
perm A permutation of (1, 2, 3) specifying which objects in the universe correspond
to the bottom left, top, and bottom right vertex, respectively of the ternary plot.
binary_pch Plotting character (pch) for binary choice probabilities. Defaults to a hollow
circle.
ternary_pch Plotting character (pch) for ternary choice probability. Defaults to a solid circle.
The convention established with the defaults for binary_pch and ternary_pch
allow one to distinguish between a binary choice probability and a ternary choice
probability that happens to be on the boundary of the triangle.
Examples
P = create_P(0.7, 0.6, 0.8, 0.6, 0.3, 0.1, names = c('x','y','z'))
plot_P3(P)
proportions Random Choice Structure from count proportions
Description
proportions takes a count matrix as input, and returns choice proportions as a random choice
structure.
Usage
proportions(N)
Arguments
NA count matrix.
Value
A random choice structure.
Examples
PC_P = proportions(PC_counts)
RanCh 11
RanCh RanCh: A package for abstract discrete Random Choice
Description
The RanCh package provides data, graphical tools and inference tools for abstract discrete random
choice analysis.
Data sets
NA
RCD_prior_1 One-parameter Dirichlet prior for a RCS
Description
RCS_prior_1 computes a matrix of Dirichlet parameters for a one-parameter Dirichlet prior for a
random choice structure.
Usage
RCD_prior_1(alpha, n_objects)
Arguments
alpha univariate parameter for the one-parameter Dirichlet prior.
n_objects number of objects in the universe.
Value
a matrix of Dirichlet parameters with the same dimensions as a count matrix for a universe of the
same size.
regularity_X3 Compute a cross section of the regularity region
Description
regularity_X3 computes the region (a triangle or the empty set) of ternary probabilities consistent
with given binary probabilities and the regularity condition.
Usage
regularity_X3(P)
12 YG_demographics
Arguments
PA random choice structure.
Value
If the region is empty, the output is NULL. Otherwise, a 3x3 matrix where each row gives one of
the three vertices in barycentric coordinates.
Examples
P = create_P(0.7, 0.6, 0.8, 0.6, 0.3, 0.1, names = c('x','y','z'))
reg_region = regularity_X3(P)
YG_counts Counts
Description
A 3x16x15x4 matrix with count data.
Usage
YG_counts
Format
An object of class table of dimension 16 x 11 x 4.
YG_demographics Demographic information for subjects
Description
Demographic information for subjects
Usage
YG_demographics
Format
A data frame with demographic information on subjects
sex Sex of subject
educ Educational attainment by subject
region Region of subject’s residence in US
race Race of subject
age_range Age range of subject
YG_raw 13
YG_raw YouGov Experiment data
Description
Record of every choice made by every respondant.
Usage
YG_raw
Format
A data frame with 17 variables:
design
card
domain
combo
perm
choiceset Choice set as a character string
option_1 Object presented in first position: 1, 2, 3 or 4
option_2 Object presented in second position
option_3 Object presented in third position
option_4 Object presented in fourth position
response Object chosen: 1, 2, 3 or 4
order
gender Sex of respondant: 1 for male, 2 for female
educ Education of respondant: 1 for No high school, 2 for High school graduate, 3 for Some
college, 4 for 2-year college, 5 for 4-year college, 6 for post-graduate
region Region of respondant: 1 for northeast, 2 for midwest, 3 for south, 4 for west
race Race of respondant: 1 for White, 2 for Black, 3 for Hispanic, 4 for Asian, 5 for Native
American, 6 for Mixed, 7 for Other, 8 for Middle Eastern
age_cross Age category of respondant: 1 for 18-34, 2 for 35-54, 3 for 55 and over
14 YG_trials
YG_trials Record of all choice trials
Description
Record of all choice trials
Usage
YG_trials
Format
A data frame with 14 variables
subj Subject identifier
domain Factor indicating choice domain
trial Trial identifier (gives the order in which a subject sees choice sets)
subs Factor indicating the choice subset presented: ’ab’, ’cde’, etc.
choice Factor indicating the choice made: ’a’, ’b’, ’c’ or ’d’
subs_conf Subset configuration, the order objects appear on the screen
subs_bin Code for subset where digits of binary representation indicate object membership
choice_int Integer code for chosen object
ab Revealed preference indicator: 1 for a revealed preferred to b, -1 for b revealed preferred to a, 0
otherwise
Index
∗Topic Multiplicative
multiplicative_X3,7
∗Topic datasets
PC_counts,7
PC_demographics,8
PC_raw,8
PC_trials,9
YG_counts,12
YG_demographics,12
YG_raw,13
YG_trials,14
∗Topic inequality
multiplicative_X3,7
create_P,2
dDir,3
dDir3_quantile,3
dDir_max,4
dDir_moments,4
Dir3_HD_region,5
Dir_mult_ML,5
Ind_Dir_mult_ML,6
marginalize,6
multiplicative_X3,7
PC_counts,7
PC_demographics,8
PC_raw,8
PC_trials,9
plot_HD_Dir3,9
plot_P3,10
proportions,10
RanCh,11
RanCh-package (RanCh),11
RCD_prior_1,11
regularity_X3,11
YG_counts,12
YG_demographics,12
YG_raw,13
YG_trials,14
15
