Event networks (tutorial): Difference between revisions

From visone manual
Jump to navigation Jump to search
Line 18: Line 18:
== Importing event networks ==
== Importing event networks ==


visone can import event lists from comma-separted-value (CSV) files. These files must contain a header in the first line (giving the column labels) followed by any number of lines each of which encodes one event. For instance, the first few lines of the example file look like this.
visone can import event lists from comma-separted-value (CSV) files. These files must contain a header in the first line (giving the column labels) followed by any number of lines each of which encodes one event. For instance, some lines in the example file look like this.
   "WEIS.code";"Time";"Source";"Target";"Description";"Goldstein.weight";"Type"
   "WEIS.code";"Time";"Source";"Target";"Description";"Goldstein.weight";"Type"
   11;940930;"USA";"ISR";"SURRENDER";0.6;"cooperation"
   ...
   11;910319;"KUR";"IRQ";"SURRENDER";0.6;"cooperation"
  222;980213;"ISR";"WES";"NONMIL DESTR";-8.7;"conflict"
   223;920717;"SYR";"ISR";"MIL ENGAGEME";-10;"conflict"
   ...
   ...
To open such a file, click on '''open''' in the [[File_menu|'''file''' menu]], select '''files of type:''' ''event list files (.csv, .txt)'', navigate to the file that you want to open, and click on '''ok'''. In the import options dialog (see below) you have to specify the character that separates the different entries in each line - this is the semicolon (''';''') in our example file - and a character enclosing text (if any) - this is the double quotes ('''"''') in our example file.
To open such a file, click on '''open''' in the [[File_menu|'''file''' menu]], select '''files of type:''' ''event list files (.csv, .txt)'', navigate to the file that you want to open, and click on '''ok'''. In the import options dialog (see below) you have to specify the character that separates the different entries in each line - this is the semicolon (''';''') in our example file - and a character enclosing text (if any) - this is the double quotes ('''"''') in our example file.
Line 28: Line 29:


To find out the right settings you can look at the file tab in the import options dialog showing you part of the input file.
To find out the right settings you can look at the file tab in the import options dialog showing you part of the input file.
visone can now read the various entries of the input file - and you have to specify how these should be mapped to the resulting network in the dialog '''EventNetwork specification''' (shown below). Concretely you have to specify how the various components of an event are encoded in the file (''Event format'' tab); how to iterate over the network sequence (''Event iterator'' tab); how the events are mapped to the network's link attributes (''Event network'' tab); and, if desired, which statistics should be computed while constructing the event network (''Eventnet statistics'' tab). The tabs should be filled out in the order as they are numbered in the dialog since choice-possibilities for the latter tabs depend on previous settings. If you make changes in some tab you have to subsequently set (again) the values for the latter tabs.


=== Specifying the event format ===
=== Specifying the event format ===
In the event format tab (see the image below) you first have to specify which columns of the input file hold the information about the five components of an event (these are ''source'', ''target'', ''time'', ''type'', and ''weight''). You can set the values as in the image below.


