cassiopeia.pl.upload_and_export_itol#
- cassiopeia.pl.upload_and_export_itol(cassiopeia_tree, tree_name, export_filepath, itol_config='~/.itolconfig', api_key=None, project_name=None, meta_data=[], allele_table=None, indel_colors=None, indel_priors=None, rect=False, include_legend=False, use_branch_lengths=False, palette=('#1f77b4', '#aec7e8', '#ff7f0e', '#ffbb78', '#2ca02c', '#98df8a', '#d62728', '#ff9896', '#9467bd', '#c5b0d5', '#8c564b', '#c49c94', '#e377c2', '#f7b6d2', '#7f7f7f', '#c7c7c7', '#bcbd22', '#dbdb8d', '#17becf', '#9edae5'), random_state=None, user_dataset_files=None, verbose=True, **kwargs)[source]#
Uploads a tree to iTOL and exports it.
This function takes in a tree, plots it with iTOL, and exports it locally. A user can also specify meta data and allele tables to visualize alongside their tree. The function requires a user to have an account with iTOL and can pass these credentials to the function in one of two ways: first, the user can specify an api_key and a project_name, which corresponds to one in the user’s iTOL account’ second, the user can have a hidden itolconfig file that can store these credentials (the default location we will check is in ~/.itolconfig, though this can be overridden by the user). We preferentially take values passed in explicitly to the function in the api_key and project_name arguments.
- TODO(mgjones): Add the ability to pass in min/max colors for specific
numeric meta data to use when creating the gradient files.
- Parameters:
- cassiopeia_tree
CassiopeiaTree A CassiopeiaTree instance, populated with a tree.
- tree_name
str Name of the tree. This is what the tree will be called within your project directory on iTOL
- export_filepath
str Output file path to save your tree. Must end with one of the following suffixes: [‘png’, ‘svg’, ‘eps’, ‘ps’, ‘pdf’].
- itol_config
str(default:'~/.itolconfig') A configuration file that a user can maintain for storing iTOL account details (specifically, an API key and a project name for uploading trees). We assume that the information is stored under the [DEFAULT] header. We also will be default check the path ~/itolconfig but the user can pass in another path should they wish. If an api_key and project_name are also passed in, we will preferentially take those values.
- api_key
Optional[str] (default:None) API key linking to your iTOL account
- project_name
Optional[str] (default:None) Project name to upload to.
- meta_data
List[str] (default:[]) Meta data to plot alongside the tree, which must be columns in the CassiopeiaTree.cell_meta variable.
- allele_table
Optional[DataFrame] (default:None) Alleletable to plot alongside the tree.
- indel_colors
Optional[DataFrame] (default:None) Color mapping to use for plotting the alleles for each cell. Only necessary if allele_table is specified.
- indel_priors
Optional[DataFrame] (default:None) Prior probabilities for each indel. Only useful if an allele table is to be plotted and indel_colors is None.
- rect
bool(default:False) Boolean indicating whether or not to save your tree as a circle or rectangle.
- use_branch_lengths
bool(default:False) Whether or not to use branch lengths when exporting the tree.
- include_legend
bool(default:False) Plot legend along with meta data.
- palette
List[str] (default:('#1f77b4', '#aec7e8', '#ff7f0e', '#ffbb78', '#2ca02c', '#98df8a', '#d62728', '#ff9896', '#9467bd', '#c5b0d5', '#8c564b', '#c49c94', '#e377c2', '#f7b6d2', '#7f7f7f', '#c7c7c7', '#bcbd22', '#dbdb8d', '#17becf', '#9edae5')) A palette of colors in hex format.
- random_state
Optional[RandomState] (default:None) A random state for reproducibility
- user_dataset_files
Optional[List[str]] (default:None) List of paths to additional dataset files to upload. See https://itol.embl.de/help.cgi#dsType for available dataset types and their definitions.
- verbose
bool(default:True) Include extra print statements.
- **kwargs
additional keyword arguments are passed as iTOL export parameters. See https://itol.embl.de/help.cgi#batch for a full list.
- cassiopeia_tree
- Raises:
iTOLError if iTOL credentials cannot be found, if the output format is – not supported, if meta data to be plotted cannot be found, or if an error with iTOL is encountered.