aGrUM 3.3.2
a C++ library for (probabilistic) graphical models
gum::dot Namespace Reference

Classes

struct  CausalDotStyle
 The style of a causal model (section causal): nodeBgColor and nodeFgColor are the ones of the observed variables. More...
struct  DotArcOptions
 the options of an arc or an edge : an empty text (no value for the width) means "not given" More...
struct  DotAttribute
 An attribute of a graph, a node or an edge : key="value". More...
struct  DotNodeOptions
 the options of a node : an empty text means "not given", so that the value of the configuration is used More...
class  DotOptions
 The options given to a toDot(const DotOptions&). More...
class  DotStyle
 The look shared by all the graphs: size, direction, layout, colors of the arcs and of the nodes. More...
class  DotWriter
 Writes a graph in the dot language, statement after statement, in the order of the calls. More...
struct  DynamicBNDotStyle
 The style of a dynamic Bayesian network (section dynamicBN) : the colors of its clusters. More...
struct  FactorGraphDotStyle
 The style of a factor graph (section factorgraph): layout, nodeBgColor and nodeFgColor are the ones of the variables. More...
struct  InfluenceDiagramDotStyle
 The style of an influence diagram (section influenceDiagram). More...
struct  JunctionTreeDotStyle
 The style of a junction tree (section notebook): size is the size of the tree, not the one of its map. More...
struct  Rgb
 a color given by its three components, each one between 0 and 255 More...

Typedefs

using DotAttributes = std::vector< DotAttribute >
 a list of attributes

Functions

bool parseColor (std::string_view color, Rgb &rgb)
 Reads a color as it is written in a dot attribute.
double brightness (const Rgb &rgb)
 Perceived brightness of a color, between 0 (black) and 255 (white): 0.299 R + 0.587 G + 0.114 B.
std::string contrastColor (const Rgb &rgb)
 The text color which is readable on a background: white if its brightness is at most 153, black otherwise.
std::string resolveFgColor (std::string_view fgColor, std::string_view bgColor, std::string_view fallback)
 The font color to use on a background, once the special value adaptive is resolved.
void writePreamble (DotWriter &writer, const DotStyle &style, const DotOptions &options, std::string_view defaultLabel="")
 Writes the beginning of a graph, as pyAgrum displays it.
DotAttributes nodeAttributes (const DotStyle &style, const DotNodeOptions *options, std::string_view defaultLabel="", std::string_view defaultTooltip="")
 The attributes of a node : its label and tooltip, and its colors if the options give some.
DotAttributes arcAttributes (const DotArcOptions *options)
 The attributes of an arc or an edge given by the options : color, penwidth, label, tooltip and the ones given with setArcAttribute.
void addDefaultAttribute (DotAttributes &attributes, std::string_view key, std::string_view value)
 Adds an attribute at the beginning of the list, unless the list already gives a value for this key : the value given by the caller of the toDot() wins over the one of the class.
std::string configFgColor (std::string_view section, std::string_view key)
 A font color of the configuration, resolved against the background color which goes with it.

Variables

constexpr std::string_view ADAPTIVE_COLOR = "adaptive"
 the special value of a font color: black or white, according to the brightness of the background

Typedef Documentation

◆ DotAttributes

using gum::dot::DotAttributes = std::vector< DotAttribute >

a list of attributes

Definition at line 74 of file dotWriter.h.

Function Documentation

◆ addDefaultAttribute()

GUM_SHARED_PUBLIC void gum::dot::addDefaultAttribute ( DotAttributes & attributes,
std::string_view key,
std::string_view value )

Adds an attribute at the beginning of the list, unless the list already gives a value for this key : the value given by the caller of the toDot() wins over the one of the class.

Definition at line 127 of file dotElements.cpp.

127 {
128 for (const auto& attribute: attributes)
129 if (attribute.key == key) return;
130 attributes.insert(attributes.begin(), {std::string(key), std::string(value)});
131 }

References addDefaultAttribute().

