API Documentation#

Factbase#

class Factbase(prefix: str = '', default_graph: str = 'default')[source]#

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')[source]#

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)[source]#

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)[source]#

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_fb(fb)[source]#: Adds a clorm fact base to the Factbase

add_model(model)[source]#

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')[source]#

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')[source]#

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()[source]#

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)[source]#

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 or node
element_id – Identifier of the element

Returns

(dic) A dictionary with attribute names as key and attribute values as values.

get_facts()[source]#

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)[source]#

Gets the list of elements for a graph

Parameters

element_type (str) – The element type: edge or node
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)[source]#

Gets the attributes for a global element: graph_nodes or graph_edges.

Parameters

element_type (str) – The element type: edge or node
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)[source]#

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

compute_graphs(fb, graphviz_type='graph', seed=None)[source]#

Computes graphs using Graphviz for the given factbase

Parameters

fb (list[Factbase] | Factbase) – A Factbase 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 for graphviz.Graph and digraph for graphviz.Digraph
seed (int) – A number used as seed

dot(graphs)[source]#

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.

render(graphs, directory='out', format='pdf', name_format=None, engine='dot', view=False)[source]#

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 or svg
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 integration to generate gifs

save_gif(graphs, directory='out', name_format='movie', engine='dot', fps=1, sort='asc-str')[source]#

Generates a gif for the given 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) – Path to the directory where to write
name_format (str) – The file name for the gif can include {model_number}
engine (str) – The engine used for rendering
fps (int) – The number of frames per second
sort (str) – How to sort the images used to generate the gif asc-str Sort ascendent based on the graph name, desc-str Sort descendent based on the graph name, asc-int Sort descendent based on the graph name converted to an interger, desc-int Sort descendent based on the graph name converted to an integer, name1,...,namex A string with the order of the graph names separated by ,

Returns

A dictionary with the paths where the gifss 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 tex#

Graphviz integration to generate latex

tex(graphs, **kwargs)[source]#

Generates the latex code 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.
**kwargs – Any additional arguments passed to dot2tex dot2tex() function

Returns: (dic|list[dic]) The dictionary or list with a string containing the latex code instead of the graphviz objects.

Utils#

Utils functions used across the project

apply(elements, function, **kwargs)[source]#

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

pythonify_symbol(s)[source]#

Get a python element from a clingo symbol

Parameters: s (clingo.Symbol) – The clingo symbol
Returns: A integer, string or tuple

stringify_symbol(s)[source]#

Get a string representation of a clingo symbol

Parameters: s (clingo.Symbol) – The clingo symbol
Returns: A string

write(elements, directory, format, name_format=None)[source]#

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 ClingraphContext[source]#

Provides avaliable python functions to be used in a visualization encoding passed in the command line via option –viz-encoding

clinguin_fontname()[source]#: Gets the font name used in clinguin

cluster(s)[source]#

Returns the cluster name for a graph

Parameters: s – The identifier of the graph
Returns: (clingo.Symbol.String) The string with the cluster name

color(option, opacity=None)[source]#

Gets the html color code for the different options and the given opacity

Parameters

option – primary, secondary, success, info, warning, danger, light
opacity – Numeric value indicating the opacity of the color

concat(*args)[source]#

Concatenates the given symbols as a string

Parameters: args – All symbols
Returns: (clingo.Symbol.String) The string concatenating all symbols

format(s, *args)[source]#

Formats the string with the given arguments

Parameters

s (clingo.Symbol.String) – The string to format, for example “{0} and {1}”
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)[source]#

Will escape the symbols of an HTML-Like label that provoque clashes: &, < and >

Parameters: s (clingo.Symbol) – The value that needs the symbols removed
Returns: (clingo.Symbol.String) The string with the replacements

pos(x, y, scale=1)[source]#

Position in the form of a tuple

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)[source]#

Turns a value into a string without underscore and capitalized if requested

Parameters: s – The value to transform
Returns: (clingo.Symbol.String) The string

svg(event, element, property_name, property_value)[source]#

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.

Parameters

event – The svg event one of: “click”,”mouseenter”,”mouseleave”,”contextmenu”
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).
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 internal representation of the interaction

svg_color()[source]#

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)[source]#

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

add_elements_ids(ctl)[source]#: 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

add_svg_interaction(paths)[source]#

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) –

add_svg_interaction_to_string(s)[source]#

Adds the svg interaction script to string representation of the svg image

Parameters: [str] (s) – the svg string

parse_clingo_json(json_str)[source]#

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.

Exceptions#

Exceptions

exception InvalidSyntax(*args)[source]#: Exception returned when the input syntax is not expected

exception InvalidSyntaxJSON(*args)[source]#: Exception returned when the input syntax is not expected