File & data formats¶

.syn¶

ISF custom file format to store synapse locations onto a morphology. Only valid with an associated Morphology file.

For each synapse, it provides the synapse type and location onto the morphology. Each row index corresponds to its synapse ID, providing a link to a corresponding .con file. The location is encoded as a section ID and x (a normalized distance along the section), to be consistent with NEURON syntax.

To create a functional network (i.e., known presynaptic origin), it must be used in conjunction with an associated .con file.

Example:

# Synapse distribution file
# corresponding to cell: morphology.hoc
# Type - section - section.x

VPM_E1  112     0.138046479525
VPM_E1  130     0.305058053119
VPM_E1  130     0.190509288017
VPM_E1  9       0.368760777084
VPM_E1  110     0.0
VPM_E1  11      0.120662910562
...

.con¶

ISF custom file format to store connectivity data. To be used in conjunction with an associated .syn file and Morphology file. It numbers each synapse, and links it to its associated presynaptic cell type and ID. A .syn file and Morphology file provide the anatomical realization of a morphology embedding into a network. The addition of a .con file makes possible to construct a functional realization, as it allows linking the synapses to presynaptic cells of a dense connectome model, which in turn allows to assign cell type specific activation patterns to each synapse. ISF’s workflow is designed to create these files in tandem, so they always co-exist.

Example:

# Anatomical connectivity realization file; only valid with synapse realization:
# synapse_ralization_file.syn
# Type - cell ID - synapse ID

L6cc_A3 0       0
L6cc_A3 1       1
L6cc_A3 2       2
L6cc_A3 3       3
L6cc_A3 4       4
L6cc_A3 4       5
...

.param¶

ISF custom file format to save JSON-like ASCII data for cell parameters, network parameters, and activity data. The .param format is valid Python code, but differs from JSON, as it allows trailing comma’s, single quotes, and tuples. JSON does not. .param files can be read using build_parameters.

Cell parameters¶

.param file to store biophysical parameters of a cell. Includes a reference to a Morphology file, biophysical properties of the cell per morphological structure (e.g. soma, dendrite, axon initial segment …), and basic simulation parameters. Morphology structure labels should match those inferred from the morphology file.

Parameters under the key *.mechanisms.range are range mechanisms, and their name should match the name of a loaded .mod file. Note that the mechanism name in .mod files are defined in the NEURON block as a SUFFIX or POINTPROCESS, and have little to do with the file name.

Each range mechanism must have the key spatial, and its value must match one of the supported spatial profiles in ISF. All spatial profiles except for "uniform" require additional parameters that need to be defined for a given range mechanism. E.g. the exponential profile expects the parameters offset, linScale, _lambda, xOffset. Distances for these spatial profiles are calculated in terms of distance to soma. If "distance": "relative" is passed for a range mechanism, the distance dependency is scaled by the maximum distance of all sections with the same label. E.g. for a simple dendrite, this means that all distance metrics are scaled with the length of the longest dendrite. This is useful for setting scaling parameters without necessarily having to worry about the exact dimensions of the neurites beforehand. Spatial profiles are evaluated on a segment-by-segment basis: the segment center is used as the distance dependency of each spatial profile, and channels are uniform within a single segment.

All other remaining parameters of a range mechanism must be valid attributes of a NEURON segment, such as passive properties, or parameters defined in PARAMETER blocks in loaded .mod files. Typically, channels only expose their conductance density as a parameter, but there is nothing stopping you from also exposing e.g. \(\tau_m\) and \(m_\infty\). The simplest range mechanism entry in a neuron parameter file is thus:

# The range mechanism name, defined as a SUFFIX in a loaded .mod file
'Ca_LVAst': {
    # non-parametrized profile - simply uses gbar
    'spatial': 'uniform',
    # the conductance density parameter, exposed in the PARAMETER block of the .mod file
    'gCa_LVAstbar': 0.00462
    },