Referenced by gum::CausalModel< GUM_SCALAR >::_toDot_(), addDefaultAttribute(), gum::BayesNetFragment< GUM_SCALAR >::toDot(), gum::credal::CredalNet< GUM_SCALAR >::toDot(), gum::EssentialGraph::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDot(), gum::InfluenceDiagram< GUM_SCALAR >::toDot(), gum::MarkovBlanket::toDot(), and gum::IMarkovRandomField< GUM_SCALAR >::toDotAsFactorGraph().

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

◆ arcAttributes()

GUM_SHARED_PUBLIC DotAttributes gum::dot::arcAttributes ( const DotArcOptions * options)

The attributes of an arc or an edge given by the options : color, penwidth, label, tooltip and the ones given with setArcAttribute.

Empty if there is no options.

Definition at line 112 of file dotElements.cpp.

112 {
113 DotAttributes attributes;
114 if (options == nullptr) return attributes;
115
116 if (!options->color.empty()) attributes.push_back({"color", options->color});
117 if (options->width.has_value())
118 attributes.push_back({"penwidth", DotWriter::number(*options->width)});
119 if (!options->label.empty()) attributes.push_back({"label", options->label});
120 if (!options->tooltip.empty()) attributes.push_back({"tooltip", options->tooltip});
121
122 attributes.insert(attributes.end(), options->attributes.begin(), options->attributes.end());
123 return attributes;
124 }
static std::string number(double value)
The shortest text that reads back as value (0.5, 1, 1e-05).
Definition dotWriter.cpp:93
std::vector< DotAttribute > DotAttributes
a list of attributes
Definition dotWriter.h:74
std::optional< double > width
Definition dotOptions.h:81
DotAttributes attributes
other attributes, written after the ones above
Definition dotOptions.h:85

References arcAttributes(), gum::dot::DotArcOptions::attributes, gum::dot::DotArcOptions::color, gum::dot::DotArcOptions::label, gum::dot::DotWriter::number(), gum::dot::DotArcOptions::tooltip, and gum::dot::DotArcOptions::width.

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), gum::CausalModel< GUM_SCALAR >::_toDot_(), arcAttributes(), gum::BayesNetFragment< GUM_SCALAR >::toDot(), gum::credal::CredalNet< GUM_SCALAR >::toDot(), gum::DiGraph::toDot(), gum::EssentialGraph::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDot(), gum::InfluenceDiagram< GUM_SCALAR >::toDot(), gum::MarkovBlanket::toDot(), gum::MixedGraph::toDot(), gum::PAG::toDot(), gum::PDAG::toDot(), and gum::UndiGraph::toDot().

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

◆ brightness()

GUM_SHARED_PUBLIC double gum::dot::brightness ( const Rgb & rgb)

Perceived brightness of a color, between 0 (black) and 255 (white): 0.299 R + 0.587 G + 0.114 B.

Definition at line 274 of file dotColor.cpp.

274{ return _millibrightness_(rgb) / 1000.0; }

References brightness().

Referenced by brightness().

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

◆ configFgColor()

GUM_SHARED_PUBLIC std::string gum::dot::configFgColor ( std::string_view section,
std::string_view key )

A font color of the configuration, resolved against the background color which goes with it.

The background color is the key of the same section whose suffix FgColor is replaced by BgColor (nodeFgColor goes with nodeBgColor). The special value adaptive is resolved by gum::dot::resolveFgColor, with the color of the arcs (key arcColor of the section notebook) when the background is not a color that can be interpreted.

Parameters
sectionthe section of the configuration (notebook, causal...).
keythe key of the font color, which ends with FgColor.
Returns
the font color, never adaptive.
Exceptions
InvalidArgumentif key does not end with FgColor.
SyntaxErrorif the font color or the background color is not a key of the configuration.

Definition at line 78 of file dotStyle.cpp.

78 {
79 constexpr std::string_view fgSuffix = "FgColor";
80 if (!key.ends_with(fgSuffix)) {
81 GUM_ERROR(InvalidArgument, "The key '" << key << "' of a font color must end with FgColor")
82 }
83 const std::string bgKey = std::string(key.substr(0, key.size() - fgSuffix.size())) + "BgColor";
84 return resolveFgColor(_str_(section, key),
85 _str_(section, bgKey),
86 _str_("notebook", "arcColor"));
87 }
Exception: at least one argument passed to a function is not what was expected.
#define GUM_ERROR(type, msg)
Definition exceptions.h:76
std::string resolveFgColor(std::string_view fgColor, std::string_view bgColor, std::string_view fallback)
The font color to use on a background, once the special value adaptive is resolved.
Definition dotColor.cpp:280

