BlueConfig File Format

Objective

BlueConfigs are text files used for storing circuit and simulation parameters, (like stimulus injection and simulation output), and paths to files (like morphologies, models).

History

Has been around since at least 2007

File Format

The general structure is a C-like braced system. The config file contains one or more configuration Sections, that have a Type, and a Name. Within an entry, there are multiple key value pairs: the key is a series of ASCII characters, followed by whitespace (space and tab characters). These are called Values, also composed of ASCII characters.

Type0 Name0                 |         |
{                           |         |
    key0 value0   | Value   | Section |
    key1 value1             |         |
}                           |         |
Type1 Name1                           | File
{                                     |
    key0 value0                       |
    key1 value1                       |
}                                     |

Note

Names can currently be reused for multiple stanzas.

Note

Commenting out the Type Name comments out the following block. EX:

#Foo Bar
{
  #Nothing in here is used
}

Section Types

The following section types are defined for BlueConfigs. The authoritative parser lives in Neurodamus.

  • Run

    Defines the versioning, data sources, and simulation-wide parameters

  • Conditions

    Specifies global parameters.

  • Stimulus

    Describes one pattern of stimulus that can be injected into multiple locations using one or more StimulusInject sections

  • StimulusInject

    Pairs a Stimulus with a Target so that the stimulus is applied to the cells that make up the target.

  • Modification

    (Deprecated, will need a new version for SONATA) Applies the necessary steps to simulate a chosen tissue manipulation from those available

  • Report

    Controls data collection during the simulation to collect things like compartment voltage.

  • Connection

    Adjusts the synaptic strength between two sets of cells.

  • Electrode

    Will not be used for SONATA config.

  • Projection

    Designed to take into account axons projecting to and from different areas of the brain. It can also be used to take gap junctions into account. In order to enable a Projection, you also need to activate it with Stimulus and StimulusInject blocks. For details see BlueConfig Projection example. For Sonata config, projections are additional edge files in "networks" (circuit_config file).

Run

Defines the versioning, data sources, and simulation-wide parameters

Key

Description

Type

Required

Unit

ForwardSkip

Run without Stimulus or Reports for a given duration using a large timestep. This is to get the cells past any initial transience.

int (non-negative)

False

CurrentDir

| Simulation execution directory. Will be prepended to other Run parameters if they do not use an absolute path: E.g.: OutputRoot, TargetFile. | Default value: Path to BlueConfig | NOTE: Relative paths are not allowed, the only exception being “.” strictly for test jobs.

abspath

False

Restore

Restore the state of the simulation saved in the provided file/directory.

string

False

MeshPath

Location of mesh files for 3D visualization

abspath

False

NumBonusFiles

Temporary support for allowing synapses from external sources (e.g. Thalamocortical input). Superseded by Projection section

int

False

TargetFile

Parameter giving location of custom user targets stored in the named file, referred to as user.target in the remainder of the document. The file contains descriptions for Cell/Compartment/Section targets. Use of relative paths is discouraged and DEPRECATED, unless CurrentDir is also set.

path

True

Note

Description field for adding details about the simulation. Recommended topics might be purpose of the sim, changes from other sims, paper references if trying to duplicate experiments, etc.

string

False

Duration

Simulation duration

float (non-negative)

True

ms

Version

Revision number of bglib to take from git/svn

string

False

OutputRoot

Location where output files should be written, namely spikes and reports. Prefer using absolute paths. Relative paths are interpreted relative to CurrentDir.

abspath

True

Time

Time of config creation/modification with format hh:mm:ss

time

False

RNGMode

Random number generator used for simulation : MCellRan4 (default) or Random123

string

False

Simulator

Simulator engine used for execution : NEURON (default) or CORENEURON

string

False

ModelBuildingSteps

Number of steps used by NEURON to construct a model. If a given network model can not be loaded into memory, NEURON can divide a model into smaller pieces and then pass all pieces to CORENEURON for simulation. For example, with given number of compute nodes if NEURON can only simulate half of the model (due to limited memory), ModelBuildingSteps can be set to 2.

int (positive)

False

KeepModelData

Keep the CORENEURON model data if this parameter is set to True. By default, the CORENEURON model data is deleted after simulation except for the save/restore process.

string

False

gitPath

URL from where bglib simulation files can be downloaded

string

False

ElectrodesPath

File path

abspath

False

METypePath

