Truth Uncertainties & new overplot_spans Function

[jrenaud90]

For your consideration: This PR adds in the functionality to overplot truth uncertainty values as spans in both the scatter and histogram plots.

Example usage of truth uncertainties:

truth_means = np.array([0.569, 0.92, 0.343, 1.0])
truth_sigms = np.array([0.025, 0.58, 0.006, 6.4e-5])

target_samples = ...
target_labels = ...
target_ranges = ...

target_color = 'k'
sigmas_to_plot = 1.0  # In case you want to plot 2, 3, ... sigmas
truth_uncerts = [sigmas_to_plot * sig for sig in truth_sigms]

# Corner Plot of Targets
target_color = 'k'
figure_targs = corner.corner(
    target_samples,
    labels=target_labels,
    truths=truth_means,
    truth_uncertainties=truth_sigms,  # New
    truth_color=target_color,
    range=target_ranges,
    smooth=True,
    color='royalblue',
    quantiles=[0.16, 0.5, 0.84],
    show_titles=True,
    title_kwargs={"fontsize": 12, "pad": 10},
    truth_uncertainties_kwargs=None,  # New: kwargs sent to plt.axvspan; if None use defaults (e.g., transparency and color)
    hist_kwargs={"density": True}
    )

Result:

Additionally, you can add different or additional spans on any corner plot using overplot_spans which follows a similar format to corner.overplot_lines:

import corner

corner.overplot_spans(corner_fig, lowers, uppers, reverse=False, **span_kwargs)

Todo's (Happy to work on these if provided some guidance):

• Needs tests
• Update documentation