# `icme` – Inferior Colliculus Multielectrode Recording Object

An `icme` object represents one inferior-colliculus multielectrode recording acquired with the custom-written MATLAB stimulation software **ExpControl** and the **Cheetah/Neuralynx** recording system.

---
## Key Object Properties

| Property | Description |
|----------|-------------|
| `ExpID` | Experiment / animal ID (e.g. `'GEK111'`) |
| `SeriesID` | Recording series ID (e.g. `'GEK111_0001'`) |
| `ExpInfo` | Struct from the ExpControl log file |
| `Stim` | Stimulus parameters extracted from `ExpInfo` |
| `SL` | Spike-list struct (filled by `ExtractMUAfromRawDataIntoSL`) that contains for each recording electrode the detected multi-unit spikes with the time after stimulus trigger and the stimulus-ID that is associated to that trigger|
| `C` | Calibration struct (filled by `getCalibration` / `calculateCalibration`) |
| `D` | Raw data directory struct |

---
## Raw Data

### File location

All raw data for one recording series must reside in a single directory registered in the parent `anex` object with `type = "IC"`.

```
<rawDataDir>/
  <SeriesID>.m                  % ExpControl log file
  <RawDataFolder>/              % Neuralynx Cheetah output folder
    *.ncs                       % continuous signal files (one per electrode)
    *.nev                       % event / TTL file
    *.nse                       % spike waveform files (optional)
    CheetahLostADRecords.txt    % Cheetah integrity log (optional)
```

The sub-folder name `<RawDataFolder>` is read from the field `ExpInfo.RawDataFolder{1}` inside the `.m` log file.

---

### ExpControl log file (`<SeriesID>.m`)

The log file is a plain MATLAB script generated automatically by ExpControl.  
When run with `run()`, it returns a struct (stored in `icme.ExpInfo`) that must contain at minimum:

| Field | Description |
|-------|-------------|
| `exp_type` | Experiment type string (e.g. `'MX_tones'`, `'OBIS_LS594_Pulse'`) |
| `stimlist` | Matrix of stimulus parameters (rows = conditions) |
| `stimheader` | Cell array of column names for `stimlist` |
| `dura` | Stimulus duration per condition [s] |
| `n_rep` | Number of repetitions per stimulus |
| `animal_ID` | Experiment ID string (must match `icme.ExpID`) |
| `RawDataFolder` | Cell array – `{1}` is the path to the Cheetah data sub-folder |
| `FreqAcqStim` | Acquisition/stimulus frequency [Hz] (used in processing) |

---
### Important: The Stimlist
ExpControl creates stimuli from a stimlist that contains all information required to reconstruct each stimulus. Rows represent individual stimuli (row number corresponds to the stimulus ID saved with spike times in `icme.SL`) and columns describe stimulus values such as applied laser intensity or pulse duration. Many FEATHER functions take a `stim_criteria_array` as input. This array defines stimulus filters in the form `[row index filter 1, min_value, max_value; row index filter 2, min_value, max_value]`. If data acquired with other stimulation software should be analyzed with FEATHER functions, stimuli should be converted into a stimlist format, and detected MU spikes should be loaded in a format that contains spike times after trigger plus stimulus IDs that point to the stimlist row.


### Neuralynx / Cheetah files

| File type | Extension | Required | Description |
|-----------|-----------|----------|-------------|
| Continuous signal | `.ncs` | ✔ | One file per electrode channel; read via `Nlx2MatCSC` |
| Event / TTL | `.nev` | ✔ | Stimulus trigger timestamps; read via `Nlx2MatEV` |
| Spike waveforms | `.nse` | optional | Pre-thresholded spike waveforms from Cheetah online sorting |
| Lost-record log | `CheetahLostADRecords.txt` | optional | Data-integrity information |

