core.annotation¶

MIRIAM annotations.

An annotation combines a qualifier (BQB, BQM) with a resource pointing at a database entry, forming the statement this element is CHEBI:17234.

RDFAnnotation parses the notations found in the wild, normalizes them to identifiers.org compact identifiers and validates them against the identifiers.org registry. RDFAnnotationData resolves what an identifier refers to via the Ontology Lookup Service.

from pymetadata.core.annotation import RDFAnnotation
from pymetadata.core.miriam import BQB

annotation = RDFAnnotation(qualifier=BQB.IS, resource="chebi/CHEBI:33699")
print(annotation.resource_normalized)  # https://identifiers.org/CHEBI:33699
print(annotation.validate())

ProviderType ¶

Bases: str, Enum

Resolver a resource was written for.

IDENTIFIERS_ORG and BIOREGISTRY_IO resources can be normalized and validated, NONE marks an arbitrary url which is kept as it is.

RDFAnnotation ¶

RDFAnnotation(qualifier, resource, validate=True)

RDFAnnotation class.

Basic storage of annotation information. This consists of the relation and the resource. The annotations can be attached to other objects thereby forming triples which can be converted to RDF.

Resource can be either

http(s)://identifiers.org/collection/term, i.e., a identifiers.org URI
collection/term, i.e., the combination of collection and term
http(s)://arbitrary.url, an arbitrary URL
urn:miriam:uniprot:P03023
https://bioregistry.io/chebi:15996 urls via the bioregistry provider

Parse a resource into collection and term.

Parameters:

Name	Type	Description	Default
`qualifier`	`BQB \| BQM`	MIRIAM qualifier of the annotation	required
`resource`	`str`	the annotated resource, as an identifiers.org url (`https://identifiers.org/CHEBI:33699`), a bioregistry.io url, a compact identifier (`CHEBI:33699`), a collection and term (`chebi/CHEBI:33699`), a MIRIAM urn (`urn:miriam:chebi:CHEBI%3A33699`) or an arbitrary url	required
`validate`	`bool`	log warnings and errors for an invalid annotation	`True`

Raises:

Type	Description
`ValueError`	if the qualifier or the resource is missing, or if the resource is not a string

resource_normalized `property` ¶

resource_normalized

Normalize resource for given annotation.

This is the correct usage. Resources are normalized to identifiers.org compact identifiers of the form https://identifiers.org/<prefix>:<accession>. If the namespace is embedded in the LUI the prefix is already part of the term, otherwise the prefix of the identifiers.org registry is prepended.

The normalization never changes what the resource says: the result is an url, and parsing it again yields the same collection and term. A ? or # of the term is percent-encoded, since it would otherwise start the query string or the fragment of the url. A collection which is not in the registry, or a term which does not carry the prefix of its collection, can not be written as a compact identifier and is returned as https://identifiers.org/<collection>/<term>. Whether the term is valid does not matter here, this is the task of validate.

Bioregistry URLs retain their original resource while exposing their collection and compact term for OLS resolution. Arbitrary URLs are also returned unchanged.

shorten_compact_term `staticmethod` ¶

shorten_compact_term(term, collection)

Shorten a compact term to the accession.

If the namespace is not embedded in the LUI, the prefix of the collection is removed from the term, e.g., ncit:C75913 becomes C75913.

Parameters:

Name	Type	Description	Default
`term`	`str`	term, possibly with the prefix of its collection	required
`collection`	`str`	collection of the term	required

Returns:

Type	Description
`str`	The term without the prefix if the namespace is not embedded in the
`str`	LUI, otherwise the unchanged term.

from_tuple `staticmethod` ¶

from_tuple(t)

Create an annotation from a (qualifier, resource) tuple.

Parameters:

Name	Type	Description	Default
`t`	`tuple[BQB \| BQM, str]`	qualifier and resource of the annotation	required

Returns:

Type	Description
`RDFAnnotation`	The annotation.

to_dict ¶

to_dict()

Convert the annotation to a dictionary.

Returns:

Type	Description
`dict[str, Any]`	Qualifier, collection and term of the annotation.

check_miriam_term ¶

check_miriam_term()

