{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "55ec15f1",
   "metadata": {},
   "source": [
    "## Working with Reports\n",
    "For the use case, where you are using basico to prepare files to run later (say on a cluster environment or such). It is often useful to manipulate the report definitions we store in COPASI files. This notebook demonstrate to work with them. Lets just start by importing basico."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "b3ca70fe",
   "metadata": {},
   "outputs": [],
   "source": [
    "from basico import *"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4f167b1f",
   "metadata": {},
   "source": [
    "here we simply load the brusselator example: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "225be197",
   "metadata": {},
   "outputs": [],
   "source": [
    "load_example('brusselator');"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cd284f99",
   "metadata": {},
   "source": [
    "### Retrieving Report Definitions\n",
    "The first function to look into is `get_reports` which will retrieve all report definition encoded in the file and returns its content as a data frame. You can filter by name, task or whether or not the reports is an automatically generated one. So while the following line reports there are 11 reports in the model, we can ignore them if we so choose (hence not getting a result printed at the end)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "e10e0996",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "there are 11 reports in the model\n"
     ]
    }
   ],
   "source": [
    "print('there are {0} reports in the model'.format(len(get_reports())))\n",
    "get_reports(ignore_automatic=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1c7c4362",
   "metadata": {},
   "source": [
    "lets look at the reports that apply to steady state tasks:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "4b023a76",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/html": [
       "<div>\n",
       "<style scoped>\n",
       "    .dataframe tbody tr th:only-of-type {\n",
       "        vertical-align: middle;\n",
       "    }\n",
       "\n",
       "    .dataframe tbody tr th {\n",
       "        vertical-align: top;\n",
       "    }\n",
       "\n",
       "    .dataframe thead th {\n",
       "        text-align: right;\n",
       "    }\n",
       "</style>\n",
       "<table border=\"1\" class=\"dataframe\">\n",
       "  <thead>\n",
       "    <tr style=\"text-align: right;\">\n",
       "      <th></th>\n",
       "      <th>separator</th>\n",
       "      <th>precision</th>\n",
       "      <th>task</th>\n",
       "      <th>comment</th>\n",
       "      <th>is_table</th>\n",
       "      <th>header</th>\n",
       "      <th>body</th>\n",
       "      <th>footer</th>\n",
       "    </tr>\n",
       "    <tr>\n",
       "      <th>name</th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "      <th></th>\n",
       "    </tr>\n",
       "  </thead>\n",
       "  <tbody>\n",
       "    <tr>\n",
       "      <th>Steady-State</th>\n",
       "      <td>\\t</td>\n",
       "      <td>6</td>\n",
       "      <td>Steady-State</td>\n",
       "      <td>&lt;body xmlns=\"http://www.w3.org/1999/xhtml\"&gt;\\n ...</td>\n",
       "      <td>False</td>\n",
       "      <td>[]</td>\n",
       "      <td>[]</td>\n",
       "      <td>[CN=Root,Vector=TaskList[Steady-State]]</td>\n",
       "    </tr>\n",
       "  </tbody>\n",
       "</table>\n",
       "</div>"
      ],
      "text/plain": [
       "             separator  precision          task  \\\n",
       "name                                              \n",
       "Steady-State        \\t          6  Steady-State   \n",
       "\n",
       "                                                        comment  is_table  \\\n",
       "name                                                                        \n",
       "Steady-State  <body xmlns=\"http://www.w3.org/1999/xhtml\">\\n ...     False   \n",
       "\n",
       "             header body                                   footer  \n",
       "name                                                               \n",
       "Steady-State     []   []  [CN=Root,Vector=TaskList[Steady-State]]  "
      ]
     },
     "execution_count": 4,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_reports(task=T.STEADY_STATE)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1dce2981",
   "metadata": {},
   "source": [
    "analoge as to when working with plots, the reports can be retrieved as dictionaries, by specifying the name of the report to retrieve. The dictionary will either include a key `body` with lists of elements to collect (in that case `is_table` will be `True`), or as seen below, a `header`, `body` and `footer` entries. Each entry in those lists can be either a display name, or common name (as not all elements can be retrieved via names). \n",
    "\n",
    "The key thing to keep in mind, is that `header` entries will be collected before runing the task, `body` and `table` entries during running of the task. And `footer` entries, once the task is complete. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "0d9f750c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'Steady-State',\n",
       " 'separator': '\\t',\n",
       " 'precision': 6,\n",
       " 'task': 'Steady-State',\n",
       " 'comment': '<body xmlns=\"http://www.w3.org/1999/xhtml\">\\n          Automatically generated report.\\n        </body>',\n",
       " 'is_table': False,\n",
       " 'header': [],\n",
       " 'body': [],\n",
       " 'footer': ['CN=Root,Vector=TaskList[Steady-State]']}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_report_dict('Steady-State')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c9605b50",
   "metadata": {},
   "source": [
    "### Adding Reports\n",
    "lets add a new report for a custom time course in which we collect the models time, the concentration of the species `X` and their rate of change: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "10ee2a3a",
   "metadata": {},
   "outputs": [],
   "source": [
    "add_report('X Time-Course', task=T.TIME_COURSE, table=['Time', '[X]', 'X.Rate']);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "31087f6f",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'X Time-Course',\n",
       " 'separator': '\\t',\n",
       " 'precision': 6,\n",
       " 'task': 'Time-Course',\n",
       " 'comment': '',\n",
       " 'is_table': True,\n",
       " 'print_headers': True,\n",
       " 'table': ['Time', '[X]', 'X.Rate']}"
      ]
     },
     "execution_count": 7,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_report_dict('X Time-Course')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8ff154c9",
   "metadata": {},
   "source": [
    "the value in `print_headers` indicates, whether the name of the elements will be printed in the header column. "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1b3d7612",
   "metadata": {},
   "source": [
    "using the `table` element directly, does only work for tasks that generate output *during* the execution of the task, as in the time course example above. Other tasks, such as steady state computation only provide results *after* the task has completed. In the following we add a report for the steady state concentration (and rate of X). We use the function `wrap_copasi_string`, to indicate that we want to have the literal string `[X]` in the header, rather than the initial concentration. \n",
    "\n",
    "One other important thing to note, is that when specifying headers manually, the separators also need to be included manually. That can be done using the separator char manually, or the special String `Separator=\\t` to indicate that it is the separator of the report. Alternatively, you can specify the boolean flagg `add_sepratator=True`, so that between header, footer and body entries the separator is automatically added. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "098b31bd",
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    "add_report('X Steady-State', task=T.STEADY_STATE, \n",
    "           header=[wrap_copasi_string('[X]'), wrap_copasi_string('X.Rate')], \n",
    "           footer=['[X]','X.Rate'], add_separator=True);"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "554e0136",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'X Steady-State',\n",
       " 'separator': '\\t',\n",
       " 'precision': 6,\n",
       " 'task': 'Steady-State',\n",
       " 'comment': '',\n",
       " 'is_table': False,\n",
       " 'header': ['String=\\\\[X\\\\]', 'Separator=\\t', 'String=X.Rate'],\n",
       " 'body': [],\n",
       " 'footer': ['[X]', 'Separator=\\t', 'X.Rate']}"
      ]
     },
     "execution_count": 10,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_report_dict('X Steady-State')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6742259a",
   "metadata": {},
   "source": [
    "### Changing values\n",
    "of course all the values can be changed using the `set_report_dict` function, say we wanted to collect CSV information for the plot above, we would specify to use `,` as separator: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 11,
   "id": "8dbe7023",
   "metadata": {},
   "outputs": [],
   "source": [
    "set_report_dict('X Time-Course', separator=',')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 12,
   "id": "cbb20d4c",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'name': 'X Time-Course',\n",
       " 'separator': ',',\n",
       " 'precision': 6,\n",
       " 'task': 'Time-Course',\n",
       " 'comment': '',\n",
       " 'is_table': True,\n",
       " 'print_headers': True,\n",
       " 'table': ['Time', '[X]', 'X.Rate']}"
      ]
     },
     "execution_count": 12,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_report_dict('X Time-Course')"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26ab3671",
   "metadata": {},
   "source": [
    "if you at any point set the `header`, `body` or `footer`, the `table` entries will be removed."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e8954a4b",
   "metadata": {},
   "source": [
    "### Assigning to task\n",
    "In order to use a report definition, it has to be assigned to a task. COPASI will only create the report if a filename is assigned to it."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 13,
   "id": "3d916516",
   "metadata": {},
   "outputs": [],
   "source": [
    "assign_report('X Time-Course', task=T.TIME_COURSE, filename='out.txt', append=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "da9c9a0a",
   "metadata": {},
   "source": [
    "Alternatively, it is also possible to assign a report directly using the `set_task_settings` method, so for example: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 14,
   "id": "251fdf2a",
   "metadata": {},
   "outputs": [],
   "source": [
    "set_task_settings(T.TIME_COURSE, \n",
    "   settings = {'report': \n",
    "              {'report_definition': 'X Time-Course'}})"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "afc4f443",
   "metadata": {},
   "source": [
    "that with `get_task_settings` you can query which report is assigned to a given task: "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 15,
   "id": "1b37f539",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "'X Time-Course'"
      ]
     },
     "execution_count": 15,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "get_task_settings(T.TIME_COURSE)['report']['report_definition']"
   ]
  }
 ],
 "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.10.4"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}