Causal Model in pyAgrum

Causality in pyAgrum primarily involves building a causal model—that is, constructing an (observational) Bayesian network along with a set of latent variables and defining their relationships with observed variables. It also includes the ability to compute causal effects in such models using do-calculus.

pyAgrum provides a set of tools to perform causal inference and estimate causal effects from data. This includes the ability to identify interventions, compute causal impacts, and evaluate the effects of interventions on observed variables.

Note

The causal module can use a LaTeX special arrow ($\hookrightarrow$) to compactly represent an intervention. By default, it uses the classical “do” notation. You can change this behavior using the following configuration keys:

pyagrum.config["causal","latex_do_prefix"]="\hookrightarrow("
pyagrum.config["causal","latex_do_suffix"]=")"

A pyagrum.CausalModel extends a pyagrum.BayesNet with latent (hidden) variables and explicit causal assumptions. It is the entry point for do-calculus reasoning and causal effect identification.

SEE ALSO

Causal computation in pyAgrum : Functions for computing causal impacts and applying do-calculus.

class pyagrum.CausalModel(*args)

A causal model pairing an observational Bayesian network with a causal DAG.

A CausalModel extends an observational BayesNet by adding latent (hidden) variables that represent unobserved common causes between observed variables. The causal DAG includes both observed and latent nodes, while the observational BN contains only the observed ones.

CausalModel(bn) -> CausalModel : Parameters: : - bn (pyagrum.BayesNet) – the observational Bayesian network.

CausalModel(bn, latents, assumeNonSpurious=False) -> CausalModel : Parameters: : - bn (pyagrum.BayesNet) – the observational Bayesian network. - latents (list of (str, list of str)) – description of latent variables. Each entry is a pair (name, children) where name is the latent variable name and children is the list of observed variable names it affects. - assumeNonSpurious (bool) – if True, existing arcs between the children of each latent variable are preserved. Default is False (arcs between affected children are removed as they are assumed to be explained by the latent confounder).

Examples

>>> import pyagrum as gum
>>> bn = pyagrum.BayesNet.fastPrototype('X->Y;X->Z;Y->Z')
>>> cm = pyagrum.CausalModel(bn)

Create a model with a latent confounder U between X and Y:

>>> cm = pyagrum.CausalModel(bn, [('U', ['X', 'Y'])], assumeNonSpurious=False)

addLatentVariable(*args)

Add a latent (hidden) variable to the causal model.

The latent variable is added as a common cause of the specified children. By default, any existing arc between two affected children is removed, as it is assumed to be explained by the new latent confounder.

• Parameters:
  • name (str) – Name of the new latent variable.
  • children (list of str) – Names of the observed variables that are children of this latent variable.
  • assumeNonSpurious (bool , optional) – If True, preserve existing arcs between the specified children. Default is False.
• Return type: None

assumeNonSpurious(*args)

Mark an arc in the causal DAG as non-spurious (a genuine causal effect).

• Parameters:
  • x (int or str) – Tail of the arc (NodeId or variable name).
  • y (int or str) – Head of the arc (NodeId or variable name).
• Return type: None

assumeSpurious(*args)

Mark an arc in the causal DAG as spurious.

A spurious arc x→y means the observed correlation between x and y is believed to be explained by a latent common cause rather than a direct causal effect. This changes the structural interpretation but does not remove the arc.

• Parameters:
  • x (int or str) – Tail of the arc (NodeId or variable name).
  • y (int or str) – Head of the arc (NodeId or variable name).
• Return type: None

backDoor(*args)

Find a backdoor adjustment set between cause and effect.

Returns the first valid backdoor adjustment set found. A backdoor set Z blocks all spurious (non-causal) paths between cause and effect while leaving all directed causal paths open, enabling estimation of the causal effect P(effect | do(cause)) via standard conditioning on Z.

• Parameters:
  • cause (int or str) – The treatment variable (NodeId or variable name).
  • effect (int or str) – The outcome variable (NodeId or variable name).
• Returns: A valid backdoor adjustment set as NodeIds, or None if no backdoor set exists. Note: an empty set is a valid backdoor (returned when X has no back-door paths); None means the causal effect cannot be identified via the backdoor criterion.
• Return type: list[int] | None

SEE ALSO

pyagrum.DoorCriteria.enumerateBackdoorSets : enumerate all valid sets.

causalBN()

causalDAG()

Return the full causal DAG, including latent variables.

• Returns: The causal DAG (observed + latent nodes).
• Return type: DAG

children(*args)

