diff --git a/docs/cli.rst b/docs/cli.rst index 63c7642a..cfecdc65 100644 --- a/docs/cli.rst +++ b/docs/cli.rst @@ -1,3 +1,5 @@ +.. _cli-page: + ###################### Command-line interface ###################### @@ -19,28 +21,28 @@ Day mode To run in daily summary mode, the following command-line options are available: -.. command-output:: python ../bin/gw_summary day --help +.. command-output:: python gw_summary day --help Week mode --------- The arguments in weekly mode are as follows: -.. command-output:: python ../bin/gw_summary week --help +.. command-output:: python gw_summary week --help Month mode ---------- In monthly mode: -.. command-output:: python ../bin/gw_summary month --help +.. command-output:: python gw_summary month --help GPS mode -------- To run within a specific (but arbitrary) range of GPS seconds: -.. command-output:: python ../bin/gw_summary gps --help +.. command-output:: python gw_summary gps --help Batch mode ========== @@ -54,4 +56,4 @@ and run jobs in parallel. To see all the available arguments and options for this tool, you can run with `--help` as usual: -.. command-output:: python ../bin/gw_summary_pipe --help +.. command-output:: python gw_summary_pipe --help diff --git a/docs/examples/first.png b/docs/examples/first.png new file mode 100644 index 00000000..30ba035c Binary files /dev/null and b/docs/examples/first.png differ diff --git a/docs/examples/imc.png b/docs/examples/imc.png index 6d5df456..dc667f5d 100644 Binary files a/docs/examples/imc.png and b/docs/examples/imc.png differ diff --git a/docs/index.rst b/docs/index.rst index 73f55d9d..aabb7cea 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -71,7 +71,6 @@ GWSumm is distributed under the `GNU General Public License`_. cli automation tabs/index - tabs/flavour tabs/websites tabs/modes tabs/api diff --git a/docs/overview.rst b/docs/overview.rst index 00f84a2b..6559c5cb 100644 --- a/docs/overview.rst +++ b/docs/overview.rst @@ -9,9 +9,9 @@ The summary pages were developed in collaboration between the LIGO Laboratory and the GEO600 project with the goal of generating an automated daily summary of laser-interferometer operations and performance. -As of summary 2014, the summary pages are extensively used to characterise -data from the new `Advanced LIGO `_ -instruments as they are being commissioned for future observing runs. +The LIGO Summary Pages are used to characterize and monitor the status +of the detectors and their subsystems. In addition, data products and +webpages from other analysis tools are included in the Summary Pages. The output acts as a kind of daily magazine, allowing instrument scientists and data analysis teams a archived, searchable summary of the key figures of @@ -40,22 +40,32 @@ should be manipulated, and how it should all be displayed. These configuration files are made up ``[tab-xxx]`` section with the following format: -.. literalinclude:: ../share/examples/imc.ini - :language: ini +.. code-block:: ini -This block defines the ``IMC`` tab, with a ``name`` (and a ``shortname``), -which should contain a single ``timeseries`` plot of the -``L1:IMC-PWR_IN_OUT_DQ`` channel. -The plot has been customised with a y-axis limit and a title. + [tab-IMC] + name = Input mode cleaner + shortname = IMC + 1 = L1:IMC-PWR_IN_OUT_DQ timeseries + 1-ylim = 0,80 + 1-title = 'Power into IMC' + [html] + issues = -This tab is then generate by passing it to the `gw_summary` executable, along +This block defines the ``IMC`` tab, with a ``name`` (and a ``shortname``): +a single ``timeseries`` plot of the ``L1:IMC-PWR_IN_OUT_DQ`` channel. +The plot has been customised with a y-axis limit and a title. This +also defines the required ``[html]`` section, where the required key +``issues`` is defined. This example can be saved to a file called ``imc.ini``. + +This tab is then generated by passing it to the `gw_summary` executable, along with some GPS times over which to run: .. code-block:: bash - $ gw_summary gps 'June 1 2014 00:00' 'June 1 2014 01:00' --config-file imc.ini + $ gw_summary gps 'Feb 29 2020 00:00' 'Feb 29 2020 01:00' --config-file imc.ini -This minimal setup will produce the following HTML page: +This minimal setup will produce the following HTML page +`1266969618-1266973218/imc/index.html`: .. image:: examples/imc.png :width: 80% diff --git a/docs/tabs/flavour.rst b/docs/tabs/flavour.rst deleted file mode 100644 index 129aebc0..00000000 --- a/docs/tabs/flavour.rst +++ /dev/null @@ -1,24 +0,0 @@ -.. _flavours: - -.. currentmodule:: gwsumm.tabs - -############## -`Tab` flavours -############## - -In its simplest form, the `Tab` is essentially a blank canvas on which to write whatever you want. -However, the original mandate for GWSumm was to provide a framework in which to generate automatic summaries of LIGO data, over a given timescale. - -To handle data processing, rather than static HTML generation, each `Tab` has a flavour, based on its relation to any interval in time - -.. currentmodule:: gwsumm.tabs.core - -.. autosummary:: - :nosignatures: - :toctree: ../api - - StaticTab - IntervalTab - EventTab - -The 'flavour' of a `Tab` is set when it is created, based on the value of the :attr:`~Tab.mode` attribute, for full details see :ref:`modes`. diff --git a/docs/tabs/index.rst b/docs/tabs/index.rst index 0ddefe08..a384a25b 100644 --- a/docs/tabs/index.rst +++ b/docs/tabs/index.rst @@ -6,6 +6,10 @@ Introduction to Tabs #################### +GWsumm can be used either from the command line as described in +:ref:`CLI interface ` or as a package to progromatically +generate pages called "tabs". + A `Tab` is a single, configurable page of output, containing some data. Each `Tab` is written in its own HTML page, and can be written to contain any set of data, with any format. @@ -22,13 +26,20 @@ A simple `Tab` can be created in only two steps .. code-block:: python + from gwsumm.tabs import Tab mytab = Tab('My first tab') mytab.write_html("This tab doesn't do very much") -This will create two directories under the current one, +This will create a directory under the current one, - ``my_first_tab/`` containing the HTML for the new tab -- ``static/`` containing all of the stylesheets and javascript files that make the page functional + +The output webpage looks like: + +.. image:: examples/first.png + :width: 80% + :align: center + :alt: First GWSumm example screenshot The content given to `Tab.write_html` is passed along untouched, so can contain any HTML you like. diff --git a/docs/tabs/modes.rst b/docs/tabs/modes.rst index a564b8c2..15d26a0f 100644 --- a/docs/tabs/modes.rst +++ b/docs/tabs/modes.rst @@ -9,7 +9,7 @@ In its simplest form, the `Tab` is essentially a blank canvas on which to write whatever you want. However, the original mandate for GWSumm was to provide a framework in which to generate automatic summaries of LIGO data, over a given timescale. -To handle data processing, rather than static HTML generation, each `Tab` has a flavour, based on its relation to any interval in time +To handle data processing, rather than static HTML generation, each `Tab` has a type, based on its relation to any interval in time .. currentmodule:: gwsumm.tabs.core @@ -21,14 +21,13 @@ To handle data processing, rather than static HTML generation, each `Tab` has a IntervalTab EventTab -The 'flavour' of a `Tab` is set automatically when it is created based on the value of the :attr:`~Tab.mode` attribute, so you don't need to remember the above objects. +The type of a `Tab` is set automatically when it is created based on the value of the :attr:`~Tab.mode` attribute, so you don't need to remember the above objects. ===== Modes ===== -All tabs have a :attr:`~Tab.mode`, loosely based around the time interval of interest. -GWSumm support seven modes: +GWSumm currently support seven different `Tab` modes: ========== ==== ============================================================= Mode Enum Description @@ -46,9 +45,16 @@ Mode Enum Description Assigning modes =============== -Each `Tab` must be assigned a mode, which can either be done locally, by passing the `~Tab.mode` keyword argument when creating a `Tab`, or globally, by using the :meth:`gwsumm.mode.set_mode`; this sets the default mode for all tabs created in this session. +Each `Tab` will be assigned a mode (unless specified as follows, the default mode +is ``STATIC``). The assignment can be done on a per-tab basis by +passing the `~Tab.mode` keyword argument when creating a `Tab`, or +globally, by using the :meth:`gwsumm.mode.set_mode`. The latter sets +the default mode for all subsequent tabs created in this session. -If a :attr:`~Tab.mode` is given that assocaites with a GPS time or times, these must be given via the `~IntervalTab.span` or `~EventTab.gpstime` keyword arguments, otherwise a `TypeError` will be raised. +If a :attr:`~Tab.mode` is given that associates with a GPS time or +times, these must be given via the `~IntervalTab.span` or +`~EventTab.gpstime` keyword arguments, otherwise a `TypeError` will be +raised. The `span` tuple is the ``(GPS start time, GPS end time)`` .. code-block:: python diff --git a/docs/tabs/websites.rst b/docs/tabs/websites.rst index 4b27038d..cfb27228 100644 --- a/docs/tabs/websites.rst +++ b/docs/tabs/websites.rst @@ -14,6 +14,7 @@ The key difference between standalone pages and a website is the ability to navi .. code-block:: python + from gwsumm.tabs import Tab tab1 = Tab('Tab 1') tab2 = Tab('Tab 2') tabs = [tab1, tab2] @@ -43,4 +44,16 @@ Here we have set a `parent` tab for 2A, and used the same for 2B, which creates Tab groups ---------- -For even larger websites, sets of tabs under a single parent can be further separated into `groups `. +For even larger websites, sets of tabs under a single parent can be +further separated into `groups `. For example, to put 2A +into group `1` and 2B into group `2`, we can write: + +.. code-block:: python + + tab1 = Tab('Tab 1') + tab2a = Tab('A', parent='Tab 2', group='1') + tab2b = Tab('B', parent=tab2a.parent, group='2') + tabs = [tab1, tab2a, tab2b] + tab1.write_html('This is tab 1', tabs=tabs) + tab2a.write_html('This is tab 2A', tabs=tabs) + tab2b.write_html('This is tab 2B', tabs=tabs)