Conductance densities are given in \(S/cm^2\), spatial coordinates and distances in \(\mu m\), and time in \(ms\).

To access different structures of a cell:

>>> cell_parameters.neuron.keys()
['Myelin', 'Soma', 'AIS', 'Dendrite', 'ApicalDendrite']

Example:

{
    'info': {...},
    'neuron': {
        'filename': 'getting_started/example_data/anatomical_constraints/*.hoc',
        'Soma': {
            'properties': {
                'Ra': 100.0,
                'cm': 1.0,
                'ions': {'ek': -85.0, 'ena': 50.0}
                },
            'mechanisms': {
                'global': {},
                'range': {
                    'pas': {
                        'spatial': 'uniform',
                        'g': 3.26e-05,
                        'e': -90},
                    'Ca_LVAst': {
                        'spatial': 'uniform',
                        'gCa_LVAstbar': 0.00462},
                    "Ih": {
                        "spatial": "exponential",
                        "distance": "relative",
                        "gIhbar": 0.0002,
                        "offset": -0.8696,
                        "linScale": 2.0870,
                        "_lambda": 3.6161,
                        "xOffset": 0.0},
                    'Ca_HVA': {...},
                    ...,}}},
        'Dendrite': {...},
        'ApicalDendrite': {...},
        'AIS': {...},
        'Myelin': {...},
        'cell_modify_functions': {
            'scale_apical': {'scale': 2.1}
        },
    'sim': {
        'Vinit': -75.0,
        'tStart': 0.0,
        'tStop': 250.0,
        'dt': 0.025,
        'T': 34.0,
        'recordingSites': ['getting_started/example_data/apical_proximal_distal_rec_sites.landmarkAscii']}
}

Network parameters¶

The .param format is used to store network parameters, describing the presynaptic cells and their synaptic activations. Only valid with an associated Morphology morphology file, .syn file, and .con file.

For each presynaptic cell type in the network, this following information is provided:

The synapses key of each presynaptic cell type contains the following information:

Each synapses.receptors.<receptor type> in synapses.receptors contains the following information:

Example:

{
"info": {
  "date": "11Feb2015",
  "name": "evoked_activity",
  "author": "name",
},
"network": {
  "cell_type_1": {
    "cellNr": 20
    "celltype": {
      'pointcell': {
        'distribution': 'PSTH_poissontrain',
        'intervals': [(0, 274.7), (274.7, 295), (295, 945), (945, 1145)],
        'offset': 0.0,
        'rates': [1.4357770278148136, 1.0890981376857083, 1.7588271630292192, 1.4357770278148136]
      }
    },
    "synapses": {
      "receptors": {
        'glutamate_syn': {
          'delay': 0.0,
          'parameter': {
            'decayampa': 1.0,
            'decaynmda': 1.0,
            'facilampa': 0.0,
            'facilnmda': 0.0,
            'tau1': 26.0,
            'tau2': 2.0,
            'tau3': 2.0,
            'tau4': 0.1},
          'threshold': 0.0,
          'weight': [1.5480934081344324, 1.5480934081344324]
          }
      },
      "releaseProb": 0.5,
      "connectionFile": "presyn_cells.con",
      "distributionFile": "syn_locations.syn"
    }
  },
  "cell_type_2": {...},
  ...
}

Activity data¶

.param files are used to store activity data. Activity data can be defined by the following activity distributions:

A single Activity data file must specify the activity data for a single cell type, for all anatomical areas. Anatomical areas can e.g. be columns in the barrel cortex (\(A1\) - \(D4\) & \(\alpha\) - \(\delta\)), or hippocampal subfields (\(CA1\) - \(CA4\)). If you do not want to make a distinction between individual anatomical areas in the model system you are using, or it simply doesn’t make sense to do so, it is fine to set this value to a single area. In that case, the parameter file below would contain only one entry.

Example:

{
"celltypeA_area1": {
"distribution": "PSTH",
"intervals": [(0.0,1.0),(1.0,2.0),(2.0,3.0),(3.0,4.0),(4.0,5.0),(5.0,6.0),(6.0,7.0),(7.0,8.0),(8.0,9.0),(9.0,10.0),(10.0,11.0),(11.0,12.0),(12.0,13.0),(13.0,14.0),(14.0,15.0),(15.0,16.0),(16.0,17.0),(17.0,18.0),(18.0,19.0),(19.0,20.0),(20.0,21.0),(21.0,22.0),(22.0,23.0),(23.0,24.0),(24.0,25.0),(25.0,26.0),(26.0,27.0),(27.0,28.0),(28.0,29.0),(29.0,30.0),(30.0,31.0),(31.0,32.0),(32.0,33.0),(33.0,34.0),(34.0,35.0),(35.0,36.0),(36.0,37.0),(37.0,38.0),(38.0,39.0),(39.0,40.0),(40.0,41.0),(41.0,42.0),(42.0,43.0),(43.0,44.0),(44.0,45.0),(45.0,46.0),(46.0,47.0),(47.0,48.0),(48.0,49.0),(49.0,50.0)],
"probabilities": [0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0062,0.0062,0.0004,0.0129,0.0062,0.0004,0.0004,0.0062,0.0004,0.0004,0.0004,0.0062,0.0062,0.0004,0.0004,0.0004],
},
"celltypeA_area2": {
"distribution": "PSTH",
"intervals": [(0.0,1.0),(1.0,2.0),(2.0,3.0),(3.0,4.0),(4.0,5.0),(5.0,6.0),(6.0,7.0),(7.0,8.0),(8.0,9.0),(9.0,10.0),(10.0,11.0),(11.0,12.0),(12.0,13.0),(13.0,14.0),(14.0,15.0),(15.0,16.0),(16.0,17.0),(17.0,18.0),(18.0,19.0),(19.0,20.0),(20.0,21.0),(21.0,22.0),(22.0,23.0),(23.0,24.0),(24.0,25.0),(25.0,26.0),(26.0,27.0),(27.0,28.0),(28.0,29.0),(29.0,30.0),(30.0,31.0),(31.0,32.0),(32.0,33.0),(33.0,34.0),(34.0,35.0),(35.0,36.0),(36.0,37.0),(37.0,38.0),(38.0,39.0),(39.0,40.0),(40.0,41.0),(41.0,42.0),(42.0,43.0),(43.0,44.0),(44.0,45.0),(45.0,46.0),(46.0,47.0),(47.0,48.0),(48.0,49.0),(49.0,50.0)],
"probabilities": [0.0004,0.0062,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0062,0.0004,0.0004,0.0004,0.0004,0.0004,0.0004,0.0062,0.0004,0.0004,0.0129,0.0062,0.0062,0.0004,0.0004,0.0004,0.0004,0.0062,0.0004,0.0004,0.0062,0.0004,0.0004,0.0004,0.0004,0.0004],
},
"celltypeA_area3": {
"distribution": "lognormal",
"mu": 1.0,
"sigma": 0.5,
"offset": 15
}
"celltypeA_area4": {
"distribution": "uniform",
"offset": 140,
"window": 50,
"activeFrac": 0.8,
}
...
}

Ongoing activity data¶

In addition to Activity data, ISF provides additional API for ongoing activity separately. Ongoing activity is modeled as a Poisson spiketrain with a certain interval.

The data format should be a two-column .csv table. The column names are ignored, and only present for clarity. The first column must be the cell type. This may include the anatomical area as a suffix, but does not need to.

Raw simulation results¶

Simulations run by simrun have a fixed folder structure. They contain a single file of somatic Voltage traces, one file of dendritic Voltage traces per recSite found in the Cell parameters, and a collection of Synapse activation and Presynaptic spike times files.

The voltage traces are written to a single .csv file (since the amount of timesteps is known in advance, at least for non-variable timesteps), but the synapse and cell activation data is written to a separate file for each simulation trial (the amount of spikes and synapse activations is not known in advance).

The amount of simulation runs per parameter configuration (i.e. the product of nSweeps and nprocs keyword arguments in any simrun function) corresponds to:

• The amount of voltage columns in the Voltage traces files

• The amount of Synapse activation files

• The amount of Presynaptic spike times files

Example:

user@host:/path/to/results/20241212-1542_seed379159821_pid209402$ ls | column
hostname_somacpu042
seed379159821_pid209402_network_model.param
seed379159821_pid209402_neuron_model.param
seed379159821_pid209402_pos_3_ID_000_sec_073_seg_000_x_0.056_somaDist_607.8_vm_dend_traces.csv
seed379159821_pid209402_pos_3_ID_001_sec_073_seg_008_x_0.944_somaDist_805.7_vm_dend_traces.csv
seed379159821_pid209402_vm_all_traces.csv
simulation_run0000_presynaptic_cells.csv
simulation_run0000_synapses.csv
simulation_run0001_presynaptic_cells.csv
simulation_run0001_synapses.csv
simulation_run0002_presynaptic_cells.csv
simulation_run0002_synapses.csv
simulation_run0003_presynaptic_cells.csv
simulation_run0003_synapses.csv
simulation_run0004_presynaptic_cells.csv
simulation_run0004_synapses.csv

Dataframes¶

The output format of various simulation pipelines are usually a dataframe. below, you find common formats used throughout ISF.

The simrun package produces output files in .csv or .npz format. many of these files need to be created for each individual simulation trial. These Raw simulation results are usually parsed into single dataframes for further analysis using a db_initializers submodule (see e.g. load_simrun_general).

Synapse activation¶

The raw output of the simrun package contains .csv files containing the synaptic activations onto a post-synaptic cell for each individual simulation trial. Each file contains the following information for each synapse during a particular simulation trial:

• type

• ID (for identifying the corresponding presynaptic cell)

• location (section ID, section pt ID, soma distance)

• dendrite label (e.g. "ApicalDendrite")

• activation times

These individual files are usually gathered and parsed into a single dataframe containing all trials for further analysis: An example of the raw and parsed format is shown below:

Raw simrun output¶

Parsed dataframe¶

Presynaptic spike times¶

The raw output of the simrun package contains .csv files containing the spike times of presynaptic cells for each individual simulation trial. Each file contains the following information for each synapse during a particular simulation trial:

• type

• ID (for identifying the corresponding synapse, and cell location)

• activation times

These individual files are usually gathered and parsed into a single dataframe containing all trials for further analysis An example of the raw and parsed format is shown below:

Raw simrun output¶

Parsed dataframe¶

Writers:

• write_presynaptic_spike_times() is used by simrun and synanalysis

  to write raw output data.

• data_base.db_initializers.load_simrun_general.init() parses these files into a pandas dataframe.

Voltage traces¶

The raw output of the simrun package contains .npz or .csv files containing the voltage traces of the postsynaptic cells. Unlike the synapse activations and spike times, it is possible for one such file to contain multiple trials.

Voltage trace .csv¶

Voltage trace .npz¶

vm_all_traces.npz:

array([[100.0, 100.025, 100.05, 100.075],
       [-61.4607218758, -61.4665809176, -61.4735021526, -61.4814187507],
       [-55.1366909604, -55.1294343391, -55.1223216173, -55.1153403448],
       [-67.1747143695, -67.1580037786, -67.1424366078, -67.1279980017]])

Voltage trace dataframe¶

The parsed dataframe is usually created by the data_base.db_initializers.load_simrun_general.init() function.

Morphology¶

ISF supports two file formats for morphologies:

• A .hoc file format

• The .swc file format

.hoc¶

NEURON [7] file format for scripting in .hoc.

The .hoc format is used for HOC scripts. HOC scripts support a variety of commands and integrate directly with NEURON. Throughout ISF, you may find some example morphologies using the HOC scripting language to define morphology. These only use a subset of .hoc commands. The information contained in this subset of HOC commands is nearly identical to the information that can be specified in .swc. The only information that this .hoc subset can capture, that cannot be captured the same way in .swc, is the connection coordinate between two sections. .hoc allows the definition of a connection between two sections as a continuous coordinate, even if this coordinate lands between two points. .swc defines connectivity in terms of point ID, and so every connection in swc necessarily connects to a point, not in-between points. For most use-cases, this difference is trivial, since sections are generally defined as a neurite between connection points, and so every connection point is at relative coordinate x=0 or x=1 anyways. One notable exception is the soma, where sections are sometimes allowed to connect at a relative coordinate that deviates from 0 and 1. Even then, ISF by default connects child sections to the soma at x=0.5 anyways, so this information is not used in ISF.

The subset of .hoc used in ISF for morphologies specifies (for each morphology section):

• The section name in a standardized format: <label>_<child_idx>

• The \((x, y, z)\) coordinates of each point per section

• The diameter of each point per section

• To which parent section each section connects, and where

Each section name follows the naming convention <label>_<child_idx>, where the label contains both a label name, and an index tracking how many sections of this label exist. For this reason, the label index starts at 1. The <child_idx> denotes the index of each child section that starts from this label. For example, the very first part of the first section of type "Dendrite" will look like: "Dendrite_1_0". Here, the 1 denotes there are so far only 1 instances of a section with label "Dendrite" All child sections of this section will start with the same string, e.g. "Dendrite_1_0_1_0" is the first child of "Dendrite_1_0_1", which is in turn the second child of "Dendrite_1_0". Other sections with the same label that are not children of "Dendrite_1_0" will e.g. look like "Dendrite_2_0*" or "Dendrite_3_0*" etc.

Connectivity between sections is defined by a line:

{connect <label>_<child_idx>(x1), <parent_label>(x2)}

This defines how the current section <label>_<child_idx> connects to its parent section. x1 and x2 denote the relative coordinates of the connection between both sections. x1 denotes where along the current section the connections occurs. Normally, x1 always equals 0, meaning the connection point is at the start of the current section. x2 denotes where along the parent section the connection occurs. This almost always equals 1 (meaning the connection is at the end of the parent section), since sections are almost always defined as a piece of neurite between two connection points. A notable example is the soma; sections may (and often do) connect at different points on the soma, and not always at the end: Soma(1.0).

Readers:

• cell_parser

• read_hoc()

Example:

{create soma}
{access soma}
{nseg = 1}
{pt3dclear()}
{pt3dadd(1.933390,221.367004,-450.045990,12.542000)}
{pt3dadd(2.321820,221.046997,-449.989990,13.309400)}
...
{pt3dadd(13.961900,210.149002,-447.901001,3.599700)}

{create BasalDendrite_1_0}
{connect BasalDendrite_1_0(0), soma(0.009696)}
{access BasalDendrite_1_0}
{nseg = 1}
{pt3dclear()}
{pt3dadd(6.369640, 224.735992, -452.399994, 2.040000)}
{pt3dadd(6.341550, 222.962997, -451.906006, 2.040000)}
...

.swc¶

SWC (Stockley-Wheal-Cannon) is a simple morphology file format, specifying for each point the:

• Point ID

• Section type

• \((x, y, z)\) coordinates

• Radius

• Parent point ID

Connectivity between sections is inferred simply based on the parent point ID. If the point ID is not consecutive, a new section starts. If more than 1 other point refer to the same point ID, a new section starts.

Section types in .swc follow a fixed integer convention:

Readers:

• cell_parser

• read_swc()

Example:

# pID type  x             y           z           r        parent ID
1     1     -126.687302   397.872009  -379.372986 2.542405 -1
2     1     -126.425797   397.434021  -379.303009 2.801655  1
3     1     -126.164299   396.996002  -379.234009 3.0609    2
4     1     -125.9506     396.481995  -379.165985 3.295415  3
...
43    1     -111.478897   383.348022 -378.470001  4.131965  42
44    1     -111.100601   383.018005 -378.457001  3.47198   43
45    3     -128.1241     390.917023 -377.123993  0.62      8
46    3     -126.512604   390.572998 -377.480988  0.62      45
...

.mod¶

MODL is a file format Used to define dynamical systems as simply as reasonably possible. NEURON Hines and Carnevale [7] provides an extension to this format called NMODL, in this case to define channel and synapse dynamics for use in NEURON simulations. NEURON translates these files to C (and to C++ since NEURON 9.0), to be compiled to machine code on the host machine.

NMODL files are categorized in blocks. We highlight some important ones below:

Example:

:Reference : :                Adams et al. 1982 - M-currents and other potassium currents in bullfrog sympathetic neurones

NEURON {
  : Name of this mechanism, defined as a SUFFIX
  : For localized mechanisms (e.g. a single synapse), POINTPROCESS is used to name the mechanism
  SUFFIX Im
  : Uses the ion Potassium (k), needs read access to the potassium reversal potential (ek), writes out potassium current (ik)
  USEION k READ ek WRITE ik
  : Range variables - can be recorded by the user. These should also appear in PARAMETER or ASSIGNED
  RANGE gImbar, gIm, ik
}

UNITS {
  (S) = (siemens)
  (mV) = (millivolt)
  (mA) = (milliamp)
}

PARAMETER {
  : Free parameters.
  : Everything defined here will be accessible and tunable by the user.
  : These are the ones e.g. optimized or explored.
  gImbar = 0.00001 (S/cm2)
}

ASSIGNED {
  v   (mV)
  ek  (mV)
  ik  (mA/cm2)
  gIm (S/cm2)
  mInf
  mTau
  mAlpha
  mBeta
}

STATE {
  : The time-dependent gating variable. This channel only has one.
  m
}

: What to calculate each time step
BREAKPOINT {
  : Solve the DERIVATIVE block named "states"
  : Use `cnexp` (Crank-Nicolson, exponential)
  SOLVE states METHOD cnexp
  : Calculate the conductance of the Im current = conductance density * gating variable
  gIm = gImbar*m
  : Calculate the Im current from the conductance
  ik = gIm*(v - ek)
}

: The ODEs defining the dynamical system. We name it "states". Not to be confused with the "STATE" block.
DERIVATIVE states {
  : Run the procedure named "rates" - evaluate mInf and mTau based on the current value of voltage
  rates(v)
  : Define the gating variable time dependency - linear first-order ODE
  m' = (mInf-m) / mTau
}

INITIAL {
  : Run the procedure named "rates" - evaluate mInf and mTau based on the current value of voltage
  rates(v)
  : Set the initial value of m to mInf i.e. the value of m if t -> inf for the current voltage
  m = mInf
}

PROCEDURE rates(v) {
  : Simple procedure named "rates"
  : Calculates mTau and mInf, used in the DERIVATIVE block
  UNITSOFF
    mAlpha = 3.3e-3*exp(2.5*0.04*(v - -35))
    mBeta = 3.3e-3*exp(-2.5*0.04*(v - -35))
    mInf = mAlpha / (mAlpha + mBeta)
    mTau = 1 / (mAlpha + mBeta)
  UNITSON
}

.am¶

The Amira proprietary VTK-like file format. Refer to the amira documentation for more information. This flexible format can be used to store 3D scalar meshes, 3D neuron morphology reconstructions, slice image data etc.

Readers:

• read_scalar_field

• read_landmark_file