Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/cscfi/beacon-python
Python-based GA4GH Beacon API Server
https://github.com/cscfi/beacon-python
api beacon elixir-beacon elixir-europe ga4gh life-sciences python3
Last synced: 5 days ago
JSON representation
Python-based GA4GH Beacon API Server
- Host: GitHub
- URL: https://github.com/cscfi/beacon-python
- Owner: CSCfi
- License: apache-2.0
- Created: 2018-05-15T10:10:52.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2023-10-17T00:04:51.000Z (about 1 year ago)
- Last Synced: 2023-10-20T19:07:02.628Z (about 1 year ago)
- Topics: api, beacon, elixir-beacon, elixir-europe, ga4gh, life-sciences, python3
- Language: Python
- Homepage: https://beacon-python.readthedocs.io
- Size: 6.76 MB
- Stars: 8
- Watchers: 6
- Forks: 4
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
# Archival Notice
`beacon-python` was developed for ELIXIR Beacon implementation studies [2018](https://elixir-europe.org/internal-projects/commissioned-services/beacon-network-service) and [2019-2021](https://elixir-europe.org/internal-projects/commissioned-services/beacon-2019-21). Development on the Beacon v1 specification has ceased, and a new Beacon v2 specification has been finalised, and is being adopted by beacon providers.
Users are encouraged to move to the next iteration of [Beacon v2 Reference Implementation](https://github.com/EGA-archive/beacon2-ri-api). Beacon v2 development can be followed at [GA4GH Beacon v2 Project](https://beacon-project.io/).
We thank all parties that have been involved with us in the development of the Beacon v1 products past these years.
## beacon-python - Python-based Beacon API Web Server
[](https://coveralls.io/github/CSCfi/beacon-python?branch=HEAD)
[](https://beacon-python.readthedocs.io/en/latest/?badge=latest)
Documentation: https://beacon-python.readthedocs.io
### Quick start
`beacon-python` Web Server requires:
* Python 3.10+;
* running DB [PostgreSQL Server](https://www.postgresql.org/) 9.6+ (recommended 13).
```shell
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](https://beacon-python.readthedocs.io) for instructions).
It is recommended to start PostgreSQL using [Docker](https://www.docker.com/):
```shell
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:13
```
#### Run beacon-python
For installing `beacon-python` do the following:
```shell
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](https://beacon-python.readthedocs.io/en/latest/db.html) documentation for information on the database schema and queries;
* migrating the database to match the [Database](https://beacon-python.readthedocs.io/en/latest/db.html) schema;
* modifying the queries in [beacon_api.utils.data_query.py](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:
```shell
╰─$ 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:
```shell
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](https://github.com/ga4gh-beacon/specification/blob/develop/beacon.md)
#### 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](https://github.com/ga4gh-beacon/specification/blob/develop/beacon.md) 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](https://nbis.se/) and [DDBJ](https://www.ddbj.nig.ac.jp), whose ideas and contributions have helped to make the Beacon services more robust.