MVD version 3

Warning

This file format is deprecated and has been superseded by the SONATA Node File.

History

The MVD version 2 files are text based files that contain the properties of the neurons in a circuit. It doesn’t support 3 dimensional rotations of morphologies, and thus cannot be used for anatomically realistic circuits. The MVD version 3 format should be able to handle these circuits and allow for larger circuits. In addition, a structured file format is required, to reduce the need to parse string data formats, and to preserve numbers without having to rely on string conversion routines and differences.

Objective

The format must be extensible as we foreseen the appearance of new fields beyond the current classifications of cells.

File Format

Fields

The file represents a description of a group of cells. It contains, for each cell, the values of a set of properties or fields.

Note

No field is mandatory and new ones may be added in the future. The container API provides a way to query the presence or absence of fields.

The following is a list of all of the known fields used in the current pipeline by different tools:

  • position: X, Y, Z, stored as 3 floats. The unit is micrometer.

  • orientation: A unit quaternion, X Y Z W stored as 4 floats.

  • etype: electrical type.

  • mtype: morphological type.

  • synapse_class: inhibitory/excitatory.

  • morphology: morphology name (i.e. the .h5 or .asc filename without the extension).

  • exc_mini_frequency: mini-frequency of a cell in response to an incoming excitatory connection, with a value that depends on the receiving cell’s layer.

  • inh_mini_frequency: mini-frequency of a cell in response to an incoming inhibitory connection, with a value that is constant across all layers.

Additional fields can be added (optionals) as static parameters for the circuit generation. These parameters are located under the group /circuit (e.g /circuit/seeds )

Container

MVD3 uses HDF5 as the structured data container. It is the HPC standard for saving data, and there are libraries for accessing it with C++ and Python. Floating-point numeric properties (like position and orientation) are stored as individual datasets under /cells/*. Text-based properties where most of the entires will be duplicated (like etype, mtype and synapse_class) are stored as two datasets:

  • One containing the list of all unique used values under /library/*

  • One containing an index into the first one for each cell under

    /cells/properties/*

Note

String types are currently encoded as variable length UTF-8 (H5T_CSET_UTF8 in HDF5)

version is an attribute defining major and minor version of the format. format is a string attribute defining the format itself.

The following is an example of the structure of an HDF5 containing all known cell properties:

/                                       Group                            DataType
/version                                Attribute. value being [3, 0]    (an array with [mayor, minor])
/format                                 Attribute. value being "MVD"     (vlen string)
/circuit                                Group
/circuit/seeds                          Dataset {4}                      double float
/cells                                  Group
/cells/orientations                     Dataset {N, 4}                   double float
/cells/positions                        Dataset {N, 3}                   double float
/cells/properties                       Group
/cells/properties/etype                 Dataset {N}                      unsigned int
/cells/properties/morphology            Dataset {N}                      unsigned int
/cells/properties/mtype                 Dataset {N}                      unsigned int
/cells/properties/synapse_class         Dataset {N}                      unsigned int
/cells/properties/exc_mini_frequency    Dataset {N}                      double float
/cells/properties/inh_mini_frequency    Dataset {N}                      double float
/library                                Group
/library/etype                          Dataset {E}                      vlen string
/library/morphology                     Dataset {M}                      vlen string
/library/mtype                          Dataset {T}                      vlen string
/library/synapse_class                  Dataset {S}                      vlen string

Where the cardinality is:

N - number of cells.
M - number of unique morphologies.
E - number of unique e-types.
T - number of unique m-types.
S - number of unique synapse classes.

To which can be added the following optional circuit parameters:

/circuit                        Group
/circuit/seeds                  Dataset {1,4} (double float)

Consumers

  • TouchDetector. Required fields are positions, orientations, morphology

  • Functionalizer. Required fields are positions, orientations, morphology etype, mtype, synapse_class

  • Brion.

  • Neurodamus. Required fields are exc_mini_frequency, inh_mini_frequency, mtype