rem (version 1.1.2)

reciprocityStat: Calculate reciprocity statistics

Description

Calculate the endogenous network statistic reciprocity for relational event models. reciprocity measures the tendency for senders to reciprocate prior events where they were targeted by other senders. One-mode network statistic only.

Usage

reciprocityStat(data, time, sender, target, halflife, 
    weight = NULL, 
    eventtypevar = NULL, 
    eventtypevalue = "valuematch", 
    eventattributevar = NULL,
    eventattributevalue = "valuematch", 
    variablename = "reciprocity",
    returnData = FALSE, 
    showprogressbar = FALSE)

Arguments

data

A data frame containing all the variables.

time

Numeric variable that represents the event sequence. The variable has to be sorted in ascending order.

sender

A string (or factor or numeric) variable that represents the sender of the event.

target

A string (or factor or numeric) variable that represents the target of the event.

halflife

A numeric value that is used in the decay function. The vector of past events is weighted by an exponential decay function using the specified halflife. The halflife parameter determines after how long a period the event weight should be halved. E.g. if halflife = 5, the weight of an event that occurred 5 units in the past is halved. Smaller halflife values give more importance to more recent events, while larger halflife values should be used if time does not affect the time between events that much.

weight

An optional numeric variable that represents the weight of each event. If weight = NULL each event is given an event weight of 1.

eventtypevar

An optional variable that represents the type of the event. Use eventtypevalue to specify how the eventtypevar should be used to filter past events.

eventtypevalue

An optional value (or set of values) used to specify how paste events should be filtered depending on their type. eventtypevalue = "valuematch" indicates that only past events that have the same type as the current event should be used to calculate the reciprocity statistic. eventtypevalue = "valuemix" indicates that past and present events of specific types should be used for the reciprocity statistic. All the possible combinations of the eventtypevar-values will be used. E.g. if eventtypevar contains three unique values "a" and "b", 4 reciprocity statistics will be calculated. The first variable calculates the reciprocity effect where the present event is of type "a" and all the past events are of type "b". The next variable calculates reciprocity for present events of type "b" and past events of type "a". Additionally, a variable is calculated, where present events as well as past events are of type "a" and a fourth variable calculates reciprocity for events with type "b" (i.e. valuematch on value "b"). eventtypevalue = c(.., ..), similar to the "nodmix"-option, all different combinations of the values specified in eventtypevalue are used to create reciprocity statistics.

eventattributevar

An optinoal variable that represents an attribute of the event. It can be a sender attribute, a target attribute, time or dyad attribute. Use eventattributevalue to specify how the eventattributevar should be used.

eventattributevalue

An optional value (or set of values) used to specify how past events should be filtered depending on their attribute. Similar to eventtypevalue. eventattributevalue = "valuematch" indicates that only past events that have the same attribute should be used to calculate the reciprocity statistic. eventtypevalue = "valuemix" indicates that past and present events of specific attributes should be used for the reciprocity statistic. All the possible combinations of the eventattributevar-values will be used. eventtypevalue = c(.., ..) similar to the "valuemix"-option, all different combinations of the values specified in eventtypevalue are used to create reciprocity statistics.

variablename

An optional value (or values) with the name the reciprocity statistic variable should be given. To be used if returnData = TRUE or multiple reciprocity statistics are calculated.

returnData

TRUE/FALSE. Set to FALSE by default. The new variable(s) are bound directly to the data.frame provided and the data frame is returned in full.

showprogressbar

TRUE/FALSE. To be implemented.

Details

The reciprocityStat()-function calculates an endogenous statistic that measures whether senders have a tendency to reciprocate events.

The effect is calculated as follows:

$$G_t = G_t(E) = (A, B, w_t), $$

\(G_t\) represents the network of past events and includes all events \(E\). These events consist each of a sender \(a \in A\) and a target \(b \in B\) and a weight function \(w_t\):

$$ w_t(i, j) = \sum_{e:a = i, b = j} | w_e | \cdot e^{-(t-t_e)\cdot\frac{ln(2)}{T_{1/2}}} \cdot \frac{ln(2)}{T_{1/2}}, $$

