Markdown exporter

This is the user documentation of mdexport package, that provides functionality to describe Brian2 models in Markdown. The markdown description provides human-readable information of Brian components defined. In background, the exporter uses the Base exporter to collect information from the run time and expand them to markdown strings.

Working example

As a quick start to use the package, let us take a simple model with adaptive threshold that increases with each spike and write the markdown output in a file

from brian2 import *
import brian2tools.mdexport
# set device 'markdown'
set_device('markdown', filename='model_description')

eqs = '''
dv/dt = -v/(10*ms) : volt
dvt/dt = (10*mV-vt)/(15*ms) : volt
'''

reset = '''
v = 0*mV
vt += 3*mV
'''

IF = NeuronGroup(1, model=eqs, reset=reset, threshold='v>vt',
                method='exact')
IF.vt = 10*mV
PG = PoissonGroup(1, 500 * Hz)

C = Synapses(PG, IF, on_pre='v += 3*mV')
C.connect()

Mv = StateMonitor(IF, 'v', record=True)
Mvt = StateMonitor(IF, 'vt', record=True)
# Record the value of v when the threshold is crossed
M_crossings = SpikeMonitor(IF, variables='v')
run(2*second)

The rendered file model_description.md would look like,

Network details

Neuron population :

  • Group neurongroup, consisting of 1 neurons.

    Model dynamics:

    =

    =

    The equations are integrated with the 'exact' method.

    Events:

    If , a spike event is triggered and , Increase by .

    Initial values:

    • Variable =

Poisson spike source :

  • Name poissongroup, with population size 1 and rate as .

Synapse :

  • Connections synapses, connecting poissongroup to neurongroup . Pairwise connections.

    For each pre-synaptic spike: Increase by

The simulation was run for 2. s

Note

By default, Monitors are not included in markdown output, and the order of variable initializations and connect statements are not shown but rather included with the respective objects. However, these default options shall be changed according to one’s need (see developer documentation of Markdown exporter for how to change the default options).

Similar to other Brian2 device modes, to inform Brian to run in the exporter mode, the minimal changes required are importing the package and mentioning device markdown in set_device. The markdown output can be accessed from device.md_text.

The above example can also be run in debug mode to print the output in stdout. In that case, the changes to the above example are,

from brian2 import *
import brian2tools.mdexport
# set device 'markdown'
set_device('markdown', debug=True)  # to print the output in stdout
. . .

run(2*second)

Exporter specific build options

Various options (apart from that of RuntimeDevice) shall be passed to set_device or in device.build(). Exporter specific build_options are,

expander

Expander is the object of the call that contains expander functions to get information from baseexport and use them to write markdown text. By default, MdExpander is used. The default argument values can be changed and expand functions can be overridden (see developer documentation of Markdown exporter for more details and how to write custom expander functions).

A small example to enable github_md in expander that specifies, whether rendered output should be non-Mathjax based (as compilers like GitHub)

from brian2tools.mdexport.expander import MdExpander
# change default value
custom_options = MdExpander(github_md=True)
set_device('markdown', expander=custom_options)  # pass the custom expander object
. . . .
filename
Filename to write output markdown text. To use the same filename of the user script, '' (empty string) shall be passed. By default, no file writing is done

Limitations

Since the package uses baseexport in the background, all the limitations applicable to baseexport applies here as well