decomp.semantics.uds.graph

Graph representations for Universal Decompositional Semantics (UDS) annotations.

This module provides the core graph infrastructure for representing UDS annotations at both sentence and document levels using NetworkX directed graphs. The graphs capture syntactic structure, semantic predicates and arguments, and the interfaces between them.

Key Components

Type Aliases

  • NodeID: String identifiers for graph nodes

  • EdgeKey: Tuples identifying edges between nodes

  • NodeAttributes, EdgeAttributes: Dictionaries storing node/edge properties

  • DomainType: The domain a node belongs to (‘syntax’, ‘semantics’, ‘document’)

  • NodeType: The type of node (‘token’, ‘predicate’, ‘argument’, ‘root’)

  • EdgeType: The type of edge (‘head’, ‘dependency’, ‘interface’)

Classes

  • UDSGraph: Abstract base class providing core graph functionality

  • UDSSentenceGraph: Sentence-level graphs with syntax and semantics layers

  • UDSDocumentGraph: Document-level graphs connecting multiple sentences

The graphs use a consistent naming scheme where node IDs incorporate the graph name and domain (e.g., ‘ewt-001-1-syntax-1’ for a syntax token). Edge attributes specify the domain and type of relationship between nodes.

Features include SPARQL querying via RDF conversion, graph operations for finding maximal/minimal nodes, extracting subgraphs by domain, and adding UDS annotations to existing graph structures. The sentence graphs automatically add performative nodes representing the speaker/addressee for discourse representation.

See also

decomp.semantics.uds.annotation

UDS annotation classes

decomp.semantics.uds.corpus

Corpus-level UDS graph collections

decomp.graph.nx

NetworkX graph utilities

class UDSGraph[source]

Bases: ABC

Abstract base class for sentence- and document-level graphs.

Parameters:

  • graph (DiGraph) – a NetworkX DiGraph

  • name (str) – a unique identifier for the graph

abstractmethod __init__(graph, name)[source]
property nodes: dict[NodeID, NodeAttributes]

All nodes in the graph with their attributes.

Returns:

Mapping from node IDs to their attributes

Return type:

dict[NodeID, NodeAttributes]

property edges: dict[EdgeKey, EdgeAttributes]

All edges in the graph with their attributes.

Returns:

Mapping from edge tuples to their attributes

Return type:

dict[EdgeKey, EdgeAttributes]

to_dict()[source]

Convert the graph to adjacency dictionary format.

Returns:

NetworkX adjacency data format

Return type:

dict[str, dict[str, dict[str, str | int | bool | dict[str, str]]]]

classmethod from_dict(graph, name='UDS')[source]

Construct a UDSGraph from a dictionary.

Parameters:
Return type:

UDSGraph

class UDSSentenceGraph[source]

Bases: UDSGraph

A Universal Decompositional Semantics sentence-level graph.

Parameters:

  • graph (DiGraph) – the NetworkX DiGraph from which the sentence-level graph is to be constructed

  • name (str) – the name of the graph

  • sentence_id (str | None, default: None) – the UD identifier for the sentence associated with this graph

  • document_id (str | None, default: None) – the UD identifier for the document associated with this graph

QUERIES: ClassVar[dict[str, Query]] = {}
__init__(graph, name, sentence_id=None, document_id=None)[source]
property rdf: Graph

The graph converted to RDF format.

Returns:

RDFLib graph representation

Return type:

Graph

Raises:

AttributeError – If RDFConverter is not available

property rootid: NodeID

The ID of the graph’s root node.

Returns:

The root node identifier

Return type:

NodeID

Raises:

ValueError – If the graph has no root or multiple roots

query(query, query_type=None, cache_query=True, cache_rdf=True)[source]

Query graph using SPARQL 1.1.

Parameters:

  • query (str | Query) – a SPARQL 1.1 query

  • query_type (str | None, default: None) – whether this is a ‘node’ query or ‘edge’ query. If set to None (default), a Results object will be returned. The main reason to use this option is to automatically format the output of a custom query, since Results objects require additional postprocessing.

  • cache_query (bool, default: True) – whether to cache the query; false when querying particular nodes or edges using precompiled queries

  • clear_rdf – whether to delete the RDF constructed for querying against. This will slow down future queries but saves a lot of memory

Return type:

Result | dict[str, TypeAliasType] | dict[TypeAliasType, TypeAliasType]

property syntax_nodes: dict[str, NodeAttributes]

All syntax domain token nodes.

Returns:

Mapping of node IDs to attributes for syntax tokens

Return type:

dict[str, NodeAttributes]

property semantics_nodes: dict[str, NodeAttributes]

All semantics domain nodes.

Returns:

