Welcome to the Open GPIAS Documentation¶
Open GPIAS is an open-source tool to record the acoustic startle reflex (ASR) of rodents.
Installation¶
Open GPIAS can be installed in different ways, you can choose the one which is the most comfortable for you and the operating system you are using.
Windows Installer¶
If you have no Python installation and just want to get started, our installer is the best option for you. Just download and execute the following installer:
This will install the miniconda environment, if it is not already installed and download the open_gpias conda package.
Note
Open GPIAS will be by default installed in a new conda environment called _app_own_environment_open_gpias.
Python Packages¶
If you are already familiar with python and have a python installation, you can choose one of the following ways:
If you are in a conda env:
conda install -c conda-forge -c dlidstrom -c rgerum open_gpias(recomended)Or with
python setup.py install
We recommend the conda installation, as this should always be the newest version of Open GPIAS.
Developer Version¶
If you want to have Open GPIAS installed from the repository and be able to update to the newest changesets, you can follow this guide. First of all you need to have mercurial installed (Mercurial). Then you can open a command line in the folder where you want to install Open GPIAS and run the following command:
hg clone https://bitbucket.org/randrian/open_gpias
To install the package with all dependencies, execute:
python install_requirements_with_conda.py
in the downloaded repository directory.
Hardware¶
The acoustic startle response setup can only record data, if the required hardware is available.
Soundcard¶
The soundcard should have at least two output channels. If two different loudspeakers for pre-stimulus and startle-stimulus should be used, the soundcard needs at least three channels:
trigger channel
pre stimulus
startle stimulus
In our setup, we use a Asus Xonar Essence STX II 7.1 soundcard (SNR: 124 dB, channels: 8, sampling rate: <192 kHz ).
Amplifier¶
Broadband low noise amplifier
Amp74, Thomas Wulf, Frankfurt
Amp75, Thomas Wulf, Frankfurt
Loudspeaker¶
The setup can either be realized with one loudspeaker or two loudspeakers. Separating the pre-stimulus from the startle-stimulus loudspeaker has the advantage, that the speaker for the pre-stimulus is not damaged by the repeated application of loud startle-pulses.
The pre-stimulus speaker should be able to reproduce the signal faithfully, while the startle-stimulus speaker only needs to be able to present a loud burst.
In our setup, we use:
Two-way loudspeaker Canton Plus XS.2 for the pre-stimulus
Neo-25s (Sinuslive) for the startle-stimulus
NiDAQ-Card¶
The data acquisition card needs at least six channels and a recording rate of 10 kHz.
In our setup, we use a PCIe-6320 data acquisition card connected to a Breakoutbox BNC-2110.
Sensor platform¶
The sensor platform has to hold the animal at a fixed distance to the speakers. In addition, the animal has to be flexibly mounted to allow for measurable vibrations when the animal twitches in response to a startle stimulus.
In our setup, we use a platform consisting of two plates. The upper plate has a mount for the animal restrainer and is mounted on the lower plate by four springs and two rubber foam blocks for damping. Underneath the upper plate, an acceleration sensor (ADXL 335 on a GY 61 board) is attached. The lower plate is screwed to the vibration isolated table.
We provide the technical drawings and CAD files for the sensor platform:
Animal restrainer¶
The animal restrainer has to hold the animal during the measurement. The restrainer should be designed, so that the animal is not able to turn around, and that the restrainer does not cause acoustic distortions.
In our setup, we use an animal restrainer made out of an acrylic tube (length x inner diameter, small: 102mm x 27mm (for mouse, cap: cap_small.stl), middle: 137mm x 37mm (small gerbil, cap: cap_normal.stl), big: 137mm x 42mm (big gerbil, cap: cap_big.stl) covered with a wire mesh at the front end and a plastic cap (custom 3D print) at the rear end.
List of all components¶
Component |
Model |
Cost |
Link |
|---|---|---|---|
Anechoic chamber |
|||
Vibration isolated table |
|||
PC |
|||
Soundcard |
Asus Xonar Essence STX II |
310.00 € |
https://www.amazon.com/Xonar-Essence-STX-II-7-1/dp/B00JF6RO7C |
Amplifier (pre-stimulus) |
Amp 74, Thomas Wulf, Frankfurt |
||
Amplifier (startle-stimulus) |
Amp 75, Thomas Wulf, Frankfurt |
||
Pre-stimulus speaker |
Canton Plus XS.2 |
71,00 € |
https://www.elektrowelt24.eu/shop/product_info.php?refID=20123&products_id=486 |
Startle-stimulus speaker |
Neo-25s, Sinuslive |
44,00 € |
https://www.amazon.de/Sinuslive-13496-Neo-25S-Hocht%C3%B6ner-Black/dp/B003A67KTK |
Data acquisition card |
PCIe-6320, National Instruments |
625.00 € |
|
Breakout box |
BNC-2110, National Instruments |
445.00 € |
|
Sensor platform |
Own construction |
||
Acceleration sensor |
ADXL 335 on a GY 61 board |
4.20 € |
http://www.robotpark.com/GY-61-DXL335-3-Axis-Accelerometer-Module |
Animal restrainer |
Acrylic tube 3D printed cab |
||
Wire Mesh |
Driller 16910; 1.4 x 1.4 mm |
4.71 € |
|
Springs |
Febrotec 1.4310 d=0.50 Da=11.50 L0=22.40 c=0.075 |
||
Cables |
Assembling the Setup¶
Preperation¶
In order to make sure, there is no interruption while you assemble the hardware we advise you to make sure you do all preparations before you start to assemble:
Obtain the needed hardware
Install the soundcard and NIDAQ-Card drivers as described in the corresponding user manual
After installing the soundcard change its settings to 4 input and 4 output channels
Build the sensor platform
Build at least one tube for the animals
Solder the speaker cables to a BNC connector (male)
Hardware¶
Place Hardware¶
Place the sensor platform in the soundproof chamber
Place the speaker(s) in front of the sensor platform without them blocking each other and both being horizontally centered in front of the tube. Place the startle-stimulus-speaker close to the sensor platform, as it needs to produce a sound pressure level of 115 dB SPL which it will only manage if the distance is small. (max about 5 cm)
Connect the amplifiers
Connect the power-supply for the sensor platform with 3V DC
Connect Hardware¶
The diagram shows how the different components are connected.
NiDAQ-Card measures the data of the soundcard, therefore needs a BNC Tee connector on the plugs ai4 an ai5
As we will connect the audio channels using BNC-cabels plug cinch-BNC(male) connectors into the channels 1,3,4 of the soundcard
Connect everything as stated by the following table
SC: soundcard SP: sensor platform BB: breakoutbox NI: NiDAQ-Card AP: amplifier pre-stimulus AS: amplifier startle-stimulus
From |
To |
Cable |
NI |
BB |
SHC 68-68 |
SP-X |
BB-ai0 |
BNC |
SP-Y |
BB-ai1 |
BNC |
SP-Z |
BB-ai2 |
BNC |
SC-1 |
BB-ai3 |
BNC |
SC-3 |
BB-ai4 |
BNC |
SC-4 |
BB-ai5 |
BNC |
BB-ai4 |
AP-in |
BNC |
BB-ai5 |
AS-in |
BNC |
AP-out |
pre-stimulus speaker |
BNC |
AS-out |
startle-stimulus speaker |
BNC |
power-supply |
SP power in |
solder |
Configuration¶
As every setup differs slightly from the components and how the parts are installed, the measurement setup needs to be configured in order to work properly. Open GPIAS therefore has a configuration module that allows to provide the needed information.
Soundcard¶
To create the acoustic stimuli, a soundcard is used. The right device has to be selected, as well as which channels are connected to the loudspeakers.
sound device: the device or driver that is used
channel trigger: the soundcard’s output channel that is used to play the trigger signal, that is send to the NiDAQ card, in order to synchronize the stimulus and the measured response. Default 1
channel pre-stimulus: the soundcard’s output channel that is connected to the NiDAQ card and the pre-stimulus loudspeaker. Default 3
channel startle-stimulus: the soundcard’s output channel that is connected to the NiDAQ card and the startle-stimulus loudspeaker. If only one loudspeaker is used, select the same channel as for the pre-stimulus. Default 4
sample rate: the sampling rate for the sound playback. Default 96000
channel latency: the delay for the playback for the different channels. Often soundcards delay the playback for some channels in order to generate surround sound, this offset can be corrected in our software. Example: 0, 0, 14.8125, 14.8125 for the Asus Xonar Essence STX II.
Loudspeakers¶
To get the desired playback of the acoustic stimuli, the loudspeakers have to be configured properly. The amplification factor has to be given, as well as an equalizer profile to guarantee a flat frequency response function.
speaker amplification factor: the value used to multiply internal values to generate the desired sound pressure level from the loudspeakers. This depends on the loudspeakers and the amplifiers. The first value is for the pre-stimulus loudspeaker, the second for the startle-stimulus loudspeaker. Example: 1.9e-05,3.125e-07
equalizer profile: the recorded profile for the speaker. See calibration for details.
NiDAQ Card¶
The data is recorded with a NiDAQ card. Currently we do not allow a different configuration of the channels, but the device can have different names, depending on the installation.
recording device: the name of the device, as seen e.g. in NiMAX. Typically, names start with “Dev” followed by a number. Example “Dev2”.
recording rate: the rate for the data recording in Hz. Default 10000
Acceleration Sensors¶
The acceleration sensors measure the response of the animal in three spatial directions.
acceleration sensor factors: three factors for the different acceleration sensors (xyz). Amplitudes will be divided by this factor to account for different forces needed to achieve the same acceleration. Example: 0.9027,1.0,3.8773. See calibration for details.
Calibration¶
Frequency correction¶
The transfer function of a loudspeaker defines how the input frequencies are reproduced by the loudspeaker. As every loudspeaker is different and details depend on the measurement setup, it has to be calibrated for the use of Open GPIAS.
We therefore provide a calibration routine.
Warning
Read this first before you use them! If you do not take care of these instructions, you may destroy your speaker!
The problem is that if you use a different speaker, amplifier, or soundcard the audiosignal may be too strong for your speaker and destroys it. That’s why we limited the maximum Value using the variable noisefactor_max and adjusted it to our setup. If you are not sure what value to take, start with a very small one. Very small means a Value which is 1000 or 10000 times smaller than the value you would expect. Than follow the instructions below and if the speakers aren’t loud enough(<60dB) increase the Value for noisefactor_max by a factor of 10 and repeat until it works.
Preparation for frequency correction¶
as a lot of soundcards are not able to play 7.1 sound and record simultaneously we us audio outputs 1 and 2. But in the final setup the speakers are plugged into channels 3 and 4. That’s why you need to take the bnc-cable of the prestimulus(channel3) and plug it into chanel 1. And take the bnc-cable of the startle stimulus(channel4) and plug it into channel 2.
connect the microphone with the dB-measurement device
connect the output of the dB-measurement device with the line-in of your soundcard
turn on dB-Measurement device
adjust the input and output gain so that you can measure 60 dB SPL
place the microphone together with some rubber foam or fabric in the tube. The foam/fabric is supposed to “behave” like the animal and the microphone are the ears of the animal. So try to place them accordingly.
place the tube on the sensor platform
turn on the amplifiers
Measure impulse response and calculate equalizer¶
execute “equalizer_prestimulus.py”
if error “didn’t find an appropriate noise factor, is the microphone plugged in, the dezibelmeter at the right attenuation and the amplifier turned on?” occurs:
did you do all of the questioned?
if not do it and try again
if yes try again and see if you hear a sound and if your dB device shows something, if not increase the Variable noisefactor_max and try again
if no error:
does the graph “residual error signal power (logarithmic)” look correct? if yes follow the steps below. If not try again after you checked if all the parameters are correct and everything is plugged in correct.
copy “equalizer praestimulus lautsprecher.npy” into the folder “as_setup/Stimulation gui”
execute “equalizer_startlestimulus.py.py”
if error “didn’t find an appropriate noisefactor, is the microphone plugged in, the dezibelmeter at the right attenuation and the amplifier turned on?” occurs:
did you do all of the questioned?
if not do it and try again
if yes try again and see if you hear a sound and if your dB device shows something, if not increase the Variable noisefactor_max and try again
if no error:
does the graph “residual error signal power (logarithmic)” look correct? if yes follow the steps below. If not try again after you checked if all the parameters are correct and everything is plugged in correct.
copy “equalizer schreckstimulus.npy” into the folder “as_setup/Stimulation gui”
calibrate dB SPL¶
An implementation to simplify this procedure will come in future releases.
calibrate acceleration sensors¶
Depending on the construction of the sensor platform, the measured acceleration in the different spacial directions can be different. Therefore, these sensors have to be calibrated to return the same values when stimulated with the same force.
For this calibration, we use a vibrational motor that is put on the sensor platform. The sensor is placed once in every spacial direction (x, y, and z) and the output of the sensor is recorded. The amplitudes of these measurements define the calibration parameters; the factors that are used to normalize the output of the sensors.
After calibration¶
Plug audio cables back into their correct place
SC-1(trigger) ⇒ BB-ai3
SC-3(pre-stimulus) ⇒ BB-ai4 BNC
SC-4(startle-stimulus) ⇒ BB-ai5 BNC
Remove microphone and foam/fabric from tube
Turn of dB-measurement device
Unplug line-in from soundcard
Protocols¶
Protocols can be created or loaded in the protocols module.
Currently two types of protocols are implemented: hearing threshold measurements and GPIAS measurements.
All measurements are divided in multiple trials, all ending with a startle-stimulus. At the beginning of each measurement, five trials without pre-stimulus are presented, to get the animal used to the startle-stimuli.
The trials in each protocol are randomized to prevent habituation effects of the animal.
Hearing threshold¶
For hearing threshold measurements, each trial can have a pre-stimulus in the form of a short (40 ms) pure tone 100 ms before the startle stimulus. For the protocol a frequency range (octave, 1/2 octave or 1/4 octave steps), a sound pressure level range and a repetition count can be specified.
GPIAS¶
For GPIAS measurements, each trial consists of a noise stimulus presented before the startle-stimulus. The noise can be interrupted by a short (50 ms, flattened with 20 ms sin²-ramps) gap of silence. The noise can be broad band or a frequency band centered around one frequency (other options will be implemented). For each measurement different center frequencies, as well as the number of measurement repetitions per stimulus condition can be specified.
Note¶
If you encounter any bugs or unexpected behaviour, you are encouraged to report a bug in our Bitbucket bugtracker.
Citing OpenGPIAS¶
If you use OpenGPIAS for academic research, you are highly encouraged (though not required) to cite the following paper:
Gerum, R., Rahlfs, H., Streb, M., Krauss, P., Grimm, J., Metzner, C., Tziridis, K., Günther, M., Schulze, H., Kellermann, W., Schilling, A. (2019), “Open(G)PIAS: An Open-Source Solution for the Construction of a High-Precision Acoustic Startle Response Setup for Tinnitus Screening and Threshold Estimation in Rodents”. Frontiers in behavioral neuroscience doi:10.3389/fnbeh.2019.00140