Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: use consistent styling for attributes #540

Merged
merged 2 commits into from
Sep 3, 2024
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
22 changes: 11 additions & 11 deletions docs/source/concepts/LocationAndReference/SequenceLocation.rst
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ Sequence Location

The sequence location class is a fundamental concept in VRS. Sequence locations are used to describe every form of :ref:`Variation`,
and they have stand-alone utility for describing sequence locations in other (non-variation) contexts.
This class is used to represent a location on a specified :ref:`SequenceReference`. The sequence reference is typically a
This class is used to represent a location on a specified :ref:`SequenceReference`. The sequence reference is typically a
chromosome, transcript, or protein sequence.

Definition and Information Model
Expand All @@ -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 @@ -49,21 +49,21 @@ Linear and Circular Sequence Coordinates

When representing a linear sequence, it is expected that for a :ref:`Sequence` of length *n*, ``0 ≤ start ≤ end ≤ n``

For a circular sequence, ``0 ≤ end ≤ start ≤ n`` is also allowed. In cases where ``end < start``, this represents
For a circular sequence, ``0 ≤ end ≤ start ≤ n`` is also allowed. In cases where ``end < start``, this represents
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
Loading