SWC specification documentation

The SWC file format is a human- and machine-readable format for representing digital reconstructions.

Latest specification

swc_specification.

Governance

Development of the SWC file format is directed by an elected governing board.

Contact

For information about neuromorphological file format’s development and governance, contact nmadmin@gmu.edu

License

The SWC file format is licensed under the Creative Commons Attribution-NoDerivatives 4.0 International License.

Contents

swc_specification

Information about the SWC file specification. A video describing the specification can be found here: https://vimeo.com/853224668?share=copy

Specification of standard SWC - adapted from (3)

An SWC file (S.W.C. encodes for the last names of its initial designers Ed Stockley, Howard Wheal, and Robert Cannon) is a text file that starts with an optional header section in which each line starts with the symbol #. Some SWC-variants use this section to store information about the data in an orderly fashion, others treat is as a free-text field.

Below the header section, a points matrix with 7 columns follows. It contains the points traced along the neuronal tree. The seven numbers in each row are separated by spaces, and have the following meaning:

Column index	Field	Description
1	Index	Sample identifier. A sequential positive integer.
2	Type	Type identifier. A positive integer.
3	X	X-position in micrometers
4	Y	Y-position in micrometers
5	Z	Z-position in micrometers
6	R	Radius in micrometers (half the node thickness)
7	Parent	Parent sample identifier.

The basic set of types used in NeuroMorpho.org SWC files are:

Type	ID	Description
undefined	0	Structure type unknown or unspecified
soma	1	Soma of a neuron
axon	2	Axon of a neuron
basal dendrite	3	Basal dendrite of a neuron
apical dendrite	4	Apical dendrite of a neuron
custom	5	Custom type of cell component
unspecified neurite	6	An unspecified part of a neuron
glia processes	7	Glial processes
custom	>7	Custom type of cell component

Parent defines how points are connected to each other. In a tree, multiple points can have the same ParentID. The first point in the file must have a ParentID equal to -1, which represents the root point. Parent samples must be defined before they are being referred to. By counting how many points refer to the a given parent, the number of its children can be computed.

Soma representation

The soma in SWC can consist of a single root point or multiple points, the first of which is the root. The single-point representation approximates the soma as a sphere of radius R and centered in X, Y, Z. The multi-point representation approximates the soma as a sequence of nodes akin to a neurite branch. Note that representing the soma as a contour tracing of the soma perimeter or a series of contour tracings approximating the soma surface is not consistent with the SWC standard.

SWC Example - adapted from Ascoli et al, 2001

