Web UI, documentation updates and connection pooling

.readthedocs.yaml

@@ -0,0 +1,15 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+python:
+  install:
+    - requirements: doc/requirements.txt

doc/index.rst

@@ -17,6 +17,14 @@ INDRA Database REST Service
 
    rest_api_doc/readme_link.rst
 
+INDRA Database Web UI
+=====================
+
+.. toctree::
+   :maxdepth: 3
+
+   web_ui_doc/index.rst
+
 Indices and tables
 ==================
 

doc/web_ui_doc/index.rst

@@ -0,0 +1 @@
+.. mdinclude:: ../../indra_db_service/search_introduction.md

indra_db/databases.py

@@ -259,7 +259,16 @@ class BaseMeta(DeclarativeMeta, IndraDBTableMetaClass):
             return
 
         # Create the engine (connection manager).
-        self.__engine = create_engine(self.url)
+        # Try to use pool_pre_ping=True and increase the pool size from the default 5:
+        # https://docs.sqlalchemy.org/en/14/core/engines.html#sqlalchemy.create_engine
+        # Also try set pool_recycle to 1 hour - this causes the pool to recycle
+        # connections after 1 hour.
+        self.__engine = create_engine(
+            self.url,
+            pool_pre_ping=True,
+            pool_size=10,
+            pool_recycle=3600
+        )
         return
 
     def _init_foreign_key_map(self, foreign_key_map):

indra_db_service/api.py

@@ -250,9 +250,12 @@ def serve_data_vis(file_path):
 
 
 if TESTING["status"] and not TESTING["deployment"]:
-    assert (
-        VUE_ROOT.exists() and VUE_ROOT.is_absolute()
-    ), "Cannot test API without absolute path to Vue packages."
+    assert VUE_ROOT and VUE_ROOT.exists(), (
+        "Local Vue package needs to be specified if no S3 deployment is used. Set "
+        "INDRA_DB_API_VUE_ROOT in the environment to specify the path to the local Vue "
+        "package."
+    )
+    assert VUE_ROOT.is_absolute(), "Cannot test API without absolute path to Vue packages."
 
     @app.route("/ilv/<path:file>")
     def serve_indralab_vue(file):
@@ -309,7 +312,6 @@ def serve_stages(stage):
 
     return jsonify(json.loads(res["Body"].read()))
 
-
 @app.route("/statements", methods=["GET"])
 @jwt_nontest_optional
 @user_log_endpoint
@@ -329,7 +331,6 @@ def old_search():
         reverse_source_mapping=rev_source_mapping,
     )
 
-
 @app.route("/<result_type>/<path:method>", methods=["GET", "POST"])
 @app.route("/metadata/<result_type>/<path:method>", methods=["GET", "POST"])
 @user_log_endpoint

indra_db_service/cli/__init__.py

@@ -33,20 +33,22 @@ def push(deployment, zappa_settings_file):
               help="Override the default port number.")
 @click.option('-h', '--host', default='0.0.0.0',
               help="Override the default host.")
-@click.option('--deployment',
+@click.option('-vd', '--vue-deployment',
+              type=click.Choice(['stable', 'dev', 'latest', 'test']),
               help="Load the vue package from this S3 deployment instead of "
-                   "a local directory.")
-def test_service(port, host, deployment=None):
+                   "a local directory.",
+              required=False)
+def test_service(port, host, vue_deployment):
     """Run the service in test mode locally."""
     from indra_db_service.config import TESTING
     TESTING['status'] = True
-    if deployment is not None:
-        TESTING['deployment'] = deployment
+    if vue_deployment is not None:
+        TESTING['deployment'] = vue_deployment
         TESTING['vue-root'] = (
             f'https://bigmech.s3.amazonaws.com/indra-db/indralabvue-'
-            f'{deployment}'
+            f'{vue_deployment}'
         )
-        click.echo(f'Using deployment {deployment} from S3 at {TESTING["vue-root"]}')
+        click.echo(f'Using deployment {vue_deployment} from S3 at {TESTING["vue-root"]}')
 
     from indra_db_service.api import app
     app.run(host=host, port=port, debug=True)

indra_db_service/search_introduction.md

