Add prefix reconciliation operations (#74)

This PR was motivated by
mapping-commons/sssom-py#426 (and serves as a
follow-up to mapping-commons/sssom-py#216). It
implements two functions that are high-level ways to rewire a given
converter.

docs/source/index.rst

@@ -62,6 +62,7 @@ for updating your code.
    :caption: Contents:
 
    tutorial
+   reconciliation
    struct
    api
    services/index

docs/source/reconciliation.rst

@@ -0,0 +1,154 @@
+Reconciliation
+==============
+Reconciliation is the high-level process of modifying an (extended) prefix map with
+domain-specific rules. This is important as it allows for building on existing
+(extended) prefix maps without having to start from scratch. Further, storing the
+rules to transform an existing prefix map allows for high-level discussion about
+the differences and their reasons.
+
+As a specific example, the `Bioregistry <https://bioregistry.io/>`_ uses ``snomedct`` as a preferred prefix for
+the Systematized Nomenclature of Medicine - Clinical Terms (SNOMED-CT). The
+OBO Foundry community prefers to use ``SCTID`` as the preferred prefix for this
+resource. Rather than maintaining a different extended prefix map than the Bioregistry,
+the OBO Foundry community could enumerate its preferred modifications to the base
+(extended) prefix map, then create its prefix map by transforming the Bioregistry's.
+
+Similarly, a consumer of the OBO Foundry prefix map who's implementing a resolver might want to override the URI prefix
+associated with the `Ontology of Vaccine Adverse Events (OVAE) <https://bioregistry.io/registry/ovae>`_
+to point towards the Ontology Lookup Service instead of the default OntoBee.
+
+There are two operations that are useful for transforming an existing (extended) prefix
+map:
+
+1. **Remapping** is when a given CURIE prefix or URI prefix is replaced with another.
+   See :func:`curies.remap_curie_prefixes` and :func:`curies.remap_uri_prefixes`.
+2. **Rewiring** is when the correspondence between a CURIE prefix and URI prefix is updated. See :func:`curies.rewire`.
+
+Throughout this document, we're going to use the following extended prefix map as an example
+to illustrate how these operations work from a high level.
+
+.. code-block:: json
+
+    [
+        {"prefix": "a", "uri_prefix": "https://example.org/a/", "prefix_synonyms": ["a1"]},
+        {"prefix": "b", "uri_prefix": "https://example.org/b/"}
+    ]
+
+
+CURIE Prefix Remapping
+----------------------
+CURIE prefix remapping is configured by a mapping from existing CURIE prefixes to new CURIE prefixes.
+The following rules are applied for each pair of old/new prefixes:
+
+1. New prefix exists
+~~~~~~~~~~~~~~~~~~~~
+If the new prefix appears as a prefix synonym in the record corresponding to the old prefix, they are swapped.
+This means applying the CURIE prefix remapping ``{"a": "a1"}`` results in the following
+
+.. code-block:: json
+
+    [
+        {"prefix": "a1", "uri_prefix": "https://example.org/a/", "prefix_synonyms": ["a"]},
+        {"prefix": "b", "uri_prefix": "https://example.org/b/"}
+    ]
+
+If the new prefix appears as a preferred prefix or prefix synonym for any other record, one of two things can happen:
+
+1. Do nothing (lenient)
+2. Raise an exception (strict)
+
+This means applying the CURIE prefix remapping ``{"a": "b"}`` results in either no change or an exception being raised.
+
+2. New prefix doesn't exist, old prefix exists
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If the old prefix appears in a record in the extended prefix map as a preferred prefix:
+
+1. Replace the record's preferred prefix with the new prefix
+2. Add the record's old preferred prefix to the record's prefix synonyms
+
+This means applying the CURIE prefix remapping ``{"a": "c"}`` results in the following
+
+.. code-block:: json
+
+    [
+        {"prefix": "c", "uri_prefix": "https://example.org/a/", "prefix_synonyms": ["a", "a1"]},
+        {"prefix": "b", "uri_prefix": "https://example.org/b/"}
+    ]
+
+Similarly, if the old prefix appears in a record in the extended prefix map as a prefix synonym, do the same.
+This means applying the CURIE prefix remapping ``{"a1": "c"}`` results in the following
+
+.. code-block:: json
+
+    [
+        {"prefix": "c", "uri_prefix": "https://example.org/a/", "prefix_synonyms": ["a", "a1"]},
+        {"prefix": "b", "uri_prefix": "https://example.org/b/"}
+    ]
+
+3. New prefix doesn't exist, old prefix doesn't exist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If neither the old prefix nor new prefix appear in the extended prefix maps, one of two things can happen:
+
+1. Do nothing (lenient)
+2. Raise an exception (strict)
+
+URI Prefix Remapping
+----------------------
+URI prefix remapping is configured by a mapping from existing URI prefixes to new URI prefixes.
+The rules work exactly the same as with CURIE prefix remapping, but for the :data:`curies.Record.uri_prefix` and
+:data:`curies.Record.uri_prefix_synonyms` fields.
+
+Prefix Rewiring
+---------------
+Prefix rewiring is configured by a mapping from existing CURIE prefixes to new URI prefixes.
+The following rules are applied for each pair of CURIE prefix/URI prefix:
+
+1. CURIE prefix doesn't exist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If the CURIE prefix doesn't exist in the extended prefix map, then the pair is simply appended.
+This means applying the rewiring ``{"c": "https://example.org/c"}`` results in the following
+
+.. code-block:: json
+
+    [
+        {"prefix": "a", "uri_prefix": "https://example.org/a/", "prefix_synonyms": ["a1"]},
+        {"prefix": "b", "uri_prefix": "https://example.org/b/"},
+        {"prefix": "c", "uri_prefix": "https://example.org/c/"}
+    ]
+
+2. CURIE prefix exists, URI prefix doesn't exist
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+If the CURIE prefix appears as either the preferred prefix or a prefix synonym, do the following
+
+1. Replace the record's preferred URI prefix with the new URI prefix
+2. Add the record's old preferred URI prefix to the record's URI prefix synonyms
+
+This means applying the rewiring ``{"b": "https://example.org/b_new/"}`` results in the following
+
+.. code-block:: json
+
+    [
+        {"prefix": "a", "uri_prefix": "https://example.org/a/", "prefix_synonyms": ["a1"]},
+        {"prefix": "b", "uri_prefix": "https://example.org/b_new/", "uri_prefix_synonyms": ["https://example.org/b/"]}
+    ]
+
+3. URI prefix exists
+~~~~~~~~~~~~~~~~~~~~
+If the URI prefix appears as either a preferred URI prefix or as a URI prefix synonym in
+any record in the extended prefix map, do one of the following:
+
+1. Do nothing (lenient)
+2. Raise an exception (strict)
+
+Transitive Mappings
+-------------------
+There's an important drawback to the current implementation of remapping - it is not able to consistently
+and correctly handle the case when the order of remapping records matters. For example, in the Bioregistry,
+the `Gene Expression Omnibus <https://www.ncbi.nlm.nih.gov/geo/>`_ is given the prefix ``geo`` and the
+`Geographical Entity Ontology <https://obofoundry.org/ontology/geo>`_ is given the
+prefix ``geogeo``. OBO Foundry users will want to rename the Gene Expression Omnibus record to something else
+like ``ncbi.geo`` and rename ``geogeo`` to ``geo``. This is possible in theory, but requires an implementation
+that will require additional introspection over the values appearing in both the keys and values of a remapping
+as well as changing the way that the records are modified.
+
+.. seealso:: Discussion about this issue on https://github.com/cthoyt/curies/issues/75

src/curies/__init__.py

@@ -15,6 +15,7 @@
     load_jsonld_context,
     load_prefix_map,
 )
