calib_plot_functions

Description of plotting functions:

bnn_for_14C_calibration.calib_plot_functions.plot_calib_results(calibration_results, c14age=None, c14sig=None, plot_BNN=True, covariables=None, color_BNN='blue', parts_1_and_2=True, part_1=False, part_2=False, plot_IntCal20=False, color_IntCal20='green', figsize=None, fontsize_legend=['xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'][2], fig=None, axs=None, add_grid=False, color_cal_date='cyan', eps=10 ** -7, plot_HPD_bounds=False, plot_HPD_threshold=False, color_c14age='gray', support_size=5, sample_size=1000, plot_density=False, fill_density=True)

Plot a full graphical summary of individual radiocarbon calibration results.

The figure combines:

• the probability density of the radiocarbon measurement,
• the calibration curve (BNN-based or IntCal20),
• the posterior density of the calibrated date with its HPD region,
• a blank panel for layout aesthetics.

Parameters:

Name	Type	Description	Default
calibration_results	Dict[str, Any]	A dictionary containing all required calibration outputs (c14age, c14sig, covariables, posterior density, HPD intervals, etc.).	required
c14age	float	Preserved for backward compatibility; the radiocarbon age (will be overwritten by the value inside calibration_results).	None
c14sig	float	Preserved for backward compatibility; the radiocarbon age uncertainty (will be overwritten by the value inside calibration_results).	None
plot_BNN	bool	If True, plot the BNN calibration curve (unless covariables is None).	True
covariables	bool or None	Preserved for backward compatibility; whether covariates were used for BNN calibration (will be overwritten by the value inside calibration_results). If None, IntCal20 is used automatically.	None
color_BNN	str	Color for the BNN calibration curve.	'blue'
parts_1_and_2	bool	Whether to plot the entire BNN curve (parts 1 and 2).	True
part_1	bool	If True, only plot part 1 of the BNN calibration curve.	False
part_2	bool	If True, only plot part 2 of the BNN calibration curve.	False
plot_IntCal20	bool	If True, plot the IntCal20 curve instead of a BNN model.	False
color_IntCal20	str	Color for the IntCal20 calibration curve.	'green'
figsize	tuple or None	Size of the figure in inches. If None, a default size is chosen.	None
fontsize_legend	str	Legend font size.	['xx-small', 'x-small', 'small', 'medium', 'large', 'x-large', 'xx-large'][2]
fig	Figure or None	A figure instance to reuse; if None, one is created.	None
axs	array-like of Axes or None	A 2×2 array of axes. If None, axes are created.	None
add_grid	bool	Whether to add grid lines to all plots.	False
color_cal_date	str	Color used for plotting the posterior distribution of the calibrated date.	'cyan'
eps	float	Density threshold below which points are considered negligible. A negative value allows to display the posterior distribution of the calibrated date over all the entire range of the calibration curve.	10 ** -7
plot_HPD_bounds	bool	If True, display vertical HPD interval bounds.	False
plot_HPD_threshold	bool	If True, plot the HPD threshold line.	False
color_c14age	str	Color for the radiocarbon measurement density plot.	'gray'
support_size	float	Half-width of the range (in σ units) used to construct the c14age density.	5
sample_size	int	Number of points in the discretized c14age density evaluation.	1000
plot_density	bool	Whether to draw the c14age density curve.	False
fill_density	bool	Whether to fill the area under the c14age density curve.	True

Returns:

Type	Description
None	The function displays the figure directly using plt.show().

bnn_for_14C_calibration.calib_plot_functions.plot_individual_calibration_curve_part_1(xlabel='Calibrated dates (in years BP)', ylabel='Radiocarbon ages (in years BP)', add_grid=True, fontsize_legend='small', ax=None, figsize=None, color='cyan', alpha=0.4, incertitude=True, sigma_length=1, Min_x=None, Max_x=None, Min_y=None, Max_y=None, invert_xaxis=True, domaine=['delta14c', 'c14', 'f14c'][0], covariables=False, credible_interval=False, credible_interval_level=0.95, credible_color=None, credible_alpha=None)

Plot the BNN calibration curve (part 1) by calling add_individual_calibration_curve_part_1 and applying axis labels, grid, legend, and final display.

This function is a thin wrapper around add_individual_calibration_curve_part_1 and only handles visual elements such as xlabel, ylabel, grid and legend.

Parameters:

Name	Type	Description	Default
xlabel	str	Label for the x-axis.	'Calibrated dates (in years BP)'
ylabel	str	Label for the y-axis. Adjusted automatically if domaine is "delta14c" or "f14c".	'Radiocarbon ages (in years BP)'
add_grid	bool	Whether to display a grid on the plot.	True
fontsize_legend	str	Font size for the legend.	'small'
ax	Axes or None	Axis to draw on. If None, the axis internally created by add_individual_calibration_curve_part_1 is used.	None
figsize	tuple(int, int) or None	Figure size forwarded to the plotting function.	None
color	str	Color used for plotting the BNN mean curve.	'cyan'
alpha	float	Transparency for uncertainty or credible interval fills.	0.4
incertitude	bool	Whether to draw the ±σ uncertainty band around the mean curve.	True
sigma_length	int	Number of standard deviations for the uncertainty band.	1
Min_x	float or None	Optional x-axis limits; when both provided the axis limits are set.	None
Max_x	float or None	Optional x-axis limits; when both provided the axis limits are set.	None
Min_y	float or None	Optional y-axis limits; when both provided the axis limits are set.	None
Max_y	float or None	Optional y-axis limits; when both provided the axis limits are set.	None
invert_xaxis	bool	If True, the x-axis is inverted (IntCal convention).	True
domaine	(delta14c, c14, f14c)	Domain of radiocarbon quantities displayed.	'delta14c'
covariables	bool	Whether to use BNN predictions trained with covariates.	False
credible_interval	bool	If True, compute and plot pointwise credible intervals from predictive samples.	False
credible_interval_level	float	Credible interval level (e.g. 0.95 for 95% credible interval). Default 0.95.	0.95
credible_color	str or None	Color for the credible interval fill. If None the main color is used.	None
credible_alpha	float or None	Alpha transparency for the credible interval fill. If None alpha is used.	None

Returns:

Type	Description
None	The function produces a plot.

bnn_for_14C_calibration.calib_plot_functions.plot_individual_calibration_curve_part_2(xlabel='Calibrated dates (in years BP)', ylabel='Radiocarbon ages (in years BP)', add_grid=True, fontsize_legend='small', ax=None, figsize=None, color='cyan', alpha=0.4, incertitude=True, sigma_length=1, Min_x=None, Max_x=None, Min_y=None, Max_y=None, invert_xaxis=True, domaine=['delta14c', 'c14', 'f14c'][0], covariables=False, credible_interval=False, credible_interval_level=0.95, credible_color=None, credible_alpha=None)

Plot the BNN calibration curve (part 2) by calling add_individual_calibration_curve_part_2 and applying axis labels, grid, legend, and final display.

This function is a thin wrapper around add_individual_calibration_curve_part_2 and only handles visual elements such as xlabel, ylabel, grid and legend.

Parameters:

Name	Type	Description	Default
xlabel	str	Label for the x-axis.	'Calibrated dates (in years BP)'
ylabel	str	Label for the y-axis. Adjusted automatically if domaine is "delta14c" or "f14c".	'Radiocarbon ages (in years BP)'
add_grid	bool	Whether to display a grid on the plot.	True
fontsize_legend	str	Font size for the legend.	'small'
ax	Axes or None	Axis to draw on. If None, the axis internally created by add_individual_calibration_curve_part_2 is used.	None
figsize	tuple(int, int) or None	Figure size forwarded to the plotting function.	None
color	str	Color used for plotting the BNN mean curve.	'cyan'
alpha	float	Transparency for uncertainty or credible interval fills.	0.4
incertitude	bool	Whether to draw the ±σ uncertainty band around the mean curve.	True
sigma_length	int	Number of standard deviations for the uncertainty band.	1
Min_x	float or None	Optional x-axis limits; when both provided the axis limits are set.	None
Max_x	float or None	Optional x-axis limits; when both provided the axis limits are set.	None
Min_y	float or None	Optional y-axis limits; when both provided the axis limits are set.	None
Max_y	float or None	Optional y-axis limits; when both provided the axis limits are set.	None
invert_xaxis	bool	If True, the x-axis is inverted (IntCal convention).	True
domaine	(delta14c, c14, f14c)	Domain of radiocarbon quantities displayed.	'delta14c'
covariables	bool	Whether to use BNN predictions trained with covariates.	False
credible_interval	bool	If True, compute and plot pointwise credible intervals from predictive samples.	False
credible_interval_level	float	Credible interval level (e.g. 0.95 for 95% credible interval). Default 0.95.	0.95
credible_color	str or None	Color for the credible interval fill. If None the main color is used.	None
credible_alpha	float or None	Alpha transparency for the credible interval fill. If None alpha is used.	None

Returns:

Type	Description
None	The function produces a plot.

