Identifiers and digests
Serialize, digest, and identify GA4GH models.
For an Allele without cached IDs or digests, the main steps are (intermediate helper calls omitted)::
ga4gh_identify(allele)
+ allele.compute_ga4gh_identifier()
+ allele.compute_digest()
+ allele.ga4gh_serialize()
+ location.get_or_create_digest() # identifiable child
+ state.ga4gh_serialize() # inline value object
+ encode_canonical_json(...)
+ sha512t24u(...)
Given an Allele, call the public helpers::
from ga4gh.core import ga4gh_digest, ga4gh_identify, ga4gh_serialize
identifier = ga4gh_identify(allele, in_place="never") # GA4GH CURIE
digest = ga4gh_digest(allele) # digest component
serialized = ga4gh_serialize(allele) # canonical JSON bytes
in_place="never" leaves the ID unchanged; "always" stores the result;
"default" stores it only when the ID is None. Digests may still be cached.
To reuse any nonempty ID::
from ga4gh.core import VrsObjectIdentifierIs, use_ga4gh_compute_identifier_when
with use_ga4gh_compute_identifier_when(VrsObjectIdentifierIs.MISSING):
identifier = ga4gh_identify(allele)
GA4GH_INVALID instead requires an ID matching the GA4GH pattern. ANY
always calls the model identifier method, which may reuse cached IDs or digests.
After editing an allele, refresh changed identifiable children first, then::
identifier = allele.get_or_create_ga4gh_identifier(
in_place="always", recompute=True
)
VrsObjectIdentifierIs
Bases: IntEnum
Control when ga4gh_identify calls the model identifier method.
ANY: Always call the method (default).GA4GH_INVALID: Call it when the ID is missing or syntactically invalid.MISSING: Call it only when the ID is None or empty.
The default policy calls the model identifier method. That method may reuse an
existing valid identifier or digest; this policy does not force recomputation. Where
the source of inputs to ga4gh_identify are well controlled, for example when
annotating a VCF file with VRS IDs, using MISSING can improve performance.
PrevVrsVersion
Bases: str, Enum
Define prior VRS versions supported for digest and identifier computation.
use_ga4gh_compute_identifier_when
use_ga4gh_compute_identifier_when(
when: VrsObjectIdentifierIs,
)
Bases: ContextDecorator
Apply an identifier policy within a context or decorated function.
As a context manager::
with use_ga4gh_compute_identifier_when(VrsObjectIdentifierIs.GA4GH_INVALID):
VCFAnnotator(...).annotate(...)
As a decorator::
@use_ga4gh_compute_identifier_when(VrsObjectIdentifierIs.GA4GH_INVALID)
def my_method(): ...
Set the identifier computation policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
when
|
VrsObjectIdentifierIs
|
Identifier computation policy for the context. |
required |
__exit__
__exit__(
exc_type: type[BaseException] | None,
exc: BaseException | None,
exc_tb: TracebackType | None,
) -> None
Restore the previous identifier computation policy.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
exc_type
|
type[BaseException] | None
|
Exception class from the context body, if any. |
required |
exc
|
BaseException | None
|
Exception instance from the context body, if any. |
required |
exc_tb
|
TracebackType | None
|
Traceback from the context body, if any. |
required |
is_ga4gh_identifier
Check whether a value starts with the GA4GH namespace prefix
For example:
>>> is_ga4gh_identifier("ga4gh:SQ.0123abcd")
True
>>> is_ga4gh_identifier("refseq:NM_01234.5")
False
>>> is_ga4gh_identifier(None)
False
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
ir
|
object
|
Value or root model to inspect. |
required |
Returns:
| Type | Description |
|---|---|
bool
|
Whether the value has the GA4GH namespace prefix. |
ga4gh_identify
ga4gh_identify(
vro: BaseModel,
in_place: str = "default",
as_version: PrevVrsVersion | None = None,
) -> str | None
Return a GA4GH identifier, or None for a non-identifiable object.
This function has three options for in_place editing of vro.id:
- 'default': the standard identifier update behavior for GA4GH identifiable objects, this mode will update the vro.id field only when it is None
- 'always': this will update the vro.id field any time the identifier is computed (compute behavior is controlled by the use_ga4gh_compute_identifier_when context)
- 'never': the vro.id field will not be edited in-place, even when empty
The context policy may return an existing ID without computing one. When computation
occurs, as_version selects legacy serialization and bypasses in-place ID
updates; it does not override the context policy. Accepts a supported PrevVrsVersion
member or its string value. Raises ValueError for other version values.
For example:
>>> from ga4gh.core import ga4gh_identify
>>> import ga4gh.vrs
>>> location = ga4gh.vrs.models.SequenceLocation(
... start=44908821,
... end=44908822,
... sequenceReference=ga4gh.vrs.models.SequenceReference(
... refgetAccession="SQ.F-LrLMe1SRpfUZHkQmvkVKFEGaoDeHul"
... ),
... )
>>> ga4gh_identify(location)
'ga4gh:SL.4t6JnYWqHwYw9WzBT_lmWBb3tLQNalkT'
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
vro
|
BaseModel
|
GA4GH model implementing is_ga4gh_identifiable and the digest and identifier methods used for identifiable objects. |
required |
in_place
|
str
|
Identifier update policy: default, always, or never. |
'default'
|
as_version
|
PrevVrsVersion | None
|
Optional prior VRS version to use. |
None
|
Returns:
| Type | Description |
|---|---|
str | None
|
Identifier, or None for a non-identifiable model. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If as_version is unsupported. |
AttributeError
|
If the model lacks the required GA4GH methods. |
ga4gh_digest
ga4gh_digest(
vro: BaseModel,
overwrite: bool = False,
as_version: PrevVrsVersion | None = None,
) -> str | None
Return the GA4GH digest for the object.
Only GA4GH identifiable objects are GA4GH digestible.
If as_version is provided, other parameters are ignored and a digest is returned
following the conventions of the VRS version indicated by as_version. Accepts a
supported PrevVrsVersion member or its string value. Raises ValueError for other
version values.
For example:
>>> from ga4gh.core import ga4gh_digest
>>> import ga4gh.vrs
>>> location = ga4gh.vrs.models.SequenceLocation(
... start=44908821,
... end=44908822,
... sequenceReference=ga4gh.vrs.models.SequenceReference(
... refgetAccession="SQ.F-LrLMe1SRpfUZHkQmvkVKFEGaoDeHul"
... ),
... )
>>> ga4gh_digest(location)
'4t6JnYWqHwYw9WzBT_lmWBb3tLQNalkT'
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
vro
|
BaseModel
|
GA4GH model implementing is_ga4gh_identifiable and the digest and identifier methods used for identifiable objects. |
required |
overwrite
|
bool
|
Recompute an existing digest when true. |
False
|
as_version
|
PrevVrsVersion | None
|
Optional prior VRS version to use. |
None
|
Returns:
| Type | Description |
|---|---|
str | None
|
Digest, or None for a non-identifiable model. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If as_version is unsupported. |
AttributeError
|
If the model lacks the required GA4GH methods. |
ga4gh_serialize
ga4gh_serialize(
obj: BaseModel, as_version: PrevVrsVersion | None = None
) -> bytes | str
Serialize an object for use in computed digest computation.
If as_version is provided, the returned serialization follows the conventions of
the VRS version indicated by as_version.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
obj
|
BaseModel
|
Model implementing ga4gh_serialize, and ga4gh_serialize_as_version when legacy serialization is requested. |
required |
as_version
|
PrevVrsVersion | None
|
Optional prior VRS version to use. |
None
|
Returns:
| Type | Description |
|---|---|
bytes | str
|
Canonical JSON bytes, or legacy serialization text. |
Raises:
| Type | Description |
|---|---|
ValueError
|
If as_version is unsupported. |
AttributeError
|
If the model lacks the required GA4GH methods. |
ga4gh digest algorithm
Source: sha512t24u from biocommons.seqrepo https://journals.plos.org/plosone/article?id=10.1371/journal.pone.0239883
sha512t24u
Generate a base64url-encode, truncated SHA-512 digest for given binary data
The sha512t24u digest is a convention for constructing and formatting digests for use as object identifiers. Specifically::
* generate a SHA512 digest on binary data
* truncate at 24 bytes
* encode using base64url encoding
For example:
>>> sha512t24u(b"")
'z4PhNX7vuL3xVChQ1m2AB9Yg5AULVxXc'
>>> sha512t24u(b"ACGT")
'aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2'
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
blob
|
bytes
|
Binary data to digest. |
required |
Returns:
| Type | Description |
|---|---|
str
|
URL-safe base64 encoding of the first 24 digest bytes. |