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.
-
Defines the versioning, data sources, and simulation-wide parameters
-
Specifies global parameters.
-
Describes one pattern of stimulus that can be injected into multiple locations using one or more StimulusInject sections
-
Pairs a Stimulus with a Target so that the stimulus is applied to the cells that make up the target.
-
(Deprecated, will need a new version for SONATA) Applies the necessary steps to simulate a chosen tissue manipulation from those available
-
Controls data collection during the simulation to collect things like compartment voltage.
-
Adjusts the synaptic strength between two sets of cells.
-
Will not be used for SONATA config.
-
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 |