Check that term follows id pattern for collection.

Uses the Identifiers collection information.

check_qualifier `staticmethod` ¶

check_qualifier(qualifier)

Check that the qualifier is a MIRIAM qualifier.

Parameters:

Name	Type	Description	Default
`qualifier`	`BQB \| BQM`	qualifier to check	required

Returns:

Type	Description
`bool`	True if the qualifier is a `BQB` or `BQM` term.

validate ¶

validate()

Validate qualifier and term of the annotation.

Returns:

Type	Description
`bool`	True if the qualifier is a MIRIAM qualifier and an identifiers.org
`bool`	term matches its collection pattern. Bioregistry.io resources do not
`bool`	use identifiers.org term validation, other resources must be urls.

Provider `dataclass` ¶

Provider(name, url, official)

A provider which resolves the term of an annotation.

Attributes:

Name	Type	Description
`name`	`str`	name of the provider, e.g., `UniProt`
`url`	`str`	url of the term at the provider
`official`	`bool`	whether the registry names it the official provider

RDFAnnotationData ¶

RDFAnnotationData(annotation)

Bases: RDFAnnotation

An annotation with the information behind the identifier resolved.

Constructing the object resolves the cross references: for every provider the identifiers.org registry lists for the collection, the url pattern is filled in with the term. query_ols then adds label, description and synonyms from the Ontology Lookup Service, and replaces xrefs with the cross references reported by OLS.

Attributes:

Name	Type	Description
`url`	`str \| None`	url of the primary provider of the collection
`providers`	`list[Provider]`	non deprecated providers, the primary one first
`collection_name`	`str \| None`	name of the collection, e.g., `UniProt Knowledgebase`
`collection_homepage`	`str \| None`	homepage of the primary provider
`pattern_match`	`bool \| None`	whether the term matches the pattern of the collection, None if it cannot be checked
`label`	`str \| None`	name of the term
`ontology`	`str \| None`	ontology id of the term in OLS, e.g., `go`
`iri`	`str \| None`	IRI of the term
`ols_url`	`str \| None`	page of the term in OLS
`description`	`str \| None`	definition of the term
`synonyms`	`list[Any]`	synonyms of the term
`xrefs`	`list[Any]`	cross references of the term
`warnings`	`list[Any]`	problems which do not invalidate the annotation
`errors`	`list[Any]`	problems which do

Example

data = RDFAnnotationData(RDFAnnotation(BQB.IS, "chebi/CHEBI:33699"))
data.query_ols()
print(data.label)

Raises:

Type	Description
`ValueError`	if the collection of the annotation is not in the registry

Resolve the cross references of the annotation.

to_dict ¶

to_dict()

Convert the annotation to a dictionary.

query_ols ¶

query_ols()

Resolve the term in the Ontology Lookup Service.

Fills in label, description and synonyms, and replaces xrefs with the cross references reported by OLS. Requires network access; errors are collected in errors instead of raising.

Returns:

Type	Description
`dict[str, Any]`	The processed OLS response.

get_ols_query ¶

get_ols_query()

Get the shared OLS query object, created on first use.

Returns:

Type	Description
`OLSQuery`	The shared `OLSQuery` for the ontologies in `ONTOLOGIES`.

primary_resource ¶

primary_resource(resources)

Get the provider a term links to: the official non deprecated one.

Falls back to the first non deprecated provider, and to the first provider when all are deprecated.

pattern_matches ¶

pattern_matches(pattern, term)

Check a term against the pattern of its collection, None if it cannot be checked.

core.annotation¶

ProviderType ¶

RDFAnnotation ¶

resource_normalized property ¶

shorten_compact_term staticmethod ¶

from_tuple staticmethod ¶

to_dict ¶

check_miriam_term ¶

check_qualifier staticmethod ¶

validate ¶

Provider dataclass ¶

RDFAnnotationData ¶

to_dict ¶

query_ols ¶

get_ols_query ¶

primary_resource ¶

pattern_matches ¶

resource_normalized `property` ¶

shorten_compact_term `staticmethod` ¶

from_tuple `staticmethod` ¶

check_qualifier `staticmethod` ¶

Provider `dataclass` ¶