Debian Codegraph @

docs/autodocs/source/filternet.rst

raw
1 FilterNet
2 =========
3
4 .. figure:: _static/images/bmtk_architecture_filternet_highlight.jpg
5 :scale: 40%
6
7 FilterNet will simulate the effects of visual stimuli onto a receptive field. It uses LGNModel simulator as a backend, which
8 uses neural filters to simulate firing rates and spike trains over a given time course and stimuli. It is based on a
9 `linear-nonlinear-Poisson cascade model <https://en.wikipedia.org/wiki/Linear-nonlinear-Poisson_cascade_model>`_
10 with options for choosing different types of spatial, temporal, or spatio-temporal units that have already been
11 optimized to closely mimic mammalian thalamic cells:
12
13
14 .. figure:: _static/images/lnp_model.jpg
15 :scale: 60%
16
17
18 FilterNet is very useful for generating spike-trains that will be used as the inputs for simulations running in BioNet,
19 PointNet, or PopNet. The procedure is as follows:
20
21 1. Generate the receptive field network.
22 2. Use FilterNet to play images and movies against the receptive field and generate responses for each unit.
23 3. Connect the receptive field network created in step #1 to some higher-level cortical circuit.
24 4. Use the spike trains generated in Step #2 to see how the high-level cortical circuit would respond to different stimuli.
25
26
27 Inputs
28 ------
29 Currently, FilterNet allows for a number of different types of custom and pre-aligned types of stimuli. To change the
30 type of stimuli requires updating the inputs section in the simulation_config.json file like above.
31
32 Movie
33 +++++
34 Allows playing a custom movie file in the form of a three-dimension matrix saved in a npy file.
35
36 .. code:: json
37
38 {
39 "movie_input": {
40 "input_type": "movie",
41 "module": "movie",
42 "data_file": "/path/to/my/movie.npy",
43 "frame_rate": 1000.0,
44 "normalize": true
45 }
46 }
47
48 * movie: Link to a 3-dimensional (time, x, y) matrix representing a movie (where time is equal to the number of frames in the movie).
49 * frame_rate: frames per second
50 * normalize: Allow the option to normalize the input movie to have contrast values between [-1.0, +1.0].
51 * If set to true then FilterNet will attempt to infer the current range of the original movie from the data (most movies use contrast between [0, 255] or [0.0, 1.0].
52 * If the original movie has a unique range, users can specify the min/max contrast for the original movie ```"normalize": [0.0, 100.0]```
53
54 Grating
55 +++++++
56 Plays a drifting grating across the screen
57
58 .. code:: json
59
60 {
61 "gratings_input": {
62 "input_type": "movie",
63 "module": "graiting",
64 "row_size": 120,
65 "col_size": 240,
66 "gray_screen_dur": 0.5,
67 "cpd": 0.04,
68 "temporal_f": 4.0,
69 "contrast": 0.8,
70 "theta": 45.0,
71 "phase": 0.0,
72 "degrees_per_pixel": 1.0
73 }
74 }
75
76 * row_size, col_size: width and heigth dimensions of screen in pixels.
77 * grapy_screen_dur: displays an optional gray screen for a number of seconds before the grating starts. (default: 0)
78 * cpd: spatial frequncy represented as cycles per degree. (default: 0.05)
79 * temporal_f: temporal frequency in Hz. (default: 4.0)
80 * theta: orientation angle, in degrees (default: 45.0)
81 * phase: temporal phase, in degrees (default: 0.0)
82 * contrast: the maximum constrast, must be between 0 and 1.0 (default: 1.0)
83 * degrees_per_pixel: sampling pitch of the movie in degrees per pixel (default: 1 / (cpd * 10))
84
85
86 Full Field Flash
87 ++++++++++++++++
88 Creates a bright (or dark) flash on a gray screen for a limited number of seconds
89
90 .. code:: json
91
92 {
93 "full_field_flash": {
94 "input_type": "movie",
95 "module": "full_field_flash",
96 "row_size": 120,
97 "col_size": 240,
98 "t_on": 1000.0,
99 "t_off": 2000.0,
100 "max_intensity": 20.0
101 }
102 }
103
104 * row_size, col_size: width and height dimensions of screen in pixels.
105 * t_on: time (ms) from the beginning on when to start the flash
106 * t_off: length (ms) of flash
107 * max_intensity: intensity of screen during flash (>0.0 is brighter, <0.0 is darker) compared to a gray screen.
108
109
110 Looming
111 +++++++
112 Creates a spreading black field originating from the center.
113
114 .. code:: json
115
116 {
117 "looming_input": {
118 "input_type": "movie",
119 "module": "looming",
120 "row_size": 120,
121 "col_size": 240,
122 "frame_rate": 1000.0,
123 "gray_screen_dur": 0.5,
124 "t_looming": 1.0
125 }
126 }
127
128 * row_size, col_size: width and height dimensions of screen in pixels.
129 * frame_rate: frames per second
130 * gray_screen_dur: duration of the initial grey screen (seconds)
131 * t_looming: time of the looming movie (seconds).
132
133
134 Optimizations Techniques
135 ------------------------
136 The time required to generate spikes will depending on the number of cells in the network, the stimulus type, complexity of the cell-models; among
137 other factors. The full simulation time can take a few seconds to a few hours. The following options may sometimes be utilized in order to
138 significantly speed up the process.
139
140
141 Parallelization with MPI
142 ++++++++++++++++++++++++
143 The `MPI <https://www.mpi-forum.org/docs/>`_ library allows the simulation to be parallelized across multiple processors and machines for use in an
144 HPC cluster or even on a single machine with multiple cores. FilterNet can take advantage of using MPI automatically. Modelers will need the following
145 installed on their machine:
146 * Either `OpenMPI <https://www.open-mpi.org/>`_ or `MPICH2 <https://www.mpich.org/>`_
147 * `mpi4py <https://mpi4py.readthedocs.io/en/stable/>`_
148
149 On most HPC clusters these will be already installed. For personal machines you can often install using either `pip install mpi4py` or
150 `conda install -c conda-forge mpi4py`. Then to run across <N> different cores execute your run_filternet.py script using
151
152 ```bash
153 $ mpirun -n <N> python run_filternet.py config.json
154 ```
155
156 Or if using a scheduler like slurm you can often use the `srun` command instead (instructions for scheduling parallel jobs on an HPC will vary depending
157 on the institute).
158
159 The results will be the same as if running FilterNet on a single core, the results stored in the same directory as specified in the config file.
160
161
162 Numba
163 +++++
164 You can also optimize FilterNet run-time using the `Numba <https://numba.pydata.org/>`_ python libary (with and without MPI). To install numba in your python
165 environment:
166
167 ```bash
168 $ pip install numba
169 ```