Data Format Specification

This document describes the supported file formats and import options for the ONA Dashboard.

Supported File Types

Type	Extension	Description
CSV	.csv	Comma-separated values
TSV	.tsv, .txt	Tab-separated values
GraphML	.graphml	XML-based graph format
Calendar CSV	.csv	Auto-detected when Organizer + Attendees columns are present

Import Options

The ONA Dashboard supports four import workflows:

1. Single File Import (CSV/TSV)

Upload a single file containing edge data with Source and Target columns.

2. Calendar Import (Auto-Detected)

Upload a calendar export CSV containing Organizer and Attendees columns. The dashboard automatically detects the calendar format and explodes each meeting into individual Organizer → Attendee edges.

• Attendees are split on semicolons (;) or commas (,)
• Declined meetings are filtered out
• All other columns (Subject, Start, End, Duration, Location, etc.) are preserved on each edge
• No manual pre-processing required

Example input row:

Organizer,Attendees,Subject,Start,Duration
elena@co.com,"xena@co.com; sam@co.com; clara@co.com",Team Sync,2026-02-06T08:00:00Z,60

Becomes 3 edges:

elena@co.com → xena@co.com  (Subject: Team Sync, Duration: 60)
elena@co.com → sam@co.com   (Subject: Team Sync, Duration: 60)
elena@co.com → clara@co.com (Subject: Team Sync, Duration: 60)

3. GraphML Import

Upload a .graphml file exported from tools like Gephi, NetworkX, or yEd. The dashboard extracts:

• Node IDs from <node> elements
• Edges from <edge> elements with source and target attributes
• Edge attributes from nested <data> elements (e.g., weight)

4. Edge + Node File Import

Upload two separate files:

• Edge File (required): Contains relationships between entities
• Node File (optional): Contains attributes for each node (e.g., department, role, house)

This approach is ideal when you want to:

• Keep node metadata separate from edge data
• Update node attributes without re-importing edges
• Add rich node attributes for colouring and filtering

---

Edge File Format

Required Columns

Column Purpose	Description	Example Values
Source	The originator of the relationship	john.doe@company.com, Arya
Target	The recipient of the relationship	jane.smith@company.com, Gendry

Optional Columns

Column Purpose	Description	Example Values
Weight	Strength/frequency of connection	1, 5.5, 100
Date/Time	Timestamp (enables timeline playback)	See Date Formats below
Department	Group for color coding	Engineering, Stark
Netscore	Numeric value for edge weight	0.75, 85
Latitude	Geographic latitude for map display	51.5074
Longitude	Geographic longitude for map display	-0.1278

Example Edge File

Source,Target,Weight
Arya,Gendry,43
Arya,Sandor,46
Jon,Samwell,31
Tyrion,Jaime,36

---

Node File Format

Node files provide attributes for each entity in your network.

Required Column

Column	Description
Id	Unique identifier matching Source/Target values in edge file

Attribute Columns

Any additional columns become node attributes. Common examples:

Column	Description	Example Values
Label	Display name	Arya Stark, Jon Snow
House	Faction/group	Stark, Lannister, Targaryen
Role	Position/function	Lord, Knight, Hand of the King
Region	Location	The North, King's Landing

Example Node File

Id,Label,House,Role
Arya,Arya Stark,Stark,Assassin
Jon,Jon Snow,Stark,Lord Commander
Tyrion,Tyrion Lannister,Lannister,Hand of the King
Gendry,Gendry Baratheon,Baratheon,Blacksmith
Sandor,Sandor Clegane,None,Warrior

How Node Attributes Are Merged

When you import both edge and node files, node attributes are added to each edge row:

Original Edge Columns	Added Columns
Source, Target, Weight	source_House, target_House, source_Role, target_Role

This allows you to:

• Color nodes by source_House in the Department dropdown
• Filter by node attributes
• Analyze cross-group connections

---

GraphML Format

GraphML is an XML format for graph data. Example structure:

<?xml version="1.0" encoding="UTF-8"?>
<graphml xmlns="http://graphml.graphdrawing.org/xmlns">
  <key attr.name="weight" attr.type="double" for="edge" id="weight"/>
  <graph edgedefault="undirected">
    <node id="Arya"/>
    <node id="Gendry"/>
    <edge source="Arya" target="Gendry">
      <data key="weight">43.0</data>
    </edge>
  </graph>
</graphml>

Converting CSV to GraphML

Use the included Python script to convert edge/node CSVs to GraphML:

cd Data
python ../Python/csv_to_graphml.py got-edges.csv -n got-nodes.csv -o got-network.graphml

See Python/csv_to_graphml.md for full documentation.

---

Updating Node Attributes

After importing a dataset, you can update node attributes without re-importing edge data:

1. Go to Load Data page
2. Find your dataset in the list
3. Click Update Nodes button
4. Upload a new node file with updated attributes
5. The node attributes will be re-merged with your edge data

This is useful for:

• Adding new attributes (e.g., adding "House" after initial import)
• Correcting attribute values
• Testing different groupings

---

Date/Time Column

Auto-Detected Column Names

The following column names are automatically recognized as date columns:

• Date, DateTime, Timestamp
• Created, CreatedAt
• Time, SendDate, EventDate

Supported Date Formats

ISO 8601 (Recommended)

2022-03-04
2022-03-04 20:09
2022-03-04T20:09:00Z

European Format (Day/Month/Year)

4/03/2022
04/03/2022 20:09

Unix Timestamps

1646423340        (seconds)
1646423340000     (milliseconds)

---

Sample Datasets

The Data/ folder includes sample datasets for testing:

File	Description
got-edges.csv	Game of Thrones character interactions
got-nodes.csv	Character attributes (for pairing with edges)
marvel-network.graphml	Marvel character network in GraphML format

---

Troubleshooting

Node attributes not appearing

• Ensure the Id column in your node file matches the Source/Target values exactly (case-sensitive)
• Check that node file is CSV/TSV format matching your edge file

GraphML import fails

• Verify the file is valid XML
• Check that <edge> elements have source and target attributes
• Ensure node IDs referenced in edges exist as <node> elements

Timeline not animating

• Verify date column is selected in sidebar
• Check browser console for date parsing messages
• Ensure dates span more than one unique value

Map background disabled

• Requires both Latitude and Longitude columns
• Values must be valid coordinates (-90 to 90 for lat, -180 to 180 for lon)