aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
gum::CausalFormula< GUM_SCALAR > Class Template Reference

A container for an identified causal query. More...

#include <causalFormula.h>

Collaboration diagram for gum::CausalFormula< GUM_SCALAR >:
[legend]

Public Member Functions

 CausalFormula (const CausalModel< GUM_SCALAR > &cm, std::unique_ptr< ASTtree< GUM_SCALAR > > root, const Set< std::string > &on, const Set< std::string > &doing, const Set< std::string > &knowing=Set< std::string >{}, std::string_view explanation="")
 Constructs a CausalFormula object (variables given by names).
 CausalFormula (const CausalModel< GUM_SCALAR > &cm, std::unique_ptr< ASTtree< GUM_SCALAR > > root, const NodeSet &on, const NodeSet &doing, const NodeSet &knowing=NodeSet{}, std::string_view explanation="")
 Constructs a CausalFormula object (variables given by node ids).
 CausalFormula (const CausalFormula &other)
 Copy constructor — performs a deep copy of the AST.
 CausalFormula (CausalFormula &&)=default
 Move constructor — defaulted (suppressed by the user-defined copy constructor above).
Tensor< GUM_SCALAR > eval () const
 Evaluates the formula's AST to compute the resulting probability distribution.
std::string toString () const
 Generates a string representation of the formula's AST.
std::string toLatex (std::string_view doOperatorPrefix="do(", std::string_view doOperatorSuffix=")") const
 Generates a full LaTeX equation: Query = Formula.
std::string latexQuery (std::string_view doOperatorPrefix="do(", std::string_view doOperatorSuffix=")") const
 Generates a LaTeX representation of the original query, e.g., P(Y | do(X), Z).
std::unique_ptr< CausalFormula< GUM_SCALAR > > copy () const
 Creates a deep copy of the CausalFormula (including its AST).
bool isIdentified () const noexcept
 Whether the causal effect has been identified.
const ASTtree< GUM_SCALAR > & root () const
 Access the root AST node of the identified formula.
const CausalModel< GUM_SCALAR > & cm () const
const NodeSet & on () const
const NodeSet & doing () const
const NodeSet & knowing () const
const std::string & explanation () const
std::vector< std::string > onNames () const
 Convenience: return names corresponding to stored node ids (sorted).
std::vector< std::string > doingNames () const
std::vector< std::string > knowingNames () const

Private Member Functions

void _ensureVariablesExist () const
 Verifies that all variables (_on, _knowing, _doing) exist in the BN.
void _ensureNoVariablesOverlap () const
 Verifies that all variables (_on, _knowing, _doing) have no intersection.

Static Private Member Functions

static NodeSet _toNodeSetFromNames_ (const CausalModel< GUM_SCALAR > &cm, const Set< std::string > &names)
 Convert a set of names to a set of node ids (validates existence).

Private Attributes

const CausalModel< GUM_SCALAR > & _cm
std::unique_ptr< ASTtree< GUM_SCALAR > > _root
const NodeSet _on
const NodeSet _doing
const NodeSet _knowing
const std::string _explanation

Detailed Description

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

A container for an identified causal query.

This class binds an identified formula (as an ASTtree) to the context of the query that produced it: the CausalModel and the sets of variables for on, doing, and knowing.

It provides methods to:

  • Evaluate the formula to get a numeric Tensor (eval).
  • Display the formula as a string (toString) or LaTeX (toLatex).
  • Display the original query that generated the formula (latexQuery).
Template Parameters
GUM_SCALARThe numeric type for tensor computations.

Definition at line 74 of file causalFormula.h.

Constructor & Destructor Documentation

◆ CausalFormula() [1/4]

template<GUM_Numeric GUM_SCALAR>
gum::CausalFormula< GUM_SCALAR >::CausalFormula ( const CausalModel< GUM_SCALAR > & cm,
std::unique_ptr< ASTtree< GUM_SCALAR > > root,
const Set< std::string > & on,
const Set< std::string > & doing,
const Set< std::string > & knowing = Set< std::string >{},
std::string_view explanation = "" )

Constructs a CausalFormula object (variables given by names).

Parameters
cmThe causal model against which the formula was identified.
rootThe identified formula as an Abstract Syntax Tree (ownership moved).
onThe set of outcome variable names (the "Y" in P(Y|...)).
doingThe set of intervention variable names (the "do(X)")).
knowingThe set of conditioning variable names (optional evidence).
explanationA human-readable explanation of the identification method used (optional).

Definition at line 102 of file causalFormula_tpl.h.

107 :
113 }
A container for an identified causal query.
const NodeSet & on() const
const std::string _explanation
const NodeSet _knowing
static NodeSet _toNodeSetFromNames_(const CausalModel< GUM_SCALAR > &cm, const Set< std::string > &names)
Convert a set of names to a set of node ids (validates existence).
const NodeSet _on
const CausalModel< GUM_SCALAR > & _cm
const NodeSet & knowing() const
const std::string & explanation() const
const CausalModel< GUM_SCALAR > & cm() const
void _ensureNoVariablesOverlap() const
Verifies that all variables (_on, _knowing, _doing) have no intersection.
const NodeSet & doing() const
std::unique_ptr< ASTtree< GUM_SCALAR > > _root
void _ensureVariablesExist() const
Verifies that all variables (_on, _knowing, _doing) exist in the BN.
const ASTtree< GUM_SCALAR > & root() const
Access the root AST node of the identified formula.
const NodeSet _doing

References _cm, _doing, _ensureNoVariablesOverlap(), _ensureVariablesExist(), _explanation, _knowing, _on, _root, _toNodeSetFromNames_(), cm(), doing(), explanation(), knowing(), on(), and root().

Referenced by CausalFormula(), and CausalFormula().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ CausalFormula() [2/4]

template<GUM_Numeric GUM_SCALAR>
gum::CausalFormula< GUM_SCALAR >::CausalFormula ( const CausalModel< GUM_SCALAR > & cm,
std::unique_ptr< ASTtree< GUM_SCALAR > > root,
const NodeSet & on,
const NodeSet & doing,
const NodeSet & knowing = NodeSet{},
std::string_view explanation = "" )

Constructs a CausalFormula object (variables given by node ids).

Parameters
cmThe causal model against which the formula was identified.
rootThe identified formula as an Abstract Syntax Tree (ownership moved).
onThe set of outcome variable ids (the "Y" in P(Y|...)).
doingThe set of intervention variable ids (the "do(X)")).
knowingThe set of conditioning variable ids (optional evidence).
explanationA human-readable explanation of the identification method used (optional).

Definition at line 116 of file causalFormula_tpl.h.

References _cm, _doing, _ensureNoVariablesOverlap(), _ensureVariablesExist(), _explanation, _knowing, _on, _root, cm(), doing(), explanation(), knowing(), on(), and root().

Here is the call graph for this function:

◆ CausalFormula() [3/4]

template<GUM_Numeric GUM_SCALAR>
gum::CausalFormula< GUM_SCALAR >::CausalFormula ( const CausalFormula< GUM_SCALAR > & other)

Copy constructor — performs a deep copy of the AST.

Required so that types containing CausalFormula (e.g. CausalImpact) remain copy-constructible. SWIG's SwigValueWrapper<T> stores the wrapped return value via copy construction, so without this the Windows/MSVC CI fails to compile any binding that returns CausalImpact by value.

Definition at line 129 of file causalFormula_tpl.h.

References CausalFormula(), _cm, _doing, _explanation, _knowing, _on, _root, and copy().

Here is the call graph for this function:

◆ CausalFormula() [4/4]

template<GUM_Numeric GUM_SCALAR>
gum::CausalFormula< GUM_SCALAR >::CausalFormula ( CausalFormula< GUM_SCALAR > && )
default

Move constructor — defaulted (suppressed by the user-defined copy constructor above).

References CausalFormula(), _ensureNoVariablesOverlap(), _ensureVariablesExist(), _toNodeSetFromNames_(), cm(), copy(), doing(), doingNames(), eval(), explanation(), isIdentified(), knowing(), knowingNames(), latexQuery(), on(), onNames(), root(), toLatex(), and toString().

Here is the call graph for this function:

Member Function Documentation

◆ _ensureNoVariablesOverlap()

template<GUM_Numeric GUM_SCALAR>
void gum::CausalFormula< GUM_SCALAR >::_ensureNoVariablesOverlap ( ) const
private

Verifies that all variables (_on, _knowing, _doing) have no intersection.

Exceptions
gum::OperationNotAllowedif any variable appears in two roles.

Definition at line 85 of file causalFormula_tpl.h.

85 {
86 // Ensure pairwise disjointness: on ∩ doing = ∅, on ∩ knowing = ∅, doing ∩ knowing = ∅
87 for (const auto& id: _on) {
88 if (_doing.contains(id))
89 GUM_ERROR(OperationNotAllowed, "Variable cannot be both in 'on' and 'doing'");
90 if (_knowing.contains(id))
91 GUM_ERROR(OperationNotAllowed, "Variable cannot be both in 'on' and 'knowing'");
92 }
93 for (const auto& id: _doing) {
94 if (_knowing.contains(id))
95 GUM_ERROR(OperationNotAllowed, "Variable cannot be both in 'doing' and 'knowing'");
96 }
97 }

References _doing, _knowing, _on, and GUM_ERROR.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ _ensureVariablesExist()

template<GUM_Numeric GUM_SCALAR>
void gum::CausalFormula< GUM_SCALAR >::_ensureVariablesExist ( ) const
private

Verifies that all variables (_on, _knowing, _doing) exist in the BN.

Exceptions
gum::NotFoundif any variable id is not found.

Definition at line 67 of file causalFormula_tpl.h.

67 {
68 const NodeSet lat = _cm.latentVariablesIds();
69 const DAG dag = _cm.causalDAG();
70 auto checkObserved = [&](const NodeSet& S) {
71 for (const auto& id: S) {
72 if (!dag.existsNode(id) || lat.contains(id)) {
74 "CausalFormula: variable id " + std::to_string(id)
75 + " is not an observed variable of the model.");
76 }
77 }
78 };
82 }

References _cm, _doing, _knowing, _on, gum::Set< Key >::contains(), gum::NodeGraphPart::existsNode(), and GUM_ERROR.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ _toNodeSetFromNames_()

template<GUM_Numeric GUM_SCALAR>
NodeSet gum::CausalFormula< GUM_SCALAR >::_toNodeSetFromNames_ ( const CausalModel< GUM_SCALAR > & cm,
const Set< std::string > & names )
staticprivate

Convert a set of names to a set of node ids (validates existence).

Definition at line 57 of file causalFormula_tpl.h.

58 {
60 for (const auto& n: names) {
61 ids.insert(cm.idFromName(n)); // throws NotFound if unknown
62 }
63 return ids;
64 }

References cm(), gum::CausalModel< GUM_SCALAR >::idFromName(), and gum::Set< Key >::insert().

Referenced by CausalFormula(), and CausalFormula().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ cm()

template<GUM_Numeric GUM_SCALAR>
const CausalModel< GUM_SCALAR > & gum::CausalFormula< GUM_SCALAR >::cm ( ) const

Definition at line 273 of file causalFormula_tpl.h.

273 {
274 return _cm;
275 }

References _cm.

Referenced by CausalFormula(), CausalFormula(), CausalFormula(), and _toNodeSetFromNames_().

Here is the caller graph for this function:

◆ copy()

template<GUM_Numeric GUM_SCALAR>
std::unique_ptr< CausalFormula< GUM_SCALAR > > gum::CausalFormula< GUM_SCALAR >::copy ( ) const

Creates a deep copy of the CausalFormula (including its AST).

Definition at line 230 of file causalFormula_tpl.h.

230 {
232 _root->copy(),
233 _on,
234 _doing,
235 _knowing);
236 }

References _cm, _doing, _knowing, _on, and _root.

Referenced by CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ doing()

template<GUM_Numeric GUM_SCALAR>
const NodeSet & gum::CausalFormula< GUM_SCALAR >::doing ( ) const

Definition at line 283 of file causalFormula_tpl.h.

283 {
284 return _doing;
285 }

References _doing.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ doingNames()

template<GUM_Numeric GUM_SCALAR>
std::vector< std::string > gum::CausalFormula< GUM_SCALAR >::doingNames ( ) const

Definition at line 251 of file causalFormula_tpl.h.

251 {
253 out.reserve(_doing.size());
254 for (const auto& id: _doing)
255 out.emplace_back(_cm.nameFromId(id));
256 std::sort(out.begin(), out.end());
257 return out;
258 }

References _cm, and _doing.

Referenced by CausalFormula(), and latexQuery().

Here is the caller graph for this function:

◆ eval()

template<GUM_Numeric GUM_SCALAR>
Tensor< GUM_SCALAR > gum::CausalFormula< GUM_SCALAR >::eval ( ) const

Evaluates the formula's AST to compute the resulting probability distribution.

Definition at line 148 of file causalFormula_tpl.h.

148 {
149 if (!_root) {
151 "CausalFormula::eval() called on a non-identified formula.");
152 }
153 return _root->eval(_cm.observationalBN());
154 }

References _cm, _root, and GUM_ERROR.

Referenced by CausalFormula().

Here is the caller graph for this function:

◆ explanation()

template<GUM_Numeric GUM_SCALAR>
const std::string & gum::CausalFormula< GUM_SCALAR >::explanation ( ) const

Definition at line 293 of file causalFormula_tpl.h.

293 {
294 return _explanation;
295 }

References _explanation.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ isIdentified()

template<GUM_Numeric GUM_SCALAR>
bool gum::CausalFormula< GUM_SCALAR >::isIdentified ( ) const
noexcept

Whether the causal effect has been identified.

Returns true iff this formula has a valid AST (i.e., identification succeeded and evaluation is possible). When this returns false, calling root() or eval() will throw.

Returns
true if an identification AST exists, false otherwise.

Definition at line 137 of file causalFormula_tpl.h.

137 {
138 return static_cast< bool >(_root);
139 }

References _root.

Referenced by CausalFormula().

Here is the caller graph for this function:

◆ knowing()

template<GUM_Numeric GUM_SCALAR>
const NodeSet & gum::CausalFormula< GUM_SCALAR >::knowing ( ) const

Definition at line 288 of file causalFormula_tpl.h.

288 {
289 return _knowing;
290 }

References _knowing.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ knowingNames()

template<GUM_Numeric GUM_SCALAR>
std::vector< std::string > gum::CausalFormula< GUM_SCALAR >::knowingNames ( ) const

Definition at line 261 of file causalFormula_tpl.h.

261 {
263 out.reserve(_knowing.size());
264 for (const auto& id: _knowing)
265 out.emplace_back(_cm.nameFromId(id));
266 std::sort(out.begin(), out.end());
267 return out;
268 }

References _cm, and _knowing.

Referenced by CausalFormula(), and latexQuery().

Here is the caller graph for this function:

◆ latexQuery()

template<GUM_Numeric GUM_SCALAR>
std::string gum::CausalFormula< GUM_SCALAR >::latexQuery ( std::string_view doOperatorPrefix = "do(",
std::string_view doOperatorSuffix = ")" ) const

Generates a LaTeX representation of the original query, e.g., P(Y | do(X), Z).

Note
This version does not yet support specific variable values.

Definition at line 184 of file causalFormula_tpl.h.

185 {
186 auto namesSorted = [&](const NodeSet& S) {
188 res.reserve(S.size());
189 for (const auto& id: S)
190 res.emplace_back(_cm.nameFromId(id));
191 std::sort(res.begin(), res.end());
192 return res;
193 };
194
195 const auto onNames = namesSorted(_on);
196 const auto doingNames = namesSorted(_doing);
197 const auto knowingNames = namesSorted(_knowing);
198
200 ss << "P\\left(";
201
202 for (size_t i = 0; i < onNames.size(); ++i) {
203 ss << onNames[i];
204 if (i + 1 < onNames.size()) ss << ",";
205 }
206
207 if (!doingNames.empty() || !knowingNames.empty()) {
208 ss << " \\mid ";
209
210 if (!doingNames.empty()) {
211 ss << doOperatorPrefix << doingNames.front();
212 for (size_t i = 1; i < doingNames.size(); ++i)
213 ss << "," << doingNames[i];
215 }
216
217 if (!knowingNames.empty()) {
218 if (!doingNames.empty()) ss << ",";
219 ss << knowingNames.front();
220 for (size_t i = 1; i < knowingNames.size(); ++i)
221 ss << "," << knowingNames[i];
222 }
223 }
224
225 ss << "\\right)";
226 return ss.str();
227 }
std::vector< std::string > doingNames() const
std::vector< std::string > knowingNames() const
std::vector< std::string > onNames() const
Convenience: return names corresponding to stored node ids (sorted).

References _cm, _doing, _knowing, _on, doingNames(), knowingNames(), and onNames().

Referenced by CausalFormula(), and toLatex().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ on()

template<GUM_Numeric GUM_SCALAR>
const NodeSet & gum::CausalFormula< GUM_SCALAR >::on ( ) const

Definition at line 278 of file causalFormula_tpl.h.

278 {
279 return _on;
280 }

References _on.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ onNames()

template<GUM_Numeric GUM_SCALAR>
std::vector< std::string > gum::CausalFormula< GUM_SCALAR >::onNames ( ) const

Convenience: return names corresponding to stored node ids (sorted).

Definition at line 241 of file causalFormula_tpl.h.

241 {
243 out.reserve(_on.size());
244 for (const auto& id: _on)
245 out.emplace_back(_cm.nameFromId(id));
246 std::sort(out.begin(), out.end());
247 return out;
248 }

References _cm, and _on.

Referenced by CausalFormula(), and latexQuery().

Here is the caller graph for this function:

◆ root()

template<GUM_Numeric GUM_SCALAR>
const ASTtree< GUM_SCALAR > & gum::CausalFormula< GUM_SCALAR >::root ( ) const

Access the root AST node of the identified formula.

Use this to inspect the symbolic structure of the identified effect.

Warning
This raises an exception if the effect is not identified.
Exceptions
gum::OperationNotAllowedif no AST is available (i.e., the effect is not identifiable with the current methods).
Returns
const ASTtree<GUM_SCALAR>& reference to the AST root.

Definition at line 142 of file causalFormula_tpl.h.

142 {
143 if (!_root) GUM_ERROR(OperationNotAllowed, "No AST: effect not identified.");
144 return *_root;
145 }

References _root, and GUM_ERROR.

Referenced by CausalFormula(), CausalFormula(), and CausalFormula().

Here is the caller graph for this function:

◆ toLatex()

template<GUM_Numeric GUM_SCALAR>
std::string gum::CausalFormula< GUM_SCALAR >::toLatex ( std::string_view doOperatorPrefix = "do(",
std::string_view doOperatorSuffix = ")" ) const

Generates a full LaTeX equation: Query = Formula.

Definition at line 163 of file causalFormula_tpl.h.

164 {
165 if (!_root) return "[unidentifiable]";
166
167 // Track variable name occurrences for prime management in AST LaTeX
169
170 auto addNames = [&](const NodeSet& S) {
171 for (const auto& id: S) {
172 const auto name = _cm.nameFromId(id);
173 if (!nameOccur.exists(name)) nameOccur.insert(name, 1);
174 }
175 };
176 addNames(_on);
179
180 return latexQuery(doOperatorPrefix, doOperatorSuffix) + " = " + _root->toLatex(nameOccur);
181 }
std::string latexQuery(std::string_view doOperatorPrefix="do(", std::string_view doOperatorSuffix=")") const
Generates a LaTeX representation of the original query, e.g., P(Y | do(X), Z).

References _cm, _doing, _knowing, _on, _root, gum::HashTable< Key, Val >::exists(), gum::HashTable< Key, Val >::insert(), and latexQuery().

Referenced by CausalFormula().

Here is the call graph for this function:
Here is the caller graph for this function:

◆ toString()

template<GUM_Numeric GUM_SCALAR>
std::string gum::CausalFormula< GUM_SCALAR >::toString ( ) const

Generates a string representation of the formula's AST.

Definition at line 157 of file causalFormula_tpl.h.

157 {
158 if (!_root) return "[unidentifiable]";
159 return _root->toString();
160 }

References _root.

Referenced by CausalFormula().

Here is the caller graph for this function:

Member Data Documentation

◆ _cm

template<GUM_Numeric GUM_SCALAR>
const CausalModel< GUM_SCALAR >& gum::CausalFormula< GUM_SCALAR >::_cm
private

◆ _doing

template<GUM_Numeric GUM_SCALAR>
const NodeSet gum::CausalFormula< GUM_SCALAR >::_doing
private

◆ _explanation

template<GUM_Numeric GUM_SCALAR>
const std::string gum::CausalFormula< GUM_SCALAR >::_explanation
private

Definition at line 205 of file causalFormula.h.

Referenced by CausalFormula(), CausalFormula(), CausalFormula(), and explanation().

◆ _knowing

template<GUM_Numeric GUM_SCALAR>
const NodeSet gum::CausalFormula< GUM_SCALAR >::_knowing
private

◆ _on

template<GUM_Numeric GUM_SCALAR>
const NodeSet gum::CausalFormula< GUM_SCALAR >::_on
private

◆ _root

template<GUM_Numeric GUM_SCALAR>
std::unique_ptr< ASTtree< GUM_SCALAR > > gum::CausalFormula< GUM_SCALAR >::_root
private

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