Merge b995faf into 2a89850

bin/hveto

@@ -53,6 +53,7 @@ from gwpy.segments import (Segment, SegmentList,
                            DataQualityFlag, DataQualityDict)
 
 from hveto import (__version__, log, config, core, plot, html, utils)
+from hveto.plot import (HEADER_CAPTION, ROUND_CAPTION, FancyPlot)
 from hveto.segments import (write_ascii as write_ascii_segments,
                             read_veto_definer_file)
 from hveto.triggers import (get_triggers, find_auxiliary_channels,
@@ -456,6 +457,7 @@ while True:
         plot.significance_drop(png, oldsignificances, newsignificances,
                                title=title, subtitle=subtitle)
         logger.debug("Figure written to %s" % png)
+        png = FancyPlot(png, caption=ROUND_CAPTION['SIG_DROP'])
         rounds[-1].plots.append(png)
     oldsignificances = newsignificances
 
@@ -596,6 +598,7 @@ cum. deadtime :   %s""" % (
         label1=beforel, label2=afterl, xlabel=slabel,
         title=ptitle, subtitle=subtitle)
     logger.debug("Figure written to %s" % png)
+    png = FancyPlot(png, caption=ROUND_CAPTION['HISTOGRAM'])
     round.plots.append(png)
 
     # snr versus time
@@ -605,6 +608,7 @@ cum. deadtime :   %s""" % (
         epoch=start, xlim=[start, end], ylabel=slabel,
         title=ptitle, subtitle=subtitle, legend_title="Primary:")
     logger.debug("Figure written to %s" % png)
+    png = FancyPlot(png, caption=ROUND_CAPTION['SNR_TIME'])
     round.plots.append(png)
 
     # snr versus frequency
@@ -614,6 +618,7 @@ cum. deadtime :   %s""" % (
         label2=vetoedl, xlabel=flabel, ylabel=slabel, xlim=pfreq,
         title=ptitle, subtitle=subtitle, legend_title="Primary:")
     logger.debug("Figure written to %s" % png)
+    png = FancyPlot(png, caption=ROUND_CAPTION['SNR'])
     round.plots.append(png)
 
     # frequency versus time coloured by SNR
@@ -625,6 +630,7 @@ cum. deadtime :   %s""" % (
         epoch=start, xlim=[start, end], ylim=pfreq,
         title=ptitle, subtitle=subtitle)
     logger.debug("Figure written to %s" % png)
+    png = FancyPlot(png, caption=ROUND_CAPTION['TIME'])
     round.plots.append(png)
 
     # aux used versus frequency
@@ -634,6 +640,7 @@ cum. deadtime :   %s""" % (
         label2=vetoedl, ylabel=slabel, epoch=start, xlim=[start, end],
         title=atitle, subtitle=subtitle)
     logger.debug("Figure written to %s" % png)
+    png = FancyPlot(png, caption=ROUND_CAPTION['USED_SNR_TIME'])
     round.plots.append(png)
 
     # snr versus time
@@ -643,6 +650,7 @@ cum. deadtime :   %s""" % (
         label1=beforeauxl, label2=(usedl, coincl), epoch=start,
         xlim=[start, end], ylabel=auxslabel, title=atitle, subtitle=subtitle)
     logger.debug("Figure written to %s" % png)
+    png = FancyPlot(png, caption=ROUND_CAPTION['AUX_SNR_TIME'])
     round.plots.append(png)
 
     # snr versus frequency
@@ -652,6 +660,7 @@ cum. deadtime :   %s""" % (
         label1=beforeauxl, label2=(usedl, coincl), xlabel=auxflabel,
         ylabel=auxslabel, title=atitle, subtitle=subtitle, legend_title="Aux:")
     logger.debug("Figure written to %s" % png)
+    png = FancyPlot(png, caption=ROUND_CAPTION['AUX_SNR_FREQUENCY'])
     round.plots.append(png)
 
     # frequency versus time coloured by SNR
@@ -662,6 +671,7 @@ cum. deadtime :   %s""" % (
         clabel=auxslabel, clim=[3, 100], cmap='YlGnBu', epoch=start,
         xlim=[start, end], title=atitle, subtitle=subtitle)
     logger.debug("Figure written to %s" % png)
+    png = FancyPlot(png, caption=ROUND_CAPTION['AUX_FREQUENCY_TIME'])
     round.plots.append(png)
 
     # move to the next round
@@ -708,12 +718,14 @@ plot.before_after_histogram(
     png, pevents[0][scol], pevents[-1][scol],
     label1=beforel, label2=afterl, xlabel=slabel,
     title=title, subtitle=subtitle)
+png = FancyPlot(png, caption=HEADER_CAPTION['HISTOGRAM'])
 plots.append(png)
 logger.debug("Figure written to %s" % png)
 
 # efficiency/deadtime curve
 png = pngname % 'ROC'
 plot.hveto_roc(png, rounds, title=title, subtitle=subtitle)
+png = FancyPlot(png, caption=HEADER_CAPTION['ROC'])
 plots.append(png)
 logger.debug("Figure written to %s" % png)
 
@@ -726,6 +738,7 @@ plot.veto_scatter(
     label1='', label2=labels, title=title,
     subtitle=subtitle, ylabel=flabel, x='time', y=fcol,
     epoch=start, xlim=[start, end], legend_title=legtitle)
+png = FancyPlot(png, caption=HEADER_CAPTION['TIME'])
 plots.append(png)
 logger.debug("Figure written to %s" % png)
 
@@ -735,6 +748,7 @@ plot.veto_scatter(
     png, pevents[0], pvetoed, label1='', label2=labels, title=title,
     subtitle=subtitle, ylabel=slabel, x='time', y=scol,
     epoch=start, xlim=[start, end], legend_title=legtitle)
+png = FancyPlot(png, caption=HEADER_CAPTION['SNR_TIME'])
 plots.append(png)
 logger.debug("Figure written to %s" % png)
 

hveto/html.py

@@ -33,7 +33,7 @@
 from _version import get_versions
 
 __author__ = 'Duncan Macleod <duncan.macleod@ligo.org>'
-__credits__ = 'Josh Smith, Joe Areeda'
+__credits__ = 'Josh Smith, Joe Areeda, Alex Urban'
 
 # -- set up default JS and CSS files
 
@@ -85,6 +85,7 @@
 	$(\".fancybox\").fancybox({
 		nextEffect: 'none',
 		prevEffect: 'none',
+		helpers: {title: {type: 'inside'}}
 	});
 });
 """
@@ -375,7 +376,8 @@ def fancybox_img(img, linkparams=dict(), **params):
     Parameters
     ----------
     img : `str`
-        the path of the image to embed
+        a `FancyPlot` object containing the path of the image to embed
+        and its caption to be displayed
     linkparams : `dict`
         the HTML attributes for the ``<a>`` tag
     **params
@@ -387,12 +389,13 @@ def fancybox_img(img, linkparams=dict(), **params):
     """
     page = markup.page()
     aparams = {
-        'title': os.path.basename(img),
+        'title': img.caption,
         'class_': 'fancybox',
         'target': '_blank',
         'data-fancybox-group': 'hveto-image',
     }
     aparams.update(linkparams)