References configFgColor(), GUM_ERROR, and resolveFgColor().

Referenced by configFgColor(), gum::dot::CausalDotStyle::read(), gum::dot::FactorGraphDotStyle::read(), gum::dot::InfluenceDiagramDotStyle::read(), gum::dot::JunctionTreeDotStyle::read(), and gum::dot::DotStyle::readCredalNet().

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

◆ contrastColor()

GUM_SHARED_PUBLIC std::string gum::dot::contrastColor ( const Rgb & rgb)

The text color which is readable on a background: white if its brightness is at most 153, black otherwise.

Definition at line 276 of file dotColor.cpp.

276 {
277 return _millibrightness_(rgb) <= 153000 ? "white" : "black";
278 }

References contrastColor().

Referenced by contrastColor(), and resolveFgColor().

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

◆ nodeAttributes()

GUM_SHARED_PUBLIC DotAttributes gum::dot::nodeAttributes ( const DotStyle & style,
const DotNodeOptions * options,
std::string_view defaultLabel = "",
std::string_view defaultTooltip = "" )

The attributes of a node : its label and tooltip, and its colors if the options give some.

What the options do not give is not written, so the default look of the preamble applies. A background color without font color gets an adaptive font color, black or white according to the background. The attributes given with setNodeAttribute come last.

Parameters
stylethe look of the graph.
optionsthe options of the node, or nullptr if there is none.
defaultLabelthe label of the node if the options give none (none if empty).
defaultTooltipthe tooltip of the node if the options give none (none if empty).

Definition at line 80 of file dotElements.cpp.

83 {
84 DotAttributes attributes;
85
86 const std::string label = (options != nullptr && !options->label.empty())
87 ? options->label
88 : std::string(defaultLabel);
89 if (!label.empty()) attributes.push_back({"label", label});
90
91 const std::string tooltip = (options != nullptr && !options->tooltip.empty())
92 ? options->tooltip
93 : std::string(defaultTooltip);
94 if (!tooltip.empty()) attributes.push_back({"tooltip", tooltip});
95
96 if (options == nullptr) return attributes;
97
98 if (!options->bgColor.empty()) {
99 attributes.push_back({"fillcolor", options->bgColor});
100 const std::string fg
101 = options->fgColor.empty() ? std::string(ADAPTIVE_COLOR) : options->fgColor;
102 attributes.push_back({"fontcolor", resolveFgColor(fg, options->bgColor, style.arcColor)});
103 } else if (!options->fgColor.empty()) {
104 attributes.push_back(
105 {"fontcolor", resolveFgColor(options->fgColor, style.nodeBgColor, style.arcColor)});
106 }
107
108 attributes.insert(attributes.end(), options->attributes.begin(), options->attributes.end());
109 return attributes;
110 }
constexpr std::string_view ADAPTIVE_COLOR
the special value of a font color: black or white, according to the brightness of the background
Definition dotColor.h:68
std::string fgColor
font color (if only the background is given, the font color is adaptive against it)
Definition dotOptions.h:69
std::string tooltip
text displayed when the mouse is over the node
Definition dotOptions.h:73
std::string bgColor
background color
Definition dotOptions.h:67
DotAttributes attributes
other attributes, written after the ones above
Definition dotOptions.h:75
std::string label
text displayed in the node
Definition dotOptions.h:71
std::string nodeBgColor
background color of the nodes
Definition dotStyle.h:86
std::string arcColor
color of the arcs and edges, and of the border of the nodes
Definition dotStyle.h:84

References ADAPTIVE_COLOR, gum::dot::DotStyle::arcColor, gum::dot::DotNodeOptions::attributes, gum::dot::DotNodeOptions::bgColor, gum::dot::DotNodeOptions::fgColor, gum::dot::DotNodeOptions::label, nodeAttributes(), gum::dot::DotStyle::nodeBgColor, resolveFgColor(), and gum::dot::DotNodeOptions::tooltip.

