API reference

main functions

graphbrain.__init__.hgraph(locator_string)

Returns an instance of Hypergraph identified by the locator_string. The hypergraph will be created if it does not exist.

Currently, the only type of hypergraph is based on LevelDB storage, and the location_string is the path to the LevelDB folder.

hyperedge module

class graphbrain.hyperedge.Atom(edge)

Atomic hyperedge.

all_atoms()

Returns a list of all the atoms contained in the edge. Unlike atoms(), which does not return repeated atoms, all_atoms() does return repeated atoms if they are different objects.

For example, consider the edge: (the/Md (of/Br mayor/Cc (the/Md city/Cs))) in this case, edge.all_atoms() returns: [the/Md, of/Br, mayor/Cc, the/Md, city/Cs]

argroles()

Returns the argument roles string of the edge, if it exists. Otherwise returns empty string.

atom_with_type(atom_type)

Returns the first atom found in the edge that has the given ‘atom_type’, or whose type starts with ‘atom_type’. If no such atom is found, returns None.

For example, given the edge (+/B a/Cn b/Bp) and the ‘atom_type’ C, this function returns: a/Cn If the ‘atom_type’ is ‘Cp’, the it will return: b/Cp

atoms()

Returns the set of atoms contained in the edge.

For example, consider the edge: (the/Md (of/Br mayor/Cc (the/Md city/Cs))) in this case, edge.atoms() returns: [the/Md, of/Br, mayor/Cc, city/Cs]

connector_type()

Returns the type of the edge’s connector. If the edge has no connector (i.e. it’s an atom), then the atom type is returned.

contains(needle, deep=False)

Checks if ‘needle’ is contained in edge.

Keyword argument: deep – search recursively (default False)

depth()

Returns maximal depth of edge, an atom has depth 0.

edges_with_argrole(argrole)

Returns the list of edges with the given argument role

insert_argrole(argrole, pos)

Returns an atom with the given argrole inserted at the specified position. Same restrictions as in replace_argroles() apply.

insert_first_argument(argument)

Returns an edge built by placing ‘argument’ as the first item after the connector of this edge. If this edge is an atom, then it becomes the connector of the returned edge.

For example, considering the ‘edge’ (a) and the ‘argument’ (b), this function returns: (a b)

Considering the ‘edge’ (a b c) and the ‘argument’ (d e), it returns: (a (d e) b c)

is_atom()

Checks if edge is an atom.

is_full_pattern()

Check if every atom is a pattern matcher.

Pattern matchers are: ‘*’, ‘@’, ‘&’, ‘…’ and variables (atom label starting with an uppercase letter)

is_pattern()

Check if this edge defines a pattern, i.e. if it includes at least one pattern matcher.

Pattern matchers are: ‘*’, ‘@’, ‘&’, ‘…’ and variables (atom label starting with an uppercase letter)

label()

Generate human-readable label from entity.

main_concepts()

Returns the list of main concepts in an concept edge. A main concept is a central concept in a built concept, e.g.: in (‘s/Bp.am zimbabwe/Mp economy/Cn.s), economy/Cn.s is the main concept.

If entity is not an edge, or its connector is not of type builder, or the builder does not contain concept role annotations, or no concept is annotated as the main one, then an empty list is returned.

parts()

Splits atom into its parts.

predicate()

Returns predicate atom if this edge is a non-atom of type relation or predicate. Returns itself if it is an atom of type predicate. Returns None otherwise.

replace_argroles(argroles)

Returns an atom with the argroles replaced with the provided string. Returns same atom if the atom does not contain a role part.

replace_atom(old, new)

Returns edge built by replacing every instance of ‘old’ in this edge with ‘new’.

replace_atom_part(part_pos, part)

Build a new atom by replacing an atom part in a given atom.

replace_main_concept(new_main)

TODO: document and test

role()

Returns the role of this atom as a list of the subrole strings.

The role of an atom is its second part, right after the root. A dot notation is used to separate the subroles. For example, the role of graphbrain/Cp.s/1 is:

Cp.s

For this case, this function returns:

[‘Cp’, ‘s’]

If the atom only has a root, it is assumed to be a concept. In this case, this function returns the role with just the generic concept type:

[‘C’].

root()

Extracts the root of an atom (e.g. the root of graphbrain/C/1 is graphbrain).

roots()

Returns edge with root-only atoms.

simplify_role()

Returns atom with a simplified role part. In the simplified role, only the type is specified.

subedges()

Returns all the subedges contained in the edge, including atoms and itself.

