beacon-python - Python-based Beacon API Web Server

Documentation: https://beacon-python.readthedocs.io

Quick start

beacon-python Web Server requires:

• Python 3.6+;
• running DB PostgreSQL Server 9.6+ (recommended 11.6).

git clone https://github.com/CSCfi/beacon-python
pip install -r requirements.txt
cd beacon-python

Database start

Start the PostgreSQL DB server and set up POSTGRES_USER and POSTGRES_PASSWORD as beacon and POSTGRES_DB as beacondb (default values, that can be changed via environment variables - see documentation for instructions).

It is recommended to start PostgreSQL using Docker:

docker run -e POSTGRES_USER=beacon \
           -e POSTGRES_PASSWORD=beacon \
           -v "$PWD/data":/docker-entrypoint-initdb.d
           -e POSTGRES_DB=beacondb \
           -p 5432:5432 postgres:11.6

Run beacon-python

For installing beacon-python do the following:

pip install .

Loading Data

If one has their own database the beacon_init utility can be skipped, and make use of the existing database by:

• creating a DB View that matches the DB schema for the beacon python server see: Database documentation for information on the database schema and queries;
• migrating the database to match the Database schema;
• modifying the queries in beacon_api.utils.data_query.py in order to fit one's own database.

For loading *.vcf/*.vcf.gz files into the database we provide the beacon_init utility:

╰─$ beacon_init --help             
usage: beacon_init [-h] datafile metadata

Load datafiles with associated metadata into the beacon database. See example
data and metadata files in the /data directory.

positional arguments:
  datafile    .vcf file containing variant information
  metadata    .json file containing metadata associated to datafile

optional arguments:
  -h, --help  show this help message and exit

Run the beacon-python Web Server from the command line simply using:

beacon

Using the application

The API has three endpoints, the info endpoint /, a second info endpoint /service-info for GA4GH compliancy, and the query end point /query. The info end point gives the user general info about the Beacon and it's datasets, while the query end point allows to retrieve dataset information based on specific parameters. The GA4GH info endpoint serves a minimal data payload.

For information about the endpoints and parameters consult the Beacon API specification

Info endpoint

Request:

• URL: /
• HTTP method: GET
• Parameters: None

GA4GH Info endpoint

Request:

• URL: /service-info
• HTTP method: GET
• Parameters: None

Query endpoint

Request:

• URL: /query
• HTTP method: GET and POST
• Parameters: Refer to Beacon API specification for full list of parameters.

License

beacon-python and all it sources are released under Apache License 2.0.

Acknowledgements

We would like to acknowledge the valuable feedback from the members of NBIS and DDBJ, whose ideas and contributions have helped to make the Beacon services more robust.