Introduction to epidemic-intelligence

Introduction to epidemic-intelligence#

The epidemic-intelligence Python library is a user-friendly module for creating publication-ready visualizations of large-scale epidemic data stored in BigQuery. It is built on top of the plotly and matplotlib graphing libraries for easy customization and image exportation.

This page explains how to install epidemic-intelligence and its dependencies. The rest of the documentation will explain the docstrings for the user-facing functions in this library, as well as show some example applications.

Please note that none of the visualizations produced as examples in this documentation are meant to be represenatative or informative, but rather to showcase the capabilities of the library.

Installation#

epidemic-intelligence may be installed using pip:

$ pip install epidemic-intelligence

It relies on several dependencies, including bigquery, plotly, matplotlib, and networkx, each of which have their own dependencies. pip will automatically try to install the correct version of these libraries, which may take a while. Once it is done, you can confirm that epidemic-intelligence has been installed correctly by running:

$ pip show epidemic-inelligence

You will then be able to import epidemic-intelligence into your Python environment.

import epidemic_intelligence as ei
print(ei.__name__)

epidemic_intelligence

Google Cloud credentials#

The first parameter of all epidemic-intelligence functions is a BigQuery client object, which is used to authenticate the permissions of your account. This authentification will require you to have BigQuery API credentials. To create these credentials, follow these instructions.

To create the client object, pass a Credentials object and the ID of your BigQuery project to the bigquery.Client function, as shown below.

from google.oauth2 import service_account
from google.cloud import bigquery

credentials = service_account.Credentials.from_service_account_file('../../../credentials.json') # use the path to your credentials
project = 'net-data-viz-handbook' # use your project name
# Initialize a GC client
client = bigquery.Client(credentials=credentials, project=project)

Reference table#

A large part of epidemic-intelligence is the customizable geographical aggregations that occur when you create a visualization. In order to facilitate this, many function will ask for the location of a reference table. This table should contain a set of foreign key relationships between different geographical levels. When functions request something like output_resolution as a parameter, they are asking for the name of a column in the reference table. This will always be indicated in the documentation.

Sample Reference Table
Sample Reference Table

Uploading a table to BigQuery#

The recommended way to add your reference table to BigQuery is to upload a CSV, which can be done using these steps and BigQuery’s graphical user interface.

Tips and Tricks#

  • Do not rely on positional arguments. These functions have many optional parameters and they get confusing quickly. Always assign parameters directly.

Contents