emperor.Emperor — Emperor 0.9.51-dev documentation

# 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]) | Build an emperor plot