control.time_response_plot

control.time_response_plot(data, *fmt, ax=None, plot_inputs=None, plot_outputs=True, transpose=False, overlay_traces=False, overlay_signals=False, add_initial_zero=True, label=None, trace_labels=None, title=None, relabel=True, **kwargs)

Plot the time response of an input/output system.

This function creates a standard set of plots for the input/output response of a system, with the data provided via a TimeResponseData object, which is the standard output for python-control simulation functions.

Parameters

dataTimeResponseData

Data to be plotted.

plot_inputsbool or str, optional

Sets how and where to plot the inputs:

• False: don’t plot the inputs

• None: use value from time response data (default)

• ‘overlay’: plot inputs overlaid with outputs

• True: plot the inputs on their own axes

plot_outputsbool, optional

If False, suppress plotting of the outputs.

overlay_tracesbool, optional

If set to True, combine all traces onto a single row instead of plotting a separate row for each trace.

overlay_signalsbool, optional

If set to True, combine all input and output signals onto a single plot (for each).

sharex, shareystr or bool, optional

Determine whether and how x- and y-axis limits are shared between subplots. Can be set set to ‘row’ to share across all subplots in a row, ‘col’ to set across all subplots in a column, ‘all’ to share across all subplots, or False to allow independent limits. Default values are False for sharex' and 'col' for `sharey, and can be set using config.defaults['timeplot.sharex'] and config.defaults['timeplot.sharey'].

transposebool, optional

If transpose is False (default), signals are plotted from top to bottom, starting with outputs (if plotted) and then inputs. Multi-trace plots are stacked horizontally. If transpose is True, signals are plotted from left to right, starting with the inputs (if plotted) and then the outputs. Multi-trace responses are stacked vertically.

*fmtmatplotlib.pyplot.plot format string, optional

Passed to matplotlib as the format string for all lines in the plot.

**kwargsmatplotlib.pyplot.plot keyword properties, optional

Additional keywords passed to matplotlib to specify line properties.

Returns

cpltControlPlot object

Object containing the data that were plotted. See ControlPlot for more detailed information.

cplt.lines2D array of matplotlib.lines.Line2D

Array containing information on each line in the plot. The shape of the array matches the subplots shape and the value of the array is a list of Line2D objects in that subplot.

cplt.axes2D array of matplotlib.axes.Axes

Axes for each subplot.

cplt.figurematplotlib.figure.Figure

Figure containing the plot.

cplt.legend2D array of matplotlib.legend.Legend

Legend object(s) contained in the plot.

Other Parameters

add_initial_zerobool

Add an initial point of zero at the first time point for all inputs with type ‘step’. Default is True.

axarray of matplotlib.axes.Axes, optional

The matplotlib axes to draw the figure on. If not specified, the axes for the current figure are used or, if there is no current figure with the correct number and shape of axes, a new figure is created. The shape of the array must match the shape of the plotted data.

input_propsarray of dict

List of line properties to use when plotting combined inputs. The default values are set by config.defaults['timeplot.input_props'].

labelstr or array_like of str, optional

If present, replace automatically generated label(s) with the given label(s). If more than one line is being generated, an array of labels should be provided with label[trace, :, 0] representing the output labels and label[trace, :, 1] representing the input labels.

legend_maparray of str, optional

Location of the legend for multi-axes plots. Specifies an array of legend location strings matching the shape of the subplots, with each entry being either None (for no legend) or a legend location string (see legend).

legend_locint or str, optional

Include a legend in the given location. Default is ‘center right’, with no legend for a single response. Use False to suppress legend.

output_propsarray of dict, optional

List of line properties to use when plotting combined outputs. The default values are set by config.defaults['timeplot.output_props'].

rcParamsdict

Override the default parameters used for generating plots. Default is set by config.defaults['ctrlplot.rcParams'].

relabelbool, optional

(deprecated) By default, existing figures and axes are relabeled when new data are added. If set to False, just plot new data on existing axes.

show_legendbool, optional

Force legend to be shown if True or hidden if False. If None, then show legend when there is more than one line on an axis or legend_loc or legend_map has been specified.

time_labelstr, optional

Label to use for the time axis.

titlestr, optional

Set the title of the plot. Defaults to plot type and system name(s).

trace_labelslist of str, optional

Replace the default trace labels with the given labels.

trace_propsarray of dict

List of line properties to use when plotting multiple traces. The default values are set by config.defaults['timeplot.trace_props'].

Notes

A new figure will be generated if there is no current figure or the current figure has an incompatible number of axes. To force the creation of a new figures, use plt.figure. To reuse a portion of an existing figure, use the ax keyword.

The line properties (color, linestyle, etc) can be set for the entire plot using the fmt and/or kwargs parameter, which are passed on to matplotlib. When combining signals or traces, the input_props, output_props, and trace_props parameters can be used to pass a list of dictionaries containing the line properties to use. These input/output properties are combined with the trace properties and finally the kwarg properties to determine the final line properties.

The default plot properties, such as font sizes, can be set using config.defaults[''timeplot.rcParams'].