*! version 1.0 05apr2011

help dyads

Title

dyads -- Transform observations into dyads

Syntax

dyads idvar [, DYadvars(varlist)]

Description

dyads takes a set of N observations and returns a set of
(N(N-1))/2 dyads. Observations are identified by idvar,
which must be specified. The user can also specify via
DYadvars() any variables whose values should be added in for the
second half of the created dyads; the default is to copy only the
value of idvar for the other half of the dyad.

Remarks

dyads is designed to take a file that has N
observations, indexed by some idvar, and create a file that has
(N(N-1))/2 dyads representing all the possible pairs of
observations in the original dataset. The command is meant to be used
as a preface to calculating dyad-based statistics, as one might do for
many types of network analyses. In addition to generating pairs of
observation identifierss, dyads can include a user-specified
collection of variables.

You could instead create dyads using Stata's matrix-programming
capabilities. The advantages of dyads are that it doesn't
require learning the matrix syntax for a discrete data-management job
and it isn't limited by Stata's matrix-size boundaries. Thus it runs
quickly on large datasets. It is worth noting that dyads
produces N*N observations before finishing with (N(N-1))/2
observations. This may be a memory issue with large datasets.

Examples

The simplest example is to take a list of IDs and generate all pairs
of IDs. Imagine the following dataset:

N id
------
1 1
2 2
3 3
4 4
5 5

Typing

. dyads id

will produce the following dataset:

N id id_d

1 1 2
2 1 3
3 1 4
4 1 5
5 2 3
6 2 4
7 2 5
8 3 4
9 3 5
10 4 5

...that is, all the pairwise combinations of id.

A more useful example might be calculating the distance between pairs
of objects. Imagine a dataset with firms and their (x,y)
locations:

firm x y

firma 12 13
firmb 4 6
firmc 10 2
firmd 5 17

. dyads firm, dy(x y)

firm x y firm_d x_d y_d

firma 12 13 firmb 4 6
firma 12 13 firmc 10 2
firma 12 13 firmd 5 17
firmb 4 6 firmc 10 2
firmb 4 6 firmd 5 17
firmc 10 2 firmd 5 17

You could now calculate distance for all the dyads using

. generate dist = sqrt((x-x_d)^2+(y-y_d)^2)

A final example shows the utility of choosing idvar
carefully. Imagine a dataset with basketball players, the times they
entered the game (expressed in minutes since the start) and the times
they exited:

id timein timeout

1 5 27
2 15 41
3 8 33
4 2 36
5 39 51
6 33 36

Assume that you want to know the amount of time that each
player-dyad spent on the court together. In order to generate that
particular statistic, you might want to ensure that the player who
came onto the court earlier is always the first member of the
dyad. Creating a unique idvar on which to run dyads can
help with this.

. sort timein id

. generate sortid = _n

. dyads sortid, dy(id timein timeout)

id timein timeout sortid sortid_d id_d timein_d timeout_d

4 2 36 1 2 1 5 27
4 2 36 1 3 3 8 33
4 2 36 1 4 2 15 41
...

Notice that, in order to keep the original observation's
identifier when generating the dyads, in this case the variable
id was included inside DYadvars(). Calculation of overlaps
could now proceed under the assumption that the first member of the
dyad always had an earlier or equal starting time than the second
member.

Author

John-Paul Ferguson

ferguson_john-paul@gsb.stanford.edu