visone manual - User contributions [en]

User:Lerner

2019-03-26T14:33:39Z

Lerner:

'''Jürgen Lerner'''

Contact: [mailto:juergen.lerner@gmail.com juergen.lerner@gmail.com]

[http://algo.uni-konstanz.de/team/lerner/ http://algo.uni-konstanz.de/team/lerner/]

User:Lerner

2019-03-26T14:33:02Z

Lerner:

'''Jürgen Lerner'''

You can reach me at [mailto:juergen.lerner@gmail.com juergen.lerner@gmail.com].

My homepage [http://algo.uni-konstanz.de/team/lerner/ http://algo.uni-konstanz.de/team/lerner/].

EgoNet2GraphML (software)

2019-03-26T14:32:29Z

Lerner:

[http://sourceforge.net/projects/egonet/ EgoNet] is a software to conduct interviews in which the [[Personal_network|personal networks]] of respondents are collected. '''EgoNet2GraphML''' can (1) convert EgoNet interviews into GraphML files (that can be opened with visone) and (2) cluster, aggregate, and visualize collections of personal networks using the methodology proposed in: Ulrik Brandes, Juergen Lerner, Miranda J. Lubbers, Chris McCarty, and Jose Luis Molina '''"Visual Statistics for Collections of Clustered Graphs"'''. ''Proc. IEEE Pacific Visualization Symp. (PacificVis'08)'', 2008 ([http://www.inf.uni-konstanz.de/algo/publications/bllmm-vsccg-08.pdf ''link to pdf'']).

See the [[Personal_networks_(tutorial)|tutorial on personal networks]] to learn how to use this software. '''To download EgoNet2GraphML go to [http://www.inf.uni-konstanz.de/algo/software/egonet2graphml/ the EgoNet2GraphML website]'''.

EgoNet2GraphML can open one or more interview files that have been filled out according to the same questionnaire (<code>.ego</code>-file). Then it can export these personal networks to [[GraphML]] files either on the individual level or after an attribute-based clustering.
* When exporting networks on the individual level, the resulting network has a node for each alter and it stores the ego attributes as network level attributes and the alter attributes as node attributes. Typically, the respondent has to evaluate the relation between every undirected pair of alters; in this case the resulting network is complete and the alter-alter responses are encoded in link attributes.
* When exporting networks on the class level the user first have to specify how the alters should be partitioned based on alter attributes. Then the class-level networks are exported to GraphML files containing a node for each class and a link for each undirected pair of classes. Summary statistics for the classes (such as number of actors in the class or number of links connecting actors in the same class) are stored as node attributes, statistics for pairs of classes are stored as link attributes. In addition, when exporting networks on the class level EgoNet2GraphML generates one GraphML file (<code>Average_clustered.graphml</code>) that shows the average (tendency and dispersion) over the whole collection of personal networks, as defined in Brandes et al. (2008).

WikiEvent (software)

2019-01-17T15:44:47Z

Lerner:

[[WikiEvent_(software)|'''WikiEvent''']] is a small graphical java software with which the '''''edit network''''' associated with the history of [http://www.wikipedia.org Wikipedia] pages can be computed.

== Download and licensing information ==

See the WikiEvent webpage [http://algo.uni-konstanz.de/software/wikievent/ http://algo.uni-konstanz.de/software/wikievent/].

== Tutorials ==

See the tutorial on [[Wikipedia_edit_networks_(tutorial)|Wikipedia edit networks]].

Wikipedia edit networks (tutorial)

2018-12-18T09:24:39Z

Lerner: /* Statistical modeling of edit event networks */

[[File:Wikipedia_vis_example.png|200px|thumb]]
The '''''edit network''''' associated with the history of [http://www.wikipedia.org Wikipedia] pages is a network whose nodes are the page(s) and all contributing users and whose edges encode time-stamped, typed, and weighted interaction events ('''''edit events''''') between users and pages and between users and users. Specifically, edit events encode the exact time when an edit has been done along with one or several of the following types of edit interaction:
* the amount of new text that a user '''adds''' to a page;
* the amount of text that a user '''deletes''' (along with the other user/s that has/have previously added this text);
* the amount of previously deleted text that a user '''restores''' (along with the users that previously deleted and the ones that originally added the text).

Together these edit events form a highly dynamic network revealing the emergent collaboration structure among contributing users. For instance, it can be derived
* who are the users that contributed most of the text;
* what are the implicit '''roles''' of users (e.g., contributors of new content, vandalism fighters, watchdogs);
* whether there are '''opinion groups''', i.e., groups of users that mutually fight against each others edits.

This [[Tutorials|tutorial]] is a practically oriented "how-to"-guide giving an example based introduction to the computation, analysis, and visualization of Wikipedia edit networks. More background can be found in the papers cited in the [[Wikipedia_edit_networks_(tutorial)#References|references]]. To follow the steps outlined here (or to do a similar study) you should download [[WikiEvent_(software)|'''WikiEvent''']] - a small graphical java software with which Wikipedia edit networks can be computed.

Please address questions and comments about this tutorial to me ([[User:Lerner|Jürgen Lerner]]).

== How to download the edit history? ==

Wikipedia not only provides access to the current version of each page but also to all of its previous versions. To view the page history in your browser you can just click on the '''history''' link on top of each page and browse through the versions. However, for automatic extraction of edit events we need to download the complete history in a more structured format. To do this there are various possibilities that are appropriate in different scenarios (and dependent on your computational resources and internet bandwidth).

To get the history of '''all''' pages you can go to the [http://dumps.wikimedia.org/backup-index.html Wikimedia database dumps], select the wiki of interest (for instance, '''enwiki''' for the English-language Wikipedia), and download all files linked under the headline ''All pages with complete edit history''. The complete database is extremely large (several [http://en.wikipedia.org/wiki/Terabyte terabytes] for the English-language Wikipedia) and probably cannot be managed with an ordinary desktop computer.

Another possibility to get the complete history of a Wikipedia page (or of a small set of pages) is to use the wiki's [http://en.wikipedia.org/wiki/Special:Export Export page]. The preceeding link is for the English-language Wikipedia - for other languages just change the language identifier ''en'' in the URL to, for instance, ''de'' or ''fr'' or ''es'', etc. (Actually, this visone wiki has, as any other MediaWiki, also an export page available at [[Special:Export]]; there you could download the edit history of visone manual pages - which are definitively much shorter than those from Wikipedia.)

[[File:Wikipedia_export_pages.png|400px]]

For instance, to download the history of the page [http://en.wikipedia.org/wiki/Social_network_analysis '''Social network analysis'''] make settings as in the screenshot above and click on the '''Export''' button. However, as it is noted on the page, exporting is limited to 1000 revisions and the example page (Social network analysis) has already more than 2700 revisions. In principle it is possible to download the next 1000 revisions by specifying an appropriate offset (as explained on the [http://www.mediawiki.org/wiki/Manual:Parameters_to_Special:Export manual page for Special:Export]) and then pasting the files together. However, since this is rather tedious the software [[WikiEvent_(software)|WikiEvent]] offers a possibility to do this automatically. (Internally WikiEvent proceeds exactly as described above by retrieving revisions in chunks of 1000 and appending these to a single output file.)

To download a page history with [[WikiEvent_(software)|WikiEvent]] you start the program (download it from [http://www.inf.uni-konstanz.de/algo/software/wikievent/ http://www.inf.uni-konstanz.de/algo/software/wikievent/] and execute by double-clicking) and click on the entry '''download history''' in the '''net''' menu. You have to specify the language of the Wikipedia (for instance, '''en''' for English, '''de''' for German, '''fr''' for French, etc), the title of the page to download and a directory on your computer in which the file should be saved.

[[File:Wikipedia_lang_code.png]] [[File:Wikipedia_page_title.png]] [[File:Wikipedia_download_sna.png]]

The program is actually very silent - for instance, you don't see a progres bar - until the download is complete. The time it takes to download depends on many factors, among them the size of the page history (which might be several [http://en.wikipedia.org/wiki/Gigabyte gigabytes] for some popular pages!) and the bandwidth of your internet connection. At the end you see the number of downloaded revisions in the message area of WikiEvent.

For information: the size of the history file for the page ''Social network analysis'' is about 84 [http://en.wikipedia.org/wiki/Megabyte Megabytes] on May 04, 2015 (obviously growing). The history is saved in a file '''Social_network_analysis.xml''' in the directory that you have chosen. If you are interested, the XML format is described in the page [http://www.mediawiki.org/wiki/Help:Export http://www.mediawiki.org/wiki/Help:Export] - but you never have to read these files since they are automatically processed as described below.

== Computing the edit network ==

To compute the edit events from a Wikipedia history file select the entry '''extract edit events''' in the '''page'''-menu of WikiEvent. You have to specify one or more history file(s) and a directory to save the files with the edit events. (These output files have the same names as the input files - just with the ending '''.xml''' replaced by '''.csv'''.)

[[File:Wikipedia_extract_edit_events.png]]

If we compute the edit events from the history of the page ''Social network analysis'', then the first few lines of the edit event file look like this:
PageTitle;RevisionID;Time(calendar);Time(milliseconds);InteractionType;WordCount;ActiveUser;Target
"Social network analysis";1711088;2003-09-23T21:08:52Z;1064344132000;added;196;"142.177.104.40";"Social network analysis"
"Social network analysis";2002109;2003-11-11T06:13:44Z;1068527624000;added;10;"63.228.105.175";"Social network analysis"
"Social network analysis";2002109;2003-11-11T06:13:44Z;1068527624000;deleted;192;"63.228.105.175";"142.177.104.40"
"Social network analysis";2036847;2003-12-19T22:42:43Z;1071870163000;added;54;"Davodd";"Social network analysis"
"Social network analysis";2036847;2003-12-19T22:42:43Z;1071870163000;deleted;7;"Davodd";"63.228.105.175"
"Social network analysis";2210638;2003-12-24T13:29:11Z;1072268951000;added;1;"210.49.82.219";"Social network analysis"
"Social network analysis";2210638;2003-12-24T13:29:11Z;1072268951000;deleted;1;"210.49.82.219";"Davodd"
...

The file encodes a table with entries separated by semicolons (''';'''). The columns from left to right encode
* The '''title''' of the page (since a history file can contain the history of several pages the title-field can actually vary.).
* The '''revision id''' which is a number uniquely identifying a revision in Wikipedia (not just in one page). A single edit can produce more than just one line in the output file (we say more on this below); the revision id makes it possible to recognize which lines belong to the same edit.
* The '''time''' of the edit given as a date/time-string. For instance the first edit happend on September 23, 2003 at 21:08:52 (where time is measured in the [http://en.wikipedia.org/wiki/Coordinated_Universal_Time UTC] time zone).
* Once again the edit '''time''' given as a number encoding milliseconds since January 1, 1970 at 00:00:00.000 Greenwich Mean Time. (This value is actually obtained by the method <code>getTimeInMillis</code> of the java class <code>Calendar</code>.) The time in milliseconds is helpful if you just need the time ''difference'' between revisions and not the actual time or date; it is obvisously easier to compute the time difference from numbers than from data/time strings.
* The edit '''type''' which can be ''added'', ''deleted'', ''restored'', or ''undeleted''; we say more on this below.
* The '''word count''', i.e., the number of words that are added, deleted, restored, or undeleted with respect to the given target.
* The '''active user''' is the user that has done the edit; it is the source node of the edit event. The user is identified by a user name if logged in; otherwise (if it is an anonymous edit) the user is identified by an IP address.
* The '''target''' node of the edit event is either the page or a user. If the event type is ''added'', then the target is the page (the active user adds text to the page). If the event type is ''deleted'', ''restored'', or ''undeleted'', then the target is the user who has previously written or deleted the text (the active user deletes/restores/undeletes text that has been added/deleted by the target user).

We say more on the different event types in the following.

=== The structure of edit network data ===

Consider an example of three revisions on one page where
* (in Revision 1) user ''Alice'' adds some new text to the page;
* subsequently (in Revision 2), user ''Bob'' deletes this text;
* then (in Revision 3), user ''Charlie'' [http://en.wikipedia.org/wiki/Help:Reverting reverts] Bob's edit - setting back the page text to the one submitted in Revision 1.

These three edits together give rise to '''four''' dyadic edit events (shown in the image below):

[[File:Edit_network_example.png]]

* An edit event of type ''added'' from user Alice to the edited page.
* An edit event of type ''deleted'' from user Bob directed to user Alice.
* An edit event of type ''restored'' from user Charlie directed to user Alice (Charlie restored text that has been previously written by Alice).
* An edit event of type ''undeleted'' from user Charlie directed to user Bob (Charlie restored text that has been previously deleted by Bob). '''Note''' that after the revert the restored text is (again) authored by Alice and not by Charlie.

All edit events are weighted by the number of words that have been added, deleted, restored, or undeleted and all edit events have a time stamp marking the time when the edit has been submitted.

A single edit on a Wikipedia page generates one '''hyperedge''' linking the active user to (potentially) several other users and the edited page. Such a hyperedge has been turned into several lines of the CSV file, each encoding one '''(dyadic) edge''', linking the source (active user) to one target in one interaction type. Note that the hyperedges can be reconstructed from the data using the revision ids (see above).

For determining the amount of text modified in an edit we make some choices. For instance, if complete sentences are just moved from one part of the page to another, we do not count this as any change. More detailed information about the text-processing conventions can be found in
* Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij: [http://www.inf.uni-konstanz.de/algo/publications/bklv-nacsw-09.pdf '''Network Analysis of Collaboration Structure in Wikipedia''']. Proc. 18th Intl. World Wide Web Conference (WWW 2009).
and more technically in
* Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij: [http://www.inf.uni-konstanz.de/algo/publications/bklv-cwen-09.pdf '''Computing Wikipedia Edit Networks''']. Technical Report, 2009.

For convenience, we make the computed edit events available for download in the file [[Media:Social_network_analysis.zip|Social_network_analysis.zip]].

== Importing edit event networks into visone ==

The CSV file with the computed edit events can be imported in visone when opening it as an '''event list file'''. Visone's capabilities in importing and analyzing event networks are documented in the [[Event_networks_(tutorial)|tutorial on event networks]]; here we treat the special case of edit event networks.

To open an event list file (such as the newly created ''Social_network_analysis.csv'') click on '''open''' in visone's '''file''' menu, select '''files of type''': ''event list files'', navigate to the CSV file, and click on '''ok'''. In the import options, choose
the semicolon (''';''') as a cell delimiter and double quotes ('''"''') as textframe.

[[File:File_open_eventlist.png]] [[File:Import_options_event_list.png]]

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.

=== 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 (source, target, time, type, and weight). You can set the values as in the image below.

[[File:Eventnet_dialog_format.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 '''yyyy-MM-dd'T'HH:mm:ss'Z'''' which is appropriate for the Wikipedia edit times. 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 a (integer) number 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 finest time unit that makes sense for the Wikipedia edit events is ''Second'' (since the edit times are not given with higher precision). But you could also choose ''Day'' as a time unit if you think that this is fine-grained enough.

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.

=== Event iterator ===

In the event iterator tab (see below) you have to specify the start and end time of the time interval to be processed and the delay between network snapshots.

[[File:Eventnet_dialog_iterator.png]]

When the events have been created after filling out the event format tab (see the preceeding section) visone suggests as start time the time of the first event and as end time the time of the last event. If you don't want to process the whole event sequence you can increase the start time and/or decrease the end time. After clicking on the upper '''Apply / get info''' button, visone informs you about the number of events and time units in the specified subsequence. You might just take all events by not changing the interval borders; this includes all events from September 23, 2003 to July 11, 2012 - as can be seen in the dialog.

Then you have to choose the time points when a network snapshot is to be created by specifying the delay between snapshots. You can see in the dialog that the event sequence spans more than 277 million time units (i.e., seconds with the current settings). The number of snapshots must be small (some 10 or 20 snapshots would still be ok), since they are all opened in a new tab in visone. When specifying: ''create snapshots after every'' '''100,000,000''' ''time unit(s)'', then visone creates three snapshots. (This is an example where a coarser time unit might be more intuitive; 100 million seconds are actually a bit more than 1157 days.) visone always creates one snapshot at the end of the event sequence - even if the waiting time is less than the specified number.

'''Note''': Do not click on ''Process event network'' before you specify the event network in the next step.

=== Event network ===

The tab to specify the event network is the most important one - here you define which '''link attributes''' of the event network summarize the past events, how events of various types add to these attributes, and how they change over time. The dialog might seem a bit complicated at first glance but the mechanism to specify the evolution of the event network is very powerful and general.

[[File:Eventnet_dialog_network.png]]

The first thing to do is to decide on the link attributes. Here you are free to choose any attribute name (that makes it easy to remember the intuition of the attribute). Furthermore, a halftime - defining how fast attributes decay over time - has to be specified. The halftime has the following effect: when a particular link attribute on a particular dyad (pair or actors) has a value of <math>x</math> at time <math>t</math>, then (if no event on the same dyad happens in between) the value is <math>x/2</math> at time
<math>t+halftime</math>. Intuitively, link attributes with a positive halftime capture ''recent interaction''. A halftime equal to zero or negative indicates that the respective attribute does not decay over time; these attributes capture ''past interaction'' irrespective of the elapsed time.

In our concrete example we choose the following link attributes.
* The attributes ''added'', ''deleted'', ''restored'', and ''undeleted'' just add up the weight (i.e., the number of words modified) of past events of the respective type (with no decay). For instance, the value of the attribute ''added'' on a link connecting user ''U'' with page ''P'' at time ''t'' is equal to the number of words that ''U'' contributed to ''P'' at or before time ''t''. Similarly, the value of ''deleted'' on a dyad ''(U,V)'' is equal to the number of words that user ''U'' deleted of text previously written by user ''V''.
* The attribute ''recently added'' counts words added by users to a page but has a decay over time. If we choose as halftime the same value as for the interval between snapshots, then 100 words added just at the end of the first interval (say) contribute with a value of 50 at the end in the second snapshot. (It is also possible to introduce attributes like ''recently deleted'', etc; and it would also be possible to have varying halftimes to capture very recent interaction, recent interaction, more distant interaction, etc., in the same event network.)
* The attribute ''log added'' adds up the logarithm of the number of newly contributed words. A logarithmic transformation is appropriate in very skewed event weights (when, say, twice the number of words should not count twice as much but only slighly more). Other transformations of event weights are also possible.
* The attribute ''interacted'' adds up the number of modified (added, deleted, restored, or undeleted) words irrespective of the event type.
* The attribute ''agreed-disagreed'' is meant as a proxy for whether a user agrees or rather disagrees with the edits of another user. Specifically, deletions and undeletions are interpreted as disagreements since a user makes another user's edits undone; restoring text is interpreted as an agreement. (This indicator is proposed and used in the published papers cited in the [[Wikipedia_edit_networks_(tutorial)#References|references]] but will also become clearer in this tutorial.)

At the beginning the dialog has two rows for two different link attributes; more can be added by clicking the '''more attributes ...''' button. When all attributes are specified they have to be added to the event network (for instance by clicking the '''Add / update all''' button). Then you can create the weight function table.

In the '''weight function table''' there is one column for every event type and one row for every link attribute. A particular entry in this table specifies how events of the column type contribute to the link attribute in the respective row. The entries are combo boxes allowing you to select from the available weight functions. For instance, selecting the weight function ''Identity'' for the attribute ''deleted'' and the event type ''deleted'' implies that the weight (i.e., the number of words) of events of type ''deleted'' are added (without transforming them) to the link attribute ''deleted''. The weight function ''Logarithm'' for the attribute ''log added'' and the event type ''added'' implies that the logarithm of the event weight is added. Note that in the row corresponding to the attribute ''interacted'' we add up the weights of all event types; for the attribute ''agreed-disagreed'' we add weights of events of type ''restored'' and subtract (chose the weight function ''MinusIdentity'') weights of events of type ''deleted'' or ''undeleted''.

When these settings are complete you can process the event network. (You need to fill out the event statistics tab only when you want to do a statistical analysis of the event network - this is documented in a latter section: [[Wikipedia_edit_networks_(tutorial)#Statistical_modeling_of_edit_event_networks]].) After clicking on the button '''Process event network!''' it takes a few minutes or so (depending on the size and number of the snapshots). With our settings we create three network tabs holding the three snapshots. The dialog does not close after processing; you might change some of the settings and create different snapshots - or close the dialog explicitly.

For convenience, we make the GraphML file of the first snapshot available for download in [[Media:Social_network_analysis_(raw).graphml.zip|Social_network_analysis_(raw).graphml.zip]].

== Analysis and visualization of edit networks ==

The created network snapshots have nodes representing the page (or pages, if there are several in the history file) and all users that contributed at or before the time of the snapshot. The link attributes encode (in our case) the number of words added, deleted, restored, undeleted, or modifications thereof (as explained before) - again taken at the snapshot time. Analysis and visualization works similar as for any other network with many numerical link attributes. In particular, many of the derived user attributes that have been proposed in Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij (2009): [http://www.inf.uni-konstanz.de/algo/publications/bklv-nacsw-09.pdf '''Network Analysis of Collaboration Structure in Wikipedia'''] can be computed and visualized by visone starting from the available link attributes. Examplarily we illustrate some possibilities with the first snapshot, the smallest one, that has 412 nodes and 1341 links.

The first observation is that the layout after loading is very cluttered. Actually, all user-nodes that added at least one word to the page (''Social network analysis'') are at a distance of two or smaller - leading to the very dense circle around one very central node. An improvement can be achieved by deleting the node representing the page - after some information has been collected in the (user-)nodes. Therefore, go to the [[analysis tab]] select the node outdegree with ''link strength'' set to the link attribute ''added'' and save it in a node attribute ''added'' (see the screen shot below). Do the same again with the attribute ''log added''.

[[File:Eventnet_outdegree_added.png]]

To delete the single node representing the page we have to select it first. This can be done by selecting the single node with the label equal to ''Social network analysis'' in the [[Attribute manager]]; or (more generally since it is applicable to networks with several page-nodes) we compute the unweighted outdegree and select all nodes with outdegree equal to zero - these are exactly the nodes representing pages.

After having deleted the node representing the page, reducing to the largest connected component, and computing and visualizing some additional indicators, we can come up with an image as the following.

[[File:Wikipedia_vis_example.png|800px]]

Here the color of the nodes represent the amount of text added (blue for those who added a lot). The size of the nodes as well as the centrality of their position and the node label size represent the activity of the nodes - computed from the ''interacted'' attribute (note that this includes adding, deleting, restoring, or undeleting text). The width of the links is again a function of the ''interacted'' attribute. Finally the link color is tending to orange if the ''agreed-disagreed'' attribute admits strongly negative values (resulting from deletion or undeletion and being interpreted as disagreement) and the link color is tending to blue when the ''agreed-disagreed'' attribute becomes larger (being interpreted as agreement).

Many other ways to graphically encode these and other indicators are possible.

For convenience, we make the GraphML file of the first snapshot with an improved layout available for download in [[Media:Social_network_analysis.graphml.zip|Social_network_analysis.graphml.zip]].

== Statistical modeling of edit event networks ==

While importing event networks it is possible to compute and save network statistics associated with dyadic events that can be used to build and estimate a statistical model for the '''conditional event type'''. Such models have been proposed in Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders (2009): [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data'''] and applied to Wikipedia edit networks in Jürgen Lerner, Ulrik Brandes, Patrick Kenis, and Denise van Raaij (2012): [http://www.transcript-verlag.de/ts1927/ts1927.php '''Modeling Open, Web-based Collaboration Networks: The Case of Wikipedia''']. These models can be used to test whether the network of past edit events explains the likelihood of future deletions or undeletions, for instance
* Do users have a tendency to delete the edits from users who deleted them previously?
* Do the deletion/undeletion events give rise to patterns of structural balance?
(Note that the functionality for statistical analysis of event networks has been superseded by the [https://github.com/juergenlerner/eventnet '''event network analyzer (eventnet)'''], which is a separate software that is not restricted to the analysis of the conditional event type and offers much more general settings. We nevertheless keep the description below how to perform a statistical analysis of event networks with visone.)

The event network statistics can be computed during importing the data, are saved in a file, and can then be analyzed with any statistical software, such as [http://www.r-project.org/ '''R'''].

To illustrate how such statistics can be computed and modeled we modify the link attributes in the event network tab (see below). (The settings in the event format and event iterator tabs stay the same.)

[[File:Eventnet_dialog_attr4stat.png]]

Specifically, we define only two attributes, one that measures past agreement (a fuction or events of type ''restored'') and one the measures past disagreement (a function of events of type ''deleted'' or ''undeleted''). The halftime of both attributes is set to 30 days (which is 2592000 seconds) and the event weights (word counts) are logarithmically scaled.

=== Specifying event statistics in the eventnet dialog ===

The statistics to be computed are defined in the eventnet statistics tab of the import dialog (see below). You first have to specify whether a statistic table should be created at all; if yes an output file has to be chosen and one or more statistics have to be defined.

[[File:Eventnet_dialog_statistics.png]]

The statistics are used to model events in the following way: whenever an event happens that is initiated by a '''source''' node and directed to a '''target''' node, then the dyad ''(source, target)'' is embedded in the network of past events, i.e., all events that happened before the current event. The event network statistics describe relevant aspects of this network of past events with respect to the specific dyad. visone offers three different types of statistics - dyad statistics, degree statistics, and triangle statistics - that can be varied with respect to edge direction and/or link attributes. After defining the statistics they have to be added to the event network by clicking on the '''Add / update''' button.

==== Dyad statistics ====

Dyad statistics encode aspects of the past events from ''source'' to ''target'' or in the other direction. That is the dyad statistics encode how ''source'' interacted with ''target'' in the past and how ''target'' interacted with ''source''. In our exmple we define four different dyad statistics that are obtained by switching the direction (''inertia'' if '''OUT'''-going events - from ''source'' to ''target'' - are considered and ''reciprocity'' if '''IN'''-coming events - from ''target'' to ''source'' - are considered) and the link attribute (''positive'' for past agreements and ''negative'' for past disagreements).

Intuitively, if users tend to delete text of those that deleted them, then we expect that the ''negative reciprocity'' statistic is positively related with the likelihood that the edit event is of type ''deleted''.

==== Degree statistics ====

Degree statistics summarize the past events around the dyad ''(source, target)'' by the weighted (out-/in-) degree of ''source'' or ''target''. The links can be weighted by any attribute. For instance, the ''neg_outdeg_source'' statistic adds up the values of the ''disagreement'' attribute on all links starting at the ''source'' node (not only those that are directed to ''target'').

Intuitively, if users that deleted a lot in the past tend to delete in the future, then we expect a positive relation between the ''neg_outdeg_source'' statistic and the likelihood that the edit event is of type ''deleted''. This could point to the presence of users that play specific roles, for instance, "vandalism fighters" that undo malicious edits.

==== Triangle statistics ====

Triangle statistics summarize the network of past events around the dyad ''(source, target)'' by weighted indirect relations from ''source'' over any third node to ''target'' or the other way round. You can select the attributes for the links attached to ''source'' and to ''target'' and the direction which can be '''OUT''' (only out-going ties with respect to the ''source''/''target''), '''IN''' (only in-coming ties), or '''SYM''' (adding up the attributes of out-going and in-coming ties).

For instance, the statistic ''enemy_of_friend'' iterates over all users ''U'' in the network, multiplies the value of the ''agreement'' attribute on links connecting ''source'' and ''U'' (in both directions) with the value of the ''disagreement'' attribute on links connecting ''target'' and ''U'' (in both directions), and adds up these products for all ''U''. Intuitively, the value of the ''enemy_of_friend'' statistic on the dyad ''(source, target)'' is high if there are many other users ''U'' that are in agreement with ''source'' and in disagreement with ''target''; structural balance theory predicts that ''source'' is then more likely to disagree with ''target''.

==== Starting the computation ====

Once the output file and the statistics are specified, click on the '''Process event network!''' button. Snapshots are created as defined in the event iterator tab and statistics are computed as defined in the eventnet statistics tab.

'''Note''' that statistics associated with an event that happens at time ''t'' are only a function of events that happend earlier (strictly before ''t'') - and do not depend on events that happen in the same time unit.

The computed eventnet statistics file (''Social_network_analysis_stats.csv'' in our example) is a table in CSV format in which each row corresponds to one event of the input file. The components of the event (source, target, time, type, and weight) are first repeated in each row - followed by the values of all statistics.

=== Modeling the conditional event type ===
The statistics file can now be analyzed with any statistical software - we describe the following for the [http://www.r-project.org R environment for statistical computing] (also see the visone tutorial on the [[R_console_(tutorial)|R console]]).

First set the R working directory to the directory where the statistics file is located, for instance
setwd("c:/juergen/projects/wiki/data/")
To read the file into a table and see some summary statistics type
eventnet.stats <- read.csv("Social_network_analysis_stats.csv", sep=";")
summary(eventnet.stats)
For modeling the likelihood whether an edit is an ''undo'' edit we create a new binary variable '''is.undo''' that is equal to ''1'' if and only if the edit type is ''deleted'' or ''undeleted''.
eventnet.stats$is.undo <- 0
eventnet.stats$is.undo[eventnet.stats$TYPE == "deleted"] <- 1
eventnet.stats$is.undo[eventnet.stats$TYPE == "undeleted"] <- 1
summary(eventnet.stats)
We remove those events that are of type ''added'' (since these are interactions between users and the page).
eventnet.stats <- eventnet.stats[eventnet.stats$TYPE != "added",]
Further we model only those events that are not self-loops.
eventnet.stats <- eventnet.stats[as.character(eventnet.stats$SOURCE) != as.character(eventnet.stats$TARGET),]
A first very simple model is a logit model for the probability that an edit from ''source'' to ''target'' is an "undo" edit - explained by the past deletions in the other direction (that is from ''target'' directed to the ''source'' node).
model.1 <- glm(is.undo ~ 1 + negative_reciprocity, family = binomial(link=logit), data = eventnet.stats)
summary(model.1)
A summary of the estimated model yields (among others) the following output:
glm(formula = is.undo ~ 1 + negative_reciprocity, family = binomial(link = logit), data = eventnet.stats)
Coefficients:
Estimate Std. Error z value Pr(>|z|)
(Intercept) 0.49213 0.02175 22.630 < 2e-16 ***
negative_reciprocity 0.61765 0.20475 3.017 0.00256 **
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
The interpretation is that there seems to be a habit of "retaliate" deletions: if ''target'' has undone edits of ''source'' then there is an increased probability (postitive coefficient for the ''negative_reciprocity'' statistic) that ''source'' makes edits of ''target'' undone.

A more complex model tests for structural balance effects
model.2 <- glm(is.undo ~ 1 + friend_of_friend + enemy_of_friend +
friend_of_enemy + enemy_of_enemy,
family = binomial(link=logit), data = eventnet.stats)
leading to the following estimates.
Coefficients:
Estimate Std. Error z value Pr(>|z|)
(Intercept) 0.46288 0.02270 20.393 < 2e-16 ***
friend_of_friend 0.05798 0.08871 0.654 0.51340
enemy_of_friend 0.20675 0.07022 2.945 0.00323 **
friend_of_enemy 0.92448 0.10156 9.102 < 2e-16 ***
enemy_of_enemy -0.18435 0.02766 -6.666 2.63e-11 ***
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
The interpretation of the estimated coefficient is as follows (also see the four illustrative images below).

[[File:Friend_of_friend.png|250px]] [[File:Enemy_of_friend.png|250px]] [[File:Friend_of_enemy.png|250px]] [[File:Enemy_of_enemy.png|250px]]

The coefficient associated with the ''enemy_of_friend'' statistic is significantly positive. This implies that there is an increase probability for ''source'' undoing an edit of ''target'' if ''target'' has past disagreements with another user with which ''source'' has past agreements (second image in the row above). A similar effect has been found if ''target'' has past agreements with another user with past disagreements with ''source'' (positive parameter associated with the ''friend_of_enemy'' statistic and third image in the row above). The parameter associated with ''enemy_of_enemy'' is significantly negative; this implied that if both, ''source'' and ''target'' have past disagreements with a common other node (forth image), then they have a decreased probability of undoing each others edits. While these three effects are in line with the predictions of [[structural balance theory]], there is no significant parameter associated with the ''friend_of_friend'' statistic (first image in the row above).

See more on structural balance theory in the context of Wikipedia edit networks in Jürgen Lerner, Ulrik Brandes, Patrick Kenis, and Denise van Raaij: [http://www.transcript-verlag.de/ts1927/ts1927.php '''Modeling Open, Web-based Collaboration Networks: The Case of Wikipedia'''].

== The network of ''simple'' edit events ==

The [[WikiEvent_(software)|'''WikiEvent''' software]] offers the possibility to compute ''simple'' edit events from a (potentially huge) set of Wikipedia pages. A '''simple edit event''' is a directed, time-stamped event from a user ''U'' to a page ''P'' encoding that ''U'' made some edit on page ''P'' at the given time point. Simple edit events do not encode the type of an edit, nor the amount of text changed, nor the other users whose text has been changed (if any). A single edit on a Wikipedia page, thus, results in exactly one simple edit event - while several (''not simple'') edit events might result from one edit. To determine the edit events, WikiEvent does not even have to look at the page text - therefore the current text of any revision does not even have to be downloaded and the data collection and processing is much faster. Simple edit events are most interesting if they are computed from more than just one page (the simple edit events from one page just form a star with the page in the center), for instance on all pages that are relevant for a certain topic.

Since the page text is not necessary for computing simple edit events, it is possible to do this from history files that just contain meta-information about the page, author, and time stamp. Such '''stub''' files are provided in the [http://dumps.wikimedia.org/backup-index.html Wikimedia backup dumps]. For instance, to download meta-data about the complete English-language Wikipedia, follow the '''enwiki'''-link on that page, search for '''enwiki-<day_of_backup>-stub-meta-history.xml.gz''', and download this file. On July 2, 2012 the compressed file had a size of 25 gigabyte and after unpacking it a size of more than 130 gigabyte. Such large files can be processed by WikiEvent because processing can be done in a single pass over the file. (Reading such a file from the hard disc can take a few hours but certainly less than a day with current standard desktop computers.) Note that simple edit events ''can'' also be computed from complete history files that do contain the page text.

To extract simple edit events click on '''extract simple edit events''' in the '''page''' menu of WikiEvent. You have to specify a file containing the titles of pages for which edit events should be extracted (we say more on this below), a history file (which can be a stub file without page text), and an output directory. WikiEvent then creates three files in the output directory, one containing the simple edit events, one with a mapping from numerical ''user ids'' to user names, and one with a mapping from numerical ''page ids'' to page titles.

[[File:Wikipedia_extract_simple_edit_events.png]]

The input file with the page titles that has to be specified must contain one title per line - and nothing else. For instance, we created a file containing all page titles that include the terms ''social'' and ''network'' (for reproducability, this file is available at [[Media:SocialNetworkPageTitles.zip]]). Page titles are case-sensitive, for instance, ''Social network analysis'' points to a different page than ''Social Network Analysis''. The first few lines of this file look like this.
Social network
Social networking
Socialist Solidarity Network
Internet social network
Social Networking
Social networks
Internet social networks
Social Science Research Network
Socialist Organizing Network
Social Network Analysis
Socialist Unity Network
...
and the file contains 149 titles.

The resulting three files are available at [[Media:Social_network_simple_edit_events.zip]]. The event file <code>Social_network_SimpleEditEvents.csv</code> contains more than 23,000 events. It can be imported into visone in a similar way as described [[Wikipedia_edit_networks_(tutorial)#Importing_edit_event_networks_into_visone|above]] (just that there are no event types and weights). A snapshot of this network in the year 2006 looks like this.

[[File:Social_Network_SimpleEditEvents_(2006).png|400px]]

== The discussion network ==

In principle, the extraction of edit events could be done for pages of all types - including [http://en.wikipedia.org/wiki/Wikipedia:Talk_page_guidelines discussion pages]. However, this would not capture the fact that the editing on discussion pages follows a different logic than the editing on content pages. On discussion pages it is rather unusual that edits are made undone; on the other hand users often '''reply''' to posts of other users. To better represent the communication structure of talk pages, WikiEvent offers the possibility to '''extract talk events'''.

[[File:Wikipedia_extract_talk_events.png]]

The discussion around a page is structured by '''discussion threads'''. A new thread is marked by a section headline - typically describing the subject to discuss or a question that the users wants to be answered. Other users can reply by writting their message under the same headline. After having downloaded the history of the page [http://en.wikipedia.org/wiki/Talk:Social_network_analysis Talk:Social network analysis] (for instance) and having extracted the '''talk events''' with WikiEvent, the first few lines of the resulting event file look like the following.

ThreadHeadline;Time(calendar);Time(milliseconds);ActiveUser;DiscussionType;CharacterCount;IndexInThread;Target;ThreadInitiator;PreceedingAuthors...
"== Dunbar's 150 rule ==";"2004-07-29T13:22:39Z";1091100159000;"200.225.194.49";initialized_thread;499;0;"== Dunbar's 150 rule ==";"200.225.194.49";
"==Expansion==";"2004-10-30T06:09:59Z";1099109399000;"Goodoldpolonius";initialized_thread;321;0;"==Expansion==";"Goodoldpolonius";
"== Dunbar's 150 rule ==";"2005-01-05T18:09:43Z";1104944983000;"AndrewGray";replied_to;274;1;"200.225.194.49";"200.225.194.49";"200.225.194.49"
"== small world effect redirect ==";"2005-03-23T21:29:57Z";1111609797000;"Boud";initialized_thread;0;0;"== small world effect redirect ==";"Boud";
"==Image==";"2005-03-27T05:01:50Z";1111892510000;"Goodoldpolonius2";initialized_thread;663;0;"==Image==";"Goodoldpolonius2";
"== External links ==";"2005-04-03T01:32:35Z";1112484755000;"CesarB";initialized_thread;393;0;"== External links ==";"CesarB";
"== External links ==";"2005-04-03T02:07:18Z";1112486838000;"Goodoldpolonius2";replied_to;458;1;"CesarB";"CesarB";"CesarB"
"== External links ==";"2005-05-02T06:07:09Z";1115006829000;"AlanAu";replied_to;402;2;"Goodoldpolonius2";"CesarB";"CesarB","Goodoldpolonius2"
"== External links ==";"2005-05-06T22:39:28Z";1115411968000;"AlanAu";replied_to;135;3;"AlanAu";"CesarB";"CesarB","Goodoldpolonius2","AlanAu"
"== External links ==";"2005-05-06T22:40:30Z";1115412030000;"AlanAu";replied_to;5;4;"AlanAu";"CesarB";"CesarB","Goodoldpolonius2","AlanAu","AlanAu"
"== External links ==";"2005-05-06T23:12:26Z";1115413946000;"Goodoldpolonius2";replied_to;232;5;"AlanAu";"CesarB";"CesarB","Goodoldpolonius2","AlanAu","AlanAu","AlanAu"
"== External links ==";"2005-05-13T18:05:40Z";1116000340000;"82.149.68.78";replied_to;181;6;"Goodoldpolonius2";"CesarB";"CesarB","Goodoldpolonius2","AlanAu","AlanAu","AlanAu","Goodoldpolonius2"
"== External links ==";"2005-05-22T18:22:01Z";1116778921000;"AlanAu";replied_to;365;7;"82.149.68.78";"CesarB";"CesarB","Goodoldpolonius2","AlanAu","AlanAu","AlanAu","Goodoldpolonius2","82.149.68.78"
"== suggested additions ==";"2005-05-26T03:01:44Z";1117069304000;"AdamRetchless";initialized_thread;913;0;"== suggested additions ==";"AdamRetchless";
...

The file is a table encoded in a CSV file whose entries are separated by semicolons (''';'''). The columns encode (from left to right).
* The thread '''headline''', i.e., the subject of the discussion topic.
* The '''time''' given as a date/time string.
* Once again the '''time''' given as a number (milliseconds since January 1, 1970; see above).
* The '''active user''' which is the one who made the post.
* The discussion '''type''' of the edit which can be ''initialized_thread'' or ''replied_to''.
* The '''character count''' indicating number of characters posted in this edit; this might be taken as a (very coarse) indicator for the amount of work invested in the post.
* The '''index''' of this post in its thread; this is a number counting the replies: 0 for the thread initialization, 1 for the first reply, 2 for the second reply, and so on.
* The '''target''' of the post. This is the thread headline if the type of the post is ''initialized_thread'' and it is the user who made the last preceeding post to the same thread.
* The '''initiator''' of the thread.
* Finally a list of all '''preceeding authors''' separated by commas (''','''); first the user who initialized the thread, then the user who made the first reply, etc.

To import such a talk-event network into visone, chose '''files of type'''=''event list files'' after clicking on '''open''' in the '''file''' menu. The settings for the cell delimiter and textframe are the same (semicolon and double-quotes). Then, as for the edit events you have to specify event format, iterator, network, and (potentially) statistics. For a possible choice on the event format see the screenshot below.

[[File:Eventnet_dialog_format_talknet.png]]

In the event iterator tab we chose to create a snapshot after every 200 days (leading to 14 snapshots). In the event network tab we create two attribute functions counting the number of ''initiate'' events or ''reply'' events and give them a halftime equal to the time span between snapshots.

[[File:Eventnet_dialog_network_talknet.png]]

After creating the 14 snapshots, encoding involvement in the discussion by node size and number of thread initializations by color, and visualizing the network collection with a [[Collections_(tutorial)#Dynamic_visualization_and_animation_of_a_network_collection|dynamic layout]] we can come up with the following still images (which are more interesting to view in an [[Collections_(tutorial)#Dynamic_visualization_and_animation_of_a_network_collection|animation]]).

[[File:Talk.Social_network_analysis.png|200px]]
[[File:Talk.Social_network_analysis(13028).png|200px]]
[[File:Talk.Social_network_analysis(13228).png|200px]]
[[File:Talk.Social_network_analysis(13428).png|200px]]
[[File:Talk.Social_network_analysis(13628).png|200px]]
[[File:Talk.Social_network_analysis(13828).png|200px]]
[[File:Talk.Social_network_analysis(14028).png|200px]]
[[File:Talk.Social_network_analysis(14228).png|200px]]
[[File:Talk.Social_network_analysis(14428).png|200px]]
[[File:Talk.Social_network_analysis(14628).png|200px]]
[[File:Talk.Social_network_analysis(14828).png|200px]]
[[File:Talk.Social_network_analysis(15028).png|200px]]
[[File:Talk.Social_network_analysis(15228).png|200px]]

== References ==

Published papers that propose and/or make use of Wikipedia edit networks include the following.
* Jürgen Lerner, Ulrik Brandes, Patrick Kenis, and Denise van Raaij: [http://www.transcript-verlag.de/ts1927/ts1927.php '''Modeling Open, Web-based Collaboration Networks: The Case of Wikipedia''']. In Markus Gamper, Linda Reschke, Michael Schönhuth (Eds.): Knoten und Kanten 2.0, pp 141-162. transcript-Verlag, 2012.
* Jürgen Lerner, Patrick Kenis, Denise van Raaij and Ulrik Brandes: [http://www.sciencedirect.com/science/article/pii/S0263237311000053 '''Will they stay or will they go? How network properties of WebICs predict dropout rates of valuable Wikipedians''']. European Management Journal, 29(5):404-413, 2011.
* Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij: [http://www.inf.uni-konstanz.de/algo/publications/bklv-nacsw-09.pdf '''Network Analysis of Collaboration Structure in Wikipedia''']. Proc. 18th Intl. World Wide Web Conference (WWW 2009).

More technical details about the computation of Wikipedia edit networks can be found in
* Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij: [http://www.inf.uni-konstanz.de/algo/publications/bklv-cwen-09.pdf '''Computing Wikipedia Edit Networks''']. Technical Report, 2009.

The techniques for modeling conditional network event types are proposed in
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.

Event networks (tutorial)

2018-12-18T09:23:04Z

Lerner: /* Statistical modeling of the conditional event type or weight */

[[File:Event_network_gulf_example.png|300px|thumb]]
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. Stated otherwise, relations like ''friendship'' have inertia (something has to happen to change them), while relational events mark time points of interaction.

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
* Carter T. Butts: [http://onlinelibrary.wiley.com/doi/10.1111/j.1467-9531.2008.00203.x/full '''A Relational event framework for social action''']. ''Sociological Methodology'' 38(1):155-200, 2008.
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.
and in other papers linked in the [[Event_networks_(tutorial)#References|references]].

The functionality for statistical analysis of event networks has been superseded by the [https://github.com/juergenlerner/eventnet '''event network analyzer (eventnet)''']. However, visone can still be used for visual analysis of event networks.

Please address questions and comments about this tutorial to me ([[User:Lerner|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 [http://eventdata.psu.edu/ 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|'''Penn State Event Data''']]. To follow the steps outlined in this tutorial you should download the file [[Media:Gulf_events_preprocessed.zip|Gulf_events_preprocessed.zip]].

Another specific application area for event networks - using different example data - is treated in the [[Wikipedia_edit_networks_(tutorial)|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|'''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.

[[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.

=== 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''). In our example, you can set the values as in the image below. The meaning of the five components is explained in the following.
*'''SOURCE''' The source actor is the one who initiates the event.
*'''TARGET''' The target actor is the one who receives the event.
*'''TIME''' The time denotes when the event happened. visone supports a wide range of time encodings - from numeric times to strings representing calendar date and time in more common or less common formats. Furthermore, a time unit can be specified that defines the precision of the time variable.
*'''TYPE''' The event type is a categorical variable specifying what happened. In our example, there are different choices for event types. One possibility is the rather coarse distinction between cooperative (positive) and conflictive (negative) events. The other possibility is to distinguish between all more than 100 different WEIS event types. An intermediate possibility (and that's what we are going to do in the following) is to use just the distinction between conflict and cooperation but to distinguish quantitatively between "strong" events and "weak" events by the event weight. For instance, the use of military force is counted more seriously than a warning - even though both are conflictive events.
*'''WEIGHT''' The event weight is a numeric variable quantifying the ''intensity'' of the event with respect to the event type (see the example above). For instance, ''military engagement'' has a weight of -10.0 while warnings have a weight of -3.0.

[[File:Eventnet_dialog_format_KEDS.png]]

After these five components have been chosen visone needs some information about the interpretation of time. 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 time of the KEDS events is given by the day. Thus, appropriate time units are '''DAY''' or coarser.

Note that the only required information are the columns containing the source and target - for the other components you can take default values (by selecting ''<implied>'' instead of a column header). The default value for the event type is the string ''EVENT'' (taking this default type means that there is no variation in event types - all have the same type); the default weight is equal to 1.0; the default event time is the row number in the input file (so that only the order of events is taken into account).

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.)

=== Event iterator ===

In the event iterator tab (see below) you have to specify the start and end time of the time interval to be processed and the delay between network snapshots.

[[File:Eventnet_dialog_iterator_KEDS.png]]

When the events have been created after filling out the event format tab (see the preceeding section) visone suggests as start time the time of the first event and as end time the time of the last event. If you don't want to process the whole event sequence you can increase the start time and/or decrease the end time. After clicking on the upper '''Apply / get info''' button, visone informs you about the number of events and time units in the specified subsequence. You might just take all events by not changing the interval borders; this includes all events from April 15, 1979 to March 31, 1999 - as can be seen in the dialog.

Then you have to choose the time points when a network snapshot is to be created by specifying the delay between snapshots. You can see in the dialog that the event sequence spans more than 7,200 time units (i.e., days with the current settings) which is almost 20 years. The number of snapshots must be small (some 10 or 20 snapshots are ok), since they are all opened in a new tab in visone. When we want to create a snapshot once a year we specify ''create snapshots after every'' '''365''' ''time unit(s)''. (The number of snapshots is then 20.) visone always creates one snapshot at the end of the event sequence - even if the waiting time is less than the specified number.

=== Event network ===

The tab to specify the event network is the most important one - here you define which '''link attributes''' of the event network summarize the past events, how events of various types add to these attributes, and how they change over time.

[[File:Eventnet_dialog_network_KEDS.png]]

The first thing to do is to decide on the link attributes. Here you are free to choose any attribute name (that makes it easy to remember the intuition of the attribute). Furthermore, a halftime - defining how fast attributes decay over time - has to be specified. The halftime has the following effect: when a particular link attribute on a particular dyad (pair or actors) has a value of <math>x</math> at time <math>t</math>, then (if no event on the same dyad happens in between) the value is <math>x/2</math> at time
<math>t+halftime</math>. Intuitively, link attributes with a positive halftime capture ''recent interaction''; if the halftime gets shorter then they capture even more recent interaction. A halftime equal to zero or negative indicates that the respective attribute does not decay over time; these attributes capture ''past interaction'' irrespective of the elapsed time.

In our concrete example we choose the following link attributes that all have a halftime of (approximately) one year.
* An attribute '''cooperation''' sums up the weights of past cooperative events.
* The link attribute '''conflict''' is similar and sums up past conflictive events. This attribute will also be non-negative; that is, a higher value means more past/recent conflict. (See later how this is achieved.)
* '''Interaction''' sums up the strength of past events - irrespective of whether these are cooperative or conflictive.
* '''Interaction (unweighted)''' sums up the number of past events - irrespective of whether these are cooperative or conflictive and irrespective of their weight.
* Finally '''cooperation-conflict''' sums up the (positive) weights of cooperative events and the (negative) weights of conflictive events. This attribute is positive on dyads that have more cooperative events (or cooperative events with higher weights) and it is negative on dyads on which there are more conflictive events (or more serious conflictive events).

When the link attributes are added (e.g., click on the '''Add / update all''' button) you have to specify how the events contribute to them. Clicking on '''Create weight-function table''' builds a table that has one row for each link attribute and one column for each event type. In the cell indexed by an attribute <math>attr</math> and an event type <math>t</math> you specify the function mapping weights of events of type <math>t</math> to increments of the link attribute <math>attr</math>. In our example, selecting the function ''Identity'' in the cell indexed by attribute ''cooperation'' and event type ''cooperation'' means that whenever an event of type ''cooperation'' and weight <math>w</math> happens then you add <math>w</math> to the current value of the ''cooperation'' attribute. If we had chosen ''SquareRoot'' as the weight function in the same cell, then we would add <math>\sqrt{w}</math> to the ''cooperation'' attribute whenever an event of type ''cooperation'' and weight <math>w</math> happens. The weight-function identifier ''N/A'' means that events of that type do not cause any change of the respective attribute. For instance, events of type ''conflict'' do not change the attribute ''cooperation''. Note that for the attribute ''conflict'' and the type ''conflict'' we choose the weight function ''MinusIdentity''; thus, when a conflictive event with weight -10 happens we add the (positive) value 10 to the attribute ''conflict'' (thereby the ''conflict'' attribute is always non-negative and higher values indicate more past conflicts). The settings for all attributes and types can be seen in the above image.

After these settings have been done you can create the snapshots by clicking on the button '''Process event network!'''. If you want to create a statistics table you first have to fill out the tab number 4. We turn to the statistics [[#Event_statistics|later]] and create the snapshots now.

== Visualization and analysis of event networks ==

With the above settings visone opens 20 network tabs. The nodes in the network have an attribute ''label'' that holds the names of the source or target nodes as they are given in the event list file. The links have (in our example) five numerical attributes encoding the values of the link attribute functions at the time of the snapshot. These link attributes allow to compute, for instance, the total amount of conflict or cooperation received or initialized by the actors (compute the indegree respectively outdegree with link strength set to ''conflict'' or ''cooperation'' or any other link attribute). These degrees can, for instance, be used for visual filtering by [[Visualization_tab|mapping]] the centrality values to size or color of the nodes or selecting nodes by importance. Examples for visualization of event networks can be found in the [[Wikipedia_edit_networks_(tutorial)|tutorial on Wikipedia edit networks]]. Note that all analysis and visualization tasks can be done in parallel for all open network tabs and note that visone also offers to compute a [[Visualization_tab#dynamic_layout|dynamic layout]] that can be animated; this is illustrated in the [[Collections_(tutorial)|tutorial on network collections]]. The image below is an example placing the most involved actors in the center of the drawing and coding rather cooperative ties in blue and rather conflictive ties in red.

[[File:Event_network_gulf_example.png|800px]]

== Statistical modeling of the conditional event type or weight ==

While importing event networks it is possible to compute and save network statistics associated with dyadic events that can be used to build and estimate a statistical model for the '''conditional event type'''. Such models have been proposed in Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders (2009): [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. These models can be used to test whether the network of past events explains the likelihood that future events among a given pair of actors are rather cooperative or rather conflictive, for instance
* Do actors have a tendency to fight those that attacked them in the past? (Tendency to retalliate.)
* Do actors have a tendency to cooperated with the enemies of their enemies, to fight the friends of their enemies, etc?

The event network statistics can be computed during importing the data, are saved in a file, and can then be analyzed with any statistical software, such as [http://www.r-project.org/ '''R'''].

It is important to understand that with the statistics table computed by visone you can estimate a model for the '''conditional''' event type, given that an event happens, as this has been defined in Brandes et al.(2009). With the visone output you cannot model the likelihood that two actors interact at all. (Such models can be specified and fitted, for instance, with the R package [http://cran.r-project.org/web/packages/relevent/index.html '''relevent'''] or with the software [https://github.com/juergenlerner/eventnet '''event network analyzer (eventnet)'''], where in the latter you can choose whether or not to condition on the sources or targets or events.) More on the difference between modeling the conditional event type and the marginal (unconditional) event type can be found in the slides [[Media:Lerner_Sunbelt12.pdf|'''Modeling Frequency and Type of Interaction in Event Networks''' (.pdf)]].

To make the analysis comparable to the one presented in Brandes et al.(2009), we modify the link attributes in the event network tab slightly (see below). Specifically we set the halftime to 30 days and include only the attributes ''conflict'' and ''cooperation''. (The settings in the event format stay the same and in the event iterator tabs you may set the delay between snapshots to 7291 to create only one snapshot.)

[[File:Eventnet_dialog_network_KEDS30.png]]

=== Event statistics ===

The statistics to be computed are defined in the eventnet statistics tab of the import dialog (see below). You first have to specify whether a statistic table should be created at all; if yes an output file has to be chosen and one or more statistics have to be defined.

[[File:Eventnet_dialog_statistics_KEDS.png]]

The statistics are used to model events in the following way: whenever an event happens that is initiated by a '''source''' node and directed to a '''target''' node, then the dyad ''(source, target)'' is embedded in the network of past events, i.e., all events that happened before the current event. The event network statistics describe relevant aspects of this network of past events with respect to the specific dyad. visone offers three different types of statistics - dyad statistics, degree statistics, and triangle statistics - that can be varied with respect to edge direction and/or link attributes. After defining the statistics they have to be added to the event network by clicking on the '''Add / update''' button.

==== Dyad statistics ====

Dyad statistics encode aspects of the past events from ''source'' to ''target'' or in the other direction. That is the dyad statistics encode how ''source'' interacted with ''target'' in the past or how ''target'' interacted with ''source''. In our exmple we define four different dyad statistics that are obtained by switching the direction (''inertia'' if '''OUT'''-going events - from ''source'' to ''target'' - are considered and ''reciprocity'' if '''IN'''-coming events - from ''target'' to ''source'' - are considered) and the link attribute (''positive'' for past cooperation and ''negative'' for past conflict).

Intuitively, if actors tend to retalliate, then we expect that the ''negative reciprocity'' statistic is negatively related with the weight of the next event.

==== Degree statistics ====

Degree statistics summarize the past events around the dyad ''(source, target)'' by the weighted (out-/in-) degree of ''source'' or ''target''. The links can be weighted by any attribute. For instance, the ''neg_outdeg_source'' statistic adds up the values of the ''conflict'' attribute on all links starting at the ''source'' node (not only those that are directed to ''target'').

Intuitively, if actors that initiated a lot of conflictive events in the past tend to do so in the future, then we expect a negative relation between the ''neg_outdeg_source'' statistic and the weight of events.

==== Triangle statistics ====

Triangle statistics summarize the network of past events around the dyad ''(source, target)'' by typed and weighted indirect relations from ''source'' over any third node to ''target'' or the other way round. You can select the attributes for the links attached to ''source'' and to ''target'' and the direction which can be '''OUT''' (only out-going ties with respect to ''source''/''target''), '''IN''' (only in-coming ties), or '''SYM''' (adding up the attributes of out-going and in-coming ties).

For instance, the statistic ''enemy_of_friend'' iterates over all actors ''A'' in the network, multiplies the value of the ''cooperation'' attribute on links connecting ''source'' and ''A'' (in both directions) with the value of the ''conflict'' attribute on links connecting ''target'' and ''A'' (in both directions), adds up these products for all ''A'', and returns the square root of this sum. Intuitively, the value of the ''enemy_of_friend'' statistic on the dyad ''(source, target)'' is high if there are many other actors ''A'' that cooperated with ''source'' and were in conflict with ''target''; structural balance theory predicts that ''source'' is then more likely to fight ''target''.

==== Starting the computation ====

Once the output file and the statistics are specified, click on the '''Process event network!''' button. Snapshots are created as defined in the event iterator tab and statistics are computed as defined in the eventnet statistics tab.

'''Note''' that statistics associated with an event that happens at time ''t'' are only a function of events that happend earlier (strictly before ''t'') - and do not depend on events that happen in the same time unit.

The computed eventnet statistics file (''gulf_events_stats.csv'' in our example) is a table in CSV format in which each row corresponds to one event of the input file. The components of the event (source, target, time, type, and weight) are first repeated - followed by the values of all statistics.

Computing the statistics for all 300,000 events may take some five to ten minutes on a current standard laptop. Once the computation is finished you see the message ''processing successfull'' in the eventnet dialog. If you get an error message you might have a look at the visone [[Console|console]] where you can get more information.

=== Modeling the conditional event weight ===

The statistics file can now be analyzed with any statistical software - we describe the following for the [http://www.r-project.org R environment for statistical computing] (also see the visone tutorial on the [[R_console_(tutorial)|R console]]).

First set the R working directory to the directory where the statistics file is located, for instance
setwd("c:/juergen/projects/event_data/keds/Gulf/")
To read the file into a table and see some summary statistics type
eventnet.stats <- read.csv("gulf_events_stats.csv", sep=";")
summary(eventnet.stats)
We model only those events that are not self-loops (loops could have been removed already while preprocessing the input event list - these two procedures are not equivalent since in our case statistics are also functions of loops).
eventnet.stats <- eventnet.stats[as.character(eventnet.stats$SOURCE) != as.character(eventnet.stats$TARGET),]
summary(eventnet.stats)
A first very simple model is a linear model for the event weigth (from ''source'' to ''target'') - explained by the past conflictive events in the other direction (that is from ''target'' directed to the ''source'' node).
model.1 <- lm(WEIGHT ~ 1 + negative_reciprocity, data = eventnet.stats)
summary(model.1)
A summary of the estimated model yields (among others) the following output:
Coefficients:
Estimate Std. Error t value Pr(>|t|)
(Intercept) -5.730e-01 8.866e-03 -64.63 <2e-16 ***
negative_reciprocity -2.629e-03 2.829e-05 -92.92 <2e-16 ***
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
The interpretation is that there seems to be a habit of retalliation: if ''target'' has initiated conflictive events towards ''source'' then the weight of events from ''source'' to ''target'' has a tendency to be smaller (significantly negative coefficient for the ''negative_reciprocity'' statistic) meaning that the event type is drawn towards conflict. The value of the coefficient (about -0.003) seems to be very small. However this parameter summarizes the change in the event weight when ''negative_reciprocity'' increases by one. Typing
sd(eventnet.stats$negative_reciprocity)
we see that the standard deviation of this statistic is around 290 - meaning that the ''negative_reciprocity'' indicator typically varies in the hundreds.

A more complex model tests for structural balance effects, controlling for variation in degrees and direct past interaction. (This is the model taken from Brandes et al.(2009).)
model.2 <- lm(WEIGHT ~ 1 + positive_inertia + negative_inertia +
positive_reciprocity + negative_reciprocity +
pos_outdeg_source + neg_outdeg_source +
pos_indeg_source + neg_indeg_source +
pos_outdeg_target + neg_outdeg_target +
pos_indeg_target + neg_indeg_target +
friend_of_friend + friend_of_enemy +
enemy_of_friend + enemy_of_enemy,
data = eventnet.stats)
We get the following results.
Coefficients:
Estimate Std. Error t value Pr(>|t|)
(Intercept) -7.707e-01 1.127e-02 -68.371 < 2e-16 ***
positive_inertia 5.814e-03 2.723e-04 21.347 < 2e-16 ***
negative_inertia -2.145e-03 7.214e-05 -29.730 < 2e-16 ***
positive_reciprocity 3.071e-03 3.125e-04 9.827 < 2e-16 ***
negative_reciprocity -2.188e-03 8.175e-05 -26.768 < 2e-16 ***
pos_outdeg_source 1.391e-03 6.853e-05 20.295 < 2e-16 ***
neg_outdeg_source -2.426e-04 3.250e-05 -7.463 8.48e-14 ***
pos_indeg_source -6.058e-04 1.022e-04 -5.930 3.02e-09 ***
neg_indeg_source 1.028e-04 3.259e-05 3.153 0.001615 **
pos_outdeg_target 9.800e-04 7.372e-05 13.293 < 2e-16 ***
neg_outdeg_target 2.142e-05 3.192e-05 0.671 0.502180
pos_indeg_target -6.572e-04 9.495e-05 -6.922 4.48e-12 ***
neg_indeg_target 6.988e-05 3.051e-05 2.290 0.022014 *
friend_of_friend 1.884e-03 5.349e-04 3.523 0.000427 ***
friend_of_enemy -8.913e-04 2.912e-04 -3.061 0.002205 **
enemy_of_friend -1.308e-03 2.874e-04 -4.553 5.30e-06 ***
enemy_of_enemy -1.935e-04 1.532e-04 -1.263 0.206593
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
Among other results, this model provides evidence for some - but not all - hypotheses derived from structural balance theory: friends of friends tend to interact more cooperatively while friend of enemies as well as enemies of friends have a tendency to fight each other. On the other hand, the parameter associated with the ''enemy_of_enemy'' statistic is not significant. Note that the data set for fitting this model is different from the one taken in Brandes et al. (2009) since here we also included self-loops to compute the statistics (although events connecting an actor with itself have not been used when fitting the linear model).

Obviously, modeling the event type or event weight as a stochastic function of the event network statistics is not restricted to linear models. Furthermore, if the model should control for actor-level or dyad-level covariates (such as the population size of a country or an indicator for whether two countries have a common border), these can be merged into the statistics table after processing of the event network.

== References ==

* Carter T. Butts: [http://onlinelibrary.wiley.com/doi/10.1111/j.1467-9531.2008.00203.x/full '''A Relational event framework for social action''']. ''Sociological Methodology'' 38(1):155-200, 2008.
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.

Event networks (tutorial)

2018-12-18T09:22:02Z

Lerner:

[[File:Event_network_gulf_example.png|300px|thumb]]
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. Stated otherwise, relations like ''friendship'' have inertia (something has to happen to change them), while relational events mark time points of interaction.

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
* Carter T. Butts: [http://onlinelibrary.wiley.com/doi/10.1111/j.1467-9531.2008.00203.x/full '''A Relational event framework for social action''']. ''Sociological Methodology'' 38(1):155-200, 2008.
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.
and in other papers linked in the [[Event_networks_(tutorial)#References|references]].

The functionality for statistical analysis of event networks has been superseded by the [https://github.com/juergenlerner/eventnet '''event network analyzer (eventnet)''']. However, visone can still be used for visual analysis of event networks.

Please address questions and comments about this tutorial to me ([[User:Lerner|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 [http://eventdata.psu.edu/ 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|'''Penn State Event Data''']]. To follow the steps outlined in this tutorial you should download the file [[Media:Gulf_events_preprocessed.zip|Gulf_events_preprocessed.zip]].

Another specific application area for event networks - using different example data - is treated in the [[Wikipedia_edit_networks_(tutorial)|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|'''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.

[[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.

=== 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''). In our example, you can set the values as in the image below. The meaning of the five components is explained in the following.
*'''SOURCE''' The source actor is the one who initiates the event.
*'''TARGET''' The target actor is the one who receives the event.
*'''TIME''' The time denotes when the event happened. visone supports a wide range of time encodings - from numeric times to strings representing calendar date and time in more common or less common formats. Furthermore, a time unit can be specified that defines the precision of the time variable.
*'''TYPE''' The event type is a categorical variable specifying what happened. In our example, there are different choices for event types. One possibility is the rather coarse distinction between cooperative (positive) and conflictive (negative) events. The other possibility is to distinguish between all more than 100 different WEIS event types. An intermediate possibility (and that's what we are going to do in the following) is to use just the distinction between conflict and cooperation but to distinguish quantitatively between "strong" events and "weak" events by the event weight. For instance, the use of military force is counted more seriously than a warning - even though both are conflictive events.
*'''WEIGHT''' The event weight is a numeric variable quantifying the ''intensity'' of the event with respect to the event type (see the example above). For instance, ''military engagement'' has a weight of -10.0 while warnings have a weight of -3.0.

[[File:Eventnet_dialog_format_KEDS.png]]

After these five components have been chosen visone needs some information about the interpretation of time. 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 time of the KEDS events is given by the day. Thus, appropriate time units are '''DAY''' or coarser.

Note that the only required information are the columns containing the source and target - for the other components you can take default values (by selecting ''<implied>'' instead of a column header). The default value for the event type is the string ''EVENT'' (taking this default type means that there is no variation in event types - all have the same type); the default weight is equal to 1.0; the default event time is the row number in the input file (so that only the order of events is taken into account).

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.)

=== Event iterator ===

In the event iterator tab (see below) you have to specify the start and end time of the time interval to be processed and the delay between network snapshots.

[[File:Eventnet_dialog_iterator_KEDS.png]]

When the events have been created after filling out the event format tab (see the preceeding section) visone suggests as start time the time of the first event and as end time the time of the last event. If you don't want to process the whole event sequence you can increase the start time and/or decrease the end time. After clicking on the upper '''Apply / get info''' button, visone informs you about the number of events and time units in the specified subsequence. You might just take all events by not changing the interval borders; this includes all events from April 15, 1979 to March 31, 1999 - as can be seen in the dialog.

Then you have to choose the time points when a network snapshot is to be created by specifying the delay between snapshots. You can see in the dialog that the event sequence spans more than 7,200 time units (i.e., days with the current settings) which is almost 20 years. The number of snapshots must be small (some 10 or 20 snapshots are ok), since they are all opened in a new tab in visone. When we want to create a snapshot once a year we specify ''create snapshots after every'' '''365''' ''time unit(s)''. (The number of snapshots is then 20.) visone always creates one snapshot at the end of the event sequence - even if the waiting time is less than the specified number.

=== Event network ===

The tab to specify the event network is the most important one - here you define which '''link attributes''' of the event network summarize the past events, how events of various types add to these attributes, and how they change over time.

[[File:Eventnet_dialog_network_KEDS.png]]

The first thing to do is to decide on the link attributes. Here you are free to choose any attribute name (that makes it easy to remember the intuition of the attribute). Furthermore, a halftime - defining how fast attributes decay over time - has to be specified. The halftime has the following effect: when a particular link attribute on a particular dyad (pair or actors) has a value of <math>x</math> at time <math>t</math>, then (if no event on the same dyad happens in between) the value is <math>x/2</math> at time
<math>t+halftime</math>. Intuitively, link attributes with a positive halftime capture ''recent interaction''; if the halftime gets shorter then they capture even more recent interaction. A halftime equal to zero or negative indicates that the respective attribute does not decay over time; these attributes capture ''past interaction'' irrespective of the elapsed time.

In our concrete example we choose the following link attributes that all have a halftime of (approximately) one year.
* An attribute '''cooperation''' sums up the weights of past cooperative events.
* The link attribute '''conflict''' is similar and sums up past conflictive events. This attribute will also be non-negative; that is, a higher value means more past/recent conflict. (See later how this is achieved.)
* '''Interaction''' sums up the strength of past events - irrespective of whether these are cooperative or conflictive.
* '''Interaction (unweighted)''' sums up the number of past events - irrespective of whether these are cooperative or conflictive and irrespective of their weight.
* Finally '''cooperation-conflict''' sums up the (positive) weights of cooperative events and the (negative) weights of conflictive events. This attribute is positive on dyads that have more cooperative events (or cooperative events with higher weights) and it is negative on dyads on which there are more conflictive events (or more serious conflictive events).

When the link attributes are added (e.g., click on the '''Add / update all''' button) you have to specify how the events contribute to them. Clicking on '''Create weight-function table''' builds a table that has one row for each link attribute and one column for each event type. In the cell indexed by an attribute <math>attr</math> and an event type <math>t</math> you specify the function mapping weights of events of type <math>t</math> to increments of the link attribute <math>attr</math>. In our example, selecting the function ''Identity'' in the cell indexed by attribute ''cooperation'' and event type ''cooperation'' means that whenever an event of type ''cooperation'' and weight <math>w</math> happens then you add <math>w</math> to the current value of the ''cooperation'' attribute. If we had chosen ''SquareRoot'' as the weight function in the same cell, then we would add <math>\sqrt{w}</math> to the ''cooperation'' attribute whenever an event of type ''cooperation'' and weight <math>w</math> happens. The weight-function identifier ''N/A'' means that events of that type do not cause any change of the respective attribute. For instance, events of type ''conflict'' do not change the attribute ''cooperation''. Note that for the attribute ''conflict'' and the type ''conflict'' we choose the weight function ''MinusIdentity''; thus, when a conflictive event with weight -10 happens we add the (positive) value 10 to the attribute ''conflict'' (thereby the ''conflict'' attribute is always non-negative and higher values indicate more past conflicts). The settings for all attributes and types can be seen in the above image.

After these settings have been done you can create the snapshots by clicking on the button '''Process event network!'''. If you want to create a statistics table you first have to fill out the tab number 4. We turn to the statistics [[#Event_statistics|later]] and create the snapshots now.

== Visualization and analysis of event networks ==

With the above settings visone opens 20 network tabs. The nodes in the network have an attribute ''label'' that holds the names of the source or target nodes as they are given in the event list file. The links have (in our example) five numerical attributes encoding the values of the link attribute functions at the time of the snapshot. These link attributes allow to compute, for instance, the total amount of conflict or cooperation received or initialized by the actors (compute the indegree respectively outdegree with link strength set to ''conflict'' or ''cooperation'' or any other link attribute). These degrees can, for instance, be used for visual filtering by [[Visualization_tab|mapping]] the centrality values to size or color of the nodes or selecting nodes by importance. Examples for visualization of event networks can be found in the [[Wikipedia_edit_networks_(tutorial)|tutorial on Wikipedia edit networks]]. Note that all analysis and visualization tasks can be done in parallel for all open network tabs and note that visone also offers to compute a [[Visualization_tab#dynamic_layout|dynamic layout]] that can be animated; this is illustrated in the [[Collections_(tutorial)|tutorial on network collections]]. The image below is an example placing the most involved actors in the center of the drawing and coding rather cooperative ties in blue and rather conflictive ties in red.

[[File:Event_network_gulf_example.png|800px]]

== Statistical modeling of the conditional event type or weight ==

While importing event networks it is possible to compute and save network statistics associated with dyadic events that can be used to build and estimate a statistical model for the '''conditional event type'''. Such models have been proposed in Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders (2009): [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. These models can be used to test whether the network of past events explains the likelihood that future events among a given pair of actors are rather cooperative or rather conflictive, for instance
* Do actors have a tendency to fight those that attacked them in the past? (Tendency to retalliate.)
* Do actors have a tendency to cooperated with the enemies of their enemies, to fight the friends of their enemies, etc?

The event network statistics can be computed during importing the data, are saved in a file, and can then be analyzed with any statistical software, such as [http://www.r-project.org/ '''R'''].

It is important to understand that with the statistics table computed by visone you can estimate a model for the '''conditional''' event type, given that an event happens, as this has been defined in Brandes et al.(2009). With the visone output you cannot model the likelihood that two actors interact at all. (Such models can be specified and fitted, for instance, with the R package [http://cran.r-project.org/web/packages/relevent/index.html '''relevent'''] or with the software [http://algo.uni-konstanz.de/software/eventnet/ '''event network analyzer (eventnet)'''], where in the latter you can choose whether or not to condition on the sources or targets or events.) More on the difference between modeling the conditional event type and the marginal (unconditional) event type can be found in the slides [[Media:Lerner_Sunbelt12.pdf|'''Modeling Frequency and Type of Interaction in Event Networks''' (.pdf)]].

To make the analysis comparable to the one presented in Brandes et al.(2009), we modify the link attributes in the event network tab slightly (see below). Specifically we set the halftime to 30 days and include only the attributes ''conflict'' and ''cooperation''. (The settings in the event format stay the same and in the event iterator tabs you may set the delay between snapshots to 7291 to create only one snapshot.)

[[File:Eventnet_dialog_network_KEDS30.png]]

=== Event statistics ===

The statistics to be computed are defined in the eventnet statistics tab of the import dialog (see below). You first have to specify whether a statistic table should be created at all; if yes an output file has to be chosen and one or more statistics have to be defined.

[[File:Eventnet_dialog_statistics_KEDS.png]]

The statistics are used to model events in the following way: whenever an event happens that is initiated by a '''source''' node and directed to a '''target''' node, then the dyad ''(source, target)'' is embedded in the network of past events, i.e., all events that happened before the current event. The event network statistics describe relevant aspects of this network of past events with respect to the specific dyad. visone offers three different types of statistics - dyad statistics, degree statistics, and triangle statistics - that can be varied with respect to edge direction and/or link attributes. After defining the statistics they have to be added to the event network by clicking on the '''Add / update''' button.

==== Dyad statistics ====

Dyad statistics encode aspects of the past events from ''source'' to ''target'' or in the other direction. That is the dyad statistics encode how ''source'' interacted with ''target'' in the past or how ''target'' interacted with ''source''. In our exmple we define four different dyad statistics that are obtained by switching the direction (''inertia'' if '''OUT'''-going events - from ''source'' to ''target'' - are considered and ''reciprocity'' if '''IN'''-coming events - from ''target'' to ''source'' - are considered) and the link attribute (''positive'' for past cooperation and ''negative'' for past conflict).

Intuitively, if actors tend to retalliate, then we expect that the ''negative reciprocity'' statistic is negatively related with the weight of the next event.

==== Degree statistics ====

Degree statistics summarize the past events around the dyad ''(source, target)'' by the weighted (out-/in-) degree of ''source'' or ''target''. The links can be weighted by any attribute. For instance, the ''neg_outdeg_source'' statistic adds up the values of the ''conflict'' attribute on all links starting at the ''source'' node (not only those that are directed to ''target'').

Intuitively, if actors that initiated a lot of conflictive events in the past tend to do so in the future, then we expect a negative relation between the ''neg_outdeg_source'' statistic and the weight of events.

==== Triangle statistics ====

Triangle statistics summarize the network of past events around the dyad ''(source, target)'' by typed and weighted indirect relations from ''source'' over any third node to ''target'' or the other way round. You can select the attributes for the links attached to ''source'' and to ''target'' and the direction which can be '''OUT''' (only out-going ties with respect to ''source''/''target''), '''IN''' (only in-coming ties), or '''SYM''' (adding up the attributes of out-going and in-coming ties).

For instance, the statistic ''enemy_of_friend'' iterates over all actors ''A'' in the network, multiplies the value of the ''cooperation'' attribute on links connecting ''source'' and ''A'' (in both directions) with the value of the ''conflict'' attribute on links connecting ''target'' and ''A'' (in both directions), adds up these products for all ''A'', and returns the square root of this sum. Intuitively, the value of the ''enemy_of_friend'' statistic on the dyad ''(source, target)'' is high if there are many other actors ''A'' that cooperated with ''source'' and were in conflict with ''target''; structural balance theory predicts that ''source'' is then more likely to fight ''target''.

==== Starting the computation ====

Once the output file and the statistics are specified, click on the '''Process event network!''' button. Snapshots are created as defined in the event iterator tab and statistics are computed as defined in the eventnet statistics tab.

'''Note''' that statistics associated with an event that happens at time ''t'' are only a function of events that happend earlier (strictly before ''t'') - and do not depend on events that happen in the same time unit.

The computed eventnet statistics file (''gulf_events_stats.csv'' in our example) is a table in CSV format in which each row corresponds to one event of the input file. The components of the event (source, target, time, type, and weight) are first repeated - followed by the values of all statistics.

Computing the statistics for all 300,000 events may take some five to ten minutes on a current standard laptop. Once the computation is finished you see the message ''processing successfull'' in the eventnet dialog. If you get an error message you might have a look at the visone [[Console|console]] where you can get more information.

=== Modeling the conditional event weight ===

The statistics file can now be analyzed with any statistical software - we describe the following for the [http://www.r-project.org R environment for statistical computing] (also see the visone tutorial on the [[R_console_(tutorial)|R console]]).

First set the R working directory to the directory where the statistics file is located, for instance
setwd("c:/juergen/projects/event_data/keds/Gulf/")
To read the file into a table and see some summary statistics type
eventnet.stats <- read.csv("gulf_events_stats.csv", sep=";")
summary(eventnet.stats)
We model only those events that are not self-loops (loops could have been removed already while preprocessing the input event list - these two procedures are not equivalent since in our case statistics are also functions of loops).
eventnet.stats <- eventnet.stats[as.character(eventnet.stats$SOURCE) != as.character(eventnet.stats$TARGET),]
summary(eventnet.stats)
A first very simple model is a linear model for the event weigth (from ''source'' to ''target'') - explained by the past conflictive events in the other direction (that is from ''target'' directed to the ''source'' node).
model.1 <- lm(WEIGHT ~ 1 + negative_reciprocity, data = eventnet.stats)
summary(model.1)
A summary of the estimated model yields (among others) the following output:
Coefficients:
Estimate Std. Error t value Pr(>|t|)
(Intercept) -5.730e-01 8.866e-03 -64.63 <2e-16 ***
negative_reciprocity -2.629e-03 2.829e-05 -92.92 <2e-16 ***
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
The interpretation is that there seems to be a habit of retalliation: if ''target'' has initiated conflictive events towards ''source'' then the weight of events from ''source'' to ''target'' has a tendency to be smaller (significantly negative coefficient for the ''negative_reciprocity'' statistic) meaning that the event type is drawn towards conflict. The value of the coefficient (about -0.003) seems to be very small. However this parameter summarizes the change in the event weight when ''negative_reciprocity'' increases by one. Typing
sd(eventnet.stats$negative_reciprocity)
we see that the standard deviation of this statistic is around 290 - meaning that the ''negative_reciprocity'' indicator typically varies in the hundreds.

A more complex model tests for structural balance effects, controlling for variation in degrees and direct past interaction. (This is the model taken from Brandes et al.(2009).)
model.2 <- lm(WEIGHT ~ 1 + positive_inertia + negative_inertia +
positive_reciprocity + negative_reciprocity +
pos_outdeg_source + neg_outdeg_source +
pos_indeg_source + neg_indeg_source +
pos_outdeg_target + neg_outdeg_target +
pos_indeg_target + neg_indeg_target +
friend_of_friend + friend_of_enemy +
enemy_of_friend + enemy_of_enemy,
data = eventnet.stats)
We get the following results.
Coefficients:
Estimate Std. Error t value Pr(>|t|)
(Intercept) -7.707e-01 1.127e-02 -68.371 < 2e-16 ***
positive_inertia 5.814e-03 2.723e-04 21.347 < 2e-16 ***
negative_inertia -2.145e-03 7.214e-05 -29.730 < 2e-16 ***
positive_reciprocity 3.071e-03 3.125e-04 9.827 < 2e-16 ***
negative_reciprocity -2.188e-03 8.175e-05 -26.768 < 2e-16 ***
pos_outdeg_source 1.391e-03 6.853e-05 20.295 < 2e-16 ***
neg_outdeg_source -2.426e-04 3.250e-05 -7.463 8.48e-14 ***
pos_indeg_source -6.058e-04 1.022e-04 -5.930 3.02e-09 ***
neg_indeg_source 1.028e-04 3.259e-05 3.153 0.001615 **
pos_outdeg_target 9.800e-04 7.372e-05 13.293 < 2e-16 ***
neg_outdeg_target 2.142e-05 3.192e-05 0.671 0.502180
pos_indeg_target -6.572e-04 9.495e-05 -6.922 4.48e-12 ***
neg_indeg_target 6.988e-05 3.051e-05 2.290 0.022014 *
friend_of_friend 1.884e-03 5.349e-04 3.523 0.000427 ***
friend_of_enemy -8.913e-04 2.912e-04 -3.061 0.002205 **
enemy_of_friend -1.308e-03 2.874e-04 -4.553 5.30e-06 ***
enemy_of_enemy -1.935e-04 1.532e-04 -1.263 0.206593
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
Among other results, this model provides evidence for some - but not all - hypotheses derived from structural balance theory: friends of friends tend to interact more cooperatively while friend of enemies as well as enemies of friends have a tendency to fight each other. On the other hand, the parameter associated with the ''enemy_of_enemy'' statistic is not significant. Note that the data set for fitting this model is different from the one taken in Brandes et al. (2009) since here we also included self-loops to compute the statistics (although events connecting an actor with itself have not been used when fitting the linear model).

Obviously, modeling the event type or event weight as a stochastic function of the event network statistics is not restricted to linear models. Furthermore, if the model should control for actor-level or dyad-level covariates (such as the population size of a country or an indicator for whether two countries have a common border), these can be merged into the statistics table after processing of the event network.

== References ==

* Carter T. Butts: [http://onlinelibrary.wiley.com/doi/10.1111/j.1467-9531.2008.00203.x/full '''A Relational event framework for social action''']. ''Sociological Methodology'' 38(1):155-200, 2008.
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.

Wikipedia edit networks (tutorial)

2018-06-19T08:54:43Z

Lerner: /* Statistical modeling of edit event networks */

[[File:Wikipedia_vis_example.png|200px|thumb]]
The '''''edit network''''' associated with the history of [http://www.wikipedia.org Wikipedia] pages is a network whose nodes are the page(s) and all contributing users and whose edges encode time-stamped, typed, and weighted interaction events ('''''edit events''''') between users and pages and between users and users. Specifically, edit events encode the exact time when an edit has been done along with one or several of the following types of edit interaction:
* the amount of new text that a user '''adds''' to a page;
* the amount of text that a user '''deletes''' (along with the other user/s that has/have previously added this text);
* the amount of previously deleted text that a user '''restores''' (along with the users that previously deleted and the ones that originally added the text).

Together these edit events form a highly dynamic network revealing the emergent collaboration structure among contributing users. For instance, it can be derived
* who are the users that contributed most of the text;
* what are the implicit '''roles''' of users (e.g., contributors of new content, vandalism fighters, watchdogs);
* whether there are '''opinion groups''', i.e., groups of users that mutually fight against each others edits.

This [[Tutorials|tutorial]] is a practically oriented "how-to"-guide giving an example based introduction to the computation, analysis, and visualization of Wikipedia edit networks. More background can be found in the papers cited in the [[Wikipedia_edit_networks_(tutorial)#References|references]]. To follow the steps outlined here (or to do a similar study) you should download [[WikiEvent_(software)|'''WikiEvent''']] - a small graphical java software with which Wikipedia edit networks can be computed.

Please address questions and comments about this tutorial to me ([[User:Lerner|Jürgen Lerner]]).

== How to download the edit history? ==

Wikipedia not only provides access to the current version of each page but also to all of its previous versions. To view the page history in your browser you can just click on the '''history''' link on top of each page and browse through the versions. However, for automatic extraction of edit events we need to download the complete history in a more structured format. To do this there are various possibilities that are appropriate in different scenarios (and dependent on your computational resources and internet bandwidth).

To get the history of '''all''' pages you can go to the [http://dumps.wikimedia.org/backup-index.html Wikimedia database dumps], select the wiki of interest (for instance, '''enwiki''' for the English-language Wikipedia), and download all files linked under the headline ''All pages with complete edit history''. The complete database is extremely large (several [http://en.wikipedia.org/wiki/Terabyte terabytes] for the English-language Wikipedia) and probably cannot be managed with an ordinary desktop computer.

Another possibility to get the complete history of a Wikipedia page (or of a small set of pages) is to use the wiki's [http://en.wikipedia.org/wiki/Special:Export Export page]. The preceeding link is for the English-language Wikipedia - for other languages just change the language identifier ''en'' in the URL to, for instance, ''de'' or ''fr'' or ''es'', etc. (Actually, this visone wiki has, as any other MediaWiki, also an export page available at [[Special:Export]]; there you could download the edit history of visone manual pages - which are definitively much shorter than those from Wikipedia.)

[[File:Wikipedia_export_pages.png|400px]]

For instance, to download the history of the page [http://en.wikipedia.org/wiki/Social_network_analysis '''Social network analysis'''] make settings as in the screenshot above and click on the '''Export''' button. However, as it is noted on the page, exporting is limited to 1000 revisions and the example page (Social network analysis) has already more than 2700 revisions. In principle it is possible to download the next 1000 revisions by specifying an appropriate offset (as explained on the [http://www.mediawiki.org/wiki/Manual:Parameters_to_Special:Export manual page for Special:Export]) and then pasting the files together. However, since this is rather tedious the software [[WikiEvent_(software)|WikiEvent]] offers a possibility to do this automatically. (Internally WikiEvent proceeds exactly as described above by retrieving revisions in chunks of 1000 and appending these to a single output file.)

To download a page history with [[WikiEvent_(software)|WikiEvent]] you start the program (download it from [http://www.inf.uni-konstanz.de/algo/software/wikievent/ http://www.inf.uni-konstanz.de/algo/software/wikievent/] and execute by double-clicking) and click on the entry '''download history''' in the '''net''' menu. You have to specify the language of the Wikipedia (for instance, '''en''' for English, '''de''' for German, '''fr''' for French, etc), the title of the page to download and a directory on your computer in which the file should be saved.

[[File:Wikipedia_lang_code.png]] [[File:Wikipedia_page_title.png]] [[File:Wikipedia_download_sna.png]]

The program is actually very silent - for instance, you don't see a progres bar - until the download is complete. The time it takes to download depends on many factors, among them the size of the page history (which might be several [http://en.wikipedia.org/wiki/Gigabyte gigabytes] for some popular pages!) and the bandwidth of your internet connection. At the end you see the number of downloaded revisions in the message area of WikiEvent.

For information: the size of the history file for the page ''Social network analysis'' is about 84 [http://en.wikipedia.org/wiki/Megabyte Megabytes] on May 04, 2015 (obviously growing). The history is saved in a file '''Social_network_analysis.xml''' in the directory that you have chosen. If you are interested, the XML format is described in the page [http://www.mediawiki.org/wiki/Help:Export http://www.mediawiki.org/wiki/Help:Export] - but you never have to read these files since they are automatically processed as described below.

== Computing the edit network ==

To compute the edit events from a Wikipedia history file select the entry '''extract edit events''' in the '''page'''-menu of WikiEvent. You have to specify one or more history file(s) and a directory to save the files with the edit events. (These output files have the same names as the input files - just with the ending '''.xml''' replaced by '''.csv'''.)

[[File:Wikipedia_extract_edit_events.png]]

If we compute the edit events from the history of the page ''Social network analysis'', then the first few lines of the edit event file look like this:
PageTitle;RevisionID;Time(calendar);Time(milliseconds);InteractionType;WordCount;ActiveUser;Target
"Social network analysis";1711088;2003-09-23T21:08:52Z;1064344132000;added;196;"142.177.104.40";"Social network analysis"
"Social network analysis";2002109;2003-11-11T06:13:44Z;1068527624000;added;10;"63.228.105.175";"Social network analysis"
"Social network analysis";2002109;2003-11-11T06:13:44Z;1068527624000;deleted;192;"63.228.105.175";"142.177.104.40"
"Social network analysis";2036847;2003-12-19T22:42:43Z;1071870163000;added;54;"Davodd";"Social network analysis"
"Social network analysis";2036847;2003-12-19T22:42:43Z;1071870163000;deleted;7;"Davodd";"63.228.105.175"
"Social network analysis";2210638;2003-12-24T13:29:11Z;1072268951000;added;1;"210.49.82.219";"Social network analysis"
"Social network analysis";2210638;2003-12-24T13:29:11Z;1072268951000;deleted;1;"210.49.82.219";"Davodd"
...

The file encodes a table with entries separated by semicolons (''';'''). The columns from left to right encode
* The '''title''' of the page (since a history file can contain the history of several pages the title-field can actually vary.).
* The '''revision id''' which is a number uniquely identifying a revision in Wikipedia (not just in one page). A single edit can produce more than just one line in the output file (we say more on this below); the revision id makes it possible to recognize which lines belong to the same edit.
* The '''time''' of the edit given as a date/time-string. For instance the first edit happend on September 23, 2003 at 21:08:52 (where time is measured in the [http://en.wikipedia.org/wiki/Coordinated_Universal_Time UTC] time zone).
* Once again the edit '''time''' given as a number encoding milliseconds since January 1, 1970 at 00:00:00.000 Greenwich Mean Time. (This value is actually obtained by the method <code>getTimeInMillis</code> of the java class <code>Calendar</code>.) The time in milliseconds is helpful if you just need the time ''difference'' between revisions and not the actual time or date; it is obvisously easier to compute the time difference from numbers than from data/time strings.
* The edit '''type''' which can be ''added'', ''deleted'', ''restored'', or ''undeleted''; we say more on this below.
* The '''word count''', i.e., the number of words that are added, deleted, restored, or undeleted with respect to the given target.
* The '''active user''' is the user that has done the edit; it is the source node of the edit event. The user is identified by a user name if logged in; otherwise (if it is an anonymous edit) the user is identified by an IP address.
* The '''target''' node of the edit event is either the page or a user. If the event type is ''added'', then the target is the page (the active user adds text to the page). If the event type is ''deleted'', ''restored'', or ''undeleted'', then the target is the user who has previously written or deleted the text (the active user deletes/restores/undeletes text that has been added/deleted by the target user).

We say more on the different event types in the following.

=== The structure of edit network data ===

Consider an example of three revisions on one page where
* (in Revision 1) user ''Alice'' adds some new text to the page;
* subsequently (in Revision 2), user ''Bob'' deletes this text;
* then (in Revision 3), user ''Charlie'' [http://en.wikipedia.org/wiki/Help:Reverting reverts] Bob's edit - setting back the page text to the one submitted in Revision 1.

These three edits together give rise to '''four''' dyadic edit events (shown in the image below):

[[File:Edit_network_example.png]]

* An edit event of type ''added'' from user Alice to the edited page.
* An edit event of type ''deleted'' from user Bob directed to user Alice.
* An edit event of type ''restored'' from user Charlie directed to user Alice (Charlie restored text that has been previously written by Alice).
* An edit event of type ''undeleted'' from user Charlie directed to user Bob (Charlie restored text that has been previously deleted by Bob). '''Note''' that after the revert the restored text is (again) authored by Alice and not by Charlie.

All edit events are weighted by the number of words that have been added, deleted, restored, or undeleted and all edit events have a time stamp marking the time when the edit has been submitted.

A single edit on a Wikipedia page generates one '''hyperedge''' linking the active user to (potentially) several other users and the edited page. Such a hyperedge has been turned into several lines of the CSV file, each encoding one '''(dyadic) edge''', linking the source (active user) to one target in one interaction type. Note that the hyperedges can be reconstructed from the data using the revision ids (see above).

For determining the amount of text modified in an edit we make some choices. For instance, if complete sentences are just moved from one part of the page to another, we do not count this as any change. More detailed information about the text-processing conventions can be found in
* Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij: [http://www.inf.uni-konstanz.de/algo/publications/bklv-nacsw-09.pdf '''Network Analysis of Collaboration Structure in Wikipedia''']. Proc. 18th Intl. World Wide Web Conference (WWW 2009).
and more technically in
* Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij: [http://www.inf.uni-konstanz.de/algo/publications/bklv-cwen-09.pdf '''Computing Wikipedia Edit Networks''']. Technical Report, 2009.

For convenience, we make the computed edit events available for download in the file [[Media:Social_network_analysis.zip|Social_network_analysis.zip]].

== Importing edit event networks into visone ==

The CSV file with the computed edit events can be imported in visone when opening it as an '''event list file'''. Visone's capabilities in importing and analyzing event networks are documented in the [[Event_networks_(tutorial)|tutorial on event networks]]; here we treat the special case of edit event networks.

To open an event list file (such as the newly created ''Social_network_analysis.csv'') click on '''open''' in visone's '''file''' menu, select '''files of type''': ''event list files'', navigate to the CSV file, and click on '''ok'''. In the import options, choose
the semicolon (''';''') as a cell delimiter and double quotes ('''"''') as textframe.

[[File:File_open_eventlist.png]] [[File:Import_options_event_list.png]]

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.

=== 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 (source, target, time, type, and weight). You can set the values as in the image below.

[[File:Eventnet_dialog_format.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 '''yyyy-MM-dd'T'HH:mm:ss'Z'''' which is appropriate for the Wikipedia edit times. 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 a (integer) number 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 finest time unit that makes sense for the Wikipedia edit events is ''Second'' (since the edit times are not given with higher precision). But you could also choose ''Day'' as a time unit if you think that this is fine-grained enough.

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.

=== Event iterator ===

In the event iterator tab (see below) you have to specify the start and end time of the time interval to be processed and the delay between network snapshots.

[[File:Eventnet_dialog_iterator.png]]

When the events have been created after filling out the event format tab (see the preceeding section) visone suggests as start time the time of the first event and as end time the time of the last event. If you don't want to process the whole event sequence you can increase the start time and/or decrease the end time. After clicking on the upper '''Apply / get info''' button, visone informs you about the number of events and time units in the specified subsequence. You might just take all events by not changing the interval borders; this includes all events from September 23, 2003 to July 11, 2012 - as can be seen in the dialog.

Then you have to choose the time points when a network snapshot is to be created by specifying the delay between snapshots. You can see in the dialog that the event sequence spans more than 277 million time units (i.e., seconds with the current settings). The number of snapshots must be small (some 10 or 20 snapshots would still be ok), since they are all opened in a new tab in visone. When specifying: ''create snapshots after every'' '''100,000,000''' ''time unit(s)'', then visone creates three snapshots. (This is an example where a coarser time unit might be more intuitive; 100 million seconds are actually a bit more than 1157 days.) visone always creates one snapshot at the end of the event sequence - even if the waiting time is less than the specified number.

'''Note''': Do not click on ''Process event network'' before you specify the event network in the next step.

=== Event network ===

The tab to specify the event network is the most important one - here you define which '''link attributes''' of the event network summarize the past events, how events of various types add to these attributes, and how they change over time. The dialog might seem a bit complicated at first glance but the mechanism to specify the evolution of the event network is very powerful and general.

[[File:Eventnet_dialog_network.png]]

The first thing to do is to decide on the link attributes. Here you are free to choose any attribute name (that makes it easy to remember the intuition of the attribute). Furthermore, a halftime - defining how fast attributes decay over time - has to be specified. The halftime has the following effect: when a particular link attribute on a particular dyad (pair or actors) has a value of <math>x</math> at time <math>t</math>, then (if no event on the same dyad happens in between) the value is <math>x/2</math> at time
<math>t+halftime</math>. Intuitively, link attributes with a positive halftime capture ''recent interaction''. A halftime equal to zero or negative indicates that the respective attribute does not decay over time; these attributes capture ''past interaction'' irrespective of the elapsed time.

In our concrete example we choose the following link attributes.
* The attributes ''added'', ''deleted'', ''restored'', and ''undeleted'' just add up the weight (i.e., the number of words modified) of past events of the respective type (with no decay). For instance, the value of the attribute ''added'' on a link connecting user ''U'' with page ''P'' at time ''t'' is equal to the number of words that ''U'' contributed to ''P'' at or before time ''t''. Similarly, the value of ''deleted'' on a dyad ''(U,V)'' is equal to the number of words that user ''U'' deleted of text previously written by user ''V''.
* The attribute ''recently added'' counts words added by users to a page but has a decay over time. If we choose as halftime the same value as for the interval between snapshots, then 100 words added just at the end of the first interval (say) contribute with a value of 50 at the end in the second snapshot. (It is also possible to introduce attributes like ''recently deleted'', etc; and it would also be possible to have varying halftimes to capture very recent interaction, recent interaction, more distant interaction, etc., in the same event network.)
* The attribute ''log added'' adds up the logarithm of the number of newly contributed words. A logarithmic transformation is appropriate in very skewed event weights (when, say, twice the number of words should not count twice as much but only slighly more). Other transformations of event weights are also possible.
* The attribute ''interacted'' adds up the number of modified (added, deleted, restored, or undeleted) words irrespective of the event type.
* The attribute ''agreed-disagreed'' is meant as a proxy for whether a user agrees or rather disagrees with the edits of another user. Specifically, deletions and undeletions are interpreted as disagreements since a user makes another user's edits undone; restoring text is interpreted as an agreement. (This indicator is proposed and used in the published papers cited in the [[Wikipedia_edit_networks_(tutorial)#References|references]] but will also become clearer in this tutorial.)

At the beginning the dialog has two rows for two different link attributes; more can be added by clicking the '''more attributes ...''' button. When all attributes are specified they have to be added to the event network (for instance by clicking the '''Add / update all''' button). Then you can create the weight function table.

In the '''weight function table''' there is one column for every event type and one row for every link attribute. A particular entry in this table specifies how events of the column type contribute to the link attribute in the respective row. The entries are combo boxes allowing you to select from the available weight functions. For instance, selecting the weight function ''Identity'' for the attribute ''deleted'' and the event type ''deleted'' implies that the weight (i.e., the number of words) of events of type ''deleted'' are added (without transforming them) to the link attribute ''deleted''. The weight function ''Logarithm'' for the attribute ''log added'' and the event type ''added'' implies that the logarithm of the event weight is added. Note that in the row corresponding to the attribute ''interacted'' we add up the weights of all event types; for the attribute ''agreed-disagreed'' we add weights of events of type ''restored'' and subtract (chose the weight function ''MinusIdentity'') weights of events of type ''deleted'' or ''undeleted''.

When these settings are complete you can process the event network. (You need to fill out the event statistics tab only when you want to do a statistical analysis of the event network - this is documented in a latter section: [[Wikipedia_edit_networks_(tutorial)#Statistical_modeling_of_edit_event_networks]].) After clicking on the button '''Process event network!''' it takes a few minutes or so (depending on the size and number of the snapshots). With our settings we create three network tabs holding the three snapshots. The dialog does not close after processing; you might change some of the settings and create different snapshots - or close the dialog explicitly.

For convenience, we make the GraphML file of the first snapshot available for download in [[Media:Social_network_analysis_(raw).graphml.zip|Social_network_analysis_(raw).graphml.zip]].

== Analysis and visualization of edit networks ==

The created network snapshots have nodes representing the page (or pages, if there are several in the history file) and all users that contributed at or before the time of the snapshot. The link attributes encode (in our case) the number of words added, deleted, restored, undeleted, or modifications thereof (as explained before) - again taken at the snapshot time. Analysis and visualization works similar as for any other network with many numerical link attributes. In particular, many of the derived user attributes that have been proposed in Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij (2009): [http://www.inf.uni-konstanz.de/algo/publications/bklv-nacsw-09.pdf '''Network Analysis of Collaboration Structure in Wikipedia'''] can be computed and visualized by visone starting from the available link attributes. Examplarily we illustrate some possibilities with the first snapshot, the smallest one, that has 412 nodes and 1341 links.

The first observation is that the layout after loading is very cluttered. Actually, all user-nodes that added at least one word to the page (''Social network analysis'') are at a distance of two or smaller - leading to the very dense circle around one very central node. An improvement can be achieved by deleting the node representing the page - after some information has been collected in the (user-)nodes. Therefore, go to the [[analysis tab]] select the node outdegree with ''link strength'' set to the link attribute ''added'' and save it in a node attribute ''added'' (see the screen shot below). Do the same again with the attribute ''log added''.

[[File:Eventnet_outdegree_added.png]]

To delete the single node representing the page we have to select it first. This can be done by selecting the single node with the label equal to ''Social network analysis'' in the [[Attribute manager]]; or (more generally since it is applicable to networks with several page-nodes) we compute the unweighted outdegree and select all nodes with outdegree equal to zero - these are exactly the nodes representing pages.

After having deleted the node representing the page, reducing to the largest connected component, and computing and visualizing some additional indicators, we can come up with an image as the following.

[[File:Wikipedia_vis_example.png|800px]]

Here the color of the nodes represent the amount of text added (blue for those who added a lot). The size of the nodes as well as the centrality of their position and the node label size represent the activity of the nodes - computed from the ''interacted'' attribute (note that this includes adding, deleting, restoring, or undeleting text). The width of the links is again a function of the ''interacted'' attribute. Finally the link color is tending to orange if the ''agreed-disagreed'' attribute admits strongly negative values (resulting from deletion or undeletion and being interpreted as disagreement) and the link color is tending to blue when the ''agreed-disagreed'' attribute becomes larger (being interpreted as agreement).

Many other ways to graphically encode these and other indicators are possible.

For convenience, we make the GraphML file of the first snapshot with an improved layout available for download in [[Media:Social_network_analysis.graphml.zip|Social_network_analysis.graphml.zip]].

== Statistical modeling of edit event networks ==

While importing event networks it is possible to compute and save network statistics associated with dyadic events that can be used to build and estimate a statistical model for the '''conditional event type'''. Such models have been proposed in Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders (2009): [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data'''] and applied to Wikipedia edit networks in Jürgen Lerner, Ulrik Brandes, Patrick Kenis, and Denise van Raaij (2012): [http://www.transcript-verlag.de/ts1927/ts1927.php '''Modeling Open, Web-based Collaboration Networks: The Case of Wikipedia''']. These models can be used to test whether the network of past edit events explains the likelihood of future deletions or undeletions, for instance
* Do users have a tendency to delete the edits from users who deleted them previously?
* Do the deletion/undeletion events give rise to patterns of structural balance?
(Note that the functionality for statistical analysis of event networks has been superseded by the [http://algo.uni-konstanz.de/software/eventnet/ '''event network analyzer (eventnet)'''], which is a separate software that is not restricted to the analysis of the conditional event type and offers much more general settings. We nevertheless keep the description below how to perform a statistical analysis of event networks with visone.)

The event network statistics can be computed during importing the data, are saved in a file, and can then be analyzed with any statistical software, such as [http://www.r-project.org/ '''R'''].

To illustrate how such statistics can be computed and modeled we modify the link attributes in the event network tab (see below). (The settings in the event format and event iterator tabs stay the same.)

[[File:Eventnet_dialog_attr4stat.png]]

Specifically, we define only two attributes, one that measures past agreement (a fuction or events of type ''restored'') and one the measures past disagreement (a function of events of type ''deleted'' or ''undeleted''). The halftime of both attributes is set to 30 days (which is 2592000 seconds) and the event weights (word counts) are logarithmically scaled.

=== Specifying event statistics in the eventnet dialog ===

The statistics to be computed are defined in the eventnet statistics tab of the import dialog (see below). You first have to specify whether a statistic table should be created at all; if yes an output file has to be chosen and one or more statistics have to be defined.

[[File:Eventnet_dialog_statistics.png]]

The statistics are used to model events in the following way: whenever an event happens that is initiated by a '''source''' node and directed to a '''target''' node, then the dyad ''(source, target)'' is embedded in the network of past events, i.e., all events that happened before the current event. The event network statistics describe relevant aspects of this network of past events with respect to the specific dyad. visone offers three different types of statistics - dyad statistics, degree statistics, and triangle statistics - that can be varied with respect to edge direction and/or link attributes. After defining the statistics they have to be added to the event network by clicking on the '''Add / update''' button.

==== Dyad statistics ====

Dyad statistics encode aspects of the past events from ''source'' to ''target'' or in the other direction. That is the dyad statistics encode how ''source'' interacted with ''target'' in the past and how ''target'' interacted with ''source''. In our exmple we define four different dyad statistics that are obtained by switching the direction (''inertia'' if '''OUT'''-going events - from ''source'' to ''target'' - are considered and ''reciprocity'' if '''IN'''-coming events - from ''target'' to ''source'' - are considered) and the link attribute (''positive'' for past agreements and ''negative'' for past disagreements).

Intuitively, if users tend to delete text of those that deleted them, then we expect that the ''negative reciprocity'' statistic is positively related with the likelihood that the edit event is of type ''deleted''.

==== Degree statistics ====

Degree statistics summarize the past events around the dyad ''(source, target)'' by the weighted (out-/in-) degree of ''source'' or ''target''. The links can be weighted by any attribute. For instance, the ''neg_outdeg_source'' statistic adds up the values of the ''disagreement'' attribute on all links starting at the ''source'' node (not only those that are directed to ''target'').

Intuitively, if users that deleted a lot in the past tend to delete in the future, then we expect a positive relation between the ''neg_outdeg_source'' statistic and the likelihood that the edit event is of type ''deleted''. This could point to the presence of users that play specific roles, for instance, "vandalism fighters" that undo malicious edits.

==== Triangle statistics ====

Triangle statistics summarize the network of past events around the dyad ''(source, target)'' by weighted indirect relations from ''source'' over any third node to ''target'' or the other way round. You can select the attributes for the links attached to ''source'' and to ''target'' and the direction which can be '''OUT''' (only out-going ties with respect to the ''source''/''target''), '''IN''' (only in-coming ties), or '''SYM''' (adding up the attributes of out-going and in-coming ties).

For instance, the statistic ''enemy_of_friend'' iterates over all users ''U'' in the network, multiplies the value of the ''agreement'' attribute on links connecting ''source'' and ''U'' (in both directions) with the value of the ''disagreement'' attribute on links connecting ''target'' and ''U'' (in both directions), and adds up these products for all ''U''. Intuitively, the value of the ''enemy_of_friend'' statistic on the dyad ''(source, target)'' is high if there are many other users ''U'' that are in agreement with ''source'' and in disagreement with ''target''; structural balance theory predicts that ''source'' is then more likely to disagree with ''target''.

==== Starting the computation ====

Once the output file and the statistics are specified, click on the '''Process event network!''' button. Snapshots are created as defined in the event iterator tab and statistics are computed as defined in the eventnet statistics tab.

'''Note''' that statistics associated with an event that happens at time ''t'' are only a function of events that happend earlier (strictly before ''t'') - and do not depend on events that happen in the same time unit.

The computed eventnet statistics file (''Social_network_analysis_stats.csv'' in our example) is a table in CSV format in which each row corresponds to one event of the input file. The components of the event (source, target, time, type, and weight) are first repeated in each row - followed by the values of all statistics.

=== Modeling the conditional event type ===
The statistics file can now be analyzed with any statistical software - we describe the following for the [http://www.r-project.org R environment for statistical computing] (also see the visone tutorial on the [[R_console_(tutorial)|R console]]).

First set the R working directory to the directory where the statistics file is located, for instance
setwd("c:/juergen/projects/wiki/data/")
To read the file into a table and see some summary statistics type
eventnet.stats <- read.csv("Social_network_analysis_stats.csv", sep=";")
summary(eventnet.stats)
For modeling the likelihood whether an edit is an ''undo'' edit we create a new binary variable '''is.undo''' that is equal to ''1'' if and only if the edit type is ''deleted'' or ''undeleted''.
eventnet.stats$is.undo <- 0
eventnet.stats$is.undo[eventnet.stats$TYPE == "deleted"] <- 1
eventnet.stats$is.undo[eventnet.stats$TYPE == "undeleted"] <- 1
summary(eventnet.stats)
We remove those events that are of type ''added'' (since these are interactions between users and the page).
eventnet.stats <- eventnet.stats[eventnet.stats$TYPE != "added",]
Further we model only those events that are not self-loops.
eventnet.stats <- eventnet.stats[as.character(eventnet.stats$SOURCE) != as.character(eventnet.stats$TARGET),]
A first very simple model is a logit model for the probability that an edit from ''source'' to ''target'' is an "undo" edit - explained by the past deletions in the other direction (that is from ''target'' directed to the ''source'' node).
model.1 <- glm(is.undo ~ 1 + negative_reciprocity, family = binomial(link=logit), data = eventnet.stats)
summary(model.1)
A summary of the estimated model yields (among others) the following output:
glm(formula = is.undo ~ 1 + negative_reciprocity, family = binomial(link = logit), data = eventnet.stats)
Coefficients:
Estimate Std. Error z value Pr(>|z|)
(Intercept) 0.49213 0.02175 22.630 < 2e-16 ***
negative_reciprocity 0.61765 0.20475 3.017 0.00256 **
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
The interpretation is that there seems to be a habit of "retaliate" deletions: if ''target'' has undone edits of ''source'' then there is an increased probability (postitive coefficient for the ''negative_reciprocity'' statistic) that ''source'' makes edits of ''target'' undone.

A more complex model tests for structural balance effects
model.2 <- glm(is.undo ~ 1 + friend_of_friend + enemy_of_friend +
friend_of_enemy + enemy_of_enemy,
family = binomial(link=logit), data = eventnet.stats)
leading to the following estimates.
Coefficients:
Estimate Std. Error z value Pr(>|z|)
(Intercept) 0.46288 0.02270 20.393 < 2e-16 ***
friend_of_friend 0.05798 0.08871 0.654 0.51340
enemy_of_friend 0.20675 0.07022 2.945 0.00323 **
friend_of_enemy 0.92448 0.10156 9.102 < 2e-16 ***
enemy_of_enemy -0.18435 0.02766 -6.666 2.63e-11 ***
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
The interpretation of the estimated coefficient is as follows (also see the four illustrative images below).

[[File:Friend_of_friend.png|250px]] [[File:Enemy_of_friend.png|250px]] [[File:Friend_of_enemy.png|250px]] [[File:Enemy_of_enemy.png|250px]]

The coefficient associated with the ''enemy_of_friend'' statistic is significantly positive. This implies that there is an increase probability for ''source'' undoing an edit of ''target'' if ''target'' has past disagreements with another user with which ''source'' has past agreements (second image in the row above). A similar effect has been found if ''target'' has past agreements with another user with past disagreements with ''source'' (positive parameter associated with the ''friend_of_enemy'' statistic and third image in the row above). The parameter associated with ''enemy_of_enemy'' is significantly negative; this implied that if both, ''source'' and ''target'' have past disagreements with a common other node (forth image), then they have a decreased probability of undoing each others edits. While these three effects are in line with the predictions of [[structural balance theory]], there is no significant parameter associated with the ''friend_of_friend'' statistic (first image in the row above).

See more on structural balance theory in the context of Wikipedia edit networks in Jürgen Lerner, Ulrik Brandes, Patrick Kenis, and Denise van Raaij: [http://www.transcript-verlag.de/ts1927/ts1927.php '''Modeling Open, Web-based Collaboration Networks: The Case of Wikipedia'''].

== The network of ''simple'' edit events ==

The [[WikiEvent_(software)|'''WikiEvent''' software]] offers the possibility to compute ''simple'' edit events from a (potentially huge) set of Wikipedia pages. A '''simple edit event''' is a directed, time-stamped event from a user ''U'' to a page ''P'' encoding that ''U'' made some edit on page ''P'' at the given time point. Simple edit events do not encode the type of an edit, nor the amount of text changed, nor the other users whose text has been changed (if any). A single edit on a Wikipedia page, thus, results in exactly one simple edit event - while several (''not simple'') edit events might result from one edit. To determine the edit events, WikiEvent does not even have to look at the page text - therefore the current text of any revision does not even have to be downloaded and the data collection and processing is much faster. Simple edit events are most interesting if they are computed from more than just one page (the simple edit events from one page just form a star with the page in the center), for instance on all pages that are relevant for a certain topic.

Since the page text is not necessary for computing simple edit events, it is possible to do this from history files that just contain meta-information about the page, author, and time stamp. Such '''stub''' files are provided in the [http://dumps.wikimedia.org/backup-index.html Wikimedia backup dumps]. For instance, to download meta-data about the complete English-language Wikipedia, follow the '''enwiki'''-link on that page, search for '''enwiki-<day_of_backup>-stub-meta-history.xml.gz''', and download this file. On July 2, 2012 the compressed file had a size of 25 gigabyte and after unpacking it a size of more than 130 gigabyte. Such large files can be processed by WikiEvent because processing can be done in a single pass over the file. (Reading such a file from the hard disc can take a few hours but certainly less than a day with current standard desktop computers.) Note that simple edit events ''can'' also be computed from complete history files that do contain the page text.

To extract simple edit events click on '''extract simple edit events''' in the '''page''' menu of WikiEvent. You have to specify a file containing the titles of pages for which edit events should be extracted (we say more on this below), a history file (which can be a stub file without page text), and an output directory. WikiEvent then creates three files in the output directory, one containing the simple edit events, one with a mapping from numerical ''user ids'' to user names, and one with a mapping from numerical ''page ids'' to page titles.

[[File:Wikipedia_extract_simple_edit_events.png]]

The input file with the page titles that has to be specified must contain one title per line - and nothing else. For instance, we created a file containing all page titles that include the terms ''social'' and ''network'' (for reproducability, this file is available at [[Media:SocialNetworkPageTitles.zip]]). Page titles are case-sensitive, for instance, ''Social network analysis'' points to a different page than ''Social Network Analysis''. The first few lines of this file look like this.
Social network
Social networking
Socialist Solidarity Network
Internet social network
Social Networking
Social networks
Internet social networks
Social Science Research Network
Socialist Organizing Network
Social Network Analysis
Socialist Unity Network
...
and the file contains 149 titles.

The resulting three files are available at [[Media:Social_network_simple_edit_events.zip]]. The event file <code>Social_network_SimpleEditEvents.csv</code> contains more than 23,000 events. It can be imported into visone in a similar way as described [[Wikipedia_edit_networks_(tutorial)#Importing_edit_event_networks_into_visone|above]] (just that there are no event types and weights). A snapshot of this network in the year 2006 looks like this.

[[File:Social_Network_SimpleEditEvents_(2006).png|400px]]

== The discussion network ==

In principle, the extraction of edit events could be done for pages of all types - including [http://en.wikipedia.org/wiki/Wikipedia:Talk_page_guidelines discussion pages]. However, this would not capture the fact that the editing on discussion pages follows a different logic than the editing on content pages. On discussion pages it is rather unusual that edits are made undone; on the other hand users often '''reply''' to posts of other users. To better represent the communication structure of talk pages, WikiEvent offers the possibility to '''extract talk events'''.

[[File:Wikipedia_extract_talk_events.png]]

The discussion around a page is structured by '''discussion threads'''. A new thread is marked by a section headline - typically describing the subject to discuss or a question that the users wants to be answered. Other users can reply by writting their message under the same headline. After having downloaded the history of the page [http://en.wikipedia.org/wiki/Talk:Social_network_analysis Talk:Social network analysis] (for instance) and having extracted the '''talk events''' with WikiEvent, the first few lines of the resulting event file look like the following.

ThreadHeadline;Time(calendar);Time(milliseconds);ActiveUser;DiscussionType;CharacterCount;IndexInThread;Target;ThreadInitiator;PreceedingAuthors...
"== Dunbar's 150 rule ==";"2004-07-29T13:22:39Z";1091100159000;"200.225.194.49";initialized_thread;499;0;"== Dunbar's 150 rule ==";"200.225.194.49";
"==Expansion==";"2004-10-30T06:09:59Z";1099109399000;"Goodoldpolonius";initialized_thread;321;0;"==Expansion==";"Goodoldpolonius";
"== Dunbar's 150 rule ==";"2005-01-05T18:09:43Z";1104944983000;"AndrewGray";replied_to;274;1;"200.225.194.49";"200.225.194.49";"200.225.194.49"
"== small world effect redirect ==";"2005-03-23T21:29:57Z";1111609797000;"Boud";initialized_thread;0;0;"== small world effect redirect ==";"Boud";
"==Image==";"2005-03-27T05:01:50Z";1111892510000;"Goodoldpolonius2";initialized_thread;663;0;"==Image==";"Goodoldpolonius2";
"== External links ==";"2005-04-03T01:32:35Z";1112484755000;"CesarB";initialized_thread;393;0;"== External links ==";"CesarB";
"== External links ==";"2005-04-03T02:07:18Z";1112486838000;"Goodoldpolonius2";replied_to;458;1;"CesarB";"CesarB";"CesarB"
"== External links ==";"2005-05-02T06:07:09Z";1115006829000;"AlanAu";replied_to;402;2;"Goodoldpolonius2";"CesarB";"CesarB","Goodoldpolonius2"
"== External links ==";"2005-05-06T22:39:28Z";1115411968000;"AlanAu";replied_to;135;3;"AlanAu";"CesarB";"CesarB","Goodoldpolonius2","AlanAu"
"== External links ==";"2005-05-06T22:40:30Z";1115412030000;"AlanAu";replied_to;5;4;"AlanAu";"CesarB";"CesarB","Goodoldpolonius2","AlanAu","AlanAu"
"== External links ==";"2005-05-06T23:12:26Z";1115413946000;"Goodoldpolonius2";replied_to;232;5;"AlanAu";"CesarB";"CesarB","Goodoldpolonius2","AlanAu","AlanAu","AlanAu"
"== External links ==";"2005-05-13T18:05:40Z";1116000340000;"82.149.68.78";replied_to;181;6;"Goodoldpolonius2";"CesarB";"CesarB","Goodoldpolonius2","AlanAu","AlanAu","AlanAu","Goodoldpolonius2"
"== External links ==";"2005-05-22T18:22:01Z";1116778921000;"AlanAu";replied_to;365;7;"82.149.68.78";"CesarB";"CesarB","Goodoldpolonius2","AlanAu","AlanAu","AlanAu","Goodoldpolonius2","82.149.68.78"
"== suggested additions ==";"2005-05-26T03:01:44Z";1117069304000;"AdamRetchless";initialized_thread;913;0;"== suggested additions ==";"AdamRetchless";
...

The file is a table encoded in a CSV file whose entries are separated by semicolons (''';'''). The columns encode (from left to right).
* The thread '''headline''', i.e., the subject of the discussion topic.
* The '''time''' given as a date/time string.
* Once again the '''time''' given as a number (milliseconds since January 1, 1970; see above).
* The '''active user''' which is the one who made the post.
* The discussion '''type''' of the edit which can be ''initialized_thread'' or ''replied_to''.
* The '''character count''' indicating number of characters posted in this edit; this might be taken as a (very coarse) indicator for the amount of work invested in the post.
* The '''index''' of this post in its thread; this is a number counting the replies: 0 for the thread initialization, 1 for the first reply, 2 for the second reply, and so on.
* The '''target''' of the post. This is the thread headline if the type of the post is ''initialized_thread'' and it is the user who made the last preceeding post to the same thread.
* The '''initiator''' of the thread.
* Finally a list of all '''preceeding authors''' separated by commas (''','''); first the user who initialized the thread, then the user who made the first reply, etc.

To import such a talk-event network into visone, chose '''files of type'''=''event list files'' after clicking on '''open''' in the '''file''' menu. The settings for the cell delimiter and textframe are the same (semicolon and double-quotes). Then, as for the edit events you have to specify event format, iterator, network, and (potentially) statistics. For a possible choice on the event format see the screenshot below.

[[File:Eventnet_dialog_format_talknet.png]]

In the event iterator tab we chose to create a snapshot after every 200 days (leading to 14 snapshots). In the event network tab we create two attribute functions counting the number of ''initiate'' events or ''reply'' events and give them a halftime equal to the time span between snapshots.

[[File:Eventnet_dialog_network_talknet.png]]

After creating the 14 snapshots, encoding involvement in the discussion by node size and number of thread initializations by color, and visualizing the network collection with a [[Collections_(tutorial)#Dynamic_visualization_and_animation_of_a_network_collection|dynamic layout]] we can come up with the following still images (which are more interesting to view in an [[Collections_(tutorial)#Dynamic_visualization_and_animation_of_a_network_collection|animation]]).

[[File:Talk.Social_network_analysis.png|200px]]
[[File:Talk.Social_network_analysis(13028).png|200px]]
[[File:Talk.Social_network_analysis(13228).png|200px]]
[[File:Talk.Social_network_analysis(13428).png|200px]]
[[File:Talk.Social_network_analysis(13628).png|200px]]
[[File:Talk.Social_network_analysis(13828).png|200px]]
[[File:Talk.Social_network_analysis(14028).png|200px]]
[[File:Talk.Social_network_analysis(14228).png|200px]]
[[File:Talk.Social_network_analysis(14428).png|200px]]
[[File:Talk.Social_network_analysis(14628).png|200px]]
[[File:Talk.Social_network_analysis(14828).png|200px]]
[[File:Talk.Social_network_analysis(15028).png|200px]]
[[File:Talk.Social_network_analysis(15228).png|200px]]

== References ==

Published papers that propose and/or make use of Wikipedia edit networks include the following.
* Jürgen Lerner, Ulrik Brandes, Patrick Kenis, and Denise van Raaij: [http://www.transcript-verlag.de/ts1927/ts1927.php '''Modeling Open, Web-based Collaboration Networks: The Case of Wikipedia''']. In Markus Gamper, Linda Reschke, Michael Schönhuth (Eds.): Knoten und Kanten 2.0, pp 141-162. transcript-Verlag, 2012.
* Jürgen Lerner, Patrick Kenis, Denise van Raaij and Ulrik Brandes: [http://www.sciencedirect.com/science/article/pii/S0263237311000053 '''Will they stay or will they go? How network properties of WebICs predict dropout rates of valuable Wikipedians''']. European Management Journal, 29(5):404-413, 2011.
* Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij: [http://www.inf.uni-konstanz.de/algo/publications/bklv-nacsw-09.pdf '''Network Analysis of Collaboration Structure in Wikipedia''']. Proc. 18th Intl. World Wide Web Conference (WWW 2009).

More technical details about the computation of Wikipedia edit networks can be found in
* Ulrik Brandes, Patrick Kenis, Jürgen Lerner, and Denise van Raaij: [http://www.inf.uni-konstanz.de/algo/publications/bklv-cwen-09.pdf '''Computing Wikipedia Edit Networks''']. Technical Report, 2009.

The techniques for modeling conditional network event types are proposed in
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.

Event networks (tutorial)

2018-06-18T11:29:18Z

Lerner: /* Statistical modeling of the conditional event type or weight */

[[File:Event_network_gulf_example.png|300px|thumb]]
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. Stated otherwise, relations like ''friendship'' have inertia (something has to happen to change them), while relational events mark time points of interaction.

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
* Carter T. Butts: [http://onlinelibrary.wiley.com/doi/10.1111/j.1467-9531.2008.00203.x/full '''A Relational event framework for social action''']. ''Sociological Methodology'' 38(1):155-200, 2008.
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.
and in other papers linked in the [[Event_networks_(tutorial)#References|references]].

The functionality for statistical analysis of event networks has been superseded by the [http://algo.uni-konstanz.de/software/eventnet/ '''event network analyzer (eventnet)''']. However, visone can still be used for visual analysis of event networks.

Please address questions and comments about this tutorial to me ([[User:Lerner|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 [http://eventdata.psu.edu/ 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|'''Penn State Event Data''']]. To follow the steps outlined in this tutorial you should download the file [[Media:Gulf_events_preprocessed.zip|Gulf_events_preprocessed.zip]].

Another specific application area for event networks - using different example data - is treated in the [[Wikipedia_edit_networks_(tutorial)|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|'''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.

[[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.

=== 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''). In our example, you can set the values as in the image below. The meaning of the five components is explained in the following.
*'''SOURCE''' The source actor is the one who initiates the event.
*'''TARGET''' The target actor is the one who receives the event.
*'''TIME''' The time denotes when the event happened. visone supports a wide range of time encodings - from numeric times to strings representing calendar date and time in more common or less common formats. Furthermore, a time unit can be specified that defines the precision of the time variable.
*'''TYPE''' The event type is a categorical variable specifying what happened. In our example, there are different choices for event types. One possibility is the rather coarse distinction between cooperative (positive) and conflictive (negative) events. The other possibility is to distinguish between all more than 100 different WEIS event types. An intermediate possibility (and that's what we are going to do in the following) is to use just the distinction between conflict and cooperation but to distinguish quantitatively between "strong" events and "weak" events by the event weight. For instance, the use of military force is counted more seriously than a warning - even though both are conflictive events.
*'''WEIGHT''' The event weight is a numeric variable quantifying the ''intensity'' of the event with respect to the event type (see the example above). For instance, ''military engagement'' has a weight of -10.0 while warnings have a weight of -3.0.

[[File:Eventnet_dialog_format_KEDS.png]]

After these five components have been chosen visone needs some information about the interpretation of time. 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 time of the KEDS events is given by the day. Thus, appropriate time units are '''DAY''' or coarser.

Note that the only required information are the columns containing the source and target - for the other components you can take default values (by selecting ''<implied>'' instead of a column header). The default value for the event type is the string ''EVENT'' (taking this default type means that there is no variation in event types - all have the same type); the default weight is equal to 1.0; the default event time is the row number in the input file (so that only the order of events is taken into account).

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.)

=== Event iterator ===

In the event iterator tab (see below) you have to specify the start and end time of the time interval to be processed and the delay between network snapshots.

[[File:Eventnet_dialog_iterator_KEDS.png]]

When the events have been created after filling out the event format tab (see the preceeding section) visone suggests as start time the time of the first event and as end time the time of the last event. If you don't want to process the whole event sequence you can increase the start time and/or decrease the end time. After clicking on the upper '''Apply / get info''' button, visone informs you about the number of events and time units in the specified subsequence. You might just take all events by not changing the interval borders; this includes all events from April 15, 1979 to March 31, 1999 - as can be seen in the dialog.

Then you have to choose the time points when a network snapshot is to be created by specifying the delay between snapshots. You can see in the dialog that the event sequence spans more than 7,200 time units (i.e., days with the current settings) which is almost 20 years. The number of snapshots must be small (some 10 or 20 snapshots are ok), since they are all opened in a new tab in visone. When we want to create a snapshot once a year we specify ''create snapshots after every'' '''365''' ''time unit(s)''. (The number of snapshots is then 20.) visone always creates one snapshot at the end of the event sequence - even if the waiting time is less than the specified number.

=== Event network ===

The tab to specify the event network is the most important one - here you define which '''link attributes''' of the event network summarize the past events, how events of various types add to these attributes, and how they change over time.

[[File:Eventnet_dialog_network_KEDS.png]]

The first thing to do is to decide on the link attributes. Here you are free to choose any attribute name (that makes it easy to remember the intuition of the attribute). Furthermore, a halftime - defining how fast attributes decay over time - has to be specified. The halftime has the following effect: when a particular link attribute on a particular dyad (pair or actors) has a value of <math>x</math> at time <math>t</math>, then (if no event on the same dyad happens in between) the value is <math>x/2</math> at time
<math>t+halftime</math>. Intuitively, link attributes with a positive halftime capture ''recent interaction''; if the halftime gets shorter then they capture even more recent interaction. A halftime equal to zero or negative indicates that the respective attribute does not decay over time; these attributes capture ''past interaction'' irrespective of the elapsed time.

In our concrete example we choose the following link attributes that all have a halftime of (approximately) one year.
* An attribute '''cooperation''' sums up the weights of past cooperative events.
* The link attribute '''conflict''' is similar and sums up past conflictive events. This attribute will also be non-negative; that is, a higher value means more past/recent conflict. (See later how this is achieved.)
* '''Interaction''' sums up the strength of past events - irrespective of whether these are cooperative or conflictive.
* '''Interaction (unweighted)''' sums up the number of past events - irrespective of whether these are cooperative or conflictive and irrespective of their weight.
* Finally '''cooperation-conflict''' sums up the (positive) weights of cooperative events and the (negative) weights of conflictive events. This attribute is positive on dyads that have more cooperative events (or cooperative events with higher weights) and it is negative on dyads on which there are more conflictive events (or more serious conflictive events).

When the link attributes are added (e.g., click on the '''Add / update all''' button) you have to specify how the events contribute to them. Clicking on '''Create weight-function table''' builds a table that has one row for each link attribute and one column for each event type. In the cell indexed by an attribute <math>attr</math> and an event type <math>t</math> you specify the function mapping weights of events of type <math>t</math> to increments of the link attribute <math>attr</math>. In our example, selecting the function ''Identity'' in the cell indexed by attribute ''cooperation'' and event type ''cooperation'' means that whenever an event of type ''cooperation'' and weight <math>w</math> happens then you add <math>w</math> to the current value of the ''cooperation'' attribute. If we had chosen ''SquareRoot'' as the weight function in the same cell, then we would add <math>\sqrt{w}</math> to the ''cooperation'' attribute whenever an event of type ''cooperation'' and weight <math>w</math> happens. The weight-function identifier ''N/A'' means that events of that type do not cause any change of the respective attribute. For instance, events of type ''conflict'' do not change the attribute ''cooperation''. Note that for the attribute ''conflict'' and the type ''conflict'' we choose the weight function ''MinusIdentity''; thus, when a conflictive event with weight -10 happens we add the (positive) value 10 to the attribute ''conflict'' (thereby the ''conflict'' attribute is always non-negative and higher values indicate more past conflicts). The settings for all attributes and types can be seen in the above image.

After these settings have been done you can create the snapshots by clicking on the button '''Process event network!'''. If you want to create a statistics table you first have to fill out the tab number 4. We turn to the statistics [[#Event_statistics|later]] and create the snapshots now.

== Visualization and analysis of event networks ==

With the above settings visone opens 20 network tabs. The nodes in the network have an attribute ''label'' that holds the names of the source or target nodes as they are given in the event list file. The links have (in our example) five numerical attributes encoding the values of the link attribute functions at the time of the snapshot. These link attributes allow to compute, for instance, the total amount of conflict or cooperation received or initialized by the actors (compute the indegree respectively outdegree with link strength set to ''conflict'' or ''cooperation'' or any other link attribute). These degrees can, for instance, be used for visual filtering by [[Visualization_tab|mapping]] the centrality values to size or color of the nodes or selecting nodes by importance. Examples for visualization of event networks can be found in the [[Wikipedia_edit_networks_(tutorial)|tutorial on Wikipedia edit networks]]. Note that all analysis and visualization tasks can be done in parallel for all open network tabs and note that visone also offers to compute a [[Visualization_tab#dynamic_layout|dynamic layout]] that can be animated; this is illustrated in the [[Collections_(tutorial)|tutorial on network collections]]. The image below is an example placing the most involved actors in the center of the drawing and coding rather cooperative ties in blue and rather conflictive ties in red.

[[File:Event_network_gulf_example.png|800px]]

== Statistical modeling of the conditional event type or weight ==

While importing event networks it is possible to compute and save network statistics associated with dyadic events that can be used to build and estimate a statistical model for the '''conditional event type'''. Such models have been proposed in Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders (2009): [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. These models can be used to test whether the network of past events explains the likelihood that future events among a given pair of actors are rather cooperative or rather conflictive, for instance
* Do actors have a tendency to fight those that attacked them in the past? (Tendency to retalliate.)
* Do actors have a tendency to cooperated with the enemies of their enemies, to fight the friends of their enemies, etc?

The event network statistics can be computed during importing the data, are saved in a file, and can then be analyzed with any statistical software, such as [http://www.r-project.org/ '''R'''].

It is important to understand that with the statistics table computed by visone you can estimate a model for the '''conditional''' event type, given that an event happens, as this has been defined in Brandes et al.(2009). With the visone output you cannot model the likelihood that two actors interact at all. (Such models can be specified and fitted, for instance, with the R package [http://cran.r-project.org/web/packages/relevent/index.html '''relevent'''] or with the software [http://algo.uni-konstanz.de/software/eventnet/ '''event network analyzer (eventnet)'''], where in the latter you can choose whether or not to condition on the sources or targets or events.) More on the difference between modeling the conditional event type and the marginal (unconditional) event type can be found in the slides [[Media:Lerner_Sunbelt12.pdf|'''Modeling Frequency and Type of Interaction in Event Networks''' (.pdf)]].

To make the analysis comparable to the one presented in Brandes et al.(2009), we modify the link attributes in the event network tab slightly (see below). Specifically we set the halftime to 30 days and include only the attributes ''conflict'' and ''cooperation''. (The settings in the event format stay the same and in the event iterator tabs you may set the delay between snapshots to 7291 to create only one snapshot.)

[[File:Eventnet_dialog_network_KEDS30.png]]

=== Event statistics ===

The statistics to be computed are defined in the eventnet statistics tab of the import dialog (see below). You first have to specify whether a statistic table should be created at all; if yes an output file has to be chosen and one or more statistics have to be defined.

[[File:Eventnet_dialog_statistics_KEDS.png]]

The statistics are used to model events in the following way: whenever an event happens that is initiated by a '''source''' node and directed to a '''target''' node, then the dyad ''(source, target)'' is embedded in the network of past events, i.e., all events that happened before the current event. The event network statistics describe relevant aspects of this network of past events with respect to the specific dyad. visone offers three different types of statistics - dyad statistics, degree statistics, and triangle statistics - that can be varied with respect to edge direction and/or link attributes. After defining the statistics they have to be added to the event network by clicking on the '''Add / update''' button.

==== Dyad statistics ====

Dyad statistics encode aspects of the past events from ''source'' to ''target'' or in the other direction. That is the dyad statistics encode how ''source'' interacted with ''target'' in the past or how ''target'' interacted with ''source''. In our exmple we define four different dyad statistics that are obtained by switching the direction (''inertia'' if '''OUT'''-going events - from ''source'' to ''target'' - are considered and ''reciprocity'' if '''IN'''-coming events - from ''target'' to ''source'' - are considered) and the link attribute (''positive'' for past cooperation and ''negative'' for past conflict).

Intuitively, if actors tend to retalliate, then we expect that the ''negative reciprocity'' statistic is negatively related with the weight of the next event.

==== Degree statistics ====

Degree statistics summarize the past events around the dyad ''(source, target)'' by the weighted (out-/in-) degree of ''source'' or ''target''. The links can be weighted by any attribute. For instance, the ''neg_outdeg_source'' statistic adds up the values of the ''conflict'' attribute on all links starting at the ''source'' node (not only those that are directed to ''target'').

Intuitively, if actors that initiated a lot of conflictive events in the past tend to do so in the future, then we expect a negative relation between the ''neg_outdeg_source'' statistic and the weight of events.

==== Triangle statistics ====

Triangle statistics summarize the network of past events around the dyad ''(source, target)'' by typed and weighted indirect relations from ''source'' over any third node to ''target'' or the other way round. You can select the attributes for the links attached to ''source'' and to ''target'' and the direction which can be '''OUT''' (only out-going ties with respect to ''source''/''target''), '''IN''' (only in-coming ties), or '''SYM''' (adding up the attributes of out-going and in-coming ties).

For instance, the statistic ''enemy_of_friend'' iterates over all actors ''A'' in the network, multiplies the value of the ''cooperation'' attribute on links connecting ''source'' and ''A'' (in both directions) with the value of the ''conflict'' attribute on links connecting ''target'' and ''A'' (in both directions), adds up these products for all ''A'', and returns the square root of this sum. Intuitively, the value of the ''enemy_of_friend'' statistic on the dyad ''(source, target)'' is high if there are many other actors ''A'' that cooperated with ''source'' and were in conflict with ''target''; structural balance theory predicts that ''source'' is then more likely to fight ''target''.

==== Starting the computation ====

Once the output file and the statistics are specified, click on the '''Process event network!''' button. Snapshots are created as defined in the event iterator tab and statistics are computed as defined in the eventnet statistics tab.

'''Note''' that statistics associated with an event that happens at time ''t'' are only a function of events that happend earlier (strictly before ''t'') - and do not depend on events that happen in the same time unit.

The computed eventnet statistics file (''gulf_events_stats.csv'' in our example) is a table in CSV format in which each row corresponds to one event of the input file. The components of the event (source, target, time, type, and weight) are first repeated - followed by the values of all statistics.

Computing the statistics for all 300,000 events may take some five to ten minutes on a current standard laptop. Once the computation is finished you see the message ''processing successfull'' in the eventnet dialog. If you get an error message you might have a look at the visone [[Console|console]] where you can get more information.

=== Modeling the conditional event weight ===

The statistics file can now be analyzed with any statistical software - we describe the following for the [http://www.r-project.org R environment for statistical computing] (also see the visone tutorial on the [[R_console_(tutorial)|R console]]).

First set the R working directory to the directory where the statistics file is located, for instance
setwd("c:/juergen/projects/event_data/keds/Gulf/")
To read the file into a table and see some summary statistics type
eventnet.stats <- read.csv("gulf_events_stats.csv", sep=";")
summary(eventnet.stats)
We model only those events that are not self-loops (loops could have been removed already while preprocessing the input event list - these two procedures are not equivalent since in our case statistics are also functions of loops).
eventnet.stats <- eventnet.stats[as.character(eventnet.stats$SOURCE) != as.character(eventnet.stats$TARGET),]
summary(eventnet.stats)
A first very simple model is a linear model for the event weigth (from ''source'' to ''target'') - explained by the past conflictive events in the other direction (that is from ''target'' directed to the ''source'' node).
model.1 <- lm(WEIGHT ~ 1 + negative_reciprocity, data = eventnet.stats)
summary(model.1)
A summary of the estimated model yields (among others) the following output:
Coefficients:
Estimate Std. Error t value Pr(>|t|)
(Intercept) -5.730e-01 8.866e-03 -64.63 <2e-16 ***
negative_reciprocity -2.629e-03 2.829e-05 -92.92 <2e-16 ***
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
The interpretation is that there seems to be a habit of retalliation: if ''target'' has initiated conflictive events towards ''source'' then the weight of events from ''source'' to ''target'' has a tendency to be smaller (significantly negative coefficient for the ''negative_reciprocity'' statistic) meaning that the event type is drawn towards conflict. The value of the coefficient (about -0.003) seems to be very small. However this parameter summarizes the change in the event weight when ''negative_reciprocity'' increases by one. Typing
sd(eventnet.stats$negative_reciprocity)
we see that the standard deviation of this statistic is around 290 - meaning that the ''negative_reciprocity'' indicator typically varies in the hundreds.

A more complex model tests for structural balance effects, controlling for variation in degrees and direct past interaction. (This is the model taken from Brandes et al.(2009).)
model.2 <- lm(WEIGHT ~ 1 + positive_inertia + negative_inertia +
positive_reciprocity + negative_reciprocity +
pos_outdeg_source + neg_outdeg_source +
pos_indeg_source + neg_indeg_source +
pos_outdeg_target + neg_outdeg_target +
pos_indeg_target + neg_indeg_target +
friend_of_friend + friend_of_enemy +
enemy_of_friend + enemy_of_enemy,
data = eventnet.stats)
We get the following results.
Coefficients:
Estimate Std. Error t value Pr(>|t|)
(Intercept) -7.707e-01 1.127e-02 -68.371 < 2e-16 ***
positive_inertia 5.814e-03 2.723e-04 21.347 < 2e-16 ***
negative_inertia -2.145e-03 7.214e-05 -29.730 < 2e-16 ***
positive_reciprocity 3.071e-03 3.125e-04 9.827 < 2e-16 ***
negative_reciprocity -2.188e-03 8.175e-05 -26.768 < 2e-16 ***
pos_outdeg_source 1.391e-03 6.853e-05 20.295 < 2e-16 ***
neg_outdeg_source -2.426e-04 3.250e-05 -7.463 8.48e-14 ***
pos_indeg_source -6.058e-04 1.022e-04 -5.930 3.02e-09 ***
neg_indeg_source 1.028e-04 3.259e-05 3.153 0.001615 **
pos_outdeg_target 9.800e-04 7.372e-05 13.293 < 2e-16 ***
neg_outdeg_target 2.142e-05 3.192e-05 0.671 0.502180
pos_indeg_target -6.572e-04 9.495e-05 -6.922 4.48e-12 ***
neg_indeg_target 6.988e-05 3.051e-05 2.290 0.022014 *
friend_of_friend 1.884e-03 5.349e-04 3.523 0.000427 ***
friend_of_enemy -8.913e-04 2.912e-04 -3.061 0.002205 **
enemy_of_friend -1.308e-03 2.874e-04 -4.553 5.30e-06 ***
enemy_of_enemy -1.935e-04 1.532e-04 -1.263 0.206593
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
Among other results, this model provides evidence for some - but not all - hypotheses derived from structural balance theory: friends of friends tend to interact more cooperatively while friend of enemies as well as enemies of friends have a tendency to fight each other. On the other hand, the parameter associated with the ''enemy_of_enemy'' statistic is not significant. Note that the data set for fitting this model is different from the one taken in Brandes et al. (2009) since here we also included self-loops to compute the statistics (although events connecting an actor with itself have not been used when fitting the linear model).

Obviously, modeling the event type or event weight as a stochastic function of the event network statistics is not restricted to linear models. Furthermore, if the model should control for actor-level or dyad-level covariates (such as the population size of a country or an indicator for whether two countries have a common border), these can be merged into the statistics table after processing of the event network.

== References ==

* Carter T. Butts: [http://onlinelibrary.wiley.com/doi/10.1111/j.1467-9531.2008.00203.x/full '''A Relational event framework for social action''']. ''Sociological Methodology'' 38(1):155-200, 2008.
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.

Event networks (tutorial)

2018-06-18T11:25:02Z

Lerner:

[[File:Event_network_gulf_example.png|300px|thumb]]
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. Stated otherwise, relations like ''friendship'' have inertia (something has to happen to change them), while relational events mark time points of interaction.

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
* Carter T. Butts: [http://onlinelibrary.wiley.com/doi/10.1111/j.1467-9531.2008.00203.x/full '''A Relational event framework for social action''']. ''Sociological Methodology'' 38(1):155-200, 2008.
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.
and in other papers linked in the [[Event_networks_(tutorial)#References|references]].

The functionality for statistical analysis of event networks has been superseded by the [http://algo.uni-konstanz.de/software/eventnet/ '''event network analyzer (eventnet)''']. However, visone can still be used for visual analysis of event networks.

Please address questions and comments about this tutorial to me ([[User:Lerner|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 [http://eventdata.psu.edu/ 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|'''Penn State Event Data''']]. To follow the steps outlined in this tutorial you should download the file [[Media:Gulf_events_preprocessed.zip|Gulf_events_preprocessed.zip]].

Another specific application area for event networks - using different example data - is treated in the [[Wikipedia_edit_networks_(tutorial)|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|'''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.

[[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.

=== 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''). In our example, you can set the values as in the image below. The meaning of the five components is explained in the following.
*'''SOURCE''' The source actor is the one who initiates the event.
*'''TARGET''' The target actor is the one who receives the event.
*'''TIME''' The time denotes when the event happened. visone supports a wide range of time encodings - from numeric times to strings representing calendar date and time in more common or less common formats. Furthermore, a time unit can be specified that defines the precision of the time variable.
*'''TYPE''' The event type is a categorical variable specifying what happened. In our example, there are different choices for event types. One possibility is the rather coarse distinction between cooperative (positive) and conflictive (negative) events. The other possibility is to distinguish between all more than 100 different WEIS event types. An intermediate possibility (and that's what we are going to do in the following) is to use just the distinction between conflict and cooperation but to distinguish quantitatively between "strong" events and "weak" events by the event weight. For instance, the use of military force is counted more seriously than a warning - even though both are conflictive events.
*'''WEIGHT''' The event weight is a numeric variable quantifying the ''intensity'' of the event with respect to the event type (see the example above). For instance, ''military engagement'' has a weight of -10.0 while warnings have a weight of -3.0.

[[File:Eventnet_dialog_format_KEDS.png]]

After these five components have been chosen visone needs some information about the interpretation of time. 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 time of the KEDS events is given by the day. Thus, appropriate time units are '''DAY''' or coarser.

Note that the only required information are the columns containing the source and target - for the other components you can take default values (by selecting ''<implied>'' instead of a column header). The default value for the event type is the string ''EVENT'' (taking this default type means that there is no variation in event types - all have the same type); the default weight is equal to 1.0; the default event time is the row number in the input file (so that only the order of events is taken into account).

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.)

=== Event iterator ===

In the event iterator tab (see below) you have to specify the start and end time of the time interval to be processed and the delay between network snapshots.

[[File:Eventnet_dialog_iterator_KEDS.png]]

When the events have been created after filling out the event format tab (see the preceeding section) visone suggests as start time the time of the first event and as end time the time of the last event. If you don't want to process the whole event sequence you can increase the start time and/or decrease the end time. After clicking on the upper '''Apply / get info''' button, visone informs you about the number of events and time units in the specified subsequence. You might just take all events by not changing the interval borders; this includes all events from April 15, 1979 to March 31, 1999 - as can be seen in the dialog.

Then you have to choose the time points when a network snapshot is to be created by specifying the delay between snapshots. You can see in the dialog that the event sequence spans more than 7,200 time units (i.e., days with the current settings) which is almost 20 years. The number of snapshots must be small (some 10 or 20 snapshots are ok), since they are all opened in a new tab in visone. When we want to create a snapshot once a year we specify ''create snapshots after every'' '''365''' ''time unit(s)''. (The number of snapshots is then 20.) visone always creates one snapshot at the end of the event sequence - even if the waiting time is less than the specified number.

=== Event network ===

The tab to specify the event network is the most important one - here you define which '''link attributes''' of the event network summarize the past events, how events of various types add to these attributes, and how they change over time.

[[File:Eventnet_dialog_network_KEDS.png]]

The first thing to do is to decide on the link attributes. Here you are free to choose any attribute name (that makes it easy to remember the intuition of the attribute). Furthermore, a halftime - defining how fast attributes decay over time - has to be specified. The halftime has the following effect: when a particular link attribute on a particular dyad (pair or actors) has a value of <math>x</math> at time <math>t</math>, then (if no event on the same dyad happens in between) the value is <math>x/2</math> at time
<math>t+halftime</math>. Intuitively, link attributes with a positive halftime capture ''recent interaction''; if the halftime gets shorter then they capture even more recent interaction. A halftime equal to zero or negative indicates that the respective attribute does not decay over time; these attributes capture ''past interaction'' irrespective of the elapsed time.

In our concrete example we choose the following link attributes that all have a halftime of (approximately) one year.
* An attribute '''cooperation''' sums up the weights of past cooperative events.
* The link attribute '''conflict''' is similar and sums up past conflictive events. This attribute will also be non-negative; that is, a higher value means more past/recent conflict. (See later how this is achieved.)
* '''Interaction''' sums up the strength of past events - irrespective of whether these are cooperative or conflictive.
* '''Interaction (unweighted)''' sums up the number of past events - irrespective of whether these are cooperative or conflictive and irrespective of their weight.
* Finally '''cooperation-conflict''' sums up the (positive) weights of cooperative events and the (negative) weights of conflictive events. This attribute is positive on dyads that have more cooperative events (or cooperative events with higher weights) and it is negative on dyads on which there are more conflictive events (or more serious conflictive events).

When the link attributes are added (e.g., click on the '''Add / update all''' button) you have to specify how the events contribute to them. Clicking on '''Create weight-function table''' builds a table that has one row for each link attribute and one column for each event type. In the cell indexed by an attribute <math>attr</math> and an event type <math>t</math> you specify the function mapping weights of events of type <math>t</math> to increments of the link attribute <math>attr</math>. In our example, selecting the function ''Identity'' in the cell indexed by attribute ''cooperation'' and event type ''cooperation'' means that whenever an event of type ''cooperation'' and weight <math>w</math> happens then you add <math>w</math> to the current value of the ''cooperation'' attribute. If we had chosen ''SquareRoot'' as the weight function in the same cell, then we would add <math>\sqrt{w}</math> to the ''cooperation'' attribute whenever an event of type ''cooperation'' and weight <math>w</math> happens. The weight-function identifier ''N/A'' means that events of that type do not cause any change of the respective attribute. For instance, events of type ''conflict'' do not change the attribute ''cooperation''. Note that for the attribute ''conflict'' and the type ''conflict'' we choose the weight function ''MinusIdentity''; thus, when a conflictive event with weight -10 happens we add the (positive) value 10 to the attribute ''conflict'' (thereby the ''conflict'' attribute is always non-negative and higher values indicate more past conflicts). The settings for all attributes and types can be seen in the above image.

After these settings have been done you can create the snapshots by clicking on the button '''Process event network!'''. If you want to create a statistics table you first have to fill out the tab number 4. We turn to the statistics [[#Event_statistics|later]] and create the snapshots now.

== Visualization and analysis of event networks ==

With the above settings visone opens 20 network tabs. The nodes in the network have an attribute ''label'' that holds the names of the source or target nodes as they are given in the event list file. The links have (in our example) five numerical attributes encoding the values of the link attribute functions at the time of the snapshot. These link attributes allow to compute, for instance, the total amount of conflict or cooperation received or initialized by the actors (compute the indegree respectively outdegree with link strength set to ''conflict'' or ''cooperation'' or any other link attribute). These degrees can, for instance, be used for visual filtering by [[Visualization_tab|mapping]] the centrality values to size or color of the nodes or selecting nodes by importance. Examples for visualization of event networks can be found in the [[Wikipedia_edit_networks_(tutorial)|tutorial on Wikipedia edit networks]]. Note that all analysis and visualization tasks can be done in parallel for all open network tabs and note that visone also offers to compute a [[Visualization_tab#dynamic_layout|dynamic layout]] that can be animated; this is illustrated in the [[Collections_(tutorial)|tutorial on network collections]]. The image below is an example placing the most involved actors in the center of the drawing and coding rather cooperative ties in blue and rather conflictive ties in red.

[[File:Event_network_gulf_example.png|800px]]

== Statistical modeling of the conditional event type or weight ==

While importing event networks it is possible to compute and save network statistics associated with dyadic events that can be used to build and estimate a statistical model for the '''conditional event type'''. Such models have been proposed in Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders (2009): [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. These models can be used to test whether the network of past events explains the likelihood that future events among a given pair of actors are rather cooperative or rather conflictive, for instance
* Do actors have a tendency to fight those that attacked them in the past? (Tendency to retalliate.)
* Do actors have a tendency to cooperated with the enemies of their enemies, to fight the friends of their enemies, etc?

The event network statistics can be computed during importing the data, are saved in a file, and can then be analyzed with any statistical software, such as [http://www.r-project.org/ '''R'''].

It is important to understand that with the statistics table computed by visone you can estimate a model for the '''conditional''' event type, given that an event happens, as this has been defined in Brandes et al.(2009). With the visone output you cannot model the likelihood that two actors interact at all. (Such models can be specified and fitted, for instance, with the R package [http://cran.r-project.org/web/packages/relevent/index.html '''relevent'''].) More on the difference between modeling the conditional event type and the marginal (unconditional) event type can be found in the slides [[Media:Lerner_Sunbelt12.pdf|'''Modeling Frequency and Type of Interaction in Event Networks''' (.pdf)]].

To make the analysis comparable to the one presented in Brandes et al.(2009), we modify the link attributes in the event network tab slightly (see below). Specifically we set the halftime to 30 days and include only the attributes ''conflict'' and ''cooperation''. (The settings in the event format stay the same and in the event iterator tabs you may set the delay between snapshots to 7291 to create only one snapshot.)

[[File:Eventnet_dialog_network_KEDS30.png]]

=== Event statistics ===

The statistics to be computed are defined in the eventnet statistics tab of the import dialog (see below). You first have to specify whether a statistic table should be created at all; if yes an output file has to be chosen and one or more statistics have to be defined.

[[File:Eventnet_dialog_statistics_KEDS.png]]

The statistics are used to model events in the following way: whenever an event happens that is initiated by a '''source''' node and directed to a '''target''' node, then the dyad ''(source, target)'' is embedded in the network of past events, i.e., all events that happened before the current event. The event network statistics describe relevant aspects of this network of past events with respect to the specific dyad. visone offers three different types of statistics - dyad statistics, degree statistics, and triangle statistics - that can be varied with respect to edge direction and/or link attributes. After defining the statistics they have to be added to the event network by clicking on the '''Add / update''' button.

==== Dyad statistics ====

Dyad statistics encode aspects of the past events from ''source'' to ''target'' or in the other direction. That is the dyad statistics encode how ''source'' interacted with ''target'' in the past or how ''target'' interacted with ''source''. In our exmple we define four different dyad statistics that are obtained by switching the direction (''inertia'' if '''OUT'''-going events - from ''source'' to ''target'' - are considered and ''reciprocity'' if '''IN'''-coming events - from ''target'' to ''source'' - are considered) and the link attribute (''positive'' for past cooperation and ''negative'' for past conflict).

Intuitively, if actors tend to retalliate, then we expect that the ''negative reciprocity'' statistic is negatively related with the weight of the next event.

==== Degree statistics ====

Degree statistics summarize the past events around the dyad ''(source, target)'' by the weighted (out-/in-) degree of ''source'' or ''target''. The links can be weighted by any attribute. For instance, the ''neg_outdeg_source'' statistic adds up the values of the ''conflict'' attribute on all links starting at the ''source'' node (not only those that are directed to ''target'').

Intuitively, if actors that initiated a lot of conflictive events in the past tend to do so in the future, then we expect a negative relation between the ''neg_outdeg_source'' statistic and the weight of events.

==== Triangle statistics ====

Triangle statistics summarize the network of past events around the dyad ''(source, target)'' by typed and weighted indirect relations from ''source'' over any third node to ''target'' or the other way round. You can select the attributes for the links attached to ''source'' and to ''target'' and the direction which can be '''OUT''' (only out-going ties with respect to ''source''/''target''), '''IN''' (only in-coming ties), or '''SYM''' (adding up the attributes of out-going and in-coming ties).

For instance, the statistic ''enemy_of_friend'' iterates over all actors ''A'' in the network, multiplies the value of the ''cooperation'' attribute on links connecting ''source'' and ''A'' (in both directions) with the value of the ''conflict'' attribute on links connecting ''target'' and ''A'' (in both directions), adds up these products for all ''A'', and returns the square root of this sum. Intuitively, the value of the ''enemy_of_friend'' statistic on the dyad ''(source, target)'' is high if there are many other actors ''A'' that cooperated with ''source'' and were in conflict with ''target''; structural balance theory predicts that ''source'' is then more likely to fight ''target''.

==== Starting the computation ====

Once the output file and the statistics are specified, click on the '''Process event network!''' button. Snapshots are created as defined in the event iterator tab and statistics are computed as defined in the eventnet statistics tab.

'''Note''' that statistics associated with an event that happens at time ''t'' are only a function of events that happend earlier (strictly before ''t'') - and do not depend on events that happen in the same time unit.

The computed eventnet statistics file (''gulf_events_stats.csv'' in our example) is a table in CSV format in which each row corresponds to one event of the input file. The components of the event (source, target, time, type, and weight) are first repeated - followed by the values of all statistics.

Computing the statistics for all 300,000 events may take some five to ten minutes on a current standard laptop. Once the computation is finished you see the message ''processing successfull'' in the eventnet dialog. If you get an error message you might have a look at the visone [[Console|console]] where you can get more information.

=== Modeling the conditional event weight ===

The statistics file can now be analyzed with any statistical software - we describe the following for the [http://www.r-project.org R environment for statistical computing] (also see the visone tutorial on the [[R_console_(tutorial)|R console]]).

First set the R working directory to the directory where the statistics file is located, for instance
setwd("c:/juergen/projects/event_data/keds/Gulf/")
To read the file into a table and see some summary statistics type
eventnet.stats <- read.csv("gulf_events_stats.csv", sep=";")
summary(eventnet.stats)
We model only those events that are not self-loops (loops could have been removed already while preprocessing the input event list - these two procedures are not equivalent since in our case statistics are also functions of loops).
eventnet.stats <- eventnet.stats[as.character(eventnet.stats$SOURCE) != as.character(eventnet.stats$TARGET),]
summary(eventnet.stats)
A first very simple model is a linear model for the event weigth (from ''source'' to ''target'') - explained by the past conflictive events in the other direction (that is from ''target'' directed to the ''source'' node).
model.1 <- lm(WEIGHT ~ 1 + negative_reciprocity, data = eventnet.stats)
summary(model.1)
A summary of the estimated model yields (among others) the following output:
Coefficients:
Estimate Std. Error t value Pr(>|t|)
(Intercept) -5.730e-01 8.866e-03 -64.63 <2e-16 ***
negative_reciprocity -2.629e-03 2.829e-05 -92.92 <2e-16 ***
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
The interpretation is that there seems to be a habit of retalliation: if ''target'' has initiated conflictive events towards ''source'' then the weight of events from ''source'' to ''target'' has a tendency to be smaller (significantly negative coefficient for the ''negative_reciprocity'' statistic) meaning that the event type is drawn towards conflict. The value of the coefficient (about -0.003) seems to be very small. However this parameter summarizes the change in the event weight when ''negative_reciprocity'' increases by one. Typing
sd(eventnet.stats$negative_reciprocity)
we see that the standard deviation of this statistic is around 290 - meaning that the ''negative_reciprocity'' indicator typically varies in the hundreds.

A more complex model tests for structural balance effects, controlling for variation in degrees and direct past interaction. (This is the model taken from Brandes et al.(2009).)
model.2 <- lm(WEIGHT ~ 1 + positive_inertia + negative_inertia +
positive_reciprocity + negative_reciprocity +
pos_outdeg_source + neg_outdeg_source +
pos_indeg_source + neg_indeg_source +
pos_outdeg_target + neg_outdeg_target +
pos_indeg_target + neg_indeg_target +
friend_of_friend + friend_of_enemy +
enemy_of_friend + enemy_of_enemy,
data = eventnet.stats)
We get the following results.
Coefficients:
Estimate Std. Error t value Pr(>|t|)
(Intercept) -7.707e-01 1.127e-02 -68.371 < 2e-16 ***
positive_inertia 5.814e-03 2.723e-04 21.347 < 2e-16 ***
negative_inertia -2.145e-03 7.214e-05 -29.730 < 2e-16 ***
positive_reciprocity 3.071e-03 3.125e-04 9.827 < 2e-16 ***
negative_reciprocity -2.188e-03 8.175e-05 -26.768 < 2e-16 ***
pos_outdeg_source 1.391e-03 6.853e-05 20.295 < 2e-16 ***
neg_outdeg_source -2.426e-04 3.250e-05 -7.463 8.48e-14 ***
pos_indeg_source -6.058e-04 1.022e-04 -5.930 3.02e-09 ***
neg_indeg_source 1.028e-04 3.259e-05 3.153 0.001615 **
pos_outdeg_target 9.800e-04 7.372e-05 13.293 < 2e-16 ***
neg_outdeg_target 2.142e-05 3.192e-05 0.671 0.502180
pos_indeg_target -6.572e-04 9.495e-05 -6.922 4.48e-12 ***
neg_indeg_target 6.988e-05 3.051e-05 2.290 0.022014 *
friend_of_friend 1.884e-03 5.349e-04 3.523 0.000427 ***
friend_of_enemy -8.913e-04 2.912e-04 -3.061 0.002205 **
enemy_of_friend -1.308e-03 2.874e-04 -4.553 5.30e-06 ***
enemy_of_enemy -1.935e-04 1.532e-04 -1.263 0.206593
---
Signif. codes: 0 ‘***’ 0.001 ‘**’ 0.01 ‘*’ 0.05 ‘.’ 0.1 ‘ ’ 1
Among other results, this model provides evidence for some - but not all - hypotheses derived from structural balance theory: friends of friends tend to interact more cooperatively while friend of enemies as well as enemies of friends have a tendency to fight each other. On the other hand, the parameter associated with the ''enemy_of_enemy'' statistic is not significant. Note that the data set for fitting this model is different from the one taken in Brandes et al. (2009) since here we also included self-loops to compute the statistics (although events connecting an actor with itself have not been used when fitting the linear model).

Obviously, modeling the event type or event weight as a stochastic function of the event network statistics is not restricted to linear models. Furthermore, if the model should control for actor-level or dyad-level covariates (such as the population size of a country or an indicator for whether two countries have a common border), these can be merged into the statistics table after processing of the event network.

== References ==

* Carter T. Butts: [http://onlinelibrary.wiley.com/doi/10.1111/j.1467-9531.2008.00203.x/full '''A Relational event framework for social action''']. ''Sociological Methodology'' 38(1):155-200, 2008.
* Ulrik Brandes, Jürgen Lerner, and Tom A. B. Snijders: [http://www.inf.uni-konstanz.de/algo/publications/bls-ness-09.pdf '''Networks Evolving Step by Step: Statistical Analysis of Dyadic Event Data''']. Proc. 2009 Intl. Conf. Advances in Social Network Analysis and Mining (ASONAM 2009), pp.200-205. IEEE Computer Society, 2009.

POLNET (data)

2018-06-18T11:06:42Z

Lerner:

The following ZIP file contains exemplary data used in introductory visone workshops.

[[Media:Visone_data.zip|'''Visone_data.zip''']] (1.36 MB)

Note that visone cannot directly load data from ZIP files. So you should extract (''unzip'') the files on your computer before opening them in visone.

In addition, you should [http://visone.info/html/download.html '''download'''] the current version of visone and (as a test) execute it as it is described in the very first sentence of the [[Installation_(tutorial)|installation tutorial]].

The following online tutorials repeat or extend content of the visone session at POLNET+

* [[Visualization_and_analysis_(tutorial)|'''Visualization and analysis''']]
* [[Personal_networks_(tutorial)|'''Personal networks''']]
* [[Collections_(tutorial)|'''Collections''']]

POLNET (data)

2018-06-18T10:59:10Z

Lerner: Created page with "The following ZIP file contains exemplary data used in introductory visone workshops. (Right-click and choose ''save link as'' to download.) [[Media:Visone_data.zip|'''Visone_da..."

The following ZIP file contains exemplary data used in introductory visone workshops. (Right-click and choose ''save link as'' to download.)

[[Media:Visone_data.zip|'''Visone_data.zip''']] (1.36 MB)

Note that visone cannot directly load data from ZIP files. So you should extract (''unzip'') the files on your computer before opening them in visone.

In addition, you should [http://visone.info/html/download.html '''download'''] the current version of visone and (as a test) execute it as it is described in the very first sentence of the [[Installation_(tutorial)|installation tutorial]].

File:Visone data.zip

2018-06-18T10:56:34Z

Lerner: uploaded a new version of "File:Visone data.zip"

Applications

2018-06-18T10:54:04Z

Lerner: /* Workshop data */

On this page we list datasets on which the usage of visone can be illustrated.

== Empirical datasets ==

* [[Egoredes_(data)|'''Egoredes''' acculturation networks]]: personal networks of immigrants
* [[Signos_(data)|'''Signos''']] newer and more comprehensive data about personal networks of immigrants than the Egoredes data above
* [[Newcomb_Fraternity_(data)|'''Newcomb Fraternity Data''']]
* [[Knecht_Classroom_(data)|'''Knecht Classroom Data''']]: four observations of a classroom friendship network
* [[Penn State Event Data|'''Penn State Event Data''']]: event data about political conflict and cooperation (formerly ''Kansas Event Data System (KEDS)'')

== Workshop data ==

* [[POLNET_(data)|'''Data for POLNET+ visone session''']]

* [[Sunbelt_workshop_(data)|'''Data for Sunbelt XXXIII (2013) visone workshop''']]

* [[Introductory_workshop_(data)|'''Data for ASNA 2011 workshop''']]

== Synthetic datasets ==

* [[Hairball_Graphs_(data)| '''Hairball Graphs''']]: 50 synthetic hairball graphs with a hidden group structure

== Auxiliary software ==

* [[EgoNet2GraphML_(software)|EgoNet2GraphML]] can (1) convert EgoNet interviews into GraphML files (that can be opened with visone) and (2) cluster, aggregate, and visualize collections of personal networks using the methodology proposed in: Ulrik Brandes, Juergen Lerner, Miranda J. Lubbers, Chris McCarty, and Jose Luis Molina '''"Visual Statistics for Collections of Clustered Graphs"'''. ''Proc. IEEE Pacific Visualization Symp. (PacificVis'08)'', 2008 ([http://www.inf.uni-konstanz.de/algo/publications/bllmm-vsccg-08.pdf ''link to pdf'']).
* [[WikiEvent_(software)|'''WikiEvent''']] is a small graphical java software with which the '''''edit network''''' associated with the history of [http://www.wikipedia.org Wikipedia] pages can be computed. See the [[Wikipedia_edit_networks_(tutorial)| tutorial on Wikipedia edit networks]].

User:Lerner

2018-04-30T07:49:20Z

Lerner:

'''Jürgen Lerner'''

You can reach me at [mailto:juergen.lerner@gmail.com juergen.lerner@gmail.com].

My homepage [http://algo.uni-konstanz.de/members/lerner/ http://algo.uni-konstanz.de/members/lerner/].

File:Attribute manager import.png

2015-03-30T06:23:29Z

Lerner: uploaded a new version of "File:Attribute manager import.png"

NLP Tab

2014-05-21T08:59:47Z

Lerner: Redirected page to NLP tab

#REDIRECT [[NLP tab]]

Links menu

2014-03-19T15:17:03Z

Lerner: /* selection... */

== deletion ==

=== delete links ===

deletes all selected links

=== delete loops ===

deletes all links from nodes to themselves within existing current selection or globally otherwise

=== delete bends ===

deletes all link bends within existing current selection or globally otherwise

== selection ==

=== select all ===

adds all links to selection

=== deselect all ===

removes all links from selection

=== invert selection ===

removes all links from selection and adds those that had not been selected before

== appearance ==

=== templates... ===

opens the [[link templates dialog]]

=== properties... ===

opens the [[link properties dialog]]

Nodes menu

2014-03-19T15:16:11Z

Lerner: /* selection... */

== deletion ==

=== delete nodes ===

deletes all selected nodes

=== delete isolates ===

deletes all nodes without incident links within existing current selection or globally otherwise

== selection ==

=== select all ===

adds all nodes to selection

=== deselect all ===

removes all nodes from selection

=== invert selection ===

removes all nodes from selection and adds those that had not been selected before

=== select groups ===

adds all [[groups]] to selection

== appearance ==

=== templates... ===

opens the [[node templates dialog]]

=== properties... ===

opens the [[node properties dialog]]

Attribute manager

2014-03-19T15:14:09Z

Lerner: /* Import & export */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

The category '''select''' allows you to select all elements that have a specified value in a given attribute.

[[File:Attribute_manager_select.png]]

The drop-down menu right of ''attribute'' is used to choose the attribute that should define the selection. The table below then shows all different values of that attribute and the number of elements that have these values. Clicking on one or several (keep the Control key pressed) rows in this table selects all these elements.

Note that the category [[#Filter|filter]] offers much more powerful ways to select elements dependent on attributes.

== Configure ==

The '''configure''' category allows you to create or delete attribute functions or to change meta information such as name, type (range of values), default value, and description.

[[File:Attribute_manager_configure.png]]

To create a new attribute click on the '''create attribute''' button (which adds a new row to the table above) and specify the attributes meta information:
* check mark '''label''': the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* '''name''': enables the (re-)definition of attribute names; choose a short but intuitive name here that indicates the semantics of the attribute
* '''type''': defines the type that is the range of values of the attribute; this can be (text, binary, integer, decimal, text list, integer list, decimal list)
* '''default''': can be used to define a default value for those elements that have no value assigned
* '''description''': a human-readable and potentially long description of what is encoded by the attribute
When all this information is specified, you have to click on the '''apply''' button to actually create the attribute.

You can also change the meta information for attributes that are already defined for the network. Attributes can be deleted by checking the box '''delete''' in the rightmost column.

All these changes can be done only for the current network (choose '''this network''' in the drop-down menu) or for all '''open networks'''.

'''Note''' that whenever some attribute is scheduled for creation or deletion or some of its meta information has been changed, you have to click on the '''apply''' button at the bottom of the attribute manager to execute these changes.

== Manipulate ==

The '''manipulate''' category provides powerful means to apply automatic transformations to one or several attributes. One example is provided in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

[[File:Attribute_manager_manipulate.png]]

In the first drop-down menu you specify the type of manipulation

You can '''copy''' an existing attribute and all its values to an already existing attribute (if you want to overwrite this) or provide a new name of the ''result attribute'' (if you just want to create a copy that you might modify later without loosing the original information).

You can '''rank''' the elements with respect to any numerical attribute that is already in the network.

'''Merge to list''' enables you to concatenate the values of two or more existing attriubtes (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) into a comma separated list of these values.

Conversely, there are a number of possibilities to '''convert list values''', namely calculating their '''maximum''', '''minimum''', '''average''', or '''sum''', count the number of elements, number of distinct elements, or '''concatenate''' them.

Finally, '''manipulate values''' provides means to apply certain functions to the values of one or several existing attributes, among others
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''add attributes'''
* '''scale''' with a specified ''scalar''
* '''multiply attributes'''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
* apply square (roots) or logarithms, etc.
While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

Category '''filter''' can be used to select elements dependent on attribute values, graphical values, incidence to selected links, adjacency to selected nodes, or combinations thereof. It is much more powerful than attribute management category '''select'''.

[[File:Attribute_manager_filter.png]]

Each row in the central area defines one condition for the filter; an element gets only selected if it satisfies all conditions. The radio buttons at the bottom specify how the selection defined by the filter is combined with the current selection (if any):
*'''replace''' turns the selection defined by the filter into the current one (irrespective the previous selection)
*'''add''' builds the union of the filter's selection with the current one
*'''remove''' deselects those elements that match the filter from the current selection
*'''intersect''' selects only those elements that are in both the current selection and in the filter's selection

There are several possibilities to specify a condition (one row of the filter):
*'''attribute''' allows to select all elements that assume values in specified ranges (the choices are different for numerical attributes than for text attributes)
*'''position''' constraints the x-/y-positions of selected nodes
*'''color''', '''size''', and '''shape''' can further specify the graphics of nodes or links
*'''incidence''' allows to select the nodes that have incident links that are already selected
*'''adjacency''' requires that neighbors of the nodes have to be currently selected

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Data_input_(tutorial)|data input tutorial]]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

[[File:Attribute_manager_import.png]]

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

Attribute manager

2014-03-19T15:08:28Z

Lerner: /* Filter */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

The category '''select''' allows you to select all elements that have a specified value in a given attribute.

[[File:Attribute_manager_select.png]]

The drop-down menu right of ''attribute'' is used to choose the attribute that should define the selection. The table below then shows all different values of that attribute and the number of elements that have these values. Clicking on one or several (keep the Control key pressed) rows in this table selects all these elements.

Note that the category [[#Filter|filter]] offers much more powerful ways to select elements dependent on attributes.

== Configure ==

The '''configure''' category allows you to create or delete attribute functions or to change meta information such as name, type (range of values), default value, and description.

[[File:Attribute_manager_configure.png]]

To create a new attribute click on the '''create attribute''' button (which adds a new row to the table above) and specify the attributes meta information:
* check mark '''label''': the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* '''name''': enables the (re-)definition of attribute names; choose a short but intuitive name here that indicates the semantics of the attribute
* '''type''': defines the type that is the range of values of the attribute; this can be (text, binary, integer, decimal, text list, integer list, decimal list)
* '''default''': can be used to define a default value for those elements that have no value assigned
* '''description''': a human-readable and potentially long description of what is encoded by the attribute
When all this information is specified, you have to click on the '''apply''' button to actually create the attribute.

You can also change the meta information for attributes that are already defined for the network. Attributes can be deleted by checking the box '''delete''' in the rightmost column.

All these changes can be done only for the current network (choose '''this network''' in the drop-down menu) or for all '''open networks'''.

'''Note''' that whenever some attribute is scheduled for creation or deletion or some of its meta information has been changed, you have to click on the '''apply''' button at the bottom of the attribute manager to execute these changes.

== Manipulate ==

The '''manipulate''' category provides powerful means to apply automatic transformations to one or several attributes. One example is provided in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

[[File:Attribute_manager_manipulate.png]]

In the first drop-down menu you specify the type of manipulation

You can '''copy''' an existing attribute and all its values to an already existing attribute (if you want to overwrite this) or provide a new name of the ''result attribute'' (if you just want to create a copy that you might modify later without loosing the original information).

You can '''rank''' the elements with respect to any numerical attribute that is already in the network.

'''Merge to list''' enables you to concatenate the values of two or more existing attriubtes (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) into a comma separated list of these values.

Conversely, there are a number of possibilities to '''convert list values''', namely calculating their '''maximum''', '''minimum''', '''average''', or '''sum''', count the number of elements, number of distinct elements, or '''concatenate''' them.

Finally, '''manipulate values''' provides means to apply certain functions to the values of one or several existing attributes, among others
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''add attributes'''
* '''scale''' with a specified ''scalar''
* '''multiply attributes'''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
* apply square (roots) or logarithms, etc.
While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

Category '''filter''' can be used to select elements dependent on attribute values, graphical values, incidence to selected links, adjacency to selected nodes, or combinations thereof. It is much more powerful than attribute management category '''select'''.

[[File:Attribute_manager_filter.png]]

Each row in the central area defines one condition for the filter; an element gets only selected if it satisfies all conditions. The radio buttons at the bottom specify how the selection defined by the filter is combined with the current selection (if any):
*'''replace''' turns the selection defined by the filter into the current one (irrespective the previous selection)
*'''add''' builds the union of the filter's selection with the current one
*'''remove''' deselects those elements that match the filter from the current selection
*'''intersect''' selects only those elements that are in both the current selection and in the filter's selection

There are several possibilities to specify a condition (one row of the filter):
*'''attribute''' allows to select all elements that assume values in specified ranges (the choices are different for numerical attributes than for text attributes)
*'''position''' constraints the x-/y-positions of selected nodes
*'''color''', '''size''', and '''shape''' can further specify the graphics of nodes or links
*'''incidence''' allows to select the nodes that have incident links that are already selected
*'''adjacency''' requires that neighbors of the nodes have to be currently selected

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

Attribute manager

2014-03-19T15:07:42Z

Lerner: /* Filter */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

The category '''select''' allows you to select all elements that have a specified value in a given attribute.

[[File:Attribute_manager_select.png]]

The drop-down menu right of ''attribute'' is used to choose the attribute that should define the selection. The table below then shows all different values of that attribute and the number of elements that have these values. Clicking on one or several (keep the Control key pressed) rows in this table selects all these elements.

Note that the category [[#Filter|filter]] offers much more powerful ways to select elements dependent on attributes.

== Configure ==

The '''configure''' category allows you to create or delete attribute functions or to change meta information such as name, type (range of values), default value, and description.

[[File:Attribute_manager_configure.png]]

To create a new attribute click on the '''create attribute''' button (which adds a new row to the table above) and specify the attributes meta information:
* check mark '''label''': the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* '''name''': enables the (re-)definition of attribute names; choose a short but intuitive name here that indicates the semantics of the attribute
* '''type''': defines the type that is the range of values of the attribute; this can be (text, binary, integer, decimal, text list, integer list, decimal list)
* '''default''': can be used to define a default value for those elements that have no value assigned
* '''description''': a human-readable and potentially long description of what is encoded by the attribute
When all this information is specified, you have to click on the '''apply''' button to actually create the attribute.

You can also change the meta information for attributes that are already defined for the network. Attributes can be deleted by checking the box '''delete''' in the rightmost column.

All these changes can be done only for the current network (choose '''this network''' in the drop-down menu) or for all '''open networks'''.

'''Note''' that whenever some attribute is scheduled for creation or deletion or some of its meta information has been changed, you have to click on the '''apply''' button at the bottom of the attribute manager to execute these changes.

== Manipulate ==

The '''manipulate''' category provides powerful means to apply automatic transformations to one or several attributes. One example is provided in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

[[File:Attribute_manager_manipulate.png]]

In the first drop-down menu you specify the type of manipulation

You can '''copy''' an existing attribute and all its values to an already existing attribute (if you want to overwrite this) or provide a new name of the ''result attribute'' (if you just want to create a copy that you might modify later without loosing the original information).

You can '''rank''' the elements with respect to any numerical attribute that is already in the network.

'''Merge to list''' enables you to concatenate the values of two or more existing attriubtes (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) into a comma separated list of these values.

Conversely, there are a number of possibilities to '''convert list values''', namely calculating their '''maximum''', '''minimum''', '''average''', or '''sum''', count the number of elements, number of distinct elements, or '''concatenate''' them.

Finally, '''manipulate values''' provides means to apply certain functions to the values of one or several existing attributes, among others
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''add attributes'''
* '''scale''' with a specified ''scalar''
* '''multiply attributes'''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
* apply square (roots) or logarithms, etc.
While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

Category '''filter''' can be used to select elements dependent on attribute values, graphical values, incidence to selected links, adjacency to selected nodes, or combinations thereof. It is much more powerful than attribute management category '''select'''.

[[File:Attribute_manager_filter.png]]

Each row in the central area defines one condition for the filter; an element gets only selected if it satisfies all conditions. The checkmarks at the bottom specify how the selection defined by the filter is combined with the current selection (if any):
*'''replace''' turns the selection defined by the filter into the current one (irrespective the previous selection)
*'''add''' builds the union of the filter's selection with the current one
*'''remove''' deselects those elements that match the filter from the current selection
*'''intersect''' selects only those elements that are in both the current selection and in the filter's selection

There are several possibilities to specify a condition (one row of the filter):
*'''attribute''' allows to select all elements that assume values in specified ranges (the choices are different for numerical attributes than for text attributes)
*'''position''' constraints the x-/y-positions of selected nodes
*'''color''', '''size''', and '''shape''' can further specify the graphics of nodes or links
*'''incidence''' allows to select the nodes that have incident links that are already selected
*'''adjacency''' requires that neighbors of the nodes have to be currently selected

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

Attribute manager

2014-03-19T14:23:58Z

Lerner: /* Filter */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

The category '''select''' allows you to select all elements that have a specified value in a given attribute.

[[File:Attribute_manager_select.png]]

The drop-down menu right of ''attribute'' is used to choose the attribute that should define the selection. The table below then shows all different values of that attribute and the number of elements that have these values. Clicking on one or several (keep the Control key pressed) rows in this table selects all these elements.

Note that the category [[#Filter|filter]] offers much more powerful ways to select elements dependent on attributes.

== Configure ==

The '''configure''' category allows you to create or delete attribute functions or to change meta information such as name, type (range of values), default value, and description.

[[File:Attribute_manager_configure.png]]

To create a new attribute click on the '''create attribute''' button (which adds a new row to the table above) and specify the attributes meta information:
* check mark '''label''': the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* '''name''': enables the (re-)definition of attribute names; choose a short but intuitive name here that indicates the semantics of the attribute
* '''type''': defines the type that is the range of values of the attribute; this can be (text, binary, integer, decimal, text list, integer list, decimal list)
* '''default''': can be used to define a default value for those elements that have no value assigned
* '''description''': a human-readable and potentially long description of what is encoded by the attribute
When all this information is specified, you have to click on the '''apply''' button to actually create the attribute.

You can also change the meta information for attributes that are already defined for the network. Attributes can be deleted by checking the box '''delete''' in the rightmost column.

All these changes can be done only for the current network (choose '''this network''' in the drop-down menu) or for all '''open networks'''.

'''Note''' that whenever some attribute is scheduled for creation or deletion or some of its meta information has been changed, you have to click on the '''apply''' button at the bottom of the attribute manager to execute these changes.

== Manipulate ==

The '''manipulate''' category provides powerful means to apply automatic transformations to one or several attributes. One example is provided in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

[[File:Attribute_manager_manipulate.png]]

In the first drop-down menu you specify the type of manipulation

You can '''copy''' an existing attribute and all its values to an already existing attribute (if you want to overwrite this) or provide a new name of the ''result attribute'' (if you just want to create a copy that you might modify later without loosing the original information).

You can '''rank''' the elements with respect to any numerical attribute that is already in the network.

'''Merge to list''' enables you to concatenate the values of two or more existing attriubtes (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) into a comma separated list of these values.

Conversely, there are a number of possibilities to '''convert list values''', namely calculating their '''maximum''', '''minimum''', '''average''', or '''sum''', count the number of elements, number of distinct elements, or '''concatenate''' them.

Finally, '''manipulate values''' provides means to apply certain functions to the values of one or several existing attributes, among others
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''add attributes'''
* '''scale''' with a specified ''scalar''
* '''multiply attributes'''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
* apply square (roots) or logarithms, etc.
While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

Category '''filter''' can be used to select elements dependent on attribute values, graphical values, incidence to selected links, adjacency to selected nodes, or combinations thereof. It is much more powerful than attribute management category '''select'''.

[[File:Attribute_manager_filter.png]]

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

Attribute manager

2014-03-19T14:21:26Z

Lerner: /* Filter */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

The category '''select''' allows you to select all elements that have a specified value in a given attribute.

[[File:Attribute_manager_select.png]]

The drop-down menu right of ''attribute'' is used to choose the attribute that should define the selection. The table below then shows all different values of that attribute and the number of elements that have these values. Clicking on one or several (keep the Control key pressed) rows in this table selects all these elements.

Note that the category [[#Filter|filter]] offers much more powerful ways to select elements dependent on attributes.

== Configure ==

The '''configure''' category allows you to create or delete attribute functions or to change meta information such as name, type (range of values), default value, and description.

[[File:Attribute_manager_configure.png]]

To create a new attribute click on the '''create attribute''' button (which adds a new row to the table above) and specify the attributes meta information:
* check mark '''label''': the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* '''name''': enables the (re-)definition of attribute names; choose a short but intuitive name here that indicates the semantics of the attribute
* '''type''': defines the type that is the range of values of the attribute; this can be (text, binary, integer, decimal, text list, integer list, decimal list)
* '''default''': can be used to define a default value for those elements that have no value assigned
* '''description''': a human-readable and potentially long description of what is encoded by the attribute
When all this information is specified, you have to click on the '''apply''' button to actually create the attribute.

You can also change the meta information for attributes that are already defined for the network. Attributes can be deleted by checking the box '''delete''' in the rightmost column.

All these changes can be done only for the current network (choose '''this network''' in the drop-down menu) or for all '''open networks'''.

'''Note''' that whenever some attribute is scheduled for creation or deletion or some of its meta information has been changed, you have to click on the '''apply''' button at the bottom of the attribute manager to execute these changes.

== Manipulate ==

The '''manipulate''' category provides powerful means to apply automatic transformations to one or several attributes. One example is provided in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

[[File:Attribute_manager_manipulate.png]]

In the first drop-down menu you specify the type of manipulation

You can '''copy''' an existing attribute and all its values to an already existing attribute (if you want to overwrite this) or provide a new name of the ''result attribute'' (if you just want to create a copy that you might modify later without loosing the original information).

You can '''rank''' the elements with respect to any numerical attribute that is already in the network.

'''Merge to list''' enables you to concatenate the values of two or more existing attriubtes (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) into a comma separated list of these values.

Conversely, there are a number of possibilities to '''convert list values''', namely calculating their '''maximum''', '''minimum''', '''average''', or '''sum''', count the number of elements, number of distinct elements, or '''concatenate''' them.

Finally, '''manipulate values''' provides means to apply certain functions to the values of one or several existing attributes, among others
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''add attributes'''
* '''scale''' with a specified ''scalar''
* '''multiply attributes'''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
* apply square (roots) or logarithms, etc.
While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

[[File:Attribute_manager_filter.png]]

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

File:Attribute manager filter.png

2014-03-19T14:20:55Z

Lerner: uploaded "File:Attribute manager filter.png"

File:Attribute manager filter.png

2014-03-19T14:20:20Z

Lerner: Blanked the page

Managing attributes (tutorial)

2014-03-19T14:20:01Z

Lerner: /* Selecting and deleting links below a threshold */

This [[Tutorials|tutorial]] introduces you to the full power of visone's [[attribute manager]] and shows you how to select elements dependent on attribute values. The attribute manager allows you, for instance, to convert tie strength to distance or rankings and vice versa, dichotomize networks, rescale tie weights and much more.

This tutorial assumes that you have a basic understanding of how to analyze and visualize networks in visone - as it is illustrated, for instance, in the [[Visualization_and_analysis_(tutorial)|previous tutorial]].

== An exemplary dataset: Newcomb Fraternity Data ==

The '''Newcomb Fraternity Data''' (see ''Newcomb T. (1961). The acquaintance process. New York: Holt, Reinhard & Winston.'') consits of 15 matrices recording weekly sociometric preference rankings from 17 men attending the University of Michigan in the fall of 1956. Each participant ranks all 16 others from best friend down to least friend. This data set is explained in more detail on the page [[Newcomb Fraternity (data)]].

To follow the steps illustrated in this tutorial, you should download the file [[Media:Newfrat.zip|Newfrat.zip]] (ZIP file containing the 15 matrices ''newfrat01.csv'' to ''newfrat15.csv''), save it to your computer and decompress (''unzip'') it.

== Import the CSV files ==

We start by importing one of the adjacency matrices (e.g., ''newfrat01.csv'') into visone. Therefore use the menu '''file, open''' and select '''files of type''' ''adjacency matrix files (.txt, .csv)''. Before importing the file it is important to set the correct options; the images below show the [[import options dialog]].

[[File:Import_options_newfrat.png]]

[[File:Newfrat01.png|100px|thumb|right]] Setting the options as shown above and clicking on '''ok''' opens the network which looks like the one shown on the right.

It can be seen that the network is complete (i.e., each pair of actors is connected by a bidirectional tie. All links have an attribute called '''csv value''' whose value corresponds to the respective entry in the adjacency matrix and, thus, is equal to the '''rank''' of the target node in the ordered list of friends of the source node.

A more exhaustive treatment of how to import data into visone is given in the [[Data_input_(tutorial)|data input tutorial]].

== Who is the most popular? ==

For illustration, we want to explore the popularity of actors with respect to the aggregated nominations of all others. Clearly, the number of incomming ties would not be a good measure for this, since each node receives exactly 16 links. The information about how popular actors are lies in the ranking of the ties. In the extremal case it would be possible that one actor (the most popular one) receives 16 links having rank equal to 1 and another actor receives 16 links labeled 16 (i.e., this actor would be the least friend for all others).

There are several possibilities to turn the weighted nominations into a one-dimensional measure for popularity: dichotomizing the network by defining a threshold that separates between the "friends" and the "non-friends"; computing a weighted indegree that takes into account the link weights; or combinations of the two. Some of these possibilities are illustrated below.

== Selecting and deleting links below a threshold ==

[[File:Attribute_manager_rename.png|200px|thumb|right]] It is convenient to rename the attribute encoding the ranks, since '''csv value''' is not a very intuitive name. To do this open the [[attribute manager]], click the button '''link''' in the top row, and '''configure''' on the left. Click in the text field where it currently says '''csv value''' and write, for instance, '''rank''' into it; click on the '''apply''' button.

Exemplarily, we want to keep only links that go to the '''top-3 friends'''. To select all links with a rank higher than 3 (i.e., all links that we want to delete) click on the button '''filter''' on the left-hand side (still having selected '''link''' in the top row). In the row where you can define the filter, select '''attribute''', then '''rank''', check (''only'') the box before the greater than-sign ('''>'''), type '''3''' in the textfield. Select the radio button '''replace''' at the bottom and click on '''select'''

[[File:Attribute_manager_filter_rank.png]]

[[File:Newfrat01_top3.png|100px|thumb|right]] This should select 221 out of 272 links (this information can be found in the lower left corner of the visone window) that can now be deleted by clicking on the menu '''links, delete links''', or from the [[link context menu]]. Clicking on the [[Quick_layout|quick layout button]] should show a network like the one on the right. It can be seen from this image that nodes 16 and 10 seem to be quite popular.

== Status layouts ==

To state this more quantitiatively, we compute the nodes' '''indegree''' via the [[analysis tab]] (ignoring the tie weights by selecting '''link strength'''=''uniform'') and save it in an attribute ''indegree (unweighted)''. This node attribute encodes, thus, the number of times that the node has been nominated as best friend, 2nd best friend, or 3rd best friend.

[[File:Analysis_tab_indegree.png|330px]] [[File:Visualization_tab_status.png|500px]]

To visualize the relative values we use a [[status layout]] that can be computed via the [[visualization tab]] (set '''node value''' to the newly computed node attribute ''indegree (unweighted)'' as shown in the screen shot above).

== Transforming attributes ==

The unweighted indegree as computed above counts the number of times that the node has been nominated as 1st, 2nd, or 3rd best friend. To count nominations as best friend more than nominations as 2nd best friend, we can map these rankings to values and then compute the ''weighted'' indegrees. The rank values can not directly be taken as measures of tie strength since a higher rank (e.g., 3) indicates a lower friendship intensity than a lower rank (e.g., 1). Thus we have to apply an order-reversing mapping on the rank attribute. This can be done via the [[attribute manager]]. Note that the particular choice for the transformation below has been done arbitrarily and merely serves for illustrating how attributes can be transformed; when a particular research questions has to be answered one should be able to justify such a choice, or show that the particular choice of transformation does not influence the findings significantly.

[[File:Attribute_manager_reverse.png]]

In the [[attribute manager]] select the '''link''' button on the top and '''manipulate''' on the left. Selecting, from top to bottom, '''manipulate values''', '''reverse''', and '''rank''', giving a new name to the transformed attribute (such as '''rank reversed'''), and clicking the ''apply'' button adds the new attribute to all nodes. '''Reverse''' means that the interval of values gets reverted as specified by the formula

<math>reversedValue=maxValue+minValue-value</math>.

In our example, 1 is mapped to 3, 2 to 2, and 3 to 1. You might inspect the other possibilities for transforming attribute values; note that transformations that are not directly implemented in the attribute manager can be done via visone's [[R console tab|R console]] (see the [[R_console_(tutorial)#Loading_networks_from_R_into_visone|R console tutorial]] for illustration).

== Centrality and status on weighted networks ==

A weighted indegree, dependent on the newly computed attribute, can be computed via the [[analysis tab]] (similar to the unweighted indegree, but setting '''link strength''' to ''rank reversed''). Mapping this weighted indegree in a [[status layout]] reveals that actor 16 is more popular than 10 with respect to the weighted measure, but equally popular with respect to the unweighted indegree.

File:Attribute manager filter.png

2014-03-19T14:19:07Z

Lerner: moved File:Attribute manager filter.png to File:Attribute manager filter rank.png

#REDIRECT [[File:Attribute manager filter rank.png]]

File:Attribute manager filter rank.png

2014-03-19T14:19:06Z

Lerner: moved File:Attribute manager filter.png to File:Attribute manager filter rank.png

Attribute manager

2014-03-19T14:09:17Z

Lerner: /* grouped modifications */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

The category '''select''' allows you to select all elements that have a specified value in a given attribute.

[[File:Attribute_manager_select.png]]

The drop-down menu right of ''attribute'' is used to choose the attribute that should define the selection. The table below then shows all different values of that attribute and the number of elements that have these values. Clicking on one or several (keep the Control key pressed) rows in this table selects all these elements.

Note that the category [[#Filter|filter]] offers much more powerful ways to select elements dependent on attributes.

== Configure ==

The '''configure''' category allows you to create or delete attribute functions or to change meta information such as name, type (range of values), default value, and description.

[[File:Attribute_manager_configure.png]]

To create a new attribute click on the '''create attribute''' button (which adds a new row to the table above) and specify the attributes meta information:
* check mark '''label''': the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* '''name''': enables the (re-)definition of attribute names; choose a short but intuitive name here that indicates the semantics of the attribute
* '''type''': defines the type that is the range of values of the attribute; this can be (text, binary, integer, decimal, text list, integer list, decimal list)
* '''default''': can be used to define a default value for those elements that have no value assigned
* '''description''': a human-readable and potentially long description of what is encoded by the attribute
When all this information is specified, you have to click on the '''apply''' button to actually create the attribute.

You can also change the meta information for attributes that are already defined for the network. Attributes can be deleted by checking the box '''delete''' in the rightmost column.

All these changes can be done only for the current network (choose '''this network''' in the drop-down menu) or for all '''open networks'''.

'''Note''' that whenever some attribute is scheduled for creation or deletion or some of its meta information has been changed, you have to click on the '''apply''' button at the bottom of the attribute manager to execute these changes.

== Manipulate ==

The '''manipulate''' category provides powerful means to apply automatic transformations to one or several attributes. One example is provided in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

[[File:Attribute_manager_manipulate.png]]

In the first drop-down menu you specify the type of manipulation

You can '''copy''' an existing attribute and all its values to an already existing attribute (if you want to overwrite this) or provide a new name of the ''result attribute'' (if you just want to create a copy that you might modify later without loosing the original information).

You can '''rank''' the elements with respect to any numerical attribute that is already in the network.

'''Merge to list''' enables you to concatenate the values of two or more existing attriubtes (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) into a comma separated list of these values.

Conversely, there are a number of possibilities to '''convert list values''', namely calculating their '''maximum''', '''minimum''', '''average''', or '''sum''', count the number of elements, number of distinct elements, or '''concatenate''' them.

Finally, '''manipulate values''' provides means to apply certain functions to the values of one or several existing attributes, among others
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''add attributes'''
* '''scale''' with a specified ''scalar''
* '''multiply attributes'''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
* apply square (roots) or logarithms, etc.
While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

Attribute manager

2014-03-19T13:45:24Z

Lerner: /* Manipulate */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

The category '''select''' allows you to select all elements that have a specified value in a given attribute.

[[File:Attribute_manager_select.png]]

The drop-down menu right of ''attribute'' is used to choose the attribute that should define the selection. The table below then shows all different values of that attribute and the number of elements that have these values. Clicking on one or several (keep the Control key pressed) rows in this table selects all these elements.

Note that the category [[#Filter|filter]] offers much more powerful ways to select elements dependent on attributes.

== Configure ==

The '''configure''' category allows you to create or delete attribute functions or to change meta information such as name, type (range of values), default value, and description.

[[File:Attribute_manager_configure.png]]

To create a new attribute click on the '''create attribute''' button (which adds a new row to the table above) and specify the attributes meta information:
* check mark '''label''': the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* '''name''': enables the (re-)definition of attribute names; choose a short but intuitive name here that indicates the semantics of the attribute
* '''type''': defines the type that is the range of values of the attribute; this can be (text, binary, integer, decimal, text list, integer list, decimal list)
* '''default''': can be used to define a default value for those elements that have no value assigned
* '''description''': a human-readable and potentially long description of what is encoded by the attribute
When all this information is specified, you have to click on the '''apply''' button to actually create the attribute.

You can also change the meta information for attributes that are already defined for the network. Attributes can be deleted by checking the box '''delete''' in the rightmost column.

All these changes can be done only for the current network (choose '''this network''' in the drop-down menu) or for all '''open networks'''.

'''Note''' that whenever some attribute is scheduled for creation or deletion or some of its meta information has been changed, you have to click on the '''apply''' button at the bottom of the attribute manager to execute these changes.

== Manipulate ==

The '''manipulate''' category provides powerful means to apply automatic transformations to one or several attributes. One example is provided in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

[[File:Attribute_manager_manipulate.png]]

In the first drop-down menu you specify the type of manipulation

You can '''copy''' an existing attribute and all its values to an already existing attribute (if you want to overwrite this) or provide a new name of the ''result attribute'' (if you just want to create a copy that you might modify later without loosing the original information).

You can '''rank''' the elements with respect to any numerical attribute that is already in the network.

'''Merge to list''' enables you to concatenate the values of two or more existing attriubtes (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) into a comma separated list of these values.

Conversely, there are a number of possibilities to '''convert list values''', namely calculating their '''maximum''', '''minimum''', '''average''', or '''sum''', count the number of elements, number of distinct elements, or '''concatenate''' them.

Finally, '''manipulate values''' provides means to apply certain functions to the values of one or several existing attributes, among others
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''add attributes'''
* '''scale''' with a specified ''scalar''
* '''multiply attributes'''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
* apply square (roots) or logarithms, etc.
While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

== grouped modifications ==

=== operations ===

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

=== import and export ===

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

File:Attribute manager manipulate.png

2014-03-19T13:21:37Z

Lerner:

Attribute manager

2014-03-19T13:08:42Z

Lerner: /* Configure */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

The category '''select''' allows you to select all elements that have a specified value in a given attribute.

[[File:Attribute_manager_select.png]]

The drop-down menu right of ''attribute'' is used to choose the attribute that should define the selection. The table below then shows all different values of that attribute and the number of elements that have these values. Clicking on one or several (keep the Control key pressed) rows in this table selects all these elements.

Note that the category [[#Filter|filter]] offers much more powerful ways to select elements dependent on attributes.

== Configure ==

The '''configure''' category allows you to create or delete attribute functions or to change meta information such as name, type (range of values), default value, and description.

[[File:Attribute_manager_configure.png]]

To create a new attribute click on the '''create attribute''' button (which adds a new row to the table above) and specify the attributes meta information:
* check mark '''label''': the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* '''name''': enables the (re-)definition of attribute names; choose a short but intuitive name here that indicates the semantics of the attribute
* '''type''': defines the type that is the range of values of the attribute; this can be (text, binary, integer, decimal, text list, integer list, decimal list)
* '''default''': can be used to define a default value for those elements that have no value assigned
* '''description''': a human-readable and potentially long description of what is encoded by the attribute
When all this information is specified, you have to click on the '''apply''' button to actually create the attribute.

You can also change the meta information for attributes that are already defined for the network. Attributes can be deleted by checking the box '''delete''' in the rightmost column.

All these changes can be done only for the current network (choose '''this network''' in the drop-down menu) or for all '''open networks'''.

'''Note''' that whenever some attribute is scheduled for creation or deletion or some of its meta information has been changed, you have to click on the '''apply''' button at the bottom of the attribute manager to execute these changes.

== Manipulate ==

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

== grouped modifications ==

=== operations ===

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

=== import and export ===

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

File:Attribute manager configure.png

2014-03-19T12:51:08Z

Lerner:

Attribute manager

2014-03-19T12:46:51Z

Lerner: /* Select */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

The category '''select''' allows you to select all elements that have a specified value in a given attribute.

[[File:Attribute_manager_select.png]]

The drop-down menu right of ''attribute'' is used to choose the attribute that should define the selection. The table below then shows all different values of that attribute and the number of elements that have these values. Clicking on one or several (keep the Control key pressed) rows in this table selects all these elements.

Note that the category [[#Filter|filter]] offers much more powerful ways to select elements dependent on attributes.

== Configure ==

* check mark: the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* name field: enables the (re-)definition of attribute names; to create a new attribute you have to use this field to define a name first
* type selection: defines the type (text, binary, integer, decimal, text list, integer list, decimal list) of the attribute
* default: can be used to define a default value for this attribute that is assigned to all nodes automatically (since only declaring the name and type of an attribute function does not define its values)
* description

Don't forget to press the apply button at the bottom of the attribute manager.

== Manipulate ==

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

== grouped modifications ==

=== operations ===

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

=== import and export ===

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

Attribute manager

2014-03-19T12:35:34Z

Lerner:

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. Attributes also encode the results of a [[Analysis_tab|network analysis algorithm]] such as node centrality of cluster membership. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

== Configure ==

* check mark: the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* name field: enables the (re-)definition of attribute names; to create a new attribute you have to use this field to define a name first
* type selection: defines the type (text, binary, integer, decimal, text list, integer list, decimal list) of the attribute
* default: can be used to define a default value for this attribute that is assigned to all nodes automatically (since only declaring the name and type of an attribute function does not define its values)
* description

Don't forget to press the apply button at the bottom of the attribute manager.

== Manipulate ==

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

== grouped modifications ==

=== operations ===

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

=== import and export ===

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

File:Attribute manager select.png

2014-03-19T12:34:05Z

Lerner: Blanked the page

Visualization and analysis (tutorial)

2014-03-19T12:33:39Z

Lerner: /* Selecting elements dependent on attribute values */

This [[Tutorials|tutorial]] shows you how analysis and visualization goes hand in hand in visone. It introduces you to the most common usage scenario: importing data from one or several files, analyzing the network, visualizing the network together with the computed indicators, exporting data and images for further processing or publication.

This tutorial assumes that you have basic knowledge about how to operate the visone [[GUI]] - as explained in the [[Introducing the visual network editor (tutorial)|previous tutorial]].

== Introducing an exemplary dataset ==

The data that we use in this tutorial has been collected in a long-term reseach project about ''acculturation networks''. More information about the project can be found at [http://www.egoredes.net]. Among others, the personal networks of now more than 1,000 immigrants have been collected within this project. Each of the respondents (called '''ego''') provided answers to four types of questions:
# '''questions about ego''', including country of origin, years of residence, age, gender, skin color, reasons for migrating, health, language skills...
# '''alters''' a list of persons known to ego (for most networks the number has been fixed to 45)
# '''questions about alters''' including country of origin, country of residence, age, skin color, type of relation to ego, ...
# '''alter-alter ties''' (undirected) pairs of alters that ''know each other'' (according to the respondent)

A more detailed description is provided on the page [[Egoredes (data)]].

In this tutorial we exemplarily analyze one of these personal networks obtained from interviewing a migrant from the Dominican Republic to the USA. The dataset here contains none of the variables characterizing ego but only the alter characteristics and the alter-alter ties.

More specifically the ties are encoded in an adjacency matrix file ''Egonet_ties.csv'', the alter characteristics in a file ''Egonet_attributes.csv''. The [[GraphML]] file ''Egonet.graphml'' contains ties and attributes in a more comfortable and reliable way; the ''CSV'' files are provided for the sole purpose of demonstrating how data can be imported from comma-separated value tables.

* [[Media:Egonet_ties.csv|'''alter-alter ties''' (''Egonet_ties.csv'')]]
* [[Media:Egonet_attributes.csv|'''alter characteristics''' (''Egonet_attributes.csv'')]]
* [[Media:Egonet.graphml|GraphML file (''Egonet.graphml'')]]

To follow the steps explained in this tutorial, you should download these three files and save them on your hard disk (right-click and select ''save link as'').

('''Note:''' we also provide more recent and more comprehensive data about personal networks of immigrants linked from the page [[Signos_(data)]]; visual analysis of that data is illustrated in the [[Personal_networks_(tutorial)|tutorial on personal networks]].)

== Importing networks from adjacency matrix files ==

The usual way to get a network into visone is to read it from a local file via the menu '''file, open'''

[[File:Menu_file_open.png]]

The usual file type to be read by visone is [[GraphML]]; GraphML files contain information about nodes and links, about attributes of nodes and links, and about graphical information such as layout, color, or shape. To read GraphML files you select ''.graphml''
in the [[file open dialog]] (shown below) and click on ''ok''; this is simple, fast, and reliable.

Here, for illustration, we go the hard way and assume that the data are not stored in a GraphML file but in ''comma-separated-value tables''. This very primitive file type can be output from many programs, including statistical software, spread-sheet editors, or other network analysis software. Sometimes you have to deal with this file type.

To open a network from an adjacency matrix file you select ''files of type'' '''CSV files (.txt, .csv)''' in the file open dialog, select the appropriate file in the file browser, and click on '''ok'''. To follow the steps outlined in this tutorial, select the file '''Egonet_ties.csv'''.

[[File:File_open_dialog.png]]

Clicking on ''ok'' does not immediatelly open the file. Indeed, in contrast to GraphML, CSV files don't have a self-explaining interpretation; rather the program that has to handle them needs some guidance. Therefore visone opens an [[import options dialog]] (see below).

[[File:Import_options_dialog_adjacency_matrix.png]]

For an exhaustive explanation of all options and their meaning see the page on the [[import options dialog]]. To continue with this tutorial, set all options as shown in the image above and click on '''ok'''.
This opens a network looking like this.

[[File:Egonet_ties.png]]

The ''.csv'' does not contain layout information. The position of the nodes has been determined by the layout algorithm that can be initiated with the [[quick layout button]].

Apart from GraphML and CSV format, visone can also open files in UCINET's ''.dl'' format, in Pajek's ''.net'' format, and some more.

A more exhaustive treatment about the various possibilities to import data into visone is given in the [[Data_input_(tutorial)|data input tutorial]].

== Importing attributes from CSV tables ==

Currently, the nodes have only one attribute called ''id''. The values of other attributes are provided in the file ''Egonet_attributes.csv''. This file can be merged into our current network via the [[attribute manager]] which can be started by clicking on the icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

In the attribute manager, choose the '''nodes''' button in the top row, '''import & export''' on the left, and select the file [[Media:Egonet_attributes.csv|''Egonet_attributes.csv'']] that you have previously downloaded to your computer.

[[File:Attribute_manager_import.png]] [[File:Attribute_manager_import_options.png]]

Before clicking on '''apply''' it is very important to correctly set the value in the ''join by'' drop-down menu. This should point to the name of the attribute that identifies the nodes and tells visone which column in the imported CSV file holds these identifiers. Currently you can only select '''id''' but in general there might be several node attributes and the nodes could as well be identified by attributes having a different name than '''id'''. Clicking on '''apply''' opens an import options dialog; setting the options as shown above - in particular, setting the cell delimiter to semicolon (''';''') - and clicking on '''ok''' imports the attributes. You can see the result by clicking the '''show & edit''' button on the left hand side of the attribute manager. Then, you should see something similar to the following image.

[[File:Attribute_manager_import_result.png]]

== Mapping attributes to graphics: categorical attributes ==

[[File:Mapping_categorical.png|300px|thumb|right]] For many networks it is extremly insightful to show the attribute values in the network image. In visone, attributes can be mapped to graphical variables via the [[visualization tab]].

In the [[visualization tab]] you can choose between plenty of options; these have to be set from top to bottom. For the '''category''' chose ''mapping'' since we want to map existing attributes to graphical variables. (The other two options are ''layout'' for applying a visualization algorithm and ''geometry'' for doing affine transformations, such as rotating or scaling.)

The '''type''' of the mapping refers to the type of the graphical variable that is used for encoding attribute values. This choice is restricted by the type of the attribute that is to be mapped. Numerical attributes can be mapped to graphical variables that allow the user to recognize that one actor has a larger value than another one; examples of such variables are size or position whose usage is demonstrated further down in this tutorial. In this section, however, we want to encode a categorical variable - more specifically, the country of origin of the actor. A good choice for a graphical variable to encode this information is ''color'' which we select in the drop-down menu right of '''type'''. For '''property''' chose ''node color''.

The drop-down menu right of '''node value''' should be set to the name of the attribute that is to be encoded; we chose ''Afrm'' (meaning ''country of origin of the actor''). Finally, selecting ''color table'' for the '''method''' option presents you a table with the different values of the ''Afrm'' attribute together with a predefined choice of colors that you can change as you wish. Clicking on the '''visualize!''' button at the bottom of the visualization tab applies the mapping whose result is shown in the network area of the visone window.

== Computing network analytic indicators: centrality ==

[[File:Analysis_example.png|200px|thumb|right]] visone offers you a rich choice of methods that compute analytic measures on a given network. In this section, we exemplarily compute a centrality indicator on the set of actors. (Node centralities specify which actors are the ''important'' ones with respect to a certain criterion.)

Computing such indicators is done via the [[analysis tab]]. To compute the degree of the actors (i.e., the number of ties attached to each actor) set '''task''' to ''indexing''. ''Indexing'' means that we are assigning values to individual elements (i.e., to nodes or edges) of the network. Set '''class''' to ''node centrality'' and '''index''' to ''degree''. The values specified for '''link length''' and '''link strength''' can currently only be ''uniform'' since we don't have any tie weights. Unchecking the '''percentage''' and '''standardize''' boxes ensures that the actual degrees are computed. The text field right of '''result attribute''' specifies the name of the attribute in which the computed values are to be stored. (visone makes suggestions for this name; at the moment it should say ''degree'' but you can change this if you want.)

Having set all these options click on the '''analyze!''' button at the bottom of the analysis tab. (You won't see any change in the image of the network; however, at the bottom line of the main window visone tells you what has been computed and in which attribute it has been stored.)
[[File:Node_properties_dialog_degree.png|100px|thumb|left]]
You could browse the values of the newly computed attribute in the attribute manager or in the attributes tab of the [[node properties dialog]] (see the last entry telling you that the degree of the selected node equals 9).
You could also export the attributes via the [[attribute manager]] (which works similar to the import of attributes explained above) and store them in CSV tables.

However, in many situation it is more insightful to visualize the computed centrality values. This is illustrated in the next section of this tutorial.

== Mapping attributes to graphics: numerical attributes ==

Centrality values (such as the node degrees that have been computed above) are numerical attributes. These can be mapped to graphical variables that let the user distinguish between larger and smaller. Examples of such graphics are size, position (x/y-coordinates), or color gradient. For instance, to map the node degree to the node size you can proceed similar as for mapping categorical attributes (illustrated above). In the [[visualization tab]] choose '''category'''=''mapping'', '''type'''=''size'', '''property'''=''node area'', and '''node value'''=''degree''; click on '''visualize!'''.

== Network layout ==

Network layout algorithms compute the positions of nodes, links, and/or labels to yield nice network images. For convenience, a general-purpose layout algorithm can be initiated by clicking on the [[Quick_layout|quick layout button]] [[File:Quick_layout.png|link=quick_layout]] in visone's toolbar. All other layout algorithms can be initiated from the [[visualization tab]] (select '''category'''=''layout''). The different choices in the drop-down menu right of '''layout''' determine which positions are to be modified. More explanation can be found in the page on the [[visualization tab]].

== Selecting elements dependent on attribute values ==

[[File:Attribute_manager_select_links.png|500px|thumb|right]] Finally, we demonstrate how network elements (i.e., nodes and links) that have specific attribute values can be selected. Therefore, download the file [[Media:Egonet.graphml|'''Egonet.graphml''']] (see the description on the page [[Egoredes (data)]]), save it to your computer, and open it in visone via the menu '''file, open'''.

This network turns out to be one big mess containing 45 nodes and 990 links (a simple calculation tells you that the network is complete, i.e., each pair of nodes is connected by a link). The information about which actors actually know each other is encoded in the link attribute '''rating''' which can assume the values ''Not at all likely'', ''Maybe'', or ''Very likely''. To delete all links that are not rated as ''Very likely'' (say), open the [[attribute manager]], click on the button '''link''' in the top, and '''select''' on the left-hand side, select the link attribute '''rating''' in the drop-down menu. The table shows the different values of this attribute along with the number of links that are assume this value and clicking on one or several rows selects these links. The selected links can be deleted either from the [[link context menu]] or from the menu '''links, delete links'''. Selecting and deleting those links that are rated as ''Not at all likely'', or ''Maybe'' and layouting the network via the [[Quick_layout|quick layout button]] shows you a network that is identical to the one encoded in the adjacency matrix ''Egonet_ties.csv''.

More sophisticated ways to select network elements are illustrated in the next tutorial on [[Managing_attributes_(tutorial)|advanced attribute management]].

File:Attribute manager select.png

2014-03-19T12:32:33Z

Lerner: uploaded "File:Attribute manager select.png"

#REDIRECT [[File:Attribute manager select links.png]]

File:Attribute manager select.png

2014-03-19T12:31:06Z

Lerner: moved File:Attribute manager select.png to File:Attribute manager select links.png

#REDIRECT [[File:Attribute manager select links.png]]

File:Attribute manager select links.png

2014-03-19T12:31:05Z

Lerner: moved File:Attribute manager select.png to File:Attribute manager select links.png

Attribute manager

2014-03-19T12:29:14Z

Lerner: /* Show & edit */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The '''Show & edit''' category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attributes.

[[File:Attribute_manager_show_n_edit.png]]

You can also modify the values if the '''allow editing''' box is checked and you can specify whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

== Configure ==

* check mark: the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* name field: enables the (re-)definition of attribute names; to create a new attribute you have to use this field to define a name first
* type selection: defines the type (text, binary, integer, decimal, text list, integer list, decimal list) of the attribute
* default: can be used to define a default value for this attribute that is assigned to all nodes automatically (since only declaring the name and type of an attribute function does not define its values)
* description

Don't forget to press the apply button at the bottom of the attribute manager.

== Manipulate ==

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

== grouped modifications ==

=== operations ===

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

=== import and export ===

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

File:Attribute manager show n edit.png

2014-03-19T12:25:12Z

Lerner:

Attribute manager

2014-03-19T12:20:28Z

Lerner: /* individual modifications */

An [[Attribute|attribute]] is a function that maps elements of the network (such as nodes or links) to values. An attribute has a name, domain (specifying the type of network elements it is defined on), type (specifying the possible values, such as ''text'', ''integer'', ''boolean'', etc), and possibly a default value and a description. Attributes attach information to network elements, such as the name or age or geographic coordinates of a node or the width or capacity or encoded type of relation of a link. The '''attribute manager''' provides functionality related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes. The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

These categories of attribute management are further explained below.

In general, whenever you have specified an operation you have to click on the '''apply''' button to execute it. Depending on the operation you can choose to apply it only to the current network or to several networks at once, you can specify whether the operation should be only applied to the currently selected elements and whether the operation result should modify the network directly (choose ''result in'' '''same tab''') or whether visone should first create a copy of the network and apply the operation to this copy ('''new tab''').

== Show & edit ==

The values category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attribute functions that are declared. You can also modify the values if the '''allow editing''' box at the bottom right of the attribute manager is checked. Additionally, you can specify whether to '''show default values''' (bottom left) and whether to display only a subset of attributes (use check marks at the top).

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#Import_&_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]].

== Select ==

== Configure ==

* check mark: the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* name field: enables the (re-)definition of attribute names; to create a new attribute you have to use this field to define a name first
* type selection: defines the type (text, binary, integer, decimal, text list, integer list, decimal list) of the attribute
* default: can be used to define a default value for this attribute that is assigned to all nodes automatically (since only declaring the name and type of an attribute function does not define its values)
* description

Don't forget to press the apply button at the bottom of the attribute manager.

== Manipulate ==

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

== Filter ==

== Import & export ==

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

== grouped modifications ==

=== operations ===

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

=== import and export ===

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

Attribute manager

2014-03-19T09:51:00Z

Lerner: /* What to do with which attributes? */

Attribute manager

2014-03-19T09:46:26Z

Lerner:

Attribute manager

2014-03-19T09:32:42Z

Lerner: /* What to do with which attributes? */

The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar. The attribute manager provides a variety of possibilities related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* '''node''' attributes
* '''link''' attributes
* '''dyad''' attributes
* '''network''' attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* '''show & edit''' displays the values of all (node, link, ...) attributes and allows to modify them manually
* '''select''' allows to select all elements taking specific values for a single specified attribute
* '''configure''' to add and delete attributes; change their names, range of values, description, or default values
* '''manipulate''' apply transformation functions to one or several attributes
* '''filter''' specify potentially complex ways to select elemens (much more powerful than '''select''')
* '''import & export''' read from and write to CSV files

== individual modifications ==

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#import_and_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]]. Creation of new attributes and type selection is illustrated in the [[Introducing_the_visual_network_editor_(tutorial)|tutorial about the visual network editor]].

=== configuration ===

* check mark: the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* name field: enables the (re-)definition of attribute names; to create a new attribute you have to use this field to define a name first
* type selection: defines the type (text, binary, integer, decimal, text list, integer list, decimal list) of the attribute
* default: can be used to define a default value for this attribute that is assigned to all nodes automatically (since only declaring the name and type of an attribute function does not define its values)
* description

Don't forget to press the apply button at the bottom of the attribute manager.

=== values ===

The values category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attribute functions that are declared. You can also modify the values if the '''allow editing''' box at the bottom right of the attribute manager is checked. Additionally, you can specify whether to '''show default values''' (bottom left) and whether to display only a subset of attributes (use check marks at the top).

Values that are ''not assigned'' yet, are marked ''N/A''.

== grouped modifications ==

=== operations ===

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

=== import and export ===

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

Attribute manager

2014-03-19T09:26:29Z

Lerner:

The attribute manager is started by clicking on its icon [[File:Attribute_manager.png|link=attribute_manager]] in visone's toolbar. The attribute manager provides a variety of possibilities related to the creation, configuration, and automatical modification of attributes, as well as methods for selecting and filtering nodes and links based on their attributes.

== What to do with which attributes? ==

The four buttons in the top row are used to select the type of elements whose attributes one wants to manage, namely
* node attributes
* link attributes
* dyad attributes
* network attributes

[[File:Attribute_manager2.png]]

The six buttons on the left-hand side are used to specify what kind of management one is looking for, namely
* configuration management (manually)
* value management (manually)
* operation involving value management (automatically)
* import & export management (automatically)

== individual modifications ==

Note, that attribute values are typically not added manually (which would be tiresome). It is more usual that attributes are [[#import_and_export|imported]] from files or computed by a [[analysis_tab|network analysis algorithm]]. Creation of new attributes and type selection is illustrated in the [[Introducing_the_visual_network_editor_(tutorial)|tutorial about the visual network editor]].

=== configuration ===

* check mark: the check mark in the left column defines the attribute that is displayed as label (for nodes/links)
* name field: enables the (re-)definition of attribute names; to create a new attribute you have to use this field to define a name first
* type selection: defines the type (text, binary, integer, decimal, text list, integer list, decimal list) of the attribute
* default: can be used to define a default value for this attribute that is assigned to all nodes automatically (since only declaring the name and type of an attribute function does not define its values)
* description

Don't forget to press the apply button at the bottom of the attribute manager.

=== values ===

The values category can be used to explore the values that the nodes/links (or the selected nodes/links, if there are selected nodes/links) assume on all attribute functions that are declared. You can also modify the values if the '''allow editing''' box at the bottom right of the attribute manager is checked. Additionally, you can specify whether to '''show default values''' (bottom left) and whether to display only a subset of attributes (use check marks at the top).

Values that are ''not assigned'' yet, are marked ''N/A''.

== grouped modifications ==

=== operations ===

The operations category provides means to change a node/link attribute function as a whole. Modification of attributes is illustrated in the [[Managing_attributes_(tutorial)|tutorial on ''advanced attribute management'']].

You might just want to '''copy''' or '''delete''' (select according ''operation'') an existing attribute function (select according ''attribute'') - and provide a new name of the ''result attribute'' (if you don't want to delete or, in general, overwrite the current one).

You can also '''rank''' the nodes/links in '''ascending''' or '''descending''' ''order'' with regard to an ''attribute'', creating an integer type ''result attribute''.

'''Merge to list''' enables you to select a number of ''source attributes'' (pressing Crtl key to add single ones or holding shift key to select a number of successive ones) to be merged into a text ''result attribute'', being a comma separated list of these values.

There are also a number of possibilities to '''convert list values''', namely calculating the '''maximum''', '''minimum''', '''average''', or '''sum''' of entries (integer/decimal list), or '''concatenate''' them (text list).

Finally, '''manipulate values''' provides means to automatically
* '''invert''' (note, that a zero attribute value will result in a N/A entry in the result attribute!)
* '''reverse'''
* '''add''' a specified ''offset''
* '''scale''' with a specified ''scalar''
* '''normalize''' (i.e. each value is divided by the maximum values)
* '''standardize''' (i.e. each value is divided by the sum of all values)
* '''round''' to specified ''fraction digits''
* '''round up''' to specified ''fraction digits''
the values of an attribute function. While the attribute manager, thus, offers only a limited set of functions to transform attributes, general transformations can be specified and executed via visone's [[R_console_tab|R interface]]; this is illustrated in the [[R_console_(tutorial)|tutorial on ''using visone's R console'']].

=== import and export ===

Attributes can be imported from and exported to files in ''comma-separated value tables''; this is illustrated in the [[Visualization_and_analysis_(tutorial)|tutorial on ''visualization and analysis'']]. When importing attributes from a .csv file you have to specify how the data shall be joined. That is, the .csv file should contain a column that is named according to the '''join by''' attribute of the network. It is also possible to import an additional link attribute via a .csv matrix (nodes IDs in the matrix have to be the same as in the network).

When exporting attributes you can specify how the data shall be sorted, using the attribute selected for '''sort by'''.

If you are working with more than one network tabs, you can also export one specified attribute of all open networks as a table.

Link selection dialog

2014-03-19T08:52:27Z

Lerner:

'''Note: the link selection dialog is no longer part of the visone GUI. Methods to select and filter links are provided by the [[attribute manager]].'''

The link selection dialog is called from the [[links_menu|links menu]], enabling convenient selection of link subsets based on a wealth of possible similarities.

Multiple [[#conditions|selection conditions]] and [[#operations|selection operations]] can be arbitrarily combined.

== conditions ==

You have to mark the conditions you want to use in the left column; and let those you do not want to use unmarked.

In general, '''ordinal''' visual properties and data attributes allow a selection based on smaller (<), equal (=) or greater (>) values according to a specified threshold (right field). You may also which to set two check marks to create selections based on smaller equal (< and =), greater equal (= and >), or non-equal (< and >) conditions.

Multiple conditions on '''nominal''' properties can be combined, performing successive [[#operations|selection operations]] accordingly.

=== visual properties ===

* shape
* color
* style
* border color
* width
* direction - directed or undirected
* confirmation - receiver confirmed, sender confirmed or (mutually) confirmed

=== attributes ===

Any link attribute can be incorporated into selection conditions, too.
In terms of text attributes, you can ask to match exactly the text entered in the right field, or to contain this text at least as a substring.

=== incidence with selected nodes ===

* '''direction:''' You can select links that have at least one selected node as source ('''out''') or sink ('''in'''). With regard to an undirected link, the incident nodes are both, source and sink.

* '''confirms:''' Similarly, you can select a link based on whether it is confirmed ('''yes''') by at least one selected node or not ('''no''').

* '''number:''' Additionally, you can select a link based on whether '''none''' of its incident nodes is selected, at least '''one''' of its incident nodes is selected or '''both''' of its incident nodes are selected.

=== selected parallel links ===

* '''direction:''' You can select links that connect two nodes in the '''same''' direction as at least one selected link and/or connect two nodes in the '''reverse''' direction as at least one selected link. With regard to an undirected link, there is no difference.

== operations ==

At the bottom of the selection dialog you have to chose which selection operation should be performed regarding the specified conditions.

* replace: discards previous selections and creates a new selection with all links fulfilling the specified conditions
* add: adds all links fulfilling the specified conditions to current selection
* remove: removes all links fulfilling the specified conditions to current selection
* restrict: restricts the current selection to all contained links fulfilling the specified conditions

Node selection dialog

2014-03-19T08:50:58Z

Lerner:

'''Note: the node selection dialog is no longer part of the visone GUI. Methods to select and filter nodes are provided by the [[attribute manager]].'''

The node selection dialog is called from the [[nodes_menu|nodes menu]], enabling convenient selection of node subsets based on a wealth of possible similarities.

Multiple [[#conditions|selection conditions]] and [[#operations|selection operations]] can be arbitrarily combined.

== conditions ==

You have to mark the conditions you want to use in the left column; and let those you do not want to use unmarked.

In general, '''ordinal''' visual properties and data attributes allow a selection based on smaller (<), equal (=) or greater (>) values according to a specified threshold (right field). You may also which to set two check marks to create selections based on smaller equal (< and =), greater equal (= and >), or non-equal (< and >) conditions.

Multiple conditions on '''nominal''' properties can be combined, performing successive [[#operations|selection operations]] accordingly.

=== visual properties ===

* shape
* color
* border style
* border color
* x-coordinate
* y-coordinate
* width of shape
* height of shape

=== attributes ===

Any node attribute can be incorporated into selection conditions, too.
In terms of text attributes, you can ask to match exactly the text entered in the right field, or to contain this text at least as a substring.

=== incidence with selected links ===

* '''direction:''' You can select nodes that are the source ('''out''') or sink ('''in''') of at least one selected link. When incident to an undirected link a node is both, a source and a sink of this link.

* '''confirms:''' Similarly, you can select a node based on whether it confirms ('''yes''') at least one selected link or not ('''no''').

=== adjacency with selected nodes ===

* '''direction:''' You can select nodes that are the source of a link to at least one selected node ('''predecessor''') or a sink of a link from at least one selected node ('''successor'''), respectively. With regard to an undirected link, the incident nodes are both, predecessor and successor of each other.

* '''confirms:''' Similarly, you can select a node based on whether it has confirmed ('''yes''') a link to at least one selected node or not ('''no''').

== operations ==

At the bottom of the selection dialog you have to chose which selection operation should be performed regarding the specified conditions.

* replace: discards previous selections and creates a new selection with all nodes fulfilling the specified conditions
* add: adds all nodes fulfilling the specified conditions to current selection
* remove: removes all nodes fulfilling the specified conditions to current selection
* restrict: restricts the current selection to all contained nodes fulfilling the specified conditions