{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Thunor Core Tutorial"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "**Thunor** (pronounced THOO-nor) is a free software platform to manage,\n",
    "visualise, and analyse high throughput cell proliferation data,\n",
    "which measure the dose-dependent response of cells to one or more drug(s).\n",
    "\n",
    "This repository, [Thunor Core](https://github.com/alubbock/thunor), is a\n",
    "Python package which can be used for standalone analysis or integration\n",
    "into computational pipelines.\n",
    "\n",
    "A web interface is also available, called [Thunor Web](https://github.com/alubbock/thunor-web).\n",
    "Thunor Web has a [comprehensive manual](https://docs.thunor.net), which goes\n",
    "into further detail about the curve fitting methods, types of plots\n",
    "available and other information you may find relevant.\n",
    "\n",
    "Please see the [Thunor website](https://www.thunor.net) for additional resources,\n",
    "and a link to our chat room, where you can ask questions about Thunor."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Load a file"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "First, load the example dataset bundled with the package. `hts007` is a\nDIP rate screen of 27 drugs on 8 breast cancer cell lines, with cell count\nmeasurements taken roughly every 6–8 hours over approximately 5 days.\n\nFor your own data, use `read_hdf` for HDF5 files or `read_vanderbilt_hts`\nfor plain-text files."
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import importlib.resources\n",
    "from thunor.io import read_hdf\n",
    "\n",
    "with importlib.resources.as_file(\n",
    "    importlib.resources.files('thunor') / 'testdata/hts007.h5'\n",
    ") as hts007_path:\n",
    "    hts007 = read_hdf(hts007_path)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We'll just use a subset of the drugs, to make the plots manageable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hts007r = hts007.filter(drugs=['cediranib', 'everolimus', 'paclitaxel'])"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hts007r.drugs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "hts007r.cell_lines"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": "## Calculate DIP rates and parameters\n\nThese two operations can be done in two lines of code (plus imports)."
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from thunor.dip import dip_rates\n",
    "from thunor.curve_fit import fit_params\n",
    "\n",
    "ctrl_dip_data, expt_dip_data = dip_rates(hts007r)\n",
    "fp = fit_params(ctrl_dip_data, expt_dip_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setting up plots\n",
    "\n",
    "Each of the `plot_X` functions returns a plotly `Figure` object. When displayed in a notebook or on this documentation page, plots are rendered interactively. To save a plot as a standalone HTML file, use `plotly.io.write_html`; see the [plotly documentation](https://plotly.com/python/interactive-html-export/) for details."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from thunor.plots import (\n",
    "    plot_drc,\n",
    "    plot_drc_params,\n",
    "    plot_time_course,\n",
    "    plot_ctrl_dip_by_plate,\n",
    "    plot_plate_map,\n",
    ")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "import plotly.io as pio\n",
    "\n",
    "# Use the notebook_connected renderer so plots display correctly in\n",
    "# both Jupyter and on the documentation pages (nbsphinx).\n",
    "pio.renderers.default = 'notebook_connected'"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Plot Types\n",
    "\n",
    "### Plot DIP rate curves"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_drc(fp)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {
    "collapsed": true
   },
   "source": [
    "### Plot DIP parameters"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_drc_params(fp, 'auc')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Filtering fit params\n",
    "\n",
    "The `fp` object is a pandas data frame, so we can filter it before plotting. Some examples:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fit_params_bt20_pac = fp[\n",
    "    fp.index.isin(['BT20'], level='cell_line')\n",
    "    & fp.index.isin(['paclitaxel'], level='drug')\n",
    "]\n",
    "\n",
    "plot_drc(fit_params_bt20_pac)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Plot time course\n",
    "\n",
    "Time course plot for paclitaxel on BT20 cells:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_time_course(hts007.filter(drugs=['paclitaxel'], cell_lines=['BT20']))"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Quality control check: plot DIP rate ranges by cell line and plate (box plot)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": false
   },
   "outputs": [],
   "source": [
    "plot_ctrl_dip_by_plate(ctrl_dip_data)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Quality control check: plot DIP rate as a plate heat map"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plate_data = hts007.plate('HTS007_149-28A', include_dip_rates=True)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_plate_map(plate_data, color_by='dip_rates')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Viability analysis\n",
    "\n",
    "For single-timepoint assays (e.g. 72-hour viability), use `viability` instead of\n",
    "`dip_rates`. The curve fitting and plotting workflow is the same, but uses a\n",
    "three-parameter Hill curve (`HillCurveLL3u`) rather than the four-parameter\n",
    "DIP rate model."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from thunor.viability import viability\n",
    "from thunor.curve_fit import HillCurveLL3u\n",
    "\n",
    "viability_data, _ = viability(hts007r, include_controls=False)\n",
    "vp = fit_params(ctrl_data=None, expt_data=viability_data, fit_cls=HillCurveLL3u)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "plot_drc(vp)"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": ".venv",
   "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.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 1
}