saga.plot

This module implements methods for plotting asymmetry results.

saga.plot.get_bin_centers(cuts, swap_axes=False)

Parameters

cutsdict, required

Dictionary of bin ids to bin cuts

swap_axesbool, optional

Swap the default x and y axes order

Returns

tuple

Tuple of maps of bin ids to bin centers and bin widths respectively

Description

Get the bin center coordinates from a list of (rectangular 2D) bin cuts. Note that bin cuts are assumed to be of the form (binvar_x>=x_min && binvar_x<=x_max) && (binvar_y>=y_min && binvar_y<=y_max).

saga.plot.get_bin_kinematics_title(bin_id, df, cols=None, col_titles=None, col_unit_titles=None, err_ext='_err', sep=' , ')

Parameters

bin_idint, required

Bin id in kinematics dataframe

dfpandas.Dataframe, required

Dataframe of kinematic variable means and errors in each kinematic bin

colslist, optional

List of column names of kinematics to add to bin title

col_titlesdict, optional

Dictionary of kinematics LaTeX titles

col_unit_titlesdict, optional

Dictionary of kinematics units titles with any necessary latex formatting

err_extstr, optional

Extension for forming column names of kinematic variable errors

sepstr, optional

Separator string for kinematics values in bin title

Returns

str

Title string

Description

Create a title string for the requested bin index and kinematic variables showing the mean and error values for each of the requested kinematic variables in the given bin.

saga.plot.get_lims_coords(node, outer_xlims, outer_ylims, var_keys=None, nested_key='nested', lims_key='lims', swap_axes=False)

Parameters

nodedict, required

Bin scheme node

outer_xlimslist, required

List of outer limits for the x-axis variable

outer_ylimslist, required

List of outer limits for the y-axis variable

var_keyslist, optional

List names of x and y axis variables for a grid bin scheme

nested_keystr, optional

Key for nested bins

lims_keystr, optional

Key for bin limits

swap_axesbool, optional

Swap the default x and y axes order

Raises

ValueError

Raises error if no acceptable bin scheme is found.

Returns

list

List of line coordinates in the form \(((x_1,x_2),(y_1,y_2))\)

Description

Get a list of line coordinates delineating the bin limits for a nested 2D binning scheme.

saga.plot.plot_bin_ids(ax, bin_centers, size=25, color='red', alpha=1.0)

Parameters

axmatplotlib.axes._axes.Axes, required

Matplotlib.pyplot axis to plot on

bin_centersdict, required

Dictionary of bin ids to bin centers

sizeint, optional

Font size for bin id text

colorstr, optional

Text color

alphafloat, optional

Text alpha value

saga.plot.plot_hists(ax1, hist_paths=None, hist_keys=None, clone_axis=True, ylabel='Density', ylims=(0.0, 0.05), histtype='step', hist_colors=None, alpha=0.5, linewidth=2, density=True, log=False, hist_labels=None, binlims=None, vlinestyle='dotted', vline_hist_idx=-1, legend_loc='upper right', hist_dim=1)

Parameters

ax1matplotlib.axes._axes.Axes, required

Matplotlib.pyplot figure axis

clone_axisbool, optional

Option to create a twin y axis sharing the x axis of the given axis

ylabelstr, optional

Y axis label for twin axis

ylimstuple, optional

Y axis limits for twin axis

histtypestr, optional

Matplotlib.pyplot histogram type

hist_colorslist, optional

List of histogram colors

alphafloat, optional

Alpha plotting paramater for histograms

linewidthint, optional

Line width for plotting histograms

densitybool, optional

Option to normalize histograms

logbool, optional

Option to plot y-axis on a log scale

hist_labelslist, optional

List of histogram labels

binlimslist, optional

List of bin limits in a 1D binning scheme

vlinestylestr, optional

Vertical line style for drawing bin limits on histogram

vline_hist_idxint, optional

Index of histogram for which to draw vertical lines for bin limits

legend_locstr, optional

Matplotlib.pyplot legend location string, will not be plotted if set to None or ''

hist_dimint, optional

Dimension of histogram to plot. Must be either 1 or 2.

Description

Draw a set of histograms on a matplotlib.pyplot axis, optionally cloning the given axis and optionally drawing vertical bin limits on a single histogram.

saga.plot.plot_injected_asyms(ax1, asyms, ytitles, colors, sgasym_idx=0, ylims=(-1.0, 1.0), label_base='Injected Signal ', linestyle='--', linewidth=1)

Parameters