+    img = str(img)
     page.a(href=img, **aparams)
     imgparams = {
         'alt': os.path.basename(img),

hveto/plot.py

@@ -21,6 +21,7 @@
 
 from __future__ import division
 
+import os.path
 import warnings
 from math import (log10, floor)
 from io import BytesIO
@@ -35,7 +36,7 @@
 from gwpy.plotter.table import get_column_string
 
 __author__ = 'Duncan Macleod <duncan.macleod@ligo.org>'
-__credits__ = 'Josh Smith, Joe Areeda'
+__credits__ = 'Josh Smith, Joe Areeda, Alex Urban'
 
 rcParams.update({
     'figure.subplot.bottom': 0.17,
@@ -74,6 +75,114 @@
     </script>"""
 
 
+# -- set up default header plot captions
+
+HEADER_CAPTION = {
+    'HISTOGRAM':
+        "Histogram of number of triggers in the primary channel before the "
+        "heveto analysis, but after the data quality flag cuts (red) compared "
+        "with the number after vetoes from all hveto rounds have been applied "
+        "(blue) versus the signal-to-noise ratio of those triggers.",
+    'ROC':
+        "The fraction of the primary channel triggers vetoed (fractional "
+        "efficiency) versus the fraction of livetime that is vetoed "
+        "(fractional deadtime) for each hveto round (blue dots). Guidelines "
+        "are given for efficiency/deadtime of 1 (the value expected for "
+        "random chance) and higher.",
+    'TIME':
+        "Frequency versus time graph of all triggers in the primary channel "
+        "before the hveto analysis (black dots) and those triggers that are "
+        "vetoed by a given round (symbols).",
+    'SNR_TIME':
+        "Signal-to-noise ratio versus time graph of all triggers in the "
+        "primary channel before the hveto analysis (black dots) and those "
+        "triggers that are vetoed by a given round (symbols)."
+}
+
+
+# -- set up default round winner plot captions
+
+ROUND_CAPTION = {
+    'HISTOGRAM':
+        "Histogram of number of triggers in the primary channel before this "
+        "round of hveto (red) compared with the number after vetoes from this "
+        "round have been applied (blue) versus the signal-to-noise ratio of "
+        "those triggers.",
+    'SNR_TIME':
+        "Signal-to-noise ratio versus time graph of all triggers in the "
+        "primary channel before this round of hveto (black dots) and those "
+        "triggers that are vetoed by this round (red plusses).",
+    'SNR':
+        "Signal-to-noise ratio versus frequency graph of all triggers in the "
+        "primary channel before this round of hveto (black dots) and those "
+        "triggers that are vetoed by this round (red plusses).",
+    'TIME':
+        "Frequency versus time graph of all triggers in the primary channel "
+        "before this hveto round (dots colored by signal-to-noise ratio) and "
+        "those triggers that are vetoed by this round (red plusses).",
+    'USED_SNR_TIME':
+        "Signal-to-noise ratio versus time graph of all triggers in the "
+        "auxiliary channel above the threshold selected for this round (black "
+        "dots, these are the triggers used to construct the veto) and the "
+        "primary channel triggers that are vetoed in this round (red "
+        "plusses). This can indicate whether, for example, louder triggers in "
+        "the auxiliary channel are used to veto quieter channels in the "
+        "primary channel, as might be expected for an external disturbance.",
+    'AUX_SNR_TIME':
+        "Signal-to-noise ratio versus time graph of all triggers in the "
+        "auxiliary channel before this round (black dots), those above the "
+        "threshold selected for this round (yellow plusses, these are the "
+        "triggers used to construct the veto), and those triggers that "
+        "actually veto one of the primary channel triggers (red plusses).",
+    'AUX_SNR_FREQUENCY':
+        "Signal-to-noise ratio versus frequency graph of all triggers in the "
+        "auxiliary channel before this round (black dots), those above the "
+        "threshold selected for this round (yellow plusses, these are the "
+        "triggers used to construct the veto), and those triggers that "
+        "actually veto one of the primary channel triggers (red plusses).",
+    'AUX_FREQUENCY_TIME':
+        "Frequency versus time graph of all triggers in the auxiliary channel "
+        "before this round (dots colored by signal-to-noise ratio), those "
+        "above the threshold selected for this round (yellow plusses, these "
+        "are the triggers used to construct the veto), and those triggers "
+        "that actually veto one of the primary channel triggers (red "
+        "plusses).",
+    'SIG_DROP':
+        "This plot includes interactive features (channel names appear when "
+        "pointed to with your mouse cursor) that can be accessed by opening "
+        "the plot in a new tab. The statistical significance value (based on "
+        "Poisson statistics) for the best SNR and time window combination for "
+        "each auxiliary channel before and after this round are shown as a "
+        "baton. The round’s winning channel, which had the highest "
+        "significance, is shown in yellow. The top of the yellow baton is the "
+        "significance of this channel before this round and the bottom of the "
+        "baton is its significance in the next round, after its triggers "
+        "above this round’s SNR threshold and time window have been removed "
+        "(note that this channel may have nonzero significance in the next "
+        "round because it may still have triggers left at a lower SNR "
+        "threshold). Blue batons are for channels whose significance dropped "
+        "after this round (indicating that that channel had some trigger "
+        "times in common with the winner) and red batons are for channels "
+        "whose significance increased in the next round (due to less "
+        "livetime)."
+}
+
+
+# -- Plot construction --------------------------------------------------------
+
+class FancyPlot(object):
+    def __init__(self, img, caption=None):
+        if isinstance(img, FancyPlot):
+            caption = caption if caption else img.caption
+        self.img = str(img)
+        self.caption = caption if caption else os.path.basename(self.img)
+
+    def __str__(self):
+        return self.img
+
+
+# -- Functions ----------------------------------------------------------------
+
 def before_after_histogram(
         outfile, x, y, label1='Before', label2='After',
         bins=100, histtype='stepfilled', range=None, figsize=[9, 6], **kwargs):

hveto/tests/test_html.py

@@ -29,6 +29,10 @@
 from hveto import html
 from hveto._version import get_versions
 
+from matplotlib import use
+use('agg')  # nopep8
+from hveto.plot import FancyPlot
+
 from common import unittest
 
 VERSION = get_versions()['version']
@@ -149,15 +153,17 @@ def test_cis_link(self):
                  'X1:TEST-CHANNEL">X1:TEST-CHANNEL</a>')
 
     def test_fancybox_img(self):
-        out = html.fancybox_img('test.png')
+        img = FancyPlot('test.png')
+        out = html.fancybox_img(img)
         self.assertEqual(
             out, '<a class="fancybox" href="test.png" target="_blank" '
                  'data-fancybox-group="hveto-image" title="test.png">\n'
                  '<img class="img-responsive" alt="test.png" src="test.png" />'
                  '\n</a>')
 
     def test_scaffold_plots(self):
-        out = html.scaffold_plots(['plot1.png', 'plot2.png'])
+        out = html.scaffold_plots([FancyPlot('plot1.png'),
+                                   FancyPlot('plot2.png')])
         self.assertEqual(
             out, '<div class="row">\n'
                  '<div class="col-sm-6">\n'

hveto/tests/test_plot.py

@@ -53,3 +53,8 @@ def test_drop_plot(self):
             finally:
                 if os.path.isfile(svg):
                     os.remove(svg)
+
+    def test_fancy_plot(self):
+        test = plot.FancyPlot('test.png')
+        assert test.img is 'test.png'
+        assert test.caption is 'test.png'