R: Helper functions for specifying nodal attribute levels

nodal_attributes-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 `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.
`l, 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)

[Package ergm version 4.1.2 Index]