expanding documentation and examples

KarrLab · Mar 2, 2020 · 043fb2b · 043fb2b
1 parent 19f45ce
commit 043fb2b
Show file tree

Hide file tree

Showing 3 changed files with 92 additions and 5 deletions.
diff --git a/bcforms/web/index.html b/bcforms/web/index.html
@@ -35,6 +35,7 @@ <h3>Table of contents</h3>
               <div class="large-6 cell">
                 <ul>
                   <li><a href="#calculator">Web application</a></li>
+                  <li><a href="#features">Features</a>
                   <li><a href="#grammar">Grammar</a>
                     <ul>
                       <li><a href="#subunit-composition">Subunit composition</a></li>
@@ -44,9 +45,10 @@ <h3>Table of contents</h3>
                               <li><a href="#onto_xlink">Ontology definition</a></li>
                           </ul>
                       </li>
-                      <li><a href="#coordinate-system">Subunit composition</a></li>
+                      <li><a href="#coordinate-system">Coordinate system</a></li>
                     </ul>
                   </li>
+                  <li><a href="#verification">Verification of descriptions of complexes</a></li>
                   <li><a href="#interfaces">User interfaces</a>
                     <ul>
                       <li><a href="#calculator">Webform</a></li>
@@ -127,10 +129,32 @@ <h3>Calculated properties of the complex</h3>
       </div>
 
       <div class="grid-x grid-padding-x orange">
+        <a name="features"></a>
+        <div class="large-12 cell">
+            <h2>Features</h2>
+        </div>
+        <div class="large-12 cell">
+          <p class="before_list">
+            <i>BcForms</i> has the following features:
+          </p>
+          <ul>
+            <li><b>Concrete:</b> To help researchers communicate and integrate data about macromolecules, the grammar can capture the primary structures of complexes, including non-canonical (NC) residues, caps, crosslinks, and nicks.</li>
+            <li><b>Abstract:</b> To facilitate network research, <i>BcForms</i> uses alphabets of residues and an ontology of crosslinks to abstract the structures of polymers.</li>
+            <li><b>Extensible:</b> To capture any complex, users can define residues and crosslinks inline or define custom alphabets and ontologies.</li>
+            <li><b>Structured coordinates:</b> To compose residues and crosslinks into complexes, each subunit, residue and atom has a unique coordinate relative to its parent.</li>
+            <li><b>Context-free:</b> To help integrate information about the processes which synthesize and modify macromolecules, the grammar captures the structures of macromolecules separately from the processes which generate them.</li>
+            <li><b>User-friendly:</b> To ensure <i>BcForms</i> is easy to use, the grammar is human-readable, and <i>BcForms</i> includes a web application and a command-line program.</li>
+            <li><b>Machine-readable:</b> The grammar is machine-readable to enable analyses of macromolecules.</li>
+            <li><b>Composable:</b> To facilitate network research, <i>BcForms</i> includes protocols for composing the grammar with formats such as CellML and SBML.</li>
+          </ul>
+        </div>
+      </div>
+
+      <div class="grid-x grid-padding-x blue">
         <a name="grammar"></a>
         <a name="subunit-composition"></a>
         <div class="large-12 cell">
-            <h2><i>BcForms</i> grammar</h2>
+            <h2>Grammar for complexes</h2>
         </div>
 
         <div class="large-5 cell grammar">
@@ -301,7 +325,19 @@ <h3>Example</h3>
             </div>
           </div>
         </div>
+      </div>
 
+      <div class="grid-x grid-padding-x orange">
+        <a name="verification"></a>
+        <div class="large-12 cell">
+          <h2>Syntactic and semantic verification of descriptions of complexes</h2>
+          <p>To help quality control information about macromolecules, the <i>BcForms</i> user interfaces include methods for verifying the syntactic and semantic correctness of complexes:</p>
+          <ul>
+            <li>Check that each residue has a defined structure, each atom that bonds an adjacent residue has a defined element and position which is consistent with the structure of its parent residue, and each pair of consecutive residues can form a bond. 
+            <li>Check that the element and position of each atom in each crosslink are consistent with the structure of its parent residue. For example, this can identify invalid proteins that contain consecutive residues that cannot bond because the first residue lacks a carboxyl terminus or the second residue lacks an amino terminus.</li>
+            <li>Check that each subunit is semantically concrete and that the element and position of each atom in each crosslink are consistent with the structure of its parent residue.</li>
+          </ul>
+        </div>
       </div>
 
       <div class="grid-x grid-padding-x blue">