Return the children of a variable in the causal DAG.

• Parameters: x (int or str) – The variable (NodeId or name).
• Returns: NodeIds of the variable’s children in the causal DAG.
• Return type: list[int]

connectedComponents()

Return the connected components of the causal DAG (treating arcs as undirected).

• Returns: A mapping from component index to the set of NodeIds in that component.
• Return type: dict[int, list[int]]

existsArc(*args)

Check whether an arc exists in the causal DAG.

• Parameters:
  • x (int or str) – Tail of the arc (NodeId or variable name).
  • y (int or str) – Head of the arc (NodeId or variable name).
• Returns: True if the arc x→y exists in the causal DAG.
• Return type: bool

frontDoor(*args)

Find a frontdoor adjustment set between cause and effect.

Returns the first valid frontdoor adjustment set found. A frontdoor set Z intercepts all directed paths from cause to effect and enables estimation of P(effect | do(cause)) even in the presence of unobserved confounders.

• Parameters:
  • cause (int or str) – The treatment variable (NodeId or variable name).
  • effect (int or str) – The outcome variable (NodeId or variable name).
• Returns: A valid frontdoor adjustment set as NodeIds, or None if no frontdoor set exists. Note: an empty set is a valid frontdoor in degenerate cases; None means the causal effect cannot be identified via the frontdoor criterion.
• Return type: list[int] | None

SEE ALSO

pyagrum.DoorCriteria.enumerateFrontdoorSets : enumerate all valid sets.

idFromName(name)

Return the NodeId of a variable by name.

• Parameters: name (str) – The variable name.
• Returns: The NodeId of the variable.
• Return type: int
• Raises: pyagrum.NotFound – If no variable with that name exists in the causal model.

inducedCausalSubModel(cm, subset)

Return the causal sub-model induced by a subset of observed nodes.

The sub-model is restricted to the specified nodes, preserving the relevant portion of the causal DAG and latent structure.

• Parameters:
  • cm (CausalModel) – The original causal model.
  • subset (list[int]) – NodeIds of the observed variables to keep.
• Returns: The induced causal sub-model.
• Return type: CausalModel

isAssumedSpurious(*args)

Check whether the arc x→y is assumed spurious.

• Parameters:
  • x (int or str) – Tail of the arc (NodeId or variable name).
  • y (int or str) – Head of the arc (NodeId or variable name).
• Returns: True if the arc x→y is marked as spurious.
• Return type: bool

latentVariablesIds()

Return the NodeIds of all latent (hidden) variables in the causal model.

• Returns: NodeIds of latent variables.
• Return type: list[int]

latentVariablesNames()

Return the names of all latent (hidden) variables in the causal model.

• Returns: Names of latent variables.
• Return type: set[str]

nameFromId(id)

Return the name of a variable by NodeId.

• Parameters: id (int) – The NodeId of the variable.
• Returns: The variable name.
• Return type: str
• Raises: pyagrum.NotFound – If no variable with that NodeId exists in the causal model.

names()

Return the names of all variables in the causal model (observed and latent).

• Returns: The set of all variable names.
• Return type: set[str]

observationalBN()

Return the observational Bayesian network underlying the causal model.

Warning

Do not use this BN for causal inference. It represents the observational distribution only. Use pyagrum.causalImpact() for interventional queries.

• Returns: The observational BN (observed variables only).
• Return type: BayesNet

parents(*args)

Return the parents of a variable in the causal DAG.

• Parameters: x (int or str) – The variable (NodeId or name).
• Returns: NodeIds of the variable’s parents in the causal DAG.
• Return type: list[int]

toDot(*args)

Return a Graphviz dot string representing the causal model.

Observed nodes are shown with default styling. Latent nodes are displayed with a distinct background colour. Their names are hidden by default.

• Parameters:
  • SHOW_LATENT_NAMES (bool , optional) – If True, display the names of latent nodes in the graph. Default is False.
  • NODE_BG (str , optional) – Background colour for latent nodes (hex or CSS colour name). Default is ‘#404040’.
  • NODE_FG (str , optional) – Text colour for latent nodes. Default is ‘white’.
  • EDGE_COL (str , optional) – Edge colour. Default is ‘#4A4A4A’.
• Returns: A dot-format string representation of the causal model.
• Return type: str

Examples

>>> import pyagrum as gum
>>> bn = pyagrum.BayesNet.fastPrototype('X->Y->Z')
>>> cm = pyagrum.CausalModel(bn)
>>> print(cm.toDot())

variable(*args)

• Return type: DiscreteVariable