Referenced by gum::KTBN< GUM_SCALAR >::_timeSlicesToDot_(), gum::CausalModel< GUM_SCALAR >::_toDot_(), gum::BayesNet< double >::maxNonOneParam(), nodeAttributes(), gum::BayesNetFragment< GUM_SCALAR >::toDot(), gum::credal::CredalNet< GUM_SCALAR >::toDot(), gum::EssentialGraph::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDot(), gum::InfluenceDiagram< GUM_SCALAR >::toDot(), gum::MarkovBlanket::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDotAsFactorGraph(), and gum::NodeGraphPart::writeDotNode().

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

◆ parseColor()

GUM_SHARED_PUBLIC bool gum::dot::parseColor ( std::string_view color,
Rgb & rgb )

Reads a color as it is written in a dot attribute.

The accepted spellings are #RGB, #RGBA, #RRGGBB, #RRGGBBAA (hexadecimal digits in any case; the transparency is ignored) and the 146 names of the HTML colors (burlywood, DarkBlue... whatever the case), with or without surrounding double quotes. Any other spelling (transparent, /blues9/3, 0.5 0.5 0.5, an unknown name...) is not interpretable.

Parameters
colorthe spelling of the color.
rgbreceives the components if (and only if) the function returns true.
Returns
true if the color is interpretable.

Definition at line 245 of file dotColor.cpp.

245 {
246 if (color.size() >= 2 && color.front() == '"' && color.back() == '"')
247 color = color.substr(1, color.size() - 2);
248 if (color.empty()) return false;
249
250 if (color.front() == '#') return _parseHexadecimal_(color.substr(1), rgb);
251
252 const std::string name = gum::toLower(color);
253 const auto it
254 = std::lower_bound(_htmlColors_.begin(),
255 _htmlColors_.end(),
256 std::string_view(name),
257 [](const NamedColor& c, std::string_view n) { return c.name < n; });
258 if (it == _htmlColors_.end() || it->name != name) return false;
259
260 rgb = {static_cast< unsigned char >(it->rgb >> 16),
261 static_cast< unsigned char >((it->rgb >> 8) & 0xFF),
262 static_cast< unsigned char >(it->rgb & 0xFF)};
263 return true;
264 }
GUM_SHARED_PUBLIC std::string toLower(std::string_view str)
Returns the lowercase version of str.

References parseColor(), and gum::toLower().

Referenced by parseColor(), and resolveFgColor().

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

◆ resolveFgColor()

GUM_SHARED_PUBLIC std::string gum::dot::resolveFgColor ( std::string_view fgColor,
std::string_view bgColor,
std::string_view fallback )

The font color to use on a background, once the special value adaptive is resolved.

Parameters
fgColorthe configured font color. If it is not adaptive (whatever the case), it is returned as is.
bgColorthe background color the text is drawn on.
fallbackreturned when fgColor is adaptive and bgColor is not interpretable (transparent, an unknown name...): usually the color of the arcs, which follows the light or dark theme.
Returns
fgColor, or white / black according to bgColor, or fallback.

Definition at line 280 of file dotColor.cpp.

282 {
283 if (gum::toLower(fgColor) != ADAPTIVE_COLOR) return std::string(fgColor);
284
285 Rgb rgb;
286 if (!parseColor(bgColor, rgb)) return std::string(fallback);
287 return contrastColor(rgb);
288 }
bool parseColor(std::string_view color, Rgb &rgb)
Reads a color as it is written in a dot attribute.
Definition dotColor.cpp:245
std::string contrastColor(const Rgb &rgb)
The text color which is readable on a background: white if its brightness is at most 153,...
Definition dotColor.cpp:276
a color given by its three components, each one between 0 and 255
Definition dotColor.h:60

References ADAPTIVE_COLOR, contrastColor(), parseColor(), resolveFgColor(), and gum::toLower().

Referenced by configFgColor(), nodeAttributes(), gum::dot::FactorGraphDotStyle::read(), and resolveFgColor().

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

◆ writePreamble()

GUM_SHARED_PUBLIC void gum::dot::writePreamble ( DotWriter & writer,
const DotStyle & style,
const DotOptions & options,
std::string_view defaultLabel = "" )

