Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Importing a Pajek Graph"

(3. *Arcs – definition of arcs. The same parameters as for edges can be used, see above.)
(Multi-Population Pajek Graph Example)
(37 intermediate revisions by 5 users not shown)
Line 1: Line 1:
==PajekNetGraphGenerator Example Project==
+
==Multi-Population Pajek Graph Example==
  
STEM allows users to create a custom graph using Pajek. '''Pajek''' ([http://vlado.fmf.uni-lj.si/pub/networks/pajek/]) uses a kind of standardized language for describing networks. Some examples might be found here: http://vlado.fmf.uni-lj.si/pub/networks/pajek/testdata.zip. A subset of this language is interpreted by the PajekNetGraphGenerator to import arbitrary graphs into STEM. The PajekNetGraphGenerator allows creating user-defined graphs (coordinates and shapes of nodes, type and rates of edges) for STEM and is based on the Pajek format.
 
  
[[Image:Pajekscreenshot.jpg|600px]]
+
This page is about the new '''Pajek''' format which is used in STEM releases since version 1.4.0 and in current milestone and integration builds. The old format that was used prior to 1.4.0 is still supported. Examples and documentation of the old format are available at the website download page for [http://www.eclipse.org/stem/download_sample.php?file=MultiPopulationExample_PajekGraphs.zip Multi-Population Pajek Graph Example].
An example project available for download may be found on the STEM website or a [http://www.eclipse.org/stem/download_sample.php?file=MultiPopulationExample_PajekGraphs.zip]. This is a standard STEM project that you may import into your workspace. It contains a graph generated using the Pajek Graph Generator. It also contains examples of the original Pajek files used to create the graphs found in the project. The files are located in the 'Doc' directory of the project. Also in that directory you can find additional documentation. Read the PajekStem_Format.doc (or PajekStem_Format.txt) for further information about the modified Pajek format. The PajekNetGraphGenerator is
+
available in the graph creation dialogue of STEM.
+
  
===The archive:===
+
== File Format ==
The archive contains the STEM project MultiPopulationExample_PajekGraphs, a modification of the STEM project MultiPopulationExample. The modification replaces the graph "3x3.graph" in the MultiPopulationNoVillageExample scenario with the imported graph "CC.graph" (that was imported with file CC.NET_2stem.net). Additionally, another Pajek file is added to the archive: 1.NET_2stem.net. The imported Pajek NETs were created with a simple Excel Macro (Pajek2STEM.xls). This macro allows the easy modification of Pajek NETs; it is not necessary, but makes things far easier - especially for complex graphs. The macro imports a Pajek NET, allows for modification and adding of additional parameters and exports a Pajek NET that is still compatible with Pajek. The usage of this macro is straightforward (be aware of the gray control buttons). It is generally applicable to all Pajek NETs.
+
  
Hint:
+
STEM allows users to create a custom graph using a format similar to the '''Pajek''' ([http://vlado.fmf.uni-lj.si/pub/networks/pajek/]) format. The PajekNetGraphGenerator, which is available in the graph creation dialogue of STEM, can create user-defined graphs for STEM and is based on this format.
Pajek allows (x,y,z)-coordinates between 0 and 1 only. STEM rounds coordinates to
+
The format specification is as follows.  
two decimal places. This might result in strange shapes of the nodes. This
+
behaviour can be avoided if the coordinates are multiplied by a large factor
+
(which is possible with the Excel macro). Be aware: the resulting file (with
+
coordinates larger than 1) cannot be imported into Pajek.
+
  
 +
*Vertices [number of nodes]
 +
[node number] [node name] [longitude] [latitude] [additional optional parameters] // spec for a new node
 +
[node number] [node URI] // spec for reference to existing node
 +
...
 +
*Edges
 +
[origin node number] [destination node number] popID [populationID] rate [rate] // spec for migration edges
 +
[containing node number] [contained node number] // spec for containment edges
 +
...
  
==Contributors:==
+
== Node Format  ==
  
The PajekNetGraphGenerator was created and developed by the department of
+
The keyword "*Vertices [number of nodes]" is the starting point for the nodes section. New nodes and references to existing nodes can be defined. The formats are as follows.
Biological Safety of the Federal Institute for Risk Assessment in Germany.
+
  
Armin Weiser, Matthias Filter
+
=== New Node ===
Dept. Biological Safety
+
Federal Institute for Risk Assessment
+
12277 Berlin
+
Germany
+
 
+
===Contact:===
+
'''armin.weiser@bfr.bund.de''' ''Italic text''
+
  
==PajekNetGraphGenerator and STEM-related Format extension to Pajek==
+
'''[node number] [node name] [longitude] [latitude] [optional parameters]:'''
 +
*node number – unique node number (1, 2, 3, ...). Successive numbering of nodes is obligatory.
 +
*node name – unique name consisting of letters a..zA..Z and digits 0..9.
 +
*longitude, latitude – coordinates of the node. All values can be entered, but real world coordinates are: -180 <= longitude <= 180, 0 <= latitude <= 90.
  
The following reserved words are supported in the current Pajek Import implementation:
+
'''Optional parameters:'''
 +
*popID – identifier of a population of the node. This parameter may be used repeatedly.
 +
*popCount – number of individuals living in the node. This parameter may be used repeatedly. The associated popID is the last mentioned one.
  
===1. *Vertices n – n is number of vertices. In STEM nodes are the equivalent of vertices. Each vertex is described using following format (take care of the sequence of the parameters, additional and STEM-only parameters may be in any order):===
+
'''Example:'''
 +
1 Berlin 13.398889 52.500556 popID men popCount 1682900000 popID women popcount 1753500000
  
* vertexnum label x y [z] [shape] [additional optional parameters]
+
=== Node Reference ===
 +
'''[node number] [node URI]:'''
 +
*node number – unique node number (1, 2, 3, ...). Successive numbering of nodes is obligatory.
 +
*node URI – URI of the node in STEM. If the URI starts with ''stem://org.eclipse.stem/node/geo/region/'', this prefix can be omitted.
  
* vertexnum – vertex number (1; 2; 3 : : : n). Successive numbering of vertices/nodes is obligatory. vertexnum itself is not used inside STEM after import.
+
'''Examples:'''
* label – if label starts with character a..zA..Z or 0..9 first blank determines end of the label (e.g., vertex1), labels consisting of more words must be enclosed in pair of special characters (e.g., ”vertex 1”). The definition of a label is obligatory.
+
1 stem://org.eclipse.stem/node/geo/region/FR-IF
* x, y, z – coordinates of vertex. The z coordinate is ignored in STEM. In Pajek the coordinates have values between 0 and 1, for STEM the values are not limited. x and y coordinates are obligatory for STEM.
+
1 FR-IF
  
* shape – shape of object which represents vertex. The following shapes are supported by the PajekNetGraphGenerator: triangle, cross, ellipse, box, diamond. In STEM ellipse is represented as circle and box and diamond both are represented as box. box is the default value.
+
== Edges Format  ==
  
* Additional parameters:
+
The keyword "*Edges" is the starting point for the edges section. Two types of edges can be described; they are migration edges and containment edges. The formats are as follows.
  
* s_size – size of the node. The default size is given by the parameter “Default Area” within the PajekNetGraphGeneratorImpl dialog in STEM. For STEM the size of the node is not limited. Overlaps of nodes are not checked by the importer, they are allowed.
+
=== Migration Edges ===
  
''Example: 1 ”vertex one” 0.3456 0.1234 0.5 ellipse s_size 0.1''
+
'''[origin node number] [destination node number] popID [populationID] rate [rate]:'''
 +
*origin node number – number of the node the population migrates from. Has to be defined as node number in *Vertices.  
 +
*destination node number – number of the node the population migrates from. Has to be defined as node number in *Vertices.
 +
*populationID – defines the ID of the migrating population.
 +
*rate - number population members migrating per day.
  
====Parameters only valid in STEM (these parameters are ignored by Pajek):====
+
'''Optional parameters:'''
 +
*date - specification a of date at which the migration rate is different from the standard value specified in the obligatory parameters. ISO 8601 standard is used (YYYY-MM-DD). This parameter may be used repeatedly.
 +
*rate - migration rate for the specified date. This parameter may be used repeatedly. The associated date is the last mentioned one.
  
* popid – identifier of a population of the node. This parameter may be used repeatedly.
+
'''Example:'''
 +
1 2 popID beef rate 1.0 date 2012-01-01 rate 10.0
  
* popcount – number of individuals living in the node. This parameter may be used repeatedly. The associated popid is the last mentioned one.
+
=== Containment Edges ===
  
''Example: 1 ”vertex one” 0.3456 0.1234 0.5 ellipse s_size 0.1 popid human popcount 24 popid anopheles popcount 1000
+
'''[containing node number] [contained node number]:'''
''
+
*containing node number – number of the node that contains the other node. Has to be defined as node number in *Vertices.  
 +
*contained node number – number of the node that is contained by the other node. Has to be defined as node number in *Vertices.
  
===2. *Edges – definition of edges. Format (take care of the sequence of the parameters, STEM-only parameters may be in any order):===
+
'''Example:'''
  
v1 v2 [borderlength] [additional optional parameters]
+
*Vertices 3
 +
1 Berlin 1 1 popID men popCount 100 popID women popCount 110
 +
2 Bonn 1.5 1 popID men popCount 100 popID women popCount 110
 +
3 Germany 1.2 1.2
 +
*Edges
 +
1 2 popID men rate 0.1
 +
2 1 popID women rate 0.2
 +
3 1
 +
3 2
  
* v1 – initial vertex number. The definition of v1 is obligatory. v1 has to be defined as node (see above: vertexnum).
+
Running the downloadable pajek scenario the map view should appear as shown below.
* v2 – terminal vertex number. The definition of v2 is obligatory. v2 has to be defined as node (see above: vertexnum).
+
* borderlength – defines the borderlength for CommonBorderEdges
+
  
====Edge Parameters only valid in STEM (these parameters are ignored by Pajek):====
+
[[Image:STEM_PajekExample.png|600px]]
  
* popid – identifier of a population migrating on the edge. This parameter may be used repeatedly. If this parameter and additionally “rateab” or “rateba” is set at least once then a MigrationEdge will be specified in STEM, otherwise a CommonBorderEdge will be defined.
 
  
* rateab – fraction of the population in node v1 migrating over the edge to the terminal node v2 in a given time period (see http://wiki.eclipse.org/Transportation_Models#Migration_Between_Regions). This parameter may be used repeatedly. The associated popid is the last mentioned one. The default value is 0.
 
  
* rateba – fraction of the population in node v2 migrating over the edge to the node v1 in a given time period. This parameter may be used repeatedly. The associated popid is the last mentioned one. The default value is 0.
+
== Using the dialog ==
  
''Example: 1 2 popid human rateab 0.2 rateba 0.1 popid anopheles rateab 0.5 rateba 0.1''
+
[[Image:STEM_PajekDialog.png|right|300px]]
 +
The dialog to import a Pajek graph from a file is shown on the right. It is available in the STEM Graph Dialog. The following parameters are available for importing.
 +
*Pajek File - The file from which the graph is imported. A file dialog is available to select the file.
 +
*Scaling Factor - A factor by which all coordinates specified in the file are scaled during import. If node has the coordinates 10.0/20.0 in the file and the scaling factor is 2.0, the node's resulting coordinates in STEM are 20.0/40.0.
 +
*Node Size - In STEM each imported node appears as a square for visualization. This parameter specifies the edge length of the squares for all imported nodes.
 +
*Use global Region Names - If selected, the URIs for the imported nodes will be of the type ''stem://org.eclipse.stem/node/geo/region/*****''. This has the advantage, that the nodes can be accessed by just using that last part of the URI ''*****''. This option should only be used if node names specified in the Pajek file are unique and do not occur in other STEM graphs. If not selected, the node URIs will contain the graph's URI.
 +
*Move Nodes to Containers - If selected, all nodes that are contained by another node from a different graph will be moved close to this container. That means that coordinates specified for these nodes in the Pajek file will be ignored.
  
===3. *Arcs – definition of arcs. The same parameters as for edges can be used, see above.===
+
== Tutorial ==
  
 +
A tutorial on how to import a Pajek graph that contains discrete migration events for a STEM graph is available at [[STEM Import Discrete Transportation Events|Import Discrete Transportation Events]]. Discrete events can be used to model commodity flows, e.g. the transportation of beef from slaughterhouses to supermarkets in order to model the spread of a foodborne disease.
  
In the downloadable project, you will find some examples that may be imported into STEM. The filename extension “.net” is not mandatory for STEM:
+
== Contributors  ==
  
* CC.NET_2stem.net
+
The PajekNetGraphGenerator was created and developed by the Department of Biological Safety of the Federal Institute for Risk Assessment in Germany.
* 1.NET_2stem.net
+
 
 +
Armin A. Weiser, Matthias Filter, Christian Thöns
 +
Dept. Biological Safety
 +
Federal Institute for Risk Assessment
 +
12277 Berlin
 +
Germany

Revision as of 12:53, 19 September 2013

Multi-Population Pajek Graph Example

This page is about the new Pajek format which is used in STEM releases since version 1.4.0 and in current milestone and integration builds. The old format that was used prior to 1.4.0 is still supported. Examples and documentation of the old format are available at the website download page for Multi-Population Pajek Graph Example.

File Format

STEM allows users to create a custom graph using a format similar to the Pajek ([1]) format. The PajekNetGraphGenerator, which is available in the graph creation dialogue of STEM, can create user-defined graphs for STEM and is based on this format. The format specification is as follows.

*Vertices [number of nodes]
[node number] [node name] [longitude] [latitude] [additional optional parameters] // spec for a new node
[node number] [node URI] // spec for reference to existing node
...
*Edges
[origin node number] [destination node number] popID [populationID] rate [rate] // spec for migration edges
[containing node number] [contained node number] // spec for containment edges
...

Node Format

The keyword "*Vertices [number of nodes]" is the starting point for the nodes section. New nodes and references to existing nodes can be defined. The formats are as follows.

New Node

[node number] [node name] [longitude] [latitude] [optional parameters]:

  • node number – unique node number (1, 2, 3, ...). Successive numbering of nodes is obligatory.
  • node name – unique name consisting of letters a..zA..Z and digits 0..9.
  • longitude, latitude – coordinates of the node. All values can be entered, but real world coordinates are: -180 <= longitude <= 180, 0 <= latitude <= 90.

Optional parameters:

  • popID – identifier of a population of the node. This parameter may be used repeatedly.
  • popCount – number of individuals living in the node. This parameter may be used repeatedly. The associated popID is the last mentioned one.

Example:

1 Berlin 13.398889 52.500556 popID men popCount 1682900000 popID women popcount 1753500000

Node Reference

[node number] [node URI]:

  • node number – unique node number (1, 2, 3, ...). Successive numbering of nodes is obligatory.
  • node URI – URI of the node in STEM. If the URI starts with stem://org.eclipse.stem/node/geo/region/, this prefix can be omitted.

Examples:

1 stem://org.eclipse.stem/node/geo/region/FR-IF
1 FR-IF

Edges Format

The keyword "*Edges" is the starting point for the edges section. Two types of edges can be described; they are migration edges and containment edges. The formats are as follows.

Migration Edges

[origin node number] [destination node number] popID [populationID] rate [rate]:

  • origin node number – number of the node the population migrates from. Has to be defined as node number in *Vertices.
  • destination node number – number of the node the population migrates from. Has to be defined as node number in *Vertices.
  • populationID – defines the ID of the migrating population.
  • rate - number population members migrating per day.

Optional parameters:

  • date - specification a of date at which the migration rate is different from the standard value specified in the obligatory parameters. ISO 8601 standard is used (YYYY-MM-DD). This parameter may be used repeatedly.
  • rate - migration rate for the specified date. This parameter may be used repeatedly. The associated date is the last mentioned one.

Example:

1 2 popID beef rate 1.0 date 2012-01-01 rate 10.0

Containment Edges

[containing node number] [contained node number]:

  • containing node number – number of the node that contains the other node. Has to be defined as node number in *Vertices.
  • contained node number – number of the node that is contained by the other node. Has to be defined as node number in *Vertices.

Example:

*Vertices 3
1 Berlin 1 1 popID men popCount 100 popID women popCount 110
2 Bonn 1.5 1 popID men popCount 100 popID women popCount 110
3 Germany 1.2 1.2
*Edges
1 2 popID men rate 0.1
2 1 popID women rate 0.2
3 1
3 2

Running the downloadable pajek scenario the map view should appear as shown below.

STEM PajekExample.png


Using the dialog

STEM PajekDialog.png

The dialog to import a Pajek graph from a file is shown on the right. It is available in the STEM Graph Dialog. The following parameters are available for importing.

  • Pajek File - The file from which the graph is imported. A file dialog is available to select the file.
  • Scaling Factor - A factor by which all coordinates specified in the file are scaled during import. If node has the coordinates 10.0/20.0 in the file and the scaling factor is 2.0, the node's resulting coordinates in STEM are 20.0/40.0.
  • Node Size - In STEM each imported node appears as a square for visualization. This parameter specifies the edge length of the squares for all imported nodes.
  • Use global Region Names - If selected, the URIs for the imported nodes will be of the type stem://org.eclipse.stem/node/geo/region/*****. This has the advantage, that the nodes can be accessed by just using that last part of the URI *****. This option should only be used if node names specified in the Pajek file are unique and do not occur in other STEM graphs. If not selected, the node URIs will contain the graph's URI.
  • Move Nodes to Containers - If selected, all nodes that are contained by another node from a different graph will be moved close to this container. That means that coordinates specified for these nodes in the Pajek file will be ignored.

Tutorial

A tutorial on how to import a Pajek graph that contains discrete migration events for a STEM graph is available at Import Discrete Transportation Events. Discrete events can be used to model commodity flows, e.g. the transportation of beef from slaughterhouses to supermarkets in order to model the spread of a foodborne disease.

Contributors

The PajekNetGraphGenerator was created and developed by the Department of Biological Safety of the Federal Institute for Risk Assessment in Germany.

Armin A. Weiser, Matthias Filter, Christian Thöns
Dept. Biological Safety 
Federal Institute for Risk Assessment
12277 Berlin
Germany

Copyright © Eclipse Foundation, Inc. All Rights Reserved.