# `histimg` – Histology Image Object

A `histimg` object stores quantification results from one histology image stack, typically a single cochlear region that was analysed using the Arivis-based analysis pipeline **Nintendo** first described in Thirumalai _et al._ 2025 (doi:10.7150/thno.104474). The pipeline handles images obtained with a confocal microscope with a 40× oil-immersion objective from slices stained against parvalbumin as a neuronal context marker and GFP as a marker for an introduced transgene. It uses Cellpose to detect cells and overlays the GFP channels with the segmented cells to obtain a transduction rate. The analysis produces an output `.csv` file with all important values. In theory, parsing output files from other analysis pipelines into the same type of `.csv` files could also be used as an interface with FEATHER.

## Raw Data

### Directory type

The `histimg` object reads from a raw-data directory registered in the parent `anex` with `type = "NintendoRes"`.  
This directory should contain the `.csv` export files generated by the analysis pipeline.

### File naming convention

Each `.csv` file corresponds to one image set. Files must include the **experiment ID** (or the animal number extracted from it) in their filename so that `listHistImgsRaw` can associate them with the correct experiment.  
Metadata encoded in the filename is used to set `histimg.side`, `histimg.turn`, and `histimg.version`:

```
<ExpID>_<Side><Turn>[-<version>].csv

Examples:
  GEK030_Rapex.csv            → side=R, turn=apex, version=1
  GEK030_Lbase_v2.csv         → side=L, turn=base, version=2
  GEK030_Lmid_v1_40x.csv     → side=L, turn=mid,  version=1
```

| Filename token | Property set | Expected values |
|---------------|-------------|-----------------|
| `L` or `R` | `histimg.side` | `L` / `R` |
| `apex`, `base`, or `mid` | `histimg.turn` | `apex` / `base` / `mid` |
| `v<n>` | `histimg.version` | integer ≥ 1 (default 1) |

### CSV file content

Each `.csv` file must be comma-delimited and contain a header row.  
The following column names are read by `readNintendoResults`:

| Column name | Required | Description |
|-------------|----------|-------------|
| `AllSGNs` | ✔ | Total number of detected spiral ganglion neurons in the full volume |
| `No_Positive` | ✔ | Number of GFP-positive (transduced) neurons in the full volume|
| `Volume_ROI_microm3_` | ✔ | 3D volume of the region of interest [µm³] |
| `AllSGNsSlice` | optional | SGN count from a single slice placed in the center of the stack |
| `Volume_Slice_microm3_` | optional | Volume of the single center slice [µm³] (for 2-D density calculation) |
| `numPlanesVolume` | optional | Number of optical planes in the 3-D volume (each 1 µm thick) |
| `usedGFPThreshold` | optional | GFP threshold used during analysis |

## Calibration / Hardware Files

The `histimg` object does **not** require any instrument-specific calibration files.  
Imaging parameters (objective, voxel size, etc.) are expected to be stored with the raw confocal image stack in a format readable by a future `readMicroscopeSettings` function (not yet implemented).

---

## SeriesID Format

The `SeriesID` passed at construction time must encode the relevant imaging metadata so that `histimg` can self-populate `side`, `turn`, and `version`:

```
<Side>_<turn>_<v<version>>_40x

Examples:
  R_apex_v1_40x
  L_base_v2_40x
  L_mid_v1_40x
```

---

## Processing Overview

| Step | Function | Description |
|------|----------|-------------|
| 1 | `listHistImgsRaw(ee)` | Scans the `NintendoRes` raw directory and builds a list of available image series |
| 2 | `histimg(ee, SeriesID, D, filename)` | Constructs the object; parses side/turn/version from SeriesID |
| 3 | `readNintendoResults(obj)` | Reads the `.csv` file and populates all density/count properties |
| 4 | `saveHistimg(obj)` | Saves the object to `processedDataDir/HISTO/H_<ExpID>_<SeriesID>.mat` |
| 5 | `chooseHistImgToUse.mlapp` | GUI for selecting the preferred image when multiple exist for the same region |

---

## Key Object Properties

| Property | Unit | Description |
|----------|------|-------------|
| `nCells` | count | Total number of SGNs detected |
| `nPosCells` | count | Number of GFP-positive (transduced) SGNs |
| `volume` | µm³ | 3-D ROI volume (automatic detection) |
| `density` | SGNs / 10⁵ µm³ | SGN density from automatic volume |
| `transductionRate` | fraction 0–1 | `nPosCells / nCells` |
| `areaSlice` | µm² | 2-D ROI area from a center slice |
| `density2D` | SGNs / 10³ µm² | 2-D density derived from a center slice of the stack |
