A causal model pairing an observational BayesNet with a causal DAG. More...

#include <causalModel.h>

Collaboration diagram for gum::CausalModel< GUM_SCALAR >:

Public Member Functions
	CausalModel ()=delete
	Default constructor disabled: a causal model must be built from a BN.
	CausalModel (const BayesNet< GUM_SCALAR > &observationalBN)
	Construct a causal model with no latent variables.
	CausalModel (const BayesNet< GUM_SCALAR > &observationalBN, const LatentDescriptorVector &latentVarsDescriptor, bool assumeNonSpurious=false)
	Construct a causal model and add a list of latent confounders.
	CausalModel (const CausalModel &other)
	Copy constructor.
	CausalModel (CausalModel &&other) noexcept
	Move constructor.
	~CausalModel ()
	Destructor.
CausalModel &	operator= (const CausalModel &other)=default
	Copy assignment.
CausalModel &	operator= (CausalModel &&other) noexcept=default
	Move assignment.
void	addLatentVariable (std::string_view latentName, const std::vector< std::string > &childrenOfLatent, bool assumeNonSpurious=false)
	Add a latent variable by names of its observed children.
void	addLatentVariable (std::string_view latentName, const std::vector< NodeId > &childrenOfLatent, bool assumeNonSpurious=false)
	Add a latent variable by NodeIds of its observed children.
bool	existsArc (NodeId x, NodeId y) const
	Whether a causal arc x → y exists (by ids) in the causal DAG.
bool	existsArc (std::string_view x, std::string_view y) const
	Whether a causal arc x → y exists (by names) in the causal DAG.
void	assumeSpurious (NodeId x, NodeId y)
	Mark an arc as spurious: present in observationalBN, removed from causalDAG.
void	assumeSpurious (std::string_view x, std::string_view y)
void	assumeNonSpurious (NodeId x, NodeId y)
	Mark an arc as non-spurious: present in observationalBN, added to causalDAG.
void	assumeNonSpurious (std::string_view x, std::string_view y)
bool	isAssumedSpurious (NodeId x, NodeId y) const
	Returns true if arc is present in observationalBN and absent in causalDAG.
bool	isAssumedSpurious (std::string_view x, std::string_view y) const
std::optional< NodeSet >	backDoor (NodeId cause, NodeId effect) const
	Find a backdoor adjustment set (Z) between cause and effect (IDs only).
std::optional< NodeSet >	backDoor (std::string_view cause, std::string_view effect) const
std::optional< NodeSet >	frontDoor (NodeId cause, NodeId effect) const
	Find a frontdoor adjustment set (Z) between cause and effect (IDs only).
std::optional< NodeSet >	frontDoor (std::string_view cause, std::string_view effect) const
	Find a frontdoor adjustment set (Z) between cause and effect (IDs only).
CausalModel< GUM_SCALAR >	inducedCausalSubModel (const CausalModel< GUM_SCALAR > &cm, NodeSet subset) const
	Induced causal submodel on a subset of nodes.
std::string	toDot (const bool SHOW_LATENT_NAMES=false, const char NODE_BG="#404040", const char NODE_FG="white", const char *EDGE_COL="#4A4A4A") const
	DOT representation of the causal DAG (observed + latent).
const BayesNet< GUM_SCALAR > &	observationalBN () const
	Observational BN (observed variables only).
DAG	causalDAG () const
	Causal DAG (observed + latent variables), with node names set.
Set< std::string >	names () const
	All variable names appearing in the causal model (observed + latent).
NodeId	idFromName (std::string_view name) const
	Node id from variable name (observed or latent).
std::string	nameFromId (NodeId id) const
	Variable name from node id (observed or latent).
Bijection< NodeId, std::string >	id2name (bool includeLatentVariable=false) const
	Bidirectional mapping between node ids and variable names.
NodeSet	latentVariablesIds () const
	Node ids of all latent variables.
Set< std::string >	latentVariablesNames () const
	Names of all latent variables.
NodeSet	parents (NodeId x) const
	Parents of a node (by id) in the causal DAG (including latents).
NodeSet	parents (std::string_view name) const
	Parents of a node (by name) in the causal DAG (including latents).
NodeSet	children (NodeId x) const
	Children of a node (by id) in the causal DAG (including latents).
NodeSet	children (std::string_view name) const
	Children of a node (by name) in the causal DAG (including latents).
HashTable< NodeId, NodeSet >	connectedComponents () const
	Weakly connected components of the causal DAG.
const DiscreteVariable &	variable (NodeId id) const
	From id to variable (observed only, by id).
const DiscreteVariable &	variable (std::string_view name) const
	From name to variable (observed only, by id).

Private Attributes
BayesNet< GUM_SCALAR >	_observationalBN_
	The underlying BayesNet representing the observed part of the model.
DAG	_causalDAG_
	The underlying DAG representing the causal structure (observed + latent).
Bijection< NodeId, std::string >	_ids_names_
	Bidirectional mapping between node ids and variable names (observed + latent).

Detailed Description

template<GUM_Numeric GUM_SCALAR>
class gum::CausalModel< GUM_SCALAR >

A causal model pairing an observational BayesNet with a causal DAG.

The class is DAG-centric for causality: all causal-structure queries and edits happen on _causalDAG_, which may include latent variables that do not appear in _observationalBN_. Name/Id bookkeeping is handled so you can work with either.

Invariants / expectations

_observationalBN_ corresponds to the observed part (no latents).
_causalDAG_ contains all observed variables and any added latent variables.
When adding a latent with children, the latent becomes a parent of all listed children in the causal DAG. The assumeNonSpurious flag controls whether existing arcs between those children are preserved or may be adjusted (implementation dependent).