+from .reconciliation import remap_curie_prefixes, remap_uri_prefixes, rewire
 from .sources import (
     get_bioregistry_converter,
     get_go_converter,
@@ -33,6 +34,9 @@
     "DuplicateURIPrefixes",
     "DuplicatePrefixes",
     "chain",
+    "remap_curie_prefixes",
+    "remap_uri_prefixes",
+    "rewire",
     "get_version",
     # i/o
     "load_prefix_map",

src/curies/reconciliation.py

@@ -0,0 +1,149 @@
+"""Reconciliation."""
+
+from typing import Collection, Mapping, Optional
+
+from .api import Converter, Record
+
+__all__ = [
+    "remap_curie_prefixes",
+    "remap_uri_prefixes",
+    "rewire",
+]
+
+
+class TransitiveError(NotImplementedError):
+    """An error when transitive mappings appear."""
+
+    def __init__(self, intersection: Collection[str]) -> None:
+        """Initialize the exception.
+
+        :param intersection: The strings that appeared both as keys and values
+            in a remapping dictionary (either for CURIEs or URIs)
+        """
+        self.intersection = intersection
+
+    def __str__(self) -> str:
+        return (
+            f"Transitive mapping has not been implemented. This is being thrown because "
+            f"the following appear in both the keys and values of the remapping: {self.intersection}."
+            "\n\nSee discussion at https://github.com/cthoyt/curies/issues/75."
+        )
+
+
+def remap_curie_prefixes(converter: Converter, remapping: Mapping[str, str]) -> Converter:
+    """Apply CURIE prefix remappings.
+
+    :param converter: A converter
+    :param remapping: A mapping from CURIE prefixes to new CURIE prefixes.
+        Old CURIE prefixes become synonyms in the records (i.e., they aren't forgotten)
+    :returns: An upgraded converter
+    :raises TransitiveError: If there are any strings that appear in both
+        the key and values of the remapping
+    """
+    intersection = set(remapping).intersection(remapping.values())
+    if intersection:
+        raise TransitiveError(intersection)
+
+    records = []
+    for record in converter.records:
+        new_prefix = _get_curie_preferred_or_synonym(record, remapping)
+        if new_prefix is None:
+            pass  # nothing to upgrade
+        elif new_prefix in converter.synonym_to_prefix and new_prefix not in record.prefix_synonyms:
+            pass  # would create a clash, don't do anything
+        else:
+            record.prefix_synonyms = sorted(
+                set(record.prefix_synonyms).union({record.prefix}).difference({new_prefix})
+            )
+            record.prefix = new_prefix
+        records.append(record)
+    return Converter(records)
+
+
+def remap_uri_prefixes(converter: Converter, remapping: Mapping[str, str]) -> Converter:
+    """Apply URI prefix remappings.
+
+    :param converter: A converter
+    :param remapping: A mapping from URI prefixes to new URI prefixes.
+        Old URI prefixes become synonyms in the records (i.e., they aren't forgotten)
+    :returns: An upgraded converter
+    :raises TransitiveError: If there are any strings that appear in both
+        the key and values of the remapping
+    """
+    intersection = set(remapping).intersection(remapping.values())
+    if intersection:
+        raise TransitiveError(intersection)
+
+    records = []
+    for record in converter.records:
+        new_uri_prefix = _get_uri_preferred_or_synonym(record, remapping)
+        if new_uri_prefix is None:
+            pass  # nothing to upgrade
+        elif (
+            new_uri_prefix in converter.reverse_prefix_map
+            and new_uri_prefix not in record.uri_prefix_synonyms
+        ):
+            pass  # would create a clash, don't do anything
+        else:
+            record.uri_prefix_synonyms = sorted(
+                set(record.uri_prefix_synonyms)
+                .union({record.uri_prefix})
+                .difference({new_uri_prefix})
+            )
+            record.uri_prefix = new_uri_prefix
+        records.append(record)
+    return Converter(records)
+
+
+def rewire(converter: Converter, rewiring: Mapping[str, str]) -> Converter:
+    """Apply URI prefix upgrades.
+
+    :param converter: A converter
+    :param rewiring: A mapping from CURIE prefixes to new URI prefixes.
+        If CURIE prefixes are not already in the converter, new records are created.
+        If new URI prefixes clash with any existing ones, they are not added.
+    :returns: An upgraded converter
+    """
+    records = []
+    for record in converter.records:
+        new_uri_prefix = _get_curie_preferred_or_synonym(record, rewiring)
+        if new_uri_prefix is None:
+            pass  # nothing to upgrade
+        elif (
+            new_uri_prefix in converter.reverse_prefix_map
+            and new_uri_prefix not in record.uri_prefix_synonyms
+        ):
+            pass  # would create a clash, don't do anything
+        else:
+            record.uri_prefix_synonyms = sorted(
+                set(record.uri_prefix_synonyms)
+                .union({record.uri_prefix})
+                .difference({new_uri_prefix})
+            )
+            record.uri_prefix = new_uri_prefix
+        records.append(record)
+
+    # potential future functionality: add missing records
+    # for prefix, new_uri_prefix in rewiring.items():
+    #     if prefix not in converter.synonym_to_prefix:
+    #         records.append(Record(prefix=prefix, uri_prefix=new_uri_prefix))
+
+    return Converter(records)
+
+
+def _get_curie_preferred_or_synonym(record: Record, upgrades: Mapping[str, str]) -> Optional[str]:
+    if record.prefix in upgrades:
+        return upgrades[record.prefix]
+    for s in record.prefix_synonyms:
+        if s in upgrades:
+            return upgrades[s]
+    return None
+
+
+def _get_uri_preferred_or_synonym(record: Record, upgrades: Mapping[str, str]) -> Optional[str]:
+    if record.uri_prefix in upgrades:
+        return upgrades[record.uri_prefix]
+    for s in record.uri_prefix_synonyms:
+        if s in upgrades:
+            return upgrades[s]
+    return None