Library Element Data_importEdgesFromMatrix

This article provides information for the code based import of edges from an Excel or CSV matrix if the file contains edges of one class, the source node identifying attribute values in the header column, the target node identifying attribute values in the header row and an attribute value to be mapped as cell label. The edge class name, the source and target node class and source and target node identifying attribute names are defined as function arguments. This allows for the automatic creation of edges of one class from a matrix, connecting the header column elements with the header row elements for each matrix cell that contains a value unequal 0 or empty. By means of a rule argument, the values in the connecting matrix cells can be mapped to an edge attribute. Thus, a matrix-based import of attributed edges is possible.

The import is done using the Data_importEdgesFromMatrix library function.

Data structure

Use the library function Data_importEdgesFromMatrix to import a list of edges if your import data matrix is structured like this:

  • the first column of the data area contains source identifying attribute values. The other source node identifiers (class name and identifying attribute name) are defined as function arguments.
  • the first row of the data area contains target identifying attribute values. The other target node identifiers (class name and identifying attribute name) are defined as function arguments.
  • the connecting matrix cells contain a value if an edge is to be created from the source to the target node. If a cell is empty or 0, no edge is to be created. The cell value is mapped to a property of the created edge which is defined as a function argument.
Part 1 Part 2 Part 3
Product A 1 2
Product B 3
Product C 6  5 4

An exemplary matrix containing identifying attribute value of the source nodes (first column) and the target nodes (first row). If the connecting matrix field contains a value different from 0 (or empty), an edge having the matrix cell value as attribute value is to be created.

If your data looks different please see this article to find the correct import function for your data scheme.

Library function scheme

When adding the library function Data_importEdgesFromMatrix from the Libraries pad to a rule sheet (*.grg file) the created code looks as follows. To execute the function, it needs to be included in a sequence as explained later.

  Data_importEdgesFromMatrix( FILE_NAME, FIRST_ROW, FIRST_COLUMN, LAST_ROW, LAST_COLUMN, TABLE_NAME, SEPARATOR, ONLY_FIRST_EDGE, EDGE_CLASS, SRC_N_CLASS, SRC_ATTR, TRG_N_CLASS, TRG_ATTR, ATTR )

Arguments:

  • FILE_NAME – string type argument defining the (relative) path to the Excel or CSV file.
    FILE_NAME path can be relative to the project’s path. If you added your data file DataFile.xlsx to the project folder, Data the FILE_NAME will be “..\\..\\Data\\DataNodes.xlsx”.
  • FIRST_ROW, FIRST_COLUMN, LAST_ROW, LAST_COLUMN – int type argument defining the data area of the sheet to be imported.
    Rows and columns are denoted as integers. Rows and columns are denoted as integers. To import the area from cell A1 to I4 the denotation would be 1,1,4,9. The first row and the first column containing the identifying attribute values of the source and target nodes have to be included in the data area. To import the complete sheet set LAST_ROW and LAST_COLUMN to -1,-1. The importer will automatically detect the last row and/or column containing data. Only one data area can be imported per import sequence.
  • TABLE_NAME – string type argument defining the exact name of the worksheet in an Excel file.
    For CSV files this must be an empty string (“”).
  • SEPARATOR – string type argument defining the separator used in a CSV file (e.g. “;” or “|”).
    For Excel files, this must be an empty string (“”).
  • ONLY_FIRST_EDGE – boolean type argument defining if multiple source/target node matches should be considered or not.
    If set to false, the importer will create edges for all found pairs of source and target node candidates. If true an edge will be created only for the first found pair (which exactly is not determined). Scroll to the end of the article to find a detailed explanation.
  • EDGE_CLASS – string type argument defining the class of the edges to be created.
    The string must match a class name defined in the metamodel. All imported edges will be of this class.
  • SRC_N_Class – string type argument defining the class of the source nodes.
    The string must match a class name defined in the metamodel. All source nodes will be of this class.
  • SRC_ATTR – string type argument defining the identifying attribute of the source nodes.
    The string must match an attribute name defined in the metamodel. This will be the identifying attribute for all source nodes.
  • TRG_N_Class – string type argument defining the class of the target nodes.
    The string must match a class name defined in the metamodel. All target nodes will be of this class.
  • TRG_ATTR – string type argument defining the identifying attribute of the target nodes.
    The string must match an attribute name defined in the metamodel. This will be the identifying attribute for all target nodes.
  • ATTR – string type argument defining the edge attribute which is mapped to the matrix cell value. The string must match an attribute name defined in the metamodel of the EDGE_CLASS.

Calling of the library function in sequence

Assume that the edges data list to be imported looks like this, either as an Excel or as a CSV table:

A B C D E
1
2 Part 1 Part 2 Part 3
3 Product A 1 2
4 Product B 3
5 Product C 6 5 4

We import this list to an existing graph that contains the Product and Part nodes required as source and target nodes (3 Product nodes with the id “Product A”, “Product B” and “Product C”, 3 Part nodes with id “Part 1”, “Part 2”, “Part 3”). Two examples of how to import this data using the library function in a sequence are given below. The sequence names can be freely defined by the user. The Excel and the CSV files are stored in the projects Data folder. For both files, the data is imported from cell B2 to the last row and column containing data. The import data area (blue area) MUST include the header row and header column. The worksheet of the Excel file is named MatrixSheet. The separator in the CSV file is “;”. As all possible edges shall be created, ONLY_FIRST_EDGE is set to false. All created edges will be of the edge class Contains. The source nodes are of the class Product and identified by the attribute id. The target nodes are of the class Part and identified by the attribute id. The matrix cell value will be mapped to the edge attribute quantity.

 sequence importEdgesFromExcelFile {
   Data_importEdgesFromMatrix("..\\..\\Data\\DataFile.xlsx", 2, 2, -1, -1, 
   "MatrixSheet", "", false, "Contains", "Product", "id", "Part", "id", "quantity" )
 } 
sequence importEdgesFromCsvFile{
   Data_importEdgesFromMatrix("..\\..\\Data\\MatrixDataFile.csv", 2, 2, -1, -1, 
   "", ";", false, "Contains", "Product", "id", "Part", "id", "quantity" )
} 

Given that the input data graph only contained the 6 nodes mentioned above, the result of this import could look like this:

Graph view resulting from matrix-based import of attributed edges using the import library function ImportTypedFixedAttributedAdjMatrix
Resulting graph file using the Data_importEdgesFromMatrix library function

The sequence is fixed to import “Contains” edges from Product nodes to Part nodes. The matrix cell value is imported as value of the edge attribute “quantity”, which is shown as edge label in the figure above.

Explanation for ONLY_FIRST_EDGE argument:
In order to create an edge, the importer has to find a pair of source and target nodes. It might be the case that the importer finds more than one pair of node candidates, for example, if the identifying attribute is not unique. Imagine the following scenario:

Source node class: BlueNode
Source attribute: id
Source attribute value: 1
Target node class: RedNode
Target attribute: id
Target attribute value: 2

ONLY_FIRST_EDGE = false
Import Edge Soley

ONLY_FIRST_EDGE = true
Import Edge Soley

Was this article helpful?