nodal_attributes-API: Helper functions for specifying nodal attribute levels

In ergm: Fit, Simulate and Diagnose Exponential-Family Models for Networks

Helper functions for specifying nodal attribute levels

Description

These functions are meant to be used in InitErgmTerm and other implementations to provide the user with a way to extract nodal attributes and select their levels in standardized and flexible ways described under nodal_attributes.

ergm_get_vattr extracts and processes the specified nodal attribute vector. It is strongly recommended that check.ErgmTerm()'s corresponding vartype="function,formula,character" (using the ERGM_VATTR_SPEC constant).

ergm_attr_levels filters the levels of the attribute. It is strongly recommended that check.ErgmTerm()'s corresponding vartype="function,formula,character,numeric,logical,AsIs,NULL" (using the ERGM_LEVELS_SPEC constant).

Usage

ERGM_GET_VATTR_MULTIPLE_TYPES

ergm_get_vattr(
  object,
  nw,
  accept = "character",
  bip = c("n", "b1", "b2", "a"),
  multiple = if (accept == "character") "paste" else "stop",
  ...
)

## S3 method for class 'AsIs'
ergm_get_vattr(
  object,
  nw,
  accept = "character",
  bip = c("n", "b1", "b2", "a"),
  multiple = if (accept == "character") "paste" else "stop",
  ...
)

## S3 method for class 'character'
ergm_get_vattr(
  object,
  nw,
  accept = "character",
  bip = c("n", "b1", "b2", "a"),
  multiple = if (accept == "character") "paste" else "stop",
  ...
)

## S3 method for class ''function''
ergm_get_vattr(
  object,
  nw,
  accept = "character",
  bip = c("n", "b1", "b2", "a"),
  multiple = if (accept == "character") "paste" else "stop",
  ...
)

## S3 method for class 'formula'
ergm_get_vattr(
  object,
  nw,
  accept = "character",
  bip = c("n", "b1", "b2", "a"),
  multiple = if (accept == "character") "paste" else "stop",
  ...
)

ergm_attr_levels(object, attr, nw, levels = sort(unique(attr)), ...)

## S3 method for class 'numeric'
ergm_attr_levels(object, attr, nw, levels = sort(unique(attr)), ...)

## S3 method for class 'logical'
ergm_attr_levels(object, attr, nw, levels = sort(unique(attr)), ...)

## S3 method for class 'AsIs'
ergm_attr_levels(object, attr, nw, levels = sort(unique(attr)), ...)

## S3 method for class 'character'
ergm_attr_levels(object, attr, nw, levels = sort(unique(attr)), ...)

## S3 method for class ''NULL''
ergm_attr_levels(object, attr, nw, levels = sort(unique(attr)), ...)

## S3 method for class 'matrix'
ergm_attr_levels(object, attr, nw, levels = sort(unique(attr)), ...)

## S3 method for class ''function''
ergm_attr_levels(object, attr, nw, levels = sort(unique(attr)), ...)

## S3 method for class 'formula'
ergm_attr_levels(object, attr, nw, levels = sort(unique(attr)), ...)

ERGM_VATTR_SPEC

ERGM_VATTR_SPEC_NULL

ERGM_LEVELS_SPEC

Arguments

object	An argument specifying the nodal attribute to select or which levels to include.
nw	Network on the LHS of the formula.
accept	A character vector listing permitted data types for the output. See the Details section for the specification.
bip	Bipartedness mode: affects either length of attribute vector returned or the length permited: "n" for full network, "b1" for first mode of a bipartite network, "b2" for the second, and "a" for not adjusting.
multiple	Handling of multiple attributes or matrix or data frame output. See the Details section for the specification.
...	Additional argument to the functions of network or to the formula's environment.
attr	A vector of length equal to the number of nodes, specifying the attribute vector.
levels	Starting set of levels to use; defaults to the sorted list of unique attributes.
a	arguments to LARGEST, which is actually a function that gets processed as a function level spec does.

Format

An object of class character of length 3.

An object of class character of length 1.

An object of class character of length 1.

An object of class character of length 1.

Details

The accept argument is meant to allow the user to quickly check whether the output is of an acceptable class or mode. Typically, if a term accepts a character (i.e., categorical) attribute, it will also accept a numeric one, treating each number as a category label. For this reason, the following outputs are defined:

"character"

Accept any mode or class (since it can be converted to character).

"numeric"

Accept real, integer, or logical.

"logical"

Accept logical.

"integer"

Accept integer or logical.

"natural"

Accept a strictly positive integer.

"0natural"

Accept a nonnegative integer or logical.

"nonnegative"

Accept a nonnegative number or logical.

"positive"

Accept a strictly positive number or logical.

"index"

Accept input appropriate for selecting from an unnamed vector: an integer or a logical; positive integers are returned as they are (bip ignored), logicals are right-sized, and negative integers reverse the selection (as with vector indexing).

Given that, the multiple argument controls how passing multiple attributes or functions that result in vectors of appropriate dimension are handled:

"paste"

Paste together with dot as the separator.

"stop"

Fail with an error message.

"matrix"

Construct and/or return a matrix whose rows correspond to vertices.

Value

ergm_get_vattr returns a vector of length equal to the number of nodes giving the selected attribute function or, if multiple="matrix", a matrix whose number of row equals the number of nodes. Either may also have an attribute "name", which controls the suggested name of the attribute combination.

ergm_attr_levels returns a vector of levels to use and their order.

Note

ergm_attr_levels.matrix() expects ⁠levels=⁠ to be a list with each element having length 2 and containing the values of the two categorical attributes being crossed. It also assumes that they are in the same order as the user would like them in the matrix.

Examples

data(florentine)
ergm_get_vattr("priorates", flomarriage)
ergm_get_vattr(~priorates, flomarriage)
ergm_get_vattr(~cbind(priorates, priorates^2), flomarriage, multiple="matrix")
ergm_get_vattr(c("wealth","priorates"), flomarriage)
ergm_get_vattr(c("wealth","priorates"), flomarriage, multiple="matrix")
ergm_get_vattr(~priorates>30, flomarriage)
ergm_get_vattr(~TRUE, flomarriage, accept="index")
ergm_get_vattr(~-(2:12), flomarriage, accept="index")
(a <- ergm_get_vattr(~cut(priorates,c(-Inf,0,20,40,60,Inf),label=FALSE)-1, flomarriage))
ergm_attr_levels(NULL, a, flomarriage)
ergm_attr_levels(-1, a, flomarriage)
ergm_attr_levels(1:2, a, flomarriage)
ergm_attr_levels(I(1:2), a, flomarriage)

ergm documentation built on Oct. 7, 2024, 5:08 p.m.