mass.visualization.phase_portraits

Contains function for visualizing phase portraits of simulation results.

See the mass.visualization documentation for general information on mass.visualization functions.

This module contains the following functions for visualization of time-dependent solutions returned in MassSolutions after simulation of models.

Module Contents

Functions

plot_phase_portrait(mass_solution, x, y[, ax, legend])

Plot phase portraits of solutions in a given MassSolution.

plot_ensemble_phase_portrait(mass_solution_list, x, y)

Plot a phase portrait for an ensemble of class:~.MassSolution objects.

plot_tiled_phase_portraits(mass_solution[, ...])

Plot phase portraits of solutions in a given MassSolution.

get_phase_portrait_default_kwargs(function_name)

Get default kwargs for plotting functions in phase_portraits.
mass.visualization.phase_portraits.plot_phase_portrait(mass_solution, x, y, ax=None, legend=None, **kwargs)[source]

Plot phase portraits of solutions in a given MassSolution.

Accepted kwargs are passed onto various matplotlib methods utilized in the function. See the visualization module documentation for more detailed information about the possible kwargs.

Notes

Parameters

  • mass_solution (MassSolution) – The MassSolution containing the time-dependent solutions to be plotted.

  • x (mass object or its string identifier) – The string identifier of a mass object or the object itself that corresponds to the key for the desired solution in the MassSolution for the x-axis of the phase portrait.

  • y (mass object or its string identifier) – The string identifier of a mass object or the object itself that corresponds to the key for the desired solution in the MassSolution for the y-axis of the phase portrait.

  • ax (matplotlib.axes.Axes, None) – An Axes instance to plot the data on. If None then the current axes instance is used.

  • legend (iterable, str, int) –

    There are three possible input formats for the legend:

    1. An iterable of legend labels as strings.

    2. A str representing the location of the legend, or an int between 0 and 14 (inclusive) corresponding to the legend location.

    3. An iterable of the format (labels, loc) to set both the legend labels and location, where labels and loc follows the format specified in 1 and 2.

    See the visualization documentation for more information about legend and valid legend locations.

  • **kwargs –

    • time_vector

    • plot_function

    • title

    • xlabel

    • ylabel

    • xlim

    • ylim

    • grid

    • grid_color

    • grid_linestyle

    • grid_linewidth

    • prop_cycle

    • color

    • linestyle

    • linewidth

    • marker

    • markersize

    • legend_ncol

    • annotate_time_points

    • annotate_time_points_color

    • annotate_time_points_marker

    • annotate_time_points_markersize

    • annotate_time_points_labels

    • annotate_time_points_legend

    • deviation

    • deviation_zero_centered

    • deviation_normalization

    See visualization documentation for more information on optional kwargs.

Returns

ax – The Axes instance containing the newly created plot.

Return type

matplotlib.axes.Axes

mass.visualization.phase_portraits.plot_ensemble_phase_portrait(mass_solution_list, x, y, ax=None, legend=None, **kwargs)[source]

Plot a phase portrait for an ensemble of class:~.MassSolution objects.

The plotted lines represent the mean for the values of a particular solution specified in observable.

Accepted kwargs are passed onto various matplotlib methods utilized in the function. See the visualization module documentation for more detailed information about the possible kwargs.

Notes