@@ -317,17 +353,17 @@ <h3>Webform</h3>
         <div class="large-3 cell">
           <a name="rest"></a>
           <h3>JSON REST API</h3>
-          A JSON REST API is available at <a href="https://bcforms.org/api">https://bcforms.org/api</a>.
+          A JSON REST API is available at <a href="https://bcforms.org/api">https://bcforms.org/api</a>. Documentation is available by opening this URL in your browser.
         </div>
         <div class="large-3 cell">
           <a name="cli"></a>
           <h3>Command line interface</h3>
-          A command line interface is available from PyPI <a href="https://pypi.python.org/pypi/bcforms"><i class="fi-link"></i></a>.
+          A command line interface is available from PyPI <a href="https://pypi.python.org/pypi/bcforms"><i class="fi-link"></i></a>. Installation instructions and documentation are available at docs.karrlab.org <a href="https://docs.karrlab.org/bcforms/"><i class="fi-link"></i></a>.
         </div>
         <div class="large-3 cell">
           <a name="library"></a>
           <h3>Python library</h3>
-          A Python library is available from PyPI <a href="https://pypi.python.org/pypi/bcforms"><i class="fi-link"></i></a>.
+          A Python library is available from PyPI <a href="https://pypi.python.org/pypi/bcforms"><i class="fi-link"></i></a>. Installation instructions are available at docs.karrlab.org <a href="https://docs.karrlab.org/bcforms/master/installation.html"><i class="fi-link"></i></a>. Documentation is available inline by running <tt>bcforms --help</tt>.
         </div>
       </div>
 
@@ -462,6 +498,10 @@ <h3>Query builder for the REST API</h3>
           <h3>Documentation for the REST API</h3>
           Documentation for the REST API is available at bcforms.org/api <a href="https://www.bcforms.org/api"><i class="fi-link"></i></a>.
         </div>
+        <div class="large-6 cell">
+          <h3>Installation instructions for the CLI and Python API</h3>
+          Installation instructions are available at docs.karrlab.org <a href="https://docs.karrlab.org/bcforms/master/installation.html"><i class="fi-link"></i></a>. A minimal Dockerfile <a href="https://github.com/KarrLab/bpforms/blob/master/Dockerfile"><i class="fi-link"></i></a> is also available from the Git repository for <i>BpForms</i>.
+        </div>
         <div class="large-6 cell">
           <h3>Documentation for the command line program</h3>
           Documentation for the command line program is available inline by running <tt>bcforms --help</tt>.

diff --git a/docs/cli.rst b/docs/cli.rst
@@ -0,0 +1,46 @@
+Command line interface
+----------------------
+
+The command line interface provides five functions to easily manipulate `BcForms`-encoded descriptions of complexes.
+
+* **Get help with the `BcForms` command line interface.** The following commands return inline help information about the command line interface::
+
+    bcforms
+    bcforms -h
+    bcforms --help
+
+* **Validate a `BcForms`-encoded description of a form of a complex.** The following command can be used to verify if description of a complex is syntactically and semantically valid. The command line interface will print any errors to the standard error::
+
+    bcforms validate <bcform>
+
+    bcforms validate '2 * a + 3 * b'
+    # Form is valid
+
+* **Calculate the formula of a complex.** The following command can be used to calculate the formula of a complex::
+
+    bcforms get-formula --help
+
+    bcforms get-formula <bcform> <dictionary of formulae of subunits>
+
+    # Calculate the formula of a complex
+    bcforms get-formula '2 * a + 3 * b' '{a: CHO, b: C2H2O2}'
+    # C8H8O8
+
+* **Calculate the charge of a complex.** The following command can be used to calculate the charge of a complex::
+
+    bcforms get-charge --help
+
+    bcforms get-charge <bcform> <dictionary of charges of subunits>
+
+    # Calculate the charge of a complex
+    bcforms get-charge '2 * a + 3 * b' '{a: 1, b: 2}'
+    # 8
+
+* **Calculate the molecular weight of a complex.** The following command can be used to calculate the molecular weight of a complex::
+
+    bcforms get-molwt --help
+    bcforms get-molwt <bcform> <dictionary of molecular weights of subunits>
+
+    # Calculate the molecular weight of a complex
+    bcforms get-molwt '2 * a + 3 * b' '{a: 1, b: 2}'
+    # 8
diff --git a/docs/index.rst b/docs/index.rst
@@ -13,6 +13,7 @@ Contents
    :numbered:
 
    installation.rst
+   cli.rst
    API documentation <source/modules.rst>
    about.rst
    references.rst