Writes the beginning of a graph, as pyAgrum displays it.

  • graph [bgcolor="transparent", size, rankdir, layout] (the size, rankdir and layout of the options if they are given, the ones of the style otherwise) and, if there is a label, label and fontcolor;
  • node [style="filled", fillcolor, fontcolor, color] : the default look of the nodes;
  • edge [color] : the default look of the arcs.
Parameters
writerthe writer, just created.
stylethe look of the graph, read from the configuration.
optionsthe options given by the caller.
defaultLabelthe label of the graph if the options give none (for instance the name of a model).

Definition at line 52 of file dotElements.cpp.

55 {
56 const auto pick
57 = [](const std::string& given, const std::string& byDefault) -> const std::string& {
58 return given.empty() ? byDefault : given;
59 };
60
61 DotAttributes graph{{"bgcolor", "transparent"},
62 {"size", pick(options.size(), style.size)},
63 {"rankdir", pick(options.rankDir(), style.rankDir)},
64 {"layout", pick(options.layout(), style.layout)}};
65
66 const std::string label = options.label().empty() ? std::string(defaultLabel) : options.label();
67 if (!label.empty()) {
68 graph.push_back({"label", label});
69 graph.push_back({"fontcolor", style.arcColor});
70 }
71 writer.graphAttributes(graph);
72
73 writer.nodeDefaults({{"style", "filled"},
74 {"fillcolor", style.nodeBgColor},
75 {"fontcolor", style.nodeFgColor},
76 {"color", style.arcColor}});
77 writer.edgeDefaults({{"color", style.arcColor}});
78 }
const std::string & layout() const
direction of the layout, TB or LR
const std::string & label() const
direction of the layout, TB or LR
const std::string & size() const
direction of the layout, TB or LR
const std::string & rankDir() const
direction of the layout, TB or LR
void nodeDefaults(const DotAttributes &attributes)
node [attributes];, the default attributes of the nodes that follow (none : does nothing).
void graphAttributes(const DotAttributes &attributes)
graph [attributes];, the attributes of the graph (does nothing if there is none).
void edgeDefaults(const DotAttributes &attributes)
edge [attributes];, the default attributes of the edges that follow (none : does nothing).
std::string size
graphviz size of the graph, in inches (5, or 12! for an exact size)
Definition dotStyle.h:78
std::string nodeFgColor
font color of the nodes
Definition dotStyle.h:88
std::string layout
graphviz layout engine (dot, neato...)
Definition dotStyle.h:82
std::string rankDir
direction of the layout : TB (top-bottom) or LR (left-right)
Definition dotStyle.h:80

References gum::dot::DotStyle::arcColor, gum::dot::DotWriter::edgeDefaults(), gum::dot::DotWriter::graphAttributes(), gum::dot::DotOptions::label(), gum::dot::DotOptions::layout(), gum::dot::DotStyle::layout, gum::dot::DotStyle::nodeBgColor, gum::dot::DotWriter::nodeDefaults(), gum::dot::DotStyle::nodeFgColor, gum::dot::DotOptions::rankDir(), gum::dot::DotStyle::rankDir, gum::dot::DotOptions::size(), gum::dot::DotStyle::size, and writePreamble().

Referenced by gum::CausalModel< GUM_SCALAR >::_toDot_(), gum::BayesNetFragment< GUM_SCALAR >::toDot(), gum::credal::CredalNet< GUM_SCALAR >::toDot(), gum::DiGraph::toDot(), gum::EssentialGraph::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDot(), gum::InfluenceDiagram< GUM_SCALAR >::toDot(), gum::MarkovBlanket::toDot(), gum::MixedGraph::toDot(), gum::PAG::toDot(), gum::PDAG::toDot(), gum::UndiGraph::toDot(), gum::IMarkovRandomField< GUM_SCALAR >::toDotAsFactorGraph(), and writePreamble().

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

Variable Documentation

◆ ADAPTIVE_COLOR

std::string_view gum::dot::ADAPTIVE_COLOR = "adaptive"
inlineconstexpr

the special value of a font color: black or white, according to the brightness of the background

Definition at line 68 of file dotColor.h.

Referenced by nodeAttributes(), gum::dot::FactorGraphDotStyle::read(), and resolveFgColor().