Add EventLinkingType, change format of Event.colocated_ids

mbollmann · mbollmann · commit bc93463cd954 · 2025-06-03T20:32:47.000+02:00
diff --git a/python/CHANGELOG.md b/python/CHANGELOG.md
@@ -12,6 +12,7 @@
 
 ### Changed
 
+- Event: `colocated_ids` has changed from listing VolumeIDs to listing tuples of `(VolumeID, EventLinkingType)`, where EventLinkingType now makes clear if the association between the VolumeID and the Event was inferred or explicitly defined in the XML (in a `<colocated>` block).
 - MarkupText: Typographic quotes now convert to/from LaTeX quotes more consistently.
 - Names: Fixed some inconsistencies where `<first/>`, `<first></first>`, and a missing "first" tag would not be considered fully equivalent (within `Name` and `utils.xml.assert_equals`).
 - Paper attachments without a type attribute in the XML now give their type as an empty string (instead of defaulting to "attachment"), in order to be able to reconstruct whether there was an explicit type attribute or not.
diff --git a/python/acl_anthology/collections/__init__.py b/python/acl_anthology/collections/__init__.py
@@ -18,7 +18,7 @@
 from .eventindex import EventIndex
 from .event import Event, Talk
 from .volume import Volume
-from .types import VolumeType
+from .types import EventLinkingType, PaperDeletionType, PaperType, VolumeType
 from .paper import Paper
 
 
@@ -28,7 +28,10 @@
     "CollectionIndex",
     "Event",
     "EventIndex",
+    "EventLinkingType",
     "Paper",
+    "PaperDeletionType",
+    "PaperType",
     "Talk",
     "Volume",
     "VolumeType",
diff --git a/python/acl_anthology/collections/collection.py b/python/acl_anthology/collections/collection.py
@@ -33,7 +33,7 @@
 from ..utils.logging import get_logger
 from ..utils import xml
 from .event import Event
-from .types import VolumeType
+from .types import EventLinkingType, VolumeType
 from .volume import Volume
 from .paper import Paper
 
@@ -284,11 +284,12 @@ def load(self) -> None:
         if self.event is not None:
             # Events are implicitly linked to volumes defined in the same collection
             self.event.colocated_ids = [
-                volume.full_id_tuple
+                (volume.full_id_tuple, EventLinkingType.INFERRED)
                 for volume in self.data.values()
                 # Edge case: in case the <colocated> block lists a volume in
                 # the same collection, don't add it twice
-                if volume.full_id_tuple not in self.event.colocated_ids
+                if (volume.full_id_tuple, EventLinkingType.EXPLICIT)
+                not in self.event.colocated_ids
             ] + self.event.colocated_ids
 
         self.is_data_loaded = True
diff --git a/python/acl_anthology/collections/event.py b/python/acl_anthology/collections/event.py
@@ -20,6 +20,7 @@
 from lxml.builder import E
 from typing import Any, Iterator, Optional, TYPE_CHECKING
 
+from .types import EventLinkingType
 from ..constants import RE_EVENT_ID
 from ..files import EventFileReference
 from ..people import NameSpecification
@@ -99,7 +100,7 @@ class Event:
         is_explicit: True if this event was defined explicitly in the XML.
 
     Attributes: List Attributes:
-        colocated_ids: Volume IDs of proceedings that were colocated with this event.
+        colocated_ids: Tuples of volume IDs and their [`EventLinkingType`][acl_anthology.collections.types.EventLinkingType] that are colocated with this event.
         links: Links to materials for this event paper. The dictionary key specifies the type of link (e.g., "handbook" or "website").
         talks: Zero or more references to talks belonging to this event.
 
@@ -113,9 +114,9 @@ class Event:
     parent: Collection = field(repr=False, eq=False)
     is_explicit: bool = field(default=False, converter=bool)
 
