Enhances documentation across UDS modules, including detailed descriptions for the UDS corpus, annotation, and metadata classes. Refines type hints for improved clarity and consistency, ensuring better type safety throughout the UDS annotation system. Updates method signatures and docstrings to reflect changes, enhancing usability for developers working with UDS datasets.

Author: aaronstevenwhite

decomp/corpus/corpus.py

@@ -1,26 +1,56 @@
-"""Module for defining abstract graph corpus readers"""
+"""Abstract base class for graph corpus readers.
+
+This module provides the foundational :class:`Corpus` class for managing collections
+of graphs in the decomp framework. The Corpus class serves as an abstract base that
+concrete corpus implementations extend to handle specific graph formats.
+
+The module defines a generic corpus container that:
+- Accepts raw graphs in an input format
+- Transforms them to an output format via an abstract graph builder
+- Provides dictionary-like access to the processed graphs
+- Handles errors during graph construction gracefully
+
+Type Variables
+--------------
+InGraph
+ The input graph type that will be processed by the corpus reader.
+
+OutGraph
+ The output graph type produced after processing.
+
+Type Aliases
+------------
+GraphDict[T]
+ Generic dictionary mapping hashable identifiers to graphs of type T.
+
+Classes
+-------
+Corpus
+ Abstract base class for graph corpus containers with generic type parameters
+ for input and output graph formats.
+"""
 
 from abc import ABCMeta, abstractmethod
 from collections.abc import Hashable, ItemsView, Iterator
 from logging import warning
 from random import sample
-from typing import Generic, TypeAlias, TypeVar
+from typing import TypeVar
 
 
 InGraph = TypeVar('InGraph') # the input graph type
 OutGraph = TypeVar('OutGraph') # the output graph type
 
-GraphDict: TypeAlias = dict[Hashable, OutGraph]
+type GraphDict[T] = dict[Hashable, T]
 
 
-class Corpus(Generic[InGraph, OutGraph], metaclass=ABCMeta):
- """Container for graphs
+class Corpus[InGraph, OutGraph](metaclass=ABCMeta):
+ """Container for graphs.
 
  Parameters
  ----------
  graphs_raw
