Package: gene-normalizer
Gene NormalizerServices and guidelines for normalizing gene termsBasic usageCreate a database instance and pass it to theQueryHandlerconstructor:>>> from gene.query import QueryHandler
>>> from gene.database import create_db
>>> q = QueryHandler(create_db())Call thenormalize()method with a gene term. If available, a rich description of the normalized concept is returned.>>> result = q.normalize("BRAF")
>>> result.gene_descriptor.gene
"hgnc:1097"
>>> result.gene_descriptor.alternate_labels
['NS7', 'RAFB1', 'B-raf', 'BRAF-1', 'BRAF1', 'B-RAF1']See thedocumentationfor more information, or check out thepublic REST instancefor a live demonstration.InstallationThe Normalizer is available via PyPI:pip install gene-normalizer[etl,pg]The[etl,pg]argument tells pip to install packages to fulfill the dependencies of thegene.etlpackage and the PostgreSQL data storage implementation.External requirementsGene Normalization relies onSeqRepodata, which you must download yourself.From therootdirectory:pip install seqrepo
sudo mkdir /usr/local/share/seqrepo
sudo chown $USER /usr/local/share/seqrepo
seqrepo pull -i 2021-01-29  # Replace with latest version using `seqrepo list-remote-instances` if outdatedIf you get an error similar to the one below:PermissionError: [Error 13] Permission denied: '/usr/local/share/seqrepo/2021-01-29._fkuefgd' -> '/usr/local/share/seqrepo/2021-01-29'You will want to do the following:(Might not be ._fkuefgd, so replace with your error message path)sudo mv /usr/local/share/seqrepo/2021-01-29._fkuefgd /usr/local/share/seqrepo/2021-01-29Use theSEQREPO_ROOT_DIRenvironment variable to set the path of an already existing SeqRepo directory. The default is/usr/local/share/seqrepo/latest.Database InitializationThe Normalizer supports two data storage options:DynamoDB, a NoSQL service provided by AWS. This is our preferred storage solution. In addition to cloud deployment, Amazon also provides a tool for local service, which can be installedhere. Once downloaded, you can start service by runningjava -Djava.library.path=./DynamoDBLocal_lib -jar DynamoDBLocal.jar -sharedDbin a terminal (add a-port <VALUE>option to use a different port)PostgreSQL, a well-known relational database technology. Once starting the Postgres server process,ensure that a database is created(we typically name oursgene_normalizer).By default, the Gene Normalizer expects to find a DynamoDB instance listening athttp://localhost:8000. Alternative locations can be specified in two ways:The first way is to set the--db_urloption to the URL endpoint.gene_update --update_all --db_url="http://localhost:8001"The second way is to set theGENE_NORM_DB_URLenvironment variable to the URL endpoint.export GENE_NORM_DB_URL="http://localhost:8001"To use a PostgreSQL instance instead of DynamoDB, provide a PostgreSQL connection URL instead, e.g.export GENE_NORM_DB_URL="postgresql://postgres@localhost:5432/gene_normalizer"Adding and refreshing dataUse thegene_updatecommand in a shell to update the database.Update source(s)The normalizer currently pulls data fromHGNC,Ensembl, andNCBI.To update one source, simply set--sourcesto the source you wish to update. The normalizer will check to see if local source data is up-to-date, acquire the most recent data if not, and use it to populate the database.For example, run the following to acquire the latest HGNC data if necessary, and update the HGNC gene records in the normalizer database:gene_update --sources="hgnc"To update multiple sources, you can use the--sourcesoption with the source names separated by spaces.Update all sourcesTo update all sources, use the--update_allflag:gene_update --update_allStarting the gene normalization serviceOnce the Gene Normalizer database has been loaded, from the project root, run the following:uvicorn gene.main:app --reloadNext, view the OpenAPI docs on your local machine:http://127.0.0.1:8000/geneDeveloper instructionsThe following sections include instructions specifically for developers.InstallationFor a development install, we recommend using Pipenv. See thepipenv docsfor direction on installing pipenv in your compute environment.Once installed, clone the repo and initialize the environment:git clone https://github.com/cancervariants/gene-normalization
cd gene-normalization
pipenv shell
pipenv update
pipenv install --devAlternatively, install thepg,etl,dev, andtestdependency groups in a virtual environment:git clone https://github.com/cancervariants/gene-normalization
cd gene-normalization
python3 -m virtualenv venv
source venv/bin/activate
pip install -e ".[pg,etl,dev,test]"Init coding style testsCode style is managed byflake8and checked prior to commit.We usepre-committo run conformance tests.This ensures:Check code styleCheck for added large filesDetect AWS CredentialsDetect Private KeyBefore first commit run:pre-commit installRunning unit testsBy default, tests will employ an existing database. For test environments where this is unavailable (e.g. in CI), theGENE_TESTenvironment variable can be set to initialize a local DynamoDB instance with miniature versions of input data files before tests are executed.export GENE_TEST=trueRunning unit tests is as easy as pytest.pipenv run pytest