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
mapping_file: pd.DataFrame
dimensions: int, optional
remote: bool or str, optional
|
---|---|
Raises: | ValueError
|
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 |