Skip to main content

Data Format Specification

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

Supported File Types​

TypeExtensionDescription
CSV.csvComma-separated values
TSV.tsv, .txtTab-separated values
GraphML.graphmlXML-based graph format
Calendar CSV.csvAuto-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 PurposeDescriptionExample Values
SourceThe originator of the relationshipjohn.doe@company.com, Arya
TargetThe recipient of the relationshipjane.smith@company.com, Gendry

Optional Columns​

Column PurposeDescriptionExample Values
WeightStrength/frequency of connection1, 5.5, 100
Date/TimeTimestamp (enables timeline playback)See Date Formats below
DepartmentGroup for color codingEngineering, Stark
NetscoreNumeric value for edge weight0.75, 85
LatitudeGeographic latitude for map display51.5074
LongitudeGeographic 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​

ColumnDescription
IdUnique identifier matching Source/Target values in edge file

Attribute Columns​

Any additional columns become node attributes. Common examples:

ColumnDescriptionExample Values
LabelDisplay nameArya Stark, Jon Snow
HouseFaction/groupStark, Lannister, Targaryen
RolePosition/functionLord, Knight, Hand of the King
RegionLocationThe 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 ColumnsAdded Columns
Source, Target, Weightsource_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​

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:

FileDescription
got-edges.csvGame of Thrones character interactions
got-nodes.csvCharacter attributes (for pairing with edges)
marvel-network.graphmlMarvel 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)