[[File:Eventnet_dialog_format_KEDS.png]]
[[File:Eventnet_dialog_format_KEDS.png]]
After these five components have been chosen visone needs some information about the interpretation of time. (visone can handle very general date/time formats - but some information is necessary.) The first choice is the selection between '''numeric time''' (if the time fields correspond to integer numbers) or '''calendar time''' (if time fields can somehow, specified below, be turned into a date/time). We have calendar time in our example.
If time is given by calendar, a '''time format pattern''' has to be specified. visone proposes some known pattern - among others the pattern '''yyMMdd''' which is appropriate for the KEDS event times. (This pattern implies that there are two digits for the year, followed by two digits for the month, followed by two digits for the day of the month; for instance, 940930 for September 30, 1994.) You can enter other than the proposed patterns in the textfield if date/time is formatted differently (see the webpage on the java class [http://docs.oracle.com/javase/6/docs/api/java/text/SimpleDateFormat.html SimpleDateFormat] for guidance). visone assists you in finding the right pattern by showing some date/time strings as they appear in the file and - whenever you select a date format pattern - the dialog shows you the current time formatted by the specified pattern.
Finally, you have to specify a '''time unit'''. If time is numeric you have to enter an integer in the textfield. If time is given by calendar you can select a "natural" time unit from ''Millisecond'' to ''Year''. An appropriate time unit makes the iteration over the event sequence (and potentially the decay of link attributes over time) more intuitive. When computing event network statistics, events that happen within the same time unit are treated as independent of each other. The appropriate time unit for KEDS events is '''DAY'''.
When all settings in the event format tab are done, you can create the list of events by clicking on the '''Apply (create events)''' button. A message informs about the number of events and the number of time units from the first to the last event. (The events are sorted in ascending order by time after reading them - thus, it is not necessary that the events are ordered by time in the input file.)


== References ==
== References ==

Revision as of 12:48, 2 August 2012

Note: this tutorial documents a visone functionality that will be in the next release (around September 2012).

The links in an event network encode time stamped interaction among actors, for instance, users sending emails to other users. There is an important difference to networks of relational states - such as friendship networks. To illustrate the difference, when two actors are friends of each other at some instant in time, then - if nothing happens in between - they are still friends in the very near future. In contrast, if someone sends and email to another person at some instant in time, then he/she does not necessarily send an email to the same person in the very next instant in time.

This tutorial is a practically oriented, example based, "how-to" guide illustrating the import, transformation, visualization, and analysis of event networks with visone. More background on event networks can be found in

and in other papers linked in the references.

Please address questions and comments about this tutorial to me (Jürgen Lerner).

Example data: networks of political conflict and cooperation

This tutorial uses for illustration networks of events among political actors that have been collected by the Penn State Event Data Project (formerly Kansas Event Data System). Specifically, we use data encoding events in or around the Persian Gulf region in the time from 1979 to 1999. This data set is described in and linked from the page on Penn State Event Data. To follow the steps outlined in this tutorial you should download the file Gulf_events_preprocessed.zip.

Another specific application area for event networks - using different example data - is treated in the tutorial on Wikipedia edit networks.

Importing event networks

visone can import event lists from comma-separted-value (CSV) files. These files must contain a header in the first line (giving the column labels) followed by any number of lines each of which encodes one event. For instance, some lines in the example file look like this.

 "WEIS.code";"Time";"Source";"Target";"Description";"Goldstein.weight";"Type"
 ...
 222;980213;"ISR";"WES";"NONMIL DESTR";-8.7;"conflict"
 223;920717;"SYR";"ISR";"MIL ENGAGEME";-10;"conflict"
 ...

To open such a file, click on open in the file menu, select files of type: event list files (.csv, .txt), navigate to the file that you want to open, and click on ok. In the import options dialog (see below) you have to specify the character that separates the different entries in each line - this is the semicolon (;) in our example file - and a character enclosing text (if any) - this is the double quotes (") in our example file.

Import options event list.png

To find out the right settings you can look at the file tab in the import options dialog showing you part of the input file.

visone can now read the various entries of the input file - and you have to specify how these should be mapped to the resulting network in the dialog EventNetwork specification (shown below). Concretely you have to specify how the various components of an event are encoded in the file (Event format tab); how to iterate over the network sequence (Event iterator tab); how the events are mapped to the network's link attributes (Event network tab); and, if desired, which statistics should be computed while constructing the event network (Eventnet statistics tab). The tabs should be filled out in the order as they are numbered in the dialog since choice-possibilities for the latter tabs depend on previous settings. If you make changes in some tab you have to subsequently set (again) the values for the latter tabs.

Specifying the event format

In the event format tab (see the image below) you first have to specify which columns of the input file hold the information about the five components of an event (these are source, target, time, type, and weight). You can set the values as in the image below.

Eventnet dialog format KEDS.png

After these five components have been chosen visone needs some information about the interpretation of time. (visone can handle very general date/time formats - but some information is necessary.) The first choice is the selection between numeric time (if the time fields correspond to integer numbers) or calendar time (if time fields can somehow, specified below, be turned into a date/time). We have calendar time in our example.

If time is given by calendar, a time format pattern has to be specified. visone proposes some known pattern - among others the pattern yyMMdd which is appropriate for the KEDS event times. (This pattern implies that there are two digits for the year, followed by two digits for the month, followed by two digits for the day of the month; for instance, 940930 for September 30, 1994.) You can enter other than the proposed patterns in the textfield if date/time is formatted differently (see the webpage on the java class SimpleDateFormat for guidance). visone assists you in finding the right pattern by showing some date/time strings as they appear in the file and - whenever you select a date format pattern - the dialog shows you the current time formatted by the specified pattern.

Finally, you have to specify a time unit. If time is numeric you have to enter an integer in the textfield. If time is given by calendar you can select a "natural" time unit from Millisecond to Year. An appropriate time unit makes the iteration over the event sequence (and potentially the decay of link attributes over time) more intuitive. When computing event network statistics, events that happen within the same time unit are treated as independent of each other. The appropriate time unit for KEDS events is DAY.

When all settings in the event format tab are done, you can create the list of events by clicking on the Apply (create events) button. A message informs about the number of events and the number of time units from the first to the last event. (The events are sorted in ascending order by time after reading them - thus, it is not necessary that the events are ordered by time in the input file.)

References