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 notebooks/99-Tools_configForPyAgrum.

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`
`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`
`histogram_epsilon`	`float`	`1e-8`	probabilities below this threshold are truncated in histograms
`tensor_parent_values`	`merge	revmerge	nomerge`
`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`
`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`
`graph_layout`	`dot	neato	fdp
`default_markovrandomfield_view`	`graph	factorgraph`	`factorgraph`
`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

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
`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)

Configuration for pyAgrum

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

add_hook(fn)

diff()

doc(section, option)

get(section, option)

getTyped(section, option)

grep(search)

load()

pop()

push()

reset()

run_hooks()

save()

schema()

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

Configuration reference

Section [core]

Section [notebook]

Section [factorgraph]

Section [dynamicBN]

Section [influenceDiagram]

Section [credalnet]

Section [causal]

Section [ROC]

Section [ctbn]

Section [bnmixture]

Deprecated keys

Section `[core]`

Section `[notebook]`

Section `[factorgraph]`

Section `[dynamicBN]`

Section `[influenceDiagram]`

Section `[credalnet]`

Section `[causal]`

Section `[ROC]`

Section `[ctbn]`

Section `[bnmixture]`