- a sequence of graphs in a format that the graphbuilder for a
- subclass of this abstract class can process
+ A sequence of graphs in a format that the graphbuilder for a
+ subclass of this abstract class can process.
  """
 
  def __init__(self, graphs_raw: dict[Hashable, InGraph]):
@@ -32,7 +62,7 @@ def __iter__(self) -> Iterator[Hashable]:
  return iter(self._graphs)
 
  def items(self) -> ItemsView[Hashable, OutGraph]:
- """Dictionary-like iterator for (graphid, graph) pairs"""
+ """Dictionary-like iterator for (graphid, graph) pairs."""
  return self._graphs.items()
 
  def __getitem__(self, k: Hashable) -> OutGraph:
@@ -56,14 +86,16 @@ def _build_graphs(self) -> None:
  warning(f'{graphid} has loops')
 
  @abstractmethod
- def _graphbuilder(self,
- graphid: Hashable,
- rawgraph: InGraph) -> OutGraph:
+ def _graphbuilder(
+ self,
+ graphid: Hashable,
+ rawgraph: InGraph
+ ) -> OutGraph:
  raise NotImplementedError
 
  @property
  def graphs(self) -> dict[Hashable, OutGraph]:
- """The graphs in corpus"""
+ """The graphs in corpus."""
  return self._graphs
 
  @property

decomp/semantics/uds/__init__.py

@@ -1,4 +1,52 @@
-"""Module for representing UDS corpora, documents, graphs, and annotations."""
+"""Universal Decompositional Semantics (UDS) representation framework.
+
+This module provides a comprehensive framework for working with Universal Decompositional
+Semantics (UDS) datasets. UDS is a semantic annotation framework that captures diverse
+semantic properties of natural language texts through real-valued annotations on
+predicate-argument structures.
+
+The module is organized hierarchically:
+
+- **Annotations** (:mod:`~decomp.semantics.uds.annotation`): Provides classes for handling
+ UDS property annotations in both raw (multi-annotator) and normalized (aggregated) formats.
+
+- **Graphs** (:mod:`~decomp.semantics.uds.graph`): Implements graph representations at
+ sentence and document levels, integrating syntactic dependency structures with semantic
+ annotations.
+
+- **Documents** (:mod:`~decomp.semantics.uds.document`): Represents complete documents
+ containing multiple sentences with their associated graphs and metadata.
+
+- **Corpus** (:mod:`~decomp.semantics.uds.corpus`): Manages collections of UDS documents
+ and provides functionality for loading, querying, and serializing UDS datasets.
+
+Classes
+-------
+NormalizedUDSAnnotation
+ Annotations with aggregated values and confidence scores from multiple annotators.
+
+RawUDSAnnotation
+ Annotations preserving individual annotator responses before aggregation.
+
+UDSSentenceGraph
+ Graph representation of a single sentence with syntax and semantics layers.
+
+UDSDocumentGraph
+ Graph connecting multiple sentence graphs within a document.
+
+UDSDocument
+ Container for sentence graphs and document-level annotations.
+
+UDSCorpus
+ Collection of UDS documents with support for various data formats and queries.
+
+Notes
+-----
+The UDS framework builds upon the PredPatt system for extracting predicate-argument
+structures and extends it with rich semantic annotations. All graph representations
+use NetworkX for the underlying graph structure and support SPARQL queries via RDF
+conversion.
+"""
 
 from .annotation import NormalizedUDSAnnotation, RawUDSAnnotation
 from .corpus import UDSCorpus

decomp/semantics/uds/annotation.py

@@ -22,7 +22,7 @@
 from overrides import overrides
 
 from .metadata import PrimitiveType, UDSAnnotationMetadata, UDSPropertyMetadata
-from .types import AnnotatorValue as TypedAnnotatorValue
+from .types import AnnotatorValue as TypedAnnotatorValue, UDSSubspace
 
 
 # type aliases for annotation data structures
@@ -209,11 +209,13 @@ def _process_node_data(self, data: dict[str, dict[str, NormalizedData | RawData]
 
  # Some attributes are not property subspaces and are thus excluded
  self._excluded_attributes = {'subpredof', 'subargof', 'headof', 'span', 'head'}
- self._node_subspaces = {ss for gid, nodedict
- in self._node_attributes.items()
- for nid, subspaces in nodedict.items()
- for ss in subspaces}
- self._node_subspaces = self._node_subspaces - self._excluded_attributes
+ self._node_subspaces: set[UDSSubspace] = {
+ cast(UDSSubspace, ss) for gid, nodedict
+ in self._node_attributes.items()
+ for nid, subspaces in nodedict.items()
+ for ss in subspaces
+ if ss not in self._excluded_attributes
+ }
 
  def _process_edge_data(self, data: dict[str, dict[str, NormalizedData | RawData]]) -> None:
  """Extract edge attributes from annotation data.
@@ -231,10 +233,12 @@ def _process_edge_data(self, data: dict[str, dict[str, NormalizedData | RawData]
  if '%%' in edge}
  for gid, attrs in data.items()}
 
- self._edge_subspaces = {ss for gid, edgedict
- in self._edge_attributes.items()
- for eid, subspaces in edgedict.items()
- for ss in subspaces}
+ self._edge_subspaces: set[UDSSubspace] = {
+ cast(UDSSubspace, ss) for gid, edgedict
+ in self._edge_attributes.items()
+ for eid, subspaces in edgedict.items()
+ for ss in subspaces
+ }
 
  def _validate(self) -> None:
  """Validate annotation data consistency.
@@ -454,39 +458,39 @@ def metadata(self) -> UDSAnnotationMetadata:
  return self._metadata
 
  @property
- def node_subspaces(self) -> set[str]:
+ def node_subspaces(self) -> set[UDSSubspace]:
  """Set of subspaces used in node annotations.
 
  Returns
  -------
