R: Helper functions for specifying nodal attribute levels

node-attr-api {ergm} | R Documentation

## 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 `node-attr`.

`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"), multiple = if (accept == "character") "paste" else "stop", ...)

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

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

    ## S3 method for class 'formula'
    ergm_get_vattr(object, nw, accept = "character",
      bip = c("n", "b1", "b2"), 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 '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_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, and `"b2"` for the second.
`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.

### Format

An object of class `character` of length 3.

### 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 beconverted 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.

`"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. It 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.

### Examples

    data(florentine)
    ergm_get_vattr("priorates", flomarriage)
    ergm_get_vattr(~priorates, flomarriage)
    ergm_get_vattr(c("wealth","priorates"), flomarriage)
    ergm_get_vattr(~priorates>30, flomarriage)
    (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)

[Package ergm version 3.10.4 Index]