| 1 |
Analyzing the Results |
| 2 |
===================== |
| 3 |
|
| 4 |
.. figure:: _static/images/bmtk_architecture_analyzer_highlight.jpg |
| 5 |
:scale: 40% |
| 6 |
|
| 7 |
After a simulation has been completed BMTK will automatically save the results to the output folder. It is possible to have |
| 8 |
BMTK read and analyzes the results before the simulation has exited but is usually not required. The type of results saved |
| 9 |
during the simulation is determined by the “reports” section of the `simulation config <./simulators.html#configuration-files>`_. |
| 10 |
But most commonly it is a spikes-trains file, a cell-variable report, an extracellular potential recording, and in the |
| 11 |
case of PopNet a report of the firing rate dynamics. |
| 12 |
|
| 13 |
The output files follow the `SONATA Data format <https://github.com/AllenInstitute/sonata>`_, and tools like |
| 14 |
`pySONATA <https://github.com/AllenInstitute/sonata/tree/master/src/pysonata>`_ or |
| 15 |
`libSONATA <https://github.com/BlueBrain/libsonata>`_ can be used to read them. The following consists of a high-level |
| 16 |
overview of these different formats and how you can use BMTK to find the results. |
| 17 |
|
| 18 |
|
| 19 |
Spike-Trains |
| 20 |
------------ |
| 21 |
Contains action potentials/spikes for all the nodes within a given population. In the HDF5 the spikes are stored under |
| 22 |
/spikes/_<population_name>_/ and contains two data-sets: |
| 23 |
|
| 24 |
* timestamps (size N): A list of all the spikes during the simulation |
| 25 |
* node_ids (size N): A list of corresponding node_ids for each spike |
| 26 |
|
| 27 |
.. figure:: _static/images/spikes_report.png |
| 28 |
:scale: 80% |
| 29 |
|
| 30 |
The group may contain an attribute “sorting” with values none, by_id, and by_time to indicate if and how the spikes are |
| 31 |
sorted (default none). There is also an optional attribute “units” for the timestamps, but defaults to milliseconds. |
| 32 |
|
| 33 |
|
| 34 |
Reading |
| 35 |
+++++++ |
| 36 |
You can use the :py:class:`SpikeTrains <bmtk.utils.reports.spike_trains.spike_trains_api.SpikeTrainsAPI>` class to load |
| 37 |
a sonata spikes files (or csv or nwb) into memory: |
| 38 |
|
| 39 |
.. code:: python |
| 40 |
|
| 41 |
from bmtk.utils.reports.spike_trains import SpikeTrains |
| 42 |
|
| 43 |
pop_name = ... |
| 44 |
spikes = SpikeTrains.load('output/spikes.h5', population='pop_name') |
| 45 |
assert(spikes.populations = [pop_name]) |
| 46 |
print(spikes.n_spikes()) |
| 47 |
print(spikes.node_ids()) |
| 48 |
|
| 49 |
If you know what node you want use the :py:meth:`get_times() <bmtk.utils.reports.spike_trains.spike_trains_api.SpikeTrainsAPI.get_times>` |
| 50 |
method to return an array of all spikes for a single node |
| 51 |
|
| 52 |
.. code:: python |
| 53 |
|
| 54 |
node0_times = spikes.get_times(node_id=0) |
| 55 |
print(node0_times) |
| 56 |
|
| 57 |
Otherwise you can use the :py:meth:`to_dataframe() <bmtk.utils.reports.spike_trains.spike_trains_api.SpikeTrainsAPI.to_dataframe>` |
| 58 |
or :py:meth:`spikes() <bmtk.utils.reports.spike_trains.spike_trains_api.SpikeTrainsAPI.spikes>` method to get a list of |
| 59 |
all node_ids plus timestamps |
| 60 |
|
| 61 |
.. code:: python |
| 62 |
|
| 63 |
for ts, pop, node_id in spikes(): |
| 64 |
assert(pop == pop_name) |
| 65 |
... |
| 66 |
|
| 67 |
.. code:: python |
| 68 |
|
| 69 |
print(spikes.to_dataframe()) |
| 70 |
|
| 71 |
|
| 72 |
Plotting |
| 73 |
++++++++ |
| 74 |
|
| 75 |
|
| 76 |
Analysis |
| 77 |
++++++++ |
| 78 |
|
| 79 |
|
| 80 |
Creating Spike Trains |
| 81 |
+++++++++++++++++++++ |
| 82 |
Commonly it’s necessary to generate spike-trains to use as inputs for a simulation. One option is to use FilterNet to |
| 83 |
generate inputs from external stimuli. You can also use the output of one simulation as the input to the next. But if |
| 84 |
you need to generate your own spike files, in property SONATA format, BMTK provides two ways of readily doing so. One |
| 85 |
is to use the :py:class:`SpikeTrains <bmtk.utils.reports.spike_trains.spike_trains_api.SpikeTrainsAPI>` class |
| 86 |
:py:meth:`add_spikes() <bmtk.utils.reports.spike_trains.spike_trains_api.SpikeTrainsAPI.add_spikes>` or |
| 87 |
:py:meth:`add_spike() <bmtk.utils.reports.spike_trains.spike_trains_api.SpikeTrainsAPI.add_spike>` method: |
| 88 |
|
| 89 |
.. code:: python |
| 90 |
|
| 91 |
from bmtk.utils.reports.spike_trains import SpikeTrains |
| 92 |
|
| 93 |
spikes = SpikeTrains(population='my_inputs') |
| 94 |
spikes.add_spikes(node_ids=0, timestamps=[1.0, 2.0, 3.0, ...]) |
| 95 |
spikes.add_spike(node_id=[1, 1, 2, 3], |
| 96 |
timestamps=[0.5, 0.9, 1.0, 1.0]) |
| 97 |
|
| 98 |
|
| 99 |
Or use the :py:class:`PoissonSpikeGenerator <bmtk.utils.reports.spike_trains.spike_trains.PoissonSpikeGenerator>` class |
| 100 |
|
| 101 |
.. code:: python |
| 102 |
|
| 103 |
from bmtk.utils.reports.spike_trains import PoissonSpikeGenerator |
| 104 |
|
| 105 |
psg = PoissonSpikeGenerator(population='thalamus') |
| 106 |
times = np.linspace(0.0, 3.0, 100000) |
| 107 |
frs = 10*np.sin(times) + 5.0 |
| 108 |
psg.add(node_ids=range(10), firing_rate=frs, times=times) |
| 109 |
psg.add(node_ids=range(10, 20), firing_rate=15.0, times=(0.0, 3.0)) |
| 110 |
psg.to_sonata('./inputs/thamlamus_inputs.h5') |
| 111 |
|
| 112 |
|
| 113 |
Cell Variable Report |
| 114 |
-------------------- |
| 115 |
Used to record the traces of intracellular and membrane variables throughout the simulation, like membrane |
| 116 |
potential V. In the HDF5 cell reports are stored under /report/<population_name>/ with the most relevant datasets: |
| 117 |
|
| 118 |
* data (size T_times x N_segments): All the recorded values, each row a different step in time and each column a |
| 119 |
different segment/cell |
| 120 |
* mapping/time (size 3 or T_times): For the exact times of each recording. If the simulation time steps are uniform then |
| 121 |
the dataset contains 3 values: start_time, stop_time, and time_step (all in ms). Otherwise, the will be of size T_times |
| 122 |
for each recording time since the start of the simulation. |
| 123 |
* node_ids: used to map each column to a specific cell |
| 124 |
|
| 125 |
.. figure:: _static/images/cell_reports.png |
| 126 |
:scale: 60% |
| 127 |
|
| 128 |
If the recording is done on point-neurons or one is only recording from the soma, there will be one column in “data” for |
| 129 |
each node. If recording different sections from a multi-compartmental neuron then *mapping/index_pointers* should be |
| 130 |
used: |
| 131 |
|
| 132 |
.. figure:: _static/images/segmentation_indexing.jpg |
| 133 |
:scale: 80% |
| 134 |
|
| 135 |
|
| 136 |
Reading Cell Variables |
| 137 |
++++++++++++++++++++++ |
| 138 |
The :py:class:`CompartmentReport <bmtk.utils.reports.compartment.core.CompartmentReaderABC>` class should be used to |
| 139 |
pull data from a cell report. |
| 140 |
|
| 141 |
.. code:: python |
| 142 |
|
| 143 |
bmtk.utils.reports.compartment import CompartmentReport |
| 144 |
|
| 145 |
pop_name = ... |
| 146 |
report = CompartmentReport('output/membrane_vm.h5', |
| 147 |
population=pop_name, mode='r') |
| 148 |
print(report.variable()) |
| 149 |
print(report.tstart(), report.tstop(), report.dt()) |
| 150 |
print(report.element_ids(node_id=0)) |
| 151 |
print(report.element_pos(node_id=0)) |
| 152 |
print(report.data(node_id=0)) |
| 153 |
|
| 154 |
.. code:: bash |
| 155 |
|
| 156 |
v |
| 157 |
0.0, 3.0, 0.01 |
| 158 |
[0, 1, 2, 2, ...] |
| 159 |
[0.5, 0.5, 0.5, 05, ...] |
| 160 |
[[-50.010, -50.911, -50.995, -51.000, ...] |
| 161 |
[-49.933, -49.330, -50.011, -50.667, ...] |
| 162 |
...] |
| 163 |
|
| 164 |
|
| 165 |
Extracellular Potential |
| 166 |
----------------------- |
| 167 |
|
| 168 |
|
| 169 |
Rates |
| 170 |
----- |
| 171 |
|
| 172 |
|
| 173 |
|