################
 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 dictionary 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)

***********************************
 Transitive CURIE Prefix Remapping
***********************************

There's a special case of CURIE prefix remapping where one prefix is supposed to
overwrite another. 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``. Taken by themselves, these two
operations would not accomplish the desired results:

1. Remapping with ``{"geo": "ncbi.geo"}`` would retain ``geo`` as a CURIE prefix synonym
2. Remapping with ``{"geogeo": "geo"}`` would not change the mapping as ``geo`` is
   already part of a different record.

The :func:`curies.remap_curie_prefixes` implements special logic to identify scenarios
where two (or more) remappings are dependent (we're calling these *transitive
remappings*) and apply them in the expected way. Therefore, we see the following

.. code-block:: python

    from curies import Converter, Record, remap_curie_prefixes

    converter = Converter(
        [
            Record(
                prefix="geo",
                uri_prefix="https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=",
            ),
            Record(prefix="geogeo", uri_prefix="http://purl.obolibrary.org/obo/GEO_"),
        ]
    )
    remapping = {"geo": "ncbi.geo", "geogeo": "geo"}
    converter = remap_curie_prefixes(converter, curie_remapping)

    assert converter.records == [
        Record(
            prefix="geo",
            prefix_synonyms=["geogeo"],
            uri_prefix="http://purl.obolibrary.org/obo/GEO_",
        ),
        Record(
            prefix="ncbi.geo",
            uri_prefix="https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=",
        ),
    ]

``geogeo`` is maintained as a CURIE prefix synonym for the Geographical Entity
Ontology's record. Synonyms of Gene Expression Omnibus would also be retained.

.. note::

    This is not the same as an "overwrite" which would delete the original ``geo``
    operation. This package expects that you give a new CURIE prefix to all
    "overwritten" records such that no records are lost.

.. warning::

    Primary prefixes must be used when doing transitive remappings. Handling synonyms
    proved to be too complex. Therefore, if you use a CURIE prefix remapping like in the
    following, you will get an exception.

    .. code-block::

        converter = Converter([
            Record(
                prefix="geo",
                prefix_synonyms=["ggg"],
                uri_prefix="https://www.ncbi.nlm.nih.gov/geo/query/acc.cgi?acc=",
            ),
            Record(prefix="geogeo", uri_prefix="http://purl.obolibrary.org/obo/GEO_"),
        ])
        curie_remapping = {"ggg": "ncbi.geo", "geogeo": "geo"}

**********************
 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.

**********
 Rewiring
**********

Rewiring is configured by a dictionary from existing CURIE prefixes to new URI prefixes.
The following rules are applied for each pair of CURIE prefix/URI prefix:

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/"]}
    ]

CURIE prefix exists, URI prefix exists
======================================

If the CURIE prefix and URI prefix both appear in the extended prefix map, there are
three possibilities.

1. If they are in the same record and the URI prefix is already the preferred prefix,
   then nothing needs to be done. This means that the rewiring ``{"a":
   "https://example.org/a/"}`` results in no change.
2. If they are in the same record and the URI prefix is a URI prefix synonym, then the
   URI prefix synonym is swapped with the preferred URI prefix. This means if we have
   the following extended prefix map

   .. code-block:: json

       [
           {"prefix": "a", "uri_prefix": "https://example.org/a/", "uri_prefix_synonyms": ["https://example.org/a1/"]}
       ]

   and apply ``{"a": "https://example.org/a1/"}``, we get the following result

   .. code-block:: json

       [
           {"prefix": "a", "uri_prefix": "https://example.org/a/", "uri_prefix_synonyms": ["https://example.org/a1/"]}
       ]

3. If they appear in different records, then either do nothing (lenient) or raise an
   exception (strict)

CURIE prefix doesn't exist, URI prefix doesn't exist
====================================================

If the CURIE prefix doesn't appear in the extended prefix map, then nothing is done.
Adding fully novel content to the extended prefix map can be done with other operations
such as :meth`:curies.Converter.add_record` or :func:`curies.chain`.

.. note::

    There is discussion whether this case could be extended with the following: 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/"}
        ]

    This is not included in the base implementation because it conflates the job of
    "rewiring" with appending to the extended prefix map

CURIE prefix doesn't exist, 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)