to_str(roots_only=False)

Converts atom to its string representation.

Keyword argument: roots_only – only the roots of the atoms will be used to create the string representation.

type()

Returns the type of the atom.

The type of an atom is its first subrole. For example, the type of graphbrain/Cp.s/1 is ‘Cp’.

If the atom only has a root, it is assumed to be a concept. In this case, this function returns the generic concept type: ‘C’.

class graphbrain.hyperedge.Hyperedge(edges)

Non-atomic hyperedge.

all_atoms()

Returns a list of all the atoms contained in the edge. Unlike atoms(), which does not return repeated atoms, all_atoms() does return repeated atoms if they are different objects.

For example, consider the edge: (the/md (of/br mayor/cc (the/md city/cs))) in this case, edge.all_atoms() returns: [the/md, of/br, mayor/cc, the/md, city/cs]

argroles()

Returns the argument roles string of the edge, if it exists. Otherwise returns empty string.

atom_with_type(atom_type)

Returns the first atom found in the edge that has the given ‘atom_type’, or whose type starts with ‘atom_type’. If no such atom is found, returns None.

For example, given the edge (+/B a/Cn b/Cp) and the ‘atom_type’ c, this function returns: a/Cn If the ‘atom_type’ is ‘Cp’, the it will return: b/Cp

atoms()

Returns the set of atoms contained in the edge.

For example, consider the edge: (the/md (of/br mayor/cc (the/md city/cs))) in this case, edge.atoms() returns: [the/md, of/br, mayor/cc, city/cs]

connect(arguments)

Returns an edge built by adding the items in ‘arguments’ to the end of this edge. ‘arguments’ must be a collection.

For example, connecting the edge (a b) with the ‘arguments’ (c d) produces: (a b c d)

connector_type()

Returns the type of the edge’s connector. If the edge has no connector (i.e. it’s an atom), then the atom type is returned.

contains(needle, deep=False)

Checks if ‘needle’ is contained in edge.

Keyword argument: deep – search recursively (default False)

contains_atom_type(atom_type)

Checks if the edge contains any atom with the given type. The edge is searched recursively, so the atom can appear at any depth.

depth()

Returns maximal depth of edge, an atom has depth 0.

edges_with_argrole(argrole)

Returns the list of edges with the given argument role.

insert_argrole(argrole, pos)

Returns an edge with the given argrole inserted at the specified position in the argroles of the connector atom. Same restrictions as in replace_argroles() apply.

insert_edge_with_argrole(edge, argrole, pos)

Returns a new edge with the provided edge and its argroles inserted at the specified position.

insert_first_argument(argument)

Returns an edge built by placing ‘argument’ as the first item after the connector of this edge. If this edge is an atom, then it becomes the connector of the returned edge.

For example, considering the ‘edge’ (a) and the ‘argument’ (b), this function returns: (a b)

Considering the ‘edge’ (a b c) and the ‘argument’ (d e), it returns: (a (d e) b c)

is_atom()

Checks if edge is an atom.

is_full_pattern()

Check if every atom is a pattern matcher.

Pattern matchers are: ‘*’, ‘@’, ‘&’, ‘…’ and variables (atom label starting with an uppercase letter)

is_pattern()

Check if this edge defines a pattern, i.e. if it includes at least one pattern matcher.

Pattern matchers are: ‘*’, ‘@’, ‘&’, ‘…’ and variables (atom label starting with an uppercase letter)

label()

Generate human-readable label for edge.

main_concepts()

Returns the list of main concepts in an concept edge. A main concept is a central concept in a built concept, e.g.: in (‘s/Bp.am zimbabwe/Mp economy/Cn.s), economy/Cn.s is the main concept.

If entity is not an edge, or its connector is not of type builder, or the builder does not contain concept role annotations, or no concept is annotated as the main one, then an empty list is returned.

predicate()

Returns predicate atom if this edge is a non-atom of type relation or predicate. Returns itself if it is an atom of type predicate. Returns None otherwise.

replace_argroles(argroles)

Returns an edge with the argroles of the connector atom replaced with the provided string. Returns same edge if the atom does not contain a role part.

replace_atom(old, new)

Returns edge built by replacing every instance of ‘old’ in this edge with ‘new’.

replace_main_concept(new_main)

TODO: document and test

roots()

Returns edge with root-only atoms.

sequence(entity, before, flat=True)

Returns an edge built by sequencing the ‘entity’, if it’s an atom, or the elements of ‘entity’ if it is an edge, either before or after the elements of this edge.