ax1matplotlib.axes._axes.Axes, required

Matplotlib.pyplot figure axis

asymslist, required

List of injected asymmetries

ytitleslist, required

List of y axis titles

colorslist, required

List of colors for each injected asymmetries

sgasym_idxint, optional

Injected signal asymmetry index

ylimstuple, optional

y limits for plotting

label_basestr, optional

Base label to prepend to ytitles for injected asymmetries

linestylestr, optional

Line style

linewidthint, optional

Line width

Description

Plot the injected asymmetries for each bin in a 1D binning scheme offsetting repeat values by a small amount. Note that injected asymmetries should have shape (N_ASYMS) if plotting constant asymmetries or (N_ASYMS,2,N_POINTS) if you would like to plot function data (x,y).

saga.plot.plot_label(ax1, plot_label_args=None)

Parameters

ax1matplotlib.axes._axes.Axes, required

Matplotlib.pyplot figure axis

plot_label_argslist, optional

List of positional arguments for plot label

Description

Plot a text label.

saga.plot.plot_lines(ax, coordinates, linecolor='red', linewidth=1)

Parameters

axmatplotlib.axes._axes.Axes, required

Matplotlib.pyplot axis to plot on

coordinateslist of lists, required

List of coordinate pairs each with structure \(((x_1,x_2),(y_1,y_2))\)

colorstr, optional

Line color

linewidthint, optional

Line width

Description

Plot a set of lines from a list of coordinates.

saga.plot.plot_results(ax1, ct_mean=None, x_mean=None, y_mean=None, xerr_mean=None, yerr_mean=None, xerr_syst=None, yerr_syst=None, y_std=None, ydiff_mean=None, ydiff_std=None, xlims=(0.0, 1.0), ylims=(-1.0, 1.0), title='Asymmetry Results', xvar='x', xlabel='$x$', ylabel='$\\mathcal{A}$', sgasym_labels=None, bgasym_labels=None, sgasym_idx=0, sgasyms=None, bgasyms=None, sg_colors=None, bg_colors=None, fill_color='gray', outpath='out.pdf', watermark='CLAS12 Preliminary', watermark_kwargs=None, show_injected_asymmetries=False, title_pad=20, lg_kwargs=None, plot_label_args=None, ecolor='black', elinewidth=2.0, capsize=18, marker='o', markersize=20, linestyle=None, linewidth=0.0, axlinewidth=1.0, hist_paths=None, hist_keys=None, hist_clone_axis=True, hist_ylabel='Density', hist_ylims=(0.0, 0.05), histtype='step', hist_colors=None, hist_alpha=0.5, hist_linewidth=2, hist_density=True, hist_log=False, hist_labels=None, binlims=None, vlinestyle='dotted', vline_hist_idx=-1, hist_legend_loc='upper right', hist_dim=1, old_dat_path='old_dat_path.csv', new_sim_path='new_sim_path.csv', old_sim_path='old_sim_path.csv', count_key='count', yerr_key='', xs_ratio=1.0, lumi_ratio=0.0, tpol_factor=1.0, tdil_factor=1.0, graph_yvalue=-100.0, aliases=None, plot_xerrors=False)

Parameters

ax1matplotlib.axes._axes.Axes, required

Matplotlib.pyplot figure axis

ct_meanlist, optional

Count mean values for each bin with shape (nbins)

x_meanlist, optional

x mean values for each bin with shape (nbins)

y_meanlist, optional

y mean values for each bin with shape (nbins)

xerr_meanlist, optional

x error alues for each bin with shape (nbins)

yerr_meanlist, optional

y error values for each bin with shape (nbins)

xerr_systlist, optional

x systematic error alues for each bin with shape (nbins) or (nbins,2)

yerr_systlist, optional

y systematic error values for each bin, with shape (nbins) or (nbins,2)

y_stdlist, optional

y standard deviation values for each bin with shape (nbins)

ydiff_meanlist, optional

y difference from injected signal asymmetry mean values for each bin with shape (nbins)

ydiff_stdlist, optional

y difference from injected signal asymmetry standard deviation values for each bin with shape (nbins)

xlimstuple, optional

x limits for plotting

ylimstuple, optional

y limits for plotting

titlestr, optional

Plot title

xvarstr, optional

Bin variable name

xlabelstr, optional

x axis label

ylabelstr, optional

y axis label

sgasym_labelslist, optional

List of signal asymmetry labels

bgasym_labelslist, optional

List of background asymmetry labels

sgasym_idxint, optional

