Integrate custom abundance widget as a full module

docs/io/visualization/abundance_widget.ipynb

@@ -0,0 +1,183 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Generating Custom Abundance Widget"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This notebook demonstrates how to generate and display Custom Abundance Widget."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "First, import `CustomAbundanceWidget` module from `visualization` subpackage to create the widget."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from tardis.visualization import CustomAbundanceWidget"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Initialize the GUI "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "There are four ways to generate the widget. You can generate it from `.yml`/`.csvy` configuration files before running any simulation."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Using a YAML file"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "widget = CustomAbundanceWidget.from_yml(\"tardis_example.yml\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Using a CSVY file"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# widget = CustomAbundanceWidget.from_csvy(\"demo.csvy\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Alternatively, you can generate the widget after the simulation from a Simulation instance or a saved simulation (HDF file)."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Using a Simulation object"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# sim = run_tardis(\"tardis_example.yml\")\n",
+    "# widget = CustomAbundanceWidget.from_sim(sim)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Using a HDF file"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# widget = CustomAbundanceWidget.from_hdf(\"demo.hdf\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Display the GUI"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "No matter which way you use to initialize the widget, you can call `.display()` to display the GUI easily."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "widget.display()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The image below is just a screenshot of the GUI for a demonstration purpose. If you want to interact with the GUI, please run the code in the notebook.\n",
+    "\n",
+    "![Custom Abundance Widget Demo](../images/custom_abundance_widget.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "interpreter": {
+   "hash": "42180fb7a26743e791b9c1155ac51f7e87399be241c0afbd4c0781c11826afd9"
+  },
+  "kernelspec": {
+   "display_name": "Python 3",
+   "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.7.10"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

docs/io/visualization/index.rst

@@ -27,4 +27,5 @@ Jupyter Notebooks, making data exploration much easier.
     :maxdepth: 2
 
     using_widgets
-    Generating Widgets in a Notebook <generating_widgets>
+    Generating Custom Abundance Widget <abundance_widget>
+    Generating Data Exploration Widgets <generating_widgets>

docs/io/visualization/using_widgets.rst

@@ -4,11 +4,87 @@ Using TARDIS Widgets
 
 This page describes what each TARDIS Widget has to offer and how you can make
 the best use of it. If you're looking for the code to generate widgets, head
-over to `Generating TARDIS Widgets <generating_widgets>`_ section and see the
+over to `Generating Custom Abundance Widget <abundance_widget>`_ section or 
+`Generating Data Exploration Widgets <generating_widgets>`_ section to see the
 notebook in action.
 
 Currently, TARDIS supports the following widgets:
 
+Custom Abundance Widget
+#######################
+This widget (or GUI) allows you to develop custom model compositions 
+graphically and output the model to a new file.
+
+.. image:: ../images/custom_abundance_widget.png
+    :alt: Demo of Custom Abundance Widget
+
+The GUI consists of three parts:
+
+1. **Visualization plot** - An interactive step graph that shows abundances 
+and densities as a function of velocity. 
+
+2. **Data editor** - An interface to edit abundances, densities and velocity 
+shells.
+
+3. **File output** - An output module to save the model compositions as a CSVY 
+file.
+
+Interacting with the GUI
+========================
+
+You can interact with this GUI in the following ways:
+
+Edit Abundances
+---------------
+There are two radio buttons which allow you to edit either single shell or 
+mutiple shells. The new input will be applied to selected shell(s) immediately 
+and the plot is updated at the same time. If you want to edit multiple shells 
+at a time, remember to choose the second radio button and set the range of 
+shell number using int slider. The selected shell(s) is highlighted in the 
+plot.
+
+.. image:: ../images/cus_abund_edit_abundance.gif
+    :alt: Demo of editing abundances
+
+Normalize Abundances
+--------------------
+Click `Normalize` button to normalize the abundances on selected shell(s) to 
+1. If you wish to keep the abundance of a certain element unchanged during the 
+normalization, you can select the checkbox near that element to lock it. 
+The normalization will be applied to other elements and the sum of the 
+abundances still remains at 1.
+
+.. image:: ../images/cus_abund_norm.gif
+    :alt: Demo of normalization
+
+Edit Densities
+--------------
+In `Edit Density` tab, you also can edit either single shell or the whole 
+density profile. To calculate a new profile, you need to choose the density 
+type and input required parameters.
+
+.. image:: ../images/cus_abund_edit_density.gif
+    :alt: Demo of editing densities
+
+Add New Element
+---------------
+At the bottom of the editor, the symbol input box allows you to add new element 
+or isotope to the model. It automatically recognizes whether the symbol exists 
+or whether the element is already in the model.
+
+.. image:: ../images/cus_abund_add_element.gif
+    :alt: Demo of adding new element
+
+Add New Shell
+-------------
+Another important functionality is to add new shell to the model. You need to 
+specify the velocity range of the new shell and abundances at that new shell 
+will be set to 0. Note that the existing shell(s) will be resized smartly if 
+the new shell overlaps with it.
+
+.. image:: ../images/cus_abund_add_shell.gif
+    :alt: Demo of adding new shell
+
 Shell Info Widget
 #################
 

tardis/visualization/__init__.py

@@ -7,4 +7,5 @@
     shell_info_from_hdf,
 )
 from tardis.visualization.widgets.line_info import LineInfoWidget
+from tardis.visualization.widgets.custom_abundance import CustomAbundanceWidget
 from tardis.visualization.tools.sdec_plot import SDECPlotter