| 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 |
``` |