emperor.Emperor

class emperor.Emperor(ordination, mapping_file, dimensions=5, remote=True)

Display principal coordinates analysis plots

Use this object to interactively display a PCoA plot using the Emperor GUI. IPython provides a rich display system that will let you display a plot inline, without the need of creating a temprorary file or having to write to disk.

Parameters:

ordination: skbio.OrdinationResults

Object containing the computed values for an ordination method in scikit-bio.

mapping_file: pd.DataFrame

DataFrame object with the metadata associated to the samples in the ordination object, should have an index set and it should match the identifiers in the ordination object.

dimensions: int, optional

Number of dimensions to keep from the ordination data, defaults to 5.

remote: bool or str, optional

This parameter can have one of the following three behaviors according to the value: (1) str - load the resources from a user-specified remote location, (2) False - load the resources from the nbextensions folder in the Jupyter installation or (3) True - load the resources from the GitHub repository. This parameter defaults to True. See the Notes section for more information.

Raises:

ValueError

If the remote argument is not of bool or str type.

Notes

This object currently does not support the full range of actions that the GUI does support and should be considered experimental at the moment.

The remote parameter is intended for different use-cases, you should use the first option “(1) - URL” when you want to load the data from a location different than the GitHub repository or your Jupyter notebook resources i.e. a custom URL. The second option “(2) - False” loads resources from your local Jupyter installation, note that you need to execute nbinstall at least once or the application will error, this option is ideal for developers modifying the JavaScript source code, and in environments of limited internet connection. Finally, the third option “(3) - True” should be used if you intend to embed an Emperor plot in a notebook and then publish it using http://nbviewer.jupyter.org.

References

[R3]EMPeror: a tool for visualizing high-throughput microbial community data Vazquez-Baeza Y, Pirrung M, Gonzalez A, Knight R. Gigascience. 2013 Nov 26;2(1):16.

Examples

Create an Emperor object and display it from the Jupyter notebook:

>>> import pandas as pd, numpy as np
>>> from emperor import Emperor
>>> from skbio import OrdinationResults

Ordination plots are almost invariantly associated with a set of data, that relates each sample to its scientific context, we refer to this as the sample metadata, and represent it using Pandas DataFrames. For this example we will need some metadata, we start by creating our metadata object:

>>> data = [['PC.354', 'Control', '20061218', 'Control_mouse_I.D._354'],
... ['PC.355', 'Control', '20061218', 'Control_mouse_I.D._355'],
... ['PC.356', 'Control', '20061126', 'Control_mouse_I.D._356'],
... ['PC.481', 'Control', '20070314', 'Control_mouse_I.D._481'],
... ['PC.593', 'Control', '20071210', 'Control_mouse_I.D._593'],
... ['PC.607', 'Fast', '20071112', 'Fasting_mouse_I.D._607'],
... ['PC.634', 'Fast', '20080116', 'Fasting_mouse_I.D._634'],
... ['PC.635', 'Fast', '20080116', 'Fasting_mouse_I.D._635'],
... ['PC.636', 'Fast', '20080116', 'Fasting_mouse_I.D._636']]
>>> columns = ['SampleID', 'Treatment', 'DOB', 'Description']
>>> mf = pd.DataFrame(columns=columns, data=data)

Before we can use this mapping file in Emperor, we should set the index to be SampleID.

>>> mf.set_index('SampleID', inplace=True)

Then let’s create some artificial ordination data:

>>> ids = ('PC.636', 'PC.635', 'PC.356', 'PC.481', 'PC.354', 'PC.593',
...             'PC.355', 'PC.607', 'PC.634')
>>> eigvals = np.array([0.47941212, 0.29201496, 0.24744925,
...                     0.20149607, 0.18007613, 0.14780677,
...                     0.13579593, 0.1122597, 0.])
>>> eigvals = pd.Series(data=eigvals, index=ids)
>>> n = eigvals.shape[0]
>>> samples = np.random.randn(n, n)
>>> samples = pd.DataFrame(data=site, index=ids)
>>> p_explained = np.array([0.26688705, 0.1625637, 0.13775413, 0.11217216,
...                         0.10024775, 0.08228351, 0.07559712, 0.06249458,
...                         0.])
>>> p_explained = pd.Series(data=p_explained, index=ids)

And encapsulate it inside an OrdinationResults object:

>>> ores = OrdinationResults(eigvals, samples=samples,
...                          proportion_explained=p_explained)

Finally import the Emperor object and display it using Jupyter, note that this call will have no effect under a regular Python session:

>>> Emperor(ores, mf)

Methods

copy_support_files([target]) Copies the support files to a target directory
make_emperor([standalone, custom_axes]) Build an emperor plot