# `berabr` – Auditory Brainstem Response Object

A `berabr` object represents one ABR measurement recorded with the **BERA** custom MATLAB software used at the IAN.

---

## Raw Data

### File location

Raw data are expected to live in the ABR raw-data directory registered with the parent `anex` object (`anex.RawDataDir` entry with `type = "ABR"`).  
Within that directory every BERA recording is stored as a single MATLAB `.mat` file whose name ends with `BERA.mat`, e.g.

```
<rawDataDir>/
  <SeriesID>BERA.mat      % one file per recording series
```

### File content (`<SeriesID>BERA.mat`)

The file must contain two top-level variables:

| Variable | Description |
|----------|-------------|
| `ExpInfo` | Struct with experiment-level metadata (acquisition frequency `FreqAcqStim`, `ProtokollSetting`, etc.) |
| `IsData`  | 1 × N struct array where each element corresponds to one stimulus condition/trace |

Each element of `IsData` must contain at minimum:

| Field | Description |
|-------|-------------|
| `Speaker` | String identifying the stimulus hardware (see supported hardware below) |
| `BERAStimMode` | Stimulus mode string used to fill `berabr.Stim.mode` |
| `dbSPL` / `Intens1` | Presented intensity (acoustic: `dbSPL`; optical/electric: `Intens1`) |
| `StimRepeatPerSec` | Stimulus repetition rate [Hz] |
| `BERAdat` | Averaged ABR waveform data (usually over 1000 repetitions of a stimulus) (or `BERAdatTrace` + `BERAdatTraceStim` for `AverageMode == 2`) |
| `StimDat` | Stimulus trace |
| `AverageMode` | `1` = averaged in-window; `2` = continuous cut |

For **optical** stimuli the following additional fields are required:

| Field | Description |
|-------|-------------|
| `isIntensTimeValue1` | Stimulus pulse duration [ms] |
| `isIntensLaser` | Present when the BERA software controlled a laser |

---

## Supported Stimulus Hardware

The `stim` function recognises the following `Speaker` field values:

| `Speaker` string | Modality | Notes |
|-----------------|----------|-------|
| `avisoft` | Acoustic | Standard loudspeaker |
| `Laser ObisTTL` | Optical | Orange OBIS laser via TTL |
| `uLED Array` | Optical | µLED array / waveguide implant |
| `Laser TTL AOTF 473` | Optical | 473 nm laser with AOTF |
| `Laser Oxxius` | Optical | Oxxius laser |
| `Laser RedL660P` | Optical | Dark-red 660 nm laser |
| `LaserOxxiusMPA542` | Optical | Green 542 nm Oxxius + MPA (post PC-upgrade label) |
| `Laser OxxiusAnalog` | Optical | Blue Oxxius analog-controlled |
| `Laser A   AOTF 473` | Optical | Alternative 473 nm AOTF label |
| `electric_placeholder` | Electric | Electric stimulation |

---

## Calibration Files

Calibration is handled by `setCalibrationBeraFromLaserControl(ee)` (called on the parent `anex`).

### File naming convention

Calibration `.txt` files must be located in the **ABR raw data directory** (default) or a custom `calibDir`.  
They are generated by the **LaserControl** software and follow the pattern:

```
<date>_<laserType>_<ComPort>_Power_Calibration_<OD>.txt
```

Example: `20240312_Obis_COM10_Power_Calibration_0.txt`

### File content

Each calibration file contains a header followed by a tab-delimited table with columns:

| Column | Description |
|--------|-------------|
| `Power_Percent` | Drive percentage sent to the laser (0–100 %) |
| `Current_mA` | Corresponding laser drive current [mA] |
| `Power_mW` | Measured optical output power [mW] |

The header must contain the string `Power (mW)` so that `setCalibrationBeraFromLaserControl` can locate the data rows automatically.

### User-input prerequisite

Before calling `setCalibrationBeraFromLaserControl`, the GUI `userberabrOD.mlapp` must have been completed for all berabr objects of the experiment.  
This saves `ODui_<ExpID>.mat` in the processed data directory, recording which **optical density (OD) filter** and which **hardware** (laser type / COM port) was used for each recording.

### Calibration result stored in `berabr.C`

| Field | Description |
|-------|-------------|
| `C.calib` | Raw calibration lookup table |
| `C.Ical` | Calibrated intensity [mW] for each trace in the berabr |
| `C.calibTag` | OD filter value used |

For **acoustic** ABRs no calibration file is required; `C.Ical` is set equal to the software output in dB SPL, since there the stimulating software gives out already calibrated values for our setups.

---

## Processing Overview

| Step | Function | Description |
|------|----------|-------------|
| 1 | `initBerabr` | Calls `loadRaw` → `stim` → `processBerabr` → `saveBerabr` |
| 2 | `processBerabr` | Bandpass-filters traces (default 300–3000 Hz), stores result in `berabr.F` |
| 3 | `setCalibrationBeraFromLaserControl(ee)` | Reads LaserControl `.txt` files and populates `berabr.C.Ical` |
| 4 | `exploreBerabr` / `berabrWaveGUI2` | GUI for manual wave-peak annotation (stored as `W_<ExpID>_<SeriesID>.mat` in the processed data directory) |
| 5 | `userberabrOD(ee)` | GUI for adding ABR-related user input, such as which density filter and specific laser were used for different berabrs |
---
