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

Documentation is provided for the main dictionary in "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).

Listed here will be all possible choices for the 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 make_plot.py make_plot_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.

**********
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 with 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".


            }

        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.

            ratio_comp_value (float):
                Default: Same value as loss/gain contour (which defaults to SNR_CUT)
                This sets the minimum SNR necessary for both configurations in a ratio plot to show the ratio contours. (rho_1>ratio_comp_value & rho_2>ratio_comp_value) in order to display the contour.
            },

        },
    }
}
