Merge pull request #73 from ratt-ru/dev

Ready for patch 0.4.1
ratt-ru · Jul 3, 2020 · c63193e · c63193e
2 parents 80276c3 + 13bb9b5
commit c63193e
Show file tree

Hide file tree

Showing 25 changed files with 647 additions and 384 deletions.
diff --git a/CHANGELOG.rst b/CHANGELOG.rst
@@ -1,3 +1,17 @@
+0.4.1
+-----
+**ragavi-gains**
+
+  - Supports all ``matplotlib`` type static outputs
+  - Generate additional static plot for interactive plots with more than 30,000 points
+  - Multiple tables also supported with static plots
+  - Adds option ``all`` to plot all amplitude, phase, real and imaginary plots in a single plot
+
+**ragavi-vis**
+
+  - Added colour bar to coloured iterated plots
+
+
 0.4.0
 -----
 **general**

diff --git a/docs/source/appendix.rst b/docs/source/appendix.rst
@@ -13,4 +13,4 @@ Visibilites
 ===========
 .. automodule:: ragavi.visibilities
    :members:
-   :exclude-members: DataCoreProcessor, hv_plotter
+   :exclude-members: DataCoreProcessor, plotter
diff --git a/docs/source/examples/gplot.png b/docs/source/examples/gplot.png
diff --git a/docs/source/examples/gplot_all.png b/docs/source/examples/gplot_all.png
diff --git a/docs/source/examples/gplot_all_html.png b/docs/source/examples/gplot_all_html.png
diff --git a/docs/source/examples/gplot_html.png b/docs/source/examples/gplot_html.png
diff --git a/docs/source/examples/high_res_amp_scan.png b/docs/source/examples/high_res_amp_scan.png
diff --git a/docs/source/examples/iter_amp_phase.png b/docs/source/examples/iter_amp_phase.png
diff --git a/docs/source/examples/iter_colour_amp_phase.png b/docs/source/examples/iter_colour_amp_phase.png
diff --git a/docs/source/examples/low_res_amp_scan.png b/docs/source/examples/low_res_amp_scan.png
diff --git a/docs/source/examples/single_amp_time.png b/docs/source/examples/single_amp_time.png
diff --git a/docs/source/examples/single_colour_amp_phase.png b/docs/source/examples/single_colour_amp_phase.png
diff --git a/docs/source/gains.rst b/docs/source/gains.rst
@@ -35,11 +35,10 @@ This will yield an output HTML file, with plots in the order
 | table4   |   0    |    F |
 +----------+--------+------+
 
-Note
-----
-* At least a single field, spectral window and correlation **must** be selected in order for plots to show up.
-* While antenna data can be made visible through clicking its corresponding legend, this behaviour is not linked to the field, SPW, correlation selection checkboxes. Therefore, clicking the legend for a specific antenna will make data from all fields, SPWs and correlation for that antenna visible. As a workaround, data points can be identified using tooltip information
-* Unless **all** the available fields, SPWs and correlations have not been selected, the antenna legends will appear greyed-out. This is because a single legend is attached to multiple data for each of the available categories. Therefore, clicking on legends without meeting the preceeding condition may lead to some awkward results (a toggling effect).
+.. note::
+    * At least a single field, spectral window and correlation **must** be selected in order for plots to show up.
+    * While antenna data can be made visible through clicking its corresponding legend, this behaviour is not linked to the field, SPW, correlation selection checkboxes. Therefore, clicking the legend for a specific antenna will make data from all fields, SPWs and correlation for that antenna visible. As a workaround, data points can be identified using tooltip information
+    * Unless **all** the available fields, SPWs and correlations have not been selected, the antenna legends will appear greyed-out. This is because a single legend is attached to multiple data for each of the available categories. Therefore, clicking on legends without meeting the preceeding condition may lead to some awkward results (a toggling effect).
 
 
 Use in Jupyter Notebooks
@@ -59,32 +58,24 @@ To use ``ragavi-gains`` in a notebook environment, run in a notebook cell
 
 Generating Static (Non-Interactive) Images
 ==========================================
