4. Importing CSV data

Click on the Import CSV Data button in the property editor widget (see the section called “Property”) to launch the import process.

To help user during the import data process Tulip provides an import wizard which is a three paneled dialog with configuration options.

The first panel allows the user to configure the source file location, the characters encoding, the field delimiter character and the text delimiter character.

The second panel allows the user to define the line range, which columns to import and to define the type of data for each column.

The third panel allows the user to select how to import data in the graph.

You can find CSV import tutorials here Section 3, “Importing data from CSV files”.

Source file settings panel

The first panel allows the user to configure the source file location, the characters encoding, the field delimiter character, the text delimiter character.

Figure 4.1. Source file settings panel

Source file settings panel

The purpose of each labeled component is explained below:

  1. The source file location field : this field indicates the location of the file to parse. To change the source file click on the “...” button.

  2. The file encoding selection menu : this drop down menu provides a list of encoding schemes for the characters in the text file.

  3. The data orientation : this check-box allows the user to invert rows and columns i.e to treat rows as columns and columns as rows in next steps.

  4. The separator selector : this field allows the user to define the characters used to separate data value fields within each row. Select a separator in the list or input a custom separator and press the enter key to validate your input.

  5. The text delimiter selector : this field allows the user to define the characters used as start and end delimiter for data value fields. Select a delimiter in the list or input a custom and press the enter key to validate your input. Separated value files often additionally define a character used to indicate the start and end of a data element which should be considered a single text entry. This strategy allows the inclusion of text entries which include the value separator.

    For example, a file which is structured as a comma separated value file, could use the double quotation mark to delimit text values and would then be able to include text values such as: 'Zoe, Mark, Sally'.

  6. The preview area : this area displays a preview of the file as it will be interpreted with these settings.

Data selection panel

The second panel allows the user to define the line range, which columns to import and to define their data types.

Figure 4.2. Data selection panel

Data selection panel

The purpose of each labeled component is explained below:

  1. Use first line tokens as column names : use the elements in the first line as default names for the columns. If checked the first line will be skipped during the import process.

  2. The line range spinbuttons : these two spin buttons allow the user to select the start and end rows for the data import. The spin boxes can be used either by typing a new value in the text entry area where the numbers are displayed, or by using the mouse button to click on the up arrow to increase the number and the down arrow to decrease the number. For instance, if the text file contained a large header area with meta information, this header could be excluded from the data imported by increasing the number of the starting, "From", line.

  3. The columns configuration area : this area allows the user to configure each column detected in the file. Any single column can be excluded from the data imported by clicking in the checkbox under its name to remove the check mark. User can rename a column by editing the field containing it's original name. You can't input the same name of another column. The data type of a column can be changed using the combo-box under it's name.

  4. The preview area : this area displays a preview of the file as it will be interpreted with these settings. If a column isn't selected it will not appear in the preview.

  5. The number of preview lines spinbutton : allows the user to increase the number of preview. If unchecked all the file will be displayed.

Import method panel

The third panel allows the user to select how to import data in the graph.

Figure 4.3. Import method panel

Import method panel

The purpose of each labeled component is explained below:

  1. The import methods list

  2. The configuration area for the selected import method

Currently you can import data on:

  • New entities (nodes).
  • New relations (edges).
  • Existing entities (nodes).
  • Existing relations (edges).

New entities (nodes)

Create a new entity (node) for each row in the file and import the data of selected columns on created entities (nodes).

New relations (edges)

Create a new relation (edge) for each row and import the data of selected columns on created relations (edges).

A relation is defined by it's source entity id and it's destination entity id. For each row we compare source and destination ids to graph entities ids. If the source and destination ids correspond to existing entities ids a new relation is created between those entities. If there is no entities in the graph with such ids you can force the creation of missing entities with the “Create missing entities” option.

The example below represents a graph with four entities “a”, “b”, “c”, “d” and two relations : “a” -> “b” and “b” -> “c”.

a;b

b;c

Existing entities (nodes)

Import the data of selected columns on existing entities (node).

For each row we compare the destination entity id to graph entities ids. If there is a correspondence we import the row data on the first matching entity. If there is no entity with such id you can force the creation of a new entity with the “Create missing entities” option.

Existing relations (edges)

Import selected columns on existing relations(edges).

For each row we compare the destination relation id to graph relations ids. If there is a correspondence we import the row data on the first matching relation.