This extremely simplified neuronal structure was obtained by extensive pruning of a dentate gyrus granule cell in (4). The left panel shows the digital SWC representation: every node compartment is described by a row containing: - A label (ID or Index, the same numbers reported next to the branches in the right panel - A tag (T or Type, 1 for soma, 3 for dendrite), - Cartesion positions (X,Y,Z in micrometers), - Radius (R) and - Connectivity (C or Parent, representing the label of parent, -1 indicates no parent)

Syntax of basic SWC reconstruction in EBNF - from Nanda et al, 2018

newline = “:raw-latex:`\n`” ;

letter = “A” | “B” | “C” | “D” | “E” | “F” | “G” | “H” | “I” | “J” | “K” | “L” | “M” | “N” | “O” | “P” | “Q” | “R” | “S” | “T” | “U” | “V” | “W” | “X” | “Y” | “Z” | “a” | “b” | “c” | “d” | “e” | “f” | “g” | “h” | “i” | “j” | “k” | “l” | “m” | “n” | “o” | “p” | “q” | “r” | “s” | “t” | “u” | “v” | “w” | “x” | “y” | “z” ;

digit = “0” | “1” | “2” | “3” | “4” | “5” | “6” | “7” | “8” | “9” ;

symbol = “[” | “]” | “{” | “}” | “(” | “)” | “<” | “>” | “‘” |’”’ | “=” | “|” | “.” | “,” | “;” ;

integer = [+|-] digit{digit} ;

double = integer [“.”] {integer} ;

character = letter | double | symbol | “_” | ” “;

header = “#” character {character} newline [“#” character {character} newline] ;

Index = integer ;

Type = integer ;

X = double ;

Y = double ;

Z = double ;

Radius = double ;

Parent = integer ;

node = Index ” ” Type ” ” X ” ” Y ” ” Z ” ” Radius ” ” Parent ;

neuron_tree = node newline {node newline} ;

SWC = [header] neuron_tree ;

Header fields defined in Cannon et al 1998

The original publication that introduced SWC (4) described the header as containing the following fields, although these are not considered a required component of SWC:

Field	Description
ORIGINAL_SOURCE	File type delivered by digitisation equipment
CREATURE	Species from which the cell came
REGION	Brain region
FIELD/LAYER	Location within region
TYPE	Cell type
CONTRIBUTOR	Name, initials, organisation, e.g. Turner DA, Duke
REFERENCE	Where the data has been published
RAW	File name of original data
EXTRAS	Files containing further information on this cell
SOMA_AREA	Area of soma (in mm2)
SHRINKAGE_CORRECTION	x, y and z correction factors
VERSION_NUMBER	To identify different versions of the same raw data
VERSION_DATE	Date this version was created (yyyy-mm-dd)
SCALE	Used internally to record applied shrinkage corrections

References

Ascoli GA, Krichmar JL, Nasuto SJ, Senft SL. Generation, description and storage of dendritic morphology data. Philos Trans R Soc Lond B Biol Sci. 2001;356(1412):1131-1145. doi:10.1098/rstb.2001.0905 (PMCID: PMC1088507)
Nanda S, Chen H, Das R, et al. Design and implementation of multi-signal and time-varying neural reconstructions. Sci Data. 2018;5:170207. Published 2018 Jan 23. doi:10.1038/sdata.2017.207 (PMCID: PMC5779069)
https://neuroinformatics.nl/swcPlus/ “SWC plus (SWC+) format specification”
Cannon RC, Turner DA, Pyapali GK, Wheal HV. An on-line archive of reconstructed hippocampal neurons. Journal of Neuroscience Methods. 1998 Oct;84(1-2):49-54. DOI: 10.1016/s0165-0270(98)00091-0. PMID: 9821633.
https://en.wikipedia.org/wiki/Extended_Backus%E2%80%93Naur_form
http://neuromorpho.org/SomaFormat.html Soma format representation in NeuroMorpho.Org as of version 5.3

Contributors

Lydia Ng
Giorgio Ascoli
Bengt Ljungquist
Sumit Nanda

Governing Board

Board Composition

The SWC format governing board has five members:

1. NeuroMorpho.Org representative
A senior representative affiliated with and appointed by NeuroMorpho.Org with expertise in neuroinformatics as well as microanatomy of neurons and glial cells. The representative communicates NeuroMorpho.Org’s ideas for development to the board, but also conveys decisions to the NeuroMorpho.Org development team to implement changes in the format to currently published and future reconstructions.
2. Allen Institute representative
A senior representative affiliated with and appointed by the Allen Institute, that has expertise in neuroinformatics as well as microanatomy of neurons and glial cells. The representative communicates the ideas of the Allen Institute for development to the board, but also conveys decisions to concerned stakeholders within the Allen Institute.
3. Microanatomy expert
An expert in neuroscience and microanatomy with long-time experience and insight in the workflow of creating digital reconstructions. Appointed by election.
4. Computational modeling expert
An expert in computational neuroscience outside of NeuroMorpho.Org and Allen Institute with long-time experience in computational modeling of neurons using the SWC format. Appointed by election.
5. INCF advisor
An advisor affiliated with and appointed by INCF that can provide an international perspective and broad community feedback to the development of the format.

Until the first election has taken place, the governing board will consist of Giorgio A. Ascoli, Bengt Ljungquist, Sumit Nanda, and Lydia Ng, serving as interrim stewards. Appointment of fifth member by INCF pending.

Governing board member election

This section describes the process by which the two electable positions of the governing board are elected.

The SWC specification Governing Board consists of five members, each representing different stakeholders and serving a term of two years at a time. Elections for the two electable positions, microanatomy expert and computational modeling expert, will be announced to the NeuroMorpho.Org mailing list and Twitter feed as well as by the Allen Institute and INCF in their communication channels relevant to the position that is up for election. Each year, an election is held to replace the electable board member who has completed their two-year term or to fill a position that has become vacant. The election is confidential and is handled by the board, and the process is as defined below. The other three members will be appointed by the respective organizations at their discretion.

1. Nomination

The opportunity for nomination is announced at least three weeks before the election takes place.
Nominations will be made through an anonymous electronic form. It is thus possible and allowed to nominate oneself.
Each nomination will include nominee’s email and name as well as a motivation why the nominee would be a good addition to the board.
Current board members cannot be nominated.
The nomination period will be at least 3 weeks and maximum of 5 weeks.
After the nomination period has ended, the current governance board will:
1. Make a list of potential nominees and confirm that the entries are valid, i.e. constitute a person that has a background in the area of required expertise, without judging it.
2. Using provided email, contact all nominees to confirm that they accept their nomination and whether they wish to change the provided motivation.
3. Make a list of confirmed nominees, including incumbent board member, provided they are not stepping down, and publish it through the same communication channels as for the call for nominations.
4. Start the call for votes.

2. Voting

The ballot will include all confirmed nominees as well as their provided motivation. The ballot will state when the voting period ends.
The election is open to all members of the SWC format user community, the ballot will require the voter to provide name, email address, and a brief description of the relationship to the SWC format (e.g. using for computational modeling, art, or other purposes, or producing reconstructions, tool developer, etc). The email will be confirmed through an automatic process to filter out any invalid votes.
Each voter may only cast one vote, including themselves, if nominated.
From the start of the voting process, the voting will be active for at least four weeks and a maximum of five weeks.
After voting has closed the governing board will:
1. Remove invalid votes, including duplicates.
2. For each vote, check the the description of relationship to the SWC format to confirm that it is valid.
3. Count votes and make a list of candidates ranked by the number of votes.

3. Counting and selection

The governing board will contact all candidates in the ranked list in order.
1. If the nominee accepts the election, the election is completed. If the nominee declines, the next candidate on the ranked list will be contacted.
If two top candidates get an equal number of votes, a special election will be held:
1. All voters from the original election will be contacted and encouraged to vote in the special election.
2. The list of candidates is limited to those with an equal number of votes.
3. The special election period will be one week.

4. Announcement of results

Following the completed election, the electee will be announced in the same channels used for the call to nominations.
The electee starts their position at the governing board directly after the announcement.