{
 "cells": [
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# pyINSPECTA demo"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "from __future__ import annotations\n",
    "\n",
    "import matplotlib as mpl\n",
    "import matplotlib.pyplot as plt\n",
    "\n",
    "mpl.rcParams[\"figure.dpi\"] = 150\n",
    "\n",
    "from sdhdf import SDHDF\n",
    "from sdhdf.logger import logger\n",
    "\n",
    "logger.setLevel(\"INFO\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's load an SDHDF file - it is represented by an SDHDF class instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "# SDHDF v1.9.3 (NOTE: This file has a single integration only)\n",
    "### Required to load local data for example - not needed for normal use\n",
    "from importlib import resources\n",
    "\n",
    "with resources.as_file(resources.files(\"sdhdf.data.tests\")) as test_data:\n",
    "    fname = \"sdhdf_v1.9.3.hdf\"\n",
    "    file_path = test_data / fname"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf = SDHDF(file_path, parallel=True)"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The SDHDF class instance contains information on the beams..."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.beams[0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "...and all associated metadata:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "editable": true,
    "slideshow": {
     "slide_type": ""
    },
    "tags": []
   },
   "outputs": [],
   "source": [
    "sdhdf.metadata"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Let's explore the observation metadata - for example the primary_header dataset can be displayed with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.metadata.primary_header"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The attribute keys and descriptions can be accessed with:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.metadata.primary_header.attrs.keys()"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.metadata.primary_header.attrs.values()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The attribute values, for example for the key 'TELESCOPE', can be accessed from the table:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.metadata.primary_header.table[\"TELESCOPE\"][0]"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The same applies for accessing the observation parameters with for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.metadata.obs_params"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The Beam class contains the subband data - these can be accessed in a similar way to the beams:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.beams[0].subbands"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "The data are stored as either an `xarray.Dataset` or `pandas.DataFrame` depending on the data type:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.beams[0].subbands[0].astronomy_dataset"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.metadata.frequency.table"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "For example, using the `xarray.DataArray` we have a lot of power to visualise and manipulate the data - see the [xarray documentation](https://docs.xarray.dev/en/stable/user-guide/data-structures.html) for more information.\n",
    "\n",
    "I've also implemented some commonly-used commands on methods inside the dataclasses. For example, we can make a waterfall plot, plot a spectrum, and inspect the metadata. This is all done with `xarray` or `pandas` under the hood - so much more complex investigations are possible using those tools."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": []
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Here's a waterfall plot, which can be called from the `SDHDF` and `Beam` classes, but is really calling the base method on the `Subband` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.plot_waterfall(\n",
    "    beam=0,\n",
    "    subband=0,\n",
    "    polarization=0,\n",
    "    flag=False,\n",
    "    norm=plt.cm.colors.LogNorm(vmin=1e0),\n",
    "    y=\"ELAPSED_TIME\",\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Note that this is just a wrapper around the methods in `xarray`. You can use these directly for powerful visualisation and processing functionality, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "if len(sdhdf.beams[0].subbands[0].astronomy_dataset.data[\"time\"]) != 1:\n",
    "    sdhdf.beams[0].subbands[0].astronomy_dataset.isel(polarization=0).data.plot(\n",
    "        norm=plt.cm.colors.LogNorm(vmin=1e0, vmax=1e4), x=\"frequency\", y=\"ELAPSED_TIME\"\n",
    "    )\n",
    "else:\n",
    "    logger.warning(\"Cannot create a waterfall plot with a single integration!\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "We can also plot the spectrum, for example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ax = sdhdf.plot_spectrum(\n",
    "    beam=0, subband=0, x=\"frequency\", flag=False, color=\"black\", linewidth=1\n",
    ")\n",
    "ax.set_yscale(\"log\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "A wide-band plot can be called from the `SDHDF` object, but it also really just calling down to the `Beam` class:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "ax = sdhdf.plot_wide(\n",
    "    beam=0, polarization=0, x=\"frequency\", flag=False, color=\"black\", linewidth=1\n",
    ")\n",
    "ax.set_yscale(\"log\")"
   ]
  },
  {
   "attachments": {},
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "Now let's try and apply the RFI flagging routine:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "sdhdf.auto_flag_rfi(sigma=5, n_windows=1, flag_persistent=False)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "fig, ax = plt.subplots()\n",
    "_ = sdhdf.plot_spectrum(\n",
    "    beam=0,\n",
    "    subband=0,\n",
    "    polarization=0,\n",
    "    x=\"frequency\",\n",
    "    flag=False,\n",
    "    color=\"black\",\n",
    "    linewidth=1,\n",
    "    alpha=0.2,\n",
    "    ax=ax,\n",
    ")\n",
    "ax.set_yscale(\"log\")\n",
    "\n",
    "_ = sdhdf.plot_spectrum(\n",
    "    beam=0,\n",
    "    subband=0,\n",
    "    polarization=0,\n",
    "    x=\"frequency\",\n",
    "    flag=True,\n",
    "    color=\"tab:red\",\n",
    "    linewidth=1,\n",
    "    ax=ax,\n",
    ")\n",
    "ax.set_yscale(\"log\")"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "sdhdf",
   "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.12.9"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 4
}