PlotlyHelper – Reference Guide

This guide is for versions 1.0 Release Candidate 0+

Source code

Class PlotlyHelper

    Static class to assist in the use of the plotly library
    
nameargumentsreturns
get_default_colorsn :int[int]
        Return a list of n colors, specified by their standard plotly names;
        meant for situations when 1 or more default colors are needed.

        The choice of default colors is hardwired in this function.

        :param n:   Desired number of default colors
        :return:
        
nameargumentsreturns
plot_curvesx, y, title="", range_x=None, x_label="", y_label="", curve_labels=None, legend_title=None, colors=None, show=Falsepgo.Figure
        Plot one or more 2D curves

        :param x:           A Numpy array, with the (common) x-axis values
        :param y:           Either a Numpy array, or a list/tuple of them, with the y-axis values of the curve(s)
        :param title:       [OPTIONAL] Title to use for the overall plot
        :param range_x:     [OPTIONAL] list of the form [t_start, t_end], to initially only show a part of the timeline.
                                Note: it's still possible to zoom out, and see the excluded portion
        :param x_label:     [OPTIONAL] Caption to use for the x-axis
        :param y_label:     [OPTIONAL] Caption to use for the y-axis
        :param curve_labels:[OPTIONAL] String, or list of strings.
                                Label(s) to use for the various curves in the legend and in the hover boxes.
                                If missing, and there's only 1 curve, the legend box won't be shown
        :param legend_title:[OPTIONAL] String to show at the top of the legend box.
                                Ignored if curve_labels wasn't set.
                                If not provided, and the legend box is shown, it will appear as "variable"
        :param colors:      [OPTIONAL] Either a single color (string with standard plotly name, such as "red"),
                                or list of names to use, in order; if None, then use the hardwired defaults
        :param show:        If True, the plot will be shown
                                Note: in JupyterLab, simply returning a plot object (without assigning it to a variable)
                                leads to it being automatically shown

        :return:            A plotly "Figure" object
        
nameargumentsreturns
plot_pandasdf :pd.DataFrame, x_var="SYSTEM TIME", fields=None, colors=None, title=None, title_prefix=None, range_x=None, range_y=None, x_label=None, y_label="Y", legend_header="Plot", vertical_lines_to_add=None, show_intervals=False, show=Falsepgo.Figure
        Using plotly, draw line plots from the values in the given dataframe.

        Note: if this plot is to be later combined with others, use PlotlyHelper.combine_plots()

        :param df:              Pandas dataframe with the data for the plot
        :param x_var:           Name of column with independent variable for the x-axis
        :param fields:          Name, or list of names, of the dataframe columns whose values are to be plotted;
                                    if a list is passed, also display a figure legend;
                                    if None, then display all columns except the one that is declared as the independent variable
        :param colors:          (OPTIONAL) Either a single color (string with standard plotly name, such as "red"),
                                    or list of names to use, in order; if None, then the hardwired default colors are used
        :param title:           (OPTIONAL) Title for the plot
        :param title_prefix:    (OPTIONAL) Strint to prefixed (automatically followed by " 
") to the title :param range_x: (OPTIONAL) list of the form [t_start, t_end], to initially show only a part of the timeline. Note: it's still possible to zoom out, and see the excluded portion :param range_y: (OPTIONAL) list of the form [y_min, y_max], to initially show only a part of the y values. Note: it's still possible to zoom out, and see the excluded portion :param x_label: (OPTIONAL) Caption to use for the x-axis :param y_label: (OPTIONAL) Caption to use for the y-axis. Default: "Y" :param legend_header: (OPTIONAL) Caption to use at the top of the legend box. Only applicable if more than 1 curve is being shown. :param vertical_lines_to_add: (OPTIONAL) Ignored if the argument `show_intervals` is specified. Value, or list, or tuple, or Numpy array, or Pandas series, of x-coordinate(s) at which to draw thin vertical dotted gray lines. If the number of vertical line is so large as to overwhelm the plot, only a sample of them is shown. Note that vertical lines, if requested, go into the plot's "layout"; as a result they might not appear if this plot is later combined with another one. :param show_intervals: (OPTIONAL) If True, it over-rides any value passed to the `vertical_lines` argument, and draws thin vertical dotted gray lines at all the x-coords of the data points in the saved history data; also, it adds a comment to the title. :param show: If True, the plot will be shown Note: on JupyterLab, simply returning a plot object (without assigning it to a variable) leads to it being automatically shown :return: A plotly "Figure" object
nameargumentsreturns
combine_plotsfig_list :Union[list, tuple], title="", x_label=None, y_label=None, xrange=None, legend_title=None, curve_labels=None, show=Falsepgo.Figure
        Combine together several existing plotly plots into a single one (with combined axes)

        EXAMPLE:
                    from life123 import PlotlyHelper
                    p1 = PlotlyHelper.plot_pandas(various args, show=False)
                    p2 = PlotlyHelper.plot_pandas(various args, show=False)
                    PlotlyHelper.combine_plots([p1, p2], other optional args)

        :param fig_list:    List or tuple of plotly "Figure" objects (as returned by several functions)
        :param title:       [OPTIONAL] The title to use for the overall plot
        :param x_label:     [OPTIONAL] Caption to use for the x-axis; if not specified, use that of the 1st plot
        :param y_label:     [OPTIONAL] Caption to use for the y-axis; if not specified, use that of the 1st plot
        :param xrange:      [OPTIONAL] list of the form [t_start, t_end], to initially only show a part of the timeline.
                                Note: it's still possible to zoom out, and see the excluded portion
        :param legend_title:[OPTIONAL] String to show at the top of the legend box
        :param curve_labels:[OPTIONAL] List of labels to use for the various curves in the legend
                                and in the hover boxes; if not specified, use the titles of the individual plots
        :param show:        If True, the plot will be shown
                                Note: on JupyterLab, simply returning a plot object (without assigning it to a variable)
                                      leads to it being automatically shown
        :return:            A plotly "Figure" object for the combined plot
        
nameargumentsreturns
combine_in_vertical_gridfig1, fig2, title1 :str, title2 :str, title_combined :str, height=900pgo.Figure
        Combine into a vertical grid 2 plotly graph objects (now treated as subplots)

        :param fig1:
        :param fig2:
        :param title1:
        :param title2:
        :param title_combined:
        :param height           [OPTIONAL] The overall height of the combined plots
        :return:                A combined plot (a plotly "figure" object)