{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# The Recording container\n",
    "\n",
    "WIP\n",
    "\n",
    "The class `cedalion.dataclasses.Recording` can be used to carry related data objects through the program. It can store time series, masks, auxiliary timeseries, probe, headmodel and stimulus information as well as meta data about the recording.\n",
    "It has the following properties:\n",
    "\n",
    "- It resembles the [NIRS group in the snirf specification](https://github.com/fNIRS/snirf/blob/v1.1/snirf_specification.md#nirsi), which provides storage for much of the data stored in a `Recording` (e.g. time series map to [data elements](https://github.com/fNIRS/snirf/blob/v1.1/snirf_specification.md#nirsidataj), [probe](https://github.com/fNIRS/snirf/blob/v1.1/snirf_specification.md#nirsiprobe), [stimulus](https://github.com/fNIRS/snirf/blob/v1.1/snirf_specification.md#nirsistimj) and [meta data](https://github.com/fNIRS/snirf/blob/v1.1/snirf_specification.md#nirsimetadatatags) are stored per NIRS element, etc). Consequently, the methods `cedalion.io.read_snirf` and `cedalion.io.write_snirf` methods operate on lists of recordings.\n",
    "- different time series and masks are stored in ordered dictionaries\n",
    "  - user differentiates time series by name\n",
    "  - there is a set of canonical names used by `read_snirf` to assign names to time series\n",
    "    ```\n",
    "    CANONICAL_NAMES = {\n",
    "          \"unprocessed raw\": \"amp\",\n",
    "          \"processed raw\": \"amp\",\n",
    "          \"processed dOD\": \"od\",\n",
    "          \"processed concentrations\": \"conc\",\n",
    "          \"processed central moments\": \"moments\",\n",
    "          \"processed blood flow index\": \"bfi\",\n",
    "          \"processed HRF dOD\": \"hrf_od\",\n",
    "          \"processed HRF central moments\": \"hrf_moments\",\n",
    "          \"processed HRF concentrations\": \"hrf_conc\",\n",
    "          \"processed HRF blood flow index\": \"hrf_bfi\",\n",
    "          \"processed absorption coefficient\": \"mua\",\n",
    "          \"processed scattering coefficient\": \"musp\",\n",
    "    }\n",
    "    ```\n",
    "- time series are stored in the dictionaries in the order that they were added\n",
    "- convenient access to the last changed time series + canonical names -> consecutive transformations of time series without the need to specify time series by name -> workflows\n",
    "- `rec[key]` is a shortcut for `rec.timeseries[key]` \n",
    "- not all information stored in a `Recording` can be stored in snirf files, e.g. for masks, the headmodel and auxiliar objects there is no provision in the snirf specification. We will probably use sidecard files or sidecar hdf groups to store these."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "cedalion_240720",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.11.8"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}