API documentation

API documentation#

Here we provide a brief overview of the nrsur_catalog python package API. Install the package with:

pip install nrsur_catalog

Note

This website has been generated with nrsur_catalog version 0.0.5.

For more details, see the docstrings of the individual classes and functions in the source code.

CLI to download results#

Download NRSur Catlog analysis results from Zenodo.

usage: get_nrsur_event [-h] [--event-name EVENT_NAME] [--cache-dir CACHE_DIR] [--all] [--clean]

Named Arguments#

--event-name

The name of the event to be downloaded (e.g. GW150914)

Default: “”

--cache-dir

The directory to save the NRSur Catlog event result files.

Default: “./.nrsur_catalog_cache”

--all

If all catalog results should be downloaded. Cannot be used with –event-name.

Default: False

--clean

If the result files need to be re-downloaded (if they already exist).

Default: False

Catalog#

class nrsur_catalog.catalog.Catalog(posteriors: DataFrame)#

get_all_posteriors() → DataFrame#

Return the dataframe of all the event posteriors concatenated together. The column ‘event’ denotes which ‘event’ the posterior sample belongs to.

pd.DataFrame: A dataframe of the all event’s posterior samples.

static get_analysed_event_names() → List[str]#

Return the list of the analysed events available in the NRSurrogate Catalog.

List[str]: List of the analysed event names.

get_event_posterior(event_name: str) → DataFrame#

Return a dataframe with the posterior for a given event.

event_name:str: The name of the event that will have its posterior returned.

pd.DataFrame: A dataframe of the event’s posterior samples

classmethod load(cache_dir: Optional[str] = './.nrsur_catalog_cache', max_samples: Optional[int] = 10000, clean: Optional[bool] = False) → Catalog#

Load all the catalog posterior samples and stores a cache of the down-sampled posteriors.

cache_dir: Optional[str]: The cache-dir where the NRSurrogate results will be loaded from. If empty, downloads all the NRSurrogate results.
max_samples: Optional[int]: The max number of samples to include from each event’s posterior.
clean: Optional[bool]: Recomputes the cache of the downsampled-posteriors.

plot_2d_posterior(parm_x: str, parm_y: str, scatter_medians: Optional[bool] = True, event_posteriors: Optional[bool] = False, event_quantiles: Optional[bool] = True, contour_all_posterior_samples: Optional[bool] = True, colors: Optional[Union[str, List[str]]] = 'tab:orange') → Figure#

Plot a 2D posterior for all events in the catalog

parm_x:str: The parameter plotted along the x-axis (e.g. mass_1, chi_eff…)
parm_y:str: The parameter plotted along the y-axis (e.g. mass_1, chi_eff…)
scatter_medians:Optional[bool]=True: Scatter median values of each event.
event_posteriors:Optional[bool]=False: Outline the event posterior.
event_quantiles:Optional[bool]=True: Plot the 68% CI quantiles of each event’s posterior.
contour_all_posterior_samples:Optional[bool]=True: Plot contours around all the posterior samples (regardless of which event each sample belongs to)
colors:Optional[Union[str, List[str]]]: The color to be used for each event. If a string, the same color will be used for each event.

plt.Figure: A matplotlib figure with the plot.

to_dict_of_posteriors(parameters: Optional[List[str]] = None) → Dict[str, DataFrame]#

Return a dictionary of event:posteriors.

parameters: Optional[List[str]]: List of the parameters to include in the posterior.

Dict[str:pd.DataFrame]: Returns a dictionary of {events: event_posteriors}.

violin_plot(parameter: str, sort_by='event_name') → Figure#

Generate a violin plot of a parameter.

parameter: str: The parameter to plot.
sort_by: str: Either ‘median’ or ‘event_name’. If ‘median’, the events will be sorted by the median value of the parameter. If ‘event_name’, the events will be sorted chronologically by their name.

NRSurrogate Result#

The NRSurrogate result class inherits the bilby.gw.result.CBCResult class. It has some additional functionality to load the NRSurrogate result from the h5 format into a python object, and some additional plotting functionality.

class nrsur_catalog.nrsur_result.NRsurResult(*args, **kwargs)#

Class to interface with a result of a NRSur Catalog analysis.

classmethod load(event_name: str, cache_dir: Optional[str] = './.nrsur_catalog_cache', event_path: Optional[str] = None) → NRsurResult#

Load a result (either by downloading or from a local dir).

event_name: str: The name of the event to load (list all available events with `nrsur_catalog.catalog.Catalog.
cache_dir: Optional[str]: The credible level to use in the plot (default 0.9)
event_path: Optional[str] = None: The path to the NRSur result file to load.

NRsurResult: loaded result object.

property lvk_result: CompactBinaryCoalescenceResult#: The event’s corresponding LVK result (from the GWTC).

plot_corner(parameters: Optional[List[str]] = None, priors: Optional[bool] = None, titles: Optional[List[str]] = True, save: Optional[bool] = False, filename: Optional[str] = None, dpi: Optional[int] = 300, **kwargs) → Optional[Figure]#

Plot a corner-plot

parameters: (list, dict), optional: If given, either a list of the parameter names to include, or a dictionary of parameter names and their “true” values to plot.
priors: {bool (False), bilby.core.prior.PriorDict}: If true, add the stored prior probability density functions to the one-dimensional marginal distributions. If instead a PriorDict is provided, this will be plotted.
titles: bool: If true, add 1D titles of the median and (by default 1-sigma) error bars. To change the error bars, pass in the quantiles kwarg. See method get_one_dimensional_median_and_error_bar for further details). If quantiles=None is passed in, no title is added.
save: bool, optional: If true, save the image using the given label and outdir
filename: str, optional: If given, overwrite the default filename
dpi: int, optional: Dots per inch resolution of the plot
**kwargs:: Other keyword arguments are passed to corner.corner. We set some defaults to improve the basic look and feel, but these can all be overridden. Also optional an ‘outdir’ argument which can be used to override the outdir set by the absolute path of the result object.

The generation of the corner plot themselves is done by the corner python module, see https://corner.readthedocs.io for more information.

Truth-lines can be passed in in several ways. Either as the values of the parameters dict, or a list via the truths kwarg. If injection_parameters where given to run_sampler, these will auto- matically be added to the plot. This behaviour can be stopped by adding truths=False.

fig:: A matplotlib figure instance

plot_lvk_comparison_corner(parameters: List[str], **kwargs)#: Plot a corner plot comparing the posterior to the LVK catalog.

property posterior#: A pandas data frame of the posterior