Configuration for pyAgrum

Configuration for pyAgrum is centralized in an object pyagrum.config, singleton of the (hidden) class PyAgrumConfiguration.

Each key is declared in the defaults with a metadata line ### type :: documentation where the type is int, float, bool, str, an enumeration of the allowed values (svg|png) or a deprecation (deprecated -> section.key). The setter refuses any value that does not respect the declared type and canonicalizes boolean values (any accepted spelling such as yes/on/1 is stored as True or False) as well as enumerated values (stored with their declared casing). config.typed[section, key] gives the value converted according to the declared type, and accessing a deprecated key emits a DeprecationWarning while transparently using its replacement.

See also the tutorial gum.config :the configuration object for pyAgrum.

class pyagrum.config.PyAgrumConfiguration(*args, **kwargs)

PyAgrumConfiguration is a the pyAgrum configuration singleton. The configuration is build as a classical ConfigParser with read-only structure. Then a value is adressable using a double key: [section,key].

Each key is described in defaults.ini by a metadata line ### type :: documentation where type is int, float, bool, str, an enumeration v1|v2|... or a deprecation deprecated -> section.key. Setting a value that does not respect the declared type raises a ValueError. Accessing a deprecated key emits a DeprecationWarning and transparently uses the replacement key. While values are always stored as strings, config.typed[section, key] gives the value converted according to the declared type. Boolean and enumerated values are canonicalized when set: any accepted boolean spelling (yes/on/1/…) is stored as True or False, an enumerated value is stored with the casing declared in defaults.ini.

See this notebook.

Examples

>>> import pyagrum
>>> pyagrum.config["dynamicBN", "default_graph_size"] = 10
>>> pyagrum.config["dynamicBN", "default_graph_size"]
"10"

add_hook(fn)

diff()

print the diff between actual configuration and the defaults. This is what is saved in the file pyagrum.ini by the method PyAgrumConfiguration.save()

doc(section, option)

Give the type and the one-line documentation declared for section.option in defaults.

Examples

>>> pyagrum.config.doc("notebook", "tensor_visible_digits")
"int :: number of visible digits when displaying a tensor"

Parameters:

• section (str) – The section.

• option (str) – The property.

Returns:

The metadata as type :: documentation (deprecated -> section.key :: documentation for a deprecated key).

Return type:

str

Raises:

SyntaxError – If the section name or the property name does not exist.

get(section, option)

Give the value associated to section.option. Preferably use __getitem__ and __setitem__.

Examples

>>> pyagrum.config["dynamicBN", "default_graph_size"] = 10
>>> pyagrum.config["dynamicBN", "default_graph_size"]
"10"

Parameters:

• section (str) – The section.

• option (str) – The property.

Returns:

The value (as string).

Return type:

str

getTyped(section, option)

Give the value associated to section.option, converted according to the type declared in defaults: int and float are converted, bool gives a Python bool, enumerations and str stay strings. Preferably use the typed accessor: config.typed[section, option].

Examples

>>> pyagrum.config.typed["notebook", "tensor_visible_digits"]
4
>>> pyagrum.config.typed["notebook", "tensor_with_colors"]
True

Parameters:

• section (str) – The section.

• option (str) – The property.

Returns:

The value, converted according to the declared type.

Return type:

int | float | bool | str

grep(search)

grep in the configuration any section or property matching the argument. If a section matches the argument, the whole section is displayed.

Parameters:

search (str) – The string to find.

load()

load pyagrum.ini in the current directory, and change the properties if needed. If pyagrum.ini contains deprecated keys or invalid values, a warning is emitted and pyagrum.ini is rewritten (deprecated keys migrated to their replacement, invalid values removed).

Raises:

FileNotFoundError – If there is no pyagrum.ini in the current directory.

pop()

Pop the last config from the stack and set it as the current configuration

push()

Push the current configuration in the stack

reset()

back to defaults

run_hooks()

save()

Save the diff with the defaults in pyagrum.ini in the current directory

