BOWIE: Binary Observability With Illustrative Exploration

alternate text

BOWIE is a tool designed for graphical analysis of binary signals from gravitational waves. It takes gridded data sets and produces different types of plots in customized arrangements for detailed analysis of gravitational wave sensitivity curves and/or binary signals. The paper detailing this tool and examples of its usage can be found at arXiv:1807.02511 (Evaluating Black Hole Detectability with LISA). There are three main portions of the code: a gridded data generator (snr_calculator.generate_contour_data.py), a plotting tool (bowie.make_plot.py), and waveform generator for general use (snr_calculator.utils.pyphenomd.py). The waveform generator creates PhenomD waveforms for binary black hole inspiral, merger, and ringdown. PhenomD is from Husa et al 2016 (arXiv:1508.07250) and Khan et al 2016 (arXiv:1508.07253). Gridded data sets are created using the PhenomD generator for signal-to-noise (SNR) analysis. Using the gridded data sets, customized configurations of plots are created with the plotting package.

The three plots to choose from are Waterfall, Ratio, and Horizon. A Waterfall plot is a filled contour plot similar to figure 3 in the LISA Mission Proposal (arxiv:1702.00786). Ratio plots show the ratio of SNRs between two different binary and sensitivity configurations. They also include loss/gain contours showing where two configurations differ in terms of the sources they can and cannot detect. Horizon plots show line contours of multiple configurations for a given SNR value. See the original paper and notebook examples for more information.

Note: The remainder of this introduction specifically details installation of the plotting module. It is very adaptable to different gravitational wave sources or other measurements with similar signal-to-noise properties. The snr_calculator package is listed as a requirement for BOWIE (meaning the plotting module). This package is installed with the bowie install, however, it is available separately from the plotting module. For this purpose, it has its own README and documentation here.

Getting Started

These instructions will get you a copy of the project up and running on your local machine for usage and testing purposes.

Available via pip and on github: https://github.com/mikekatz04/BOWIE

Prerequisites

It is best to run out of conda environment. It will handle the dependencies better. If you have issues with certain modules, try to update them.

Software installation/usage only requires a few specific libraries in python. If you install with pip, all of these libraries should be automatically installed if you do not have them (this includes snr_calculator, which is required). All python libraries are included with Anaconda. If you do not run python in an anaconda environment, you will need the following libraries and modules to run with all capabilities: Numpy, Scipy, collections, sys, json, multiprocessing, datetime, time, astropy, h5py, and matplotlib. All can be installed with pip. For example, within your python environment of choice:

pip install h5py

In order to properly create waveforms with ctypes, you will need complex, gsl, and math c libraries. For installing gsl, refer to https://www.gnu.org/software/gsl/ or install it through anaconda.

gwsnrcalc is also required. This will install automatically with pip install or setup.py.

Installation

Begin with updating conda:

conda update conda

Create a conda environment (change the name as desired. Default: bowie_env):

conda create -n bowie_env numpy scipy astropy h5py gsl matplotlib jupyter ipython python=3.7

Installation is done two ways:

  1. using pip

pip install bowie

This will download all necessary packages to your current environment. It will not download the notebooks for testing and example usage.

  1. Clone the git repo on the command line, or download it from github. This is for all the modules, example jupyter notebooks, and extra files.

  1. navigate to the directory of your choice.

  2. clone the git repo on the command line.

git clone https://github.com/mikekatz04/BOWIE.git

  1. pip install the local files to add the modules to your environment and compile the c codes.

pip install ./BOWIE/

Testing and Running an Example

To test the codes, you run the testing notebook.

jupyter notebook quick_testing_example.ipynb

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us.

Versioning

Current version is 2.0.0.

We use SemVer for versioning.

Authors

Please email the author with any bugs or requests.

License

This project is licensed under the GNU License - see the LICENSE.md file for details.

Acknowledgments

  • Thanks to Michael Puerrer, Sebastian Khan, Frank Ohme, Ofek Birnholtz, Lionel London for authorship of the original c code for PhenomD within LALsuite.

bowie package documentation:

User interfacing modules:

make_plot module

make_plot turns gridded datasets into helpful plots. It is designed for LISA Signal-to-Noise (SNR) comparisons across sennsitivity curves and parameters, but is flexible to other needs. It is part of the BOWIE analysis tool. Author: Michael Katz.

Please cite “Evaluating Black Hole Detectability with LISA” (arXiv:1807.02511) for usage of this code.

This code is licensed under the GNU public license.

TThe plotting classes are also importable for customization. See BOWIE_basic_examples.ipynb for examples on how to use this code. See paper_plots.ipynb for the plots shown in the paper.

The three main classes are plot types: Waterfall, Horizon, and Ratio.

Waterfall:

SNR contour plot based on plots from LISA Mission proposal.

Ratio:

Comparison plot of the ratio of SNRs for two different inputs. This plot also contains Loss/Gain contours, which describe when sources are gained or lost compared to one another based on a user specified SNR cut. See paper above for further explanation.

Horizon:

SNR contour plots comparing multipile inputs. User can specify contour value. The default is the user specified SNR cut.

bowie.make_plot.plot_main(pid, return_fig_ax=False)

Main function for creating these plots.

Reads in plot info dict from json file or dictionary in script.

Parameters

return_fig_ax (bool, optional) – Return figure and axes objects.

Returns

2-element tuple containing

  • fig (obj): Figure object for customization outside of those in this program.

  • ax (obj): Axes object for customization outside of those in this program.

forminput module

