{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "170380fc-ed7d-424a-a474-134100bd3532",
   "metadata": {},
   "source": [
    "# Interactive Clean\n",
    "The CASA interactive clean application is available for use in Jupyter notebooks. The primary difference between usage in Jupyter and usage directly from a Python command line interface (CLI) is that the `iclean.notebook` function is used within a notebook instead of the `iclean` function that is used from the Python CLI.\n",
    "\n",
    "## Current status\n",
    "\n",
    "Currently the interactive clean app works well when a **single** instance is run within a notebook **and** the Jupyter kernel is running on the same host as the browser displaying the notebook. Things begin to go wrong when the *red stop sign* is pressed. Doing this is necessary because this is how the `iclean` return dictionary is returned. The `get_result` function blocks until the *red stop sign* is clicked and confirmed. At this point, the `iclean` return dictionary is returned as the result of `get_result`. Another function called `get_future` is available which does not block but instead retrieved the future where the `iclean` return dictionary will eventually appear.\n",
    "\n",
    "Supporting, multiple `iclean` instances within a single worksheet is the goal, but currently only one instance should be used, *unless you are willing to risk corruption of your Jupyter session*. All of the GUI display cells in this notebook are beleved to work when a **single** one is executed within a given notebook instance.\n",
    "\n",
    "## Which version of cubevis to use\n",
    "\n",
    "The current version of `cubevis` to use is [v1.0.14](https://pypi.org/project/cubevis/1.0.14/).\n",
    "\n",
    "## Setup\n",
    "This first cell ensures that CASA 6 and cubevis are available:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9f8d3c54-6691-4674-ba81-6d9387a53f84",
   "metadata": {},
   "outputs": [],
   "source": [
    "!mkdir -p ~/.casa/data\n",
    "!pip install --upgrade \"bokeh>=3.8\" \"casatasks>=6.7.2.42\" cubevis"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b16f7cb4-ba89-4fc3-b31d-6df60c3bf495",
   "metadata": {},
   "source": [
    "This cell simply retrieves the test data that is required."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "738dd1a5-2fa5-4824-a2d5-d3b0db850a8a",
   "metadata": {},
   "outputs": [],
   "source": [
    "import os\n",
    "import ssl\n",
    "import certifi\n",
    "import urllib\n",
    "import tarfile\n",
    "ms_path = 'refim_point_withline.ms'\n",
    "ms_url = \"https://casa.nrao.edu/download/devel/casavis/data/refim_point_withline-ms.tar.gz\"\n",
    "if not os.path.isdir(ms_path):\n",
    "    try:\n",
    "        context = ssl.create_default_context(cafile=certifi.where())\n",
    "        tstream = urllib.request.urlopen(ms_url, context=context, timeout=400)\n",
    "        tar = tarfile.open(fileobj=tstream, mode=\"r:gz\")\n",
    "        tar.extractall(filter='data')\n",
    "    except urllib.error.URLError:\n",
    "        print(\"Failed to open connection to \"+ms_url)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "68fdc83b-17d1-4d8e-a12e-2c420cb13a35",
   "metadata": {},
   "source": [
    "## Import\n",
    "The first step is to import the `iclean` function:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aac06f5e-27cf-4465-983c-967f6dca2a66",
   "metadata": {},
   "outputs": [],
   "source": [
    "from cubevis import iclean"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5b93ca76-abe4-42e2-940b-e312bb3e9203",
   "metadata": {},
   "source": [
    "## Cleanup\n",
    "`iclean` operates on state contained within files in the current directory, so it is always a good idea to make sure that you are starting with a clean slate. This command removes the state files that accumulate from running this example."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c2998492-96d3-46a1-b830-c2fa50d1a8f3",
   "metadata": {},
   "outputs": [],
   "source": [
    "!rm -rf test.*"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4505c0a4-b73b-43a6-a265-29bf4157d544",
   "metadata": {},
   "source": [
    "## Create the Application Object\n",
    "This cell creates the interactive clean application object. This object is used to display the GUI and to retreive the `iclean` return dictionary from the GUI once the user has completed cleaning."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "415cf4e6-4e29-4b86-8d35-7d38485b22f4",
   "metadata": {},
   "outputs": [],
   "source": [
    "ic = iclean.notebook( vis=ms_path, imagename='test',\n",
    "                      imsize=512, niter=50,\n",
    "                      cycleniter=10,\n",
    "                      cell='12.0arcsec',\n",
    "                      specmode='cube', interpolation='nearest',\n",
    "                      nchan=5, start='1.0GHz', width='0.2GHz', pblimit=-1e-05,\n",
    "                      deconvolver='hogbom', threshold='0.001Jy', cyclefactor=3, scales=[0,3,10] )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e73d12a1-327d-483c-9835-d6fccb5a04ad",
   "metadata": {},
   "source": [
    "## Display the GUI\n",
    "Once the application object has been created, the GUI can be displayed:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0a465972-26e9-44ca-8bc1-9f2e3c789c3a",
   "metadata": {},
   "outputs": [],
   "source": [
    "ic.show( )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0fca3f96-f725-4155-a2de-b197fe7c196f",
   "metadata": {},
   "source": [
    "## Retrieve the result\n",
    "Once the user has completed cleaning, clicked the stop sign and approved the exiting the application, the result can be retrieved:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8c555250-7425-43e2-83f7-0ba2d0a6ff21",
   "metadata": {},
   "outputs": [],
   "source": [
    "ic.get_result( )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a9f3aba7-7c19-4876-84a4-14a14e89e87e",
   "metadata": {},
   "source": [
    "## Alternate ways to display the GUI\n",
    "While this is the most obvious way to create and use the interactive clean within a Jupyter notebook, there are also some subtle variations.\n",
    "\n",
    "### Display as a result of cell evaulation\n",
    "The last evaluated statement in a notebook cell is displayed and displaying the `iclean` application object results in the GUI being displayed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "537b51db-0d57-43e4-96b3-45e65fa6d1ff",
   "metadata": {},
   "outputs": [],
   "source": [
    "!rm -rf test.*\n",
    "iclean.notebook( vis=ms_path, imagename='test',\n",
    "                 imsize=512, niter=50,\n",
    "                 cycleniter=10,\n",
    "                 cell='12.0arcsec',\n",
    "                 specmode='cube', interpolation='nearest',\n",
    "                 nchan=5, start='1.0GHz', width='0.2GHz', pblimit=-1e-05,\n",
    "                 deconvolver='hogbom', threshold='0.001Jy', cyclefactor=3, scales=[0,3,10] )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "94ec4e93-0156-4791-938d-72358bc303c4",
   "metadata": {},
   "source": [
    "### Retrieving the result\n",
    "Even though we did not retain the application object, the value of the **last** cell evaluation is available as `_`. So using this, we can retrieve the return dictionary:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "10755706-58fc-40eb-81e0-a45c0b77d4e0",
   "metadata": {},
   "outputs": [],
   "source": [
    "_.get_result( )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ac33d8bf-3a21-4c84-b940-e94afdf98fc0",
   "metadata": {},
   "source": [
    "### Using Bokeh's show function\n",
    "One last slight variation is to use [Bokeh's](https://bokeh.org/) `show` function to display the application object:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "437e425d-96a1-4007-a131-cf6d1d3b4379",
   "metadata": {},
   "outputs": [],
   "source": [
    "!rm -rf test.*\n",
    "from bokeh.io import output_notebook\n",
    "from bokeh.plotting import show\n",
    "output_notebook( )\n",
    "ic = iclean.notebook( vis=ms_path, imagename='test',\n",
    "                      imsize=512, niter=50,\n",
    "                      cycleniter=10,\n",
    "                      cell='12.0arcsec',\n",
    "                      specmode='cube', interpolation='nearest',\n",
    "                      nchan=5, start='1.0GHz', width='0.2GHz', pblimit=-1e-05,\n",
    "                      deconvolver='hogbom', threshold='0.001Jy', cyclefactor=3, scales=[0,3,10] )\n",
    "show(ic)"
   ]
  }
 ],
 "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.11.13"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}