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.
Difference between revisions of "Importing a Pajek Graph"
(→Contributors) |
(→New Node) |
||
| (38 intermediate revisions by 5 users not shown) | |||
| Line 1: | Line 1: | ||
| − | == | + | ==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 [http://www.eclipse.org/stem/download_sample.php?file=MultiPopulationExample_PajekGraphs.zip Multi-Population Pajek Graph Example]. | |
| − | + | ==Create a Pajek file== | |
| − | + | To create a Pajek file, download and use this ODS spreadsheet document [https://wiki.eclipse.org/images/b/bb/STEM_Pajek_Creator.zip here]. | |
| + | Open the ODS spreadsheet, with LibreOffice [https://de.libreoffice.org/] and activate the macro element. | ||
| + | Important: To do this, you must be running JRE [http://www.oracle.com/technetwork/java/javase/downloads/jre8-downloads-2133155.html] on your system. | ||
| − | + | After modifying the spreadsheet, you can export the file as Pajek file. <br> | |
| + | Please click for this: | ||
| + | <ol> | ||
| + | <li>File</li> | ||
| + | <li>ExportToPajek (The first option in the opened dialogue)</li> | ||
| + | <li>Save it on your system (it will automatically be saved as a .net file) </li> | ||
| + | </ol> | ||
| − | + | ||
| + | It is also possible to open and modify a Pajek file with a text editor, but it is much simpler to use the recommended spreadsheet. | ||
| − | + | == File Format == | |
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | ||
| − | + | 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 Libre Office spreadsheet produces a .net file that is in the correct format to be imported into STEM via the PajekNetGraphGenerator, which is available in the graph creation dialogue of STEM: [[Image:STEMDefineANewGraphIcon.png|50px]] | |
| − | The | + | 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 | + | The keyword "*Vertices [number of nodes]" is the starting point for the nodes section. New nodes and references to existing nodes can be defined. Available formats appear below. |
| − | === | + | === 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 | ||
| − | + | Note: when using a Demographic Population Model in STEM you need only declare the main population name e.g. human in the list of nodes. You can refer to individual population subgroups (e.g., men, women) when declaring the populationID for the edges. | |
| − | + | ||
| − | + | ||
| − | * | + | === 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 | ||
| − | + | Note: the optional parameters are not automatically implemented when you use the pajek graph in STEM. They are all specified in a single trigger which will be located in the "Triggers" folder of your project. The name of the trigger usually starts with "List platform:/resource" and ends with the name of your pajek graph. The trigger must be dragged into your scenario in order for the optional parameters to be implemented. | |
| − | + | [[Image:STEMTriggerOptionalParametersPajekGraph.JPG|400px]] | |
| − | + | === 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 | ||
| − | + | To edit the pajek graph in STEM, right-click on the graph and then select "display", as described here [https://wiki.eclipse.org/Visualizing_and_Editing_Graphs] and shown below: | |
| − | + | [[Image:STEM_PajekExample.png|600px]] | |
| − | + | == Using the dialog == | |
| − | * | + | [[Image:STEMDisplayPajekGraphGenerator.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. | ||
| + | *Use Absolute Migration Rates- If selecting “yes” then the rate will be the exact number of individuals that are moving across migration edges. If selecting “no”, then a rate from 0-1 must be specified to move a proportion of individuals across the migration edge. Note that if a stochastic solver is used, then this will be a probability of movements, rather than an exact proportion. | ||
| − | + | == 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. | |
| − | + | == Common Errors == | |
| + | If you get an “out of bounds” exception, then it is likely that the numbers in your nodes do not match those used in your edges. | ||
| + | If you are using data from an Excel spreadsheet and copying into the Libre Office spreadsheet, make sure you choose “paste special” > “unformatted code” > “unitext”. | ||
| + | == 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 | |
| − | + | ||
Latest revision as of 17:47, 18 October 2018
Contents
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.
Create a Pajek file
To create a Pajek file, download and use this ODS spreadsheet document here. Open the ODS spreadsheet, with LibreOffice [1] and activate the macro element. Important: To do this, you must be running JRE [2] on your system.
After modifying the spreadsheet, you can export the file as Pajek file.
Please click for this:
- File
- ExportToPajek (The first option in the opened dialogue)
- Save it on your system (it will automatically be saved as a .net file)
It is also possible to open and modify a Pajek file with a text editor, but it is much simpler to use the recommended spreadsheet.
File Format
STEM allows users to create a custom graph using a format similar to the Pajek ([3]) format. The Libre Office spreadsheet produces a .net file that is in the correct format to be imported into STEM via the PajekNetGraphGenerator, which is available in the graph creation dialogue of STEM: 
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. Available formats appear below.
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
Note: when using a Demographic Population Model in STEM you need only declare the main population name e.g. human in the list of nodes. You can refer to individual population subgroups (e.g., men, women) when declaring the populationID for the edges.
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
Note: the optional parameters are not automatically implemented when you use the pajek graph in STEM. They are all specified in a single trigger which will be located in the "Triggers" folder of your project. The name of the trigger usually starts with "List platform:/resource" and ends with the name of your pajek graph. The trigger must be dragged into your scenario in order for the optional parameters to be implemented.
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
To edit the pajek graph in STEM, right-click on the graph and then select "display", as described here [4] and shown below:
Using the dialog
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.
- Use Absolute Migration Rates- If selecting “yes” then the rate will be the exact number of individuals that are moving across migration edges. If selecting “no”, then a rate from 0-1 must be specified to move a proportion of individuals across the migration edge. Note that if a stochastic solver is used, then this will be a probability of movements, rather than an exact proportion.
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.
Common Errors
If you get an “out of bounds” exception, then it is likely that the numbers in your nodes do not match those used in your edges. If you are using data from an Excel spreadsheet and copying into the Libre Office spreadsheet, make sure you choose “paste special” > “unformatted code” > “unitext”.
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