Location of metypes or CCells, the files defining morphological and electrical combinations used by the simulation.

abspath

True

MorphologyPath

Location of morphology files. If MorphologyType is not specified, ‘/ascii’ is automatically appended to the path and morphology loading assumes ‘asc’ type (legacy handling).

abspath

True

MorphologyType

Type of morphology files. This is required if you wish to specify the morphology type (asc, swc, h5, hoc). NOTE: if this option is set, then MorphologyPath is not suffixed with ‘/ascii’ anymore. For example: MorphologyPath /path/to/swc/v1 MorphologyType swc

string

False

Save

name of the file or directory where the state of the simulation will be stored after a duration of “Time”.

path

False

BioName

string

False

CircuitPath

Root location of the circuit, where start.target and cell geometry info (MVD / SONATA nodes) should be found.

abspath

False

CellLibraryFile

Specify the file containing cell geometry info. Default is start.ncs. “start.ncs” is searched within nrnPath, “circuit.mvd3” within CircuitPath. Any other value is interpreted as a path to a format readable by MVDtool, namely SONATA nodes.

string

False

BaseSeed

For random sequences, the BaseSeed is added in order to give the user the capacity to change the sequences.

int

False

StimulusSeed

A non-negative integer used for seeding noise stimuli and any other future stochastic stimuli. Default is 0.

int

False

IonChannelSeed

A non-negative integer used for seeding stochastic ion channels. Default is 0.

int

False

MinisSeed

A non-negative integer used for seeding the Poisson processes that drive the minis. Default is 0.

int

False

SynapseSeed

A non-negative integer used for seeding stochastic synapses. Default is 0.

int

False

nrnPath

| Location of connectvity file(s): SONATA Edges or older Syn2, Nrn formats. | Option: specify a population name after the path, format “path:population”. | NOTES: | - For compat reasons, users can provide a path to a folder, in which case it will look for SONATA files, followed by syn2 and nrn. Such usage is DEPRECATED and file paths should be used. | - DEPRECATED: Having start.ncs or start.target in this location. | They should be within CircuitPath instead.

abspath

True

RunMode

Optional parameter which currently accepts WholeCell and LoadBalance as a valid values. Neurons will be distributed round-robin, otherwise. If CORENEURON simulator is being used, WholeCell should be used.

RunMode

False

Dt

Duration of a single integration timestep

float (positive)

True

ms

ProspectiveHosts

deprecated, use ModelBuildingSteps instead

int

False

BonusSynapseFile

Use Projection instead. Name of additional files containing synapse data. This is useful for introducing synapses from “external” sources such as long range connections from other brain regions.

abspath

False

CircuitTarget

Parameter which will restrict the neurons instantiated to those in the named target. Target can be from start.target or target file given in the TargetFile parameter. Option: specify a population name before the target name, format “population:target_name”.

string

False

ExtracellularCalcium

Extracellular calcium concentration. This parameter, together with the uHill parameter of synapses, is used to scale the U parameter of synapses, and is working for py-neurodamus not hoc-neurodamus.

float (non-negative)

False

mM

SecondOrder

Selects the NEURON/CoreNEURON integration method. This parameter sets the NEURON global variable h.secondorder. The allowed values are ‘0’ for default implicit backward euler, ‘1’ for Crank-Nicolson and ‘2’ for Crank-Nicolson with fixed ion currents. For more info see: https://www.neuron.yale.edu/neuron/static/py_doc/simctrl/programmatic.html?highlight=second%20order#secondorder

int

False

V_Init

Initial voltage value for cells. This value is used in finitialize() function in Neuron.

float

False

mV

Celsius

Temperature of the simulation in degrees centigrade (celsius).

float

False

degrees centigrade

SpikeLocation

The spike detection location. Can be either ‘soma’ for detecting spikes in the soma or ‘AIS’ for detecting spikes on the AIS.

string

False

SpikeThreshold

The spike detection threshold. A spike is detected whenever the voltage in the spike detection location goes over the spike threshold value.

float

False

mV

MinisSingleVesicle

Spont minis to use a single release vesicle, as discussed in BBPBGLIB-660.

boolean(0/1)

False

RandomizeGabaRiseTime

A global parameter to skip randomizing the GABA_A rise time in the helper functions.

string

False

Conditions

Specifies global parameters.

Key

Description

Type

Required

Unit

randomize_Gaba_risetime

An option to skip randomizing the GABA_A rise time in the helper functions, the same as RandomizeGabaRiseTime in the Run section.