- set[str]
+ set[UDSSubspace]
  Subspace names excluding structural attributes
  """
  return self._node_subspaces
 
  @property
- def edge_subspaces(self) -> set[str]:
+ def edge_subspaces(self) -> set[UDSSubspace]:
  """Set of subspaces used in edge annotations.
 
  Returns
  -------
- set[str]
+ set[UDSSubspace]
  Subspace names for edges
  """
  return self._edge_subspaces
 
  @property
- def subspaces(self) -> set[str]:
+ def subspaces(self) -> set[UDSSubspace]:
  """Set of all subspaces (node and edge).
 
  Returns
  -------
- set[str]
+ set[UDSSubspace]
  Union of node and edge subspaces
  """
  return self.node_subspaces | self._edge_subspaces
 
- def properties(self, subspace: str | None = None) -> set[str]:
+ def properties(self, subspace: UDSSubspace | None = None) -> set[str]:
  """Get properties for a subspace.
 
  Parameters
@@ -501,7 +505,7 @@ def properties(self, subspace: str | None = None) -> set[str]:
  """
  return self._metadata.properties(subspace)
 
- def property_metadata(self, subspace: str,
+ def property_metadata(self, subspace: UDSSubspace,
  prop: str) -> UDSPropertyMetadata:
  """Get metadata for a specific property.
 
