Skip to content

Commit

Permalink
docs: use consistent styling for attributes (#540)
Browse files Browse the repository at this point in the history
  • Loading branch information
korikuzma authored Sep 3, 2024
1 parent 3445e14 commit 3644679
Show file tree
Hide file tree
Showing 5 changed files with 19 additions and 19 deletions.
2 changes: 1 addition & 1 deletion docs/source/appendices/ga4gh_identifiers.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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::
Expand Down
18 changes: 9 additions & 9 deletions docs/source/concepts/LocationAndReference/SequenceLocation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -19,25 +19,25 @@ 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
################

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

Expand All @@ -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
14 changes: 7 additions & 7 deletions docs/source/concepts/MolecularVariation/Allele.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -18,24 +18,24 @@ 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`).

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/
Expand All @@ -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).
string syntaxes following the conventions other variant standards (e.g. HGVS, SPDI) and resources (e.g. ClinVar, gnomAD).
2 changes: 1 addition & 1 deletion docs/source/conventions/example.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:

Expand Down
2 changes: 1 addition & 1 deletion docs/source/terms_and_model.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit 3644679

Please sign in to comment.