{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "3e45b3bc-e4fa-4247-bccd-0e049bb97afa",
   "metadata": {},
   "source": [
    "# Tutorial about fluopy - add fluorophore and transition data"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "70389406-e48d-4984-a6c8-202e44f6d19a",
   "metadata": {},
   "source": [
    "Here we provide some hints on extending fluoropy with new fluorophore and transition data."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "69c0ebd0-b041-4676-b14b-a51a47334bef",
   "metadata": {},
   "source": [
    "## Naming conventions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c5863e2c-c435-4183-91ae-001d3b3db578",
   "metadata": {},
   "source": [
    "|name|meaning|\n",
    "|---|---|\n",
    "|SingleState|photophysical state fo a single fluorophore|\n",
    "|PairedState|Two SingleStates of paired fluorophores as in donor and acceptor pairs|\n",
    "|Transition|constant and variable attributes of photophysical transition|\n",
    "|combined states|combinations of SingleStates depending on number of fluorophores|\n",
    "|combined state transition|transitions between combined states|\n",
    "|realizable|theoretically possible|\n",
    "|resample|change the frame integration time|"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3e1ea529",
   "metadata": {},
   "source": [
    "## Adding a fluorophore\n",
    "1. Create a new instance of FluorophoreData in fluodata.py\n",
    "2. Overwrite the known constants**\n",
    "3. Create a Fluorophore instance with a name matching the variable in fluodata.py\n",
    "4. Provide datafiles containing absorption and emission spectra* in a folder in fluorophore_spectra and keep the naming convention (e.g., absorption of S0 should be named absorption_S0.csv). The name of the folder should be provided as a str in fluo_data.py (data_files=str)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "96c80306",
   "metadata": {},
   "source": [
    "## Adding a single state transition\n",
    "1. Check if the involved photophysical states are present in transitions.py SingleState, if not, add them\n",
    "2. Add the transition as a transition.py - TransitionType\n",
    "3. For automatic read-in, add the rate constant to fluo_data.py (to base class with value 0 and to class instance with true value). Add the transition to transitions.py - derive_transitions(). If the rate depends on other factors, add appropriate constants to fluo_data.py**, look for an appropriate function in formulas.py and if not available, add it. Call the function in derive_transitions() to get the rate constant."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b0d91877",
   "metadata": {},
   "source": [
    "## Adding an ET transition\n",
    "1. Check if the involved photophysical states are present in transitions.py SingleState and if the PairedState exists, if not, add them\n",
    "2. Add the transition as a transition.py - TransitionType\n",
    "3. For automatic read-in, provide absorption spectra* of the acceptor state and emission spectra* for the donor state. Add the transition to transitions.py - derive_energy_transfer_transitions(). "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f97f7213-0c66-4f51-83d3-c05df4f5db56",
   "metadata": {},
   "source": [
    "## Keep in mind"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f15bacf2",
   "metadata": {
    "vscode": {
     "languageId": "plaintext"
    }
   },
   "source": [
    "### Spectra\n",
    "The absorption spectra should contain absolute extinction coefficient values for each wavelength (nm) [200, 201, ..., 1000]. The emission spectrum should contain relative values where 1 corresponds to maximum emission, for each wavelength (nm) [200, 201, ..., 1000]."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "896e067f",
   "metadata": {},
   "source": [
    "## Constants\n",
    "If a cross section is provided, it should correspond to the excitation wavelength used. Energy transfers refer to absorption spectra, not individual cross sections."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.14.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}