Functions¶

General¶

myplotspec.load_dataset(cls=None, dataset_cache=None, loose=False, **kwargs)¶

Loads a dataset, or reloads a previously-loaded dataset from a cache.

Datasets are stored in dataset_cache, a dictionary containing copies of previously loaded datasets keyed by tuples containing the class and arguments used to instantiate the dataset.

In order to support caching, a class must implement the static method Dataset.Dataset.get_cache_key(), which generates the hashable tuple key. Only arguments that influence the resulting dataset should be included in the key (e.g. infile should be included, but verbose and debug should not). If the function accepts arguments that are not hashable or convertable into a hashable form, Dataset.Dataset.get_cache_key() should return None, causing load_dataset() to reload the dataset.

Cachable dataset classes may also implement the method Dataset.Dataset.get_cache_message() which returns a message to display when the dataset is loaded from the cache.

Parameters:

cls (class, str) – Dataset class; may be either class object itself or name of class in form of ‘package.module.class’; if None, will be set to Dataset.Dataset; if ‘__noclass__’, function will return None dataset_cache (dict, optional) – Cache of previously-loaded datasets loose (bool) – Check only infile when reloading from cache; this may be used to reload a previously-loaded dataset without specifiying every argument every time. verbose (int) – Level of verbose output kwargs (dict) – Keyword arguments passed to Dataset.Dataset.get_cache_key() and Dataset.Dataset.cls()

Returns:

cls – Dataset, either newly initialized or copied from cache

myplotspec.get_yaml(input)¶

Generates a data structure from yaml input.

Parameters:	input (str, dict) – yaml input; if str, tests whether or not it is a path to a yaml file. If it is, the file is loaded using yaml; if it is not a file, the string itself is loaded using yaml. If dict, returned without modification
Returns:	output – Data structure specified by input
Warns:	UserWarning – Loaded data structure is a string; occurs if input file is a path to a yaml file that is not found
Raises:	TypeError – Input is not str or dict

myplotspec.merge_dicts(dict_1, dict_2)¶

Recursively merges two dictionaries.

Parameters:	dict_1 (dict) – First dictionary dict_2 (dict) – Second dictionary; values for keys shared by both dictionaries are drawn from dict_2
Returns:	(dict) – Merged dictionary
Raises:	AttributeError – Either dict_1 or dict_2 lacks ‘keys’ function

myplotspec.multi_get(*args, **kwargs)¶

Scans dict for keys; returns first value.

Parameters:	keys (str, list) – Acceptable key(s) in order of decreasing priority dictionary (dict) – dict to be tested value – Default to be returned if not found
Returns:	value – Value from first matching key; or None if not found

myplotspec.multi_get_copy(*args, **kwargs)¶

Scans dict for keys; returns copy of first value.

Parameters:	keys (str, list) – Acceptable key(s) in order of decreasing priority dictionary (dict) – dict to be tested value – Default to be returned if not found
Returns:	value – Value from first matching key; or None if not found

myplotspec.multi_pop(*args, **kwargs)¶

Scans dict for keys; returns first value and deletes it and others.

Parameters:	keys (str, list) – Acceptable key(s) in order of decreasing priority dictionary (dict) – dict to be tested value – Default to be returned if not found
Returns:	value – Value from first matching key; or None if not found

myplotspec.pad_zero(ticks, digits=None, **kwargs)¶

Prepares list of tick labels, each with the same precision.

Parameters:	ticks (list, ndarray) – ticks digits (int, optional) – Precision; by default uses largest provided
Returns:	tick_labels (list) – Tick labels, each with the same number of digits after the decimal point

myplotspec.get_color(color)¶

Converts color from a format understood by myplotspec to a format understood by matplotlib

If color is a str, may be of form ‘pastel.red’, ‘dark.blue’, etc. corresponding to a color set and color; if no set is specified the ‘default’ set is used. If list or ndarray, should contain three floating point numbers corresponding to red, green, and blue values. If these numbers are greater than 1, they will be divided by 255. If float, should correspond to a grayscale shade, if greater than 1 will be divided by 255.

Parameters:	color (str, list, ndarray, float) – color
Returns:	(list) – [red, green, blue] on interval 0.0-1.0