Index of injected signal asymmetry

sgasymslist, optional

List of injected signal asymmetries

bgasymslist, optional

List of injected background asymmetries

sg_colorslist, optional

List of signal asymmetry plotting colors

bg_colorslist, optional

List of background asymmetry plotting colors

fill_colorstr, optional

Color of 1 sigma band or systematic uncertainties

outpathstr, optional

Name of output pdf

watermarkstr, optional

Optional watermark to put on top of plot

watermark_kwargsdict, optional

Optional key word arguments for plot_watermark()

show_injected_asymmetriesbool, optional

Option to show injected signal and background asymmetries

title_padint, optional

Title padding

lg_kwargsdict, optional

Matplotlib.pyplot legend keyword arguments

plot_label_argslist, optional

List of positional arguments for plot label

ecolorstr, optional

Error line color

ecolorfloat, optional

Error line width

capsizeint, optional

Error cap size

markerstr, optional

Marker type

markersizeint, optional

Marker size

linestylestr, optional

Line style

linewidthfloat, optional

Line width

axlinewidthfloat, optional

Axis line and injected asymmetries line width

hist_clone_axisbool, optional

Option to create a twin y axis sharing the x axis of the given axis

hist_ylabelstr, optional

Y axis label for twin axis

hist_ylimstuple, optional

Y axis limits for twin axis

histtypestr, optional

Matplotlib.pyplot histogram type

hist_colorslist, optional

List of histogram colors

hist_alphafloat, optional

Alpha plotting paramater for histograms

hist_linewidthint, optional

Line width for plotting histograms

hist_densitybool, optional

Option to normalize histograms

hist_logbool, optional

Option to plot y-axis on a log scale

hist_labelslist, optional

List of histogram labels

binlimslist, optional

List of bin limits in a 1D binning scheme

vlinestylestr, optional

Vertical line style for drawing bin limits on histogram

vline_hist_idxint, optional

Index of histogram for which to draw vertical lines for bin limits

hist_legend_locstr, optional

Matplotlib.pyplot legend location string for histograms, will not be plotted if set to None or ''

hist_dimint, optional

Dimension of histogram to plot. Must be either 1 or 2.

old_dat_pathstr, optional

Part of path to replace

new_sim_pathstr, optional

Path with which to replace old_dat_path to find new simulation graph CSVs

old_sim_pathstr, optional

Path with which to replace old_dat_path to find new simulation graph CSVs

count_keystr, optional

CSV column key for graph bin counts

yerr_keystr, optional

CSV column key for graph bin y errors

xs_ratiofloat, optional

Cross-section ratio (new/old) for scaling

lumi_ratiofloat, optional

Luminosity ratio (new/old) for scaling

tpol_factorfloat, optional

Target polarization factor for rescaling

tdil_factorfloat, optional

Target dilution factor for rescaling

graph_yvaluefloat, optional

Constant asymmetry value to be plotted for showing rescaled errors

aliasesdict, optional

Map of configuration option names to maps of option values to string aliases for chained CSVs when rescaling

plot_xerrorsbool, optional

Option to plot x errors on asymmetry graph

Description

Plot asymmetry results for each bin in a 1D binning scheme showing projection variable histograms, bin limits, systematic errors, a standard deviation band for aggregate graphs, injected asymmetries, watermark, and legend if desired. Save results and differences from the injected signal to CSV in <outpath>.csv and <outpath>_ydiff.csv. Optionally, rescale the input graph using rescale_graph_data(). Note that the graph y values can be set to a constant with graph_yvalue if you only wish to show the rescaled errors, and that here, the rescaled asymmetry errors will be further scaled to account for target polarization and dilution factors like \(\sigma_{A} = \frac{1}{P_{Target} \cdot D_{Target}}\cdot\sqrt{\frac{1-(A \cdot P_{Target})^{2}}{N_{Rescaled}}}\).

saga.plot.plot_results_array(graph_array, plot_results_kwargs_array, plot_results_kwargs_base=None, figsize=(16, 10), outpath='plot_projections.pdf', use_grid_titles=True, use_grid_xlabels=True, use_grid_ylabels=True, use_grid_hist_ylabels=True, use_default_plt_settings=True)

Parameters

graph_arraylist, required

List array of graph dictionaries from get_aggregate_graph() with the desired shape

plot_results_kwargs_arraylist, required

List array of plot_results() key word arguments for each graph

plot_results_kwargs_basedict, optional

Dictionary of base plot_results() key word arguments to apply to every graph

