From 3644679c327246005c6d6cef86c37f8227f9e7e2 Mon Sep 17 00:00:00 2001 From: Kori Kuzma Date: Tue, 3 Sep 2024 16:56:04 -0400 Subject: [PATCH] docs: use consistent styling for attributes (#540) --- docs/source/appendices/ga4gh_identifiers.rst | 2 +- .../LocationAndReference/SequenceLocation.rst | 18 +++++++++--------- .../concepts/MolecularVariation/Allele.rst | 14 +++++++------- docs/source/conventions/example.rst | 2 +- docs/source/terms_and_model.rst | 2 +- 5 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/source/appendices/ga4gh_identifiers.rst b/docs/source/appendices/ga4gh_identifiers.rst index 0a03e5b1..f8de0f75 100644 --- a/docs/source/appendices/ga4gh_identifiers.rst +++ b/docs/source/appendices/ga4gh_identifiers.rst @@ -70,7 +70,7 @@ reference: GA4GH Digest Keys ################# When creating computed identifiers from objects, VRS uses a custom schema -attribute, ``ga4ghDigest``, that contains the keys used for filtering out +attribute, *ga4ghDigest*, that contains the keys used for filtering out properties. For example, the Allele JSON Schema: .. parsed-literal:: diff --git a/docs/source/concepts/LocationAndReference/SequenceLocation.rst b/docs/source/concepts/LocationAndReference/SequenceLocation.rst index cf561d58..0cdc47d9 100644 --- a/docs/source/concepts/LocationAndReference/SequenceLocation.rst +++ b/docs/source/concepts/LocationAndReference/SequenceLocation.rst @@ -19,17 +19,17 @@ Implementation Guidance Start, End, and Ranges ###################### -At least one of the ``start`` and ``end`` properties MUST be specified in any ``SequenceLocation`` instance. +At least one of the *start* and *end* properties MUST be specified in any ``SequenceLocation`` instance. When only one of these properties is specified, this represents an open interval beginning at the specified -coordinate and extending left (when ``start`` is ``null``) or right (when ``end`` is ``null``). +coordinate and extending left (when *start* is ``null``) or right (when *end* is ``null``). -When there is ambiguity at a coordinate (e.g., when using a SequenceLocation to describe the confidence boundary +When there is ambiguity at a coordinate (e.g., when using a ``SequenceLocation`` to describe the confidence boundary of a copy number segment), this is specified using the :ref:`Range` class for that coordinate. .. admonition:: New in v2 - In VRS v1, the ``SequenceLocation`` class had an ``interval`` property which contained ``start`` and ``end`` - attributes. This intermediate object layer has been removed in v2.0, making ``start`` and ``end`` + In VRS v1, the ``SequenceLocation`` class had an *interval* property which contained *start* and *end* + attributes. This intermediate object layer has been removed in v2.0, making *start* and *end* top-level properties of the ``SequenceLocation``. The "Ref" Allele @@ -37,7 +37,7 @@ The "Ref" Allele In some variant representation formats (e.g. HGVS, VCF) sequence variants are described by both their "reference" (ref) and "alternate" (alt) alleles. When representing an Allele with VRS v2, it is also possible to describe the -ref sequence (derived from the :ref:`SequenceReference` at the location) using the `sequence` property. +ref sequence (derived from the :ref:SequenceReference at the location) using the *sequence* property. .. admonition:: New in v2 @@ -54,16 +54,16 @@ a location that spans the circular sequence origin coordinate. .. admonition:: New in v2 - The v2 ``SequenceLocation`` now also supports circular sequences. The optional ``circular`` property of the + The v2 ``SequenceLocation`` now also supports circular sequences. The optional *circular* property of the :ref:`SequenceReference` class may be set to ``True`` or ``False`` to explicitly indicate if a reference is circular, and therefore if ``0 ≤ end ≤ start ≤ n`` is also allowed. Implied Sequence Coordinates ############################ -The *Sequence Location* class refers to coordinates on a :ref:`SequenceReference`; if that sequence +The ``Sequence Location`` class refers to coordinates on a :ref:`SequenceReference`; if that sequence represents a coding transcript, then the coordinates refer to the coding transcript, and not a -chromosome sequence to which it aligns. VRS intentionally does not allow for `start` or `end` values +chromosome sequence to which it aligns. VRS intentionally does not allow for *start* or *end* values that use an offset system to represent sequence not found on the :ref:`SequenceReference`. .. TODO:: Describe and add a ref to an intronic variant profile diff --git a/docs/source/concepts/MolecularVariation/Allele.rst b/docs/source/concepts/MolecularVariation/Allele.rst index ef088b9f..274371d8 100644 --- a/docs/source/concepts/MolecularVariation/Allele.rst +++ b/docs/source/concepts/MolecularVariation/Allele.rst @@ -3,8 +3,8 @@ Allele !!!!!! -The allele class is used for representing contiguous changes on a reference sequence. This class covers the most -commonly described forms of variation, including all "small" variants such as SNVs and indels that are also representable +The allele class is used for representing contiguous changes on a reference sequence. This class covers the most +commonly described forms of variation, including all "small" variants such as SNVs and indels that are also representable in other contemporary genomic variant formats, such as SPDI, HGVS, and VCF. Definition and Information Model @@ -18,7 +18,7 @@ Implementation Guidance Sequence Location Coordinates ############################# -The ``location`` property of the allele will almost always have ``start`` and ``end`` coordinates that are specified using +The *location* property of the allele will almost always have *start* and *end* coordinates that are specified using integers (not :ref:`Range`). There are some situations, such as the detection of deleted sequence by microarray, where it may be appropriate to represent the variant as an Allele; however, other classes for representing such findings should also be considered (e.g. :ref:`CopyNumberCount`). @@ -26,16 +26,16 @@ considered (e.g. :ref:`CopyNumberCount`). Normalization ############# -The ``Allele`` also includes conventions for variant normalization (see :ref:`allele-normalization`) that allows for compact and +The ``Allele`` also includes conventions for variant normalization (see :ref:`allele-normalization`) that allows for compact and uniform representation of variants. .. admonition:: New in v2 In VRS v1.x, normalization included methods for full justification of variants, as derived from the NCBI `VOCA`_ algorithm. - In v2, this has been extended to include reference length encoding (see :ref:`ReferenceLengthExpression`), to + In v2, this has been extended to include reference length encoding (see :ref:`ReferenceLengthExpression`), to accommodate compressed representation of variants that occur in large repetitive regions. - For alleles in small repeating regions, it may be convenient to also use the ``ReferenceLengthExpression.sequence`` attribute + For alleles in small repeating regions, it may be convenient to also use the *ReferenceLengthExpression.sequence* attribute to represent the sequence state explicitly alongside the reference encoding. .. _VOCA: https://www.ncbi.nlm.nih.gov/pmc/articles/PMC7523648/ @@ -46,4 +46,4 @@ Expressions .. admonition:: New in v2 The v2 :ref:`variation` classes now support :ref:`expressions`. This is a convenient mechanism for annotating Alleles using - string syntaxes following the conventions other variant standards (e.g. HGVS, SPDI) and resources (e.g. ClinVar, gnomAD). \ No newline at end of file + string syntaxes following the conventions other variant standards (e.g. HGVS, SPDI) and resources (e.g. ClinVar, gnomAD). diff --git a/docs/source/conventions/example.rst b/docs/source/conventions/example.rst index 65e1e181..485eec4a 100644 --- a/docs/source/conventions/example.rst +++ b/docs/source/conventions/example.rst @@ -66,7 +66,7 @@ A :ref:`LiteralSequenceExpression` object consists simply of the replacement seq "type": "LiteralSequenceExpression" } -The :ref:`Allele` object's ``location`` and ``state`` attributes may +The :ref:`Allele` object's *location* and *state* attributes may then be constructed from the above SequenceLocation and LiteralSequenceExpressions respectively: diff --git a/docs/source/terms_and_model.rst b/docs/source/terms_and_model.rst index f2b643bc..e134516e 100644 --- a/docs/source/terms_and_model.rst +++ b/docs/source/terms_and_model.rst @@ -63,7 +63,7 @@ Information Model Principles a kind of Variation, SequenceLocation is a kind of Location, and SequenceState is a kind of State. See :ref:`future-plans` for the roadmap of VRS data classes and relationships. All VRS objects - contain a ``type`` attribute, which is used to discriminate + contain a *type* attribute, which is used to discriminate polymorphic objects. * **Error handling is intentionally unspecified and delegated to