*****************************************************
*** Main Dictionary for generate_contour_data.py: ***
*****************************************************


Documentation is provided for main dictionaries in "generate_contour_data.py" and "make_plot.py". In both codes, dictionaries are passed into the main function of the code, providing the preferences of the user. 

Listed here will be all possible choices for each dictionary, including which choices are optional and which are required. 

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 code.py confi.json. For example, generate_contour_data.py generate_config.json. 

It is part of the BOWIE analysis tool. Author: Michael Katz. Please see "Evaluating Black Hole Detectability with LISA" (arXiv:1807.02511) for example usage. 



{

general:
    {
    WORKING_DIRECTORY (str):
        Default: "."
        working directory for file export and retrieval

    signal_type (str list):
        Required
        SNR calculations for phases of binary coalescence. 
        Choices are "ins" (inspiral), "merg" (merger), "rd" (ringdown), and/or "all". 

    generation_type (str):
        Required
        Calculation run on single thread or in parallel. 
        Choices are "parallel" or "single". 

    num_processors (int):
        Default: 4
        Number of processors to run across in parallel. 
       

    num_splits (int):
        Default: 1000
        Number of binaries to run on a thread. The number of processes needed are the total number of binaries  
            divided by num_splits. 
       
    add_wd_noise (str): 
        Default: "no"
        Indicates if calculation with a galactic foreground is needed. 
        Choices are "yes" (or "True" (string)), "no" (or False" (string)), or "both". "yes" only calculates with the foreground noise. "both" does both with and without foreground noise. 
    },

output_info:
    {
    output_folder (str): 
        Default: "."
        Folder to output the gridded SNR calculation to. 

    output_file_name (str):
        Required
        File to output SNR calculations to. DO NOT INCLUDE '.' + THE FILE EXTENSION. 

    output_file_type (str):
        Default: "hdf5"
        File extension for output file. 
        Choices are "hdf5" or "txt". 

    x_col_name/y_col_name (str):
        Default: "x"/"y"
        Column name for x/y values output to file for each SNR calculation. 

    added_note (str):
        Default: None
        If the user wants to add a note to the output file. 
    },


input_info:
    {
    input_folder (str):
        Default: "."
    freq_column_label (str):
        Default: "f"
        Column label in input file sensitivity curve frequency. 

    amplitude_column_label (str):
        Default: "ASD"
        Column label in input file sensitivity curve amplitude. 

    sensitivity_averaging_factor (float):
        Default: 1.0
        Value used for sky-averaging and/or polarization averaging for the sensitivity curve. LISA value is 3/20. 

    sensitivity_curves (list of dictionaries):
        Required
        This is referred to as a file_dict.

        file_dict:
            [
            {
            name (str):
                Required
                File name of sensitivity curve. Must be in .txt format. 

            type (str):
                Default: "ASD"
                Type of sensitivity curve used. 
                Choices are "ASD", "PSD", or "characteristic strain".

            freq_column_label (str):
                Same as previous definition inside "input_info". This will override that value if given. This is 
                    used if a specific sensitivity curve has a different file setup than the others. 

            amplitude_column_label (str):
                Same as previous definition inside "input_info". This will override that value if given. This is 
                    used if a specific sensitivity curve has a different file setup than the others. 

            sensitivity_averaging_factor (float):
                Same as previous definition inside "input_info". This will override that value if given. This is 
                    used if a specific sensitivity curve has a different file setup than the others. 
            }
            ]
    galactic_background (dictionary):
        Required if general[add_wd_noise] == yes or both
        This is a file dictionary representing the galactic foreground. It takes the exact same form of the 
            file_dict shown above. 

    },

generate_info:
    {
    xscale/yscale (str): 
        Required
        Scaling used for generation of x/y points. 
        Choices are "log" (log base 10) or "lin" (linear). 

    num_x/num_y (int): 
        Required
        Number of points in x/y. 

    x_low/y_low (float):
        Required
        Low number to use for x/y points. 

    x_high/y_high (float):
        Required
        Low number to use for x/y points.

    fixed_parameter_1/fixed_parameter_2/fixed_parameter_3/fixed_parameter_4 (float):
        Required
        Value for the parameters fixed for each binary. 

    xval_name/yval_name/par_1_name/par_2_name/par_3_name/par_4_name (str):
        Required
        Name of the x/y values being tested. 
        Choices are "total_mass", "mass_ratio", "luminosity_distance", "comoving_distance", "redshift", "spin_1", 
            "spin_2", "spin", "start_time", "end_time". To test different observation times, use specific values of "start_time" and "end_time".

    par_5_name (str):
        Required
        Same as above names with one difference. If the same spin is desired for both black holes, par_3_name
            should be set to "same_spin".

    fixed_parameter_5 (float):
        Required if par_5_name != "same_spin"
        Same choices as above. 

    xval_unit/yval_unit/par_1_unit/par_2_unit/par_3_unit/par_4_unit/par_5_unit (str): 
        Required
        This is for export to a file. It keeps track of quantities for future use of the file. Start time and end 
            time must be given in years. Mass must be given in solar masses. If "luminosity_distance" or "comoving_distance" is used, then the units matter. Default is "Mpc". However, "Gpc" can be given. 
        
    num_points (int): 
        Default: 8192
        This represents the number of frequency points used to represent the waveform. Smaller numbers can speed up computation, but will sacrifice accuracy at some point. 

    snr_calculation_factors (dictionary):
        {
        averaging_factor (float): 
            Default: 1.0
            Value for averaging of the waveform over orientation and inclination. For LISA, sqrt(12/25). 

        snr_factor (float): 
            Default: 1.0
            Value multiplied by integral value to achieve SNR. For LISA, sqrt(2). 
        }
    }
}





*****************************************
*** Main Dictionary for make_plot.py: ***
*****************************************

**********
One thing to notice is that there is a lot of overlap between the general dictionary and dictionaries for specific plots. The general dictionary describes general setup of all plots, but can be overridden by dictionaries for specific plots. 
**********




{
general:
    {
    WORKING_DIRECTORY (str):
        Default: "."
        working directory for file export and retrieval

    SNR_CUT (float): 
        Default: 5.0
        The SNR cut for a detectable signal. Usually between 1-10. 

    switch_backend (str):
        Use for switching backend of matplotlib. Use if running codes in parallel. Typical string value is "agg".

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

    save_figure (boolean): 
        Default: False
        Use fig.savefig() function from matplotlib to save figure. 

    dpi (float):
        Default: 200
        dpi for output image.

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

    file_name (str):
        Required if no file names are given in "plot_info".
        File name for input SNR grids. Can be overridden by specific plot. 

    num_rows/num_cols (int):
        Required
        Number of rows/columns of plots present in the figure. 

    x_column_label/y_column_label (str):
        Default: x/y
        Column label from input file identifying x/y values. This can be overrided in the file_dicts for 
            specific files. 

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

    figure_width/figure_height (float): 
        Default: 8.0
        Dimensions of the figure set with fig.set_size_inches() from matplotlib.

    spacing (str):
        Default: wide
        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 axis 
            contacting each other. 

    adjust_figure_bottom/adjust_figure_top/adjust_figure_left/
        adjust_figure_right/adjust_wspace/adjust_hspace (float): 
        Default: 0.1/0.85/0.12/0.85/0.3/0.3
        Adjust figure dimensions using plt.subplots_adjust() from matplotlib. See the matplotlib url for more 
            info:
            https://matplotlib.org/api/_as_gen/matplotlib.pyplot.subplots_adjust.html

    fig_x_label/fig_y_label (str):
        Overall figure label on the left and bottom. 

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

    fig_label_fontsize/fig_title_fontsize (float):
        Default: 20
        Fontsize corresponding to fig_x_label/fig_y_label and fig_title.  

    xlims/ylims (length 2 list of floats):
        Required
        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]. 

    dx/dy (float):
        Required
        Spacing of x and y ticks. If xscale/yscale == log, the dx/dy is a log10 value. See examples.

    xscale/yscale (str): 
        Default: lin
        Choices are lin for linear spacing or log for log (base 10) spacing. 

    tick_label_fontsize (float):
        Default: 14
        Sets fontsize for both x and y tick labels on the plots. This can be overridden for individual plots.

    x_tick_label_fontsize/y_tick_label_fontsize (float):
        Default: 14
        Sets fontsize fot x/y tick labels. This overrides tick_label_fontsize and can be overridden for specific plots.

    add_grid (boolean):
        Default: True
        Adds gridlines to plots. Can be overridden for specific plots. 

    reverse_x_axis/reverse_y_axis (boolean):
        Default: False
        Reverses the tick marks on the x/y axis. Can be overridden.

    colorbars (dictionary):
        Dictionary containing information on colorbar placement and properties. The keys are the types of plots. Choices are Waterfall or Ratio. 

        {
        label (str):
            Default: Waterfall - $\rho_i$, Ratio - $\rho_i/\rho_0$. 
            Label for the colorbar.

        ticks_fontsize (float):
            Default: 17
            Fontsize for tick marks on colorbar. The ticks are set based on the plot type. 

        label_fontsize (float):
            Default: 20
            Colorbar label fontsize. 

        pos (int):
            Default: Waterfall - 1, Ratio - 2. If plot is alone on figure, default is 5. 
            Preset positions for the colorbars. 1 - top right, 2 - lower right, 3 - top left (horizontal), 4 - top right (horizontal), 5 - stretched to fill right side (effectively 1 & 2 combined).

        colorbar_axes (length 4 list of floats):
            Default: placement based on "pos"
            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
        }
        
    
    },



plot_info (dictionary):
    Required
    Dictionary will all plot info and keys corresponding to index of the plot in the configuration, starting at zero (see examples). 

    {
    (plot index as key):
        {
        file (list of dictionaries):
            At least 1 is required.  
            This file list caries dictionaries for all SNR grids input from files. 

            [
            {
            name (str):
                Required if reading from a file (at least one). Required if file_name is not in "general".
                Name of file. Must be ".txt" or ".hdf5". Can include path from working directory. 

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

            x_column_label/y_column_label (str):
                Default: x/y
                Column label from input file identifying x/y values. This can override setting in "general". 
            }
            ],

        indices (list of int):
            This can be used to refer to other plots that have their files loaded in already. See examples.

        control (dictionary):
            Contains information for control data set for which to compare against in ratio plots. This can either be the exact same form shown above for file dictionary. Or:
            {
            name (str):
                Required if not using index or file_name is not used in "general".
                Name of file. Must be ".txt" or ".hdf5". Can include path from working directory. 

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

            x_column_label/y_column_label (str):
                Default: x/y
                Column label from input file identifying x/y values. This can override setting in "general". 

            index (str):
                Required if not loading a file. 
                Index of plot with preloaded data for which to call the control. 
            }

        type (str):
            Required
            Choices are Waterfall, Ratio, or Horizon. 

        label (dictionary):
            Dictionary containing specifics for specific plots. Can override settings from "general"

            {
            xlabel/ylabel (str):
                Creates x/y labels for specific plot. 

            title (str):
                Sets title for specific plot.

            xlabel_fontsize/ylabel_fontsize/title_fontsize (float):
                Default: 20
                Fontsize for corresponding object on specific plot.

            tick_label_fontsize (float):
                Default: 14
                Sets fontsize for both x and y tick labels on the plots. This can be overridden for individual plots.


            x_tick_label_fontsize/y_tick_label_fontsize (float):
                Default: 14
                Sets fontsize fot x/y tick labels. This overrides tick_label_fontsize and can be overridden for specific plots. Overrides tick_label_fontsize
            },


        limits (dictionary):
            Contains information on axes limits for specific plot. Can override general setup. 
            {
            xlims/ylims (length 2 list of floats):
                Required
                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]. 

            dx/dy (float):
                Required
                Spacing of x and y ticks. If xscale/yscale == log, the dx/dy is a log10 value. See examples.

            xscale/yscale (str): 
                Default: lin
                Choices are lin for linear spacing or log for log (base 10) spacing. 

            reverse_x_axis/reverse_y_axis (boolean):
                Default: False
                Reverses the tick marks on the x/y axis.

            },

        legend (dictionary):
            Contains information for adding a legend to a specific plot. This is only implimented for horizon plots. 
            {
            labels (list of strs):
                Labels for the legend in the same order as the lines being plotted.

            loc (str):
                Default: upper left
                Implimented the same as matplotlib. See matplotlib for options. 

            bbox_to_anchor (list of length 2 or 4 of floats):
                List for placement of a legend on an axis. See url: https://matplotlib.org/api/_as_gen/matplotlib.axes.Axes.legend.html

            size (float):
                Default: 10
                Sets size of legend. 

            },


        extra (dictionary):
            Dictionary containing extra arguments for specifc plot. 

            {
            add_grid (boolean):
                Default: True
                Adds gridlines to plots. Overrides setting from "general". 

            contour_vals (list of floats):
                Default: [0.,10,20,50,100,200,500,1000,3000,1e10]
                Provides contour values for Waterfall plot only. 

            snr_contour_value (float):
                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. 

            ratio_contour_lines (boolean):
                Default: False
                This only applies to ratio plots. This will show contour lines at each order of magnitude ratio.

            show_loss_gain (boolean):
                Default: True
                Toggle loss/gain contours on and off. Only applies to Ratio plots. 
            },
    
        },
    }
}