If flat is False, then both this edge and ‘entity’ are treated as self-contained edges when building the new edge.

For example, connecting the edge (a b) and the ‘entity’ c produces, if before is True: (c a b) and if before is False: (a b c) Connecting the edge (a b) and the ‘entity’ (c d) produces, if before is True: (c d a b) and if before is False: (a b c d) This last example, if ‘flat’ is False, becomes respectively: ((c d) (a b)) ((a b) (c d))

subedges()

Returns all the subedges contained in the edge, including atoms and itself.

to_str(roots_only=False)

Converts edge to its string representation.

Keyword argument: roots_only – only the roots of the atoms will be used to create the string representation.

type()

Returns the type of this edge as a string.

The type is derived from the type of the connector. This applies recursively, as necessary.

For example: (is/Pd.so graphbrain/Cp.s great/C) has type ‘Rd’ (red/M shoes/Cn.p) has type ‘Cn’ (before/Tt noon/C) has type ‘St’

class graphbrain.hyperedge.UniqueAtom(edge)

graphbrain.hyperedge.build_atom()

Build an atom from text and other parts.

graphbrain.hyperedge.edge_matches_pattern()

Check if an edge matches a pattern.

Patterns are themselves edges. They can match families of edges by employing special atoms:

-> ‘*’ represents a general wildcard (matches any entity)

-> ‘@’ represents an atomic wildcard (matches any atom)

-> ‘&’ represents an edge wildcard (matches any edge)

-> ‘…’ at the end indicates an open-ended pattern.

The pattern can be any valid hyperedge, including the above special atoms. Examples: (is/Pd graphbrain/C @) (says/Pd * …)

graphbrain.hyperedge.edges2str()

Convert a collection of edges to a string representation (no outer parenthesis).

graphbrain.hyperedge.hedge()

Create an hyperedge.

graphbrain.hyperedge.match_pattern()

Matches an edge to a pattern. This means that, if the edge fits the pattern, then a dictionary will be returned with the values for each pattern variable. If the pattern specifies no variables but the edge matches it, then an empty dictionary is returned. If the edge does not match the pattern, None is returned.

Patterns are themselves edges. They can match families of edges by employing special atoms:

-> ‘*’ represents a general wildcard (matches any entity)

-> ‘@’ represents an atomic wildcard (matches any atom)

-> ‘&’ represents an edge wildcard (matches any edge)

-> ‘…’ at the end indicates an open-ended pattern.

The three wildcards (‘*’, ‘@’ and ‘&’) can be used to specify variables, for example ‘*x’, ‘&claim’ or ‘@actor’. In case of a match, these variables are assigned the hyperedge they correspond to. For example,

(1) the edge: (is/Pd (my/Mp name/Cn) mary/Cp) applied to the pattern: (is/Pd (my/Mp name/Cn) *NAME) produces the result: {‘NAME’, mary/Cp}

(2) the edge: (is/Pd (my/Mp name/Cn) mary/Cp) applied to the pattern: (is/Pd (my/Mp name/Cn) &NAME) produces the result: {}

(3) the edge: (is/Pd (my/Mp name/Cn) mary/Cp) applied to the pattern: (is/Pd @ *NAME) produces the result: None

graphbrain.hyperedge.rel_arg_role()

Returns argument role of argument in a given ‘position’ of ‘relation’. Returns None if argument role cannot be determined.

Example: The argument role of argument at position 0 in: (is/Pd.sc graphbrain/C great/C) is: s

graphbrain.hyperedge.split_edge_str()

Shallow split into tokens of a string representation of an edge, without outer parenthesis.

graphbrain.hyperedge.str2atom()

Converts a string into a valid atom.

hypergraph module

class graphbrain.hypergraph.Hypergraph

Hypergraph interface.

add(edge, primary=True, count=False)

Adds an edge if it does not exist yet, returns same edge. All children are recursively added as non-primary edge, for indexing purposes.

Edges can be passed in both Hyperedge or string format.

Keyword arguments: primary – edge is primary, meaning, for example, that it counts towards degrees. Non-primary edges are used for indexing purposes, for example to make it easy to find the subedges contained in primary edges when performing queries. count – an integer counter attribute is added to the edge. If the edge already exists, the counter is incremented.

add_to_sequence(name, pos, edge)

Adds ‘edge’ to sequence ‘name’ at position ‘pos’.

all()

Returns a generator of all the edges.

all_atoms()

