Skip to content

Commit

Permalink
Update documentation pages (#58)
Browse files Browse the repository at this point in the history 
* Update documentation

* Fix some typos

* Updates based on ben's suggestions

* Update headers

* Add software information

* Update resources.html

* Update wsgi.py

Co-authored-by: Ben Gyori <[email protected]>
  • Loading branch information
@cthoyt @bgyori
cthoyt and bgyori authored May 26, 2021
1 parent ff76011 commit beab1e6
Show file tree
Hide file tree
Showing 9 changed files with 345 additions and 58 deletions.
119 changes: 119 additions & 0 deletions src/bioregistry/app/templates/access.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,119 @@
{% extends "prose.html" %}

{% block title %}Bioregistry Programmatic Usage{% endblock %}

{% block styles %}
{{ super() }}
<link href="https://cdn.jsdelivr.net/npm/[email protected]/themes/prism.css" rel="stylesheet"/>
{% endblock %}

{% block scripts %}
{{ super() }}
<script src="https://cdn.jsdelivr.net/npm/[email protected]/prism.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/[email protected]/plugins/autoloader/prism-autoloader.min.js"></script>
{% endblock %}

{% block content %}
<h2>API Usage</h2>
<p>
The Bioregistry web application is built on <a href="https://flask.palletsprojects.com">Flask</a>
as a thin wrapper around the <a href="https://github.com/bioregistry/bioregistry"><code>bioregistry</code></a>
Python package. It exposes several endpoints for accessing the registry, metaregistry, collections, and search
functionality for which <a href="https://swagger.io/">Swagger</a> API documentation is automatically generated
by <a href="https://github.com/flasgger/flasgger">Flasgger</a>.
</p>
<p>
See the remaining Bioregistry <a href="{{ url_for('flasgger.apidocs') }}"><i class="fas fa-book"></i> API
documentation</a> or follow some of these examples using Python:
</p>
<h3>Registry</h3>
<p>
Get the whole registry:
</p>
<pre><code class="language-python">import requests
res = requests.get('https://bioregistry.io/api/registry').json()</code></pre>
<p>
Just get metadata for ChEBI:
</p>
<pre><code class="language-python">import requests
res = requests.get('https://bioregistry.io/api/registry/chebi').json()</code></pre>
<p>
Get metadata about ChEBI entry 138488 (alsterpaullone):
</p>
<pre><code
class="language-python">res = requests.get('https://bioregistry.io/api/registry/chebi:138488').json()</code></pre>
<p>
Search prefixes containing <code>che</code>:
</p>
<pre><code class="language-python">res = requests.get(
'https://bioregistry.io/api/search',
params={'q': 'che'},
).json()</code></pre>
{#
<h3>Metaregistry</h3>
<p>TODO</p>
<h3>Collections</h3>
<p>TODO</p>
#}
<h2>Python Package Usage</h2>
<p>
The Python source code can be found at
<a href="https://github.com/bioregistry/bioregistry"><i class="fab fa-github"></i> bioregistry/bioregistry</a>.
It can be installed with <code>pip install bioregistry</code> or in development mode by following
<a href="https://github.com/bioregistry/bioregistry#-installation">these instructions</a>.
</p>
<p>
The Bioregistry can be used to normalize prefixes across MIRIAM and all the (very plentiful) variants that pop
up in ontologies in OBO Foundry and the OLS with the <code>normalize_prefix()</code> function.
</p>
<pre><code class="language-python">import bioregistry

# This works for synonym prefixes, like:
assert 'ncbitaxon' == bioregistry.normalize_prefix('taxonomy')

# This works for common mistaken prefixes, like:
assert 'pubchem.compound' == bioregistry.normalize_prefix('pubchem')

# This works for prefixes that are often written many ways, like:
assert 'eccode' == bioregistry.normalize_prefix('ec-code')
assert 'eccode' == bioregistry.normalize_prefix('EC_CODE')

# If a prefix is not registered, it gives back `None`
assert bioregistry.normalize_prefix('not a real key') is None</code></pre>
<p>
Entries in the Bioregistry can be looked up with the <code>get()</code> function.
</p>
<pre><code class="language-python">entry = bioregistry.get('taxonomy')
# there are lots of mysteries to discover in this dictionary!</code></pre>
<p>
The full Bioregistry can be read in a Python project using:
</p>
<pre><code class="language-python">registry = bioregistry.read_registry()</code></pre>

<h2>Local Deployment of the Bioregistry Web Application</h2>
<p>
As the Bioregistry is open source, it's possible to host your own instance of the Bioregistry web application.
Further, it's possible create a local derivative of the registry, metaregistry, or collections that can be
deployed in your own instance. Here are examples how to do that:
</p>
<h4>Python CLI</h4>
<p>
You can also install and run the Bioregistry app from the shell:
</p>
<pre><code class="language-shell">$ pip install bioregistry[web]
$ bioregistry web</code></pre>
<p>You can also download the source code, install in development mode, and run the Bioregistry app from the shell:
</p>
<pre><code class="language-shell">$ git clone https://github.com/bioregistry/bioregistry.git
$ cd bioregistry
$ pip install --editable .[web]
$ bioregistry web</code></pre>
<h4>Docker</h4>
<p>You can deploy your own instance of the Bioregistry with:</p>
<pre><code class="language-shell">$ docker run -id -p 8766:8766 bioregistry/bioregistry:latest</code></pre>
<p>
If you want to mix using a custom version of the Bioregistry with a Docker-based deployment, please
see the dockerfile in <a href="https://github.com/bioregistry/bioregistry-docker">
<i class="fab fa-github"></i> bioregistry/bioregistry-docker</a> for inspiration.
</p>
{% endblock %}
16 changes: 13 additions & 3 deletions src/bioregistry/app/templates/base.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -52,11 +52,21 @@
<li class="nav-item active">
<a class="nav-link" href="{{ url_for("ui.collections") }}">Collections</a>
</li>
<li class="nav-item active">
<a class="nav-link" href="{{ url_for("summary") }}">Summary</a>


<li class="nav-item active dropdown">
<a class="nav-link dropdown-toggle" href="#" id="navbarDropdown" role="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
About
</a>
<div class="dropdown-menu" aria-labelledby="navbarDropdown">
<a class="dropdown-item" href="{{ url_for("summary") }}">Summary</a>
<a class="dropdown-item" href="{{ url_for("usage") }}">Programmatic Usage</a>
<a class="dropdown-item" href="{{ url_for("sustainability") }}">Deployment and Sustainability</a>
<!--<div class="dropdown-divider"></div>-->
</div>
</li>
<li class="nav-item active">
<a class="nav-link" href="{{ url_for("download") }}">Downloads</a>
<a class="nav-link" href="{{ url_for('download') }}">Downloads</a>
</li>
<li class="nav-item active">
<a class="nav-link" href="{{ url_for('flasgger.apidocs') }}">API</a>
Expand Down
10 changes: 9 additions & 1 deletion src/bioregistry/app/templates/collections.html
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{% extends "base.html" %}
{% import "macros.html" as utils %}

{% block title %}Bioregistry - Colletions{% endblock %}
{% block title %}Bioregistry - Collections{% endblock %}

{% block container %}
<div class="card">
Expand All @@ -16,6 +16,14 @@
</div>
</div>
<div class="card-body">
<p>
Collections are curated lists of prefixes along with a description of what the list is for. For example,
there's a <a href="{{ url_for("api.collection", identifier="0000001") }}">collection</a> that lists all
of the resources from the review article <i><a href="https://doi.org/10.1002/1873-3468.14067">Sharing
biological data: why, when, and how</a></i>. There's also a
<a href="{{ url_for("api.collection", identifier="0000002") }}">collection</a> comprising semantic web
prefixes.
</p>
<p>New collections can be added in one of the following ways:</p>
<ul>
<li>Edit the <a
Expand Down
92 changes: 42 additions & 50 deletions src/bioregistry/app/templates/download.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,10 @@
{% endblock %}

{% block content %}
<h2>Download</h2>
<h2>Downloads</h2>
<h3>Registry</h3>
<p>
The bioregistry database can be downloaded as:
The registry can be downloaded as:
</p>
<ul>
<li>
Expand All @@ -30,63 +31,54 @@ <h2>Download</h2>
</ul>
<p>
The manually curated portions of these data are available under the
<a href="https://creativecommons.org/share-your-work/public-domain/cc0/">
<i class="fab fa-creative-commons-zero"></i> CC0 1.0 Universal License</a>. Aggregated data are
redistributed under their original licenses.
</p>
<h3>Metaregistry</h3>
<p>
The metaregistry can be downloaded as:
</p>
<ul>
<li>
<a href="https://github.com/bioregistry/bioregistry/blob/main/src/bioregistry/data/metaregistry.json">JSON</a>
(reference file)
</li>
</ul>
<p>
The entirety of the metaregistry is manually curated and is available under the
<a href="https://creativecommons.org/share-your-work/public-domain/cc0/">
<i class="fab fa-creative-commons-zero"></i> CC0 1.0 Universal License</a>.
</p>
<h3>Bioregistry Knowledge Graph</h3>
<h3>Collections</h3>
<p>
There is preliminary work in generating a knowledge graph around the information in the Bioregistry, including
the relations between resources, providers, and registries. It can be viewed on the
<a href="{{ url_for("ui.resolve", prefix="ndex", identifier="aa78a43f-9c4d-11eb-9e72-0ac135e8bacf") }}">
Network Data Exchange (NDEx)</a>.
The collections can be downloaded as:
</p>
<h2>API Usage</h2>
<ul>
<li>
<a href="https://github.com/bioregistry/bioregistry/blob/main/src/bioregistry/data/collections.json">JSON</a>
(reference file)
</li>
</ul>
<p>
See the Swagger <a href="{{ url_for('flasgger.apidocs') }}">API documentation</a>.
The entirety of the collections is manually curated and is available under the
<a href="https://creativecommons.org/share-your-work/public-domain/cc0/">
<i class="fab fa-creative-commons-zero"></i> CC0 1.0 Universal License</a>.
</p>
<h2>Programmatic Usage</h2>
<h2>Derived and Related Resources</h2>
<h3>Bioregistry Regular Expression Report</h3>
<p>
The Python source code can be found at
<a href="https://github.com/bioregistry/bioregistry"><i class="fab fa-github"></i> bioregistry/bioregistry</a>.
It can be installed with <code>pip install bioregistry</code> or in development mode by following
<a href="https://github.com/bioregistry/bioregistry#-installation">these instructions</a>.
The Bioregistry Regular Expression Report uses <a href="https://github.com/pyobo/pyobo">PyOBO</a> to check how
consistent all of the regular expression patterns are with the actual identifiers from databases that are parsed
by PyOBO. This contains most entries from the OBO Foundry that are still accessible as well as several
additional resources such as HGNC, UniProt, etc. The automatically generated/updated report is available
<a href="https://bioregistry.github.io/regex-report/">here</a>.
</p>
<h3>Example Usage</h3>
<h3>Bioregistry Knowledge Graph</h3>
<p>
The Bioregistry can be used to normalize prefixes across MIRIAM and all the (very plentiful) variants that pop
up in ontologies in OBO Foundry and the OLS with the <code>normalize_prefix()</code> function.
There is preliminary work in generating a knowledge graph around the information in the Bioregistry, including
the relations between resources, providers, and registries. It can be viewed on the
<a href="{{ url_for("ui.resolve", prefix="ndex", identifier="aa78a43f-9c4d-11eb-9e72-0ac135e8bacf") }}">
Network Data Exchange (NDEx)</a>.
</p>
<pre><code class="language-python">
import bioregistry

# This works for synonym prefixes, like:
assert 'ncbitaxon' == bioregistry.normalize_prefix('taxonomy')

# This works for common mistaken prefixes, like:
assert 'chembl.compound' == bioregistry.normalize_prefix('chembl')

# This works for prefixes that are often written many ways, like:
assert 'eccode' == bioregistry.normalize_prefix('ec-code')
assert 'eccode' == bioregistry.normalize_prefix('EC_CODE')

# If a prefix is not registered, it gives back `None`
assert bioregistry.normalize_prefix('not a real key') is None
</code></pre>

Entries in the Bioregistry can be looked up with the <code>get()</code> function.

<pre><code class="language-python">
import bioregistry

entry = bioregistry.get('taxonomy')
# there are lots of mysteries to discover in this dictionary!
</code></pre>

The full Bioregistry can be read in a Python project using:

<pre><code class="language-python">
import bioregistry

registry = bioregistry.read_bioregistry()
</code></pre>
{% endblock %}
6 changes: 6 additions & 0 deletions src/bioregistry/app/templates/metaresources.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,12 @@
</div>
</div>
</div>
<div class="card-body">
<p>
The metaregistry contains metadata about registries including their names, descriptions, and their
various capabilities such as their ability to act as a resolver.
</p>
</div>
<table id="table-entries" class="table table-striped table-hover ">
<thead>
<tr>
Expand Down
8 changes: 7 additions & 1 deletion src/bioregistry/app/templates/resources.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@
<script>
$(document).ready(function () {
$("#table-entries").DataTable({
"order": [[ 1, "asc" ]]
"order": [[1, "asc"]]
});
$("#table-entries_wrapper").children(":first-child").addClass("card-body");
$("#table-entries_wrapper").children(":last-child").addClass("card-body");
Expand All @@ -39,6 +39,12 @@
</div>
</div>
</div>
<div class="card-body">
<p style="margin-bottom: 0">
The registry contains metadata about ontologies, controlled vocabularies, and resources including their
preferred prefix, name, description, homepage, mappings to other registries, and more.
</p>
</div>
<table id="table-entries" class="table table-striped table-hover ">
<thead>
<tr>
Expand Down
6 changes: 3 additions & 3 deletions src/bioregistry/app/templates/summary.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,7 @@ <h2>Motivation</h2>
<p>
The goal of the <a href="https://cthoyt.com/2020/04/19/inspector-javerts-xref-database.html">Inspector
Javert's Xref Database</a> was to extract all the xrefs from OBO ontologies in the OBO Foundry. However,
most ontologies took a lot of creative freedom in how what prefixes they used to refer to which
most ontologies took a lot of creative freedom in what prefixes they used to refer to which
resources, and they therefore had to be normalized. Unfortunately, most did not appear in popular
registries like MIRIAM, so the Bioregistry was created to store this information and facilitate
downstream data integration. Later, the Bioregistry became a tool that enabled the investigation of the
Expand Down Expand Up @@ -96,7 +96,7 @@ <h3>How Complete is the Bioregistry?</h3>
Biological databases, ontologies, and resource will continue to be generated as we learn about new and
exciting phenomena, so the medium-term plan to grow the Bioregistry is to continue to cover resources
that are not covered by the other resources it references. New external registries can be suggested on
the Bioregistries GitHub <a href="https://github.com/bioregistry/bioregistry/issues/new">issue
the Bioregistry GitHub <a href="https://github.com/bioregistry/bioregistry/issues/new">issue
tracker</a> using the <a href="https://github.com/bioregistry/bioregistry/labels/External%20Registry">External
Registry</a> label. Further, there are <a
href="https://github.com/bioregistry/bioregistry#-contributing">contribution guidelines</a> on the
Expand Down Expand Up @@ -215,7 +215,7 @@ <h3>Resources that Aren't Authorities</h3>
<p>
While entries in the Bioregistry are <i>supposed</i> to represent nomenclature authorities, this is not always
true because it imports from external sources that don't enforce this constraint.
For example, the Chemotoxicogenomics Database uses
For example, the Comparative Toxicogenomics Database uses
<a href="{{ url_for('ui.resource', prefix='ncbigene') }}">NCBI Gene</a> for naming genes and
<a href="{{ url_for('ui.resource', prefix='mesh') }}">MeSH</a> for naming diseases and chemicals.
Identifiers.org has minted 3 prefixes
Expand Down
Loading

0 comments on commit beab1e6

Please sign in to comment.