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)[source]

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

  • data (TimeResponseData) – Data to be plotted.

  • plot_inputs (bool 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_outputs (bool, optional) – If False, suppress plotting of the outputs.

  • overlay_traces (bool, optional) – If set to True, combine all traces onto a single row instead of plotting a separate row for each trace.

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

  • sharex (str 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’].

  • sharey (str 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’].

  • transpose (bool, 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.

  • *fmt (matplotlib.pyplot.plot() format string, optional) – Passed to matplotlib as the format string for all lines in the plot.

  • **kwargs (matplotlib.pyplot.plot() keyword properties, optional) – Additional keywords passed to matplotlib to specify line properties.

  • add_initial_zero (bool) – Add an initial point of zero at the first time point for all inputs with type ‘step’. Default is True.

  • ax (array 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_props (array of dicts) – List of line properties to use when plotting combined inputs. The default values are set by config.defaults[‘timeplot.input_props’].

  • label (str 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_map (array 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_loc (int 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_props (array of dicts, optional) – List of line properties to use when plotting combined outputs. The default values are set by config.defaults[‘timeplot.output_props’].

  • rcParams (dict) – Override the default parameters used for generating plots. Default is set by config.default[‘ctrlplot.rcParams’].

  • relabel (bool, 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_legend (bool, 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_label (str, optional) – Label to use for the time axis.

  • title (str, optional) – Set the title of the plot. Defaults to plot type and system name(s).

  • trace_labels (list of str, optional) – Replace the default trace labels with the given labels.

  • trace_props (array of dicts) – List of line properties to use when plotting combined outputs. The default values are set by config.defaults[‘timeplot.trace_props’].

Returns

cplt –

Object containing the data that were plotted:

  • cplt.lines: Array of matplotlib.lines.Line2D objects for 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.axes: 2D array of matplotlib.axes.Axes for the plot.

  • cplt.figure: matplotlib.figure.Figure containing the plot.

  • cplt.legend: legend object(s) contained in the plot

See ControlPlot for more detailed information.

Return type

ControlPlot object

Notes

  1. 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.

  2. 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.

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