Definition at line 84 of file causalModel.h.

Constructor & Destructor Documentation

◆ CausalModel() [1/5]

template<GUM_Numeric GUM_SCALAR>

gum::CausalModel< GUM_SCALAR >::CausalModel ( )

delete

Default constructor disabled: a causal model must be built from a BN.

References CausalModel(), assumeNonSpurious(), and observationalBN().

Referenced by CausalModel(), CausalModel(), CausalModel(), CausalModel(), CausalModel(), ~CausalModel(), operator=(), and operator=().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ CausalModel() [2/5]

template<GUM_Numeric GUM_SCALAR>

gum::CausalModel< GUM_SCALAR >::CausalModel ( const BayesNet< GUM_SCALAR > & observationalBN )

explicit

Construct a causal model with no latent variables.

Parameters

observationalBN the observed Bayesian network

Initializes the causal DAG as the BN's DAG (observed-only).

Definition at line 61 of file causalModel_tpl.h.

                                                                                      :
      _observationalBN_(observationalBN), _causalDAG_(observationalBN.internalDag()) {
    GUM_CONSTRUCTOR(CausalModel)
  }

References CausalModel(), _causalDAG_, _observationalBN_, and observationalBN().

Here is the call graph for this function:

◆ CausalModel() [3/5]

template<GUM_Numeric GUM_SCALAR>

gum::CausalModel< GUM_SCALAR >::CausalModel	(	const BayesNet< GUM_SCALAR > &	observationalBN,
		const LatentDescriptorVector &	latentVarsDescriptor,
		bool	assumeNonSpurious = false )

explicit

Construct a causal model and add a list of latent confounders.

Parameters

observationalBN	the observed Bayesian network
latentVarsDescriptor	list of (latentName, childrenIds) descriptors
assumeNonSpurious	whether to preserve existing arcs among the latent's children

Each latent is created and added as a parent of the provided children in the causal DAG. The observed BN remains unchanged.

Definition at line 72 of file causalModel_tpl.h.

                                                                                          :
      _observationalBN_(observationalBN), _causalDAG_(observationalBN.internalDag()) {
    // add each latent (children given as names)
    for (const auto& [latent, children]: latentVarsDescriptor) {
      addLatentVariable(latent, children, assumeNonSpurious);
    }
    GUM_CONSTRUCTOR(CausalModel)
  }

References CausalModel(), _causalDAG_, _observationalBN_, addLatentVariable(), assumeNonSpurious(), children(), and observationalBN().

Here is the call graph for this function:

◆ CausalModel() [4/5]

template<GUM_Numeric GUM_SCALAR>

gum::CausalModel< GUM_SCALAR >::CausalModel ( const CausalModel< GUM_SCALAR > & other )

Copy constructor.

Definition at line 85 of file causalModel_tpl.h.

                                                                 :
      _observationalBN_(other._observationalBN_), _causalDAG_(other._causalDAG_),
      _ids_names_(other._ids_names_) {
    GUM_CONS_CPY(CausalModel)
  };

References CausalModel(), _causalDAG_, _ids_names_, and _observationalBN_.

Here is the call graph for this function:

◆ CausalModel() [5/5]

template<GUM_Numeric GUM_SCALAR>

gum::CausalModel< GUM_SCALAR >::CausalModel ( CausalModel< GUM_SCALAR > && other )

noexcept

Move constructor.

Definition at line 93 of file causalModel_tpl.h.

                                                                     :
      _observationalBN_(std::move(other._observationalBN_)),
      _causalDAG_(std::move(other._causalDAG_)), _ids_names_(std::move(other._ids_names_)) {
    GUM_CONS_MOV(CausalModel)
  };

References CausalModel(), _causalDAG_, _ids_names_, and _observationalBN_.

Here is the call graph for this function:

◆ ~CausalModel()

template<GUM_Numeric GUM_SCALAR>

gum::CausalModel< GUM_SCALAR >::~CausalModel ( )

Destructor.

Definition at line 67 of file causalModel_tpl.h.

                                          {
    GUM_DESTRUCTOR(CausalModel)
  }

References CausalModel().

Here is the call graph for this function:

Member Function Documentation

◆ addLatentVariable() [1/2]

template<GUM_Numeric GUM_SCALAR>

void gum::CausalModel< GUM_SCALAR >::addLatentVariable	(	std::string_view	latentName,
		const std::vector< NodeId > &	childrenOfLatent,
		bool	assumeNonSpurious = false )

Add a latent variable by **NodeId**s of its observed children.

Parameters

latentName	new latent variable name
childrenOfLatent	node ids of observed children
assumeNonSpurious	preserve existing arcs among the children if true.

A new latent node is inserted into the causal DAG and connected as a parent of each listed child. The observed BN is not modified.

Warning: When assumeNonSpurious == false and the latent has children \(\{X_1,\ldots,X_n\}\), any existing arcs \(X_i \rightarrow X_j\) among those children may be removed from the causal DAG. To preserve some child→child arcs while dropping others, consider creating separate latents: one with assumeNonSpurious = true for the subset to preserve, and another with assumeNonSpurious = false for the subset to drop. A finer-grained edit API may be added later.

Definition at line 117 of file causalModel_tpl.h.

                                                                            {
    // must have at least 2 children
    if (childrenOfLatent.size() < 2) {
      GUM_ERROR(InvalidArgument, "A latent variable must affect at least 2 children.");
    }
 
    // reject names that collide with observed or existing latent variables
    if (_observationalBN_.variableNodeMap().exists(latentName)) {
      GUM_ERROR(InvalidArgument,
                "Latent variable name conflicts with an observed variable: "
                    + std::string(latentName));
    }
    if (_ids_names_.existsSecond(std::string(latentName))) {
      GUM_ERROR(InvalidArgument,
                "Latent variable name already used by another latent: " + std::string(latentName));
    }
 
    // create a fresh node id for the latent in the causal DAG
    const NodeId id_latent = _causalDAG_.addNode();
 
    // record bookkeeping
    _ids_names_.insert(id_latent, std::string(latentName));
 
    // add arcs latent -> each child
    for (const auto& cid: childrenOfLatent) {
      // children are observed nodes: they must already exist in causal DAG (copied from observed
      // BN)
      _causalDAG_.addArc(id_latent, cid);
    }
 
    // remove any direct causal arc among children unless assumeNonSpurious=true
    if (!assumeNonSpurious) {
      for (auto i = childrenOfLatent.begin(); i != childrenOfLatent.end(); ++i) {
        auto j = i;
        ++j;
        for (auto jj = j; jj != childrenOfLatent.end(); ++jj) {
          const NodeId a = *i;
          const NodeId b = *jj;
          // remove either direction if present
          Arc ab(a, b), ba(b, a);
          if (_causalDAG_.existsArc(ab)) _causalDAG_.eraseArc(ab);
          else if (_causalDAG_.existsArc(ba)) _causalDAG_.eraseArc(ba);
        }
      }
    }
  }

References _observationalBN_, assumeNonSpurious(), and GUM_ERROR.

Here is the call graph for this function:

◆ addLatentVariable() [2/2]

template<GUM_Numeric GUM_SCALAR>

void gum::CausalModel< GUM_SCALAR >::addLatentVariable	(	std::string_view	latentName,
		const std::vector< std::string > &	childrenOfLatent,
		bool	assumeNonSpurious = false )

Add a latent variable by names of its observed children.

Parameters

latentName	new latent variable name
childrenOfLatent	names of observed children
assumeNonSpurious	preserve existing arcs among the children if true

A new latent node is inserted into the causal DAG and connected as a parent of each listed child. The observed BN is not modified.

Warning: When assumeNonSpurious == false and the latent has children \(\{X_1,\ldots,X_n\}\), any existing arcs \(X_i \rightarrow X_j\) among those children may be removed from the causal DAG. To preserve some child→child arcs while dropping others, consider creating separate latents: one with assumeNonSpurious = true for the subset to preserve, and another with assumeNonSpurious = false for the subset to drop. A finer-grained edit API may be added later.

Definition at line 104 of file causalModel_tpl.h.

                                                           {
    std::vector< NodeId > childIds;
    childIds.reserve(childrenOfLatent.size());
    for (const auto& nm: childrenOfLatent) {
      childIds.push_back(idFromName(nm));
    }
    addLatentVariable(latentName, childIds, assumeNonSpurious);
  }

References addLatentVariable(), assumeNonSpurious(), and idFromName().

Referenced by CausalModel(), and addLatentVariable().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ assumeNonSpurious() [1/2]

template<GUM_Numeric GUM_SCALAR>

void gum::CausalModel< GUM_SCALAR >::assumeNonSpurious	(	NodeId	x,
		NodeId	y )

Mark an arc as non-spurious: present in observationalBN, added to causalDAG.

Throws if arc is not present in observationalBN.

Definition at line 222 of file causalModel_tpl.h.

                                                                      {
    // Validate arc in observationalBN
    if (!_observationalBN_.internalDag().existsArc(Arc(x, y))) {
      GUM_ERROR(InvalidArgument,
                "Arc(" + std::to_string(x) + "," + std::to_string(y)
                    + ") not present in observationalBN");
    }
    // Add arc to causalDAG if absent
    if (!_causalDAG_.existsArc(Arc(x, y))) { _causalDAG_.addArc(x, y); }
  }

Referenced by CausalModel(), CausalModel(), addLatentVariable(), addLatentVariable(), assumeNonSpurious(), and operator=().

Here is the caller graph for this function:

◆ assumeNonSpurious() [2/2]

template<GUM_Numeric GUM_SCALAR>

void gum::CausalModel< GUM_SCALAR >::assumeNonSpurious	(	std::string_view	x,
		std::string_view	y )

Definition at line 234 of file causalModel_tpl.h.

                                                                                      {
    assumeNonSpurious(idFromName(x), idFromName(y));
  }

References assumeNonSpurious(), and idFromName().

Here is the call graph for this function:

◆ assumeSpurious() [1/2]

template<GUM_Numeric GUM_SCALAR>

void gum::CausalModel< GUM_SCALAR >::assumeSpurious	(	NodeId	x,
		NodeId	y )

Mark an arc as spurious: present in observationalBN, removed from causalDAG.

Throws if arc is not present in observationalBN.

Definition at line 205 of file causalModel_tpl.h.

                                                                   {
    // Validate arc in observationalBN
    if (!_observationalBN_.internalDag().existsArc(Arc(x, y))) {
      GUM_ERROR(InvalidArgument,
                "Arc(" + std::to_string(x) + "," + std::to_string(y)
                    + ") not present in observationalBN");
    }
    // Remove arc from causalDAG if present
    if (_causalDAG_.existsArc(Arc(x, y))) { _causalDAG_.eraseArc(Arc(x, y)); }
  }

References _causalDAG_, _observationalBN_, and GUM_ERROR.

Referenced by assumeSpurious().

Here is the caller graph for this function:

◆ assumeSpurious() [2/2]

template<GUM_Numeric GUM_SCALAR>

void gum::CausalModel< GUM_SCALAR >::assumeSpurious	(	std::string_view	x,
		std::string_view	y )

Definition at line 217 of file causalModel_tpl.h.

                                                                                   {
    assumeSpurious(idFromName(x), idFromName(y));
  }

References assumeSpurious(), and idFromName().

Here is the call graph for this function:

◆ backDoor() [1/2]

template<GUM_Numeric GUM_SCALAR>

std::optional< NodeSet > gum::CausalModel< GUM_SCALAR >::backDoor	(	NodeId	cause,
		NodeId	effect ) const

Find a backdoor adjustment set (Z) between cause and effect (IDs only).

Enumerates admissible backdoor sets in the current causal DAG (excluding latent variables) and returns the first valid one found. Returns std::nullopt if no backdoor set exists at all. Note: an empty set is a valid backdoor when X has no back-door paths.

Preconditions:

cause and effect must be observed variables of the model.

Parameters

cause	NodeId of the cause (X).
effect	NodeId of the effect (Y).

Returns: std::optional<NodeSet> The backdoor adjustment set (Z) as NodeIds, or std::nullopt if no backdoor set exists.

Definition at line 389 of file causalModel_tpl.h.

                                                                                              {
    // Preconditions: cause/effect must be observed (non-latent).
    const NodeSet lat = latentVariablesIds();
    if (lat.contains(cause) || lat.contains(effect)) {
      GUM_ERROR(InvalidArgument,
                "CausalModel::backDoor: 'cause' and 'effect' must be observed (non-latent).");
    }
 
    const auto candidates = DoorCriteria::enumerateBackdoorSets(_causalDAG_, cause, effect, lat);
    if (candidates.empty()) return std::nullopt;
    return candidates.front();   // first valid set (may itself be empty)
  }

References _causalDAG_, gum::Set< Key >::contains(), gum::DoorCriteria::enumerateBackdoorSets(), GUM_ERROR, and latentVariablesIds().

Referenced by backDoor().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ backDoor() [2/2]

template<GUM_Numeric GUM_SCALAR>

std::optional< NodeSet > gum::CausalModel< GUM_SCALAR >::backDoor	(	std::string_view	cause,
		std::string_view	effect ) const

Definition at line 562 of file causalModel_tpl.h.

                                                                                            {
    return backDoor(idFromName(cause), idFromName(effect));
  }

References backDoor(), and idFromName().

Here is the call graph for this function:

◆ causalDAG()

template<GUM_Numeric GUM_SCALAR>

DAG gum::CausalModel< GUM_SCALAR >::causalDAG ( ) const

Causal DAG (observed + latent variables), with node names set.

Definition at line 554 of file causalModel_tpl.h.

                                                 {
    DAG g = _causalDAG_;
    for (auto id: g)
      g.setName(id, nameFromId(id));
    return g;
  }

References _causalDAG_, nameFromId(), and gum::NodeGraphPart::setName().

Referenced by gum::DoCalculus< GUM_SCALAR >::_ID_().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ children() [1/2]

template<GUM_Numeric GUM_SCALAR>

NodeSet gum::CausalModel< GUM_SCALAR >::children ( NodeId x ) const

Children of a node (by id) in the causal DAG (including latents).

Definition at line 375 of file causalModel_tpl.h.

                                                            {
    return _causalDAG_.children(x);
  }

References _causalDAG_.

Referenced by CausalModel(), gum::DoCalculus< GUM_SCALAR >::_cDecomposition_(), and children().

Here is the caller graph for this function:

◆ children() [2/2]

template<GUM_Numeric GUM_SCALAR>

NodeSet gum::CausalModel< GUM_SCALAR >::children ( std::string_view name ) const

Children of a node (by name) in the causal DAG (including latents).

Definition at line 380 of file causalModel_tpl.h.

                                                                       {
    return children(idFromName(name));
  }

References children(), and idFromName().

Here is the call graph for this function:

◆ connectedComponents()

template<GUM_Numeric GUM_SCALAR>

HashTable< NodeId, NodeSet > gum::CausalModel< GUM_SCALAR >::connectedComponents ( ) const

Weakly connected components of the causal DAG.

Returns: A table mapping a representative NodeId to the NodeSet of nodes in its component.

Definition at line 261 of file causalModel_tpl.h.

                                                                                    {
    HashTable< NodeId, NodeSet > comps;
 
    // Build a mutable "remaining" set from the DAG's node view
    NodeSet remaining;
    for (auto n: _causalDAG_.nodes())
      remaining.insert(n);
 
    while (!remaining.empty()) {
      const NodeId root = *remaining.begin();
 
      NodeSet               cc;
      std::vector< NodeId > stack{root};
      remaining.erase(root);
 
      while (!stack.empty()) {
        const NodeId u = stack.back();
        stack.pop_back();
        cc.insert(u);
 
        // weak neighbours = parents ∪ children
        for (auto v: _causalDAG_.parents(u)) {
          if (remaining.contains(v)) {
            remaining.erase(v);
            stack.push_back(v);
          }
        }
        for (auto v: _causalDAG_.children(u)) {
          if (remaining.contains(v)) {
            remaining.erase(v);
            stack.push_back(v);
          }
        }
      }
 
      comps.insert(root, std::move(cc));
    }
 
    return comps;
  }

References _causalDAG_, gum::Set< Key >::begin(), gum::Set< Key >::empty(), and gum::Set< Key >::insert().

Here is the call graph for this function:

◆ existsArc() [1/2]

template<GUM_Numeric GUM_SCALAR>

bool gum::CausalModel< GUM_SCALAR >::existsArc	(	NodeId	x,
		NodeId	y ) const

Whether a causal arc x → y exists (by ids) in the causal DAG.

Definition at line 167 of file causalModel_tpl.h.

                                                                    {
    return _causalDAG_.existsArc(Arc(x, y));
  }

References _causalDAG_.

Referenced by existsArc().

Here is the caller graph for this function:

◆ existsArc() [2/2]

template<GUM_Numeric GUM_SCALAR>

bool gum::CausalModel< GUM_SCALAR >::existsArc	(	std::string_view	x,
		std::string_view	y ) const

Whether a causal arc x → y exists (by names) in the causal DAG.

Definition at line 172 of file causalModel_tpl.h.

                                                                                    {
    const NodeId ix = idFromName(x);
    const NodeId iy = idFromName(y);
    return existsArc(ix, iy);
  }

References existsArc(), and idFromName().

Here is the call graph for this function:

◆ frontDoor() [1/2]

template<GUM_Numeric GUM_SCALAR>

std::optional< NodeSet > gum::CausalModel< GUM_SCALAR >::frontDoor	(	NodeId	cause,
		NodeId	effect ) const

Find a frontdoor adjustment set (Z) between cause and effect (IDs only).

Enumerates admissible frontdoor sets in the current causal DAG (excluding latent variables) and returns the first valid one found. Returns std::nullopt if no frontdoor set exists at all. Note: an empty set is a valid frontdoor in degenerate cases.

Preconditions:

cause and effect must be observed variables of the model.

Parameters

cause	NodeId of the cause (X).
effect	NodeId of the effect (Y).

Returns: std::optional<NodeSet> The frontdoor adjustment set (Z) as NodeIds, or std::nullopt if no frontdoor set exists.

Definition at line 403 of file causalModel_tpl.h.

                                                                                               {
    // Preconditions: cause/effect must be observed (non-latent).
    const NodeSet lat = latentVariablesIds();
    if (lat.contains(cause) || lat.contains(effect)) {
      GUM_ERROR(InvalidArgument,
                "CausalModel::frontDoor: 'cause' and 'effect' must be observed (non-latent).");
    }
 
    const auto candidates = DoorCriteria::enumerateFrontdoorSets(_causalDAG_, cause, effect, lat);
    if (candidates.empty()) return std::nullopt;
    return candidates.front();   // first valid set (may itself be empty)
  }

References _causalDAG_, gum::Set< Key >::contains(), gum::DoorCriteria::enumerateFrontdoorSets(), GUM_ERROR, and latentVariablesIds().

Referenced by frontDoor().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ frontDoor() [2/2]

template<GUM_Numeric GUM_SCALAR>

std::optional< NodeSet > gum::CausalModel< GUM_SCALAR >::frontDoor	(	std::string_view	cause,
		std::string_view	effect ) const

Find a frontdoor adjustment set (Z) between cause and effect (IDs only).

Enumerates admissible frontdoor sets in the current causal DAG (excluding latent variables) and returns the first valid one found. Returns std::nullopt if no frontdoor set exists at all. Note: an empty set is a valid frontdoor in degenerate cases.

Preconditions:

cause and effect must be observed variables of the model.

Parameters

cause	name (string_view) of the cause (X).
effect	name (string_view) of the effect (Y).

Returns: std::optional<NodeSet> The frontdoor adjustment set (Z) as NodeIds, or std::nullopt if no frontdoor set exists.

Definition at line 568 of file causalModel_tpl.h.

                                                                                             {
    return frontDoor(idFromName(cause), idFromName(effect));
  }

References frontDoor(), and idFromName().

Here is the call graph for this function:

◆ id2name()

template<GUM_Numeric GUM_SCALAR>

Bijection< NodeId, std::string > gum::CausalModel< GUM_SCALAR >::id2name ( bool includeLatentVariable = false ) const

Bidirectional mapping between node ids and variable names.

Definition at line 526 of file causalModel_tpl.h.

                                                                          {
    Bijection< NodeId, std::string > result;
 
    // Add observed variables
    for (const auto n: _observationalBN_.nodes()) {
      result.insert(n, _observationalBN_.variable(n).name());
    }
 
    // Add latent variables if requested
    if (includeLatentVariables) {
      for (auto iter = _ids_names_.beginSafe(); iter != _ids_names_.endSafe(); ++iter) {
        result.insert(iter.first(), iter.second());
      }
    }
 
    return result;
  }

References _ids_names_, _observationalBN_, and gum::BijectionImplementation< T1, T2, std::is_scalar< T1 >::value &&std::is_scalar< T2 >::value >::insert().

Here is the call graph for this function:

◆ idFromName()

template<GUM_Numeric GUM_SCALAR>

NodeId gum::CausalModel< GUM_SCALAR >::idFromName ( std::string_view name ) const

Node id from variable name (observed or latent).

Definition at line 507 of file causalModel_tpl.h.

                                                                        {
    if (_ids_names_.existsSecond(std::string(name))) {
      return _ids_names_.first(std::string(name));
    } else {
      return _observationalBN_.idFromName(name);
    }
  }

References _ids_names_, and _observationalBN_.

Referenced by addLatentVariable(), assumeNonSpurious(), assumeSpurious(), backDoor(), children(), gum::Counterfactual< GUM_ELEMENT >::counterFactualModel(), gum::counterfactualModel(), existsArc(), frontDoor(), parents(), and variable().

Here is the caller graph for this function:

◆ inducedCausalSubModel()

template<GUM_Numeric GUM_SCALAR>

CausalModel< GUM_SCALAR > gum::CausalModel< GUM_SCALAR >::inducedCausalSubModel	(	const CausalModel< GUM_SCALAR > &	cm,
		NodeSet	subset ) const

Induced causal submodel on a subset of nodes.

Parameters

cm	a source causal model
subset	node set to keep (observed + latent)

Returns: A new CausalModel induced by the subset (both BN/DAG restricted appropriately).

Definition at line 305 of file causalModel_tpl.h.

                                                                             {
    // If caller gave an empty subset, use "all observed" nodes
    if (subset.empty()) {
      for (auto n: cm.observationalBN().nodes())
        subset.insert(n);
    }
 
    // Keep only OBSERVED nodes (drop latents explicitly)
    NodeSet nodes = subset;
    for (auto L: cm.latentVariablesIds())
      nodes.erase(L);
 
    // --- Build an observational BN restricted to `nodes`
    BayesNet< GUM_SCALAR >      bn;
    HashTable< NodeId, NodeId > idmap;   // oldId -> newId
 
    // add variables
    for (auto n: nodes) {
      const auto&  var = cm.observationalBN().variable(n);
      const NodeId nn  = bn.add(var, n);   // API accepts "add(var, id)"
      idmap.insert(n, nn);
    }
 
    // add arcs among the kept observed nodes (from the *causal* DAG)
    const auto causalDag = cm.causalDAG();
    for (const auto& a: causalDag.arcs()) {
      const NodeId x = a.tail();
      const NodeId y = a.head();
      if (nodes.contains(x) && nodes.contains(y)) { bn.addArc(idmap[x], idmap[y]); }
    }
 
    // --- Rebuild latent descriptor restricted to kept nodes
    LatentDescriptorVector latentDesc;
    for (auto L: cm.latentVariablesIds()) {
      std::vector< NodeId > mapped_children;
      mapped_children.reserve(4);
 
      // intersect latent children with kept observed nodes
      for (auto c: cm.children(L)) {
        if (nodes.contains(c)) mapped_children.push_back(idmap[c]);
      }
 
      // keep the latent ONLY if it still has at least 2 children
      if (mapped_children.size() >= 2) {
        latentDesc.emplace_back(cm.nameFromId(L), std::move(mapped_children));
      }
    }
 
 
    // assumeNonSpurious=true : pyagrum uses True here (do not remove arcs among children)
    return CausalModel< GUM_SCALAR >(bn, latentDesc, /*assumeNonSpurious=*/true);
  }

Referenced by gum::DoCalculus< GUM_SCALAR >::_ID_().

Here is the caller graph for this function:

◆ isAssumedSpurious() [1/2]

template<GUM_Numeric GUM_SCALAR>

bool gum::CausalModel< GUM_SCALAR >::isAssumedSpurious	(	NodeId	x,
		NodeId	y ) const

Returns true if arc is present in observationalBN and absent in causalDAG.

Definition at line 239 of file causalModel_tpl.h.

                                                                            {
    return _observationalBN_.internalDag().existsArc(Arc(x, y))
        && !_causalDAG_.existsArc(Arc(x, y));
  }

References _causalDAG_, and _observationalBN_.

◆ isAssumedSpurious() [2/2]

template<GUM_Numeric GUM_SCALAR>

bool gum::CausalModel< GUM_SCALAR >::isAssumedSpurious	(	std::string_view	x,
		std::string_view	y ) const

Definition at line 245 of file causalModel_tpl.h.

                                                                                            {
    return isAssumedSpurious(idFromName(x), idFromName(y));
  }

◆ latentVariablesIds()

template<GUM_Numeric GUM_SCALAR>

NodeSet gum::CausalModel< GUM_SCALAR >::latentVariablesIds ( ) const

Node ids of all latent variables.

Definition at line 183 of file causalModel_tpl.h.

                                                              {
    NodeSet latentIds;
    for (auto it = _ids_names_.begin(); it != _ids_names_.end(); ++it) {
      latentIds.insert(it.first());
    }
    return latentIds;
  }

References _ids_names_, and gum::Set< Key >::insert().

Referenced by gum::DoCalculus< GUM_SCALAR >::_cDecomposition_(), gum::DoCalculus< GUM_SCALAR >::_ID_(), backDoor(), gum::Counterfactual< GUM_ELEMENT >::counterFactualModel(), gum::Counterfactual< GUM_ELEMENT >::counterFactualModel(), gum::counterfactualModel(), frontDoor(), and toDot().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ latentVariablesNames()

template<GUM_Numeric GUM_SCALAR>

Set< std::string > gum::CausalModel< GUM_SCALAR >::latentVariablesNames ( ) const

Names of all latent variables.

Definition at line 192 of file causalModel_tpl.h.

                                                                         {
    Set< std::string > latentNames;
    for (auto it = _ids_names_.begin(); it != _ids_names_.end(); ++it) {
      latentNames.insert(it.second());
    }
    return latentNames;
  }

◆ nameFromId()

template<GUM_Numeric GUM_SCALAR>

std::string gum::CausalModel< GUM_SCALAR >::nameFromId ( NodeId id ) const

Variable name from node id (observed or latent).

Definition at line 516 of file causalModel_tpl.h.

                                                                 {
    if (_ids_names_.existsFirst(id)) {
      return _ids_names_.second(id);
    } else {
      return _observationalBN_.variable(id).name();
    }
  }

References _ids_names_, and _observationalBN_.

Referenced by gum::DoCalculus< GUM_SCALAR >::_hedgeExceptionMsg(), gum::DoCalculus< GUM_SCALAR >::_ID_(), causalDAG(), and toDot().

Here is the caller graph for this function:

◆ names()

template<GUM_Numeric GUM_SCALAR>

Set< std::string > gum::CausalModel< GUM_SCALAR >::names ( ) const

All variable names appearing in the causal model (observed + latent).

Definition at line 494 of file causalModel_tpl.h.

                                                          {
    Set< std::string > names;
    for (const auto n: _observationalBN_.nodes()) {
      names.insert(_observationalBN_.variable(n).name());
    }
    // latent names (from bijection)
    for (auto it = _ids_names_.begin(); it != _ids_names_.end(); ++it) {
      names.insert(it.second());
    }
    return names;
  }

References _ids_names_, _observationalBN_, and names().

Referenced by names().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ observationalBN()

template<GUM_Numeric GUM_SCALAR>

const BayesNet< GUM_SCALAR > & gum::CausalModel< GUM_SCALAR >::observationalBN ( ) const

Observational BN (observed variables only).

Definition at line 549 of file causalModel_tpl.h.

                                                                                 {
    return _observationalBN_;
  }

References _observationalBN_.

Referenced by CausalModel(), CausalModel(), CausalModel(), gum::Counterfactual< GUM_ELEMENT >::_adaptToOriginalVariables_(), gum::DoCalculus< GUM_SCALAR >::_cDecomposition_(), gum::DoCalculus< GUM_SCALAR >::_ID_(), gum::Counterfactual< GUM_ELEMENT >::_idAssignToNameAssign_(), gum::Counterfactual< GUM_ELEMENT >::_idsToNames_(), gum::DoCalculus< GUM_SCALAR >::_topoObserved_(), gum::CausalModel< GUM_ELEMENT >::children(), gum::Counterfactual< GUM_ELEMENT >::counterFactualModel(), gum::Counterfactual< GUM_ELEMENT >::counterFactualModel(), gum::counterfactualModel(), and gum::CausalModel< GUM_ELEMENT >::latentVariablesIds().

Here is the caller graph for this function:

◆ operator=() [1/2]

template<GUM_Numeric GUM_SCALAR>

CausalModel & gum::CausalModel< GUM_SCALAR >::operator= ( CausalModel< GUM_SCALAR > && other )

defaultnoexcept

Move assignment.

References CausalModel(), and assumeNonSpurious().

Here is the call graph for this function:

◆ operator=() [2/2]

template<GUM_Numeric GUM_SCALAR>

CausalModel & gum::CausalModel< GUM_SCALAR >::operator= ( const CausalModel< GUM_SCALAR > & other )

default

Copy assignment.

References CausalModel().

Here is the call graph for this function:

◆ parents() [1/2]

template<GUM_Numeric GUM_SCALAR>

NodeSet gum::CausalModel< GUM_SCALAR >::parents ( NodeId x ) const

Parents of a node (by id) in the causal DAG (including latents).

Definition at line 364 of file causalModel_tpl.h.

                                                           {
    // delegate to the causal DAG (includes latent->observed arcs)
    return _causalDAG_.parents(x);
  }

References _causalDAG_.

Referenced by parents().

Here is the caller graph for this function:

◆ parents() [2/2]

template<GUM_Numeric GUM_SCALAR>

NodeSet gum::CausalModel< GUM_SCALAR >::parents ( std::string_view name ) const

Parents of a node (by name) in the causal DAG (including latents).

Definition at line 370 of file causalModel_tpl.h.

                                                                      {
    return parents(idFromName(name));
  }

References idFromName(), and parents().

Here is the call graph for this function:

◆ toDot()

template<GUM_Numeric GUM_SCALAR>

std::string gum::CausalModel< GUM_SCALAR >::toDot	(	const bool	SHOW_LATENT_NAMES = false,
		const char *	NODE_BG = "#404040",
		const char *	NODE_FG = "white",
		const char *	EDGE_COL = "#4A4A4A" ) const

DOT representation of the causal DAG (observed + latent).

Parameters

SHOW_LATENT_NAMES	If true, display latent names explicitly.
NODE_BG	Node background color (hex code like "#404040" or Graphviz color name like "lightgray").
NODE_FG	Node label/text color (hex code or Graphviz color name).
EDGE_COL	Edge color (hex code or Graphviz color name).

Returns: A string containing a Graphviz/DOT graph.

Definition at line 420 of file causalModel_tpl.h.

                                                                           {
    //   SHOW_LATENT_NAMES => causal.show_latent_names
    //   NODE_BG           => causal.default_node_bgcolor
    //   NODE_FG           => causal.default_node_fgcolor
    //   EDGE_COL          => notebook.default_arc_color
 
    std::stringstream out;
    out << "digraph {\n";
 
    // First, latent nodes
    for (const auto n: _causalDAG_.nodes()) {
      if (latentVariablesIds().contains(n)) {
        std::string label;
        try {
          label = nameFromId(n);
        } catch (gum::NotFound&) { label = "L" + std::to_string(n); }
        out << "  \"" << label << "\" "
            << "[fillcolor=\"" << NODE_BG << "\", "
            << "fontcolor=\"" << NODE_FG << "\", "
            << "style=filled,shape=" << (SHOW_LATENT_NAMES ? "ellipse" : "point") << "];\n";
      }
    }
 
    // Then, observed nodes
    for (const auto n: _causalDAG_.nodes()) {
      if (!latentVariablesIds().contains(n)) {
        std::string label;
        try {
          label = nameFromId(n);
        } catch (gum::NotFound&) { label = "L" + std::to_string(n); }
        out << "  \"" << label << "\" "
            << "[fillcolor=\"" << NODE_BG << "\", "
            << "fontcolor=\"" << NODE_FG << "\", "
            << "style=filled,shape=ellipse];\n";
      }
    }
 
    // Edges
    for (const auto tail: _causalDAG_.nodes()) {
      for (const auto head: _causalDAG_.children(tail)) {
        std::string lt, lh;
        try {
          lt = nameFromId(tail);
        } catch (gum::NotFound&) { lt = "L" + std::to_string(tail); }
        try {
          lh = nameFromId(head);
        } catch (gum::NotFound&) { lh = "L" + std::to_string(head); }
 
        const bool dashed
            = latentVariablesIds().contains(tail) || latentVariablesIds().contains(head);
 
        out << "  \"" << lt << "\"->\"" << lh << "\" ";
        if (dashed) {
          out << "[style=dashed]";
        } else {
          // match Python: color="#4A4A4A:#4A4A4A"
          out << "[color=\"" << EDGE_COL << ":" << EDGE_COL << "\"]";
        }
        out << ";\n";
      }
    }
 
    out << "}\n";
    return out.str();
  }

References _causalDAG_, gum::contains(), latentVariablesIds(), and nameFromId().

Here is the call graph for this function:

◆ variable() [1/2]

template<GUM_Numeric GUM_SCALAR>

const DiscreteVariable & gum::CausalModel< GUM_SCALAR >::variable ( NodeId id ) const

From id to variable (observed only, by id).

Throws if id does not correspond to an observed variable.

Parameters

id	the node id

Exceptions

throws gum::NotFound if id does not correspond to an observed variable in the model

Returns: the variable if exists

Definition at line 574 of file causalModel_tpl.h.

                                                                             {
    return _observationalBN_.variable(id);
  }

References _observationalBN_.

◆ variable() [2/2]

template<GUM_Numeric GUM_SCALAR>

const DiscreteVariable & gum::CausalModel< GUM_SCALAR >::variable ( std::string_view name ) const

From name to variable (observed only, by id).

Throws if id does not correspond to an observed variable.

Parameters

name

Exceptions

throws gum::NotFound if id does not correspond to an observed variable in the model

Returns: the variable if exists

Definition at line 579 of file causalModel_tpl.h.

                                                                                       {
    return _observationalBN_.variable(idFromName(name));
  }

References _observationalBN_, and idFromName().

Here is the call graph for this function:

Member Data Documentation

◆ _causalDAG_

template<GUM_Numeric GUM_SCALAR>

DAG gum::CausalModel< GUM_SCALAR >::_causalDAG_

private

The underlying DAG representing the causal structure (observed + latent).

Definition at line 90 of file causalModel.h.

Referenced by CausalModel(), CausalModel(), CausalModel(), CausalModel(), assumeSpurious(), backDoor(), causalDAG(), children(), connectedComponents(), existsArc(), frontDoor(), isAssumedSpurious(), parents(), and toDot().

◆ _ids_names_

template<GUM_Numeric GUM_SCALAR>

Bijection< NodeId, std::string > gum::CausalModel< GUM_SCALAR >::_ids_names_

private

Bidirectional mapping between node ids and variable names (observed + latent).

Definition at line 93 of file causalModel.h.

Referenced by CausalModel(), CausalModel(), id2name(), idFromName(), latentVariablesIds(), nameFromId(), and names().

◆ _observationalBN_

template<GUM_Numeric GUM_SCALAR>

BayesNet< GUM_SCALAR > gum::CausalModel< GUM_SCALAR >::_observationalBN_

private

The underlying BayesNet representing the observed part of the model.

Definition at line 87 of file causalModel.h.

Referenced by CausalModel(), CausalModel(), CausalModel(), CausalModel(), addLatentVariable(), assumeSpurious(), id2name(), idFromName(), isAssumedSpurious(), nameFromId(), names(), observationalBN(), variable(), and variable().

The documentation for this class was generated from the following files:

agrum/CM/causalModel.h
agrum/CM/causalModel_tpl.h

Public Member Functions

Private Attributes

Detailed Description

Invariants / expectations

Constructor & Destructor Documentation

◆ CausalModel() [1/5]

◆ CausalModel() [2/5]

◆ CausalModel() [3/5]

◆ CausalModel() [4/5]

◆ CausalModel() [5/5]

◆ ~CausalModel()

Member Function Documentation

◆ addLatentVariable() [1/2]

◆ addLatentVariable() [2/2]

◆ assumeNonSpurious() [1/2]

◆ assumeNonSpurious() [2/2]

◆ assumeSpurious() [1/2]

◆ assumeSpurious() [2/2]

◆ backDoor() [1/2]

◆ backDoor() [2/2]

◆ causalDAG()

◆ children() [1/2]

◆ children() [2/2]

◆ connectedComponents()

◆ existsArc() [1/2]

◆ existsArc() [2/2]

◆ frontDoor() [1/2]

◆ frontDoor() [2/2]

◆ id2name()

◆ idFromName()

◆ inducedCausalSubModel()

◆ isAssumedSpurious() [1/2]

◆ isAssumedSpurious() [2/2]

◆ latentVariablesIds()

◆ latentVariablesNames()

◆ nameFromId()

◆ names()

◆ observationalBN()

◆ operator=() [1/2]

◆ operator=() [2/2]

◆ parents() [1/2]

◆ parents() [2/2]

◆ toDot()

◆ variable() [1/2]

◆ variable() [2/2]

Member Data Documentation

◆ _causalDAG_

◆ _ids_names_

◆ _observationalBN_