myplotspec.get_colors(dict_1, *args, **kwargs)¶

Convers color variables in a dict from formats understood by myplotspec to formats understood by matplotlib

This function is intended to process dictionaries of keyword arguments including colors before passing them on to matplotlib’s plotting functions. For each name of color argument provided in color_keys, the function searches through dict_1 and processes each using get_color(). If the argument is not found in dict_1, it then searches through each additional dictionary provided in args.

Parameters:	dict_1 (dict) – Target and first source of keys color_keys (list) – Names of keys *args (tuple) – Additional dictionary sources of keys (additional keyword arguments (**kwargs) – keys (list) – Acceptable keys in order of decreasing priority

myplotspec.get_edges(figure_or_subplots, absolute=False, **kwargs)¶

Finds the outermost edges of a set of subplots on a figure.

Parameters:	figure_or_subplots (Figure, list, dict) – Axes whose edges to get; if Figure, use all Axes
Returns:	(dict) – Edges; keys are ‘left’, ‘right’, ‘top’, and ‘bottom’

myplotspec.get_figure_subplots(figure=None, subplots=None, index=None, nrows=None, ncols=None, nsubplots=None, left=None, sub_width=None, wspace=None, right=None, bottom=None, sub_height=None, hspace=None, top=None, fig_width=None, fig_height=None, figsize=None, verbose=1, debug=0, **kwargs)¶

Generates a figure and subplots to provided specifications.

Differs from matplotlib’s built-in functions in that it:

• Accepts subplot dimensions is inches rather than proportional figure coordinates
• Optionally calculates figure dimensions from provided subplot dimensions, rather than the reverse
• Returns subplots in an OrderedDict
• Smoothly adds additional subplots to a previously-generated figure (i.e. can be called multiple times)

Parameters:

figure (Figure, optional) – Figure, if adding subplots to a preexisting Figure subplots (OrderedDict, optional) – Subplots, if adding subplots to a prevexisting Figure nrows (int) – Number of rows of subplots to add ncols (int) – Number of columns of subplots to add nsubplots (int, optional) – Number of subplots to add; if less than nrows*ncols (e.g. 2 cols and 2 rows but only three subplots) sub_width (float) – Width of subplot(s) sub_height (float) – Height of subplot(s) left (float) – Margin between left side of figure and leftmost subplot right (float) – Margin between right side of figure and rightmost subplot top (float) – Margin between top of figure and topmost subplot bottom (float) – Margin between bottom of figure and bottommost subplot wspace (float) – Horizontal margin between adjacent subplots hspace (float) – Vertical margin between adjacent subplots fig_width (float) – Width of figure; by default calculated from left, sub_width, wspace, right, and ncols fig_height (float) – Height of figure, by default calculated from bottom, sub_height, hspace, top, and nrows figsize (list) – Equivalent to [fig_width, fig_height] figure_kw (dict) – Additional keyword arguments passed to figure() subplot_kw (dict) – Additional keyword arguments passed to Axes() axes_kw (dict) – Alias to subplot_kw verbose (int) – Level of verbose output debug (int) – Level of debug output kwargs (dict) – Additional keyword arguments

Returns:

(*Figure, OrderedDict)* – Figure and subplots

myplotspec.get_font(fp=None, **kwargs)¶

Generates font based on provided specification.

fp may be a string of form ‘##L’ in which ‘##’ is the font size and L is ‘r’ for regular or ‘b’ for bold. fp may also be a dict of keyword arguments to pass to FontProperties. fp may also be a FontProperties, in which case it is returned without modification.

Parameters:	fp (str, dict, FontProperties) – Font specifications
Returns:	(FontProperties) – Font with given specifications

myplotspec.wiprint(text, width=80, subsequent_indent=u' ', **kwargs)¶

Prints wrapped text.

Parameters:	text (str) – Text to wrap width (int) – Width of formatted text subsequent_indent (str) – Text with which to prepend lines after the first kwargs (dict) – Additional keyword arguments passed to TextWrapper()

myplotspec.sformat(text, **kwargs)¶

Formats whitespace in text.

Parameters:	text (str) – Text to format
Returns:	str – text with all whitespace replaced with single spaces

Axes¶

myplotspec.axes.set_xaxis(subplot, **kwargs)¶

Formats the x axis of a subplot using provided keyword arguments.

Parameters:

subplot (Axes) – Axes to format {x}ticks (list, ndarray) – Ticks; first and last are used as upper and lower boundaries {x}tick_kw (dict) – Keyword arguments passed to subplot.set_xticks() {x}ticklabels (list) – Tick label text {x}tick{label}_fp (str, dict, FontProperties) – Tick label font {x}ticklabel_kw (dict) – Keyword arguments passed to subplot.set_xticklabels() {x}label (str) – Label text {x}label_fp (str, dict, FontProperties) – Label font {x}label_kw (dict) – Keyword arguments passed to subplot.set_xlabel() {x}tick_params (dict) – Keyword arguments passed to subplot.tick_params(); only affect x axis {x}lw (float) – Subplot top and bottom line width kwargs (dict) – Additional keyword arguments

myplotspec.axes.set_yaxis(subplot, **kwargs)¶

Formats the y axis of a subplot using provided keyword arguments.

Parameters:

subplot (Axes) – Axes to format subplot_y2 (Axes, optional) – Second y axes to format; if this is omitted, but y2ticks is included, the second y axis will be generated yticks (list or ndarray) – Ticks; first and last are used as upper and lower boundaries ytick_kw (dict) – Keyword arguments passed to subplot.set_yticks() yticklabels (list) – Tick label text {y}tick{label}_fp (str, dict, FontProperties) – Tick label font yticklabel_kw (dict) – Keyword arguments passed to subplot.set_yticklabels() ylabel (str) – Label text {y}label_fp (str, dict, FontProperties) – Label font ylabel_kw (dict) – Keyword arguments passed to subplot.set_ylabel() {y}tick_params (dict) – Keyword arguments passed to subplot.tick_params(); only affect y axis {y}lw (float) – Subplot top and bottom line width y2ticks (list or ndarray) – Ticks for second y axis; first and last are used as upper and lower boundaries; if this argument is provided, a y2 axis is generated using subplot.twiny() y2tick_kw (dict) – Keyword arguments passed to subplot.set_yticks() for second y axis y2ticklabels (list) – Tick label text for second y axis {y2}tick{label}_fp (str, dict, FontProperties) – Tick label font for second y axis y2ticklabel_kw (dict) – Keyword arguments passed to subplot.set_yticklabels() for second y axis y2label (str) – Label text for second y axis {y2}label_fp (str, dict, FontProperties) – Label font for second y axis y2label_kw (dict) – Keyword arguments passed to subplot.set_ylabel() for second y axis kwargs (dict) – Additional keyword arguments

myplotspec.axes.set_colorbar(subplot, mappable, **kwargs)¶

Configures a colorbar.

Parameters:

subplot (Axes) – axes on which mappable – Object used to generate colorbar; typically returned by matplotlib’s imshow or pcolormesh colorbar_kw (dict) – Keyword arguments used to configure colorbar; ‘position’ key is used to control orientation {z|c}ticks (list or ndarray) – Ticks; first and last are used as upper and lower boundaries {z|c}tick_kw (dict) – Keyword arguments passed to subplot.set_ticks {z|c}ticklabels (list) – Tick label text {z|c}tick{label}_fp (str, dict, FontProperties) – Tick label font {z|c}ticklabel_kw (dict) – Keyword arguments passed to subplot.set_{x|y}ticklabels() {z|c}label (str) – Label text {z|c}label_fp (str, dict, FontProperties) – Label font zlabel_kw (dict) – Keyword arguments passed to subplot.set_label {z|c}tick_params (dict) – Keyword arguments passed to subplot.tick_params() kwargs (dict) – Additional keyword arguments

myplotspec.axes.add_partner_subplot(subplot, figure, subplots, verbose=1, debug=0, **kwargs)¶

Adds a subplot to the side

Typically used for colorbars.

Parameters:	subplot (Axes) – Host subplot to which partner will be added figure (Figure) – Figure on which subplot and partner are located subplots (OrderedDict) – subplots partner_kw (dict) – Keyword arguments passed to get_figure_subplots() to add partner subplot; ‘position’ key is used to control position relative to host subplot verbose (int) – Level of verbose output debug (int) – Level of debug output
Returns:	partner (Axes) – Parter subplot

Text¶

myplotspec.text.set_title(figure_or_subplot, verbose=1, debug=0, *args, **kwargs)¶

Draws a title on a Figure or subplot.

Parameters:	figure_or_subplot (Figure, Axes) – Object on which to draw title title (str) – Title text title_fp (str, dict, FontProperties) – Title font top (float) – Distance between top of figure and title (inches); Figure title only title_kw (dict) – Keyword arguments passed to Figure.suptitle() or Axes.set_title()
Returns:	(*Text)* – Title

myplotspec.text.set_shared_xlabel(figure_or_subplots, *args, **kwargs)¶

Draws an x axis label shared by multiple subplots.

The horizontal position of the shared x label is by default the center of the selected subplots, and the vertical position is halfway between the bottommost subplot and the bottom of the figure.

Parameters:

figure_or_subplots (Figure, OrderedDict) – Subplots to use to calculate label horizontal position; if Figure, all subplots present on figure are used [shared][x]label (str) – Label text [shared][x]label_fp (str, dict, FontProperties) – Label font [shared][x]label_kw (dict) – Keyword arguments passed to set_text() bottom (float) – Distance between bottom of figure and label (inches); if negative, distance between bottommost plot and label top (float) – Distance between top of figure and label (inches); if negative, distance between topmost subplot and label; overrides bottom x (float) – X position within figure (proportion 0.0-1.0); default = center of selected subplots y (float) – Y position within figure (proportion 0.0-1.0); overrides bottom and top; default = halfway between bottommost subplot and bottom of figure

Returns:

(Text) – X axis label

myplotspec.text.set_shared_ylabel(figure_or_subplots, *args, **kwargs)¶

Draws a y-axis label shared by multiple subplots.

The vertical position of the shared y label is by default the center of the selected subplots, and the horizontal position is halfway between the leftmost subplot and the left edge of the figure.

Parameters:

figure_or_subplots (Figure, OrderedDict) – Subplots to use to calculate label vertical position; if Figure, all subplots present on figure are used [shared][y]label (str) – Label text [shared][y]label_fp (str, dict, FontProperties) – Label font [shared][y]label_kw (dict) – Keyword arguments passed to set_text() left (float) – Distance between left edge of figure and label (inches); if negative, distance between leftmost plot and label right (float) – Distance between right edge of figure and label (inches); if negative, distance between rightmost plot and label; overrides left x (float) – X position within figure (proportion 0.0-1.0); overrides left and right; default = halfway between leftmost subplot and left edge of figure y (float) – Y position within figure (proportion 0.0-1.0); default = center of selected subplots

Returns:

(Text) – Y axis label

myplotspec.text.set_label(subplot, *args, **kwargs)¶

myplotspec.text.set_text(figure_or_subplot, *args, **kwargs)¶

Draws text on a figure or subplot.

Parameters:	figure_or_subplot (Figure, Axes) – Object on which to draw text (str) – Text text_fp (str, dict, FontProperties) – Text font text_kw (dict) – Keyword arguments passed to text()
Returns:	(Text) – Text

Legend¶

myplotspec.legend.set_legend(subplot, handles=None, **kwargs)¶

Draws and formats a legend on a subplot.

Parameters:	subplot (Axes) – Subplot to which to add legend handles (OrderedDict) – Collection of [labels]: handles for datasets to be plotted on legend; by default all available datasets are included legend_lw (float) – Legend handle linewidth legend_fp (str, dict, FontProperties) – Legend font legend_kw (dict) – Keyword arguments passed to subplot.legend()
Returns:	(Legend) – Legend

myplotspec.legend.set_shared_legend(figure, subplots, handles, mode=u'manual', spines=False, **kwargs)¶

Draws a legend on a figure, shared by multiple subplots.

Useful when several plots on the same figure share the same description and plot style.

Parameters:	figure (Figure) – Figure to which to add shared legend subplots (OrderedDict) – Collection of subplots to which to append new subplot for shared legend
Returns:	(Legend) – Legend