Skip to content

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.

validate classmethod

validate(version: object) -> None

Validate a supported prior VRS version.

Parameters:

Name Type Description Default
version object

Version value to validate; None selects the current version.

required

Raises:

Type Description
ValueError

If the version is unsupported.

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

__enter__

__enter__() -> None

Apply the identifier computation policy.

__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

is_ga4gh_identifier(ir: object) -> bool

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

sha512t24u(blob: bytes) -> str

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.