docs: update examples in implementation documentation (#535)

* docs: update examples in implementation documentation

close #531

* resolve typos + only use one space after period

* pr suggestions

* update styling for attributes

follow docs/source/style.rst conventions

* docs: resolve typos + only include one space after a period (#536)

docs/source/appendices/ga4gh_identifiers.rst

@@ -5,7 +5,7 @@ GA4GH Computed Identifier Alignment
 
 This appendix describes alignment on standard practices for
 for serializing data, computing digests on serialized data, and
-constructing CURIE identifiers from the digests.  Essentially, it is a
+constructing CURIE identifiers from the digests. Essentially, it is a
 generalization of the :ref:`computed-identifiers` section.
 
 This mechanism for generating identifiers has been in place
@@ -18,23 +18,23 @@ 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
+for each identifier. Traditionally, identifiers are assigned to
 entities, which means that disconnected groups must coordinate on
 identifier assignment.
 
-The computed identifier scheme used in VRS 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 scheme used in VRS computes identifiers
+from the data itself. Because identifiers 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.  Adopting a common identifier scheme will
+the entire GA4GH ecosystem. 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
+share tooling that manipulate identified data. In short, it provides
 an important consistency within the GA4GH ecosystem.
 
 Here we detail alignment between VRS and other GA4GH products to work
@@ -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::
@@ -95,8 +95,8 @@ properties. For example, the Allele JSON Schema:
 
 .. note::
 
-  The `ga4ghDigest` property names are currently being aligned with the Sequence 
-  Collections effort (see `SeqCol#84 <https://github.com/ga4gh/refget/issues/84>`_) 
+  The `ga4ghDigest` property names are currently being aligned with the Sequence
+  Collections effort (see `SeqCol#84 <https://github.com/ga4gh/refget/issues/84>`_)
   and may potentially change.
 
 GA4GH Type Prefixes
@@ -114,9 +114,9 @@ We use the following guidelines for type prefixes:
 
 * Prefixes SHOULD be short, approximately 2-4 characters.
 * Prefixes SHOULD be used only for concrete classes, not abstract parent classes.
-* Prefixes SHOULD be used only for stand-alone classes (e.g. :ref:`Variation`, :ref:`Location`), 
+* Prefixes SHOULD be used only for stand-alone classes (e.g. :ref:`Variation`, :ref:`Location`),
   not classes that require additional context to be meaningful (e.g. :ref:`Range`, :ref:`SequenceExpression`)
-  or are primarily used for adding descriptive context to external data types (e.g. :ref:`SequenceReference`) 
+  or are primarily used for adding descriptive context to external data types (e.g. :ref:`SequenceReference`)
 * A prefix MUST map 1:1 with a schema.
 
 Administration

docs/source/appendices/glossary.rst

@@ -12,10 +12,10 @@ Glossary
       data.
 
    digest, ga4gh_digest
-      A digest is a digital fingerprint of a block of binary data.  A
+      A digest is a digital fingerprint of a block of binary data. A
       digest is always the same size, regardless of the size of the
-      input data.  It is statistically extremely unlikely for two
-      fingerprints to match when the underlying data are distinct. 
+      input data. It is statistically extremely unlikely for two
+      fingerprints to match when the underlying data are distinct.
 
    identifiable object
       An identifiable object in VRS is any data structure for

docs/source/appendices/truncated_digest_collision_analysis.rst

@@ -12,7 +12,7 @@ of truncation length.
   <https://github.com/biocommons/biocommons.seqrepo/blob/master/docs/Truncated%20Digest%20Collision%20Analysis.ipynb>`__
   in `Python SeqRepo library
   <https://github.com/biocommons/biocommons.seqrepo>`__ for code and
-  updates.  A fuller explanation is given in [Hart2020]_.
+  updates. A fuller explanation is given in [Hart2020]_.
 
 
 Conclusions
@@ -30,11 +30,11 @@ Conclusions
     import hashlib
     import math
     import timeit
-    
+
     from IPython.display import display, Markdown
-    
+
     from ga4gh.vrs.extras.utils import _format_time
-    
+
     algorithms = {'sha512', 'sha1', 'sha256', 'md5', 'sha224', 'sha384'}
 
 
@@ -49,16 +49,16 @@ basis for the Truncated Digest.
     def blob(l):
         """return binary blob of length l (POSIX only)"""
         return open("/dev/urandom", "rb").read(l)
-    
+
     def digest(alg, blob):
         md = hashlib.new(alg)
         md.update(blob)
         return md.digest()
-    
+
     def magic_run1(alg, blob):
         t = %timeit -o digest(alg, blob)
         return t
-    
+
     def magic_tfmt(t):
         """format TimeitResult for table"""
         return "{a} ± {s} ([{b}, {w}])".format(
@@ -159,15 +159,15 @@ in a corpus is difficult. Instead, we first seek to solve for
 the digests are unique). Because are only two outcomes,
 :math:`P + P' = 1` or, equivalently, :math:`P = 1 - P'`.
 
-For a corpus of size :math:`m=1`, the probabability that the digests of
+For a corpus of size :math:`m=1`, the probability that the digests of
 all :math:`m=1` messages are unique is (trivially) 1:
 
 .. math:: P' = s/s = 1
 
 because there are :math:`s` ways to choose the first digest from among
 :math:`s` possible values without a collision.
 
-For a corpus of size :math:`m=2`, the probabability that the digests of
+For a corpus of size :math:`m=2`, the probability that the digests of
 all :math:`m=2` messages are unique is:
 
 .. math:: P' = 1 \times (\frac{s-1}{s})
@@ -211,7 +211,7 @@ The Taylor series expansion of the exponential function is
 .. math:: e^x = 1 + x + \frac{x^2}{2!} + \frac{x^3}{3!} + ...
 
 For :math:`|x| \ll 1`, the expansion is dominated by the first terms and
-therecore :math:`e^x \approx 1 + x`.
+therefore :math:`e^x \approx 1 + x`.
 
 In the above expression for :math:`P'`, note that the product term
 :math:`(s-i)/s` is equivalent to :math:`1-i/s`. Combining this with the
@@ -270,13 +270,13 @@ collisions.
      - Assumptions
      - Source/Comparison
    * - exact
-     - :math:`\prod_\nolimits{i=0}^{m-1} \frac{(s-i)}{s}`     
+     - :math:`\prod_\nolimits{i=0}^{m-1} \frac{(s-i)}{s}`
      - :math:`1-P'`
      - :math:`1 \le m\le s`
      - [1]
    * - Taylor approximation on #1
      - :math:`e^{-m(m-1)/2s}`
-     - :math:`1-P'` 
+     - :math:`1-P'`
      - :math:`m \ll s`
      - [1]
    * - Taylor approximation on #2
@@ -286,7 +286,7 @@ collisions.
      - [1]
    * - Large square approximation
      - :math:`1 - \frac{m^2}{2s}`
-     - :math:`\frac{m^2}{2s}` 
+     - :math:`\frac{m^2}{2s}`
      - (same)
      - [2] (where :math:`s=2^n`)
 
@@ -347,20 +347,20 @@ This equation is not used further in this analysis.
 
     def b2B3(b):
         """Convert bits b to Bytes, rounded up modulo 3
-    
+
         We report modulo 3 because the intent will be to use Base64 encoding, which is
         most efficient when inputs have a byte length modulo 3. (Otherwise, the resulting
         string is padded with characters that provide no information.)
-        
+
         """
         return math.ceil(b/8/3) * 3
-        
+
     def B(P, m):
         """return the number of bits needed to achieve a collision probability
         P for m messages
-    
+
         Assumes m << 2^b.
-        
+
         """
         b = math.log2(m**2 / P) - 1
         if b < 5 + math.log2(m):
@@ -417,4 +417,3 @@ digest length (bytes) required for expected collision probability :math:`P` over
 | 1e+ | 39  | 39  | 36  | 36  | 33  | 33  | 30  | 30  | 30  | 27  | 27  |
 | 30  |     |     |     |     |     |     |     |     |     |     |     |
 +-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+-----+
-

docs/source/concepts/MolecularVariation/Adjacency.rst

@@ -7,9 +7,9 @@ Adjacency
 
    The Adjacency class was added in v2 to describe structural variation.
 
-The adjacency class is a core concept for structural variation, representing the junction point of 
+The adjacency class is a core concept for structural variation, representing the junction point of
 two adjoined molecules. This class can be used on its own (e.g. for junctions of chimeric transcript fusions)
-or in higher order structures such as :ref:`DerivativMolecule` to represent molecules derived from multiple
+or in higher order structures such as :ref:`DerivativeMolecule` to represent molecules derived from multiple
 adjacencies (e.g. for translocations).
 
 Definition and Information Model
@@ -28,7 +28,7 @@ of the provided :ref:`SequenceReference`. These types of adjacencies are common
 can be found, for example, on either end of a chromosomal inversion.
 
 To represent this, the :ref:`SequenceLocation` used by each partner of the adjacency is defined using
-only one of the `start` or `end` attributes. Defining the location by `start` means that the sequence content 
+only one of the `start` or `end` attributes. Defining the location by `start` means that the sequence content
 extends right (increases) on the :ref:`SequenceReference`, and defining the location by `end` means that the
 sequence content extends left (decreases) on the :ref:`SequenceReference`.
 
@@ -41,18 +41,18 @@ sequence content extends left (decreases) on the :ref:`SequenceReference`.
 .. figure:: ../../images/ex_revcomp_breakpoint.png
 
    **An example Adjacency with a reverse complement partner.** The chromosome 1 sequence extends left from
-   position 1:87337011 and so is defined by the location `start`. The chromosome 10 sequence *also* extends left 
+   position 1:87337011 and so is defined by the location `start`. The chromosome 10 sequence *also* extends left
    from position 10:36119127 and so is *also* defined by the location `start`. Reading left-to-right along this
    adjacency one would expect reference sequence up to the adjacency and reverse complement sequence following.
 
 Normalization
 #############
 
-Conventions for ordering sequences and handling ambiguous sequence Adjacencies are described in 
+Conventions for ordering sequences and handling ambiguous sequence Adjacencies are described in
 :ref:`adjacency-normalization`.
 
 Linker Sequences
 ################
 
-Intervening sequences between adjoined sequences in an adjacency are called *linker sequences* and may be specified 
+Intervening sequences between adjoined sequences in an adjacency are called *linker sequences* and may be specified
 with a :ref:`SequenceExpression`.`

docs/source/concepts/MolecularVariation/CisPhasedBlock.rst

@@ -4,7 +4,7 @@ Cis-Phased Block
 !!!!!!!!!!!!!!!!
 
 The Cis-Phased Block is a set of Alleles that are found *in-cis*: occurring
-on the same physical molecule. The `CisPhasedBlock` structure is useful for 
+on the same physical molecule. The `CisPhasedBlock` structure is useful for
 representing genetic *Haplotypes*, which are commonly described with respect
 to locations on a gene, a set of nearby genes, or other physically proximal
 genetic markers that tend to be transmitted together. Unlike haplotypes, the
@@ -13,14 +13,14 @@ genetic markers that tend to be transmitted together. Unlike haplotypes, the
 .. admonition:: New in v2
 
    In VRS v1, a class with the same computational use as the `CisPhasedBlock`
-   was defined and named the `Haplotype` class. This term is not used to describe 
+   was defined and named the `Haplotype` class. This term is not used to describe
    this concept in v2, as the use of the `Haplotype` name created confusion in the
-   community, due to the additional semantics of the term around genetic linkage 
-   and ancestry. In practice, implmentations transitioning from v1 to v2 should
+   community, due to the additional semantics of the term around genetic linkage
+   and ancestry. In practice, implementations transitioning from v1 to v2 should
    find the `CisPhasedBlock` able to accommodate the same information content
    from v1 `Haplotypes`.
 
 Definition and Information Model
 @@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@
 
-.. include::  ../../def/vrs/CisPhasedBlock.rst
+.. include::  ../../def/vrs/CisPhasedBlock.rst

docs/source/concepts/MolecularVariation/index.rst

@@ -3,9 +3,9 @@
 Molecular Variation
 !!!!!!!!!!!!!!!!!!!
 
-VRS currently covers many classes of variation that are defined on a contiguous molecule such as single nucleotide 
-variants (SNVs), multi-nucleotide variants (MNVs), indels, repeats, haplotypes, breakpoints, and sequence 
-rearrangments that form derivative molecules. 
+VRS currently covers many classes of variation that are defined on a contiguous molecule such as single nucleotide
+variants (SNVs), multi-nucleotide variants (MNVs), indels, repeats, haplotypes, breakpoints, and sequence
+rearrangements that form derivative molecules.
 
 Collectively, these types of variation are called molecular variation.
 
@@ -21,4 +21,3 @@ Collectively, these types of variation are called molecular variation.
    CisPhasedBlock
    Terminus
    DerivativeMolecule
-

docs/source/concepts/SystemicVariation/index.rst

@@ -3,9 +3,9 @@
 Systemic Variation
 !!!!!!!!!!!!!!!!!!
 
-VRS currently covers many classes of variation that are defined on a contiguous molecule such as single nucleotide 
-variants (SNVs), multi-nucleotide variants (MNVs), indels, repeats, haplotypes, breakpoints, and sequence 
-rearrangments that form derivative molecules. 
+VRS currently covers many classes of variation that are defined on a contiguous molecule such as single nucleotide
+variants (SNVs), multi-nucleotide variants (MNVs), indels, repeats, haplotypes, breakpoints, and sequence
+rearrangements that form derivative molecules.
 
 Collectively, these types of variation are called molecular variation.
 
@@ -15,5 +15,5 @@ Collectively, these types of variation are called molecular variation.
 
 .. toctree::
    :titlesonly:
-   
+
    CopyNumber

docs/source/conf.py

@@ -69,7 +69,7 @@ def _parse_release_as_version(rls):
 
 # -- Options for HTML output -------------------------------------------------
 
-# The theme to use for HTML and HTML Help pages.  See the documentation for
+# The theme to use for HTML and HTML Help pages. See the documentation for
 # a list of builtin themes.
 #
 html_theme = 'sphinx_rtd_theme'