https://github.com/matthiaskoenig/annotatedb
Annotation database for computational models
https://github.com/matthiaskoenig/annotatedb
Last synced: 4 months ago
JSON representation
Annotation database for computational models
- Host: GitHub
- URL: https://github.com/matthiaskoenig/annotatedb
- Owner: matthiaskoenig
- Created: 2019-06-13T10:22:17.000Z (about 6 years ago)
- Default Branch: develop
- Last Pushed: 2020-06-14T22:00:52.000Z (about 5 years ago)
- Last Synced: 2025-01-04T20:24:32.580Z (5 months ago)
- Language: Python
- Homepage: https://annotatedb.com
- Size: 3.65 MB
- Stars: 4
- Watchers: 5
- Forks: 0
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](https://zenodo.org/badge/latestdoi/191741174)
[](http://opensource.org/licenses/LGPL-3.0)
[](https://badge.fury.io/gh/matthiaskoenig%2Fannotatedb)
Matthias König
and
Jan Grzegorzewski
AnnotateDB
* [Overview](https://github.com/matthiaskoenig/annotatedb#overview)
* [Installation](https://github.com/matthiaskoenig/annotatedb#installation)
* [REST webservice](https://github.com/matthiaskoenig/annotatedb#rest-webservice)
* [Postgres database](https://github.com/matthiaskoenig/annotatedb#postgres-database)
* [Data sources](https://github.com/matthiaskoenig/annotatedb#data-sources)
* [Release notes](https://github.com/matthiaskoenig/annotatedb#release-notes)
* [Acknowledgements](https://github.com/matthiaskoenig/annotatedb#acknowledgements)
## Overview
[[^]](https://github.com/matthiaskoenig/annotatedb#-annotatedb) `AnnotateDB` (pronounced `annotated bee`) is a database with web frontend for mapping of annotations found in computational models in biology.
`AnnotateDB` is accessible via https://annotatedb.com.
* **Our mission** is to provide mapped annotation resources which simplify annotation of computational models and mapping of entities in such models.
* **Our vision** is to provide a single integrated knowledge resource which simplifies mapping between commonly occurring
annotations in biological models and data.
`AnnotateDB` provides a high quality mapping of annotations on each other based on existing resources.
Features are
- annotation mappings from multiple sources
- support for custom annotation mappings
- support for `qualifiers`, i.e., more detailed relationships between annotations
- support for evidence of annotations, i.e., provenance about the source and method with which the
mapping was inferred
- direct access to the `postgres` database
- `docker` and `docker-compose` scripts for easy local setup and deployment
- `REST` based web interface
- `elastisearch` based indexing and search (The `elasticsearch` end points are still in development and will be part of [`v0.2.0`](https://github.com/matthiaskoenig/annotatedb/milestone/3))
`AnnotateDB` is accessible under the following licenses
* Source Code: [LGPLv3](http://opensource.org/licenses/LGPL-3.0)
* Documentation: [CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/)
To cite the project use [](https://zenodo.org/badge/latestdoi/191741174)
## Installation
[[^]](https://github.com/matthiaskoenig/annotatedb#-annotatedb) `AnnotateDB` is distributed as `docker` containers, requiring a working [`docker`](https://docs.docker.com/install/) and [`docker-compose`](https://docs.docker.com/compose/install/)
installation.
To install `AnnotateDB` locally use
```bash
# clone or pull the latest source code
git clone https://github.com/matthiaskoenig/annotatedb.git
cd annotatedb
# set environment variables
set -a && source .env.local
# create/rebuild all docker containers
./docker-purge.sh
# restore database
./adb_restore.sh
# elasticsearch indexing
./elasticsearch.sh
```
This creates the following services
* `adb_postgres` http://localhost:5434/ - postgres database
* `adb_backend` http://localhost:5434/ - django backend
* `adb_frontend` http://localhost:8090/ - vue.js frontend
* `adb_elasticsearch` http://localhost:9124/ - elasticsearch instance
In later releases the installation will be simplified,
i.e., prebuild docker containers will be available from dockerhub (see [#32](https://github.com/matthiaskoenig/annotatedb/issues/32)).
## REST webservice
[[^]](https://github.com/matthiaskoenig/annotatedb#-annotatedb) `AnnotateDB` provides `REST` endpoints for querying the database at https://annotatedb.com/api/v1.
Some examples
* to query the `collections`use: [`https://annotatedb.com/api/v1/collections/?format=json`](https://annotatedb.com/api/v1/collections/?format=json).
* to query the `mappings`use: [`https://annotatedb.com/api/v1/mappings/?format=json`](https://annotatedb.com/api/v1/mappings/?format=json).
* to query a single `collection` use [`https://annotatedb.com/api/v1/collections/sbo/?format=json`](https://annotatedb.com/api/v1/collections/sbo/?format=json).
This will return the information on the `collection`, in this example for `sbo`
```json
{
"namespace":"sbo",
"miriam":true,
"name":"Systems Biology Ontology",
"idpattern":"^SBO:\\d{7}$",
"urlpattern":"https://identifiers.org/sbo/{$id}"
}
```
Currently only basic `REST` endpoints are available. With the introduction of the `elasticsearch`
endpoints in [`v0.3.0`](https://github.com/matthiaskoenig/annotatedb/milestone/3) the REST based search will largely improve.
For now users should directly interact with the postgres database to interact
with the mappings (see information below).
## Postgres database
[[^]](https://github.com/matthiaskoenig/annotatedb#-annotatedb) The postgres database is accessible via
```
HOST: localhost
PORT: 5434
DB: adb
USER: adb
PASSWORD: adb
```
The database contains the following main tables (see schema below):
- `adb_collection`: A data source or miriam collection for annotation or xref information
- `adb_annotation`: The combination of a term from a collection and the given collection
- `adb_mapping`: Mapping between annotations, from source annotation to target annotation. The kind of mapping is defined by the qualifier. E.g. the qualifier `BQM_IS` encodes that the source annotation `is` the target annotation.
- `adb_evidence`: Evidence for the given mapping between annotations.
In addition the materialized view `mapping_view` is provided which allows easy filtering and search of
mapped annotations and annotation synonyms. For most use cases the `mapping_view` is the table to work with.
### SQL queries
For instance query the `bigg.metabolite` for a given `chebi` identifier via
```sql
SELECT source_term FROM mapping_view
WHERE (target_term = 'CHEBI:698' AND
target_namespace = 'chebi' AND
source_namespace = 'bigg.metabolite' AND
qualifier = 'IS');
```
which results in
```
('10fthf',)
```
A more comprehensive list of SQL queries and use cases is provided [here](./docs/examples/python/example_postgres.py)
with output [here](./docs/examples/python/example_postgres.out).
## Data sources
[[^]](https://github.com/matthiaskoenig/annotatedb#-annotatedb) `AnnotateDB` uses the following data sources:
### Collections
identifiers.org
Information on collections is based mainly on [identifiers.org](http://identifiers.org/collection).
Collections were parsed with [`sbmlutils`](https://github.com/matthiaskoenig/sbmlutils).
### Mappings
BiGG
A major source of annotation mappings is the [BiGG Database](http://bigg.ucsd.edu/)
with information used from the latest [database release](https://github.com/SBRG/bigg_models_data/releases). `AnnotateDB` currently includes `BiGG-v1.5`.
## Release notes
[[^]](https://github.com/matthiaskoenig/annotatedb#-annotatedb) This section provides an overview of major changes and releases
### 0.2.0
* security fixes
* django update (>3.0), elasticsearch update (7.7.1), postgres update (12.3),
* replacing deprecated `django-rest-swagger` with `drf-yasg`
### 0.1.1
* bug fixes admin interface
* bug fixes frontend server
* enforcing uniqueness of mappings & removing duplicates
* materialized views
* detailed postgres examples
* updated documentation
### 0.1.0
* vue frontend
* bigg mappings import
* database release files
### 0.0.1
* django development server
* first database schema
* docker-compose files for backend, database and elasticsearch
## Acknowledgements
[[^]](https://github.com/matthiaskoenig/annotatedb#-annotatedb) We acknowledge
* [Dr. Andreas Dräger](http://draeger-lab.org)
* Thomas Zajac
for their input and discussions.
© 2019-2020 Matthias König & Jan Grzegorzewski