Returns a generator of all the atoms.

all_attributes()

Returns a generator with a tuple for each edge. The first element of the tuple is the edge itself, the second is a dictionary of attribute values (as strings).

all_non_atoms()

Returns a generator of all the edges that are not atoms.

atom_count()

Returns total number of atoms.

atoms_with_root(root)

Returns generator of all atoms with the given root.

close()

Closes the hypergraph.

count(pattern)

Number of edges that match a pattern. See search() method for an explanation of patterns.

dec_attribute(edge, attribute)

Increments an attribute of an entity.

deep_degree(edge)

Returns the deep degree of an entity.

degree(edge)

Returns the degree of an entity.

destroy()

Erase the entire hypergraph.

edge_count()

Returns total number of edges.

edges_with_edges(edges, root=None)

Returns generator of all edges containing the given edges, and optionally a given root.

Keyword argument: root – edge must also contain an atom with this root (default None)

ego(center)

Returns all atoms directly connected to center by hyperedges.

exists(edge)

Checks if the given edge exists.

get_float_attribute(edge, attribute, or_else=None)

Returns attribute as float value.

or_else – value to return if the entity does not have

the give attribute. (default None)

get_int_attribute(edge, attribute, or_else=None)

Returns attribute as integer value.

or_else – value to return if the entity does not have

the give attribute. (default None)

get_str_attribute(edge, attribute, or_else=None)

Returns attribute as string.

Keyword argument: or_else – value to return if the entity does not have the given attribute. (default None)

inc_attribute(edge, attribute)

Increments an attribute of an entity, sets initial value to 1 if attribute does not exist.

is_primary(edge)

Check if an edge is primary.

name()

Returns name of the hypergraph.

primary_atom_count()

Returns number of primary atoms.

primary_edge_count()

Returns number of primary edges.

remove(edge, deep=False)

Removes an edge.

Keyword argument: deep – recursively remove all subedges (default False)

remove_by_pattern(pattern)

Removes all edges that match the pattern.

root_degrees(edge)

Finds all the atoms that share the same root as the given edge and computes the sum of both their degrees and deep degrees. These two sums are returned.

If the parameter edge is non-atomic, this function simply returns the degree and deep degree of that edge.

search(pattern)

Returns generator for all the edges that match a pattern.

Patterns are themselves edges. They can match families of edges by employing special atoms: -> ‘*’ represents a general wildcard (matches any edge) -> ‘@’ represents an atomic wildcard (matches any atom) -> ‘&’ represents a non-atomic wildcard (matches any non-atom) -> ‘…’ at the end indicates an open-ended pattern.

The pattern can be a string, that must represent an edge. Examples: ‘(is/Pd graphbrain/C @)’ ‘(says/pd * …)’

Atomic patterns can also be used to match all edges in the hypergraph (*), all atoms (@), and all non-atoms (&).

sequence(name)

Returns an iterator for a sequence of hyperedges, given the name of the sequence.

sequences()

Returns an iterator for all the sequence names present in the hypergraph.

set_attribute(edge, attribute, value)

Sets the value of an attribute.

set_primary(edge, value)

Make edge primary if value is True, make it non-primary otherwise.

star(center, limit=None)

Returns generator of the edges that contain the center.

Keyword argument: limit – maximum number of results to return, infinite if None

sum_deep_degree(edges)

Returns sum of the deep degrees of all edges contained in the parameter.

sum_degree(edges)

Returns sum of the degrees of all edges contained in the parameter.

notebook module

graphbrain.notebook.show(edge, roots_only=True, style='indented')

Displays a representation of the edge in the notebook.

Keyword arguments:

roots_only – only show roots of atoms (default: True)

style – render style (‘indented’, ‘compact’ or ‘oneline’) (default: ‘indented’)

parsers package

package functions

graphbrain.parsers.__init__.create_parser(name, lemmas=False, resolve_corefs=False)

Creates and returns a parser (as an instanceof a subclass of Parser) for the language specified in the parameter. Throws exception if language is not implemented.

Available parsers: ‘en’ – English

Keyword argument: lemmas – if True, lemma edges are generated by the parser. resolve_corefs – if True, coreference resolution is performed. (default: False)

parser module

class graphbrain.parsers.parser.Parser(lemmas=False, resolve_corefs=False, debug=False)

Defines the common interface for parser objects. Parsers transofrm natural text into graphbrain hyperedges.

parse(text)

Transforms the given text into hyperedges + aditional information. Returns a dictionary with two fields:

