examples/demo-basic.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Intro"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "This notebook demonstrates basic usage of the firefly_client API.\n",
    "\n",
    "Note that it may be necessary to wait for some cells (like those displaying an image) to complete before executing later cells."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Setup"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Imports for firefly_client:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from firefly_client import FireflyClient\n",
    "import astropy.utils.data\n",
    "using_lab = False\n",
    "#url = 'https://irsa.ipac.caltech.edu/irsaviewer'\n",
    "url = 'http://127.0.0.1:8080/firefly'\n",
    "#FireflyClient._debug= True"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The firefly_client needs to connect to a firefly server. In this example, we use the IRSA Viewer application for the server:"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instantiate `FireflyClient` using the URL above:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fc = FireflyClient.make_lab_client() if using_lab else FireflyClient.make_client(url)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Download Sample Data"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the following example, we download a sample image and table by using astropy (it's used only for convenience, firefly_client itself does not depend on astropy):"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Download a cutout of a WISE band as 1 FITS image:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "image_url = ('http://irsa.ipac.caltech.edu/ibe/data/wise/allsky/4band_p1bm_frm/6a/02206a' + \n",
    "             '/149/02206a149-w1-int-1b.fits?center=70,20&size=200pix')\n",
    "filename = astropy.utils.data.download_file(image_url, cache=True, timeout=120)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Download a 2MASS catalog using an IRSA VO Table Access Protocol ([TAP](https://irsa.ipac.caltech.edu/docs/program_interface/astropy_TAP.html)) search:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "table_url = (\"http://irsa.ipac.caltech.edu/TAP/sync?FORMAT=IPAC_TABLE&\" +\n",
    "                                             \"QUERY=SELECT+*+FROM+fp_psc+WHERE+CONTAINS(POINT('J2000',ra,dec),\" +\n",
    "                                             \"CIRCLE('J2000',70.0,20.0,0.1))=1\")\n",
    "tablename = astropy.utils.data.download_file(table_url, timeout=120, cache=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Display Tables and Catalogs"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Instantiating FireflyClient should open a browser to the firefly server in a new tab. You can also achieve this using the following method. The browser open only works when running the notebook locally, otherwise a link is displayed."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# localbrowser, browser_url = fc.launch_browser()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "If it does not open automatically, try using the following command to display a web browser link to click on:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fc.display_url()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, uncomment the lines below (while commenting out the 2 lines above) to display the browser application in the notebook:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# from IPython.display import IFrame\n",
    "# print('url: %s' % fc.get_firefly_url())\n",
    "# IFrame(fc.get_firefly_url(), 1100, 1000)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The current example involves 2 images in FITS format to be viewed through the chosen browser, both in different ways.\n",
    "For the 1st method, upload a local file to the server and then display it:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "imval = fc.upload_file(filename)\n",
    "status = fc.show_fits(file_on_server=imval, plot_id=\"wise-cutout\", title='WISE Cutout')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For the 2nd method, pull an image directly from a URL:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "status = fc.show_fits(file_on_server=None, plot_id=\"wise-fullimage\", \n",
    "                      URL='http://irsa.ipac.caltech.edu/ibe/data/wise/allsky/4band_p1bm_frm/6a/02206a' + \n",
    "             '/149/02206a149-w1-int-1b.fits')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Upload a catalog table (with coordinates) to the server so it will overlay the image with markers by default. Note that markers can be visible on both \"wise-cutout\" and \"wise-fullimage\" since they would include the same field of view:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "file= fc.upload_file(tablename)\n",
    "status = fc.show_table(file, tbl_id='tablemass', title='My 2MASS Catalog', page_size=50)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add an xy plot using the uploaded table data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "status = fc.show_xyplot(tbl_id='tablemass', xCol='j_m', yCol='h_m-k_m')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Alternatively, more generic method show_chart() can be used to create the same plot"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# trace0 = {'tbl_id': 'tablemass', 'x': \"tables::j_m\", 'y': \"tables::h_m-k_m\", \n",
    "#           'type' : 'scatter', 'mode': 'markers'}\n",
    "# status = fc.show_chart(data=[trace0])"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Zoom into the full image by a factor of 2 (note the `plot_id` parameter we used earlier)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "status = fc.set_zoom('wise-fullimage', 2)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Pan the full image to center on a given celestial coordinate:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "status = fc.set_pan('wise-fullimage', x=70, y=20, coord='J2000')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Set the stretch for the full image based on IRAF zscale interval with a linear algorithm:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "status = fc.set_stretch('wise-fullimage', stype='zscale', algorithm='linear')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Change color of the image:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "status = fc.set_color('wise-fullimage', colormap_id=6, bias=0.6, contrast=1.5)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Add region data to the cutout image (2 areas to begin with):"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "my_regions= ['image;polygon 125 25 160 195 150 150 #color=cyan',\n",
    "            'icrs;circle 69.95d 20d 30i # color=orange text={region 5/7}']\n",
    "status = fc.add_region_data(region_data=my_regions, region_layer_id='layer1',\n",
    "                  plot_id='wise-cutout')"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Remove the second region whlie keeping the first one visible:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fc.remove_region_data(region_data=my_regions[1], region_layer_id='layer1')"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": []
  }
 ],
 "metadata": {
  "anaconda-cloud": {},
  "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.12"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}