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

Atomic hyperedge.

argroles

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

atom_with_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 set of atoms contained in edge.

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

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

Returns the list of edges with the given argument role

insert_first_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 ‘…’

is_pattern

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

Pattern matchers are: ‘*’, ‘@’, ‘&’’ and ‘…’

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_atom

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

replace_atom_part

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

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.

subedges

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

to_str

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

Non-atomic hyperedge.

argroles

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

atom_with_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 set of atoms contained in edge.

connect

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

Checks if ‘needle’ is contained in edge.

Keyword argument: deep – search recursively (default False)

contains_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

Returns the list of edges with the given argument role.

insert_first_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 ‘…’

is_pattern

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

Pattern matchers are: ‘*’, ‘@’, ‘&’’ and ‘…’

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.

nest

Returns a new entity built by nesting this edge (inner) inside the given (outer) edge.

Nesting the ‘inner’ atom (a) in the ‘outer’ atom (b) produces: (b a)

Nesting the ‘inner’ edge (a b) in the ‘outer’ atom c produces: (c (a b))

If the outer entity is an edge, the result depends on the ‘before’ parameter. Considering the ‘inner’ entity (a b) and the ‘outer’ entity (c d), nesting if ‘before’ is True produces: (c d (a b)) If ‘before’ is False it produces: (c (a b) d)

Keyword argument: before – controls how outer edges are handled, as per above. (default: False)

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_atom

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

roots

Returns edge with root-only atoms.

sequence

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

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’

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)

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 argument: 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.

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.

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.

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 (&).

search_count(pattern)

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

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)

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. (default: False)

parser module

class graphbrain.parsers.parser.Parser(lemmas=False)

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

parse(text)

Transforms the given text into hyperedges + aditional information. Returns a sequence of dictionaries, with one dictionary for each sentence found in the text.

Each dictionary contains the following fields:

-> main_edge: the hyperedge corresponding to the sentence.

-> 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.

-> spacy_sentence: the spaCy structure representing the sentence enriched with NLP annotations.

meaning package

actors module

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_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.

agents package

package functions

graphbrain.agents.__init__.create_agent(name, hg)

Creates and returns an instance of the agent identified by the given name. Throws an exception if no such agent is known.

agent module

class graphbrain.agents.agent.Agent(hg)

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.

add(edge, primary=True)

Tell agent to add this edge to the hypergraph.

end()

End the agent’s current cycle of activities.

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)

Feeds the agent an edge to process.

input_file(file_name)

Feeds the agent a path to a file to process.

languages()

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

name()

Returns the agent’s name.

report()

Produce a report of the agent’s activities.

run(infile=None)

High-level method to run an agent. It will start a cycle of activities, provide a full set of inputs, end the cycle of activities and print a report.

Keyword argument:

infile – if provided, agent inputs information from a file, otherwise it goes through all the edges present in the hypergraph that are selected by its internal pattern (defaulting to ‘*’, meaning all of them).

start()

Tell agent that a new cycle of activity is starting. What this means in practice depends on the agent. For example, for a knowledge inference agent this could mean one full pass through all the edges in the hypergraph. For an agent that extracts knowledge from external files, this could mean one pass through an entire file.