-    colocated_ids: list[AnthologyIDTuple] = field(
+    colocated_ids: list[tuple[AnthologyIDTuple, EventLinkingType]] = field(
         factory=list,
-        repr=lambda x: f"<list of {len(x)} AnthologyIDTuple objects>",
+        repr=lambda x: f"<list of {len(x)} tuples>",
     )
     links: dict[str, EventFileReference] = field(factory=dict, repr=False)
     talks: list[Talk] = field(
@@ -143,7 +144,7 @@ def root(self) -> Anthology:
 
     def volumes(self) -> Iterator[Volume]:
         """Returns an iterator over all volumes co-located with this event."""
-        for anthology_id in self.colocated_ids:
+        for anthology_id, _ in self.colocated_ids:
             volume = self.root.get_volume(anthology_id)
             if volume is None:
                 raise ValueError(
@@ -152,13 +153,18 @@ def volumes(self) -> Iterator[Volume]:
                 )
             yield volume
 
-    def add_colocated(self, volume: Volume | AnthologyID) -> None:
+    def add_colocated(
+        self,
+        volume: Volume | AnthologyID,
+        type_: EventLinkingType = EventLinkingType.EXPLICIT,
+    ) -> None:
         """Add a co-located volume to this event.
 
-        Will do nothing if the given volume is already co-located with this event.
+        If the given volume is already co-located with this event and type_ is 'explicit', this will change its type to 'explicit'; otherwise, it will do nothing.
 
         Parameters:
             volume: The ID or Volume object to co-locate with this event.
+            type_: Whether this volume is/should be explicitly linked in the XML or is inferred. (Defaults to 'explicit'.)
         """
         from .volume import Volume
 
@@ -167,10 +173,16 @@ def add_colocated(self, volume: Volume | AnthologyID) -> None:
         else:
             volume_id = parse_id(volume)
 
-        if volume_id in self.colocated_ids:
-            return
+        for idx, (existing_id, existing_type) in enumerate(self.colocated_ids):
+            if volume_id == existing_id:
+                if (
+                    existing_type == EventLinkingType.INFERRED
+                    and type_ == EventLinkingType.EXPLICIT
+                ):
+                    self.colocated_ids[idx] = (volume_id, type_)
+                return
 
-        self.colocated_ids.append(volume_id)
+        self.colocated_ids.append((volume_id, type_))
 
         # Update the event index as well
         if self.root.events.is_data_loaded:
@@ -201,7 +213,7 @@ def from_xml(cls, parent: Collection, event: etree._Element) -> Event:
                 kwargs["talks"].append(Talk.from_xml(element))
             elif element.tag == "colocated":
                 kwargs["colocated_ids"] = [
-                    parse_id(str(volume_id.text))
+                    (parse_id(str(volume_id.text)), EventLinkingType.EXPLICIT)
                     for volume_id in element
                     if volume_id.tag == "volume-id"
                 ]
@@ -239,10 +251,11 @@ def to_xml(self) -> etree._Element:
         # <colocated>
         if self.colocated_ids:
             colocated = E.colocated()
-            for id_tuple in self.colocated_ids:
-                if id_tuple[0] != self.parent.id:
+            for id_tuple, el_type in self.colocated_ids:
+                if el_type == EventLinkingType.EXPLICIT:
                     colocated.append(
                         getattr(E, "volume-id")(build_id_from_tuple(id_tuple))
                     )
-            elem.append(colocated)
+            if len(colocated):
+                elem.append(colocated)
         return elem
diff --git a/python/acl_anthology/collections/eventindex.py b/python/acl_anthology/collections/eventindex.py
@@ -1,4 +1,4 @@
-# Copyright 2023-2024 Marcel Bollmann <marcel@bollmann.me>
+# Copyright 2023-2025 Marcel Bollmann <marcel@bollmann.me>
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -24,6 +24,7 @@
 from ..utils.ids import AnthologyID, AnthologyIDTuple, parse_id
 from ..utils.logging import get_logger
 from .event import Event
+from .types import EventLinkingType
 from .volume import Volume
 
 if TYPE_CHECKING:
@@ -79,11 +80,10 @@ def _add_to_index(self, event: Event) -> None:
             return
 
         if event.id in self.data:
-            for co_id in self.data[event.id].colocated_ids:
-                if co_id not in event.colocated_ids:
-                    event.colocated_ids.append(co_id)
+            for co_id, co_type in self.data[event.id].colocated_ids:
+                event.add_colocated(co_id, co_type)
         self.data[event.id] = event
-        for volume_fid in event.colocated_ids:
+        for volume_fid, _ in event.colocated_ids:
             self.reverse[volume_fid].add(event.id)
 
     def load(self) -> None:
@@ -104,11 +104,10 @@ def load(self) -> None:
                     if explicit_event.id in self.data:
                         # This event has already been implicitly created in another file
                         # See https://github.com/acl-org/acl-anthology/issues/2743#issuecomment-2453501562
-                        for co_id in self.data[explicit_event.id].colocated_ids:
-                            if co_id not in explicit_event.colocated_ids:
-                                explicit_event.colocated_ids.append(co_id)
+                        for co_id, co_type in self.data[explicit_event.id].colocated_ids:
+                            explicit_event.add_colocated(co_id, co_type)
                     self.data[explicit_event.id] = explicit_event
-                    for volume_fid in explicit_event.colocated_ids:
+                    for volume_fid, _ in explicit_event.colocated_ids:
                         self.reverse[volume_fid].add(explicit_event.id)
 
                 for volume in collection.volumes():
@@ -125,12 +124,12 @@ def load(self) -> None:
                                 event_id,
                                 collection,
                                 is_explicit=False,
-                                colocated_ids=[volume_fid],
+                                colocated_ids=[(volume_fid, EventLinkingType.INFERRED)],
                                 title=MarkupText.from_string(event_name),
                             )
-                        elif volume_fid not in event.colocated_ids:
+                        else:
                             # Add implicit connection to existing event
-                            event.colocated_ids.append(volume_fid)
+                            event.add_colocated(volume_fid, EventLinkingType.INFERRED)
                         self.reverse[volume_fid].add(event_id)
             except Exception as exc:
                 log.exception(exc)
diff --git a/python/acl_anthology/collections/types.py b/python/acl_anthology/collections/types.py
@@ -15,6 +15,16 @@
 from enum import Enum
 
 
+class EventLinkingType(Enum):
+    """How a volume ID was connected to an Event."""
+
+    EXPLICIT = "explicit"
+    """Volume ID is explicitly listed in <colocated> block in XML."""
+
+    INFERRED = "inferred"
+    """Volume ID was inferred to belong to Event through venue association."""
+
+
 class PaperDeletionType(Enum):
     """Type of deletion of a paper."""
 
diff --git a/python/docs/guide/getting-started.md b/python/docs/guide/getting-started.md
@@ -148,7 +148,7 @@ belong to the conference or to colocated workshops:
 Event(
     id='acl-2022',
     is_explicit=True,
-    colocated_ids=<list of 34 AnthologyIDTuple objects>,
+    colocated_ids=<list of 34 tuples>,
     title=MarkupText('60th Annual Meeting of the Association for Computational Linguistics'),
     location='Dublin, Ireland',
     dates='May 22–27, 2022'
@@ -177,9 +177,9 @@ event (`ws-2020`), as well as the EMNLP 2020 event.
 >>> volume = anthology.get("2020.blackboxnlp-1")
 >>> volume.get_events()
 [
-    Event(id='blackboxnlp-2020', colocated_ids=<list of 1 AnthologyIDTuple objects>, ...),
-    Event(id='ws-2020', colocated_ids=<list of 105 AnthologyIDTuple objects>, ...),
-    Event(id='emnlp-2020', colocated_ids=<list of 27 AnthologyIDTuple objects>, ...)
+    Event(id='blackboxnlp-2020', colocated_ids=<list of 1 tuples>, ...),
+    Event(id='ws-2020', colocated_ids=<list of 105 tuples>, ...),
+    Event(id='emnlp-2020', colocated_ids=<list of 27 tuples>, ...)
 ]
 ```
 
diff --git a/python/tests/collections/collection_test.py b/python/tests/collections/collection_test.py
@@ -17,7 +17,12 @@
 from pathlib import Path
 
 from acl_anthology import Anthology
-from acl_anthology.collections import Collection, CollectionIndex, VolumeType
+from acl_anthology.collections import (
+    Collection,
+    CollectionIndex,
+    EventLinkingType,
+    VolumeType,
+)
 from acl_anthology.people import NameSpecification
 from acl_anthology.utils import xml
 from acl_anthology.text import MarkupText
@@ -231,7 +236,9 @@ def test_collection_create_volume_should_create_event(anthology, pre_load, reset
 
     # New implicit event should exist in the event index
     assert "acl-2000" in anthology.events
-    assert volume.full_id_tuple in anthology.events["acl-2000"].colocated_ids
+    assert (volume.full_id_tuple, EventLinkingType.INFERRED) in anthology.events[
+        "acl-2000"
+    ].colocated_ids
     assert volume.full_id_tuple in anthology.events.reverse
     assert anthology.events.reverse[volume.full_id_tuple] == {"acl-2000"}
 
@@ -262,7 +269,9 @@ def test_collection_create_volume_should_update_event(anthology, pre_load, reset
 
     # New volume should be added to existing event
     assert "acl-2022" in anthology.events
-    assert volume.full_id_tuple in anthology.events["acl-2022"].colocated_ids
+    assert (volume.full_id_tuple, EventLinkingType.INFERRED) in anthology.events[
+        "acl-2022"
+    ].colocated_ids
     assert volume.full_id_tuple in anthology.events.reverse
     assert anthology.events.reverse[volume.full_id_tuple] == {"acl-2022"}
 
@@ -331,7 +340,9 @@ def test_collection_create_event_should_update_eventindex(pre_load, anthology):
 
     if pre_load:
         # Volume should automatically have been added
-        assert event.colocated_ids == [collection.get("1").full_id_tuple]
+        assert event.colocated_ids == [
+            (collection.get("1").full_id_tuple, EventLinkingType.INFERRED)
+        ]
     else:
         # If event index wasn't loaded, it's not
         assert event.colocated_ids == []
diff --git a/python/tests/collections/event_test.py b/python/tests/collections/event_test.py
@@ -1,4 +1,4 @@
-# Copyright 2023-2024 Marcel Bollmann <marcel@bollmann.me>
+# Copyright 2023-2025 Marcel Bollmann <marcel@bollmann.me>
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
 # you may not use this file except in compliance with the License.
@@ -16,7 +16,7 @@
 from attrs import define
 from lxml import etree
 
-from acl_anthology.collections import Event, Talk
+from acl_anthology.collections import Event, EventLinkingType, Talk
 from acl_anthology.files import EventFileReference
 from acl_anthology.text import MarkupText
 from acl_anthology.utils.xml import indent
@@ -91,9 +91,9 @@ def test_event_all_attribs():
         location="Online",
         dates="August 17-19, 2023",
         colocated_ids=[
-            ("2023.foobar", "1", None),
-            ("2023.baz", "1", None),
-            ("2023.asdf", "1", None),
+            (("2023.foobar", "1", None), EventLinkingType.EXPLICIT),
+            (("2023.baz", "1", None), EventLinkingType.EXPLICIT),
+            (("2023.asdf", "1", None), EventLinkingType.EXPLICIT),
         ],
         talks=[Talk(MarkupText.from_string("Invited talk"))],
         links={"Website": EventFileReference("http://foobar.com")},
@@ -108,10 +108,10 @@ def test_event_to_xml_dont_list_colocated_volumes_of_parent():
         id="li-2023",
         parent=CollectionStub("2023.li"),
         colocated_ids=[
-            ("2023.baz", "1", None),
-            ("2023.li", "main", None),
-            ("2023.li", "side", None),
-            ("2023.ling", "1", None),
+            (("2023.baz", "1", None), EventLinkingType.EXPLICIT),
+            (("2023.li", "main", None), EventLinkingType.INFERRED),
+            (("2023.li", "side", None), EventLinkingType.INFERRED),
+            (("2023.ling", "1", None), EventLinkingType.EXPLICIT),
         ],
     )
     out = event.to_xml()
@@ -143,7 +143,9 @@ def test_event_volumes(anthology):
     assert len(event.colocated_ids) == 4
     volumes = list(event.volumes())
     assert len(volumes) == 4
-    assert {vol.full_id_tuple for vol in volumes} == set(event.colocated_ids)
+    assert {vol.full_id_tuple for vol in volumes} == set(
+        x[0] for x in event.colocated_ids
+    )
     with pytest.raises(ValueError):
         # acl-2022 lists co-located volumes that we don't have in the toy
         # dataset, so trying to access them should raise an error
@@ -158,7 +160,7 @@ def test_event_add_colocated(anthology):
     # Adding colocated volume should update Event & EventIndex
     event.add_colocated(volume)
     assert len(event.colocated_ids) == 2
-    assert volume.full_id_tuple in event.colocated_ids
+    assert (volume.full_id_tuple, EventLinkingType.EXPLICIT) in event.colocated_ids
     assert event in anthology.events.by_volume(volume)
 
     # Adding the same volume a second time shouldn't change anything
diff --git a/python/tests/collections/eventindex_test.py b/python/tests/collections/eventindex_test.py
