From 043fb2b45741a188ac7284464a72953debc6e9b9 Mon Sep 17 00:00:00 2001 From: Jonathan Karr Date: Mon, 2 Mar 2020 18:15:01 -0500 Subject: [PATCH] expanding documentation and examples --- bcforms/web/index.html | 50 +++++++++++++++++++++++++++++++++++++----- docs/cli.rst | 46 ++++++++++++++++++++++++++++++++++++++ docs/index.rst | 1 + 3 files changed, 92 insertions(+), 5 deletions(-) create mode 100644 docs/cli.rst diff --git a/bcforms/web/index.html b/bcforms/web/index.html index 77af36c..5ca488a 100644 --- a/bcforms/web/index.html +++ b/bcforms/web/index.html @@ -35,6 +35,7 @@

Table of contents

+
  • Verification of descriptions of complexes
  • User interfaces
    • Webform
      • @@ -127,10 +129,32 @@

      Calculated properties of the complex

    • + +
    +

    Features

    +
    +
    +

    + BcForms has the following features: +

    +
      +
    • Concrete: 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.
      • +
    • Abstract: To facilitate network research, BcForms uses alphabets of residues and an ontology of crosslinks to abstract the structures of polymers.
      • +
    • Extensible: To capture any complex, users can define residues and crosslinks inline or define custom alphabets and ontologies.
      • +
    • Structured coordinates: To compose residues and crosslinks into complexes, each subunit, residue and atom has a unique coordinate relative to its parent.
      • +
    • Context-free: 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.
      • +
    • User-friendly: To ensure BcForms is easy to use, the grammar is human-readable, and BcForms includes a web application and a command-line program.
      • +
    • Machine-readable: The grammar is machine-readable to enable analyses of macromolecules.
      • +
    • Composable: To facilitate network research, BcForms includes protocols for composing the grammar with formats such as CellML and SBML.
      • +
    +
    +
    + +
    -

    BcForms grammar

    +

    Grammar for complexes

    @@ -301,7 +325,19 @@

    Example

    + +
    + +
    +

    Syntactic and semantic verification of descriptions of complexes

    +

    To help quality control information about macromolecules, the BcForms user interfaces include methods for verifying the syntactic and semantic correctness of complexes:

    +
      +
    • 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. +
    • 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.
      • +
    • 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.
      • +
    +
    @@ -317,17 +353,17 @@

    Webform

    JSON REST API

    - A JSON REST API is available at https://bcforms.org/api. + A JSON REST API is available at https://bcforms.org/api. Documentation is available by opening this URL in your browser.

    Command line interface

    - A command line interface is available from PyPI . + A command line interface is available from PyPI . Installation instructions and documentation are available at docs.karrlab.org .

    Python library

    - A Python library is available from PyPI . + A Python library is available from PyPI . Installation instructions are available at docs.karrlab.org . Documentation is available inline by running bcforms --help.
    @@ -462,6 +498,10 @@

    Query builder for the REST API

    Documentation for the REST API

    Documentation for the REST API is available at bcforms.org/api . +
    +

    Installation instructions for the CLI and Python API

    + Installation instructions are available at docs.karrlab.org . A minimal Dockerfile is also available from the Git repository for BpForms. +

    Documentation for the command line program

    Documentation for the command line program is available inline by running bcforms --help. diff --git a/docs/cli.rst b/docs/cli.rst new file mode 100644 index 0000000..18129b9 --- /dev/null +++ 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 + + 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 + + # 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 + + # 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 + + # 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 index 39a9769..84d4d36 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -13,6 +13,7 @@ Contents :numbered: installation.rst + cli.rst API documentation about.rst references.rst \ No newline at end of file