-It is possible to generate PNG and SVG with ``ragavi-gains`` via two methods. The first method involves generating the HTML format first and then using the save tool found in the toolbar to download the plots. This method requires minimal effort although it may be a necessary redundancy to achieve the static image goal. The second method requires some additional setup, which may be slightly more taxing. 
+It is possible to generate png, ps, pdf, svg with ``ragavi-gains`` via two methods. The first method involves generating the HTML format first and then using the save tool found in the toolbar to download the plots. This method requires minimal effort although it may be a necessary redundancy to achieve the static image goal. 
 
-**Step 1**: Install selenium, which can be done via:
+The second method involves supplying the ``--plotname`` argument, including 
+the desired file extension. For example, ``--plotname test.png``. If only 
+this argument is supplied, then only a single static plot is generated. In 
+case of multiple tables, multiple static files will be generated. However, 
+in case one wants both static and interactive plots, both ``--htmlname`` and
+ ``--plotname`` must be supplied.
 
-.. code-block:: bash
-
-    pip install selenium
-
-**Step 2**: Download geckodriver for Firefox web browser, or chromedriver for Google chrome browser, and add it's executable to ``PATH``. Because Ubuntu linux ships with Firefox by default, I will demonstrate geckodriver v0.26.0, which is the latest driver at the time of wringing. The download page is `Geckodriver`_ 
-
-.. code-block:: bash
-
-    mkdir gecko && cd gecko
-
-    wget https://github.com/mozilla/geckodriver/releases/download/v0.26.0/geckodriver-v0.26.0-linux32.tar.gz
-
-    tar -xvzf geckodriver-v0.26.0-linux32.tar.gz
-
-    chmod +x geckodriver
-
-    export PATH=$PATH:/absolute/path/to/gecko
+By default, ``ragavi`` uses the canvas image backend for interactive plots, due to performance issues associated with SVG image backend as stated in the Bokeh `docs`_.
+The default plots generated are always in HTML format.
 
-With this setup, one can now supply to ``ragavi-gains`` a ``--plotname`` value, which will result in the generation of PNG/SVG files, depending on the file extension provided. If, for example, the plotname provided is ``foo.png``, ``ragavi-gains`` will assume the desired output should be PNG. The same applies for SVG. If both ``--plotname`` and ``--htmlname`` are provided, ``ragavi`` will generate both static (PNG) and interactive (HTML) outputs simulaneously.
+.. warning::
+    If the gain tables supplied contain more than 30,000 points, interactive plots become extremely large and barely interactive (and unresponsive).
 
-It is necessary to point out that by default, ``ragavi`` uses the canvas image backend for interactive plots, due to performance issues associated with SVG image backend as stated in the Bokeh `docs`_.
-The default plots generated are always in HTML format.
+    In an attempt to overcome this, ``ragavi-gains`` generates static plots, 
+    in addition to interactive plots, in this case. It is advisable to 
+    **avoid opening the large (upto hundreds of MBs) HTML as they may cause the browser to hang**. Instead, **inspect the static plot first** and **then make an interactive plot containing the antenna / field / corr etc. of your interest** by using the selection arguments provided.
 
 
 Help
@@ -131,7 +122,7 @@ The full help output for ``ragavi-gains`` is:
                           https://colorcet.holoviz.org/user_guide/index.html .
                           Defaults to coolwarm
     -d , --doplot         Plot complex values as amplitude & phase (ap) or real
-                          and imaginary (ri). Defaults to ap.
+                          and imaginary (ri) or both (all). Defaults to ap.
     --debug               Enable debug messages
     -g [  [  ...]], --gaintype [  [  ...]]
                           Type of table(s) to be plotted. Can be specified as a
@@ -151,7 +142,44 @@ The full help output for ``ragavi-gains`` is:
                           the type of plot. If foo.png, the output will be PNG,
                           else if foo.svg, the output will be of the SVG format.
 
+Examples
+========
+This subsection demonstrates the kind of plots that are generated
+
+Interactive plots
+-----------------
+
+Command:
+:code:`ragavi-gains --table test.B0 --doplot ap --htmlname test`
+
+.. image:: examples/gplot_html.png
+    :width: 800
+    :alt: Interactive plot with ``--doplot ap``
+
+Command:
+:code:`ragavi-gains --table test.B0 --doplot all --htmlname test`
+
+.. image:: examples/gplot_all_html.png
+    :width: 800
+    :alt: Interactive plot with ``--doplot all``
+
+
+Static plots
+------------
+
+Command:
+:code:`ragavi-gains --table test.B0 --doplot ap --plotname test.png`
+
+.. image:: examples/gplot.png
+    :width: 800
+    :alt: Static plot with ``--doplot ap`` and ``--plotname test.png``
+
+Command:
+:code:`ragavi-gains --table test.B0 --doplot all --plotname test.png`
 