@@ -0,0 +1,65 @@
+# INDRA DB Search Interface
+
+On the landing page of the INDRA DB web interface, you can search for statements by
+agent name, statement type, MeSH term, or paper. By default, an unfilled agent search
+option is displayed. You can add additional search options by selecting one from the
+dropdown below the current list of search options. You can also remove a search option
+by clicking the "X" button next to it. Once you have entered your search criteria, click
+the "Search" button to retrieve the statements that match your search criteria.
+
+## Search Options
+
+The search options are as follows:
+
+- Agent: search by a specific entity (gene, small molecule, biological process, etc.)
+  The options are:
+  - role:
+
+    - subject: the agent is an upstream/controller in retrieved statements
+    - object: the agent is downstream/controlled in retrieved statements
+    - any: any role is allowed
+  - text: Enter the name of the agent
+  - namespace and Gilda grounding option: Typically it's more reliable to query the DB
+    using identifiers rather than informal names. If you know the identifier for e.g., a
+    gene, say "HGNC:1234", you enter '1234' in the text box and then chose 'hgnc' in the
+    namespace dropdown. However, if you only know the name, the Gilda grounding option
+    is useful. If you enter e.g., "K-ras" and click "Ground with GILDA", it will
+    automatically find an identifier for it. If there is ambiguity, you can select the
+    correct entity from a dropdown. Once you click "Search", the DB will be queried
+    using the ID selected from the dropdown.
+- Type: the type of statement e.g. Activation, Phosphorylation, DecreaseAmount, Complex,
+  etc. Read more about the types of statements in the 
+  [INDRA documentation](https://indra.readthedocs.io/en/latest/modules/statements.html).
+- MeSH: a Medical Subject Headings term that the papers retrieved as evidence are
+  annotated with. This option also has the option to ground with Gilda if you only know
+  the name of the MeSH term.
+- Paper: Limit the search to a specific publication that evidence comes from. To include
+  multiple papers, select another paper search option from the dropdown. In the paper
+  search option, you can search by these publication identifiers:
+  - PMID: PubMed ID
+  - PMCID: PubMed Central ID
+  - DOI: Digital Object Identifier
+  - TRID: Internal INDRA DB ID signifying a specific publication regardless of the
+    external identifier (PMID, PMCID, DOI).
+  - TCID: Internal INDRA DB ID signifying a piece of a text retrieved from 
+    a particular source.
+
+## Search Results
+
+The search results are displayed in hierarchical list format. At the top level, the
+most generic form of interaction matching the search criteria are displayed. Clicking
+on one of the rows expands the next level of detail, showing the specific forms of
+interactions that match the search criteria. Clicking on one of these rows expands the
+next level of detail, showing the specific statements that match the search criteria.
+The nesting is at most three levels deep, but can also be less if e.g., there is only one
+statement type for one interaction type.
+
+![Web UI screenshot](../doc/web_ui_results_expanded.png)
+<span class="caption">Search results view with three levels of nesting expanded for USP15 affecting BARD1</span>
+
+The search results allows you to curate evidence for each statement. To do this, click
+on the pencil icon next to the piece of evidence you want to curate. This will open a
+curation area where different options for curating the evidence are available. To read
+more about curation, see the
+[curation tutorial](https://indra.readthedocs.io/en/latest/tutorials/html_curation.html)
+in the INDRA documentation.

indra_db_service/templates/idbr_description.html

@@ -1 +1,6 @@
-A database built with INDRA combining content from numerous readers and databases.
+This project is developed by the <a href="https://gyorilab.github.io">
+Gyori Lab for Computational Biomedicine</a> at Northeastern University.
+This work was funded by DARPA grants W911NF‐15‐1‐0544 and HR00112220036
+under the DARPA CwC, DARPA ASKEM and ARPA-H BDF programs.
+Source code for the INDRA DB is available <a href='https://github.com/gyorilab/indra_db'>here</a>.
+Contact: <a href="mailto:[email protected]">Benjamin M. Gyori</a>.

indra_db_service/templates/idbr_statements_view.html

@@ -16,7 +16,7 @@
     {{ nav_header(identity) }}
 {% endblock %}
 
-{% block header_desc %}{% include "idbr_description.html" %}{{ super() }}{% endblock %}
+{% block footer_desc %}{% include "idbr_description.html" %}{{ super() }}{% endblock %}
 
 {% block body %}
     {{ login_overlay() }}

indra_db_service/templates/idbr_template.html

@@ -60,10 +60,16 @@
             Search
           </a>
         </li>
-        <li class="nav-item {% if old_search_active %}active{% endif %}">
-          <a class="nav-link" href="{{ url_for('old_search') }}"
+        <li>
+          <a class="nav-link" href="https://github.com/gyorilab/indra_db/blob/master/indra_db_service/search_introduction.md"
              target="_blank">
-            (Old Search)
+            Documentation
+          </a>
+        </li>
+        <li>
+          <a class="nav-link" href="https://github.com/gyorilab/indra_db/blob/master/indra_db_service/README.md"
+             target="_blank">
+            Rest API
           </a>
         </li>
       </ul>
@@ -94,15 +100,12 @@
     {{ nav_header(identity) }}
 {% endblock %}
 
-{% block header_desc %}
-  <p>{% include "idbr_description.html" %}</p>
-{% endblock %}
 
 {% block body %}
     {{ login_overlay() }}
     {{ super() }}
 {% endblock %}
 
-{% block additional_footer %}
-  <p>{% include "idbr_footer.html" %}</p>
+{% block footer_desc %}
+  <p>{% include "idbr_description.html" %}</p>
 {% endblock %}

indra_db_service/templates/search.html

@@ -3,7 +3,14 @@
 {% block scripts %}
 {{ super() }}
 
-<script src="https://cdn.jsdelivr.net/npm/vue/dist/vue.js"></script>
+<!-- Vue.js setup -->
+
+<!-- development version, includes helpful console warnings -->
+<!--<script src="https://cdn.jsdelivr.net/npm/vue@2/dist/vue.js"></script>-->
+<!-- production version, optimized for size and speed -->
+<script src="https://cdn.jsdelivr.net/npm/vue@2"></script>
+
+<!-- indralab vue package, sourced from either S3 or locally when developing -->
 <script src="{{ vue_src }}"></script>
 <link href="{{  vue_style }}" rel="stylesheet">