schema()

Iterate over the whole configuration schema (in the order of the defaults).

Examples

>>> for section, option, meta, default in pyagrum.config.schema():
...   print(f"{section}.{option} ({meta.kind}) = {default} : {meta.doc}")

Yields:

Tuple[str, str, ConfigMetadata, Optional[str]] – section, option, the metadata of the key (type, allowed values, documentation, deprecation target) and its default value (None for a deprecated key).

set(section, option, value, no_hook=False)

set a property in a section. Preferably use __getitem__ and __setitem__.

Examples

>>> pyagrum.config["dynamicBN", "default_graph_size"] = 10
>>> pyagrum.config["dynamicBN", "default_graph_size"]
"10"

Parameters:

• section (str) – The section name (has to exist in defaults).

• option (str) – The option/property name (has to exist in defaults).

• value (str) – The value (will be stored as string).

• no_hook (bool, optional) – Should this call trigger the hooks?

Raises:

• SyntaxError – If the section name or the property name does not exist.

• ValueError – If the value does not respect the type declared for this key in defaults.

Configuration reference

Section [core]

Key	Type	Default	Description
default_maxnumberofthreads	int	24	default maximum number of threads used by aGrUM
default_jgumindent	int	-1	default indentation when exporting a model to JGum (-1 = compact)
allow_modification_when_saving	bool	False	allow to fix syntax errors in a model instead of raising when exporting to external format (BIF, etc.)

Section [notebook]

