API Documentation¶
Factbase¶
- class clingraph.orm.Factbase(prefix: str = '', default_graph: str = 'default')¶
Stores facts that are accepted by clingraphs syntax. It performs a preprocessing of the facts to unify them, and uses clorm as ORM to store and query the facts.
- __init__(prefix: str = '', default_graph: str = 'default')¶
Defines the factbase behavior based on the prefix for the predicates and the name of the deafult graph
- Parameters
prefix (str) – The prefix to all predicate names
default_graph (str) – Name of the default graph, all elements with arity 1 will be assigned to this graph
- add_fact_file(file)¶
Adds a file containing facts to the
Factbase
- Parameters
file (str) – The path to the file
- Raises
InvalidSyntax – If the input are not facts
- add_fact_string(program)¶
Adds a string containing facts to the
Factbase
- Parameters
program (str) – A string consisting of only facts, divided by a
.
- Raises
InvalidSyntax – If the input are not facts
- add_model(model)¶
Adds a clingo model to the
Factbase
- Parameters
model (clingo.Model) – A model returned by clingo
- classmethod from_model(model, prefix: str = '', default_graph: str = 'default')¶
Creates a
Factbase
from a clingo model- Parameters
model (clingo.Model) – A model returned by clingo
prefix (str) – The prefix to all predicate names
default_graph (str) – Name of the default graph, all elements with arity 1 will be assigned to this graph
- classmethod from_string(string, prefix: str = '', default_graph: str = 'default')¶
Creates a
Factbase
from a string- Parameters
string (str) – A string consisting of only facts, divided by a
.
prefix (str) – The prefix to all predicate names
default_graph (str) – Name of the default graph, all elements with arity 1 will be assigned to this graph
- Raises
InvalidSyntax – If the input are not facts
- get_all_graphs()¶
Gets a list if the identifiers for all the graphs
- Returns
(list) A list with the identifiers for all the graphs
- get_element_attr(element_type, element_id)¶
Gets the attributes a specific element Returns a dictionary where the keys are attribute name and values are attribute values.
- Parameters
element_type (str) – The element type:
graph
,edge
ornode
element_id – Identifier of the element
- Returns
(dic) A dictionary with attribute names as key and attribute values as values.
- get_facts()¶
Gets the facts in the factbase after preprocessing as a string
- Returns
(str) A string with the facts
- get_graph_elements(element_type, graph_id)¶
Gets the list of elements for a graph
- Parameters
element_type (str) – The element type:
edge
ornode
graph_id – Identifier of the graph
- Returns
(list) The list of elements that belong to the graph
- get_graph_global_element_attr(element_type, graph_id)¶
Gets the attributes for a global element: graph_nodes or graph_edges.
- Parameters
element_type (str) – The element type:
edge
ornode
graph_id – Identifier of the graph
- Returns
(dic) A dictionary with attribute names as key and attribute values as values.
- get_parent_graph(graph_id)¶
Gets the parent graph for a given graph_id.
- Parameters
graph_id – Identifier of the subgraph
- Returns
The identifier of the parent graph or None if there is no parent
Graphviz¶
Graphviz functionality
- clingraph.graphviz.compute_graphs(fb, graphviz_type='graph', seed=None)¶
Computes graphs using Graphviz for the given factbase
- Parameters
fb (list[
Factbase
] |Factbase
) – AFactbase
to generate the graphviz objects. If a list is passed, each element is cosidered as the Factbase for a stable model.graphviz_type (str) – The type of graph
graph
forgraphviz.Graph
anddigraph
forgraphviz.Digraph
seed (int) – A number used as seed
- clingraph.graphviz.dot(graphs)¶
Gets the source string in dot language for the graphs
- Parameters
graphs (dic|list[dic]) – A dictionary of graphviz objects where the keys are the graph names. Or a list of such dictionaries, each element corresponding to a model.
- clingraph.graphviz.render(graphs, directory='out', format='pdf', name_format=None, engine='dot', view=False)¶
Render the given graphviz graphs that where computed using
compute_graphs()
.- Parameters
graphs (dic|list[dic]) – A dictionary of graphviz objects where the keys are the graph names. Or a list of such dictionaries, each element corresponding to a model.
directory (str) – Where to save the object
format (str) – The format for the output
pdf
,png
orsvg
name_format (str) – The format for the name.
engine (str) – Engine used for the layout
view (bool) – If the rendered files will be oppend
- Returns
- A dictionary with the paths where the images where saved as values for each graph.
Or a list of such dictionaries, each element corresponding to a model.
- Return type
[dic | list[dic]]
Graphviz gif¶
Graphviz tex¶
Utils¶
Utils functions used across the project
- clingraph.utils.apply(elements, function, **kwargs)¶
Applies a given function to the elements.
- Parameters
elements (list[dic]|dic) – A dictionary where the keys are considered the graph names and the function is applied to the values. Can also be a list of such dictionaries, where each element is considered a model. Any
None
values in the list will be skiped.function (callable) – The function to be applied
**kwargs – Any arguments passed to the function. If an argument
name_format
is passed,{graph_name}
and{model_number}
will be substituted in this string by the corresponding values during the iteration.
Returns: (list[dic]|[dic]) The elements after appling the function to the values
- clingraph.utils.pythonify_symbol(s)¶
Get a python element from a clingo symbol
- Parameters
s (clingo.Symbol) – The clingo symbol
- Returns
A integer, string or tuple
- clingraph.utils.stringify_symbol(s)¶
Get a string representation of a clingo symbol
- Parameters
s (clingo.Symbol) – The clingo symbol
- Returns
A string
- clingraph.utils.write(elements, directory, format, name_format=None)¶
Writes all the elements info using
apply()
- Parameters
elements (list|dic) – A dictionary where the keys are considered the graph names and the write is applied to the values. Can also be a list of such dictionaries, where each element is considered a model.
directory (str) – Path to the directory where to write
format (str) – Output format
name_format (str) – The file name
- Returns
- A dictionary with the paths where the files where saved as values for each graph.
Or a list of such dictionaries, each element corresponding to a model.
- Return type
[dic | list[dic]]
Clingo Utils¶
Functions used for the clingo integration
- class clingraph.clingo_utils.ClingraphContext¶
Provides avaliable python functions to be used in a visualization encoding passed in the command line via option –viz-encoding
- clinguin_fontname()¶
Gets the font name used in clinguin
- cluster(s)¶
Returns the cluster name for a graph :param s: The identifier of the graph
- Returns
(clingo.Symbol.String) The string with the cluster name
- color(option, opacity=None)¶
Gets the html color code for the different options and the given opacity :param option: primary, secondary, success, info, warning, danger, light :param opacity: Numeric value indicating the opacity of the color
- concat(*args)¶
Concatenates the given symbols as a string :param args: All symbols
- Returns
(clingo.Symbol.String) The string concatenating all symbols
- format(s, *args)¶
Formats the string with the given arguments :param s: The string to format, for example “{0} and {1}” :type s: clingo.Symbol.String :param args: All symbols that can be accessed by the position starting in 0
- Returns
(clingo.Symbol.String) The string concatenating all symbols
- html_escape(s)¶
Will escape the symbols of an HTML-Like label that provoque clashes: &, < and > :param s: The value that needs the symbols removed :type s: clingo.Symbol
- Returns
(clingo.Symbol.String) The string with the replacements
- pos(x, y, scale=1)¶
- Parameters
x (clingo.Symbol.Number) – Number for the X coordinate
y (clingo.Symbol.Number) – Number for the Y coordinate
- Returns
(clingo.Symbol.String) position as a string of form (x,y)!
- stringify(s, capitalize=False)¶
Turns a value into a string without underscore and capitalized if requested :param s: The value to transform
- Returns
(clingo.Symbol.String) The string
- svg(event, element, property_name, property_value)¶
Generates an svg string for interactive actions This property will be set on the group tag <g> used around the elements. Notice that any properties set using the attr predicates will not be overwritten. :param event: The svg event one of: “click”,”mouseenter”,”mouseleave”,”contextmenu” :param element: The id on the element in which the action is performed. This element must have the id property set: attr(node,ID,id,ID):-node(ID). :param property_name: The name of the css property to set. :param property_value: The value of the property to set
- Returns
(clingo.Symbol.String) The string internal representation of the interaction
- svg_color()¶
Generates an svg string that is used as a placeholder for the color in properties. This string will be mapped into the css variable currentcolor. :returns: (clingo.Symbol.String) The string as a color placeholder
- svg_init(property_name, property_value)¶
Generates an svg string for the initial state. This string has a format that is handled by clingraph internally in the generation of svg files. This property will be set on the group tag <g> used around the elements. Notice that any properties set using the attr predicates will not be overwritten.
- Parameters
property_name – The name of the css property to set.
property_value – The value of the property to set
- Returns
(clingo.Symbol.String) The string representing the property
- clingraph.clingo_utils.add_elements_ids(ctl)¶
Adds a program to the control that will set the ids of the elements to the id attribute :param ctl Clingo.Control: The clingo control object that is used
- clingraph.clingo_utils.add_svg_interaction(paths)¶
Adds the svg interaction script to a list of svg files defined in the paths. This paths can be the output of the render function.
- Parameters
list[dic]] (paths [dic |) – A dictionary with the paths where the images where saved as values for each graph.
dictionaries (Or a list of such) –
model. (each element corresponding to a) –
- clingraph.clingo_utils.add_svg_interaction_to_string(s)¶
Adds the svg interaction script to string representation of the svg image
- Parameters
[str] (s) – the svg string
- clingraph.clingo_utils.parse_clingo_json(json_str)¶
Parses a json string from the output of clingo obtained using the option
--outf=2
. Expects a SATISFIABLE answer.- Parameters
json_str (str) – A string with the json
- Returns
(list[str]) A list with the programs as strings
- Raises
InvalidSyntax – if the json format is invalid or is not a SAT result.