Documentation is provided for creating the main input dictionary for make_plot.py. A dictionary is passed into the main function of the code, providing the preferences of the user. A dictionary in python is contained within {} (see 5.5 Dictionaries at https://docs.python.org/3/tutorial/datastructures.html).

This documentation will direct the user to all choices related to this dictionary included required and optional parameters.

These dictionaries can be used in a python code or jupyter notebook by importing the main functions from each script. They can also be implemented with .json files similar to those included in the repository. If .json is used, the function call is python make_plot.py make_plot_config.json.

This code is part of the BOWIE analysis tool. Author: Michael Katz. Please see “Evaluating Black Hole Detectability with LISA” (arXiv:1807.02511) for example usage. Please cite arXiv:1807.02511 for its usage.

This code is shared under the GNU Public License.

NOTE: This code associates classes with a name (e.g. Label) and a Container

class for storing its information (e.g. LabelContainer). This is due to the need to inherit methods in a separate way from where the information is actually stored.

Therefore, when reading the documentation, the main classes (without Container) will describe the methods for adding information for plotting. This includes required values and default values for optional Args related to the methods themselves and not the defaults and required values within the actual plotting module code.

The Container classes have descriptions of their attributes. Their attributes involve the same requirements and default/optional Args as the plotting code itself.

class bowie.plotutils.forminput.DataImport

Bases: object

DataImport contains the methods inherited by SinglePlot.

These methods are used by SinglePlot class to add data for each plot. This class allows for file import as well as indexing to files that have already been imported.

add_dataset(name=None, label=None, x_column_label=None, y_column_label=None, index=None, control=False)

Add a dataset to a specific plot.

This method adds a dataset to a plot. Its functional use is imperative to the plot generation. It handles adding new files as well as indexing to files that are added to other plots.

All Args default to None. However, these are note the defaults in the code. See DataImportContainer attributes for defaults in code.

Parameters

  • name (str, optional) – Name (path) for file. Required if reading from a file (at least one). Required if file_name is not in “general”. Must be “.txt” or “.hdf5”. Can include path from working directory.

  • label (str, optional) – Column label in the dataset corresponding to desired SNR value. Required if reading from a file (at least one).

  • x_column_label/y_column_label (str, optional) – Column label from input file identifying x/y values. This can override setting in “general”. Default is x/y.

  • index (int, optional) – Index of plot with preloaded data. Required if not loading a file.

  • control (bool, optional) – If True, this dataset is set to the control. This is needed for Ratio plots. It sets the baseline. Default is False.

Raises

ValueError – If no options are passes. This means no file indication nor index.

class bowie.plotutils.forminput.DataImportContainer

Bases: object

Holds all of the attributes related to a dataset.

This class holds file information for each file imported as an added dataset. It does not take index information, which is added to the GeneralContainer class.

The attributes associated with DataImportContainer can override GeneralContainer values. However, the GeneralContainer is used to set these values if it applies to all or most of the plots.

file_name

Name (path) for file. Required if reading from a file (at least one). Required if file_name is not in “general”. Must be “.txt” or “.hdf5”. Can include path from working directory.

Type

str, optional

label

Column label in the dataset corresponding to desired SNR value. Required if reading from a file (at least one).

Type

str, optional

x_column_label/y_column_label

Column label from input file identifying x/y values. This can override setting in “general”. Default is x/y.

Type

str, optional

class bowie.plotutils.forminput.Extra

Bases: object

Extra contains the methods inherited by SinglePlot.

These methods are used by SinglePlot class to add configuration information pertaining to the extra dict involved in plot creation.

All attributes are appended to the ExtraContainer class. The ExtraContainer class is contained in the extra attribute in the SinglePlot class.

The associated methods in Extra class as well as the attributes in the ExtraContainer class detail the options related to extra customization of plots.

grid(grid=True)

Add gridlines to plot.

Adds gridlines for specific plot.

Parameters

grid (bool, optional) – If True, add grid to specific plot. Default is True.

ratio_comp_value(val)

Change the comparison value limit for Ratio plots.

The ratio plots are only shown when both configurations are above a detectable limit set by SNR_CUT. This function will override that value.

Parameters

val (float) – Sets minimum snr where Ratio contours are shown.

set_contour_vals(vals)

Set contour values related to Waterfall plots.

Customize contour values related to Waterfall plots. This functionality may be added to the other plots in the future, but, so far, it seems as if that is not needed.

Parameters

vals (list of floats) – Set contour values to this list. Default is [0.,10,20,50,100,200,500,1000,3000,1e10].

set_order_contour_lines(lines=True)

Toggle showing order of magnitude lines in Ratio plots.

This will show dashed lines for each order of magnitude contour in Ratio plots.

Parameters

lines (bool, optional) – Add order of magnitude contour lines to Ratio plots. Default is True. Specifically, when calling this function, the default is True because the assumption is that the user desires these lines if they call this function. Without calling this function, the default is False.

set_snr_contour_value(val)

Set snr value for which singular contours are shown.

Set a specific contour value to plot. In Waterfall plots this will add a line contour in white. For Horizon and Ratio plots, this value will override the SNR_CUT option and use this value.

Parameters

val (float) – Set snr contour value specific to each style of plot. See above.

show_loss_gain(show=True)

Toggle showing loss/gain plots.

This will keep or remove the loss/gain plots when viewing a ratio plot.

Parameters

show (bool, optional) – If True, keep loss/gain. Default is True.

class bowie.plotutils.forminput.ExtraContainer

Bases: object

Holds all of the attributes related to the extra dictionary.

This class is used to store the information when methods from Extra class are called by the SinglePlot class.

add_grid

Adds gridlines to plots. Overrides setting from “general”. Default is True.

Type

bool, optional

contour_vals

Provides contour values for Waterfall plot only. Default is [0.,10,20,50,100,200,500,1000,3000,1e10].

Type

list of floats, optional

snr_contour_value

Adds contour for a specific value for Waterfall plot. Color is white. For Ratio and Horizon plots, this overrides the SNR_CUT for a custom value.

Type

float, optional

order_contour_lines

This only applies to ratio plots. This will show contour lines at each order of magnitude ratio. Default is False.

Type

bool, optional

show_loss_gain

Toggle loss/gain contours on and off. Only applies to Ratio plots. Default is True.

Type

bool, optional

ratio_comp_value

This sets the minimum SNR necessary for both configurationsin a ratio plot to show the ratio contours. (rho_1>ratio_comp_value & rho_2>ratio_comp_value) in order to display the contour. Default is same value as loss/gain contour (which defaults to SNR_CUT).

Type

float, optional

class bowie.plotutils.forminput.Figure

Bases: object

savefig(output_path, **kwargs)

Save figure during generation.

This method is used to save a completed figure during the main function run. It represents a call to matplotlib.pyplot.fig.savefig.

# TODO: Switch to kwargs for matplotlib.pyplot.savefig

Parameters

output_path (str) – Relative path to the WORKING_DIRECTORY to save the figure.

Keyword Arguments
set_colorbar(plot_type, **kwargs)

Setup colorbar for specific type of plot.

Specify a plot type to customize its corresponding colorbar in the figure.

See the ColorbarContainer class attributes for more specific explanations.

Parameters

  • plot_type (str) – Type of plot to adjust. e.g. Ratio

  • label (str, optional) – Label for colorbar. Default is None.

  • label_fontsize (int, optional) – Fontsize for colorbar label. Default is None.

  • ticks_fontsize (int, optional) – Fontsize for colorbar tick labels. Default is None.

  • pos (int, optional) – Set a position for colorbar based on defaults. Default is None.

  • colorbar_axes (len-4 list of floats) – List for custom axes placement of the colorbar. See fig.add_axes from matplotlib. url: https://matplotlib.org/2.0.0/api/figure_api.html

Raises

UserWarning – User calls set_colorbar without supplying any Args. This will not stop the code.

set_fig_size(width, height=None)

Set the figure size in inches.

Sets the figure size with a call to fig.set_size_inches. Default in code is 8 inches for each.

Parameters

  • width (float) – Dimensions for figure width in inches.

  • height (float, optional) – Dimensions for figure height in inches. Default is None.

set_fig_title(title, **kwargs)

Set overall figure title.

Set title for overall figure. This is not for a specific plot. It will place the title at the top of the figure with a call to fig.suptitle.

Parameters

title (str) – Figure title.

Keywork Arguments:
x/y (float, optional): The x/y location of the text in figure coordinates.

Defaults are 0.5 for x and 0.98 for y.

horizontalalignment/ha (str, optional): The horizontal alignment of

the text relative to (x, y). Optionas are ‘center’, ‘left’, or ‘right’. Default is ‘center’.

verticalalignment/va (str, optional): The vertical alignment of the text

relative to (x, y). Optionas are ‘top’, ‘center’, ‘bottom’, or ‘baseline’. Default is ‘top’.

fontsize/size (int, optional): The font size of the text. Default is 20.

set_fig_x_label(xlabel, **kwargs)

Set overall figure x.

Set label for x axis on overall figure. This is not for a specific plot. It will place the label on the figure at the left with a call to fig.text.

Parameters

xlabel (str) – xlabel for entire figure.

Keyword Arguments

  • x/y (float, optional) – The x/y location of the text in figure coordinates. Defaults are 0.01 for x and 0.51 for y.

  • horizontalalignment/ha (str, optional) – The horizontal alignment of the text relative to (x, y). Optionas are ‘center’, ‘left’, or ‘right’. Default is ‘center’.

  • verticalalignment/va (str, optional) – The vertical alignment of the text relative to (x, y). Optionas are ‘top’, ‘center’, ‘bottom’, or ‘baseline’. Default is ‘center’.

  • fontsize/size (int) – The font size of the text. Default is 20.

  • rotation (float or str) – Rotation of label. Options are angle in degrees, horizontal, or vertical. Default is vertical.

  • Note – Other kwargs are available. See https://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.figtext

set_fig_y_label(ylabel, **kwargs)

Set overall figure y.

Set label for y axis on overall figure. This is not for a specific plot. It will place the label on the figure at the left with a call to fig.text.

Parameters

ylabel (str) – ylabel for entire figure.

Keyword Arguments

  • x/y (float, optional) – The x/y location of the text in figure coordinates. Defaults are 0.45 for x and 0.02 for y.

  • horizontalalignment/ha (str, optional) – The horizontal alignment of the text relative to (x, y). Optionas are ‘center’, ‘left’, or ‘right’. Default is ‘center’.

  • verticalalignment/va (str, optional) – The vertical alignment of the text relative to (x, y). Optionas are ‘top’, ‘center’, ‘bottom’, or ‘baseline’. Default is ‘top’.

  • fontsize/size (int) – The font size of the text. Default is 20.

  • rotation (float or str) – Rotation of label. Options are angle in degrees, horizontal, or vertical. Default is horizontal.

  • Note – Other kwargs are available. See https://matplotlib.org/api/pyplot_api.html#matplotlib.pyplot.figtext

set_spacing(space)

Set the figure spacing.

Sets whether in general there is space between subplots. If all axes are shared, this can be tight. Default in code is wide.

The main difference is the tick labels extend to the ends if space==`wide`. If space==`tight`, the edge tick labels are cut off for clearity.

Parameters

space (str) – Sets spacing for subplots. Either wide or tight.

show()

Show figure after generation.

This method is used to show a completed figure after the main function run. It represents a call to matplotlib.pyplot.show.

subplots_adjust(**kwargs)

Adjust subplot spacing and dimensions.

Adjust bottom, top, right, left, width in between plots, and height in between plots with a call to plt.subplots_adjust.

See https://matplotlib.org/api/_as_gen/matplotlib.pyplot.subplots_adjust.html for more information.

Keyword Arguments

  • bottom (float, optional) – Sets position of bottom of subplots in figure coordinates. Default is 0.1.

  • top (float, optional) – Sets position of top of subplots in figure coordinates. Default is 0.85.

  • left (float, optional) – Sets position of left edge of subplots in figure coordinates. Default is 0.12.

  • right (float, optional) – Sets position of right edge of subplots in figure coordinates. Default is 0.79.

  • wspace (float, optional) – The amount of width reserved for space between subplots, It is expressed as a fraction of the average axis width. Default is 0.3.

  • hspace (float, optional) – The amount of height reserved for space between subplots, It is expressed as a fraction of the average axis width. Default is 0.3.

class bowie.plotutils.forminput.FigureContainer

Bases: object

Holds all of the attributes related to the figure dictionary.

This class is used to store the information when methods from Figure class are called by the MainContainer class.

show_figure

Use plt.show() function from matplotlib to show plot. Do not use this in Jupyter Notebook. Use the magic command: %matplotlib inline. Default is False.

Type

bool, optional

save_figure

Use fig.savefig() function from matplotlib to save figure. Default is False.

Type

bool, optional

output_path

Path from the working directory to save the figure, including file name and extension. Required if save_figure == True.

Type

str, optional

savefig_kwargs

Additional kwargs for fig.savefig().

Type

dict, optional

subplots_adjust_kwargs

Kwargs for sizing with plt.subplots_adjust().

Type

dict, optional

spacing

This sets the general spacing of the plot configuration. Choices are wide or tight (hspace = wspace = 0.0). Tight spacing will cut off the outer labels on each axis due to axes contacting each other. Default is wide.

Type

str, optional

fig_x_label/fig_y_label

Overall figure label on the left and bottom. Called with fig.text() from matplotlib.

Type

str, optional

fig_x_label_kwargs, fig_y_label_kwargs

Kwargs for fig.text().

Type

dict, optional

fig_title

Overall figure title. Produced with fig.suptitle() from matplotlib.

Type

str, optional

fig_title_kwargs

Kwargs for fig.suptitle`.

Type

dict, optional

figure_width/figure_height

Dimensions of the figure set with

Type

float, optional

``fig.set_size_inches()`` from matplotlib. Default is 8.0 for each.
colorbars

ColorbarContainer object carrying information for the colorbars.

Type

obj

class bowie.plotutils.forminput.General

Bases: object

General contains the methods inherited by MainContainer.

These methods are used by MainContainer class to add information that applies to all plots. Many of its settings pertaining to plots can be overriden with methods in SinglePlot.

reverse_axis(axis_to_reverse)

Reverse an axis in all figure plots.

This will reverse the tick marks on an axis for each plot in the figure. It can be overridden in SinglePlot class.

Parameters

axis_to_reverse (str) – Axis to reverse. Supports x and y.

Raises

ValueError – The string representing the axis to reverse is not x or y.

set_all_file_column_labels(xlabel=None, ylabel=None)

Indicate general x,y column labels.

This sets the general x and y column labels into data files for all plots. It can be overridden for specific plots.

Parameters

xlabel/ylabel (str, optional) – String indicating column label for x,y values into the data files. Default is None.

Raises

UserWarning – If xlabel and ylabel are both not specified, The user will be alerted, but the code will not stop.

set_all_file_name(name)

Add general file name.

This sets the file name for all the plots. This can be overriden by specific plots.

Parameters

name (str) – String indicating the relative path to the file.

set_all_ticklabel_fontsize(fontsize)

Set tick label fontsize for both axis in entire figure.

This will set x and y axis tick label fontsize for the entire figure. It can be overridden in the SinglePlot class.

Parameters

fontsize (int) – Set fontsize for x and y axis tick marks.

set_all_xlims(xlim, dx, xscale, fontsize=None)

Set limits and ticks for x axis for whole figure.

This will set x axis limits and tick marks for the entire figure. It can be overridden in the SinglePlot class.

Parameters

  • xlim (len-2 list of floats) – The limits for the axis.

  • dx (float) – Amount to increment by between the limits.

  • xscale (str) – Scale of the axis. Either log or lin.

  • fontsize (int, optional) – Set fontsize for x axis tick marks. Default is None.

set_all_ylims(ylim, dy, yscale, fontsize=None)

Set limits and ticks for y axis for whole figure.

This will set y axis limits and tick marks for the entire figure. It can be overridden in the SinglePlot class.

Parameters

  • ylim (len-2 list of floats) – The limits for the axis.

  • dy (float) – Amount to increment by between the limits.

  • yscale (str) – Scale of the axis. Either log or lin.

  • fontsize (int, optional) – Set fontsize for y axis tick marks. Default is None.

set_grid(grid=True)

Add gridlines to all plots in figure.

Adds gridlines for all plots in figure. Can be overridden with SinglePlot class.

Parameters

grid (bool, optional) – If True, add grid to specific plot. Default is True.

set_snr_cut(cut_val)

Set the SNR_CUT value.

Sets the SNR cut value for detectability. In code, it defaults to 5. This can also be viewed as the contour value desired if it is not a cut.

Parameters

cut_val (float) – Sets SNR_CUT variable.

set_working_directory(wd)

Set the WORKING_DIRECTORY variable.

Sets the WORKING_DIRECTORY. The code will then use all paths as relative paths to the WORKING_DIRECTORY. In code default is current directory.

Parameters

wd (str) – Absolute or relative path to working directory.

switch_backend(string='agg')

Switch the matplotlib backend.

Changes the backend for matplotlib. See https://matplotlib.org/faq/usage_faq.html for more infomation. This is specifcally important if generating plots in parallel or on devices without a graphical user interface.

Parameters

string (str, optional) – String indicating the new backend. Default is agg.

class bowie.plotutils.forminput.GeneralContainer(nrows, ncols, sharex=True, sharey=True)

Bases: object

Holds all of the attributes related to the general dictionary.

This class is used to store the information when methods from General class are called by the MainContainer class.

Parameters
num_rows, num_cols

Number of rows/columns of plots present in the figure.

Type

int

xlims/ylims

Sets the x,y limits of the plots. Can be overridden for specific plots. If xscale/yscale == log, the xlims/ylims must be log10 of the actual desired values. Ex. for 1e4 to 1e8, xlims would be [4.0, 8.0]. Required if xlims/ylims are not specified for every specific plot.

Type

len-2 list of floats

dx, dy

Spacing of x and y ticks. If xscale/yscale == log, the dx/dy is a log10 value. See examples. Required if limits are not set for each specific plot.

Type

float

xscale/yscale

Choices are lin for linear spacing or log for log (base 10) spacing. Default is lin.

Type

str, optional

tick_label_fontsize

Sets fontsize for both x and y tick labels on the plots. This can be overridden for individual plots. Default is 14.

Type

float, optional

x_tick_label_fontsize/y_tick_label_fontsize

Sets fontsize fot x/y tick labels. This overrides tick_label_fontsize and can be overridden for specific plots. Default is 14.

Type

float, optional

WORKING_DIRECTORY

Working directory for file export and retrieval. Default is '.'.

Type

str, optional

SNR_CUT

The SNR cut for a detectable signal. Usually between 1-10. Default is 5.0.

Type

float, optional

switch_backend

Use for switching backend of matplotlib. Use if running codes in parallel. Typical string value is “agg”.

Type

str, optional

file_name

File name for input SNR grids. Can be overridden by specific plot. Required if no file names are given in “plot_info” dictionaries.

Type

str, optional

x_column_label/y_column_label

Column label from input file identifying x/y values. This can be overrided in the file_dicts for specific files. Default is x/y.

Type

str, optional

sharex, sharey

Applies sharex, sharey as used in plt.subplots(). See https://matplotlib.org/api/_as_gen/matplotlib.pyplot.subplots.html Default is True.

Type

bool, optional

add_grid

Adds gridlines to all plots. Can be overridden for specific plots. Default is True.

Type

bool, optional

reverse_x_axis, reverse_y_axis

Reverses the tick marks on the x/y axis. Can be overridden for specific plots. Default is False.

Type

bool, optional

class bowie.plotutils.forminput.Label

Bases: object

Label contains the methods inherited by SinglePlot.

These methods are used by SinglePlot class to add configuration information pertaining to the labels dict involved in plot creation.

All attributes are appended to the LabelContainer class. The LabelContainer class is contained in the label attribute in the SinglePlot class.

set_tick_label_fontsize(fontsize)

Set x_tick_label_fontsize and y_tick_label_fontsize for plot.

This will set the tick label fontsize for both the x and y axes for the specific plot.

Parameters

fontsize (int) – Fontsize for x and y axes tick labels.

set_title(title, **kwargs)

Set title for plot.

Similar to matplotlib, this will set the title for the specific plot.

Parameters

title (str) – The title to be added.

Keyword Arguments
set_x_tick_label_fontsize(fontsize)

Set x_tick_label_fontsize for plot.

This will set the tick label fontsize for the x axis for the specific plot. This will override a call to set_tick_label_fontsize.

Parameters

fontsize (int) – Fontsize for x axis tick labels.

set_xlabel(label, **kwargs)

Set xlabel for plot.

Similar to matplotlib, this will set the xlabel for the specific plot.

Parameters

label (str) – The label to be added.

Keyword Arguments
set_y_tick_label_fontsize(fontsize)

Set y_tick_label_fontsize for plot.

This will set the tick label fontsize for the y axis for the specific plot. This will override a call to set_tick_label_fontsize.

Parameters

fontsize (int) – Fontsize for y axis tick labels.

set_ylabel(label, **kwargs)

Set ylabel for plot.

Similar to matplotlib, this will set the ylabel for the specific plot.

Parameters

label (str) – The label to be added.

Keyword Arguments
class bowie.plotutils.forminput.LabelContainer

Bases: object

Holds all of the attributes related to the label dictionary.

This class is used to store the information when methods from Label class are called by the SinglePlot class.

xlabel/ylabel

x,y label for specific plot.

Type

str, optional

title

Title for specific plot.

Type

str, optional

xlabel_fontsize/ylabel_fontsize

Sets fontsize for x,y label for specific plot. Default is 20.

Type

float, optional

title_fontsize

Sets fontsize for y label for specific plot. Default is 20.

Type

float, optional

x_tick_label_fontsize/y_tick_label_fontsize

Sets fontsize for x,y tick labels for specific plot. Default is 14.

Type

float, optional

class bowie.plotutils.forminput.Legend

Bases: object

Legend contains the methods inherited by SinglePlot.

These methods are used by SinglePlot class to add configuration information pertaining to the legend dict involved in plot creation.

All attributes are appended to the LegendContainer class. The LegendContainer class is contained in the legend attribute in the SinglePlot class.

add_legend(labels=None, **kwargs)

Specify legend for a plot.

Adds labels and basic legend specifications for specific plot.

For the optional Args, refer to https://matplotlib.org/api/_as_gen/matplotlib.pyplot.legend.html for more information.

# TODO: Add legend capabilities for Loss/Gain plots. This is possible

using the return_fig_ax kwarg in the main plotting function.

Parameters

labels (list of str) – String representing each item in plot that will be added to the legend.

Keyword Arguments

  • loc (str, int, len-2 list of floats, optional) – Location of legend. See matplotlib documentation for more detail. Default is None.

  • bbox_to_anchor (2-tuple or 4-tuple of floats, optional) – Specify position and size of legend box. 2-tuple will specify (x,y) coordinate of part of box specified with loc kwarg. 4-tuple will specify (x, y, width, height). See matplotlib documentation for more detail. Default is None.

  • size (float, optional) – Set size of legend using call to prop dict in legend call. See matplotlib documentaiton for more detail. Default is None.

  • ncol (int, optional) – Number of columns in the legend.

  • Note – Other kwargs are available. See: https://matplotlib.org/api/_as_gen/matplotlib.pyplot.legend.html

class bowie.plotutils.forminput.LegendContainer

Bases: object

Holds all of the attributes related to the add_legend dictionary.

This class is used to store the information when methods from Legend class are called by the SinglePlot class.

labels

String representing each item in plot that will be added to the legend.

Type

list of str

legend_kwargs

Stores kwargs for ax.legend().

Type

dict

class bowie.plotutils.forminput.Limits

Bases: object

Limits contains the methods inherited by SinglePlot.

These methods are used by SinglePlot class to add configuration information pertaining to the limits dict involved in plot creation.

All attributes are appended to the LimitsContainer class. The LimitsContainer class is contained in the limits attribute in the SinglePlot class.

set_xlim(xlims, dx, xscale, reverse=False)

Set x limits for plot.

This will set the limits for the x axis for the specific plot.

Parameters

  • xlims (len-2 list of floats) – The limits for the axis.

  • dx (float) – Amount to increment by between the limits.

  • xscale (str) – Scale of the axis. Either log or lin.

  • reverse (bool, optional) – If True, reverse the axis tick marks. Default is False.

set_ylim(xlims, dx, xscale, reverse=False)

Set y limits for plot.

This will set the limits for the y axis for the specific plot.

Parameters

  • ylims (len-2 list of floats) – The limits for the axis.

  • dy (float) – Amount to increment by between the limits.

  • yscale (str) – Scale of the axis. Either log or lin.

  • reverse (bool, optional) – If True, reverse the axis tick marks. Default is False.

class bowie.plotutils.forminput.LimitsContainer

Bases: object

Holds all of the attributes related to the limits dictionary.

This class is used to store the information when methods from Limits class are called by the SinglePlot class.

xlims,ylims

REQUIRED. x,y limits for specific plot. If xscale,yscale == log, the xlims/ylims must be log10 of the actual desired values. Ex. for 1e4 to 1e8, xlims would be [4.0, 8.0].

Type

len-2 list of floats

dx,dy

Required. Spacing of x and y ticks. If xscale,yscale == log, then dx,dy is a log10 value. See examples.

Type

float

xscale,yscale

Choices are lin for linear spacing or log for log (base 10) spacing. Default is lin.

Type

str

reverse_x_axis,reverse_y_axis

Reverses the tick marks on the x,y axis. Default is False.

Type

bool, optional

class bowie.plotutils.forminput.MainContainer(nrows, ncols, sharex=True, sharey=True, print_input=False)

Bases: bowie.plotutils.forminput.General, bowie.plotutils.forminput.Figure

Main class for creating input dictionary to make_plot.py.

This class creates a pythonic way to add information to the input dictionary to make_plot.py. It creates and can read out this dictionary.

MainContainer inherits methods from General class so that it can add general dictionary information to GeneralContainer class

The __init__ function is similar to a call to plt.subplots().

# TODO: make default on sharing to False?

Parameters

  • nrows/ncols (int) – Number of rows/columns of plots present in the figure. This is passed into the general dictionary. These determine the number of plots to create.

  • sharex/sharey (bool, optional) – Applies sharex, sharey as used in plt.subplots(). See https://matplotlib.org/api/_as_gen/matplotlib.pyplot.subplots.html Default is True.

  • print_input (bool, optional) – If True, print the dictionary created by MainContainer class after it is completed.

total_plots

nrows`*`ncols.

Type

int

general

GeneralContainer class for holding information for general dictionary.

Type

obj

ax

SinglePlot object for holding information pertaining to specific plots. If there is more than one plot in the figure, this will be a list of SinglePlot objects of len=total_plots.

Type

obj or list of objects

print_input

If True, print the dictionary created by MainContainer class after it is completed.

Type

bool, optional

return_dict()

Output dictionary for make_plot.py input.

Iterates through the entire MainContainer class turning its contents into dictionary form. This dictionary becomes the input for make_plot.py.

If print_input attribute is True, the entire dictionary will be printed prior to returning the dicitonary.

Returns

Dicitonary for input into make_plot.py.

Return type

  • output_dict (dict)

class bowie.plotutils.forminput.SinglePlot

Bases: bowie.plotutils.forminput.Label, bowie.plotutils.forminput.Limits, bowie.plotutils.forminput.Legend, bowie.plotutils.forminput.Extra, bowie.plotutils.forminput.DataImport

Add information for each singular plot.

Each plot has special information stored in its dictionary. See above documentation for this information.

SinglePlot inherits methods from Label, Limits, Legend, Extra, and DataImport. It uses the methods to store values in the respective Container classes.

type

Which type of plot. Currently supporting Ratio, Watefall, Horizon.

Type

str

file

List of DataImportContainer objects with information on which dataset to use.

Type

list of obj

label

LabelContainer holding informaiton pertaining to labels of the plot. Default is empty container or {}.

Type

obj

limits

LimitsContainer holding information pertaining to limits of the plot. Default is empty container or {}.

Type

obj

legend

LegendContainer holding information pertaining to legend for the plot. Default is empty container or {}.

Type

obj

extra

ExtraContainer holding information pertaining to extra information for the plot. Default is empty container or {}.

Type

obj

add_comparison(comp_list)
set_colormap(cmap)

Set colormap for Ratio plots.

Change the colormap.

Parameters

cmap (str) – String representing the colormap from predefined python colormaps.

set_plot_type(plot_type)

Set type for each plot.

This is a mandatory call for each plot to tell the program which plot is desired.

Parameters

plot_type (str) – Type of specific plot. Currently supporting Ratio, Watefall, Horizon.

Background documentation (plotutils package):

readdata module

class bowie.plotutils.readdata.PlotVals(x_arr_list, y_arr_list, z_arr_list)

Bases: object

This class is designed to carry around the data for each plot as an attribute of self.

Parameters

x_arr_list/y_arr_list/z_arr_list (list of 2D arrays of floats) – List of gridded, 2D datasets representing the x/y/z-values.

class bowie.plotutils.readdata.ReadInData(**kwargs)

Bases: object

Read in the data from txt or hdf5.

This class reads in data. The information is transferred to the read in methods that work for .txt, .csv, and .hdf5.

Keyword Arguments

  • WORKING_DIRECTORY (str) – Path to working directory.

  • file_name (str) – File name for output file.

  • label (str) – Label for column of data in file that will be the z value (SNR).

  • xlims/ylims (len-2 list of floats) – x/y min value followed by max value. Default is lin for linear. If log, the limits should be log of values.

  • dx/dy (float) – increments in x and y.

  • xscale/yscale (string, optional) – scaling for axes. Either ‘log’ or ‘lin’. Default is lin.

  • x_column_label/y_column_label (str, optional) – Column label within the file for x and y.

file_type

File extension. Either hdf5, txt, or csv.

Type

str

xvals/yvals/zvals

Values received from files.

Type

2D array of floats

x_append_value/y_append_value/z_append_value

The value to append to data lists. This can be log10 values for x/y if xcale/yscale == log10. For z values, it will just be zvals.

Type

2D array of floats

hdf5_read_in()

Method for reading in hdf5 files.

txt_read_in()

Read in txt files.

Method for reading in text or csv files. This uses ascii class from astropy.io for flexible input. It is slower than numpy, but has greater flexibility with less input.

plottypes module

class bowie.plotutils.plottypes.Horizon(fig, axis, xvals, yvals, zvals, **kwargs)

Bases: bowie.plotutils.baseplot.CreateSinglePlot

Create Horizon plots.

Horizon is a subclass of bowie.plotutils.baseplot.CreateSinglePlot.

Horizon plots snr contour lines for a designated SNR value. The defaul is SNR_CUT, but can be overridden with snr_contour_value. Horizon can make as many curves as the user prefers and will plot a legend to label those curves. It can only contour one snr value.

get_contour_values()

Get values for contours.

This function is added for modularity.

make_plot()

Make the horizon plot.

class bowie.plotutils.plottypes.Ratio(fig, axis, xvals, yvals, zvals, **kwargs)

Bases: bowie.plotutils.baseplot.CreateSinglePlot

Create a ratio plot.

Ratio is a subclass of bowie.plotutils.baseplot.CreateSinglePlot.

Ratio creates a filled contour plot comparing snrs from two different data sets. Typically, it is used to compare sensitivty curves and/or varying binary parameters. It takes the snr of the first dataset and divides it by the snr from the second dataset. Additionally, a Loss/Gain contour is plotted. Loss/Gain contour is based on SNR_CUT but can be overridden with ‘snr_contour_value’ kwarg. A gain indicates the first dataset reaches the snr threshold while the second does not. A loss is the opposite.

comp1/comp2

Comparison and control datasets respectivley.

Type

2D array of floats

find_difference_contour()

Find the ratio and loss/gain contours.

This method finds the ratio contour and the Loss/Gain contour values. Its inputs are the two datasets for comparison where the second is the control to compare against the first.

The input data sets need to be the same shape.

Returns

2-element tuple containing

  • diff (2D array of floats): Ratio contour values.

  • loss_gain_contour (2D array of floats): loss/gain contour values.

make_plot()

Creates the ratio plot.

set_comparison()

Defines the comparison values for the ratio.

This function is added for easier modularity.

class bowie.plotutils.plottypes.Waterfall(fig, axis, xvals, yvals, zvals, **kwargs)

Bases: bowie.plotutils.baseplot.CreateSinglePlot

Create Waterfall plot.

Waterfall is a subclass of bowie.plotutils.baseplot.CreateSinglePlot.

Waterfall creates an snr filled contour plot similar in style to those seen in the LISA proposal. Contours are displayed at snrs of 10, 20, 50, 100, 200, 500, 1000, and 3000 and above. If lower contours are needed, adjust ‘contour_vals’ kwarg.

Contour_vals needs to start with zero and end with a higher value than the max in the data. Contour_vals needs to be a list of max length 9 including zero and max value.

make_plot()

This method creates the waterfall plot.

makeprocess module

This module houses the main class for plotting within the BOWIE package. It runs through the whole plot creation process.

It is part of the BOWIE analysis tool. Author: Michael Katz. Please cite “Evaluating Black Hole Detectability with LISA” (arXiv:1807.02511) for usage of this code.

This code is licensed under the GNU public license.

class bowie.plotutils.makeprocess.MakePlotProcess(**kwargs)

Bases: object

Process hub for creating plots.

Class that carries the input dictionary (pid) and directs the program to accomplish plotting tasks.

Parameters

**kwargs (dict) – Combination of all input dictionaries to have their information stored as attributes.

Keyword Arguments

  • plot_info (dict) – Dictionary containing all the individual plot info.

  • sharey (sharex,) – Applies sharex, sharey as used in plt.subplots(). See https://matplotlib.org/api/_as_gen/matplotlib.pyplot.subplots.html Default is True.

  • figure_width/figure_height (float, optional) – Dimensions of the figure set with fig.set_size_inches() from matplotlib. Default is 8.0 for each.

  • bottom (float, optional) – Sets position of bottom of subplots in figure coordinates. Default is 0.1.

  • top (float, optional) – Sets position of top of subplots in figure coordinates. Default is 0.85.

  • left (float, optional) – Sets position of left edge of subplots in figure coordinates. Default is 0.12.

  • right (float, optional) – Sets position of right edge of subplots in figure coordinates. Default is 0.79.

  • wspace (float, optional) – The amount of width reserved for space between subplots, It is expressed as a fraction of the average axis width. Default is 0.3.

  • hspace (float, optional) – The amount of height reserved for space between subplots, It is expressed as a fraction of the average axis width. Default is 0.3.

  • snr_input (dict) – kwargs for gwsnrcalc.gw_snr_calculator.SNR.

total_mass

Total mass of each binary.

Type

1D array of floats

mass_ratio

Mass ratio of each binary.

Type

1D array of floats

m1

Mass 1 of each binary.

Type

1D array of floats

m2

Mass 2 of each binary.

Type

1D array of floats

z_or_dist

Redshift or distance of each binary.

Type

1D array of floats

spin_1

Spin of mass 1 of each binary.

Type

1D array of floats

spin_2

Spin of mass 2 of each binary.

Type

1D array of floats

start_time

Start time in years before merger of each binary.

Type

1D array of floats

total_mass

End time in years before merger of each binary.

Type

1D array of floats

dist_type

Which type of distance measure is used. Options are redshift, luminosity_distance, or comoving_distance.

Type

str

value_classes

Class bowie.plotutils.readdata.PlotVals that holds data.

Type

obj

final_dict

Dictionary with SNR results.

Type

dict

Note

All kwargs above are added as attributes.

create_plots()

Creates plots according to each plotting class.

input_data()

Function to extract data from files according to pid.

This function will read in the data with bowie.plotutils.readdata.ReadInData.

setup_figure()

Sets up the initial figure on to which every plot is added.

baseplot module

class bowie.plotutils.baseplot.CreateSinglePlot(fig, axis, xvals, yvals, zvals, **kwargs)

Bases: object

Base class for the subclasses designed for creating the plots.

All of the plot types inherit this class and its methods. The __init__ method is the same for all plots. Each plot_type in bowie.plotutils.plottypes has its own make_plot method and associated methods for creating the plot.

Parameters

  • fig (obj) – Figure environment for the plots.

  • axis (obj) – Axis object representing specific plot.

  • xvals/yvals/zvals (list of 2D arrays of floats) – List of x,y,z-value arrays for the plot.

Keyword Arguments

  • plot_type (str) – String representing the plot type.

  • SNR_CUT (float) – SNR cut for detectability or another desired value.

  • xlims/ylims (len-2 list of floats) – Limits for the x/y axis. If xscale/yscale == 'log', these values are the log10 of the limits.

  • dx/dy (float) – Amount to increment for tick labels. If log10 of values, then dx/dy repesents increments in log10.

  • xscale/yscale (str) – lin for linear scale. log for log10 scale.

  • title/xlabel/ylabel (str, optional) – String for title/xlabel/ylabel for specific plot.

  • title_kwargs/xlabel_kwargs/ylabel_kwargs – Kwargs for call to add string labelling to plot.

  • x_tick_label_fontsize/y_tick_label_fontsize (int, optional) – Tick label fontsize for x/y axis. Default is 14.

  • tick_label_fontsize (int, optional) – Tick label fontsize for both x and y axes. If not None, this will set both axis in one go to the same value. Default is None.

  • reverse_x_axis/reverse_y_axis (bool, optional) – If True, reverse the order of the ticks along each axis from ascending to descending. Default is False.

  • spacing (str, optional) – Spacing of plots. wide indicates spaced out plots (hspace = 0.3 and wspace = 0.3 in subplots_adjust). All the tick labels will show. If tight, no space between plots in the figure (hspace = 0.0 and wspace = 0.0 in subplots_adjust). In this case, the edge tick labels are cut off for clarity. Default is wide.

  • add_grid (bool, optional) – If True, add a grid to the specific plot. Default is True.

  • colorbar (obj, optional) – Object of type bowie.plotutils.baseplot.FigColorbar. This houses information for the colorbar for the associated plot type. Default is None.

  • colormap (str, optional) – String represented the the colormap choice through python’s predefined colormaps. This is for ratio plots. Default is coolwarm.

  • loss_gain_status (bool, optional) – If True, show the loss gain contours. This only applies to bowie.plotutils.plottypes.Ratio plot. Default is True.

  • snr_contour_value (float, optional) – This will set the value for contours in plots. In bowie.plotutils.plottypes.Ratio plots, this sets the value for loss/gain contours and minimal value for ratio contours (overrides SNR_CUT). For bowie.plotutils.plottypes.Horizon plots this sets the value for the horizon contours. For bowie.plotutils.plottypes.Waterfall plots, this will add an additional contour in white. Default is None.

  • order_contour_lines (bool, optional) – Show dashed lines at each order of magnitude within the ratio contours. Default is False.

  • ratio_comp_value (float, optional) – If not None, this value is used as the minimum value for the ratio contours. If None, this value will be SNR_CUT or snr_contour_value if given. In other words, it will be the same as loss/gain contour maximum. Default is None.

  • legend_kwargs (dict, optional) – kwargs for call to ax.legend(). Default is {}.

  • legend_labels (list of str, optional) – Labels for the curves in the legend. If calling legend, these are required. Default is [].

  • add_legend (bool, optional) – If True, add legend.

  • contour_vals (list or array of floats) – Contour values to use for bowie.plotutils.plottypes.Waterfall. Default is np.array([0., 10, 20, 50, 100, 200, 500, 1000, 3000, 1e10]). Default kwarg value is [].

comparison_value

Value to use for contour comparisons. This will either be SNR_CUT or snr_contour_value.

Type

float

Note

all args and kwargs become attributes.

setup_plot()

Set up limits and labels.

For all plot types, this method is used to setup the basic features of each plot.

class bowie.plotutils.baseplot.FigColorbar(fig, plot_type, **kwargs)

Bases: object

Create colorbars

This class holds and creates colorbars for the plots shown. It has default values for each plot that can be replaced by passing kwargs.

Parameters

  • fig (obj) – Figure object for adding the colorbar.

  • plot_type (str) – String representing the plot type for this colorbar.

Keyword Arguments

  • cbar_ticks (list or array of floats, optional) – List or array representing the ticks to be shown on the colorbar. Default kwarg is []. If cbar_ticks == [], the default for each plot type is used. For Waterfall it is [0., 10, 20, 50, 100, 200, 500, 1000, 3000, 1e10]. For Ratio plots, it is [-3.0, -2.0, -1.0, 0.0, 1.0, 2.0, 3.0].

  • cbar_tick_labels (list of str, optional) – List of strings corresponding to the labels for the cbar_ticks. Default is []. In this case, default for each plot type is used. Waterfall plots default to [0., 10, 20, 50, 100, 200, 500, 1000, 3000]. Ratio plots default to [-2.0, -1.0, 0.0, 1.0, 2.0].

  • cbar_ticks_fontsize (int, optional) – Fontsize for colorbar ticks. Default is 15.

  • cbar_label_fontsize (int, optional) – Label fontsize for the colorbar. Default is 20.

  • cbar_pos (int, optional) – Describes defined positions (axes) for the colorbar. Default positions are 1-5. {‘1’: [0.83, 0.49, 0.03, 0.38], ‘2’: [0.83, 0.05, 0.03, 0.38], ‘3’: [0.05, 0.92, 0.38, 0.03], ‘4’: [0.47, 0.92, 0.38, 0.03], ‘5’: [0.83, 0.1, 0.03, 0.8]}. Default is 1 for Waterfall and 2 for Ratio. Default value for kwarg is ‘use_default’.

  • cbar_axes (len-4 list of floats, optional) – Custom axes for colorbar. This overrides any entry to cbar_pos. Default is []. In this case, it will default to axes for cbar_pos value.

  • cbar_orientation (str, optional) – Vertical or horizontal orientation for the colorbar. Default is vertical if the bar is thinner than it is tall. If it is wider than it is tall, default is horizontal. Default value for kwarg is None.

  • cbar_label_pad (float, optional) – Label padding of colorbar label. Default is None. This means -60 for horizontal and 10 for vertical. # TODO check these numbers.

cbar_ax

Axes object on the figure for the colorbar.

Type

obj

cbar_var

String representing the axis of the colorbar to add labels to. For horizontal this is ‘x’ and for vertical it is ‘y’.

Type

str

Note

all args and kwargs are added as attributes.

setup_colorbars(plot_call_sign)

Setup colorbars for each type of plot.

Take all of the optional performed during __init__ method and makes the colorbar.

Parameters

plot_call_sign (obj) – Plot instance of ax.contourf with colormapping to add as a colorbar.