-> parses: a sequence of dictionaries, with one dictionary for each sentence found in the text.

-> inferred_edges: a sequence of edges inferred during by parsing process (e.g. genders, ‘X is Y’ relationships)

Each sentence parse dictionary contains at least the following fields:

-> main_edge: the hyperedge corresponding to the sentence.

-> resolved_corefs: main_edge with coreferences resolved, can be the same as main_edge if coreference resolution is not performed.

-> extra_edges: aditional edges, e.g. connecting atoms that appear in the main_edge to their lemmas.

-> text: the string of natural language text corresponding to the main_edge, i.e.: the sentence itself.

-> edges_text: a dictionary of all edges and subedges to their corresponding text.

meaning package

actors module

graphbrain.meaning.actors.actors(hg)

“Returns an iterator over all actors.

graphbrain.meaning.actors.find_actors(hg, edge)

Returns set of all coreferences to actors found in the edge.

graphbrain.meaning.actors.is_actor(hg, edge)

Checks if the edge is a coreference to an actor.

concepts module

graphbrain.meaning.concepts.all_concepts(edge)

Recursively search for all concepts contained in the edge, returning a set that can also contain itself.

graphbrain.meaning.concepts.has_common_or_proper_concept(edge)

Check if the concept either is a common/proper edge, or contains one.

graphbrain.meaning.concepts.has_proper_concept(edge)

Check if the concept either is a proper edge, or contains one.

graphbrain.meaning.concepts.strip_concept(edge)

Strip away nesting edges with connectors such as triggers and subpredicates, to expose the outmost and leftmost concept that can be found. May be the edge itself.

For example:

(against/T (the/M (of/B treaty/C paris/C)))

becomes

(the/M (of/B treaty/C paris/C))

corefs module

graphbrain.meaning.corefs.are_corefs(hg, edge1, edge2, corefs=None)

Checks if the two given edges are coreferences.

graphbrain.meaning.corefs.coref_id(hg, edge)

Returns the coreference identifier of the edge.

graphbrain.meaning.corefs.coref_set(hg, edge, corefs=None)

Returns the set of coreferences that the given edge belongs to.

graphbrain.meaning.corefs.main_coref(hg, edge)

Returns main edge for the coreference set that the given edge belongs to.

graphbrain.meaning.corefs.main_coref_from_id(hg, cref_id)

Returns main edge in the coreference set for the given identifier.

graphbrain.meaning.corefs.make_corefs(hg, edge1, edge2)

Make the two given edges belong to the same corefernce set.

This may trigger further updates to maintain consistency, such as merging existing coreference sets and recomputing the main edge of a coreference set.

lemmas module

graphbrain.meaning.lemmas.deep_lemma(hg, edge)

Returns the lemma of an atomic edge, or the lemma of the first atom found by recursively descending the hyperedge, always choosing the subedge immediatly after the connector.

This is useful, for example, to find the lemma of the central verb in a non-atomic predicate edge. For example:

(not/A (is/A going/P))

could return

go/P

graphbrain.meaning.lemmas.lemma(hg, atom)

Returns the lemma of the given atom if it exists, None otherwise.

graphbrain.meaning.lemmas.lemma_degrees(hg, edge)

Finds all the atoms that share the same given lemma and computes the sum of both their degrees and deep degrees. These two sums are returned.

If the parameter edge is non-atomic, this function simply returns the degree and deep degree of that edge.

ontology module

graphbrain.meaning.ontology.subtypes(hg, edge, deep=False)

Returns all subtypes of the given edge.

graphbrain.meaning.ontology.supertypes(hg, edge, deep=False)

Returns all supertypes of the given edge.

cognition package

package functions

system module

agent module

class graphbrain.cognition.agent.Agent(name, progress_bar=True, logging_level=20)

Base class for Graphbrain cognitive agents.

These agents perform some change to an hypergraph, either by processing some external source of information of by inferring new knowledge from what is already contained in the hypregraph.

input()

Input to the agent all the edges corresponding to its current search pattern. A typical use is in knowledge inference agents, which infer new knowledge from edges already present in the hypergraph.

input_edge(edge, depth=0)

Feeds the agent an edge to process.

languages()

Returns set of languages supported by the agent, or an empty set if the agent is language-agnostic.

on_end()

Called at the end of a cycle of activity.

on_start()

Called before a cycle of activity is started.

process_edge(edge, depth)

Feeds the agent an edge to process.

report()

Produce a report of the agent’s activities.

run()

High-level method to run an agent.