Key	Type	Default	Description
tensor_visible_digits	int	4	number of visible digits when displaying a tensor
tensor_with_colors	bool	True	use a background color gradient for the values in a tensor
tensor_color_0	str	#FF7F64	color for the minimal value of a tensor
tensor_color_1	str	#7FFF64	color for the maximal value of a tensor
tensor_with_fraction	bool	False	display the values of a tensor as fractions when possible
tensor_fraction_limit	int	50	maximal denominator for the fraction representation in a tensor
tensor_fraction_round_error	float	1e-6	maximal rounding error when looking for a fraction representation
tensor_fraction_with_latex	bool	True	use LaTeX to render the fractions in a tensor
histogram_horizontal_visible_digits	int	2	number of visible digits in horizontal histograms
histogram_vertical_visible_digits	int	2	number of visible digits in vertical histograms
histogram_horizontal_threshold	int	8	maximal domain size for a horizontal histogram (vertical above)
histogram_line_threshold	int	40	domain size above which a histogram becomes a line plot
histogram_color	str	darkseagreen	color of the histogram bars
histogram_edge_color	str	darkgreen	color of the edges of the histogram bars
histogram_use_percent	bool	True	display probabilities as percentages in histograms
histogram_discretized_visualisation	histogram|bar	histogram	visualisation of the histogram for a discretized variable
histogram_discretized_scale	float	1.0	scale for the histogram of a discretized variable
export_pdf_margin_x	int	50	horizontal margin (in points) when exporting to pdf
export_pdf_margin_y	int	37	vertical margin (in points) when exporting to pdf
histogram_mode	compact|classical	compact	mode for displaying histograms
histogram_epsilon	float	1e-8	probabilities below this threshold are truncated in histograms
tensor_parent_values	merge|revmerge|nomerge	merge	how to display the parent values in a tensor
figure_facecolor	str	#E0E0E0	face color of the matplotlib figures (see matplotlib)
flow_background_color	str	transparent	background color of an item in a flow
flow_border_color	str	transparent	border color of an item in a flow
flow_border_width	int	0	border width (in pixels) of an item in a flow
graph_format	svg|png	svg	format used to render graphs in a notebook
show_inference_time	bool	True	display the inference time below an inference graph
default_arc_color	str	#4A4A4A	default color of the arcs
default_node_bgcolor	str	#404040	default background color of the nodes
default_node_fgcolor	str	white	default font color of the nodes
evidence_bgcolor	str	sandybrown	background color of a node with evidence
evidence_fgcolor	str	black	font color of a node with evidence
default_node_cmap	str	Pastel1	matplotlib color map for the nodes
default_arc_cmap	str	BuGn	matplotlib color map for the arcs
default_edge_cmap	str	BuGn	matplotlib color map for the edges
default_graph_size	str	5	default size (in inches) of a graph (graphviz size, e.g. “5” or “12!” for exact size)
default_graph_inference_size	str	8	default size (in inches) of a graph during inference (graphviz size, e.g. “8” or “12!”)
graph_rankdir	TB|LR	TB	direction of the graph layout (top-bottom or left-right)
graph_layout	dot|neato|fdp|sfdp|twopi|circo|nop|nop2|osage|patchwork	dot	graphviz layout engine
default_markovrandomfield_view	graph|factorgraph	factorgraph	default view for a Markov random field
junctiontree_graph_size	str	10	size (in inches) of a junction tree (graphviz size, e.g. “10” or “12!”)
junctiontree_with_names	bool	True	show the variable names in the cliques of a junction tree
junctiontree_separator_bgcolor	str	palegreen	background color of the separators of a junction tree
junctiontree_separator_fgcolor	str	black	font color of the separators of a junction tree
junctiontree_separator_fontsize	int	8	font size of the separators of a junction tree
junctiontree_clique_bgcolor	str	burlywood	background color of the cliques of a junction tree
junctiontree_clique_fgcolor	str	black	font color of the cliques of a junction tree
junctiontree_clique_fontsize	int	10	font size of the cliques of a junction tree
junctiontree_map_cliquescale	float	0.3	scale of the cliques in a junction tree map
junctiontree_map_sepscale	float	0.1	scale of the separators in a junction tree map
junctiontree_map_edgelen	float	1	length of the edges in a junction tree map
junctiontree_map_size	str	10	size (in inches) of a junction tree map (graphviz size, e.g. “10” or “12!”)
graphdiff_missing_style	str	dashed	style of an arc missing in the compared graph
graphdiff_missing_color	str	red	color of an arc missing in the compared graph
graphdiff_overflow_style	str	dashed	style of an arc absent from the reference graph
graphdiff_overflow_color	str	purple	color of an arc absent from the reference graph
graphdiff_reversed_style	str	solid	style of an arc reversed in the compared graph
graphdiff_reversed_color	str	purple	color of an arc reversed in the compared graph
graphdiff_correct_style	str	solid	style of an arc identical in both graphs
graphdiff_correct_color	str	grey	color of an arc identical in both graphs

Section [factorgraph]

Key	Type	Default	Description
default_node_bgcolor	str	coral	default background color of the variable nodes
default_node_fgcolor	str	black	default font color of the variable nodes
default_factor_bgcolor	str	burlywood	default background color of the factor nodes
edge_length	float	0.7	length of the edges in a factor graph
edge_length_inference	float	0.9	length of the edges in a factor graph during inference
graph_layout	dot|neato|fdp|sfdp|twopi|circo|nop|nop2|osage|patchwork	neato	graphviz layout engine

Section [dynamicBN]

Key	Type	Default	Description
default_graph_size	str	6	default size (in inches) of a dynamic BN (graphviz size, e.g. “6” or “12!”)

Section [influenceDiagram]

