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 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) 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:
Remapping is when a given CURIE prefix or URI prefix is replaced with another. See
curies.remap_curie_prefixes()
andcuries.remap_uri_prefixes()
.Rewiring is when the correspondence between a CURIE prefix and URI prefix is updated. See
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.
[
{"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
[
{"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:
Do nothing (lenient)
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:
Replace the record’s preferred prefix with the new prefix
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
[
{"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
[
{"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:
Do nothing (lenient)
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 is given the prefix geo
and the Geographical Entity Ontology 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:
Remapping with
{"geo": "ncbi.geo"}
would retaingeo
as a CURIE prefix synonymRemapping with
{"geogeo": "geo"}
would not change the mapping asgeo
is already part of a different record.
The 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
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)
>>> 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.
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 curies.Record.uri_prefix
and
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
Replace the record’s preferred URI prefix with the new URI prefix
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
[
{"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.
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.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
[ {"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[ {"prefix": "a", "uri_prefix": "https://example.org/a/", "uri_prefix_synonyms": ["https://example.org/a1/"]} ]
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 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
[
{"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:
Do nothing (lenient)
Raise an exception (strict)