R: Attribute Interface Methods for the Network Class

attribute.methods {network} | R Documentation

## Attribute Interface Methods for the Network Class

### Description

These methods get, set, list, and delete attributes at the network, edge, and vertex level.

### Usage

    delete.edge.attribute(x, attrname, ...)

    ## S3 method for class 'network'
    delete.edge.attribute(x, attrname, ...)

    delete.network.attribute(x, attrname, ...)

    ## S3 method for class 'network'
    delete.network.attribute(x, attrname, ...)

    delete.vertex.attribute(x, attrname, ...)

    ## S3 method for class 'network'
    delete.vertex.attribute(x, attrname, ...)

    get.edge.attribute(x, ..., el)

    ## S3 method for class 'network'
    get.edge.attribute(
      x,
      attrname,
      unlist = TRUE,
      na.omit = FALSE,
      null.na = FALSE,
      deleted.edges.omit = FALSE,
      ...,
      el
    )

    ## S3 method for class 'list'
    get.edge.attribute(
      x,
      attrname,
      unlist = TRUE,
      na.omit = FALSE,
      null.na = FALSE,
      deleted.edges.omit = FALSE,
      ...,
      el
    )

    get.edge.value(x, ...)

    ## S3 method for class 'network'
    get.edge.value(
      x,
      attrname,
      unlist = TRUE,
      na.omit = FALSE,
      null.na = FALSE,
      deleted.edges.omit = FALSE,
      ...
    )

    ## S3 method for class 'list'
    get.edge.value(
      x,
      attrname,
      unlist = TRUE,
      na.omit = FALSE,
      null.na = FALSE,
      deleted.edges.omit = FALSE,
      ...
    )

    get.network.attribute(x, ...)

    ## S3 method for class 'network'
    get.network.attribute(x, attrname, unlist = FALSE, ...)

    get.vertex.attribute(x, ...)

    ## S3 method for class 'network'
    get.vertex.attribute(
      x,
      attrname,
      na.omit = FALSE,
      null.na = TRUE,
      unlist = TRUE,
      ...
    )

    list.edge.attributes(x, ...)

    ## S3 method for class 'network'
    list.edge.attributes(x, ...)

    list.network.attributes(x, ...)

    ## S3 method for class 'network'
    list.network.attributes(x, ...)

    list.vertex.attributes(x, ...)

    ## S3 method for class 'network'
    list.vertex.attributes(x, ...)

    network.vertex.names(x)

    network.vertex.names(x) <- value

    set.edge.attribute(x, attrname, value, e, ...)

    ## S3 method for class 'network'
    set.edge.attribute(x, attrname, value, e = seq_along(x$mel), ...)

    set.edge.value(x, attrname, value, e, ...)

    ## S3 method for class 'network'
    set.edge.value(x, attrname, value, e = seq_along(x$mel), ...)

    set.network.attribute(x, attrname, value, ...)

    ## S3 method for class 'network'
    set.network.attribute(x, attrname, value, ...)

    set.vertex.attribute(x, attrname, value, v = seq_len(network.size(x)), ...)

    ## S3 method for class 'network'
    set.vertex.attribute(x, attrname, value, v = seq_len(network.size(x)), ...)

### Arguments

`x` | an object of class `network`, or a list of edges (possibly `network$mel`) in `get.edge.attribute`.
`attrname` | the name of the attribute to get or set.
`...` | additional arguments
`el` | Deprecated; use `x` instead.
`unlist` | logical; should retrieved attribute values be `unlist`ed prior to being returned?
`na.omit` | logical; should retrieved attribute values corresponding to vertices/edges marked as 'missing' be removed?
`null.na` | logical; should `NULL` values (corresponding to vertices or edges with no values set for the attribute) be replaced with `NA`s in output?
`deleted.edges.omit` | logical: should the elements corresponding to deleted edges be removed?
`value` | values of the attribute to be set; these should be in `vector` or `list` form for the `edge` and `vertex` cases, or `matrix` form for `set.edge.value`.
`e` | IDs for the edges whose attributes are to be altered.
`v` | IDs for the vertices whose attributes are to be altered.

### Details

The `list.attributes` functions return the names of all edge, network, or vertex attributes (respectively) in the network. All attributes need not be defined for all elements; the union of all extant attributes for the respective element type is returned.

