Entry Graphs

Entry graphs are graphs which represent a subset of the ontological network of the database. It is a graph representation of the database, with vertices representing entries and edges representing relationships between entries.

../_images/eg.svg

Entry graphs are created from a set of given initial entries. Entry graphs can be expanded from the initial entries by calling exploration protocols. For more information on the built-in protocols, as well as how to define your own, see Exploration Protocols.

When an entry graph has been expanded, the scoring algorithm can be used to assign scores to each entry, broadly speaking represeenting the connectedness of each entry. See Scoring for details.

ChemRecon provides a number of methods for inspecting the entry graph. However, for more advanced analysis, we recommend using the underlying graph library, rustworkx. The underlying graph object is available as the g attribute of the entry graph. For the directed graphs used in ChemRecon, refer to the following documentation: rustworkx.PyDiGraph.

This page documents the API for the entry graphs.

class chemrecon.EntryGraph(initial_entries: set[Entry])

Bases: object

Represents a directed graph structure of entries and relations.

Variables:

  • g – RustWorkX directed graph object used to store vertices and edges.

  • index_entry – Maps Entry objects to corresponding vertex indices.

  • index_reconid – Maps (Entry type, ReconID) tuples to vertex indices.

  • index_relation – Maps Relation objects to corresponding edge indices.

  • initial_entries – Set of Entry objects that serve as the initial vertices in the graph.

  • initial_vertices – Set of vertex indices corresponding to the initial entries.

  • parent_entrygraph – Reference to the parent EntryGraph if this graph is a subgraph view.

get_vertex_index_by_recon_id(entry_type: type[Entry], recon_id: ReconID) → VertexIndex | None

Retrieve the vertex index associated with the given entry type and recon ID. If no matching vertex index is found, the method returns None.

Parameters:

  • entry_type (type[Entry]) – The class type of the entry being queried.

  • recon_id (ReconID) – The recon ID that uniquely identifies the entry.

Returns:

The vertex index corresponding to the given entry type and recon ID, or None if not found.

Return type:

Optional[VertexIndex]

get_vertex_by_entry(entry: Entry) → VertexIndex | None

Retrieves the vertex index associated with a given entry and returns None if it does not exist.

Parameters:

entry (Entry) – The entry object to search for in the index map.

Returns:

The vertex index associated with the given entry, or None if the entry does not exist in the mapping.

Return type:

Optional[VertexIndex]

get_vertex_by_vertex_index(vertex_index: VertexIndex) → Vertex | None

Retrieve the vertex corresponding to the given vertex index, returns None if it does not exist. :param vertex_index: Index of the vertex to retrieve. :type vertex_index: VertexIndex :return: The vertex associated with the given index or None if it does not exist. :rtype: Optional[Vertex]

get_out_edges_of_vertex(vertex_index: VertexIndex) → list[tuple[Edge, Vertex]]

Retrieve all outgoing edges of a vertex along with the corresponding target vertices.

This method provides a list of tuples where each tuple contains the edge data and the target vertex data for the edges originating from the specified vertex. This function is useful for analysing the outgoing connections and relationships in a graph data structure.

Parameters:

vertex_index (VertexIndex) – Index of the vertex whose outgoing edges are to be queried.

Returns:

A list of tuples with each tuple containing edge data and the target vertex data.

Return type:

list[tuple[Edge, Vertex]]

vertices() → Generator[Vertex, None, None]

Generator over vertices (entries).

edges() → Generator[Edge, None, None]

Generator over edges (relations).

add_vertex(entry: Entry, generation: int = -1) → VertexIndex

Add a new entry to the graph. If it already exists, return the index.

add_edge(source_v_index: VertexIndex, target_v_index: VertexIndex, relation: Relation) → EdgeIndex

Add a relation between the specified source and target vertices

add_vertex_from(from_index: VertexIndex, relation: Relation, entry: T2, generation: int) → VertexIndex

Adds a new entry vertex along with a relation. Returns vertex_index of the newly creted vertex. If the vertex already exists, return add the edge and return the vertex index.

draw(filename: str = None, filetype: str = 'jpg', scores: dict[Entry, float] | None = None)

Draw using default settings, returning an image, or write to the disk if the filename is specified. For more settings, create an EntryGraphDrawer instance.

show(scores: dict[Entry, float] | None = None)

Same as draw, but displays the image in a window instead of saving to disk.

class chemrecon.Vertex(entry: E, generation: int)

Bases: VertexBase, Generic

A database entry in a graph context. None is used as the type parameter for artificial vertices (those not corresponding to a DB object). A vertex is initial if its generation is 0.

vertex_index: VertexIndex

Index in the graph representation.

entry: E

The entry represented by this vertex

recon_id: ReconID
generation: int

Distance from initial entries.

class chemrecon.Edge(relation: R)

Bases: EdgeBase, Generic

A database relation in a graph context. None is used as the type parameter for artificial edges (those not corresponding to a DB object).

edge_index: EdgeIndex

Index in the graph representation

relation: R
recon_id_1: ReconID
recon_id_2: ReconID