Key	Type	Default	Description
default_graph_size	str	6	default size (in inches) of an influence diagram (graphviz size, e.g. “6” or “12!”)
default_chance_bgcolor	str	#808080	default background color of the chance nodes
default_chance_fgcolor	str	white	default font color of the chance nodes
default_utility_bgcolor	str	#50508A	default background color of the utility nodes
default_utility_fgcolor	str	white	default font color of the utility nodes
default_decision_bgcolor	str	#9A5050	default background color of the decision nodes
default_decision_fgcolor	str	white	default font color of the decision nodes
chance_shape	str	ellipse	graphviz shape of the chance nodes
utility_shape	str	hexagon	graphviz shape of the utility nodes
decision_shape	str	box	graphviz shape of the decision nodes
decision_arc_style	str	tapered, bold, dotted	graphviz style of the arcs pointing to a decision node
utility_arc_style	str	dashed	graphviz style of the arcs pointing to a utility node
default_id_size	str	6	default size (in inches) of an influence diagram (graphviz size, e.g. “6” or “12!”)
default_id_inference_size	str	6	default size (in inches) of an influence diagram during inference (graphviz size, e.g. “6” or “12!”)
utility_visible_digits	int	2	number of visible digits when displaying a utility
utility_show_stdev	bool	True	show the standard deviation together with a utility
utility_show_loss	bool	False	show the loss (negative utility) instead of the utility

Section [credalnet]

Key	Type	Default	Description
default_node_bgcolor	str	#404040	default background color of the nodes
default_node_fgcolor	str	white	default font color of the nodes
histo_max_color	str	#BBFFAA	color for the maximal value in a credal set histogram

Section [causal]

Key	Type	Default	Description
show_latent_names	bool	False	show the names of the latent variables
latex_do_prefix	str	\text{do}(	LaTeX command inserted before an intervention (do) in a formula
latex_do_suffix	str	)	LaTeX command inserted after an intervention (do) in a formula
default_graph_size	str	2.5	default size (in inches) of a causal model (graphviz size, e.g. “2.5” or “12!”)
default_node_bgcolor	str	#404040	default background color of the nodes
default_node_fgcolor	str	white	default font color of the nodes
default_latent_bgcolor	str	#A08080	default background color of the latent nodes
default_latent_fgcolor	str	black	default font color of the latent nodes

Section [ROC]

Key	Type	Default	Description
draw_color	str	#008800	color of the ROC/PR curve
fill_color	str	#AAEEAA	color of the area under the ROC/PR curve

Section [ctbn]

Key	Type	Default	Description
show_latent_names	bool	False	show the names of the latent variables
default_graph_size	str	2.5	default size (in inches) of a CTBN (graphviz size, e.g. “2.5” or “12!”)
default_node_bgcolor	str	#404040	default background color of the nodes
default_node_fgcolor	str	white	default font color of the nodes
default_latent_bgcolor	str	#A08080	default background color of the latent nodes
default_latent_fgcolor	str	black	default font color of the latent nodes

Section [bnmixture]

Key	Type	Default	Description
default_graph_size	str	5	default size (in inches) of a BN mixture (graphviz size, e.g. “5” or “12!”)
default_line_size	float	1.0	default width of the arcs
default_head_size	float	0.25	default size of the arrow heads
default_arrow_type	str	normal	graphviz type of the arrow heads
default_arc_cmap	str	Greens	matplotlib color map for the arcs
default_arc_color	str	#4A4A4A	default color of the arcs
default_arc_style	str	solid	graphviz style of the arcs
default_node_bgcolor	str	#404040	default background color of the nodes
default_node_fgcolor	str	white	default font color of the nodes
default_layout	dot|neato|fdp|sfdp|twopi|circo|nop|nop2|osage|patchwork	fdp	graphviz layout engine
default_overlap	float	0	overlap scaling for the graphviz layout
default_bar_capsize	float	1.5	size of the caps on the error bars
default_bar_height	float	0.8	height of the bars in the bar plots
default_boot_histo_scale	float	2.0	scale for the bootstrap histograms
default_histo_scale	float	1.0	scale for the histograms
correct_arc_style	str	solid	graphviz style of an arc present in the reference BN
correct_arc_color	str	green	color of an arc present in the reference BN
incorrect_arc_style	str	dashed	graphviz style of an arc absent from the reference BN
incorrect_arc_color	str	green	color of an arc absent from the reference BN
left_quantile	float	0.2	lower quantile used when displaying the distribution of parameters
right_quantile	float	0.8	upper quantile used when displaying the distribution of parameters

Deprecated keys

(none)