diff --git a/docs/Makefile b/docs/Makefile index 69fe55ec..65d49ad1 100644 --- a/docs/Makefile +++ b/docs/Makefile @@ -16,4 +16,8 @@ help: # Catch-all target: route all unknown targets to Sphinx using the new # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). %: Makefile - @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + + +watch: + while true; do find source -name \*.rst | entr -dn make html; done diff --git a/docs/source/_static/theme_overrides.css b/docs/source/_static/theme_overrides.css new file mode 100644 index 00000000..3bee59c8 --- /dev/null +++ b/docs/source/_static/theme_overrides.css @@ -0,0 +1,13 @@ +/* override table width restrictions */ +@media screen and (min-width: 767px) { + + table.reece-wrap td { + /* !important prevents the common CSS stylesheets from overriding + this as on RTD they are loaded after this stylesheet */ + white-space: normal !important; + } + + table.reece-wrap { + overflow: visible !important; + } +} diff --git a/docs/source/algorithms/computed_identifier.rst b/docs/source/algorithms/computed_identifier.rst deleted file mode 100644 index 76428d12..00000000 --- a/docs/source/algorithms/computed_identifier.rst +++ /dev/null @@ -1,91 +0,0 @@ -.. _computed-identifier: - -Computed Identifier -!!!!!!!!!!!!!!!!!!! - -The VR-Spec provides an algorithmic solution to deterministically -generate a globally unique identifier from a VR object itself. All -valid implementations of the VR Computed Identifier will generate the -same identifier when the objects are identical, and will generate -different identifiers when they are not. Adopting the VR Computed -Digest algorithm obviates centralized registration services, allows -computational pipelines to generate ids in isolation of other systems, -and makes it easier for distributed groups to share data. - -The VR Computed Identifier algorithm uses two well-established standard -algorithms, the SHA-512 hash function, which generates a binary digest -from binary data, and Base64 URL encoding, which encodes binary data -using printable characters. - -The VR Computed Identifier algorithm applies only to *identifiable* -objects, that is, objects with an `id` property. In addition, the -algorithm is defined only when nested objects use `ga4gh` identifiers. -For example, generating a Computed Identifier for an Allele requires a -Computed Identifier for the embedded location, which requires that the -reference sequence is defined using a Computed Identifier. - -To generate a VR Computed Identifier, an implementation MUST: - -* if the object is an Allele, normalize as described in - :ref:`normalization` -* serialize the object into a binary string as described in - :ref:`serialization` -* generate a :ref:`digest` -* construct a CURIE Identifier, described below - -In addition, the VR Computed Identifier is explicitly NOT defined -(that is, invalid) if used with any other normalization, -serialization, or digest mechanism to generate a GA4GH Computed -Identifier. - - -Identifier Construction -@@@@@@@@@@@@@@@@@@@@@@@ - -A `W3C CURIE `_ format has the form:: - - prefix ":" reference - -The GA4GH VR Spec constructs computed identifiers as follows:: - - "ga4gh" ":" "." - -Type prefixes used by VR are: - -.. csv-table:: - :header: type_prefix, VR Spec class name - :align: left - - SQ, Sequence - VA, Allele - VL, Location - VT, Text - VH, (reserved) Haplotype - VG, (reserved) Genotype - VX, (reserved) Translocation - -For example:: - - ga4gh:SQ.v_QTc1p-MUYdgrRv4LMT6ByXIOsdw3C_ - - -.. note:: Do not confuse the W3C CURIE `prefix` ("ga4gh" in this case) - with a prefix used to indicate type. - - - - -.. note:: **Proposal for GA4GH-wide use** - - The Variation Representation team created the computed - identifier scheme for VR objects. However, this scheme is - applicable and useful to the entire GA4GH ecosystem. As a - result, we are proposing that the computed identifier scheme - described here be considered for adoption as a GA4GH-wide - standard. For this reason, we have adopted the use of the - `ga4gh` prefix above. - - If the Computed Identifier scheme is adopted as a GA4GH-wide - standard, documentation and type prefixes would moved from - the VR specification to a separate repository for GA4GH-wide - use. diff --git a/docs/source/algorithms/digest.rst b/docs/source/algorithms/digest.rst deleted file mode 100644 index 012390ba..00000000 --- a/docs/source/algorithms/digest.rst +++ /dev/null @@ -1,23 +0,0 @@ -.. _digest: - -Digest -!!!!!! - -Computing digests for identifiable VR objects consists of three steps: - -1. Compute the `SHA-512`_ digest of a binary object. -2. Truncate the digest to the left-most 24 bytes (192 bits). See - :ref:`truncated-digest-collision-analysis` for the rationale for 24 - bytes. -3. Encode the truncated digest as a base64url_ ASCII string. - - -.. code-block:: python - - >>> import base64, hashlib - >>> blob = b"ACGT" - >>> digest = hashlib.sha512(blob).digest() - >>> digest - b'h\xa1x\xf7\xc7@\xc5\xc2@\xaag\xbaA\x84;\x11\x9d;\xf9\xf8 ... - >>> base64.urlsafe_b64encode(digest[:24]).decode("ASCII") - 'aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2' diff --git a/docs/source/algorithms/index.rst b/docs/source/algorithms/index.rst deleted file mode 100644 index 26433936..00000000 --- a/docs/source/algorithms/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -.. _algorithms: - -Algorithms -!!!!!!!!!! - -The VR Specification REQUIRES implementation of the following -algorithms: - -* :ref:`normalization`: Expands Alleles to the maximal region of - representational ambiguity. (Conventional left and right shuffling - is insufficient for compliance with the specification.) -* :ref:`digest`: A convention for constructing and representing - digests from binary data for the purposes of constructing an - identifier. -* :ref:`serialization`: Converts objects into canonical binary - forms in order to generate consistent digests across implementations - and computing languages. -* :ref:`computed-identifier`: A proposed string format for object - identifiers across all GA4GH products. - - - -.. toctree:: - :hidden: - :maxdepth: 1 - - digest - computed_identifier - normalization - serialization - diff --git a/docs/source/algorithms/serialization.rst b/docs/source/algorithms/serialization.rst deleted file mode 100644 index fe6749f2..00000000 --- a/docs/source/algorithms/serialization.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _serialization: - -Serialization -!!!!!!!!!!!!! - -In the context of generating a Computed Identifier, serialization -converts a VR object into a binary representation. Because the result -will be used to generate a digest, VR implementations MUST serialize -data identically. The VR-Spec provides validation tests to ensure -compliance. - -The criteria for the VR serialization method was that it must be -relatively easy and reliable to implement in any common computer -language. Although several proposals exist [1]_:superscript:`,` -[2]_:superscript:`,` [3]_ for serializing arbitrary data in a -consistent manner, none have been ratified. As a result, VR-Spec -defines a custom serialization format that is consistent with these -proposals but does not rely on them for definition. - -The first step in serialization is to generate message content that: - - * MUST replace nested identifiable objects (i.e., objects that - have id properties) with their corresponding ids - * MUST order arrays of Ids by Unicode Character Set values - * MUST require that all arrays of ids are CURIE formatted and use the - `ga4gh` namespace prefix - * MUST NOT include id fields - * MUST NOT include null values - - -The second step is to serialize the message content as JSON that: - - * MUST be encoded in UTF-8 - * MUST NOT include insignificant whitespace, as defined in `RFC8259§2 - `__ - * MUST order all keys by Unicode Character Set values - * MUST use two-char escapes when available, as defined in `RFC8259§7 - `__ - - - -**References** - -.. [1] `Gibson Canonical JSON `__ -.. [2] `OLPC Canonical JSON `__ -.. [3] `JSON Canonicalization Scheme `__ - diff --git a/docs/source/appendices/ga4gh_identifiers.rst b/docs/source/appendices/ga4gh_identifiers.rst new file mode 100644 index 00000000..40fccfdb --- /dev/null +++ b/docs/source/appendices/ga4gh_identifiers.rst @@ -0,0 +1,59 @@ +.. _ga4gh-identifiers: + +Proposal for GA4GH-wide Computed Identifier Standard +!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!! + +This appendix describes a proposal for creating a GA4GH-wide standard +for serializing data, computing digests on serialized data, and +constructing CURIE identifiers from the digests. Essentially, it is a +generalization of the :ref:`computed-identifier` section. + +This standard is proposed now because the VR Specification needs a +well-defined mechanism for generating identifiers. Changing the +identifier mechanism later will create significant issues for VR +adopters. + + +Background +@@@@@@@@@@ + +The GA4GH mission entails structuring, connecting, and sharing data +reliably. A key component of this effort is to be able to *identify* +entities, that is, to associate identifiers with entities. Ideally, +there will be exactly one identifier for each entity, and one entity +for each identifier. Traditionally, identifiers are assigned to +entities, which means that disconnected groups must coordinate on +identifier assignment. + +The computed identifier scheme proposed in the VR Specification +computes identifiers from the data itself. Because identifers depend +on the data, groups that independently generate the same variation +will generate the same computed identifier for that entity, thereby +obviating centralized identifier systems and enabling identifiers to +be used in isolated settings such as clinical labs. + +The computed identifier mechanism is broadly applicable and useful to +the entire GA4GH ecosystem. As a result, we are proposing that the +computed identifier scheme described in the VR specification be +considered for adoption as a GA4GH-wide standard. + +Adopting a common identifier scheme will make interoperability of +GA4GH entities more obvious to consumers, will enable the entire +organization to share common entity definitions (such as sequence +identifiers), and will enable all GA4GH products to share tooling that +manipulate identified data. In short, it provides an important +consistency within the GA4GH ecosystem. + + +Proposal +@@@@@@@@ + +The GA4GH computed identifier proposal consists of a truncated digest, +syntax for a GA4GH identifier, declaration of the namespace, and a +system for adminstering entity type prefixes. + +* seralization +* truncated digest +* identifier GA4GH Identifier +* namespace +* type prefix administration diff --git a/docs/source/appendices/glossary.rst b/docs/source/appendices/glossary.rst index e6e9e063..4d06a55f 100644 --- a/docs/source/appendices/glossary.rst +++ b/docs/source/appendices/glossary.rst @@ -9,6 +9,9 @@ Glossary .. glossary:: :sorted: + accession + def + Base64 base64url def @@ -16,10 +19,16 @@ Glossary computed identifier This is a test + CURIE + def + digest ga4gh_digest synonym test + identifier + def + serialize def diff --git a/docs/source/appendices/index.rst b/docs/source/appendices/index.rst index 85a40406..f004e97c 100644 --- a/docs/source/appendices/index.rst +++ b/docs/source/appendices/index.rst @@ -5,6 +5,7 @@ Appendices :maxdepth: 2 design_decisions + ga4gh_identifiers vr-python/index truncated_digest_collision_analysis development_process diff --git a/docs/source/conf.py b/docs/source/conf.py index 34882bcd..0d17380c 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -31,7 +31,7 @@ def _parse_release_as_version(rls): # -- Project information ----------------------------------------------------- project = 'GA4GH Variation Representation Specification' -copyright = '2019, GA4GH' +copyright = '2019, GA4GH VR Contributors' author = 'Committers' master_doc = 'index' # N.B. RTD ignores these values. :-/ @@ -76,6 +76,12 @@ def _parse_release_as_version(rls): # so a file named "default.css" will overwrite the builtin "default.css". html_static_path = ['_static'] +html_context = { + 'css_files': [ + '_static/theme_overrides.css', # override wide tables in RTD theme + ], + } + # Sidebars html_sidebars = { '**': ['globaltoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html'] } diff --git a/docs/source/images/id-dig-ser.png b/docs/source/images/id-dig-ser.png new file mode 100644 index 00000000..16eba46b Binary files /dev/null and b/docs/source/images/id-dig-ser.png differ diff --git a/docs/source/impl-guide/computed_identifier.rst b/docs/source/impl-guide/computed_identifier.rst new file mode 100644 index 00000000..d675f5c8 --- /dev/null +++ b/docs/source/impl-guide/computed_identifier.rst @@ -0,0 +1,221 @@ +.. _computed-identifiers: + +Computed Identifiers +!!!!!!!!!!!!!!!!!!!! + +.. note:: This section depends on the :ref:`ga4gh-identifiers`, which + is submitted concurrently. Based on conversations with + GA4GH technical leaders, we expect that the proposal will be + approved and have therefore assumed acceptance when writing + this section. In the event that the proposal is not + accepted, this section will be modified as described in + :ref:`plan-b`. Because identifiers created + through this proposal are expected to be durable, it is + critical for GA4GH to make a long-term decision regarding + identifiers. + + +The VR-Spec provides an algorithmic solution to deterministically +generate a globally unique identifier from a VR object itself. All +valid implementations of the VR Computed Identifier will generate the +same identifier when the objects are identical, and will generate +different identifiers when they are not. The VR Computed Digest +algorithm obviates centralized registration services, allows +computational pipelines to generate "private" ids efficiently, and +makes it easier for distributed groups to share data. + +A VR Computed Identifier is computed as follows: + +* :ref:`Normalize the object ` if the object is an Allele +* :ref:`Serialize the object ` into binary data. +* :ref:`Generate a truncated digest ` from the binary data. +* :ref:`Construct an identifier ` based on the digest and object type. + +The following diagram depicts the operations necessary to generate a +computed identifier. These operations are described in detail in the +subsequent sections. + +.. _ser-dig-id: + +.. figure:: ../images/id-dig-ser.png + :align: left + + **Serialization, Digest, and Computed Identifier Operations** + Entities are shown in gray boxes. Functions are denoted by bold + italics. The yellow, green, and blue boxes, corresponding to the + ``sha512t24u``, ``vr_digest``, and ``vr_identify`` functions + respectively, depict the dependencies among functions. + ``SHA512/192`` is :ref:`SHA-512` truncated at 192 bits using the + systematic name recommended by SHA-512 (§5.3.6). base64url_ is the + official name of the variant of :ref:`Base64` encoding that uses a + URL-safe character set. [`figure source + `__] + + +Requirements +@@@@@@@@@@@@ + +Implementations MUST adhere to the following requirements: + +* The VR Computed Identifier algorithm applies only to *identifiable* + objects, that is, objects with an `id` property. + +* The VR Computed Identifier is NOT defined if used with any other + normalization, serialization, or digest mechanism to generate a + GA4GH Computed Identifier. + +* VR Computed Identifiers are defined only when all nested objects are + identified with ``ga4gh.vr`` identifiers. Generating VR identifiers + using objects referenced within any other namespace is not compliant + with this specification. In particular, it is not compliant to + generate VR identifiers using sequences referenced with RefSeq, + Ensembl, or other accession outside the `ga4gh.vr`` namespace. + + + +.. _serialize: + +VR Serialization +@@@@@@@@@@@@@@@@ + +.. important:: Do not confuse VR serialization with other + serialization formats, including JSON serialization used to + transmit VR messages. Although VR and JSON serializations appear + similar, they are NOT interchangeable. A VR object might have many + valid JSON serializations, but it will have only one valid VR + serialization. + +VR serialization converts a VR object into a binary representation in +preparation for computing a digest of the object. The VR +serialization specification ensures that all implementations serialize +variation objects identically, and therefore that the digests will +also be identical. |vr-spec| provides validation tests to ensure +compliance. + +Although several proposals exist for serializing arbitrary data in a +consistent manner ([Gibson]_, [OLPC]_, [JCS]_), none have been +ratified. As a result, |vr-spec| defines a custom serialization format +that is consistent with these proposals but does not rely on them for +definition; it is hoped that a future ratified standard will be +forward compatible with the process described here. + +The first step in serialization is to generate message content. To do +so, implementations MUST: + + * ensure that objects are referenced with identifiers in the + ``ga4gh.vr`` namespace. + * replace nested identifiable objects (i.e., objects that have id + properties) with their corresponding *digests* + * order arrays of digests and ids by Unicode Character Set values + * filter out id fields + * filter out fields with null values + +The second step is to JSON serialize the message content with the +following REQUIRED constraints: + + * encode the serialization in UTF-8 + * exclude insignificant whitespace, as defined in `RFC8259§2 + `__ + * order all keys by Unicode Character Set values + * use two-char escape codes when available, as defined in + `RFC8259§7 `__ + +The criteria for the VR serialization method was that it must be +relatively easy and reliable to implement in any common computer +language. + + +.. _digest: + +Truncated Digest (sha512t24u) +@@@@@@@@@@@@@@@@@@@@@@@@@@@@@ + +The Truncated Digest algorithm computes an ASCII digest from binary +data. The method uses two well-established standard algorithms, the +`SHA-512`_ hash function, which generates a binary digest from binary +data, and `Base64`_ URL encoding, which encodes binary data using +printable characters. Computing the Truncated Digest for binary data +consists of three steps: + +1. Compute the `SHA-512`_ digest of a binary data. +2. Truncate the digest to the left-most 24 bytes (192 bits). See + :ref:`truncated-digest-collision-analysis` for the rationale for 24 + bytes. +3. Encode the truncated digest as a base64url_ ASCII string. + + + +.. code-block:: python + + >>> import base64, hashlib + >>> def truncated_digest(blob): + digest = hashlib.sha512(blob).digest() + tdigest = digest[:24] + tdigest_b64u = base64.urlsafe_b64encode(tdigest).decode("ASCII") + return tdigest_b64u + >>> truncated_digest(b"ACGT") + 'aKF498dAxcJAqme6QYQ7EZ07-fiw8Kw2' + + +.. _identify: + +Identifier Construction +@@@@@@@@@@@@@@@@@@@@@@@ + + +The final step of generating a computed identifier for a VR object is +to generate a `W3C CURIE `_ formatted identifier, which +has the form:: + + prefix ":" reference + +The GA4GH VR Spec constructs computed identifiers as follows:: + + "ga4gh" ":" type_prefix "." + +.. note:: Do not confuse the W3C CURIE ``prefix`` ("ga4gh") with the + type prefix. + +Type prefixes used by VR are: + +.. csv-table:: + :header: type_prefix, VR Spec class name + :align: left + + SQ, Sequence + VA, Allele + VL, Location + VT, Text + VH, (reserved) Haplotype + VG, (reserved) Genotype + VX, (reserved) Translocation + +For example:: + + ga4gh:SQ.v_QTc1p-MUYdgrRv4LMT6ByXIOsdw3C_ + + + +.. _plan-b: + +Namespace Contingency Plan +@@@@@@@@@@@@@@@@@@@@@@@@@@ + +In the event that :ref:`ga4gh-identifiers` is not accepted, the +following changes will be made to this section of the specification: + +* The namespace (CURIE prefix) will become ``ga4gh.vr``. + +* The GA4GH VR team will manage prefixes. + +All other aspects of the computed identifier scheme will remain intact. + + +---- + +**References** + +.. [Gibson] `Gibson Canonical JSON `__ +.. [OLPC] `OLPC Canonical JSON `__ +.. [JCS] `JSON Canonicalization Scheme `__ + diff --git a/docs/source/impl-guide/index.rst b/docs/source/impl-guide/index.rst new file mode 100644 index 00000000..bba89aa5 --- /dev/null +++ b/docs/source/impl-guide/index.rst @@ -0,0 +1,27 @@ +.. _impl-guide: + +Implementation Guide +!!!!!!!!!!!!!!!!!!!! + +This section describes the data and algorithmic components that are +required for implementations of the VR Specification. + +* :ref:`required-data`: All implementations will require access to + sequences and sequence accessions. The Required External Data + section provides guidance on the abstract functionality that is + required in order to implement VR. +* :ref:`normalization`: Expands Alleles to the maximal region of + representational ambiguity. +* :ref:`computed-identifiers`: Generate globally unique identifiers + based solely on the variation definition. + + + +.. toctree:: + :hidden: + :maxdepth: 1 + + required_data + normalization + computed_identifier + diff --git a/docs/source/algorithms/normalization.rst b/docs/source/impl-guide/normalization.rst similarity index 100% rename from docs/source/algorithms/normalization.rst rename to docs/source/impl-guide/normalization.rst diff --git a/docs/source/impl-guide/required_data.rst b/docs/source/impl-guide/required_data.rst new file mode 100644 index 00000000..45705637 --- /dev/null +++ b/docs/source/impl-guide/required_data.rst @@ -0,0 +1,91 @@ +.. _required-data: + +Required External Data +!!!!!!!!!!!!!!!!!!!!!! + +All VR Spec implementations will require external data regarding +sequences and sequence metadata. The choices of data sources and +access methods are left to implementations. This section provides +guidance about how to implement required data and helps implementers +estimate effort. This section is descriptive only: it is not intended +to impose requirements on interface to, or sources of, external data. +For clarity and completeness, this section also describes the contexts +in which external data are used. + + +Contexts +@@@@@@@@ + +* **Conversion from other variant formats** When converting from other + variation formats, implementations must translate primary database + accessions or identifiers (|eg| ``NM_000551.3`` or + ``refseq:NM_000551.3``) to a GA4GH VR sequence identifier ( + ``ga4gh:SQ.v_QTc1p-MUYdgrRv4LMT6ByXIOsdw3C_``) + +* **Conversion to other variant formats** When converting to other + variation formats, implementations are likely to translate GA4GH VR + sequence identifier ( ``ga4gh:SQ.v_QTc1p-MUYdgrRv4LMT6ByXIOsdw3C_``) + to primary database identifiers (``refseq:NM_000551.3``) that will + be more readily recognized by users. + +* **Normalization** During :ref:`normalization`, implementations will + need access to sequence length (metadata) and sequence contexts. + + + +Data Services +@@@@@@@@@@@@@ + +The following tables summarizes data required in the above contexts: + +.. list-table:: Data Service Desciptions + :class: reece-wrap + :widths: auto + :header-rows: 1 + + * - Data Service + - Description + - Contexts + * - sequence + - For a given sequence identifier and range, return the + corresponding subsequence. + - normalization + * - sequence length + - For a given sequence identifier, return the length of the + sequence + - normalization + * - identifier translation + - For a given sequence identifier and target namespace, return + all identifiers in the target namespace that are equivelent to + the given identifier. + - Conversion to/from other formats + + + +Suggested Implementation +@@@@@@@@@@@@@@@@@@@@@@@@ + +In order to maximize portability and to insulate implementations from +decisions about external data sources, implementers should consider +writing an abstract data proxy interface that to define a service, and +then implement this interface for each data backend to be +supported. The :ref:`impl-vr-python` `DataProxy class +`__ +provides an example of this design pattern and sample replies. + +The DataProxy interface defines three methods: + +* ``get_sequence(identifier, start, end)``: Given a sequence + identifier and start and end coordinates, return the corresponding + sequence segment. +* ``get_metadata(identifier)``: Given a sequence identifier, return a + dictionary of length, alphabet, and known aliases. +* ``translate_sequence_identifier(identifier, namespace)``: Given a + sequence identifier, return all aliases in the specified + namespace. Zero or more aliases may be returned. + +The VR Reference Implementation implements the DataProxy interface +using a local |seqrepo| instance backend and using a |seqrepo_rs| +backend. A GA4GH refget implementation has been started, but is +pending interface changes to support lookup using primary database +accesssions. diff --git a/docs/source/index.rst b/docs/source/index.rst index 42eaea9c..620d996f 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,7 +10,8 @@ implementation that promotes adoption of the standard. .. toctree:: - :maxdepth: 3 + :maxdepth: 2 + :includehidden: introduction terms_and_model diff --git a/docs/source/rst_epilog b/docs/source/rst_epilog index acaa2b9c..98bbf20f 100644 --- a/docs/source/rst_epilog +++ b/docs/source/rst_epilog @@ -1,4 +1,6 @@ +.. _Base64: https://tools.ietf.org/html/rfc4648 .. _Compact URI (CURIE): https://www.w3.org/TR/curie/ +.. _Equivalence Function: https://en.wikipedia.org/wiki/Equivalence_relation .. _FHIR Business Identifiers: https://www.hl7.org/fhir/datatypes.html#identifier .. _FHIR Id: http://build.fhir.org/datatypes.html#id .. _HGVS: http://www.hgvs.org/ @@ -6,7 +8,6 @@ .. _RFC 2119: https://www.ietf.org/rfc/rfc2119.txt .. _SHA-512: https://nvlpubs.nist.gov/nistpubs/FIPS/NIST.FIPS.180-4.pdf .. _Sequence Ontology: http://www.sequenceontology.org/browser/current_svn/term/SO:0001023 -.. _Equivalence Function: https://en.wikipedia.org/wiki/Equivalence_relation .. _Wikipedia Residue page: https://en.wikipedia.org/wiki/Residue_%28chemistry%29 .. _Wikipedia: https://en.wikipedia.org/wiki/Allele .. _base64url: https://tools.ietf.org/html/rfc4648#section-5 @@ -18,9 +19,12 @@ .. _polymeric chain: https://en.wikipedia.org/wiki/Polymer .. _protein: https://en.wikipedia.org/wiki/Protein -.. |vr-python| replace:: `vr-python `__ +.. |vr-spec| replace:: `VR Specification `__ +.. |vr-python| replace:: `VR Reference Implementation `__ .. |vr_json| replace:: `vr.json `__ .. |vr_yaml| replace:: `vr.yaml `__ +.. |seqrepo| replace:: `SeqRepo `__ +.. |seqrepo_rs| replace:: `SeqRepo REST Service `__ .. |eg| replace:: *e.g.,* .. |ie| replace:: *i.e.,*