The `get.attribute` functions look for an edge, network, or vertex attribute (respectively) with the name `attrname`, returning its values. Note that, to retrieve an edge attribute from all edges within a network `x`, `x$mel` should be used as the first argument to `get.edge.attribute`; `get.edge.value` is a convenience function which does this automatically. As of v1.7.2, if a `network` object is passed to `get.edge.attribute` it will automatically call `get.edge.value` instead of returning NULL. When the parameters `na.omit`, or `deleted.edges.omit` are used, the position index of the attribute values returned will not correspond to the vertex/edge id. To preserved backward compatibility, if the edge attribute `attrname` does not exist for any edge, `get.edge.attribute` will still return `NULL` even if `null.na=TRUE`

`network.vertex.names` is a convenience function to extract the `"vertex.names"` attribute from all vertices.

The `set.attribute` functions allow one to set the values of edge, network, or vertex attributes. `set.edge.value` is a convenience function which allows edge attributes to be given in adjacency matrix form, and the assignment form of `network.vertex.names` is likewise a convenient front-end to `set.vertex.attribute` for vertex names. The `delete.attribute` functions, by contrast, remove the named attribute from the network, from all edges, or from all vertices (as appropriate). If `attrname` is a vector of attribute names, each will be removed in turn. These functions modify their arguments in place, although a pointer to the modified object is also (invisibly) returned.

Additional practical example of how to load and attach attributes are on the `loading.attributes` page.

Some attribute assignment/extraction can be performed conveniently through the various extraction/replacement operators, although they may be less efficient. See the associated man page for details.

### Value

For the `list.attributes` methods, a vector containing attribute names. For the `get.attribute` methods, a list containing the values of the attribute in question (or simply the value itself, for `get.network.attribute`). For the `set.attribute` and `delete.attribute` methods, a pointer to the updated `network` object.

### Note

As of version 1.9 the `set.vertex.attribute` function can accept and modify multiple attributes in a single call to improve efficiency. For this case `attrname` can be a list or vector of attribute names and `value` is a list of values corresponding to the elements of `attrname` (can also be a list of lists of values if elements in v should have different values).

### Author(s)

Carter T. Butts buttsc@uci.edu

### References

Butts, C. T. (2008). “network: a Package for Managing Relational Data in R.” Journal of Statistical Software, 24(2). https://www.jstatsoft.org/v24/i02/

### See Also

`loading.attributes`,`network`, `as.network.matrix`, `as.sociomatrix`, `as.matrix.network`, `network.extraction`

### Examples

    #Create a network with three edges
    m<-matrix(0,3,3)
    m[1,2]<-1; m[2,3]<-1; m[3,1]<-1
    g<-network(m)

    #Create a matrix of values corresponding to edges
    mm<-m
    mm[1,2]<-7; mm[2,3]<-4; mm[3,1]<-2

    #Assign some attributes
    set.edge.attribute(g,"myeval",3:5)
    set.edge.value(g,"myeval2",mm)
    set.network.attribute(g,"mygval","boo")
    set.vertex.attribute(g,"myvval",letters[1:3])
    network.vertex.names(g) <- LETTERS[1:10]

    #List the attributes
    list.edge.attributes(g)
    list.network.attributes(g)
    list.vertex.attributes(g)

    #Retrieve the attributes
    get.edge.attribute(g$mel,"myeval")  #Note the first argument!
    get.edge.value(g,"myeval")          #Another way to do this
    get.edge.attribute(g$mel,"myeval2")
    get.network.attribute(g,"mygval")
    get.vertex.attribute(g,"myvval")
    network.vertex.names(g)

    #Purge the attributes
    delete.edge.attribute(g,"myeval")
    delete.edge.attribute(g,"myeval2")
    delete.network.attribute(g,"mygval")
    delete.vertex.attribute(g,"myvval")

    #Verify that the attributes are gone
    list.edge.attributes(g)
    list.network.attributes(g)
    list.vertex.attributes(g)

    #Note that we can do similar things using operators
    g %n% "mygval" <- "boo"               #Set attributes, as above
    g %v% "myvval" <- letters[1:3]
    g %e% "myeval" <- mm
    g[,,names.eval="myeval"] <- mm          #Another way to do this
    g %n% "mygval"                        #Retrieve the attributes
    g %v% "myvval"
    g %e% "mevval"
    as.sociomatrix(g,"myeval")              # Or like this

[Package network version 1.17.2 Index]