@@ -650,11 +654,13 @@ def _process_node_data(self, data: dict[str, dict[str, NormalizedData | RawData]
 
  # some attributes are not property subspaces and are thus excluded
  self._excluded_attributes = {'subpredof', 'subargof', 'headof', 'span', 'head'}
- self._node_subspaces = {ss for gid, nodedict
- in self._node_attributes.items()
- for nid, subspaces in nodedict.items()
- for ss in subspaces}
- self._node_subspaces = self._node_subspaces - self._excluded_attributes
+ self._node_subspaces: set[UDSSubspace] = {
+ cast(UDSSubspace, ss) for gid, nodedict
+ in self._node_attributes.items()
+ for nid, subspaces in nodedict.items()
+ for ss in subspaces
+ if ss not in self._excluded_attributes
+ }
 
  # initialize as nested defaultdict, will be frozen to regular dict later
  # the actual type is a nested defaultdict but we'll treat it as the final dict type
@@ -692,10 +698,12 @@ def _process_edge_data(self, data: dict[str, dict[str, NormalizedData | RawData]
  if '%%' in edge}
  for gid, attrs in data.items()}
 
- self._edge_subspaces = {ss for gid, edgedict
- in self._edge_attributes.items()
- for eid, subspaces in edgedict.items()
- for ss in subspaces}
+ self._edge_subspaces: set[UDSSubspace] = {
+ cast(UDSSubspace, ss) for gid, edgedict
+ in self._edge_attributes.items()
+ for eid, subspaces in edgedict.items()
+ for ss in subspaces
+ }
 
  # initialize as nested defaultdict, will be frozen to regular dict later
  # the actual type is a nested defaultdict but we'll treat it as the final dict type
@@ -820,7 +828,7 @@ class method must be:
  """
  return cast('RawUDSAnnotation', super().from_json(jsonfile))
 
- def annotators(self, subspace: str | None = None,
+ def annotators(self, subspace: UDSSubspace | None = None,
  prop: str | None = None) -> set[str] | None:
  """Get annotator IDs for a subspace and property.
 

decomp/semantics/uds/corpus.py

@@ -24,7 +24,7 @@
 from logging import warn
 from os.path import basename, splitext
 from random import sample
-from typing import TextIO, TypeAlias, cast
+from typing import Literal, TextIO, TypeAlias, cast
 from zipfile import ZipFile
 
 import requests
@@ -35,7 +35,7 @@
 from .annotation import NormalizedUDSAnnotation, RawUDSAnnotation, UDSAnnotation
 from .document import SentenceGraphDict, UDSDocument
 from .graph import EdgeAttributes, EdgeKey, NodeAttributes, UDSSentenceGraph
-from .metadata import UDSCorpusMetadata, UDSPropertyMetadata
+from .metadata import AnnotationMetadataDict, UDSCorpusMetadata, UDSPropertyMetadata
 
 
 Location: TypeAlias = str | TextIO
@@ -69,8 +69,8 @@ class UDSCorpus(PredPattCorpus):
 
  UD_URL = 'https://github.com/UniversalDependencies/' +\
  'UD_English-EWT/archive/r1.2.zip'
- ANN_DIR = str(importlib.resources.files('decomp') / 'data')
- CACHE_DIR = str(importlib.resources.files('decomp') / 'data')
+ ANN_DIR = str(importlib.resources.files('decomp') / 'data') + '/'
+ CACHE_DIR = str(importlib.resources.files('decomp') / 'data') + '/'
 
  def __init__(self,
  sentences: PredPattCorpus | None = None,
@@ -120,16 +120,15 @@ def __init__(self,
  self._sentences = {str(name): UDSSentenceGraph(g, str(name))
  for name, g in sentences.items()}
  self._graphs = self._sentences
+ else:
+ # When sentences is already a dict of UDSSentenceGraph objects
+ self._sentences = sentences
+ self._graphs = self._sentences
 
  self._documents = documents or {}
 
- if sentence_annotations:
- for ann in sentence_annotations:
- self.add_annotation(ann)
-
- if document_annotations:
- for ann in document_annotations:
- self.add_annotation(document_annotation=ann)
+ if sentence_annotations or document_annotations:
+ self.add_annotation(sentence_annotations, document_annotations)
 
  def _validate_arguments(self, sentences: PredPattCorpus | None, documents: dict[str, UDSDocument] | None,
  version: str, split: str | None, annotation_format: str) -> None:
@@ -497,11 +496,16 @@ def from_json(cls, sentences_jsonfile: Location,
  sent_ids, name)
  for name, d_json in documents_json['data'].items()}
 
- corpus = cls(cast(PredPattCorpus | None, sentences), documents)
+ corpus = cls(sentences, documents)
 
- metadata_dict = {'sentence_metadata': sentences_json['metadata'],
- 'document_metadata': documents_json['metadata']}
- metadata = UDSCorpusMetadata.from_dict(metadata_dict)
+ metadata_dict = {
+ 'sentence_metadata': sentences_json['metadata'],
+ 'document_metadata': documents_json['metadata']
+ }
+ metadata = UDSCorpusMetadata.from_dict(cast(
+ dict[Literal['sentence_metadata', 'document_metadata'], AnnotationMetadataDict],
+ metadata_dict
+ ))
  corpus.add_corpus_metadata(metadata)
 
  return corpus
@@ -516,8 +520,8 @@ def add_corpus_metadata(self, metadata: UDSCorpusMetadata) -> None:
  """
  self._metadata += metadata
 
- def add_annotation(self, sentence_annotation: UDSAnnotation | None = None,
- document_annotation: UDSAnnotation | None = None) -> None:
+ def add_annotation(self, sentence_annotation: list[UDSAnnotation] | None = None,
+ document_annotation: list[UDSAnnotation] | None = None) -> None:
  """Add annotations to UDS sentence and document graphs
 
  Parameters
@@ -528,10 +532,12 @@ def add_annotation(self, sentence_annotation: UDSAnnotation | None = None,
  the annotations to add to the document graphs in the corpus
  """
  if sentence_annotation:
- self.add_sentence_annotation(sentence_annotation)
+ for ann in sentence_annotation:
+ self.add_sentence_annotation(ann)
 
  if document_annotation:
- self.add_document_annotation(document_annotation)
+ for ann in document_annotation:
+ self.add_document_annotation(ann)
 
  def add_sentence_annotation(self, annotation: UDSAnnotation) -> None:
  """Add annotations to UDS sentence graphs