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