.. _sec-generate_case:

****************************
Generating case files
****************************

To generate a new case file click on the ``File`` menu and then on ``Generate case``. The ``generate case`` window will open up. Cases are generated on the basis of psychometric function (PF) parameters for bone conduction (BC) thresholds and air-bone gaps (ABGs). PF parameters for air-conduction (AC) responses are internally generated by the software on the basis of the BC parameters and of the ABGs. For example, the AC PF midpoint is equal to the BC PF midpoint plus the ABG. The false alarm and the lapse rate for AC responses are assumed to be the same as those for BC responses. When you generate a case, virtual listener thresholds are simulated over a large number of iterations to obtain the median thresholds and the 95% confidence intervals that are shown by clicking the ``Show actual threshold`` checkboxes in the main ``audiometry_trainer`` window. Please see Section :ref:`sec-virtual_listener` for further details on PFs.

The virtual listener parameters are specified using a spreadsheet-like interface in which each row represents a different frequency. Frequencies can be added/removed by clicking on the ``Edit`` menu and then on ``Frequencies``. Only a discrete set of frequencies between 0.125 and 8 kHz can be used. Selecting with the mouse multiple cells and right clicking allows you to copy/cut/paste cell values as well as set the same value for all selected cells.

Some abbreviations are used in the column headers of the ``generate case`` window to save space: `mdp` for midpoint, `F.A.` for false alarm, `R` for right and `L` for left. To give some concrete usage examples, if you wanted to simulate a sensorineural hearing loss of 45 dB HL at a given frequency you could set the BC midpoint of the PF to around 43 dB HL, the PF width to around 8 dB, and the ABG to zero. The midpoint is the point at which the listener responds "Yes" 50% of the time (assuming F.A. and lapse rates close to zero). The threshold found with the Hughson-Westlake procedure is found at a %Yes responses between 50% and 100%. A width of 8 dB means that the PF will go from 5% to 95% correct in the span of 8 dB, therefore it will go from the midpoint (43 dB HL) to 95% "Yes", in the span of 4 dB (half the width). Overall, using these parameters the threshold will be located within a couple of dB of 45 dB HL. Given that a step size of 5 dB is used for the threshold search, the resulting threshold will almost certainly be found, on average, at 45 dB HL. This is simply an example and variations of each of the PF parameters (midpoint, width, F.A. rate and lapse rate) could be used to obtain a virtual listener with the same threshold but a different response behavior. Empirically, the region of uncertainty between inaudibility and certain detection in clinical audiometry has been found to be around 10 dB wide [Barr-HamiltonEtAl1969]_, therefore PF widths of around 10 dB should result in relatively realistic virtual listeners.

To simulate a conductive/mixed hearing loss simply set the ABG to the desired value of the conductive component. The AC PF midpoint will be shifted by the ABG with respect to the BC PF midpoint.

In addition to the BC and ABG PF parameters there are two columns, ``Gain R`` and ``Gain L`` that represent the gain of a hearing aid worn by the virtual listener. The values in these columns do not have any influence on the listener's responses to stimuli delivered via earphones or via the bone conduction transducer. They only influence free-field responses. Free-field responses are not currently implemented in ``audiometry_trainer`` but may be implemented in the future, so for now you can simply leave the ``Gain R`` and ``Gain L`` cells values to their default value of zero.

Once you're happy with the virtual listener parameters, you can input the desired number of simulations to run in the ``No. simulations`` input field and then click on the ``Run simulation`` button. You will be promted to select a destination file in which the results will be saved. To use the newly generated case file in ``audiometry_trainer`` simply load it through the main ``audiometry_trainer`` window by clicking on its ``File`` menu and then on ``Load case``.

A random seed can be optionally set to obtain reproducible results. Additionaly, case information (e.g. type of hearing loss, source of the case, etc...) can be added to the ``Case info`` box. Markdown syntax can be used in this box and will be rendered appropriately when the case info is loaded into ``audiometry_trainer``. Case information is saved to a case info file which is saved automatically when the simulation is run, even if the case info box is empty. The case info file will have the same root filename as the case file but will end with a ``_info.md`` suffix. In order for the case info file to be loaded by ``audiometry_trainer`` it has to be located in the same folder from which the case file is loaded.

The virtual listener parameters can be saved and later reloaded into the ``generate case`` window by clicking on the ``Save parameters`` and ``Load parameters`` actions found under the ``File`` menu. Saving a parameter file also saves any text found in the ``Case info`` box in a case info file. Loading a parameter files also loads case info from a case info file with the same root filename, provided that it is located within the same directory.
