GWCat demo

Summary: It doesn't work :'(

The data here is a compilation of data from the Gravitational Wave Open Science Centre and GraceDB. It is intended for public outreach purposes only. If you require the latest scientific data, then please use the source repositories.

More info

Download the catalogue data in JSON or CSV formats (parameter/columns definitions are here).
For other data files see:
- [all data (JSON)] (data/gwosc_gracedb.json) (includes parameter definitions and referece links)
- [all data (JSON, minified)] (data/gwosc_gracedb.min.json) (includes parameter definitions and reference links)
- [data values only (JSON)] (data/data.json)
- [Data parameters only (JSON)] (data/parameters.json)
- [References/links only (JSON)] (data/links.json)
- [data values (CSV)] (data/gwosc_gracedb.csv)
- [data parameters (CSV)] (data/parameters.csv)
- [References/links (CSV)] (data/links.csv)
See this page for localisation images
See this page for a catalog display
See this page for a display of waveforms

Initialisation

In the <head> of the page, include the gwcat library.


		<script type="text/javascript" src="js/gwcat.js"></script>

To initialise the database of events


		gwcat = new GWCat(callback, {parameters});

callback [function]: a javascript function to be run once data is loaded.
parameters [Object, optional]: a dictionary containing input parameters:
- debug: [boolean] set to print useful debugging scripts to the console (default=false)
- fileIn: [string] json file to load data from (default=https://data.cardiffgravity.org/gwcat-data/data/gwosc_gracedb.json)
- fileInJsonp: [string] jsonp file to load data from (default=https://data.cardiffgravity.org/gwcat-data/data/gwosc_gracedb.json)
- loadMethod: [string] set to 'json' or 'jsonp' to force method. Useful if using local version (default="", i.e. auto-detect)
- confirmedOnly: [boolean] only read in data for confirmed detection. i.e. use GWOSC, but not GraceDB (default=true))

The resulting object contains the following objects:

data: An array containing all the events, each one of which is a javascript object.
datadict: An object containing the metadata of all the parameter names, default precisions etc.
dataOrder: An array of the event names, showing the order of data.
links: An object containing links for the events in data. Each link contains a url, a descriptive text field, and a type field. links.all contains the list of all links.

Data format

The data array contains an object for each event. Each event has a set of parameters (M1, M2, Mchirp, UTC, etc.), within which is an object containing the relevant values.


	gwcat.data = [
		{
            "name": Event name,
            "meta": object containing metadata, such as source, date retrieved etc.
            "ref": Reference to paper (if applicable)
            "opendata": Reference to open-data source
			"Event1 Parameter1": {
				"Event1 Parameter1 Value1": string/number/array
			},
			"Event1 Parameter2": {
				"Event1 Parameter2 Value1": string/array/value
				"Event1 Parameter2 Value2": string/array/value
			},...
		},
		{
			"Event2 Parameter1":{
				"Event2 Parameter1 Value1": string/number/array
			},...
		},...
	]

The parameters are those recorded for each event. Note that not all are present for each event.

name: Event name (e.g. GW150914)
UTC: UTC time of detection (YYYY-MM-DDThh:mm:ss)
GPS: GPS time of detection
M1: Primary mass (Msun)
M2: Secondary mass (Msun)
Mchirp: Chirp mass (Msun)
Mtotal: Total mass (Msun)
Mfinal: Final mass (Msun)
Mratio: Mass ratio
chi: Effective inspiral spin
af: Final spin
DL: Luminosity distance (MPc)
z: Redshift
lpeak: Peak luminosity (10⁵⁶ erg s^-1)
Erad: Radiated energy (Msun c²)
FAR: False alarm rate (yr^-1)
deltaOmega: Sky localization area (deg²)
rho: Signal-to-noise ratio
objType: Type of object (BBH, BNS etc.), including the possible values for candidates.
net: Detector network that made the detection (e.g. HLV=Hanford, Livingston, Virgo; HV=Hanford, Virgo)
detType: Type of detection (GW / LVT / Candidate)

The values can be any of:

best: exact or best-fit value of parameter. Can be string (e.g. name, UTC), or number (e.g. masses, spins, GPS).
lower: a (numerical) lower limit on the parameter.
upper: a (numerical) upper limit on the parameter.
lim: a two-element array (of numberse) containing the range of plausible values (where applicable), in order [min, max]. Used where a best-fit value and corresponding error isn't appropriate.
err: a two-element array (of numberse) containing the errors on the "best" value (where applicable). Erros are lists as positive and negative. Only accompanies a "best" value.

Link format

The link object contains an object for each event, labelled by event name. A few links are specifically listed, where available, but most are in list.


	gwcat.links = [
		event1:{
            "Det Paper": Detection paper,
            "GWOSCData": Open-data on GWOSC or GraceDB
            "SkyMapFile": Localisation map
            "all": [
			          {Link 1 for event 1},
                {Link 2 for event 1},
                ...
			]
		},
        event2:{
            "Det Paper": Detection paper,
            "GWOSCData": Open-data on GWOSC or GraceDB
            "SkyMapFile": Localisation map
            "SkyMapPlots": Plots of skymaps
            "all": [
			          {Link 1 for event 2},
                {Link 2 for event 2},
                ...
			]
		},...
	]

Each link contains:

url: URL to reference
text: descriptive text field
type: type of reference (e.g. "pub", "open-data", "skymap-fits", "skymaps-plot")
files: list of files (optional)
- file: filename, designed to be appended to url to access file
- text: descriptive text field, designed replace text
citation: citation (optional; for papers only)

The skymaps available are:

type='skymaps-plot': plots of the sky localisation (Equatorial coordinates)
- file='moll': Mollweide view, with title, credit and constellations, centred on (0,0)
- file='moll_rot': Mollweide view, with title, credit and constellations, centred on peak likelihood
- file='moll_pretty': Mollweide view, without title or constellations, centred on (0,0)
- file='moll_pretty_black': Mollweide view, without title or constellations, with black background, centred on (0,0)
- file='cart': Cartesian view, with title, credit and constellations, centred on (0,0)
- file='cart_rot': Cartesian view, with title, credit and constellations, centred on peak likelihood
- file='cartzoom': Cartesian view, with title, credit and constellations, zoomed and centred on peak likelihood
- file='cartzoom_pretty': Cartesian view, without title, credit or border, zoomed and centred on peak likelihood
type='skymaps-thumb': smaller versions of the above
type='skymaps-plain': unannotated, black & white Cartesian maps of the sky localisation
- file='eq_8192': Equatorial coordinates, 8192x4096 image size
- file='gal_8192': Galactic coordinates, 8192x4096 image size
- file='gal_4096': Galactic coordinates, 4096x2048 image size

Built-in functions

A number of functions exist to allow access to the data.

getParamType(event, param): get the type of the value of parameter param [string] for event event (name [string] or index [integer]). Returns string of value type, or '' if not found.
hasError(event, param): returns whether the param [string] has an "err" value for event event (name [string] or index [integer]). Returns boolean (true|false), or false if not found.
getBest(event, param): gets "best" value for param [string] for event event (name [string] or index [integer]). Returns value, or NaN if not found.
getBestErr(event, param): gets "best" and "err" value for param [string] for event event (name [string] or index [integer]). Returns array of [best, err].
getLim(event, param): gets "lim" value for param [string] for event event (name [string] or index [integer]). Returns value, or empty array [] if not found.
getLower(event, param): gets "lower" value for param [string] for event event (name [string] or index [integer]). Returns value, or NaN if not found.
getUpper(event, param): gets "upper" value for param [string] for event event (name [string] or index [integer]). Returns value, or NaN if not found.
getError(event, param): gets "err" value for param [string] for event event (name [string] or index [integer]). Returns value, or empty array [] if not found.
getNegError(event, param): gets negative "err" value for param [string] for event event (name [string] or index [integer]). Returns value, or NaN if not found.
getNegError(event, param): gets positive "err" value for param [string] for event event (name [string] or index [integer]). Returns value, or NaN if not found.
getNominal(event, param): gets the nominal value for param [string] for event event (name [string] or index [integer]). Returns best, lower or upper value, or average of lim values.
getMinVal(event, param): gets the minimum value for param [string] for event event (name [string] or index [integer]). Returns "best"-"err[1]", "lower", lower "lim" values, or -Infinity for "upper" values
getMaxVal(event, param): gets the minimum value for param [string] for event event (name [string] or index [integer]). Returns "best"+"err[0]", "upper", higher "lim" values, or +Infinity for "lower" values
paramName(param): returns the name of param [string] as stored in datadict, or '' if not found.
paramUnit(param): returns the unit of param [string] as stored in datadict, or '' if not found.
getRef(event): returns the reference dict of event [string] as stored in datadict, or {} if not found. Result is a dict containing URL and name.
getOpenData(event): returns the data link of event [string] as stored in datadict, or {} if not found. Result is a dict containing URL and name.
orderData([order='GPS', reverse]): orders the data in data by parameter order (optional [string], default='GPS'). Set reverse (optional [boolean],default=false) to reverse order.
getLink(event, [lytpe='', [ltxt='',[lfile='']]]): returns list of links for event (name [string] or index [integer]) which have type parameter containing ltype ([string], ignored if set to '') and text parameter containing ltxt ([string], ignored if set to '').
- If lfile set, then if link contains files object, replaces url and text field for that file.
- Searching for type and text uses regex syntax, while file uses exact match. Returns list of link objects, or empty list if not found.
getSkymapPlot(event, file, [maptype='plot']): returns skymap file for event (name [string] or index [integer]) which hase file tag file.
- maptype is 'plot'|'thumb'|'plain' and sets whether to search skymaps-plot, skymaps-thumb or skymaps-plain. Default='plot'
getMeta(event, [meta-name='']): gets the metadata parameter meta-name ( optional [string]) for event (name [string] or index [integer]). If not meta-name is provided (or is empty string), then returns object containing full metadata for the event, or null if not available.

Example Tests

Check we can get the mass of the primary object. Note that getBest(event,param) is just an alias for getValue(event,param,'best')
gwcat.getBest("GW150914","M1") + " " + gwcat.paramUnit("M1") // Expect: 35.6 M_sun // Return: ERROR
Check we can get the mass of the primary object using the this object rather than a global variable. This will allow multiple catalogues to be loaded and a single callback function to process them as it doesn't need to know the name of the variable.
this.getBest("GW150914","M1") + " " + this.paramUnit("M1") // Expect: 35.6 M_sun // Return: ERROR
Get the upper limit on the primary mass. (noting floating-point precision problem)
gwcat.getMaxVal("GW150914","M1") + " " + gwcat.paramUnit("M1") // Expect: 40.300000000000004 M_sun // Return: ERROR
Get the final, combined, mass of the event.
gwcat.getBest("GW170817","Mfinal") + " " + gwcat.paramUnit("Mfinal") // Expect: 2.8 M_sun // Return: ERROR
gwcat.getParamType("GW170817","Mfinal") // Expect: best // Return: ERROR
Return a text description of the parameter.
gwcat.paramName("chi") // Expect: Effective inspiral spin // Return: ERROR
gwcat.paramUnit("lpeak") // Expect: 10^56 erg s^-1 // Return: ERROR
Get the URL of the open data
gwcat.getOpenData("GW150914")['url'] // Expect: https://gwosc.org/eventapi/html/GWTC-1-confident/GW150914/v3 // Return: ERROR
Get a link to the Cartesian zoomed skymap
gwcat.getSkymapPlot("GW170817","cartzoom")[0]['url'] // Expect: https://ligo.gravity.cf.ac.uk/~chris.north/gwcat-data/data/png/GW170817_cartzoom.png // Return: ERROR
Get a link to a plain skymap
gwcat.getSkymapPlot("GW150914","gal_8192",maptype='plain')[0]['url'] // Expect: https://ligo.gravity.cf.ac.uk/~chris.north/gwcat-data/data/gravoscope/GW150914_8192.png // Return: ERROR

Get the earliest gravitational wave. To do this we explicitly order the catalogue by the UTC of the event.

function earliestGW(){
        gwcat.orderData("UTC");
        return gwcat.data[0].name;
        }
        earliestGW();
// Expect: GW150914
// Return: ERROR

Get the most massive gravitational wave. To do this we explicitly order the catalogue by the primary mass, then find the first one with a value.

function mostMassiveGW(){
            gwcat.orderData("M1",true);
            for(d in gwcat.data){
                if (gwcat.getNominal(gwcat.data[d].name,"M1")){return(gwcat.data[d].name);};
            }
            return('none');
        }
        mostMassiveGW();
// Expect: GW190426_190642
// Return: ERROR