diff --git a/.gitignore b/.gitignore index b2db3c3..a0d60b5 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,9 @@ # documentation products /docs/_build/ -/docs/api/ +/docs/_generated/ +/docs/api/modules.rst +/docs/api/hveto.* # test products /.cache/ diff --git a/.readthedocs.yml b/.readthedocs.yml new file mode 100644 index 0000000..ccd3b91 --- /dev/null +++ b/.readthedocs.yml @@ -0,0 +1,30 @@ +# .readthedocs.yml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Build documentation in the docs/ directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Build docs in additional formats +formats: all + +# include submodules +submodules: + include: all + +# Set the version of Python and requirements required to build your docs +python: + version: 3.7 + install: + - requirements: docs/requirements.txt + - requirements: requirements.txt + - method: setuptools + path: . + - method: pip + path: . + extra_requirements: + - docs diff --git a/README.rst b/README.rst index 69cb683..4e3644c 100644 --- a/README.rst +++ b/README.rst @@ -1,24 +1,27 @@ -HVeto is a python implementation of the HierarchicalVeto algorithm. It is -a package designed for for gravitational-wave detector characterisation and +================= +Hierarchical Veto +================= + +Hveto is a python implementation of the HierarchicalVeto algorithm. It is +a package designed for gravitational-wave detector characterisation and data quality. -|PyPI version| |DOI| |License| |Supported Python versions| +The Hveto algorithm is fully described in `Smith et al. 2011`_ +(Classical and Quantum Gravity). + +|PyPI version| |Conda version| -|Build Status| |Coverage Status| +|DOI| |License| |Supported Python versions| ------- -Method ------- +|Build Status| |Coverage Status| |Documentation Status| -The HVeto algorithm is fully described in `Smith et al. 2011`_ -(Classical and Quantum Gravity). `Documentation`_ for running HVeto -is also available, but requires LIGO.ORG credentials. +https://hveto.readthedocs.io ------------ Installation ------------ -HVeto is best installed with `conda`_: +Hveto is best installed with `conda`_: .. code:: bash @@ -47,10 +50,11 @@ proposing additions/changes. .. _conda: https://conda.io .. _pip: https://pip.pypa.io/en/stable/ .. _Smith et al. 2011: //dx.doi.org/10.1088/0264-9381/28/23/235005 -.. _Documentation: https://ldas-jobs.ligo.caltech.edu/~duncan.macleod/hveto/latest/ .. |PyPI version| image:: https://badge.fury.io/py/hveto.svg :target: http://badge.fury.io/py/hveto +.. |Conda version| image:: https://img.shields.io/conda/vn/conda-forge/hveto.svg + :target: https://anaconda.org/conda-forge/hveto/ .. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/2584615.svg :target: https://doi.org/10.5281/zenodo.2584615 .. |License| image:: https://img.shields.io/pypi/l/hveto.svg @@ -61,3 +65,5 @@ proposing additions/changes. :target: https://travis-ci.org/gwdetchar/hveto .. |Coverage Status| image:: https://codecov.io/gh/gwdetchar/hveto/branch/master/graph/badge.svg :target: https://codecov.io/gh/gwdetchar/hveto +.. |Documentation Status| image:: https://readthedocs.org/projects/hveto/badge/?version=stable + :target: https://hveto.readthedocs.io/en/stable/?badge=stable diff --git a/bin/hveto-cache-events b/bin/hveto-cache-events index 7b9bcbd..43d87d5 100644 --- a/bin/hveto-cache-events +++ b/bin/hveto-cache-events @@ -17,7 +17,7 @@ # You should have received a copy of the GNU General Public License # along with hveto. If not, see . -"""Create a (temporary) cache of event triggers for analysis by `hveto` later +"""Create a (temporary) cache of event triggers for analysis by `hveto` This method will apply the minimal SNR thresholds and any frequency cuts as given in the configuration files diff --git a/bin/hveto-trace b/bin/hveto-trace index f18d1ee..2cad097 100644 --- a/bin/hveto-trace +++ b/bin/hveto-trace @@ -16,8 +16,9 @@ # # You should have received a copy of the GNU General Public License # along with hveto. If not, see . -# """Check if a trigger was vetoed by a specified hveto run. -# """ + +"""Check if a trigger was vetoed by a specified hveto run +""" import os import sys diff --git a/docs/_static/css/custom.css b/docs/_static/css/custom.css new file mode 100644 index 0000000..8080b4f --- /dev/null +++ b/docs/_static/css/custom.css @@ -0,0 +1,216 @@ +/.text-primary { + color: #4ba6ff; +} + +.bg-primary { + background-color: #4ba6ff; +} + +.btn-primary { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +a.text-primary:hover, a.text-primary:focus { + color: #0080fe; +} + +a.bg-primary:hover, a.bg-primary:focus { + background-color: #0080fe; +} + +.btn-primary:focus, .btn-primary.focus { + background-color: #0080fe; + border-color: #0080fe; +} + +.btn-primary:hover { + background-color: #0080fe; + border-color: #0080fe; +} + +.btn-primary:active, .btn-primary.active, .open > .dropdown-toggle.btn-primary { + background-color: #0080fe; + border-color: #0080fe +} + +.navbar-default .navbar-nav > .active > a, .navbar-default .navbar-nav > .active > a:hover, +.navbar-default .navbar-nav > .active > a:focus { + background-color: #0080fe +} + +.navbar-default .navbar-nav > .open > a, .navbar-default .navbar-nav > .open > a:hover, +.navbar-default .navbar-nav > .open > a:focus { + background-color: #0080fe; +} + +.label-primary[href]:hover, .label-primary[href]:focus { + background-color: #0080fe +} + +a.text-primary:hover, a.text-primary:focus { + color: #0080fe +} + +a.bg-primary:hover, a.bg-primary:focus { + background-color: #0080fe +} + +.btn-primary:focus, .btn-primary.focus { + background-color: #0080fe; + border-color: #0080fe +} + +.btn-primary:hover { + background-color: #0080fe; + border-color: #0080fe +} + +.btn-primary:active, .btn-primary.active, .open > .dropdown-toggle.btn-primary { + background-color: #0080fe; + border-color: #0080fe +} + +.navbar-default .navbar-nav > .open > a, .navbar-default .navbar-nav > .open > a:hover, +.navbar-default .navbar-nav > .open > a:focus { + background-color: #0080fe; +} + + +.label-primary[href]:hover, .label-primary[href]:focus { + background-color: #0080fe +} + +.btn-primary.disabled:hover, .btn-primary[disabled]:hover, fieldset[disabled] .btn-primary:hover, +.btn-primary.disabled:focus, .btn-primary[disabled]:focus, fieldset[disabled] .btn-primary:focus, +.btn-primary.disabled.focus, .btn-primary[disabled].focus, fieldset[disabled] .btn-primary.focus { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +.btn-primary .badge { + color: #4ba6ff; +} + +.btn-link { + color: #4ba6ff; +} + +.dropdown-menu > li > a:hover, .dropdown-menu > li > a:focus { + background-color: #4ba6ff; +} + +.dropdown-menu > .active > a, .dropdown-menu > .active > a:hover, .dropdown-menu > .active > a:focus { + background-color: #4ba6ff; +} + +.nav .open > a, .nav .open > a:hover, .nav .open > a:focus { + border-color: #4ba6ff; +} + +.nav-pills > li.active > a, .nav-pills > li.active > a:hover, .nav-pills > li.active > a:focus { + background-color: #4ba6ff; +} + +.navbar-default { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +.navbar-default .navbar-nav > li > a:hover, .navbar-default .navbar-nav > li > a:focus { + background-color: #188dff; +} + +.navbar-default .navbar-toggle { + border-color: #188dff +} + +.navbar-default .navbar-toggle:hover, .navbar-default .navbar-toggle:focus { + background-color: #188dff +} + +@media (max-width:767px) { + .navbar-default .navbar-nav .open .dropdown-menu > li > a:hover, .navbar-default .navbar-nav .open .dropdown-menu > li > a:focus { + background-color: #188dff + } + + .navbar-default .navbar-nav .open .dropdown-menu > .active > a, .navbar-default .navbar-nav .open .dropdown-menu > .active > a:hover, + .navbar-default .navbar-nav .open .dropdown-menu > .active > a:focus { + background-color: #0080fe + } +} + +.pagination > li > a:hover, .pagination > li > span:hover, .pagination > li > a:focus, +.pagination > li > span:focus { + color: #188dff; +} + +a:hover, a:focus { + color: #188dff; +} + +.btn-link:hover, .btn-link:focus { + color: #188dff; +} + +.navbar-default .navbar-nav > li > a:hover, .navbar-default .navbar-nav > li > a:focus { + background-color: #188dff; +} + +.navbar-default .navbar-toggle { + border-color: #188dff; +} + +.navbar-default .navbar-collapse, .navbar-default .navbar-form { + border-color: #d34615 +} + +.pagination > li > a, .pagination > li > span { + color: #4ba6ff; +} + +.label-primary { + background-color: #4ba6ff; +} + +.list-group-item.active > .badge, .nav-pills > .active > a > .badge { + color: #4ba6ff; +} + +a.thumbnail:hover, a.thumbnail:focus, a.thumbnail.active { + border-color: #4ba6ff; +} + +.progress-bar { + background-color: #4ba6ff; +} + +.list-group-item.active, .list-group-item.active:hover, .list-group-item.active:focus { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +.panel-primary { + border-color: #4ba6ff; +} + +.panel-primary > .panel-heading { + background-color: #4ba6ff; + border-color: #4ba6ff; +} + +.panel-primary > .panel-heading + .panel-collapse > .panel-body { + border-top-color: #4ba6ff; +} + +.panel-primary > .panel-heading .badge { + color: #4ba6ff; +} + +.panel-primary > .panel-footer + .panel-collapse > .panel-body { + border-bottom-color: #4ba6ff; +} + +.navbar-default .badge { + color: #4ba6ff; +} diff --git a/docs/_static/hveto-docs.css b/docs/_static/hveto-docs.css deleted file mode 100644 index 795a077..0000000 --- a/docs/_static/hveto-docs.css +++ /dev/null @@ -1,13 +0,0 @@ -/* -- hveto documentation style --------------------------------------------- */ -/* just a few tweaks to the sphinx_rtd_theme styling */ - -/* override table width restrictions */ -.wy-table-responsive table td, .wy-table-responsive table th { - white-space: normal; -} - -.wy-table-responsive { - margin-bottom: 24px; - max-width: 100%; - overflow: visible; -} diff --git a/docs/api/index.rst b/docs/api/index.rst new file mode 100644 index 0000000..a69e68a --- /dev/null +++ b/docs/api/index.rst @@ -0,0 +1,8 @@ +API +--- + +.. toctree:: + :maxdepth: 2 + :glob: + + * diff --git a/docs/command-line/index.rst b/docs/command-line/index.rst index d62dc1f..cae584b 100644 --- a/docs/command-line/index.rst +++ b/docs/command-line/index.rst @@ -1,24 +1,25 @@ .. _command-line: -##################################### -Running ``hveto`` on the command line -##################################### +################### +On the command-line +################### -As described on the home page, the main interface to the hveto algorithm is the command-line executable ``hveto``. +The main interface to the Hveto algorithm is the command-line executable `hveto`. Basic instructions ================== -Basic instructions on running ``hveto`` can be gained by looking at the ``--help`` menu: +For a full explanation of the available command-line arguments and options, you can run .. command-output:: hveto --help Detailed instructions ===================== -A few of the command-line options require special formatting, use the reference below for more detailed info. +A few of the command-line options require special formatting, which is detailed +in this section. -``gpsstart`` and ``gpsend`` +`gpsstart` and `gpsend` --------------------------- Each of the required GPS start and stop times can be given as GPS integers, or as date strings, e.g. @@ -35,43 +36,73 @@ will produce the same analysis as .. note:: - The quote marks used in the date string example are important so that the shell passes them to ``python`` as a single argument + It is important to use quote marks when passing date strings on the command-line. + This will ensure that the shell passes these to `python` as individual arguments. -``-j/--nproc`` +`-j/--nproc` -------------- -The majority of the processing time for ``hveto`` is taken up by two things +Wall-clock processing time for `hveto` is dominated by two things: -- reading event files for the auxiliary channels -- determining the most-significant channel for a given round +- Reading event files for the auxiliary channels +- Determining the most-significant channel for a given round -Each of these can be sped up by using multiple CPUs available on the host machine by supplying ``--nproc X`` where X is any integer. +Each of these can be sped up by using multiple CPUs on the host machine by +supplying `--nproc X`, where `X` is any integer. .. warning:: - No restrictions are placed on the number of parallel processes that can be given on the command line, users should be aware that using too-high a number could overload the machine, or otherwise cause problems for themselves and other users. + Beware that using too many CPUs could overload the machine at runtime, + or otherwise cause problems for yourself and other users. - You can check how many processors are available on the machine with the following unix command + You can check how many processors are available with the following unix + command: - .. code-block:: bash + .. code:: bash cat /proc/cpuinfo | grep processor | wc -l -``-p/--primary-cache`` +`-p/--primary-cache` ---------------------- -This should receive a LAL-format cache file (see :mod:`glue.lal` for details) +This flag should receive a LAL-format cache file (see :mod:`glue.lal` for details). +If needed, you can use `hveto-cache-events` for this purpose (see below). -``-a/--auxiliary-cache`` +`-a/--auxiliary-cache` ------------------------ -This should receive a LAL-format cache file (similarly to ``--primary-cache``), but with a specific format: +This flag requires a LAL-format cache file (similar to `--primary-cache`), +but with a specific format: -- each contained trigger file should contain events for only a single channel -- the contained files should map to their channel as follows; if a channel is named ``X1:SYS-SUBSYS_NAME``, each filename should start ``X1-SYS_SUBSYS_NAME`` according to the `T050017 `_ convention. Additional underscore-delimited components can be given, but will not be used to map to the channel. +- Each trigger file should contain events for only a single channel +- The cached trigger files should map to their channel as follows: + if a channel is named `X1:SYS-SUBSYS_NAME`, each filename should start + `X1-SYS_SUBSYS_NAME` according to the `T050017 `_ + convention. Additional underscore-delimited components can be given, + but will not be used to map to the channel. + +If needed, `hveto-cache-events` can be used to create this cache (see below). .. note:: - If the ``channels`` option is not given in the ``[auxiliary]`` section of the configuration, it will be populated from the unique list of channels parsed as above from the ``--auxiliary-cache`` + If `channels` is not given in the `[auxiliary]` section of the + configuration file, it will be populated from the unique list of channels + parsed from the `--auxiliary-cache`. + +Caching trigger events +====================== + +The `hveto-cache-events` utility can be used to save both gravitational-wave +and auxiliary channel triggers: + +.. command-output:: hveto-cache-events --help + +Tracing event triggers +====================== + +The `hveto-trace` utility can be used to determine whether event triggers +are vetoed by a given `hveto` run: + +.. command-output:: hveto-trace --help diff --git a/docs/conf.py b/docs/conf.py index 6397ec0..ddb61ec 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -1,8 +1,5 @@ # -*- coding: utf-8 -*- # -# Hveto documentation build configuration file, created by -# sphinx-quickstart on Thu Apr 21 14:05:08 2016. -# # This file is execfile()d with the current directory set to its # containing dir. # @@ -14,14 +11,11 @@ import sys import os +import glob +import sphinx_bootstrap_theme from hveto import __version__ as hveto_version -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -sys.path.insert(0, os.path.abspath('.')) - # -- General configuration ------------------------------------------------ # If your documentation needs a minimal Sphinx version, state it here. @@ -32,10 +26,11 @@ # ones. extensions = [ 'sphinx.ext.autodoc', + 'sphinx.ext.autosummary', 'sphinx.ext.doctest', 'sphinx.ext.intersphinx', + 'sphinx.ext.mathjax', 'sphinx.ext.viewcode', - 'sphinx.ext.autosummary', 'numpydoc', 'sphinxcontrib.programoutput', ] @@ -43,9 +38,7 @@ # Add any paths that contain templates here, relative to this directory. templates_path = ['_templates'] -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] +# The suffix of source filenames. source_suffix = '.rst' # The encoding of source files. @@ -56,8 +49,8 @@ # General information about the project. project = u'Hveto' -copyright = u'2016, Joshua Smith' -author = u'Joshua Smith' +copyright = u'2016, Josh Smith' +author = 'Josh Smith, Duncan Macleod, Alex Urban' # The version info for the project you're documenting, acts as replacement for # |version| and |release|, also used in various other places throughout the @@ -70,10 +63,7 @@ # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = None +#language = None # There are two options for replacing |today|: either, you set today to some # non-false value, then it is used: @@ -83,15 +73,14 @@ # List of patterns, relative to source directory, that match files and # directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store'] +exclude_patterns = ['_build'] # The reST default role (used for this markup: `text`) to use for all # documents. -#default_role = None +default_role = 'obj' # If true, '()' will be appended to :func: etc. cross-reference text. -#add_function_parentheses = True +add_function_parentheses = True # If true, the current module name will be prepended to all description # unit titles (such as .. function::). @@ -102,7 +91,7 @@ #show_authors = False # The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' +pygments_style = 'default' # A list of ignored prefixes for module index sorting. #modindex_common_prefix = [] @@ -110,27 +99,30 @@ # If true, keep warnings as "system message" paragraphs in the built documents. #keep_warnings = False -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = False - # -- Options for HTML output ---------------------------------------------- # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -html_theme = 'sphinx_rtd_theme' +html_theme = 'bootstrap' # Theme options are theme-specific and customize the look and feel of a theme # further. For a list of options available for each theme, see the # documentation. -#html_theme_options = {} +html_theme_options = { + 'source_link_position': None, + 'navbar_site_name': "Contents", + 'navbar_sidebarrel': True, + 'navbar_pagenav': False, + 'bootswatch_theme': 'united', +} # Add any paths that contain custom themes here, relative to this directory. -#html_theme_path = [] +html_theme_path = sphinx_bootstrap_theme.get_html_theme_path() -# The name for this set of Sphinx documents. -# " v documentation" by default. -#html_title = u'Hveto v0.1' +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None # A shorter title for the navigation bar. Default is the same as html_title. #html_short_title = None @@ -139,8 +131,8 @@ # of the sidebar. #html_logo = None -# The name of an image file (relative to this directory) to use as a favicon of -# the docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 # pixels large. #html_favicon = None @@ -154,17 +146,16 @@ # directly to the root of the documentation. #html_extra_path = [] -# If not None, a 'Last updated on:' timestamp is inserted at every page -# bottom, using the given strftime format. -# The empty string is equivalent to '%b %d, %Y'. -#html_last_updated_fmt = None +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' # If true, SmartyPants will be used to convert quotes and dashes to # typographically correct entities. #html_use_smartypants = True # Custom sidebar templates, maps document names to template names. -#html_sidebars = {} +html_sidebars = {'**': ['localtoc.html', 'sourcelink.html', 'searchbox.html']} # Additional templates that should be rendered to pages, maps page names to # template names. @@ -196,24 +187,10 @@ # This is the file name suffix for HTML files (e.g. ".xhtml"). #html_file_suffix = None -# Language to be used for generating the HTML full-text search index. -# Sphinx supports the following languages: -# 'da', 'de', 'en', 'es', 'fi', 'fr', 'hu', 'it', 'ja' -# 'nl', 'no', 'pt', 'ro', 'ru', 'sv', 'tr', 'zh' -#html_search_language = 'en' - -# A dictionary with options for the search language support, empty by default. -# 'ja' uses this config value. -# 'zh' user can custom change `jieba` dictionary path. -#html_search_options = {'type': 'default'} - -# The name of a javascript file (relative to the configuration directory) that -# implements a search results scorer. If empty, the default will be used. -#html_search_scorer = 'scorer.js' - # Output file base name for HTML help builder. htmlhelp_basename = 'Hvetodoc' + # -- Options for LaTeX output --------------------------------------------- latex_elements = { @@ -225,17 +202,14 @@ # Additional stuff for the LaTeX preamble. #'preamble': '', - -# Latex figure (float) alignment -#'figure_align': 'htbp', } # Grouping the document tree into LaTeX files. List of tuples # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'Hveto.tex', u'Hveto Documentation', - u'Joshua Smith', 'manual'), + ('index', 'Hveto.tex', u'Hveto Documentation', + u'Josh Smith, Duncan Macleod, Alex Urban', 'manual'), ] # The name of an image file (relative to this directory) to place at the top of @@ -264,8 +238,8 @@ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'hveto', u'Hveto Documentation', - [author], 1) + ('index', 'hveto', u'Hveto Documentation', + [u'Josh Smith, Duncan Macleod, Alex Urban'], 1) ] # If true, show URL addresses after external links. @@ -278,9 +252,9 @@ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'Hveto', u'Hveto Documentation', - author, 'Hveto', 'One line description of project.', - 'Miscellaneous'), + ('index', 'Hveto', u'Hveto Documentation', + u'Josh Smith, Duncan Macleod, Alex Urban', 'Hveto', 'One line description of project.', + 'Miscellaneous'), ] # Documents to append as an appendix to all manuals. @@ -295,7 +269,6 @@ # If true, do not generate a @detailmenu in the "Top" node's menu. #texinfo_no_detailmenu = False -# -- Extensions ----------------------------------------------------------- # Example configuration for intersphinx: refer to the Python standard library. intersphinx_mapping = { @@ -303,5 +276,54 @@ 'numpy': ('http://docs.scipy.org/doc/numpy/', None), 'scipy': ('http://docs.scipy.org/doc/scipy/reference/', None), 'matplotlib': ('http://matplotlib.sourceforge.net/', None), - 'gwpy': ('http://gwpy.github.io/docs/latest/', None), + 'astropy': ('http://docs.astropy.org/en/stable/', None), + 'gwpy': ('http://gwpy.github.io/docs/stable/', None), + 'gwdetchar': ('http://gwdetchar.readthedocs.io/en/stable', None), + 'gwsumm': ('http://gwsumm.readthedocs.io/en/stable', None), } + +# -- autosummary + +autosummary_generate = True + +# -- numpydoc + +# use blockquotes (numpydoc>=0.8 only) +numpydoc_use_blockquotes = True + + +# -- run sphinx-apidoc automatically ------------------------------------------ +# this is required to have apidoc generated as part of readthedocs builds +# see https://github.com/rtfd/readthedocs.org/issues/1139 + +def run_apidoc(_): + """Call sphinx-apidoc + """ + from sphinx.ext.apidoc import main as apidoc_main + curdir = os.path.abspath(os.path.dirname(__file__)) + apidir = os.path.join(curdir, 'api') + module = os.path.join(curdir, os.path.pardir, 'hveto') + apidoc_main([module, '--separate', '--force', '--output-dir', apidir]) + + +# -- add static files---------------------------------------------------------- + +def setup_static_content(app): + # configure stylesheets + for sdir in html_static_path: + # add stylesheets + cssdir = os.path.join(sdir, 'css') + for cssf in glob.glob(os.path.join(cssdir, '*.css')): + app.add_stylesheet(cssf.split(os.path.sep, 1)[1]) + + # add custom javascript + jsdir = os.path.join(sdir, 'js') + for jsf in glob.glob(os.path.join(jsdir, '*.js')): + app.add_javascript(jsf.split(os.path.sep, 1)[1]) + + +# -- setup -------------------------------------------------------------------- + +def setup(app): + setup_static_content(app) + app.connect('builder-inited', run_apidoc) diff --git a/docs/index.rst b/docs/index.rst index 2deb87e..56c884e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,60 +1,94 @@ -.. Hveto documentation master file, created by - sphinx-quickstart on Thu Apr 21 14:05:08 2016. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. +================= +Hierarchical Veto +================= -Welcome to Hveto's documentation! -================================= +|PyPI version| |Conda version| -The HierarchichalVeto is an algorithm to identify statistically-significant correlations between transient noise events (triggers) in instrumental or environment data channels and those in the main calibrated gravitational-wave strain output for a ground-based laser interferometer gravitational-wave detector. -It is a key tool in reducing the noise background in searches for transient gravitational-wave signals, and was used during the detection of the binary black hole signal `GW150914 `_. +|DOI| |License| |Supported Python versions| -For full details see `Smith et al. (Classical and Quantum Gravity, 2011) `_ +Hveto is a package designed for gravitational-wave detector characterisation +and data quality. The algorithm identifies statistically significant +correlations between transient noise events (triggers) in instrumental or +environmental data channels, and those in the calibrated gravitational-wave +strain output. Hveto is a key tool in reducing the noise background in searches +for transient gravitational-wave signals, and was used, for example, during the +detection of the binary black hole signal +`GW150914 `_. -Installing Hveto ----------------- +For full details about the algorithm, please refer to `Smith et al. 2011`_ +(Classical and Quantum Gravity). -The easiest method to install hveto is using `pip `_ directly from the `GitHub repository `_: +To get started, simply import the core module: -.. code-block:: bash +.. code:: python - $ pip install git+https://github.com/gwdetchar/hveto.git + import hveto -How to run Hveto ----------------- +------------ +Installation +------------ -The main product of this package is the command-line executable `hveto`, which runs an end-to-end search for statistical coincidences, and produces a list of viable data-quality flags that can be used as vetoes in a search, as well as an HTML summary. +Hveto is best installed with `conda`_: -To run an analysis: +.. code:: bash -.. code-block:: bash + conda install -c conda-forge hveto - $ hveto --config-file ./my-config-file.ini +but can also be installed with `pip`_: -where ```` and ```` are the start and stop GPS times of the analysis period, and ``./my-config-file.ini`` is the path of your configuration file. Strictly speaking the configuration file is optional, but is highly recommend if you want to have any control over your analysis. +.. code:: bash -For a full list of command-line argument and options, run + python -m pip install hveto -.. code-block:: bash +Note, users with `LIGO.ORG` credentials have access to a software +container with a regularly-updated build of Hveto. For more +information please refer to the +`LSCSoft Conda `_ documentation. - $ hveto --help +------------ +Contributing +------------ -For more details see :ref:`command-line`. +All code should follow the Python Style Guide outlined in `PEP 0008`_; +users can use the `pep8`_ package to check their code for style issues +before submitting. -Package documentation ---------------------- +See `the contributions guide`_ for the recommended procedure for +proposing additions/changes. -Please consult these pages for more details on using Hveto: +The Hveto project is hosted on GitHub: + +* Issue tickets: https://github.com/gwdetchar/hveto/issues +* Source code: https://github.com/gwdetchar/hveto + +License +------- + +Hveto is distributed under the `GNU General Public License`_. .. toctree:: :maxdepth: 1 + :hidden: command-line/index api/hveto.config - -Indices and tables -================== - -* :ref:`genindex` -* :ref:`modindex` -* :ref:`search` + api/index + +.. _PEP 0008: https://www.python.org/dev/peps/pep-0008/ +.. _pep8: https://pypi.python.org/pypi/pep8 +.. _the contributions guide: https://github.com/gwdetchar/hveto/blob/master/CONTRIBUTING.md +.. _conda: https://conda.io +.. _pip: https://pip.pypa.io/en/stable/ +.. _Smith et al. 2011: //dx.doi.org/10.1088/0264-9381/28/23/235005 +.. _GNU General Public License: https://github.com/gwdetchar/hveto/blob/master/LICENSE + +.. |PyPI version| image:: https://badge.fury.io/py/hveto.svg + :target: http://badge.fury.io/py/hveto +.. |Conda version| image:: https://img.shields.io/conda/vn/conda-forge/hveto.svg + :target: https://anaconda.org/conda-forge/hveto/ +.. |DOI| image:: https://zenodo.org/badge/DOI/10.5281/2584615.svg + :target: https://doi.org/10.5281/zenodo.2584615 +.. |License| image:: https://img.shields.io/pypi/l/hveto.svg + :target: https://choosealicense.com/licenses/gpl-3.0/ +.. |Supported Python versions| image:: https://img.shields.io/pypi/pyversions/hveto.svg + :target: https://pypi.org/project/hveto/ diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..dbbdab1 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,3 @@ +numpydoc +sphinx_bootstrap_theme +sphinxcontrib-programoutput