{
    "info": {
        "author": "Chiara Rasi",
        "author_email": "chiara.rasi@scilifelab.se",
        "bugtrack_url": null,
        "classifiers": [
            "Intended Audience :: Science/Research",
            "License :: OSI Approved :: MIT License",
            "Operating System :: MacOS",
            "Operating System :: Unix",
            "Programming Language :: Python",
            "Programming Language :: Python :: 2.6",
            "Programming Language :: Python :: 2.7",
            "Programming Language :: Python :: 3",
            "Programming Language :: Python :: 3.3",
            "Programming Language :: Python :: 3.4",
            "Programming Language :: Python :: 3.5",
            "Programming Language :: Python :: 3.6",
            "Programming Language :: Python :: Implementation :: CPython",
            "Programming Language :: Python :: Implementation :: PyPy"
        ],
        "description": "# CGbeacon\n\nInstructions and files to set up an Elixir-based beacon connected to a MySQL database.\n\n- [What is a Beacon?](#what-is-a-beacon-)\n- [Purpose](#purpose)\n- [Backend](#backend)\n  * [Requirements:](#requirements-)\n  * [Database setup:](#database-setup-)\n  * [Java Beacon installation:](#java-beacon-installation-)\n  * [Beacon setup:](#beacon-setup-)\n  * [Deploying the Beacon:](#deploying-the-beacon-)\n  * [Queries:](#queries-)\n  * [Populate the databases with your data](#populate-the-databases-with-your-data)\n    + [Installation](#installation)\n    + [Database settings](#database-settings)\n    + [Usage](#usage)\n- [User interface](#user-interface)\n\n\n## What is a Beacon?\nBeacons are web-based discovery services for genetic variants. They are useful to know if the dataset present at any institution connected to the beacon network contains a given allele (or genetic variant). Beacons are an efficient way to share valuable genetic information without overly expose genomic data, due to privacy or security issues.\n\nYou can find more info on the Beacon Network at this page: [https://beacon-network.org/#/about](https://beacon-network.org/#/about). <br>\nBeacon API v.0.3 can be found at this link: [https://github.com/ga4gh/beacon-team/releases/tag/v0.3.0](https://github.com/ga4gh/beacon-team/releases/tag/v0.3.0)   \n\n## Purpose\nThis document illustrates how to set up a beacon based on the [Elixir beacon v.0.3](https://github.com/elixirhub/human-data-beacon) on a Linux server. This beacon is meant to work with variants stored in a **MySQL database**.\n\n## Backend\nThese instructions follow those present on the Elixir Beacon's ones but differ from them for the setup of a MySQL database instead.\n\n### Requirements:\n* MySQL server 5.7\n* Java 8 JDK\n* Apache Maven 3<br>\n\n### Database setup:\nFrom inside the MySQL shell, as root, create an empty database and name it 'elixir_beacon_dev':\n\n<pre>\ncreate database elixir_beacon_dev;\n</pre>\n\nDownload the database data structure from [here](db/elixir_beacon_dev.sql) and restore it on your local machine:\n\n<pre>\nmysql -u [root] -p[root_password] elixir_beacon_dev < [path/to/downloaded/db.sql]\n</pre>\n\nYou can also set up a production MySQL database with the same data structure. \nFirst create it from a MySQL shell:\n\n<pre>\ncreate database elixir_beacon_prod;\n</pre>\n\nThen import into it the same data structure as the devel one:\n\n<pre>\nmysql -u [root] -p[root_password] elixir_beacon_prod < [path/to/downloaded/db.sql]\n</pre>\n\nFrom inside a MySQL shell, as root, create a new user named \"microaccounts_dev\", identified by a standard password 'r783qjkldDsiu', and grant it privileges over the newly-created database:\n\n<pre>\nCREATE USER 'microaccounts_dev'@'localhost' IDENTIFIED BY 'r783qjkldDsiu';\nGRANT ALL ON elixir_beacon_dev.* TO 'microaccounts_dev'@'localhost';\nGRANT ALL ON elixir_beacon_prod.* TO 'microaccounts_dev'@'localhost';\nFLUSH PRIVILEGES;\n</pre><br>\n\n### Java Beacon installation:\nTo create the Beacon jar executable clone the project in you working directory. From the terminal execute the command:\n\n<pre>\ngit clone https://github.com/elixirhub/human-data-beacon.git\n</pre>\n\nFrom terminal enter the newly created folder and the nested elixir-core folder:\n\n<pre>\ncd human-data-beacon/elixir_core\n</pre>\n\nSince the beacon is going to connect to a MySQL server it is necessary to configure the java connectore as a Maven dependency.\nOpen the **pom.xml file under the elixir_core directory** and, under the ```<dependencies>``` block, add the following code:\n\n```HTML\n<!-- https://mvnrepository.com/artifact/mysql/mysql-connector-java -->\n<dependency>\n    <groupId>mysql</groupId>\n    <artifactId>mysql-connector-java</artifactId>\n    <version>8.0.8-dmr</version>\n</dependency>\n```\n(Older versions of the jdbc driver can be found [here](https://mvnrepository.com/artifact/mysql/mysql-connector-java)).<br><br>\n\nCompile the code in the **elixir_core**:\n<pre>\nmvn clean compile jar:jar\nmvn install\n</pre>\n\nNow you should see a new folder 'target' in your current directory. This folder should contain the jar file '**elixir-core-beacon_api_v0.3-SNAPSHOT.jar**'.<br><br>\n\n### Beacon setup:\nBefore running the beacon it is necessary to change some settings in the following configuration file:<br><br>\n**human-data-beacon/elixir_beacon/src/main/resources/application-dev.properties**<br><br>\nSpecifically, the server and management **default port of the beacon is port 9075**. This might be changed into another port number.<br>\nTo communicate with a MySQL server it is necessary to changed the following lines:\n\n1. datasource.elixirbeacon.url = ~~jdbc:postgresql://127.0.0.1:5432/elixir_beacon_dev~~ must be changed into:\ndatasource.elixirbeacon.url = jdbc:mysql://127.0.0.1:3306(or_other_mysql_port)/elixir_beacon_dev\n\n2. datasource.elixirbeacon.driverClassName = ~~org.postgresql.Driver~~ must be changed into:\ndatasource.elixirbeacon.driverClassName = com.mysql.jdbc.Driver\n\n3. spring.jpa.properties.hibernate.dialect = ~~org.hibernate.dialect.PostgreSQLDialect~~ becomes:\nspring.jpa.properties.hibernate.dialect = org.hibernate.dialect.MySQLDialect\n\nOther information such as the beacon id, name, description etc. can be customized by modifying parameters in this file. <br>\nWhen deploying a new beacon it is also necessary to modify the file <br> <b>human-data-beacon/elixir_beacon/src/main/resources/application-dev.yml</b>. An example of these two files can be found in the folder [elixir_beacon_settings](elixir_beacon_settings).<br><br>\n\n### Deploying the Beacon:\nNext step is to compile and test the beacon. From terminal change directory to **human-data-beacon/elixir_beacon**. Then type:\n<pre>\nmvn clean compile package -Dspring.profiles.active=\"dev\" -Dmaven.test.skip=true\n</pre>\n\nNote that the command -Dmaven.test.skip=true will make compiling skip the tests, but it is necessary because tests will fail when trying to connect on a non-PostgreSQL database, like in this case.<br>\nIn case of successfull compilation the executable named **elixir-beacon-0.3.jar** should appear under **human-data-beacon/elixir_beacon/target/**.\nTo run the jar, from terminal move into the target directory and type:\n<pre>\njava -jar elixir-beacon-0.3.jar --spring.profiles.active=dev\n</pre>\n\nThe argument --spring.profiles.active=dev specifies the profile to be used. The other profile which could be used instead is 'test'. This latter profile requires the use and connection to a different database elixir_beacon_dev, described above.<br><br>\n\n### Queries:\n\nOnce the beacon is started it operates at the default address: **http://localhost:9075/elixirbeacon/v03/beacon/**<br>\nTo ask the beacon for a variant on a given chromosome, compose a query using the following base syntax:<br>\n\n<pre>\n<b>http://localhost:9075/elixirbeacon/v03/beacon/query?</b>\n</pre>\n\nAnd the following parameters:\n\n\n|Required/Optional|   Name\t          | Accepted values        |  Example                   |\n|:---------------:|:----------------------|:-----------------------|:---------------------------|\n|R  \t          |assemblyId             |a genome assembly       | assemblyId=GRCh37          |\n|R   \t\t  |referenceName          |1-22, X, Y, MT\t   | referenceName=1            |\n|R                |start\t          |a number                | start=1138913              |\n|O                |referenceBases         |the reference base      | referenceBases=C           |\n|O                |alternate              |the variant of interest | alternateBases=T           |\n|O                |datasetIds             |name of a dataset       | datasetIds=EGAD00000000028 |\n|O                |includeDatasetResponses|true or false(default)  |includeDatasetResponses=true|\n\n<br>So a typical query wold look like this:\n\nhttp://localhost:9075/elixirbeacon/v03/beacon/query?assemblyId=GRCh37&referenceName=1&start=1138913&alternateBases=T&includeDatasetResponses=true<br>\n\nThe possible answer to a query to the beacon would be :\n\n1. <b>\"exists\" : true</b>,  if the variant of interest is present within the beacon dataset.\n2. <b>\"exists\" : false</b>, if a variant is present at the given position, but the base(s) is different than the one present in the query.\n3. <b>\"exists\" : false</b>, if the chromosome and position given in the query do no match any entry in the database.\n\n\n\n### Populate the databases with your data\n\nYou can use the software from this repository to parse VCF files and insert into the databases your own data.\n\n#### Installation\nClone this repository in a local directory using the following command:\n<pre>\ngit clone https://github.com/Clinical-Genomics/cgbeacon.git\n</pre>\n\nChange directory to the newly created folder:\n<pre>\ncd cgbeacon\n</pre>\n\nInstall the package:\n<pre>\npip install .\n</pre>\n\n#### Database settings\nDatabase settings are specified by the connection string passed to the program. This string should have this format:\n<pre>\nmysql+pymysql://db_user:db_password@db_host:db_port/db_name\n</pre>\nIf not provided by the user the following connection string is passed to the program: mysql+pymysql://microaccounts_dev:r783qjkldDsiu@localhost:3306/elixir_beacon_dev\n\n#### Usage\nThe program parses variants from a VCF file. Samples to be included in the Beacon database and variant quality threshold might be specified as optional parameters.\n\nTo execute the program:\n<pre>\ncgbeacon --vcf path_to_vcf_file --dataset dataset_name\n</pre>\n\nOptional parameters:\n\n<pre>\n--db_connection (mysql+pymysql://db_user:db_password@db_host:db_port/db_name)\n--qual [0-99] (variant quality threshold. default=20)\n--ref chr_build (reference genome build, default is grch37)\n--use_panel path_to_gene_panel_bed_file (filter VCF file to use only intervals from a gene panel)\n--outfile (name of the pdf output file with the results of submission to Beacon)\n--customer customer_id (a text string with the name of the customer/institution owning the samples in the VCF file)\n[list of samples to process separated by space] (Default is all samples found in the VCF file)\n</pre>\n\n## User interface\nA simple front-end query Flask app to the Clinical Genomics Beacon is available under the [UI folder](UI). Download the compressed archive and uncompress it in the folder where you want to run the app from.\nTo run it, change directory to the cgbeacon_UI folder and launch it with python 3:\n\n<pre>\ncd cgbeacon_UI\npython3 run.py\n</pre>\n\nYour query interface should be now available from a web browser page at the following address:\n<pre>\nhttp://127.0.0.1:5000/\n</pre>\n\nThe app is designed to connect via SQL Alchemy to a default MySQL database present on the same machine as the app, but you can customize the connections parameter by modifying the parameter \"SQLALCHEMY_DATABASE_URI\" in the config file present in the \"instance\" folder.",
        "description_content_type": "",
        "docs_url": null,
        "download_url": "https://github.com/Clinical-Genomics/cgbeacon/tarball/0.3.0",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/Clinical-Genomics/cgbeacon",
        "keywords": "Genetic variants,VCF,sequencing,mutations,beacon",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "cgbeacon",
        "package_url": "https://pypi.org/project/cgbeacon/",
        "platform": "",
        "project_url": "https://pypi.org/project/cgbeacon/",
        "project_urls": {
            "Download": "https://github.com/Clinical-Genomics/cgbeacon/tarball/0.3.0",
            "Homepage": "https://github.com/Clinical-Genomics/cgbeacon"
        },
        "release_url": "https://pypi.org/project/cgbeacon/0.3.0/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "Extracts variants from a VCF file and inserts them into a Beacon MySQL database",
        "version": "0.3.0"
    },
    "last_serial": 3779688,
    "releases": {
        "0.2.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "6885bd36b28b50840dc7d859f38b8512",
                    "sha256": "a5a6bb1c1ba0d4ddb2c6fc40d4e35c7a66ac22320a58c7494e9579861fa15413"
                },
                "downloads": -1,
                "filename": "cgbeacon-0.2.0.tar.gz",
                "has_sig": false,
                "md5_digest": "6885bd36b28b50840dc7d859f38b8512",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16743,
                "upload_time": "2018-02-08T08:05:10",
                "url": "https://files.pythonhosted.org/packages/45/ae/a7ef6d163111ebc69ff5986724e02b076c2dac5157765b7d9c500d4d35c6/cgbeacon-0.2.0.tar.gz"
            }
        ],
        "0.2.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "9fdadbcf252a1406915e2535342a54e7",
                    "sha256": "a127cdc7c151d8c140be995e3592fec696a2a4625d51030333a4ff85902a61c6"
                },
                "downloads": -1,
                "filename": "cgbeacon-0.2.1.tar.gz",
                "has_sig": false,
                "md5_digest": "9fdadbcf252a1406915e2535342a54e7",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16746,
                "upload_time": "2018-02-08T08:31:43",
                "url": "https://files.pythonhosted.org/packages/ce/d2/8b856d40f54b19f94117776eed7ca81dff1604ba132023797268a7bdfaac/cgbeacon-0.2.1.tar.gz"
            }
        ],
        "0.3.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "dea2843cb4d053fdebf3377e31fb1ae6",
                    "sha256": "4196e9e88ff96ee7d160f142eb1f2130ed92ddf7af0dc35e1286f5903b5425c8"
                },
                "downloads": -1,
                "filename": "cgbeacon-0.3.0.tar.gz",
                "has_sig": false,
                "md5_digest": "dea2843cb4d053fdebf3377e31fb1ae6",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 16762,
                "upload_time": "2018-04-19T07:04:50",
                "url": "https://files.pythonhosted.org/packages/ec/e4/92d2fb6b93cb4607f38cb5e2ba0bd34522449cac33d3a06a4f654a8a4832/cgbeacon-0.3.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "dea2843cb4d053fdebf3377e31fb1ae6",
                "sha256": "4196e9e88ff96ee7d160f142eb1f2130ed92ddf7af0dc35e1286f5903b5425c8"
            },
            "downloads": -1,
            "filename": "cgbeacon-0.3.0.tar.gz",
            "has_sig": false,
            "md5_digest": "dea2843cb4d053fdebf3377e31fb1ae6",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 16762,
            "upload_time": "2018-04-19T07:04:50",
            "url": "https://files.pythonhosted.org/packages/ec/e4/92d2fb6b93cb4607f38cb5e2ba0bd34522449cac33d3a06a4f654a8a4832/cgbeacon-0.3.0.tar.gz"
        }
    ]
}