> **Note:** The Neuralynx MATLAB import tools (`Nlx2MatCSC`, `Nlx2MatEV`) from the Neuralynx MatlabImportExport package must be on the MATLAB path. The required version for IAN data is included in `FEATHER/cheetah/`.

---

## Calibration Files

Calibration is handled by `getCalibration` (stimlist already uses calibrated values from ExpControl) or `calculateCalibration` (stimlist stores raw drive percentages and FEATHER interpolates to mW).

### When is a calibration file needed?

| Experiment type | Function to call | Calibration file needed? |
|----------------|-----------------|--------------------------|
| `OBIS_*`, `OXXIUS_*`, `DarkRedLaser_*` | `getCalibration` or `calculateCalibration` | ✔ see below |
| `SBcreeLED10x1` | `calculateCalibration` | ✔ see below |
| Acoustic (`MX_tones`) | — | ✗ no file needed |

### File naming convention

Calibration files are expected in the **IC raw data directory** (default) or a custom `calibDir`.  
They are generated by the custom-written MATLAB GUI **LaserControl**, but other calibration files can be parsed into the same format and then used.
The calibration file naming conventions are:

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

Examples:
  20240312_OBIS_COM10_Power_Calibration_0.txt
  20240312_OBIS_COM10_Power_Calibration_1.txt     (OD 1 filter)
  20240312_SB_COM5_Power_Calibration_ID_XYZ_ResistorNo_2.txt  (µLED)
```

The `OD` describes a manual set parameter such as an optical density filter or the applied voltage in a laser that then changes the current for different intensities. The `ComPort` is important if more than one laser of a type is connected to a setup. The  `OD` and `ComPort` parameters must match what was entered in `ICuserInput.mlapp` (stored in `ICUserInput_<ExpID>.mat` in the processed data directory) for the correct association from calibration files to icmes.

### File content

Each calibration file contains a short header followed by a tab-delimited table.  
The header must contain the string `Power (mW)` for automatic header-detection.  
Expected columns (default names):

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

### User-input prerequisite

The GUI `ICuserInput.mlapp` must be completed before calling any calibration function.  
It saves `ICUserInput_<ExpID>.mat` to `processedDataDir/ICME/` and records for each `icme`:

- Whether the recording should be used (`Use` flag: `1` = use, `-1` = skip)
- The **OD filter** value applied during the recording
- The **COM port** of the laser
- The **stimulus type** (from a dropdown)
- Electrode probe / position information

---
## Processing Overview

| Step | Function | Description |
|------|----------|-------------|
| 1 | `allIcme(ee)` | Calls `initIcme` for all ICs (whole `anex`): loads log file and saves initial icme objects |
| 2 | `ICuserInput(ee)` | GUI: records hardware, filter, quality flags per icme |
| 3 | `getCalibration` / `calculateCalibration` | Reads LaserControl `.txt` file and populates `icme.C` |
| 4 | `ExtractMUAfromRawDataIntoSL` | Reads `.ncs` / `.nev` files, detects MU spikes, fills `icme.SL`, and optionally saves a spike-list `.txt` export |
| 5 | `saveIcme` | Saves icme to `processedDataDir/ICME/IC/IC_<ExpID>_<SeriesID>.mat` |
| 6 | `calculateSpikeRate` | Calculates mean spike rate and per-repetition spike rate in a chosen response window |
| 7 | `calculateDprimeMultipleStimVars` | Calculates d' across stimuli (baseline or increasing-level mode), commonly used for threshold analyses |
| 8 | `getResponsiveUnits` | Returns electrodes with significant responsiveness based on d' (`> 1`) |
| 9 | `calculateSOEContourlinesMultipleStimVars` | Calculates the spread of excitation based on the heatmap contourlines with different methods |
| 10 | `calculatePSTH` | Calculates PSTH and response timing metrics (onset, offset, peak response time) |
| 11 | `calculateVS` | Calculates vector strength and phase locking significance for trains of stimuli |
| ... | | more functions can be found by calling `methods icme` |