string

False

SYNAPSES__minis_single_vesicle

An option to release only a single vesicle at Spont. events, as discussed in BBPBGLIB-660, the same as MinisSingleVesicle in the Run section.

boolean(1/0)

False

SYNAPSES__init_depleted

An option to initialize synapses in depleted state.

boolean(1/0)

False

cao_CR_GluSynapse

cao_CR (the extracellular calcium concentration) is a GLOBAL parameter in GluSynapse.mod, that ensures the correct derivation of Ca++ related currents. Setting it to the same value as ExtracellularCalcium in the Run section is crucial (but not yet automatic) in plasticity simulation.

float (non-negative)

False

mM

Stimulus

Describes one pattern of stimulus that can be injected into multiple locations using one or more StimulusInject sections

Key

Description

Type

Required

Unit

Name

string

False

Pattern

Type of stimulus: Linear, RelativeLinear, Pulse, Subthreshold, Noise, SynapseReplay, Hyperpolarizing, ReplayVoltageTrace, SEClamp, ShotNoise, RelativeShotNoise, AbsoluteShotNoise, OrnsteinUhlenbeck, RelativeOrnsteinUhlenbeck. NOTE: Sinusoidal, NPoisson and NPoissonInhomogeneus are deprecated. For poisson stims, please consider using replay on projections instead

Pattern

True

Delay

Time when stimulus commences

float

True

ms

Mode

Current is used for most stimuli. Exceptions include ReplayVoltageTrace and SEClamp which then use “Voltage” instead. Conductance stimuli use “Conductance”, and some stimuli (ShotNoise, AbsoluteShotNoise and OrnsteinUhlenbeck) can be injected as either Current or Conductance.

Mode

True

AmpStart

The amount of current initially injected when the stimulus activates

float

False

nA

AmpEnd

The final current when a stimulus concludes. Used by Linear

float

False

nA

Duration

Time length of stimulus duration

float

True

ms

PercentStart

For RelativeLinear, the percentage of a cell’s threshold current to inject at the start of the injection

float

False

PercentEnd

For RelativeLinear, the percentage of a cell’s threshold current to inject at the end of the injection

float

False

PercentLess

For Subthreshold stimulus, each cell has a defined amount of current which will trigger one spike in 2 seconds. This pattern will use that defined current and scale it according to the PercentLess value

float

False

Width

For Pulse Stimulus, the duration in ms of a single pulse

float

False

ms

Variance

For Noise stimuli, the variance around the mean of current to inject as a percentage of a cell’s threshold current

float

False

MeanPercent

For Noise and RelativeShotNoise stimuli, the mean value of current to inject as a percentage of a cell’s threshold current. For RelativeOrnsteinUhlenbeck stimulus, the mean value of conductance to inject as a percentage of a cell’s inverse input resistance. Used instead of ‘Mean’ in Noise stimulus

float

False

Format

Format

False

Frequency

For Pulse Stimulus, the frequency of pulse trains

float

False

Hz

Voltage

For SEClamp, specifies the membrane voltage the targeted cells should be held at.

float

False

mV

File

File path

abspath

False

Offset

For Pulse Stimulus, a std dev value each cell will apply to the Delay in order to add variation to the stimulation. Not for SONATA config.

float

False

SpikeFile

For SynapseReplay, indicates the location of the file with the spike info for injection. The weights of the replay synapses are set at t=0 ms and are not altered by any delayed connection.

path

False

Dt

For Noise, ShotNoise, RelativeShotNoise, AbsoluteShotNoise, OrnsteinUhlenbeck and RelativeOrnsteinUhlenbeck stimuli, the timestep of the current or conductance to inject.

float

False

ms

Mean

For Noise, AbsoluteShotNoise and OrnsteinUhlenbeck stimuli, the mean value of current or conductance to inject.

float

False

nA or uS

Electrode

Electrode section to use

string

False

RiseTime

For ShotNoise, RelativeShotNoise and AbsoluteShotNoise stimuli, the rise time of the bi-exponential shots

float

False

ms

DecayTime

For ShotNoise, RelativeShotNoise and AbsoluteShotNoise stimuli, the decay time of the bi-exponential shots

float

False

ms

Seed

For ShotNoise, RelativeShotNoise, AbsoluteShotNoise, OrnsteinUhlenbeck and RelativeOrnsteinUhlenbeck stimuli, override the random seed (to introduce correlations between cells)

