GraceDB

Analyse a gravitational-wave sky map: how big the localisation is, how far away, and how likely given sky positions or telescope fields are to contain the source. Args: graceid: Superevent id, e.g. ``S230518h``. filename: Sky map to use, e.g. ``bayestar.multiorder.fits``. Defaults to the most recently uploaded one; later maps (Bilby, publication maps) are usually more accurate than the rapid BAYESTAR map. positions: Up to 100 sky positions (e.g. candidate host galaxies or optical transients) to check. fields: Up to 20 circular telescope fields; returns the probability inside each. Returns: 50% and 90% credible areas (deg^2), the overall distance estimate (Mpc), the most probable position, and the other available sky maps. For each position: the credible level (smallest credible region containing it; below 0.9 means inside the 90% region), probability density per deg^2 and, inside the 99% region, the distance along that line of sight (compare it with a galaxy's distance before calling it a likely host). For each field: the enclosed probability.

Audit the public alerts of a period: how many, how many retracted, how fast, and by whom. Counts all superevents created in the period, the significant public alerts (label GCN_PRELIM_SENT) and the alerts sent only as low-significance (LOW_SIGNIF_PRELIM_SENT, O4 onwards). Breaks the significant alerts down by detector network, pipeline and search, and lists every retracted superevent (ADVNO) with the hours from creation to retraction. GraceDB does not record why an alert was retracted: read the LVK retraction circular (``search_gcn_circulars``). Args: start: Start of the period (ISO-8601 date or time, UTC); matched against superevent creation time. end: End of the period, inclusive. category: ``Production`` (real alerts), ``MDC`` (simulated) or ``Test``.

Check which detectors have public GWOSC strain data for a time span. Call this before ``download_strain_data``. Public strain exists only for released observing runs, and detectors are often offline, so coverage is frequently partial. Args: gps_start: Start of the span in GPS seconds. Use together with ``gps_end``. gps_end: End of the span in GPS seconds, at most 7 days after ``gps_start``. event: Instead of a span, a GraceDB superevent id (``S190814bv``) or a catalogue name (``GW150914``); checks ``window`` seconds centred on it. window: Span in seconds around ``event``. detectors: Detectors to check. Defaults to H1, L1, V1 and K1. Returns: For each detector, the public data segments and the fraction of the span they cover. ``available`` lists detectors with complete coverage, also counting the short files GWOSC publishes around catalogue events.

Data-quality flags for each detector over a span, from GWOSC. Flags say whether data passes each search's vetoes: CBC (compact binaries), BURST, CW (continuous waves) and STOCH (stochastic background), at categories CAT1 (most basic checks) to CAT3 (strictest). ``NO_<search>_HW_INJ`` flags mark time free of hardware injections, simulated signals physically added to the detector. CW injections are weak, long-lasting signals present for much of each run; they matter for continuous-wave searches, not for transients such as compact-binary mergers. Args: gps_start: Start of the span in GPS seconds. Use together with ``gps_end``. gps_end: End of the span in GPS seconds, at most 7 days after ``gps_start``. event: Instead of a span, a GraceDB superevent id or catalogue name; checks ``window`` seconds centred on it. window: Span in seconds around ``event``. detectors: Detectors to check. Defaults to H1, L1, V1 and K1. Returns: Per detector: ``data_coverage`` (fraction of the span with public data), ``failed`` (flags vetoing part of the time that has data), hardware injections in that time, and every flag's coverage.

Download GraceDB artifacts (skymaps, p_astro, PE results, logs) for an event. These are the files GraceDB actually hosts. This is NOT raw strain data (use ``download_strain_data`` for that). Args: graceid: The superevent id, e.g. ``S230518h``. filenames: Specific filenames to download. If omitted, downloads every file attached to the superevent. Returns: A dict mapping each requested filename to the local path it was saved to, and ``resources`` mapping it to a ``gracedb://`` URI readable over MCP (files over 50 MB are local only).

Download public strain time series around an event from GWOSC. IMPORTANT: GraceDB does not host raw strain. This tool reads the event GPS time (``t_0``) from GraceDB, then fetches open strain from GWOSC. It only succeeds for events whose data has been publicly released (past observing runs); fresh low-latency alerts will not have public strain yet. Requires the optional ``gwpy`` dependency (``pip install gracedb-mcp[strain]``). Args: graceid: The superevent id, e.g. ``S190814bv``. When ``gps_time`` is given this is only used as the output folder name (e.g. ``GW150914``). detectors: Detector prefixes to fetch, e.g. ``["H1", "L1", "V1"]``. Defaults to H1 and L1. duration: Length of the segment in seconds, centred on ``t_0``. Up to 30 s fits the short file GWOSC publishes around catalogue events (the event is not exactly centred in it); longer windows read ~100 MB hour-long files. sample_rate: Target sample rate in Hz (4096 or 16384 typically). gps_time: Centre time in GPS seconds. Skips the GraceDB lookup, which is needed for O1 events such as GW150914 (``1126259462.4``) that predate GraceDB superevents. Returns: A dict mapping each detector to the saved ``.hdf5`` strain file path, and ``resources`` mapping it to a ``gracedb://`` URI readable over MCP.

Source parameters for one published event, with 90% credible intervals. Args: name: A catalogue name such as ``GW150914`` or ``GW200129_065458``, or a GraceDB superevent id such as ``S190814bv`` (matched by GPS time). Returns: Masses, distance, redshift, spin, SNR, FAR and p_astro as ``{value, interval_90}``, plus the GraceDB id, available strain files, parameter-estimation sets and the GWOSC event page.

GraceDB labels on a superevent, in the order they were applied, with meanings. Labels record the event's history: data-quality checks (DQOK, DQV), human review (ADVOK, ADVNO = retracted), injections (INJ), and which products are ready (SKYMAP_READY, PE_READY). Args: graceid: The superevent id, e.g. ``S190814bv``.

Fetch the full record and source classification for one superevent. Args: graceid: The superevent id, e.g. ``S230518h``. Returns: A dict with the raw superevent record, the available file list, the parsed source-classification probabilities (BBH / BNS / NSBH / Terrestrial) when a p_astro file has been published, and ``pipelines``: each search pipeline's best candidate (O4 onwards), so you can see which pipelines found the signal and how significant each one rated it.

Full text of one GCN Circular, with its links (GCN page, ADS for citation). Args: circular_id: The circular number, e.g. ``33813``.

Observing runs whose data GWOSC has publicly released, oldest first. Args: gps: Optional GPS time; the answer says which released run covers it, or that it falls outside every released run (detectors off, or data not public yet). Returns: Each run's name, GPS and UTC span, detectors and dataset DOI (cite it when using the data).

Search published gravitational-wave events in the GWOSC catalogues. Unlike GraceDB alerts, catalogue events are vetted detections with estimated source parameters. Each event appears once, in its newest version. Args: catalog: Restrict to one catalogue, e.g. ``GWTC-1-confident``, ``GWTC-2.1-confident``, ``GWTC-3-confident``, ``GWTC-4.0``. Omit for all. gps_start: Earliest event GPS time. Optional. gps_end: Latest event GPS time. Optional. min_snr: Minimum network matched-filter SNR (louder signals are clearer). min_p_astro: Minimum probability of astrophysical origin, 0-1. min_total_mass: Minimum total source-frame mass in solar masses. max_total_mass: Maximum total source-frame mass in solar masses. max_distance_mpc: Maximum luminosity distance in megaparsecs. max_results: Maximum number of events to return (newest first). Returns: ``count`` of all matches and up to ``max_results`` event summaries with masses, distance, redshift, spin (chi_eff), SNR, FAR and p_astro.

Search NASA GCN Circulars: rapid reports from telescopes, satellites and neutrino detectors about transients, including follow-up of gravitational-wave alerts. Reports name gravitational-wave events by their GraceDB id (``S230518h``), so a catalogue name such as ``GW190814`` is also searched as ``S190814bv``. Args: event: An event name: GraceDB id (``S230518h``), GW name (``GW170817``), GRB (``GRB 230518A``), IceCube alert (``IceCube-261020A``), etc. Matches circulars with the name in their subject, i.e. reports about the event. query: Free search in Lucene syntax over ``subject``, ``body`` and ``submitter``, e.g. ``subject:"Fermi" AND body:"upper limit"``. Combined with ``event`` using AND when both are given. Use ``body:"S230518h"`` to also find circulars that only mention an event in passing. start_date: Only circulars submitted on or after this date (``YYYY-MM-DD``). end_date: Only circulars submitted on or before this date (``YYYY-MM-DD``). sort: ``newest`` (default) or ``relevance`` (best for well-studied events with hundreds of circulars, such as GW170817). page: Page of results, for more than ``max_results`` matches. include_bodies: Include each circular's full text (about 1-3 kB each). max_results: Circulars per page, at most 50. Returns: ``total`` matching circulars and one page of them with id, subject, event, submission time, links (GCN page, ADS for citation), and optionally the text; plus ``archive_url`` to see the same search on the GCN website.

Search GraceDB superevents, newest first. Args: start: Inclusive lower bound on creation time (ISO-8601, e.g. ``2023-05-01`` or ``2023-05-01T00:00:00``). Optional. end: Inclusive upper bound on creation time (same format). Optional. max_far: Maximum false-alarm rate in Hz. Lower = more significant. A common "confident detection" threshold is ``3.2e-8`` (~1 per year). Optional. min_confidence: Minimum astrophysical probability in [0, 1], computed as ``1 - P(Terrestrial)`` from each event's p_astro file. Applied as a post-filter (requires extra fetches per event). Optional. category: ``Production`` (real alerts), ``MDC`` (simulated signals injected continuously, useful for testing) or ``Test``. max_results: Maximum number of superevents to return. Returns: A dict with the resolved ``query`` string and a list of matching ``superevents``.

Convert an ISO-8601 UTC timestamp to GPS seconds (handy for building queries). Args: iso_timestamp: e.g. ``2015-09-14T09:50:45`` (UTC assumed if no tz given).