bnn_for_14C_calibration.calib_plot_functions.plot_bnn_calibration_curve(xlabel='Calendar dates (in years BP)', ylabel='Radiocarbon ages (in years BP)', add_grid=True, fontsize_legend='small', reset_margins=False, ax=None, figsize=None, color='cyan', alpha=0.4, incertitude=True, sigma_length=1, Min_x=None, Max_x=None, Min_y=None, Max_y=None, invert_xaxis=True, domaine=['delta14c', 'c14', 'f14c'][0], covariables=False, credible_interval=False, credible_interval_level=0.95, credible_color=None, credible_alpha=None)

Plot the full BNN-based calibration curve, including optional uncertainty visualization, credible intervals, grid, labels, and legend. This function acts as a convenience wrapper around add_bnn_calibration_curve, and automatically configures axis labels, grid display, margins, and legend formatting.

Parameters:

Name	Type	Description	Default
xlabel	str	X-axis label.	'Calendar dates (in years BP)'
ylabel	str	Y-axis label. Adjusted automatically if domaine is "delta14c" or "f14c".	'Radiocarbon ages (in years BP)'
add_grid	bool	If True, draw a grid behind the plot.	True
fontsize_legend	str	Legend font size (e.g., "small", "medium", "large").	'small'
reset_margins	bool	Whether to remove extra margins around the plotted data.	False
ax	Axes or None	Axis on which to draw the curves. If None, the axis is taken from add_bnn_calibration_curve.	None
figsize	tuple or None	Figure size passed to underlying plotting functions.	None
color	str	Color used for plotting the curve and uncertainty bands.	'cyan'
alpha	float	Transparency level for uncertainty shading and credible interval bands.	0.4
incertitude	bool	Whether to add the ±σ uncertainty band around the mean curve.	True
sigma_length	float	Width of the uncertainty band in standard deviations.	1
Min_x	float or None	Optional x-axis limits; when both provided the axis limits are set.	None
Max_x	float or None	Optional x-axis limits; when both provided the axis limits are set.	None
Min_y	float or None	Optional y-axis limits; when both provided the axis limits are set.	None
Max_y	float or None	Optional y-axis limits; when both provided the axis limits are set.	None
invert_xaxis	bool	Whether to invert the x-axis (used for IntCal-style plots).	True
domaine	(delta14c, c14, f14c)	Domain of radiocarbon quantities displayed.	'delta14c'
covariables	bool	Whether to use BNN predictions trained with covariates; influences legend content.	False
credible_interval	bool	Whether to compute and display credible intervals for the BNN predictions.	False
credible_interval_level	float	Credible interval level (e.g., 0.95 for 95% CI).	0.95
credible_color	str or None	Color of the credible interval shading (defaults to color).	None
credible_alpha	float or None	Transparency of the credible interval shading (defaults to alpha).	None

Returns:

Type	Description
None	The function produces a plot.

bnn_for_14C_calibration.calib_plot_functions.plot_IntCal20_curve(xlabel='Calibrated dates (years BP)', ylabel='Radiocarbon ages (years BP)', add_grid=True, fontsize_legend='small', reset_margins=False, ax=None, figsize=None, color='green', alpha=0.4, incertitude=True, sigma_length=1, Min_x=None, Max_x=None, Min_y=None, Max_y=None, invert_xaxis=True, domaine='delta14c')

Plot the IntCal20 calibration curve in the chosen radiocarbon domain.

Parameters:

Name	Type	Description	Default
xlabel	str	X-axis label.	'Calibrated dates (years BP)'
ylabel	str	Y-axis label. Adjusted automatically if domaine is "delta14c" or "f14c".	'Radiocarbon ages (years BP)'
add_grid	bool	If True, draw a grid behind the plot.	True
fontsize_legend	int or str	Font size passed to matplotlib’s legend.	'small'
reset_margins	bool	If True, reset axis margins to zero.	False
ax	Axes or None	Existing axis onto which the curve is drawn. If None, a new one is created.	None
figsize	tuple(int, int)	Figure size passed to matplotlib.	None
color	str	Color of the IntCal20 curve.	'green'
alpha	float	Transparency for the uncertainty band.	0.4
incertitude	bool	If True, display the ±σ IntCal20 uncertainty envelope.	True
sigma_length	int	Number of sigma widths for the uncertainty envelope.	1
Min_x	float or None	Optional x-axis limits; when both provided the axis limits are set.	None
Max_x	float or None	Optional x-axis limits; when both provided the axis limits are set.	None
Min_y	float or None	Optional y-axis limits; when both provided the axis limits are set.	None
Max_y	float or None	Optional y-axis limits; when both provided the axis limits are set.	None
invert_xaxis	bool	If True, invert X axis (IntCal standard orientation).	True
domaine	(delta14c, c14, f14c)	Domain in which to express radiocarbon values.	'delta14c'

Returns:

Type	Description
None