Skip to contents

Add an actor line to a actor nodelist data frame

add_actor.Rd

The nodelist is a data frame that contains information for the actors in a simulation, including names and EPA dictionaries and equations. Actors also have optional parameters that control how they manage uncertainty in interactions.

Usage

add_actor(
  nodelist,
  name,
  dicts = "usfullsurveyor2015",
  dict_stat = "mean",
  dict_group = "all",
  dict_file_prefix = "dict",
  eqns = "us2010",
  eqns_group = c("all", "female"),
  alphas = NA,
  betas = NA,
  deltas = NA,
  numsamples = NA
)

Arguments

nodelist

a data frame to add the actor line to

name

a string to use as the actor's name

dicts

one of several options (see Details):

  • 1a: A dictionary key from actdata. Data is pulled from that package and split into the four required components based on the component column.

  • 1b: A list of four dictionary keys from actdata to be used for, in order, own identities, behaviors, partner identities, and emotions. The same key may be used for more than one category.

  • 2a: An EPA data frame with a "component" column that is used to split it into a list of length 4 following the above order.

  • 2b: A list of four EPA data frames in order: own identities, behaviors, partner identities, emotions. Use "list()", rather than "c()", to construct this list.

  • 3: A list of four file paths to csv files containing the required dictionaries.

dict_stat

string or string list length 4: stat of provided dictionaries (mean, cov, sd). For data sets in actdata, check available stats with actdata::dict_info().

dict_group

string or string list length 4: respondent subset of provided dictionaries (usually genders; all, female, male). For data sets in actdata, check available groups with actdata::dict_info().

dict_file_prefix

prefix to append to dictionary data files that are written out. Default is "dict."

eqns

string or string list length 2 providing equations to use. See Details. Entries must either by equation keys from the actdata package or valid filepaths to coefficient matrices. If provided as a length 2 list, the first entry is used as the impression ABO coefficients and the second as the emotion coefficients. If a single entry (only possible for coefficients in actdata), the function attempts to find these two components itself.

eqns_group

string or string list length 2: respondent subset of equations to use (usually genders; all, female, male). For datasets in actdata, check available groups with actdata::eqn_info(). An error is thrown if the specified equation set is not available for the specified group.

alphas

numeric or numeric list length 3: alpha value(s) to use. See Details.

betas

numeric or numeric list length 2: beta value(s) to use. See Details.

deltas

numeric or numeric list length 2: delta value(s) to use. See Details.

numsamples

numeric: number of samples to be used by the actor for each interaction. Default is 1000.

Value

provided nodelist with actor line appended

Dictionaries and equations

Each actor needs four dictionaries representing:

  1. the EPA values for identities they assign to themselves

  2. the EPA values they assign to behaviors that are valid within the interaction

  3. the EPA values for identities they assign to their interaction partners

  4. the EPA values they assign to modifiers and emotions.

They also need two sets of equation coefficients:

  1. Impression equation coefficients which determine ideal elements of A-B-O (actor-behavior-object) events. In actdata, these are referred to with the "impressionabo" keyword.

  2. Emotion equation coefficients which estimate emotional reactions to events. In actdata, these are referred to with the "emotionid" keyword.

These dictionaries and equations can be provided in one of three ways (mixing and matching is allowed):

  • If you are working with publicly available ACT sentiment dictionaries and equation sets, dictionaries may be specified using keywords from the actdata package. This package is a repository for standardized versions of many publicly available ACT sentiment dictionaries and equation sets, and it and bayesactR were developed to complement each other. If using dictionaries and/or equations from actdata, provide the applicable keyword as the dict or eqns argument. To see information about available data sets and group subsets, see the package readme or call actdata::dict_info() or actdata::eqn_info().

  • Dictionaries can also be provided as data frame objects. This is particularly useful when you wish to use a subset of terms from a public dictionary–for example, perhaps you only want your agents to be able to take a limited set of behaviors, or identities from just one institution, rather than having access to the whole list. The actdata::epa_subset() function within actdata makes creating subsets from public data straightforward.

  • If you have collected or estimated your own data or otherwise have access to non-public data sets, you may provide a filepath to the dictionary and equation files in the dict and eqns arguments. These must be properly formatted for BayesACT. When provided with filepaths, bayesactR passes them directly to BayesACT with no formatting checks or changes. See also actdata::format_for_bayesact(), which can help reformat datasets correctly.

Parameters alpha, beta, and delta

There are three parameters that control how actors tend to respond to interactions. In each case, these parameters can be set separately for the relevant elements of the situation (actor, behavior, and client/object), or can be provided as a single number which is applied across elements.

For more information on these parameters, see the BayesACT Version 2: Technical Users Manual, available in the BayesACT C directory under the subdirectory bayesact/docs/. The following is a summary of description found there.

  • Alpha (a set of three values alpha_a, alpha_b, alpha_c) represents the strength of the affect control principle (higher value is weaker; default is 0.1).

  • Beta (a set of two values beta_a and beta_c) represents identity sentiment inertia, or how stable we expect EPA values for identities to remain over time. Default is 0.01.

  • Delta (a set of two values delta_a and delta_c) represents denotative identity stability, or how likely it is that someone is relabeled. Default is 0.1.

If the actor is given optional arguments (alphas, betas, deltas, numsamples) that are not already columns in the data frame, these columns will be added.

Examples

nodelist <- blank_nodelist()
nodelist <- add_actor(nodelist, name = "Sally", dict_stat = "cov")
nodelist <- add_actor(nodelist, name = "Reem", dicts = "egypt2015", dict_stat = "cov",
    eqns = "egypt2014")
nodelist <- add_actor(nodelist, name = "Jamal",
    dicts = c("indiana2003", "usmturk2015", "indiana2003", "indiana2003"), alphas = .5)