Parameters

  • mass_solution_list (iterable) – An iterable of MassSolution objects containing the time-dependent solutions to be plotted.

  • x (mass object or its string identifier) – The string identifier of a mass object or the object itself that corresponds to the key for the desired solution in the MassSolution for the x-axis of the phase portrait.

  • y (mass object or its string identifier) – The string identifier of a mass object or the object itself that corresponds to the key for the desired solution in the MassSolution for the y-axis of the phase portrait.

  • ax (matplotlib.axes.Axes, None) – An Axes instance to plot the data on. If None then the current axes instance is used.

  • legend (iterable, str, int) –

    There are three possible input formats for the legend:

    1. An iterable of legend labels as strings.

    2. A str representing the location of the legend, or an int between 0 and 14 (inclusive) corresponding to the legend location.

    3. An iterable of the format (labels, loc) to set both the legend labels and location, where labels and loc follows the format specified in 1 and 2.

    See the visualization documentation for more information about legend and valid legend locations.

  • **kwargs –

    • time_vector

    • plot_function

    • title

    • xlabel

    • ylabel

    • xlim

    • ylim

    • grid

    • grid_color

    • grid_linestyle

    • grid_linewidth

    • prop_cycle

    • color

    • linestyle

    • linewidth

    • marker

    • markersize

    • legend_ncol

    • annotate_time_points

    • annotate_time_points_color

    • annotate_time_points_marker

    • annotate_time_points_markersize

    • annotate_time_points_labels

    • annotate_time_points_legend

    • deviation

    • deviation_zero_centered

    • deviation_normalization

    See visualization documentation for more information on optional kwargs.

Returns

ax – The Axes instance containing the newly created plot.

Return type

matplotlib.axes.Axes

mass.visualization.phase_portraits.plot_tiled_phase_portraits(mass_solution, observable=None, ax=None, plot_tile_placement='all', additional_data=None, **kwargs)[source]

Plot phase portraits of solutions in a given MassSolution.

Accepted kwargs are passed onto various matplotlib methods in utilized in the function. See the visualization module documentation for more detailed information about the possible kwargs.

Notes

  • To prevent any changes to the original MassSolution, a copy of the MassSolution will be created and used.

  • i and j represent the number of rows and columns, respectively.

Parameters

  • mass_solution (MassSolution) – The MassSolution containing the time-dependent solutions to be plotted.

  • observable (iterable) – An iterable containing string identifiers of the mass objects or the objects themselves that correspond to the keys for the desired solutions in the MassSolution.

  • ax (matplotlib.axes.Axes, None) – An Axes instance to plot the data on. If None then the current axes instance is used.

  • plot_tile_placement (str) –

    A string representing the location to place the tiles containing phase portrait plots. Must be one of the following:

    • "lower" to place plot tiles on the lower left triangular section (i < j) on the figure tiles.

    • "upper" to place plot tiles on the upper right triangular section (i > j) on the figure tiles.

    • all to place plot tiles on the lower left triangular section (i < j) AND on the upper right triangular section (i > j) on the figure tiles.

  • additional_data (array_like, None) – A matrix of shape (N, N) where N_obs is the number of observables provided, or the number of keys in the MassSolution if observable=None. The value at (i, j) of the matrix must correspond to the empty tile that the data should be displayed on. All other values are ignored. If None then no data will be displayed and tiles will be left empty.

  • **kwargs –

    • time_vector

    • plot_function

    • title

    • xlim

    • ylim

    • grid

    • grid_color

    • grid_linestyle

    • grid_linewidth

    • prop_cycle

    • color

    • linestyle

    • linewidth

    • marker

    • markersize

    • annotate_time_points

    • annotate_time_points_color

    • annotate_time_points_marker

    • annotate_time_points_markersize

    • annotate_time_points_legend

    • annotate_time_points_zorder

    • tile_ticks_on

    • tile_xlabel_fontdict

    • tile_ylabel_fontdict

    • data_tile_fontsize

    • data_tile_color

    • diag_tile_color

    • empty_tile_color

    See visualization documentation for more information on optional kwargs.

Returns

ax – The Axes instance containing the newly created plot.

Return type

matplotlib.axes.Axes

mass.visualization.phase_portraits.get_phase_portrait_default_kwargs(function_name)[source]

Get default kwargs for plotting functions in phase_portraits.

Parameters

function_name (str) –

The name of the plotting function to get the kwargs for. Valid values include the following:

  • "plot_phase_portrait"

  • "plot_tiled_phase_portraits"

Returns

Default kwarg values for the given function_name.

Return type

dict