+.. image:: examples/gplot_all.png
+    :width: 800
+    :alt: Static plot with ``--doplot all`` and ``--plotname test.png``
 
 Useful function
 ===============

diff --git a/docs/source/utilities.rst b/docs/source/utilities.rst
@@ -3,5 +3,5 @@ Utilities
 *********
 Some utilities useful internally and externally from ``ragavi``
 
-.. automodule:: ragavi.vis_utils
+.. automodule:: ragavi.utils
    :members:
diff --git a/docs/source/vis.rst b/docs/source/vis.rst
@@ -62,6 +62,9 @@ It is also possible to colour over some axis (most of the iteration axes are
 supported as shown in the table above) and this can be activated through the 
 :code:`-ca / --colour-axis` argument. Please note that the mandatory arguments are :code:`--xaxis`, :code:`--yaxis`, :code:`--ms`.
 
+.. note::
+    Output files genrated by ``ragavi-vis`` can be very large for iterated plots because of the resolution of each generated plot. For this reason, unless ``--canvas-width`` and ``--canvas-height`` are explicitly provided, ``ragavi-gains`` will automatically shrink the canvas sizes to 200 by 200 in order to minimise the resulting output.
+
 
 Averaging
 =========
@@ -190,6 +193,61 @@ The output of the help is as follows:
                           to ensure that: num-cores * mem-limit < total RAM
                           available
 
+Examples
+========
+Some example plots generated by ``ragavi-vis``
+
+Command:
+:code:`ragavi-vis --ms dir/test.ms --xaxis time --yaxis amp`
+
+.. image:: examples/single_amp_time.png
+    :width: 800
+    :alt: amplitude vs time
+
+Command:
+:code:`ragavi-vis --ms dir/test.ms --xaxis phase --yaxis amp --colour-axis antenna1`
+
+.. image:: examples/single_colour_amp_phase.png
+    :width: 800
+    :alt: amplitude vs phase coloured by antenna1
+
+Command:
+:code:`ragavi-vis --ms dir/test.ms --xaxis phase --yaxis amp --iter-axis scan`
+
+.. image:: examples/iter_amp_phase.png
+    :width: 800
+    :alt: amplitude vs phase iterated by scan
+
+Command:
+:code:`ragavi-vis --ms dir/test.ms --xaxis phase --yaxis amp --iter-axis scan --colour-axis corr`
+
+.. image:: examples/iter_colour_amp_phase.png
+    :width: 800
+    :alt: amplitude vs phase iterated by scan coloured by corr
+
+
+In some cases, the plot generated may have data points that are small and bordering invisible, such as the one below
+
+Command:
+:code:`ragavi-vis --ms dir/test.ms --xaxis scan --yaxis amp --cmap bmy`
+
+.. image:: examples/high_res_amp_scan.png
+    :width: 800
+    :alt: amplitude vs phase iterated by scan coloured by corr
+
+A work around for such a case, is to reduce the resolution of the resulting 
+image, by providing the ``--canvas-width`` and ``--canvas-height`` arguments.
+The image above, was generating using the default values 1080 and 720 
+respectively. If this is changed to 100 and 100, the resulting plot albeit 
+coarse, is clearer as shown below
+
+Command:
+:code:`ragavi-vis --ms dir/test.ms --xaxis scan --yaxis amp --cmap bmy --canvas-width 100 --canvas-height 100`
+
+.. image:: examples/low_res_amp_scan.png
+    :width: 800
+    :alt: amplitude vs scan
+
 
 .. _Codex: https://codex-africanus.readthedocs.io/en/latest/
 .. _help: https://ragavi.readthedocs.io/en/dev/vis.html#help
diff --git a/ragavi/__init__.py b/ragavi/__init__.py
@@ -1,4 +1,4 @@
 import ragavi.raglog
 
 # set ragavi version number (single source)
-__version__ = "0.4.0"
+__version__ = "0.4.1"