Commit 705fbfcd authored by Leo Pound Singer's avatar Leo Pound Singer
Browse files

Rename to LIGO/Virgo/KAGRA Public Alerts User Guide

parent a112b723
Pipeline #96419 failed with stage
in 26 minutes and 53 seconds
LIGO/Virgo Public Alerts User Guide
LIGO/Virgo/KAGRA Public Alerts User Guide
===================================
This Git repository contains the source code for the LIGO/Virgo Public Alerts
This Git repository contains the source code for the LIGO/Virgo/KAGRA Public Alerts
User Guide. For most recently released HTML edition of the User Guide, visit
http://emfollow.docs.ligo.org/.
......
......@@ -24,7 +24,7 @@ The timeline for distribution of alerts is described below.
Alert Timeline
--------------
Here, we describe the sequence of LIGO/Virgo alerts for a single event that
Here, we describe the sequence of LIGO/Virgo/KAGRA alerts for a single event that
will be distributed through the Gamma-ray Coordinates Network (:term:`GCN`) via
notices and circulars (see the :doc:`/content` and :doc:`/tutorial/index`
sections for details).
......
......@@ -127,7 +127,7 @@ to trigger preliminary alerts once this is finished.
**LLAMA** [#LLAMA1]_ [#LLAMA2]_ The `Low-Latency Algorithm for Multi-messenger
Astrophysics <http://gwhen.com>`__
is a an online search pipeline combining LIGO/Virgo GW triggers with High
is a an online search pipeline combining LIGO/Virgo/KAGRA GW triggers with High
Energy Neutrino (HEN) triggers from IceCube. It finds temporally-coincident
sub-threshold IceCube neutrinos and performs a detailed Bayesian significance
calculation to find joint GW+HEN triggers.
......
......@@ -43,7 +43,7 @@ Live Status
-----------
There are a handful of public web pages that report live status of the
LIGO/Virgo detectors and alert infrastructure.
LIGO/Virgo/KAGRA detectors and alert infrastructure.
* | **Detector Status Portal**: Daily summary of detector performance.
| https://www.gw-openscience.org/detector_status/
......@@ -52,7 +52,7 @@ LIGO/Virgo detectors and alert infrastructure.
| https://ldas-jobs.ligo.caltech.edu/~gwistat/gwistat/gwistat.html
* | **LIGO Data Grid Status**: Live dashboard showing up/down status of the
detectors and online analyses. Status of the LIGO/Virgo alert pipeline is
detectors and online analyses. Status of the LIGO/Virgo/KAGRA alert pipeline is
indicated by the "EMFollow" box.
| https://monitor.ligo.org/gwstatus
......
......@@ -6,6 +6,9 @@ Version 15 (unreleased)
.. rubric:: General
* Change the name of this document from "LIGO/Virgo Public Alerts User Guide"
to "LIGO/Virgo/KAGRA Public Alerts User Guide".
.. rubric:: Getting Started Checklist
.. rubric:: Observing Capabilities
......@@ -41,8 +44,8 @@ Version 13 (2019-12-16)
.. rubric:: Alert Contents
* Add a warning that :term:`VOEvent` over anonymous :term:`VTP` is the only
GCN format and distribution method that is fully supported by LIGO/Virgo. In
particular, LIGO/Virgo performs only limited quality control control checks
GCN format and distribution method that is fully supported by LIGO/Virgo/KAGRA. In
particular, LIGO/Virgo/KAGRA performs only limited quality control control checks
for the textual "full format" and the binary format.
* In the VOEvent alert schema, add a ``name`` attribute to each ``<Group>``
......@@ -154,7 +157,7 @@ Version 10 (2019-07-31)
will also make it simpler to work with Numpy indexing operations, since Numpy
uses a signed integer type for indexing.
This change will go into effect in the LIGO/Virgo low-latency alert system on
This change will go into effect in the LIGO/Virgo/KAGRA low-latency alert system on
2019-08-06.
Users of `ligo.skymap`_ should update to version 0.1.8 or newer because older
......@@ -309,7 +312,7 @@ Version 3 (2019-02-13)
* Change the IVORN prefix from ``ivo://gwnet/gcn_sender`` to
``ivo://gwnet/LVC``, because GCN traditionally uses the text after the ``/``
to indicate the name of the mission, which most closely corresponds to "LVC,"
short for "LIGO/Virgo Collaboration." Note that this IVORN is used for
short for "LIGO/Virgo/KAGRA Collaboration." Note that this IVORN is used for
historical purposes and continuity with the GCN notice format used in O1 and
O2, and is likely to change in the future with the commissioning of
additional gravitational-wave facilities.
......@@ -336,7 +339,7 @@ Version 2 (2018-12-13)
.. rubric:: Sample Code
* GCN has now begun publicly broadcasting sample LIGO/Virgo GCN Notices.
* GCN has now begun publicly broadcasting sample LIGO/Virgo/KAGRA GCN Notices.
Updated the sample code accordingly with instructions for receiving live
sample notices.
......
......@@ -22,9 +22,9 @@ from versioneer import get_version
# -- Project information -----------------------------------------------------
project = 'LIGO/Virgo Public Alerts User Guide'
copyright = '2018, LIGO Scientific Collaboration, Virgo Collaboration'
author = 'LIGO Scientific Collaboration, Virgo Collaboration'
project = 'LIGO/Virgo/KAGRA Public Alerts User Guide'
copyright = '2018, LIGO Scientific Collaboration, Virgo Collaboration, KAGRA Collaboration'
author = 'LIGO Scientific Collaboration, Virgo Collaboration, KAGRA Collaboration'
# The full version, including alpha/beta/rc tags
release = get_version()
......@@ -151,8 +151,8 @@ latex_elements = {
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
(master_doc, 'LIGOVirgoPublicAlertsUserGuide.tex', 'LIGO/Virgo Public Alerts User Guide Documentation',
'LIGO Scientific Collaboration, Virgo Collaboration', 'manual'),
(master_doc, 'LIGOVirgoPublicAlertsUserGuide.tex', 'LIGO/Virgo/KAGRA Public Alerts User Guide Documentation',
'LIGO Scientific Collaboration, Virgo Collaboration, KAGRA Collaboration', 'manual'),
]
......@@ -161,7 +161,7 @@ latex_documents = [
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
(master_doc, 'ligovirgopublicalertsuserguide', 'LIGO/Virgo Public Alerts User Guide Documentation',
(master_doc, 'ligovirgopublicalertsuserguide', 'LIGO/Virgo/KAGRA Public Alerts User Guide Documentation',
[author], 1)
]
......@@ -172,7 +172,7 @@ man_pages = [
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
(master_doc, 'LIGOVirgoPublicAlertsUserGuide', 'LIGO/Virgo Public Alerts User Guide Documentation',
(master_doc, 'LIGOVirgoPublicAlertsUserGuide', 'LIGO/Virgo/KAGRA Public Alerts User Guide Documentation',
author, 'LIGOVirgoPublicAlertsUserGuide', 'One line description of project.',
'Miscellaneous'),
]
......
Alert Contents
==============
Public LIGO/Virgo alerts are distributing using NASA's Gamma-ray Coordinates
Public LIGO/Virgo/KAGRA alerts are distributing using NASA's Gamma-ray Coordinates
Network (:term:`GCN`). There are two types of alerts:
**GCN Notices** are machine-readable packets. They are available as
......@@ -10,14 +10,14 @@ Network (:term:`GCN`). There are two types of alerts:
format.
.. warning::
We recommend receiving LIGO/Virgo alerts in the VOEvent XML format using one
We recommend receiving LIGO/Virgo/KAGRA alerts in the VOEvent XML format using one
of `GCN's anonymous VOEvent brokers`_. VOEvent over anonymous :term:`VTP` is
the **only GCN format and distribution method that is fully supported by
LIGO/Virgo.**
LIGO/Virgo/KAGRA.**
The VOEvent XML alerts are official data products of LIGO/Virgo. GCN
The VOEvent XML alerts are official data products of LIGO/Virgo/KAGRA. GCN
produces `several other legacy formats`_ from them, in particular a
text-based "full format" and binary format. LIGO/Virgo performs only limited
text-based "full format" and binary format. LIGO/Virgo/KAGRA performs only limited
quality control of the legacy formats.
**GCN Circulars** are short human-readable astronomical bulletins. They are
......@@ -73,7 +73,7 @@ assessment`_.
Notice Contents
---------------
The table below is a representation of the contents of a LIGO/Virgo GCN Notice.
The table below is a representation of the contents of a LIGO/Virgo/KAGRA GCN Notice.
+-------------------+-----------------------------------------------------------+-------------------------------------------------------------------+
| **Root** |
......@@ -214,7 +214,7 @@ such as ``bayestar.fits.gz``, always points to the most recent version.
rationale in :dcc:`G1800186`). It uses HEALPix :ref:`explicit indexing
<gamma-astro-data-formats:hpx_explicit>` and the `NUNIQ numbering scheme`_,
which is closely related to `multi-order coverage (MOC) maps`_ in Aladin.
This is the internal format that is used by the LIGO/Virgo low-latency
This is the internal format that is used by the LIGO/Virgo/KAGRA low-latency
alert pipeline. **This is an experimental format, and it is currently
recommended only for advanced users.** See the section
:doc:`/tutorial/multiorder_skymaps` for details.
......@@ -367,7 +367,7 @@ NSBH, BBH, or MassGap merger):
All of the quantities in the Classification and Properties sections are model
dependent to some extent: the Classification section takes into consideration
prior knowledge of astrophysical compact binary merger rates from previous
LIGO/Virgo observations, and both the Classification and Properties sections
LIGO/Virgo/KAGRA observations, and both the Classification and Properties sections
depend on details of neutron star physics (e.g. maximum NS mass, equation of
state). See the earlier subsection of the :doc:`Data Analysis
</analysis/inference>` section for implementation details.
......
......@@ -52,7 +52,7 @@ Glossary
GraceDB
Gravitational Wave Candidate Event Database (https://gracedb.ligo.org),
the official public marshal portal for LIGO/Virgo candidates.
the official public marshal portal for LIGO/Virgo/KAGRA candidates.
GRB
Gamma-ray burst.
......
LIGO/Virgo Public Alerts User Guide
===================================
LIGO/Virgo/KAGRA Public Alerts User Guide
=========================================
.. image:: _static/banner.png
:alt: GW170817/GRB170817A discovery images
Welcome to the LIGO/Virgo Public Alerts User Guide! This document is intended
Welcome to the LIGO/Virgo/KAGRA Public Alerts User Guide! This document is intended
for both professional astronomers and science enthusiasts who are interested in
receiving alerts and real-time data products related to gravitational-wave (GW)
events.
Three sites (:term:`LHO`, :term:`LLO`, :term:`Virgo`) together form a global
network of ground-based GW detectors. The `LIGO Scientific Collaboration`_ and
the `Virgo Collaboration`_ jointly analyze the data in real time to detect and
Four sites (:term:`LHO`, :term:`LLO`, :term:`Virgo`, :term:`KAGRA`) together form a global
network of ground-based GW detectors. The `LIGO Scientific Collaboration`_,
the `Virgo Collaboration`_, and the `KAGRA Collaboration`_ jointly analyze the data in real time to detect and
localize transients from compact binary mergers and other sources. When a
signal candidate is found, an alert is sent to astronomers in order to search
for counterparts (electromagnetic waves or neutrinos).
`Advanced LIGO`_ and `Advanced Virgo`_ began their third observing run (O3) on
April 1, 2019. For the first time, **LIGO/Virgo alerts are public**. Alerts are
April 1, 2019. `KAGRA`_ expects to come online in 2020. For the first time, **LIGO/Virgo/KAGRA alerts are public**. Alerts are
distributed through NASA's Gamma-ray Coordinates Network (:term:`GCN`). There
are two types of alerts: human-readable :term:`GCN Circulars <GCN Circular>`
and machine-readable :term:`GCN Notices <GCN Notice>`. This document provides a
......@@ -55,5 +55,7 @@ Appendix
.. _`LIGO Scientific Collaboration`: https://ligo.org/
.. _`Virgo Collaboration`: http://public.virgo-gw.eu/the-virgo-collaboration/
.. _`KAGRA Collaboration`: https://gwcenter.icrr.u-tokyo.ac.jp/en/organization
.. _`Advanced LIGO`: https://ligo.caltech.edu
.. _`Advanced Virgo`: http://www.virgo-gw.eu
.. _`KAGRA`: https://gwcenter.icrr.u-tokyo.ac.jp/en/
......@@ -9,7 +9,7 @@ items on this checklist.
-----------------------
Pay particular attention to the :doc:`content` section of this user guide to
familiarize yourself with the contents of machine-readable LIGO/Virgo
familiarize yourself with the contents of machine-readable LIGO/Virgo/KAGRA
:term:`GCN Notices <GCN Notice>`. Play with the :doc:`tutorial/index` to
receive example GCN Notices and practice working with :doc:`sky localization
maps <tutorial/skymaps>`.
......@@ -20,9 +20,9 @@ maps <tutorial/skymaps>`.
`Subscribe to GCN Circulars`_ and review the `instructions for posting GCN
Circulars`_. A :term:`GCN Circular` is a short, public bulletin to rapidly
report an astronomical observation. GCN Circulars are distributed by email and
`archived online`_. [#f1]_ LIGO/Virgo uses GCN Circulars to announce
`archived online`_. [#f1]_ LIGO/Virgo/KAGRA uses GCN Circulars to announce
detections, and the astronomy community expects participants to promptly
disseminate preliminary reports of follow-up observations of LIGO/Virgo
disseminate preliminary reports of follow-up observations of LIGO/Virgo/KAGRA
counterparts using GCN Circulars as well.
.. important::
......@@ -33,15 +33,15 @@ counterparts using GCN Circulars as well.
------------------------------
Sign up to the OpenLVEM mailing list by following the `OpenLVEM instructions`_.
LIGO/Virgo will use this list to make announcements and solicit input. It is
also a great place to ask questions or discuss issues related to LIGO/Virgo
LIGO/Virgo/KAGRA will use this list to make announcements and solicit input. It is
also a great place to ask questions or discuss issues related to LIGO/Virgo/KAGRA
public alerts. Documents relating to teleconferences and in-person meetings are
available at `OpenLVEM wiki`_.
4. Visit GraceDB
----------------
Familiarize yourself with GraceDB_, LIGO/Virgo's online portal for alerts and
Familiarize yourself with GraceDB_, LIGO/Virgo/KAGRA's online portal for alerts and
real-time results.
.. [#f1] GCN Circulars are similar to `Astronomer's Telegrams`_ (ATels). By
......
......@@ -35,7 +35,7 @@ multi-order sky maps encode *sampled images or functions on the sphere*. The
multi-order sky map FITS format is a superset of the MOC FITS format, the only
difference being that a multi-order sky map has values attached to each cell
(probability density, distance estimates) whereas a MOC map does not. Future
Aladin releases will support the LIGO/Virgo multi-resolution sky maps.
Aladin releases will support the LIGO/Virgo/KAGRA multi-resolution sky maps.
Running Aladin Desktop
----------------------
......@@ -45,9 +45,9 @@ Virtual Machine`_ (JVM) installed. More details are in Aladin's `download
page`_.
.. note::
Aladin may fail to load some LIGO/Virgo sky maps and display a
Aladin may fail to load some LIGO/Virgo/KAGRA sky maps and display a
``java.lang.OutOfMemoryError`` error message. This is because the highest
resolution LIGO/Virgo sky maps do not fit inside Aladin's default memory
resolution LIGO/Virgo/KAGRA sky maps do not fit inside Aladin's default memory
size.
You can increase the maximum memory size used by your Java runtime
......
Additional Resources
====================
Here are a few additional resources for working with LIGO/Virgo alerts.
Here are a few additional resources for working with LIGO/Virgo/KAGRA alerts.
.. toctree::
:maxdepth: 1
......
......@@ -3,19 +3,19 @@ Sample Code
This section provides Python sample code for receiving and interacting with
:term:`GCN Notices <GCN Notice>`. GCN Notices are available over several
different protocols and in several different formats. LIGO/Virgo recommends
different protocols and in several different formats. LIGO/Virgo/KAGRA recommends
using the VOEvent Transport Protocol (:term:`VTP`) to receive notices in
:term:`VOEvent` XML format because it is anonymous, configuration-free, and
easy to parse.
.. warning::
The VOEvent XML alerts are official data products of LIGO/Virgo. GCN
The VOEvent XML alerts are official data products of LIGO/Virgo/KAGRA. GCN
produces `several other legacy formats`_ from them, in particular a
text-based "full format" and binary format. LIGO/Virgo performs only limited
text-based "full format" and binary format. LIGO/Virgo/KAGRA performs only limited
quality control of the legacy formats.
This tutorial will walk you through writing a Python script to receive and
process the example LIGO/Virgo GCN notices that are sent every hour. The
process the example LIGO/Virgo/KAGRA GCN notices that are sent every hour. The
tutorial is broken into the following subsections:
.. toctree::
......
Multi-Order Sky Maps (For Advanced Users)
=========================================
For most events, LIGO/Virgo distributes both the standard :term:`HEALPix`
For most events, LIGO/Virgo/KAGRA distributes both the standard :term:`HEALPix`
format with the file extension ``.fits.gz``, as well as an experimental
multi-resolution HEALPix format, distinguished by the file extension
``.multiorder.fits``.
......@@ -19,7 +19,7 @@ GW170817. It will get slowly worse as we approach design sensitivity. It’s
already a major pain if you are studying future detector networks with
simulations.
It is worth reviewing why LIGO/Virgo has adopted HEALPix rather than a more
It is worth reviewing why LIGO/Virgo/KAGRA has adopted HEALPix rather than a more
commonplace image format for sky maps in the first place. Gravitational-wave
localizations are distinguished from many other kinds of astronomical image
data by the following features:
......@@ -45,7 +45,7 @@ gravitational-wave detectors improve in sensitivity and additional detectors
come online, finer resolutions will be required.
Fortunately, the increased resolution will come at little to no computational
cost for actually producing localizations because most LIGO/Virgo parameter
cost for actually producing localizations because most LIGO/Virgo/KAGRA parameter
estimation analyses use a simple multi-resolution adaptive mesh refinement
scheme that limits them to sampling the sky at only about 20k points.
......@@ -76,7 +76,7 @@ and in terms of memory (up to several gigabytes). The time and memory will
worsen as localization accuracy improves.
The multi-resolution format is immune to these issues because it is a direct
representation of the adaptive mesh produced by the LIGO/Virgo localization
representation of the adaptive mesh produced by the LIGO/Virgo/KAGRA localization
algorithms.
The UNIQ Indexing Scheme
......@@ -115,7 +115,7 @@ The inverse is:
FITS Format for Multi-Order Sky Maps
------------------------------------
The FITS format for LIGO/Virgo multi-resolution sky maps uses the **UNIQ**
The FITS format for LIGO/Virgo/KAGRA multi-resolution sky maps uses the **UNIQ**
indexing scheme and is a superset of the FITS serialization for Multi-Order
Coverage (MOC) maps specified by IVOA [#HiPSStandard]_ as part of the
Hierarchical Progressive Survey (HiPS) capability [#HiPSPaper]_, notably used
......@@ -187,7 +187,7 @@ Let's look at the FITS header:
MJD-OBS = 58423.93248442635 / modified Julian date of the observation
DATE = '2018-11-01T22:34:49.000000' / UTC date of file creation
CREATOR = 'BAYESTAR' / Program that created this file
ORIGIN = 'LIGO/Virgo' / Organization responsible for this FITS file
ORIGIN = 'LIGO/Virgo/KAGRA' / Organization responsible for this FITS file
RUNTIME = 3.24746292643249 / Runtime in seconds of the CREATOR program
DISTMEAN= 39.76999609489013 / Posterior mean distance (Mpc)
DISTSTD = 8.308435058808886 / Posterior standard deviation of distance (Mpc)
......@@ -317,7 +317,7 @@ The following binary search method of looking up a pixel by sky position
exploits the algebraic properties of HEALPix. It has a complexity of
:math:`O(\log N)` where :math:`N` is the number of multi-resolution pixels. It
assumes that every sky position is mapped on to exactly one multi-resolution
tile, which is true for LIGO/Virgo multi-resolution sky maps.
tile, which is true for LIGO/Virgo/KAGRA multi-resolution sky maps.
1. First, find the **NESTED** pixel index of every multi-resolution tile,
at an arbitrarily high resolution. (``nside = 2**29`` works nicely
......
......@@ -12,7 +12,7 @@ need to import a few extra Python modules::
import astropy.time
import astropy.units as u
The LIGO/Virgo probability sky maps are always in equatorial coordinates. Once
The LIGO/Virgo/KAGRA probability sky maps are always in equatorial coordinates. Once
we have looked up the coordinates of the :term:`HEALPix` pixels, we will use
Astropy to transform those coordinates to a horizontal (altitude–azimuth) frame
for a particular site on the Earth at a particular time. Then we can quickly
......@@ -114,7 +114,7 @@ Let's run the new GCN handler now...
# (killed or interrupted with control-C).
gcn.listen(handler=process_gcn)
When you run this script, each time you receive a sample LIGO/Virgo GCN Notice,
When you run this script, each time you receive a sample LIGO/Virgo/KAGRA GCN Notice,
it will print something like the following (note that probability will change
as a function of time):
......
......@@ -14,7 +14,7 @@ this. The example below will handle only 'CBC' events.
.. important::
Note that mock or 'test' observations are denoted by the ``role="test"``
VOEvent attribute. Alerts resulting from real LIGO/Virgo science data will
VOEvent attribute. Alerts resulting from real LIGO/Virgo/KAGRA science data will
always have ``role="observation"``. The sample code below will respond
**only** to 'test' events. When preparing for actual observations, you
**must remember to switch to 'observation' events**.
......@@ -94,7 +94,7 @@ we defined above.
# (killed or interrupted with control-C).
gcn.listen(handler=process_gcn)
When you run this script you should receive a sample LIGO/Virgo GCN Notice
When you run this script you should receive a sample LIGO/Virgo/KAGRA GCN Notice
every hour. For each event received it will print output that looks like what
is shown in the :ref:`offline-testing` example below.
......
Working with Sky Maps
=====================
Let's take a look at what is inside one of the LIGO/Virgo probability sky maps.
Let's take a look at what is inside one of the LIGO/Virgo/KAGRA probability sky maps.
They are FITS image files and can be manipulated and viewed with many
commonplace FITS tools. However, they are a little unusual in two regards.
First, since they are all-sky images, they are stored in the :term:`HEALPix`
......@@ -78,7 +78,7 @@ tools like funhead_ from Funtools_, imhead_ from WCSTools_, or
MJD-OBS = 58423.93248442613 / modified Julian date of the observation
DATE = '2018-11-01T22:34:49.000000' / UTC date of file creation
CREATOR = 'BAYESTAR' / Program that created this file
ORIGIN = 'LIGO/Virgo' / Organization responsible for this FITS file
ORIGIN = 'LIGO/Virgo/KAGRA' / Organization responsible for this FITS file
RUNTIME = 3.24746292643249 / Runtime in seconds of the CREATOR program
DISTMEAN= 39.76999609489013 / Posterior mean distance (Mpc)
DISTSTD = 8.308435058808886 / Posterior standard deviation of distance (Mpc)
......@@ -100,9 +100,9 @@ tools like funhead_ from Funtools_, imhead_ from WCSTools_, or
There are several useful pieces of information here:
* ``COORDSYS=C``, telling you that the :term:`HEALPix` projection is in the
Celestial (equatorial, ICRS) frame, as all LIGO/Virgo probability sky maps
Celestial (equatorial, ICRS) frame, as all LIGO/Virgo/KAGRA probability sky maps
will be.
* ``OBJECT``, the unique LIGO/Virgo identifier for the event.
* ``OBJECT``, the unique LIGO/Virgo/KAGRA identifier for the event.
* ``REFERENC``, a link to the candidate page in :term:`GraceDB`.
* ``INSTRUME``, a list of gravitational-wave sites that triggered on the
event: `H1` for LIGO Hanford, `L1` for LIGO Livingston, and `V1` for Virgo.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment