aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
causalModel.h
Go to the documentation of this file.
1/****************************************************************************
2 * This file is part of the aGrUM/pyAgrum library. *
3 * *
4 * Copyright (c) 2005-2026 by *
5 * - Pierre-Henri WUILLEMIN(_at_LIP6) *
6 * - Christophe GONZALES(_at_AMU) *
7 * *
8 * The aGrUM/pyAgrum library is free software; you can redistribute it *
9 * and/or modify it under the terms of either : *
10 * *
11 * - the GNU Lesser General Public License as published by *
12 * the Free Software Foundation, either version 3 of the License, *
13 * or (at your option) any later version, *
14 * - the MIT license (MIT), *
15 * - or both in dual license, as here. *
16 * *
17 * (see https://agrum.gitlab.io/articles/dual-licenses-lgplv3mit.html) *
18 * *
19 * This aGrUM/pyAgrum library is distributed in the hope that it will be *
20 * useful, but WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, *
21 * INCLUDING BUT NOT LIMITED TO THE WARRANTIES MERCHANTABILITY or FITNESS *
22 * FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE *
23 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER *
24 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, *
25 * ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR *
26 * OTHER DEALINGS IN THE SOFTWARE. *
27 * *
28 * See LICENCES for more details. *
29 * *
30 * SPDX-FileCopyrightText: Copyright 2005-2026 *
31 * - Pierre-Henri WUILLEMIN(_at_LIP6) *
32 * - Christophe GONZALES(_at_AMU) *
33 * SPDX-License-Identifier: LGPL-3.0-or-later OR MIT *
34 * *
35 * Contact : info_at_agrum_dot_org *
36 * homepage : http://agrum.gitlab.io *
37 * gitlab : https://gitlab.com/agrumery/agrum *
38 * *
39 ****************************************************************************/
40
41
42#ifndef GUM_CAUSAL_MODEL_H
43#define GUM_CAUSAL_MODEL_H
44
45#include <optional>
46#include <string>
47
48#include <agrum/BN/BayesNet.h>
49
50namespace gum {
51
52 namespace dot {
53 class DotOptions;
54 struct CausalDotStyle;
55 } // namespace dot
56
57 // forward declaration:
58 template < GUM_Numeric GUM_SCALAR >
59 class ASTtree;
60
62
68 using LatentDescriptorIds = std::pair< std::string, std::vector< NodeId > >;
69
71 using LatentDescriptorVector = std::vector< LatentDescriptorIds >;
72
95 template < GUM_Numeric GUM_SCALAR >
97 private:
99 std::string _toDot_(const dot::CausalDotStyle& style, const dot::DotOptions& options) const;
100
103 std::optional< BayesNet< GUM_SCALAR > > _observationalBN_;
104
108
111
114
115 public:
117 CausalModel() = delete;
118
125 explicit CausalModel(const BayesNet< GUM_SCALAR >& observationalBN);
126
136 explicit CausalModel(const BayesNet< GUM_SCALAR >& observationalBN,
137 const LatentDescriptorVector& latentVarsDescriptor,
138 bool assumeNonSpurious = false);
139
153 explicit CausalModel(const DAG& dag,
154 const LatentDescriptorVector& latentVarsDescriptor = {},
155 bool assumeNonSpurious = false);
156
158 CausalModel(const CausalModel& other);
159
161 CausalModel(CausalModel&& other) noexcept;
162
164 ~CausalModel();
165
167 CausalModel& operator=(const CausalModel& other) = default;
168
170 CausalModel& operator=(CausalModel&& other) noexcept = default;
171
189 void addLatentVariable(std::string_view latentName,
190 const std::vector< std::string >& childrenOfLatent,
191 bool assumeNonSpurious = false);
192
210 void addLatentVariable(std::string_view latentName,
211 const std::vector< NodeId >& childrenOfLatent,
212 bool assumeNonSpurious = false);
213
215 bool existsArc(NodeId x, NodeId y) const;
216
218 bool existsArc(std::string_view x, std::string_view y) const;
219
224 void assumeSpurious(NodeId x, NodeId y);
225 void assumeSpurious(std::string_view x, std::string_view y);
226
232 void assumeNonSpurious(std::string_view x, std::string_view y);
233
237 bool isAssumedSpurious(NodeId x, NodeId y) const;
238 bool isAssumedSpurious(std::string_view x, std::string_view y) const;
239
240 // ======================================================================
241 // Door-criteria conveniences
242 // ======================================================================
243
261 std::optional< NodeSet > backDoor(NodeId cause, NodeId effect) const;
262
263 std::optional< NodeSet > backDoor(std::string_view cause, std::string_view effect) const;
264
282 std::optional< NodeSet > frontDoor(NodeId cause, NodeId effect) const;
283
301 std::optional< NodeSet > frontDoor(std::string_view cause, std::string_view effect) const;
302
310 NodeSet subset) const;
311
322 std::string toDot() const;
323
333 std::string toDot(const dot::DotOptions& options) const;
334
347 std::string toDot(const bool SHOW_LATENT_NAMES,
348 const char* NODE_BG = nullptr,
349 const char* NODE_FG = nullptr,
350 const char* EDGE_COL = nullptr) const;
351
353 bool hasObservationalBN() const noexcept;
354
360 const BayesNet< GUM_SCALAR >& observationalBN() const;
361
363 DAG causalDAG() const;
364
366 Set< std::string > names() const;
367
369 NodeId idFromName(std::string_view name) const;
370
372 std::string nameFromId(NodeId id) const;
373
375 Bijection< NodeId, std::string > id2name(bool includeLatentVariable = false) const;
376
379
381 Set< std::string > latentVariablesNames() const;
382
384 NodeSet parents(NodeId x) const;
385
387 NodeSet parents(std::string_view name) const;
388
390 NodeSet children(NodeId x) const;
391
393 NodeSet children(std::string_view name) const;
394
400
414 const DiscreteVariable& variable(NodeId id) const;
415
429 const DiscreteVariable& variable(std::string_view name) const;
430 };
431
432#ifndef GUM_NO_EXTERN_TEMPLATE_CLASS
433 extern template class GUM_PUBLIC_CM CausalModel< double >;
434#endif
435
436} // namespace gum
437
439
440#endif // GUM_CAUSAL_MODEL_H
Class representing Bayesian networks.
Template implementation of CausalModel/causalModel.h.
Root abstract node for the AST of algebraic expressions.
Definition doAST.h:91
Class representing a Bayesian network.
Definition BayesNet.h:99
A causal model pairing a causal DAG with an optional observational BayesNet.
Definition causalModel.h:96
DAG causalDAG() const
Causal DAG (observed + latent variables), with node names set.
DAG _observedDAG_
Frozen copy of the observed DAG (never mutated after construction); names are set on it directly (set...
std::string _toDot_(const dot::CausalDotStyle &style, const dot::DotOptions &options) const
the dot of the causal DAG, with a look and options
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.
CausalModel< GUM_SCALAR > inducedCausalSubModel(const CausalModel< GUM_SCALAR > &cm, NodeSet subset) const
Induced causal submodel on a subset of nodes.
NodeProperty< NodeId > connectedComponents() const
Weakly connected components of the causal DAG.
bool hasObservationalBN() const noexcept
Whether this model was built from a BayesNet (CPTs available).
NodeSet latentVariablesIds() const
Node ids of all latent variables.
DAG _causalDAG_
The underlying DAG representing the causal structure (observed + latent).
bool isAssumedSpurious(NodeId x, NodeId y) const
Returns true if arc is present in observationalBN and absent in causalDAG.
Set< std::string > latentVariablesNames() const
Names of all latent variables.
std::optional< NodeSet > frontDoor(NodeId cause, NodeId effect) const
Find a frontdoor adjustment set (Z) between cause and effect (IDs only).
Bijection< NodeId, std::string > id2name(bool includeLatentVariable=false) const
Bidirectional mapping between node ids and variable names.
Bijection< NodeId, std::string > _ids_names_
Bidirectional mapping between node ids and variable names (latents only).
NodeId idFromName(std::string_view name) const
Node id from variable name (observed or latent).
CausalModel & operator=(const CausalModel &other)=default
Copy assignment.
std::string toDot() const
DOT representation of the causal DAG (observed + latent), with the look of the configuration.
bool existsArc(NodeId x, NodeId y) const
Whether a causal arc x → y exists (by ids) in the causal DAG.
std::string nameFromId(NodeId id) const
Variable name from node id (observed or latent).
NodeSet children(NodeId x) const
Children of a node (by id) in the causal DAG (including latents).
const DiscreteVariable & variable(NodeId id) const
From id to variable (observed only, by id).
CausalModel()=delete
Default constructor disabled: a causal model must be built from a BN.
Set< std::string > names() const
All variable names appearing in the causal model (observed + latent).
std::optional< BayesNet< GUM_SCALAR > > _observationalBN_
The observed Bayesian network, when the model was built with CPTs. Absent when built from a plain DAG...
CausalModel & operator=(CausalModel &&other) noexcept=default
Move assignment.
void assumeNonSpurious(NodeId x, NodeId y)
Mark an arc as non-spurious: present in observationalBN, added to causalDAG.
std::optional< NodeSet > backDoor(NodeId cause, NodeId effect) const
Find a backdoor adjustment set (Z) between cause and effect (IDs only).
void assumeSpurious(NodeId x, NodeId y)
Mark an arc as spurious: present in observationalBN, removed from causalDAG.
NodeSet parents(NodeId x) const
Parents of a node (by id) in the causal DAG (including latents).
const BayesNet< GUM_SCALAR > & observationalBN() const
Observational BN (observed variables only).
Base class for dag.
Definition DAG.h:121
Base class for discrete random variable.
Representation of a set.
Definition set.h:129
The options given to a toDot(const DotOptions&).
Definition dotOptions.h:110
Size NodeId
Type for node ids.
HashTable< NodeId, VAL > NodeProperty
Property on graph elements.
Set< NodeId > NodeSet
Some typdefs and define for shortcuts ...
gum is the global namespace for all aGrUM entities
Definition agrum.h:46
std::pair< std::string, std::vector< NodeId > > LatentDescriptorIds
LatentDescriptorIds = (latentName, (child1Id, child2Id, ...)).
Definition causalModel.h:68
template class GUM_PUBLIC_CM CausalModel< double >
std::vector< LatentDescriptorIds > LatentDescriptorVector
Collection of latent descriptors (see LatentDescriptorIds).
Definition causalModel.h:71
STL namespace.
The style of a causal model (section causal): nodeBgColor and nodeFgColor are the ones of the observe...
Definition dotStyle.h:153