int

False

Rate

For ShotNoise stimulus, the rate of Poisson events

float

False

Hz

AmpMean

For ShotNoise stimulus, the mean of gamma-distributed amplitudes

float

False

nA

AmpVar

For ShotNoise stimulus, the variance of gamma-distributed amplitudes

float

False

nA^2

AmpCV

For RelativeShotNoise and AbsoluteShotNoise stimuli, the coefficient of variation (sd/mean) of gamma-distributed amplitudes

float

False

SDPercent

For RelativeShotNoise stimulus, the std dev of the current to inject as a percent of a cell’s threshold current. For RelativeOrnsteinUhlenbeck the std dev of the conductance to inject as a percent of a cell’s inverse input resistance.

float

False

Lambda

Deprecated: For NPoisson Stimulus to configure the random distribution

float

False

Weight

Deprecated: For NPoisson Stimulus. The strength of the created synapse

float

False

NumOfSynapses

Deprecated: For NPoisson Stimulus. The number of synapses to create. Not for SONATA config.

int (non-negative)

False

SynapseConfigure

Deprecated: For NPoisson Stimuli, allows the user to specify a Synapse object type which is available to the simulator. The default is ExpSyn. Possible values are : ProbAMPANMDA_EMS, ProbGABAAB_EMS, and ExpSyn.

string

False

Sigma

For AbsoluteShotNoise and OrnsteinUhlenbeck stimuli, the std dev of the current or conductance to inject.

float

False

nA or uS

Reversal

For Conductance mode stimuli, the reversal potential of the conductance injection. Sets the holding voltage of the underlying SEClamp.

float

False

mV

Tau

For OrnsteinUhlenbeck and RelativeOrnsteinUhlenbeck stimuli, the relaxation time constant of the Ornstein-Uhlenbeck process.

float

False

ms

StimulusInject

Pairs a Stimulus with a Target so that the stimulus is applied to the cells that make up the target.

Key

Description

Type

Required

Unit

Stimulus

Named stimulus

string

True

Source

Name of a target in start.target or user.target to replay spikes from The target can be set as <population_name>:<target_name>. If not defined default target is None and all cells are selected for replay.

target

False

Target

Name of a target in start.target or user.target to receive the stimulation The target can be set as <population_name>:<target_name>

target

True

Type

Type of the connectivity between the Source and Target of the StimulusInject. Used to select the proper edge manager in neurodamus-py. Valid types are: [`Synaptic`, `GapJunction`, `NeuroGlial`, `GlioVascular`, `NeuroModulation`] Default value is `Synaptic`. Additional types can be specified in the ConnectionTypes member of additional plug-in Engines. For example the PointEngine included in neurodamus-py defines also `Point` type. This nomenclature of the types is specific to Neurodamus and corresponds to the SONATA types [`chemical`, `electrical`, `synapse_astrocyte`, `endfoot`, `neuromodulatory`].

string

False

Modification

(Deprecated, will need a new version for SONATA) Applies the necessary steps to simulate a chosen tissue manipulation from those available

Key

Description

Type

Required

Unit

GifParamsPath

Description: Define path to .h5 file where parameters for simplified GIF neurons are stored

abspath

False

Type

Name of one of the available Tissue Manipulations. Currently available: TTX, ConfigureAllSections

string

True

Target

Name of the target in start.target or user.target to receive the manipulation

target

True

SectionConfigure

A snippet of python code to perform one or more assignments involving section attributes, for all sections that have all the referenced attributes. The wildcard %s represents each section. Multiple statements are separated by semicolons. E.g., “%s.attr = value; %s.attr2 *= value2”.

string

True for ConfigureAllSections

Report

Controls data collection during the simulation to collect things like compartment voltage.

Key

Description

Type

Required

Unit

Scaling

For Summation reports, the user can specify the handling of density values: “None” disables all scaling, “Area” (default) converts density to area values. This makes them compatible with values from point processes such as synapses.

string

False

Electrode

Name of an electrode section

string

False

Target

Defines what is to be reported. Note that cell targets versus compartment targets can influence report behavior. The same applies to section targets, that could request axon, dend, or apic inside the user.target file. Note that CoreNEURON has limited support for section targets (i.e., only one subtarget is allowed per section target).

target

True

StartTime

Time to start reporting

float

True

Format

ASCII, SONATA or Bin defining report output format

