Click this link to access the CARD:Live Dashboard server.
This repository contains code for the CARD:Live Dashboard. This is used to summarize and display data from CARD:Live in a dashboard.
This application uses Python Dash and so requires Python to be installed (Python 3.7+). It is recommended that you use a Python virtual environment (or conda) to install. To set this up and install the application please run:
# Setup virtual environment
virtualenv card-live-venv
source card-live-venv
python -m pip install card-live-dashboard
python -m pip install 'pandas<2.0.0' # Resolves deprecation of DataFrame.append in pandasNote: If you encounter an error related to libgeos_c.so, you may need to install this separately. One option is to install the geos package via conda (conda install geos) which should include libgeos_c. See issue #18.
If, instead, you want to install and do development on the code you can instead run (after creating a virtual environment):
# Clone project
git clone https://github.com/arpcard/card-live-dashboard
cd card-live-dashboard
# Change to main project directory
cd card-live-dashboard
python -m pip install -e .
python -m pip install 'pandas<2.0.0' # Resolves deprecation of DataFrame.append in pandasThis will make the installed application reflect any code changes made within card-live-dashboard/.
Before running, you will have to create a CARD:Live dashboard home directory. This directory will be used to store the CARD:Live data as well as the NCBI taxnomy database and configuration. Please run the below command to create this directory:
card-live-dash-init [cardlive-home]By default this will download a copy of the most recent data from CARD:Live (available at https://bergen.mcmaster.ca/cardlive/data/all).
If, instead, you wish to start with an empty data directory you can use --no-download-data. In this case, you will have to copy data to [cardlive-home]/data/card_live before the application starts up.
If you are intending to do development or wishing to test out CARD:Live, it is recommended you downsample the data prior to running the application. This will make everything run quicker and smoother.
To do this, please run the following commands:
# Rename full data directory
mv [cardlive-home]/data/card_live [cardlive-home]/data/card_live.all
# Create new directory for downsampled data
mkdir [cardlive-home]/data/card_live
# Select a random subset of 500 samples and link them in the appropriate directory
find [cardlive-home]/data/card_live.all/ | shuf | head -n 500 | xargs -I {} ln {} [cardlive-home]/data/card_live/Make sure to replace [cardlive-home] with your chosen directory name when running card-live-dash-init.
To run the production server, please run:
card-live-dash-prod start [cardlive-home]Where [cardlive-home] is the CARD:Live home directory.
This will serve the CARD:Live dashboard on port 8050 by default. Underneath, this runs gunicorn.
To check the status of the CARD:Live application you can run:
card-live-dash-prod status [cardlive-home]This will let you know if the application is running.
To stop the application you can run:
card-live-dash-prod stop [cardlive-home]
This will kill the main application and any workers. Note this requires the application to be started in daemon mode to work properly.
The file [cardlive-home]/config/gunicorn.conf.py can be used to adjust many configuration options for running the web server. An example of this file can be found here. A subset of the options is shown below and a more detailed list can be found in the gunicorn configuration documentation.
bind = '127.0.0.1:8050'
workers = 2
...
Please modify this file to adjust configuration.
There also exists a separate YAML configuration file for the application. Right now this is only used to specify a path where the application can run. This will be stored in [cardlive-home]/config/cardlive.yaml and will look like:
---
## A URL path under which the application should run (e.g., http://localhost/app/).
## Defaults to '/'. Uncomment if you want to run under a new path.
#url_base_pathname: /app/If you wish to run the application under some non-root directory (e.g., under http://localhost:8050/app) you can modify the url_base_pathname here.
You can also run the gunicorn command directly to override configuration settings.
gunicorn --workers 2 -b 0.0.0.0:8050 "card_live_dashboard.app:flask_app(card_live_home='[cardlive-home]')" --timeout 600 --log-level debugTo run the development server please run:
card-live-dash-dev [cardlive-home]Note: As per the Dash documentation (which references the Flash documentation) it is not recommended to run the development (built-in) server for a production machine since it doesn't scale well. Important: also, since debug mode is turned on this will expose certain information about the underlying server. Please do not use development mode in production.
There is also a server used to profile requests coming to the server (for looking at time of requests). This can be run like:
card-live-dash-profiler [cardlive-home]The same caveats as for the Development server still apply (it also turns on Debug mode and should not be run for a production server).
If you wish to make use of the data, it is all available for download from the main application (https://bergen.mcmaster.ca/cardlive/):
This will give you a zip file of the results (in JSON format) of RGI,LMAT,MLST tools.
If you wish to make use of the data (e.g., load into dataframes for plotting) then feel free to following along with the following Juptyer notebook for how to convert the JSON results files to a dataframe using the CARD:Live Dashboard API.
For more general information on working with Plotly/Dash to construct figures (including producing the chropleth map) you can look at the below Juptyer notebook which was used for a previous CARD:Live presentation.
A lot more details are found in the Dash Documentation.
To run the tests, please first install the application (to get the dependencies installed) and run:
pytestFor more information you can contact card@mcmaster.ca or aaron.petkau@gmail.com.