Spreadsheet and GraphML format

This page has the detailed rules behind Importing and exporting.

How a file is recognised

There are no filename rules. The columns identify the file, and column names are matched without regard to case.

• A file of nodes starts with Label (or ID).
• A file of connections starts with From, then To.

To put several values in one cell, separate them with a pipe: housing|mutual aid.

A file of nodes

Column	Becomes
Label	The node’s name. Required, unless the file has an ID column instead.
ID	Your own key, used to match From and To. With no Label column, the ID is also the name. Kept as a property.
Type	One tag per distinct value, in a tag group named after the column.
Tags	One tag per distinct value.
Description	A property.
Anything else	A measure if the values are numbers, a tag if they’re true/false, otherwise a property.

Label,Type,Tags,Households
Bristol Renters Union,tenant union,housing|rent,420
Acme Housing Trust,funder,housing,0
Somewhere Community Centre,venue,,85

A file of connections

Column	Becomes
From	The node the connection starts at, by label (or ID). Required.
To	The node it goes to. Required. Several names separated by | make one connection each.
Type	One connection type per distinct value.
Direction	directed, undirected or mutual. See Direction.
Amount, Strength or another number	With a Type column, the first numeric column is suggested as the value of each row’s connection: funds, 5000 becomes one “funds” connection with the value 5000. Without a Type column, it becomes a connection type of its own that records a value.
Date, Year, Start date, End date	The connection’s dates: when it happened (Date, Year) and the period it holds (Start date, End date). Each cell is a year, month or day: 2024, 2024-06, 2024-06-15. A cell that isn’t a date gives that row no date.
Label, Description, ID	Properties.
Tags	As for nodes.
Anything else	As for nodes.

From,To,Type,Direction,Strength
Acme Housing Trust,Bristol Renters Union,funds,directed,0.8
Bristol Renters Union,Somewhere Community Centre,meets at,undirected,
Bristol Renters Union,Acme Housing Trust|Somewhere Community Centre,allies,mutual,

The last row creates two connections, one to each name in To.

How From and To are matched

By label, unless the file of nodes has an ID column. Then From and To must hold those IDs. Matching tries the ID, then the exact label, then the label ignoring case.

Matching only happens within one import. IDs aren’t remembered, so importing the same files again creates a second copy.

Before you import, the mapping step tells you about rows that won’t work, with examples:

• a From or To that isn’t in the file of nodes
• a row connecting a node to itself
• a label shared by more than one node.

Those rows are skipped and the rest import. A node row with no label, or a repeated ID, is also skipped.

What each column can be

The tool reads a sample of rows from across the file and only offers options that fit:

If a column…	it can’t be…
holds free text	a measure or a single tag
holds numbers	a tag, or tags (one per value)
holds true/false	a measure, or tags (one per value)
has | in its cells	a measure, tag, connection type, label, ID or Direction
doesn’t hold directed/undirected/mutual	Direction
isn’t numbers	the value of each row’s connection type
isn’t years, months or days	a date
is empty	anything but property or ignore

• Measures and tags are only offered in a file of nodes, and connection types only in a file of connections. Property and Ignore are always offered.
• Empty columns start as Ignore. Columns whose values don’t fit one kind start as Property.
• The tool reads a sample, so an odd value further down might not be seen. That cell is dropped at import and the rest of its row still imports.
• A column of true/false values becomes a tag that rows with “true” get. Rows with “false” import, but without the tag. The warnings say so.
• The warning about personal data is based on column names, such as “email”, “phone” or “address”.

One tag per value

Tags (one per value) and Connection types (one per value) create one tag or type for each distinct value in the column. A column with more than 24 distinct values (12 in GraphML) is kept as a single property instead, and the summary says so.

Whether the new tags form a group depends on the data:

• If no cell in the column holds a |, each node has one value, so the tags go in a tag group named after the column. A node can have only one tag from a group, so clustering by the whole group gives each node one cluster.
• If any cell holds a |, nodes can have several, so the tags stay ungrouped.

If a value matches a tag the map already has, that tag is used, and keeps its own group. If a cell names two tags from the same group, only the first is applied, and the summary lists the ones left out.

Type on nodes and on connections

A node’s Type is a category, such as “tenant union”, and becomes a tag. A text value can’t be a measure, because a measure is a number.

A connection’s Type is the relationship itself, such as “funds”, and becomes a connection type. That’s what draws arrows, and what you filter and weight by in Visualise mode.

Direction

In Kumu, each connection has its own direction. Here, direction belongs to the connection type, so every “funds” connection reads the same way. When an import creates a connection type:

• it takes the direction its rows agree on;
• if rows disagree, it’s created undirected, and the summary tells you.

If a Type value links to a connection type the map already has, its direction is never changed. The summary tells you if your rows disagree with it.

Either way, each connection keeps the original Direction cell as a property. From → To order is always kept as written.

What doesn’t carry over exactly

• Per-connection direction: see above.
• Strength is a numeric column like any other. Next to a Type column, it’s the value of each row’s connection, so a row stays one connection. If you map a numeric column to a connection type of its own instead, each row becomes two connections, one per type.
• Connection Label, Description and ID, and node Description, become properties.
• A file of connections on its own can’t be imported. It needs the file of nodes in the same import.

GraphML

A GraphML file already says which nodes each connection joins. The mapping step lists its attributes, and each can be linked to an existing measure, tag or connection type, created as a new one, kept as a property, or ignored. A node attribute can also be the node’s label. An attribute with a few repeated values (such as “type”: “follows” or “jaccard”) is split into one row per value. A GraphML edge with several attributes mapped to connection types becomes one connection per type.

When you import a GraphML file exported from the same map, its attributes are suggested as links to that map’s existing measures, tags and connection types.