figsizetuple, optional

Figure size

outpathstr, optional

Output graphic path

use_grid_titlesbool, optional

Option to assume grid titles and only use titles for plots on top row of array

use_grid_xlabelsbool, optional

Option to assume grid x-axis labels and only use x-axis labels for plots on bottom row of array

use_grid_ylabelsbool, optional

Option to assume grid y-axis labels and only use y-axis labels for plots on leftmost column of (2D) array

use_grid_hist_ylabelsbool, optional

Option to assume grid histogram y-axis labels and only use histogram y-axis labels for plots on rightmost column of (2D) array

use_default_plt_settingsbool, optional

Option to use default font and tick parameter style settings

Description

Plot an array of asymmetry graph results using the plot_results() method. Note that plot_projection_kwargs should have the same shape as graph_array and that plot and axis titles will not be set unless they are on the outside edge of the plot grid. Also, note that changing the figure size to allow for a \((16,10)\) space for each figure will be ideal when using the use_default_plt_settings option.

saga.plot.plot_systematics(x_means, yerr_syst, palette='Dark2', stacked=False, syst_names=None, syst_labels=None, xlims=(0.0, 1.0), ylims=(-1.0, 1.0), title='Systematic Errors', xtitle='$Q^{2} (GeV^{2})$', ytitle='$\\Delta \\mathcal{A}$', outpath='systematics.pdf', watermark='CLAS12 Preliminary', watermark_kwargs=None, use_default_plt_settings=True, title_pad=20, lg_kwargs=None, plot_label_args=None, axlinewidth=1.0, log=False, figsize=(16, 10))

Parameters

x_meanslist, required

Mean x values for each bin

yerr_systnp.array, required

Array of absolute systematic error in each bin further indexed by the sources of systematic error

palettestr, optional

Seaborn color palette

stackedbool, optional

Whether to stack histograms from different sources of systematic error

syst_nameslist, optional

List of column names for each source of systematic error

syst_labelslist, optional

List of labels for each source of systematic error

xlimstuple, optional

x limits for plotting

ylimstuple, optional

y limits for plotting

titlestr, optional

Plot title

xtitlestr, optional

x axis title

ytitlestr, optional

y axis title

outpathstr, optional

Name of output pdf

watermarkstr, optional

Optional watermark to put on top of plot

watermark_kwargsdict, optional

Optional key word arguments for plot_watermark()

use_default_plt_settingsbool, optional

Option to use default font and tick parameter style settings

title_padint, optional

Title padding

lg_kwargsdict, optional

Matplotlib.pyplot legend keyword arguments

plot_label_argslist, optional

List of positional arguments for plot label

axlinewidthfloat, optional

Axis line and injected asymmetries line width

logbool, optional

Option to plot y-axis on a log scale

figsizetuple, optional

Figure size

Description

Plot the systematic error for each bin in a 1D binning scheme broken down by sources of systematic error. Save systematics breakdowns to CSV in <outpath>.csv. Note that this does not allow for asymmetric errors.

saga.plot.plot_th2(h2, ax, add_colorbar=True, norm=<matplotlib.colors.LogNorm object>, **kwargs)

Parameters

h2tuple or list, required

List of 2D histogram data with structure (weights, xbins, ybins)

axmatplotlib.axes._axes.Axes, required

Matplotlib.pyplot axis to plot on

add_colorbarbool, optional

Add a colorbar to show the z-axis scale

normstr or matplotlib.colors.Normalize, optional

Normalization used to scale data to \([0,1]\) range before mapping to a color map

kwargs

Additional parameters are passed along to matplotlib.pyplot.hist2d()

Description

Easily plot a TH2 histogram loaded from ROOT.

saga.plot.plot_vlines(hist, binlims=None, linestyle='dotted')

Parameters

histtuple, required

Matplotlib.pyplot histogram of y and x values (np.ndarray, np.ndarray, …)

binlimslist, required

List of bin limits in a 1D binning scheme

linestylestr, optional

Line style

Description

Draw vertical bin limit lines on a histogram

saga.plot.plot_watermark(ax1, watermark='CLAS12 Preliminary', size=50, rotation=25.0, color='gray', alpha=0.25)

Parameters

ax1matplotlib.axes._axes.Axes, required

Matplotlib.pyplot figure axis

watermarkstr, optional

Watermark text

Description

Plot a watermark.

saga.plot.set_default_plt_settings()

Description

Set plt.rc parameters for font sizes and family and tick font size and tick length and direction in a nice format.