This README only gives a brief overview of Scout, for a more complete reference, please check out our docs: https://clinical-genomics.github.io/scout .
A simple demo instance of Scout requires the installation of Docker and can be launched either by using the command:
docker-compose up -d or make up.
The repository includes a Makefile with common shortcuts to simplify setting up and working with Scout. To see a full list and description of these shortcuts run: make help.
This demo is consisting of 3 containers:
Once the server has started you and open the app in the web browser at the following address: http://localhost:8000/
The command to stop the demo are either docker-compose down or make down.
Instructions on how to run a Scout image connected to your local database or a custom database are present on this page.
git clone https://github.com/Clinical-Genomics/scout
cd scout
pip install --editable .
Scout PDF reports are created using Flask-WeasyPrint. This library requires external dependencies which need be installed separately (namely Cairo and Pango). See platform-specific instructions for Linux, macOS and Windows available on the WeasyPrint installation pages.
NB: in order to convert HTML reports into PDF reports, we have recently switched from the WeasyPrint lib to python-pdfkit. For this reason, when upgrading to a Scout version >4.47, you need to install an additional wkhtmltopdf system library.
You also need to have an instance of MongoDB running. I've found that it's easiest to do using the official Docker image:
docker run --name mongo -p 27017:27017 mongo
Once installed, you can setup Scout by running a few commands using the included command line interface. Given you have a MongoDB server listening on the default port (27017), this is how you would setup a fully working Scout demo:
scout setup demo
This will setup an instance of scout with a database called scout-demo. Now run
scout --demo serve
And play around with the interface. A user has been created with email clark.kent@mail.com so use that address to get access
To initialize a working instance with all genes, diseases etc run
scout setup database
for more info, run scout --help
The previous command initializes the database with a curated collection of gene definitions with links to OMIM along with HPO phenotype terms. Now we will load some example data. Scout expects the analysis to be accomplished using various gene panels so let's load one and then our first analysis case:
scout load panel scout/demo/panel_1.txt
scout load case scout/demo/643594.config.yaml
Scout may be configured to visualize coverage reports produced by Chanjo or chanjo2. Instructions on how to enable this feature can be found in the document chanjo_coverage_integration.
Scout may be configured to visualize local variant frequencies monitored by Loqusdb. Instructions on how to enable this feature can be found in the document loqusdb integration.
Scout may be configured to link to a local Gens installation. Instructions on how to enable this feature can be found in the document Gens integration.
Scout needs a server config to know which databases to connect to etc. Depending on which information you provide you activate different parts of the interface automatically, including user authentication, coverage, and local observations.
This is an example of the config file:
# scoutconfig.py
# list of email addresses to send errors to in production
ADMINS = ['paul.anderson@magnolia.com']
MONGO_HOST = 'localhost'
MONGO_PORT = 27017
MONGO_DBNAME = 'scout'
MONGO_USERNAME = 'testUser'
MONGO_PASSWORD = 'testPass'
# enable user authentication using Google OAuth 2.0
GOOGLE = dict(
client_id="client_id_string.apps.googleusercontent.com",
client_secret="client_secret_string",
discovery_url="https://accounts.google.com/.well-known/openid-configuration"
)
# enable Phenomizer gene predictions from phenotype terms
PHENOMIZER_USERNAME = '???'
PHENOMIZER_PASSWORD = '???'
# enable Chanjo coverage integration
SQLALCHEMY_DATABASE_URI = '???'
REPORT_LANGUAGE = 'en' # or 'sv'
# other interesting settings
SQLALCHEMY_TRACK_MODIFICATIONS = False # this is essential in production
TEMPLATES_AUTO_RELOAD = False # consider turning off in production
SECRET_KEY = 'secret key' # override in production!
Most of the config settings are optional. A minimal config would consist of SECRET_KEY and MONGO_DBNAME.
Starting the server in now really easy, for the demo and local development we will use the CLI:
scout --flask-config config.py serve
When running the server in production you will likely want to use a proper Python server solution such as Gunicorn. This is also how we can multiprocess the server and use encrypted HTTPS connections.
SCOUT_CONFIG=./config.py gunicorn --workers 4 --bind 0.0.0.0:8080 scout.server.auto:app
For added security and flexibility, we recommend a reverse proxy solution like NGINX.
Scout currently supports 3 mutually exclusive types of login:
The first 2 solutions are both suitable for a production server. A description on how to set up an advanced login system is available in the admin guide
Starting from release 4.4, Scout offers integration for patient data sharing via Matchmaker Exchange. General info about Matchmaker and patient matching could be found in this paper. For a technical guideline of our implementation of Matchmaker Exchange at Clinical Genomics and its integration with Scout check scouts matchmaker docs. A user-oriented guide describing how to share case and variant data to Matchmaker using Scout can be found here.
To keep the code base consistent, formatting with Black is always applied as part of the PR submission process via GitHub Actions. While not strictly required, to avoid confusion, it is suggested that developers apply Black locally. Black defaults to 88 characters per line, we use 100.
To format all the files in the project run:
black --line-length 100 .
We recommend using Black with pre-commit.
In .pre-commit-config.yaml you can find the pre-commit configuration.
To enable this configuration run:
pre-commit install
To run unit tests:
pytest
If you want to contribute and make Scout better, you help is very appreciated! Bug reports or feature requests are really helpful and can be submitted via github issues. Feel free to open a pull request to add a new functionality or fixing a bug, we welcome any help, regardless of the amount of code provided or your skills as a programmer. More info on how to contribute to the project and a description of the Scout branching workflow can be found in CONTRIBUTING.
FAQs
Clinical DNA variant visualizer and browser.
We found that scout-browser demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 4 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
PyPI confirms no security flaws were exploited in the Ultralytics supply chain attack and highlights improvements for safer package publishing.
Security News
Research
The Socket Research Team breaks down a malicious wrapper package that uses obfuscation to harvest credentials and exfiltrate sensitive data.
Research
Security News
Attackers used a malicious npm package typosquatting a popular ESLint plugin to steal sensitive data, execute commands, and exploit developer systems.