Mapping of node IDs to attributes for semantics nodes

Return type:

dict[str, NodeAttributes]

property predicate_nodes: dict[str, NodeAttributes]

All predicate nodes in the semantics domain.

Returns:

Mapping of node IDs to attributes for predicates

Return type:

dict[str, NodeAttributes]

property argument_nodes: dict[str, NodeAttributes]

All argument nodes in the semantics domain.

Returns:

Mapping of node IDs to attributes for arguments

Return type:

dict[str, NodeAttributes]

property syntax_subgraph: DiGraph

Subgraph containing only syntax nodes.

Returns:

NetworkX subgraph with syntax nodes

Return type:

DiGraph

property semantics_subgraph: DiGraph

Subgraph containing only semantics nodes.

Returns:

NetworkX subgraph with semantics nodes

Return type:

DiGraph

semantics_edges(nodeid=None, edgetype=None)[source]

Return edges between semantics nodes.

Parameters:

  • nodeid (str | None, default: None) – The node that must be incident on an edge

  • edgetype (str | None, default: None) – The type of edge (“dependency” or “head”)

Return type:

dict[TypeAliasType, TypeAliasType]

argument_edges(nodeid=None)[source]

Return edges between predicates and their arguments.

Parameters:

nodeid (str | None, default: None) – The node that must be incident on an edge

Return type:

dict[TypeAliasType, TypeAliasType]

argument_head_edges(nodeid=None)[source]

Return edges between nodes and their semantic heads.

Parameters:

nodeid (str | None, default: None) – The node that must be incident on an edge

Return type:

dict[TypeAliasType, TypeAliasType]

syntax_edges(nodeid=None)[source]

Return edges between syntax nodes.

Parameters:

nodeid (str | None, default: None) – The node that must be incident on an edge

Return type:

dict[TypeAliasType, TypeAliasType]

instance_edges(nodeid=None)[source]

Return edges between syntax nodes and semantics nodes.

Parameters:

nodeid (str | None, default: None) – The node that must be incident on an edge

Return type:

dict[TypeAliasType, TypeAliasType]

span(nodeid, attrs=None)[source]

Get the span corresponding to a semantics node.

Parameters:

  • nodeid (str) – the node identifier for a semantics node

  • attrs (list[str] | None, default: None) – a list of syntax node attributes to return

Return type:

dict[int, list[TypeAliasType]]

Returns:

  • a mapping from positions in the span to the requested

  • attributes in those positions

head(nodeid, attrs=None)[source]

Get the head corresponding to a semantics node.

Parameters:

  • nodeid (str) – the node identifier for a semantics node

  • attrs (list[str] | None, default: None) – a list of syntax node attributes to return

Return type:

tuple[int, list[TypeAliasType]]

Returns:

  • a pairing of the head position and the requested

  • attributes

maxima(nodeids=None)[source]

Find nodes not dominated by any other nodes in the set.

Parameters:

nodeids (list[str] | None, optional) – Nodes to consider. If None, uses all nodes.

Returns:

Node IDs that have no incoming edges from other nodes in the set

Return type:

list[str]

minima(nodeids=None)[source]

Find nodes not dominating any other nodes in the set.

Parameters:

nodeids (list[str] | None, optional) – Nodes to consider. If None, uses all nodes.

Returns:

Node IDs that have no outgoing edges to other nodes in the set

Return type:

list[str]

add_annotation(node_attrs, edge_attrs, add_heads=True, add_subargs=False, add_subpreds=False, add_orphans=False)[source]

Add node and or edge annotations to the graph.

Parameters:

  • node_attrs (dict[str, TypeAliasType])

  • edge_attrs (dict[TypeAliasType, TypeAliasType])

  • add_heads (bool, default: True)

  • add_subargs (bool, default: False)

  • add_subpreds (bool, default: False)

  • add_orphans (bool, default: False)

Return type:

None

property sentence: str

The sentence text reconstructed from syntax nodes.

Returns:

The sentence text with tokens in surface order

Return type:

str

class UDSDocumentGraph[source]

Bases: UDSGraph

A Universal Decompositional Semantics document-level graph.

Parameters:

  • graph (DiGraph) – the NetworkX DiGraph from which the document-level graph is to be constructed

  • name (str) – the name of the graph

__init__(graph, name)[source]
add_annotation(node_attrs, edge_attrs, sentence_ids)[source]

Add node and or edge annotations to the graph.

Parameters:

  • node_attrs (dict[str, TypeAliasType]) – the node annotations to be added

  • edge_attrs (dict[TypeAliasType, TypeAliasType]) – the edge annotations to be added

  • sentence_ids (dict[str, str]) – the IDs of all sentences in the document

Return type:

None