string

True

ReportOn

The NEURON variable to access

string

True

Dt

Frequency of reporting in milliseconds

float

True

EndTime

Time to stop reporting

float

True

Type

Compartment, Summation, or Synapse. Compartment means that each compartment outputs separately in the report file. Summation will sum up the currents and compartments to write a single value to the report (soma target) or sum up the currents and leave them in each compartment (compartment target). Synapse indicates that each synapse will have a separate entry in the report.

string

True

Unit

String to output as descriptive test for unit recorded. Not validated for correctness

string

True

Connection

Adjusts the synaptic strength between two sets of cells.

Key

Description

Type

Required

Unit

Destination

Target defining postsynaptic cells

target

True

SynapseConfigure

Provide a snippet of hoc code which is to be executed on the synapse objects created under this Connection section

string

False

Delay

The weight modifications of this Connection can be applied after a specified delay has elapsed. Note that only Weight modifications are applied and no other features of Connection sections

float

False

NeuromodDtc

Only applicable to `NeuroModulation` projections. It can be used to override the {{neuromod_dtc}} values between the selected {{Source}} and {{Destination}} neurons. It represents the decay time constant of the neuromodulator concentration at the target synapse

float

False

ms

NeuromodStrength

Only applicable to `NeuroModulation` projections. It can be used to override the {{neuromod_strength}} values between the selected {{Source}} and {{Destination}} neurons. It represents the amount of increase of the neuromodulator concentration at the synapse when an incoming neuromodulatory event (i.e., a spike in the virtual pre-synaptic neuron) is transmitted to the target synapse

float

False

µM

Source

Target defining presynaptic cells

target

True

Weight

Scalar used to adjust synaptic strength

float

False

SpontMinis

During simulation, Synapses created under this Connection section will spontaneously trigger with the given rate

float

False

ModOverride

Changes the synapse helper files used to instantiate the synapses in this connection. A synapse helper initializes the synapse object and the parameters of the synapse model. By default, AMPANMDAHelper.hoc / GABAABHelper.hoc are used for excitatory / inhibitory synapses. The value of this field determines the prefix of the helper file to use e.g. “Newfun” would lead to NewfunHelper.hoc being used. Exceptionally, passing “GluSynapse” will lead to GluSynapse.hoc being used. That helper will use the additional parameters of the plastic synapse model read from the SONATA edges file using Neurodamus. This is required when using the GluSynapse.mod model and will fail for other models, or if the parameters are not present in the edges file.

string

False

SynDelayOverride

Value to override the synaptic delay time originally set in the edge file, and to be given to netcon object.

float

False

ms

Electrode

Will not be used for SONATA config.

Key

Description

Type

Required

Unit

y

y position

float

True

um

x

x position

float

True

um

z

z position

float

True

um

Version

version of the reader to use

int

False

File

file name under the electrodePath directory

path

True

Projection

Designed to take into account axons projecting to and from different areas of the brain. It can also be used to take gap junctions into account. In order to enable a Projection, you also need to activate it with Stimulus and StimulusInject blocks. For details see BlueConfig Projection example. For Sonata config, projections are additional edge files in “networks” (circuit_config file).

Key

Description

Type

Required

Unit

Path

Location of data files with additional connectivity info Option: specify a population name after the path, format “path:population”.

abspath

True

Type

Distinguishes between “Synaptic”, “GapJunction”, and “NeuroModulation” projections. If omitted, Synaptic is assumed.

string

False

NumSynapseFiles

The number of synapse files. To be made obsolete once better metadata handling is added.

int

False

Source

Optional. Provides new gids if the connection sources are external to the main circuit

target

False

PopulationID

Defines an ID for the population for RNG seeding purposes. Default is 0, which is used by circuit connections (e.g. nrn.h5) so using 0 for projections would create overlapping streams. User should set it to 1 or greater. Should they be unique? It depends on if the projections should be considered as coming from the same ‘source’. If the user creates multiple projections from a population to different destination groups, then it would make sense to reuse the same populationID. This should be considered a temporary fix until we fully support SONATA population labels NOTE: With MCellRan4, the max value accepted is 255 and for Random123 it is 65535.

int (positive)

False

AppendBasePopulation

When using a Sonata projection file containing legacy gid-offset connections, in order to merge connections with base connectivity and avoid creating a new PopulationID (implying different seeding), this option should be set to 1. Default is disabled (0)

int

False