SpreadHits: Spread hits across a network in clusters

In alexjcornish/SANTA: Spatial Analysis of Network Associations

Description

Spread hits across a network in one or more clusters using an exponential probability distribution related to the distance of each vertex from a seed vertex.

Usage

SpreadHits(g, h, clusters=1, distance.cutoff=3, lambda=1, 
dist.method=c("shortest.paths", "diffusion", "mfpt"), 
edge.attr=NULL, hit.color="red", D=NULL, attempts=1000, verbose=TRUE)

Arguments

g	igraph object, the network to work on.
h	Integer value, the number of hits in each cluster.
clusters	Integer value, the number of clusters to add the network.
distance.cutoff	Integer value, the minimum distance between the seed vertex of each cluster.
lambda	Numeric value, the strength of hit clustering. If lambda == 0, then the hits are randomly distributed. If lambda > 0, then the hits are clustered. The greater the value of lambda, the greater the strength of the hit clustering.
dist.method	String, the method used to compute the distance between each vertex and the seed vertex.
edge.attr	String, the name of the edge attribute to be used as distances along the edges. If NULL, then each edge is assumed to have a distance of 1. Smaller edge distances denote stronger interactions between vertex pairs.
hit.color	String, the colour of the hits if the network is plotted.
D	Pre-computed numeric distance matrix. If NULL, then D is computed within the function.
attempts	Integer value, the number of attempts made at each stage of the placement algorithm before the function terminates.
verbose	Logical, if TRUE messages about the progress of the function are displayed.

Details

SpreadHits can be used to add hits to a network without hits, or replace hits on a network with hits. The probability of a vertex being labelled as a hit depends on its distance from a randomly chosen starting vertex. The value of lambda denotes the shape of the probability distribution used to spread the hits. The greater the value of lambda, the greater the strength of hit clustering. The probability of vertex i being a hit is proportional to

P[i] \sim lambda^{-d[start,i]}

where d[start,i] is the distance between the start vertex and vertex i.

Hits can be added in one or more clusters. If multiple clusters are being added, then the function first identifies an equal number of seed vertices at least distance.cutoff distance apart in the network. If the function cannot identify vertices that satisfy this condition within the specified number of attempts, then it returns NULL. If the function is able to find suitable seed vertices, then it proceeds to label vertices positioned around each seed vertex as hits, using a probability function shaped by lambda.

Whether a vertex is a hit or a miss is given in the vertex attribute hits. If the vertex is a hit, then it has the score 1. If it is a miss, then it has the score 0. A color can also be chosen to highlight the hits when the network is plotted. Misses are automatically coloured grey.

Value

A modified version of the input igraph object. Whether a vertex is a hit or miss is given under the vertex attribute hits.

Author(s)

Alex J. Cornish [e-mail]

Examples

# create a network and add 1 cluster of 3 hits
g1 <- erdos.renyi.game(30, p.or.m=0.1, directed=FALSE)
g1 <- SpreadHits(g1, h=3, clusters=1, lambda=10)
plot(g1, layout=layout.fruchterman.reingold)

# create a network and add 2 clusters of 3 hits
g2 <- erdos.renyi.game(30, p.or.m=0.1, directed=FALSE)
g2 <- SpreadHits(g2, h=3, clusters=3, distance.cutoff=2, lambda=0)
plot(g2, layout=layout.fruchterman.reingold)

alexjcornish/SANTA documentation built on Aug. 7, 2021, 3:06 p.m.