where \(w_e\) is the event weight (usually a constant set to 1 for each event), \(t\) is the current event time, \(t_e\) is the past event time and \(T_{1/2}\) is a halflife parameter.

For the reciprocity effect, the past events \(G_t\) are filtered to include only events where the senders are the present targets and the targets are the present senders:

$$reciprocity(G_t , a , b) = w_t(b, a)$$

An exponential decay function is used to model the effect of time on the endogenous statistics. Each past event that involves the sender as target and the target as sender, and fulfills additional filtering options specified via event type or event attributes, is weighted with an exponential decay. The further apart the past event is from the present event, the less weight is given to this event. The halflife parameter in the reciprocityStat()-function determines at which rate the weights of past events should be reduced.

The eventtypevar- and eventattributevar-options help filter the past events more specifically. How they are filtered depends on the eventtypevalue- and eventattributevalue-option.

See Also

rem-package

Examples

# create some data with 'sender', 'target' and a 'time'-variable
# (Note: Data used here are random events from the Correlates of War Project)
sender <- c('TUN', 'NIR', 'NIR', 'TUR', 'TUR', 'USA', 'URU', 
            'IRQ', 'MOR', 'BEL', 'EEC', 'USA', 'IRN', 'IRN', 
            'USA', 'AFG', 'ETH', 'USA', 'SAU', 'IRN', 'IRN',
            'ROM', 'USA', 'USA', 'PAN', 'USA', 'USA', 'YEM', 
            'SYR', 'AFG', 'NAT', 'NAT', 'USA')
target <- c('BNG', 'ZAM', 'JAM', 'SAU', 'MOM', 'CHN', 'IRQ', 
            'AFG', 'AFG', 'EEC', 'BEL', 'ITA', 'RUS', 'UNK',
            'IRN', 'RUS', 'AFG', 'ISR', 'ARB', 'USA', 'USA',
            'USA', 'AFG', 'IRN', 'IRN', 'IRN', 'AFG', 'PAL',
            'ARB', 'USA', 'EEC', 'BEL', 'PAK')
time <- c('800107', '800107', '800107', '800109', '800109', 
          '800109', '800111', '800111', '800111', '800113',
          '800113', '800113', '800114', '800114', '800114', 
          '800116', '800116', '800116', '800119', '800119',
          '800119', '800122', '800122', '800122', '800124', 
          '800125', '800125', '800127', '800127', '800127', 
          '800204', '800204', '800204')
type <- sample(c('cooperation', 'conflict'), 33,
               replace = TRUE)
important <- sample(c('important', 'not important'), 33,
               replace = TRUE)

# combine them into a data.frame
dt <- data.frame(sender, target, time, type, important)

# create event sequence and order the data
dt <- eventSequence(datevar = dt$time, dateformat = '%y%m%d', 
                    data = dt, type = "continuous", 
                    byTime = 'daily', returnData = TRUE,
                    sortData = TRUE)

# calculate reciprocity statistic
dt$recip <- reciprocityStat(data = dt,
                            time = dt$time, 
                            sender = dt$sender, 
                            target = dt$target,
                            halflife = 2)

# plot sender-outdegree over time
library('ggplot2')
ggplot(dt, aes ( event.seq.cont, recip) ) +
  geom_point()+ geom_smooth() 

# calculate reciprocity statistic with typematch
# if a cooperated with b in the past, does
# b cooperate with a now?
dt$recip.typematch <- reciprocityStat(data = dt,
                                      time = dt$time, 
                                      sender = dt$sender, 
                                      target = dt$target,
                                      eventtypevar = dt$type,
                                      eventtypevalue = 'valuematch',
                                      halflife = 2)

# calculate reciprocity with valuemix on type
dt <- reciprocityStat(data = dt,
                      time = dt$time,
                      sender = dt$sender,
                      target = dt$target, 
                      eventtypevar = dt$type,
                      eventtypevalue = 'valuemix',
                      halflife = 2, 
                      variablename = 'recip',
                      returnData = TRUE)

# calculate reciprocity and count important events only
dt$recip.im <- reciprocityStat(data = dt,
                               time = dt$time, 
                               sender = dt$sender, 
                               target = dt$target,
                               eventattributevar = dt$important,
                               eventattributevalue = 'important',
                               halflife = 2)