Debian Codegraph @

docs/autodocs/source/analyzer.rst

raw
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