Python API#

class rallyplot.Plotter(width=800, height=600, color_mode='light', anti_aliasing_samples=0, axis_tick_label_font='arial', axis_tick_label_font_size=12, axis_right=True, width_margin_size=50, height_margin_size=25)[source]#

Methods

add_linked_subplot(height_as_proportion)

Add a linked subplot to the subplot.

add_subplot(row, col, row_span, col_span)

Add a new subplot to the figure.

bar(y[, dates, linked_subplot_idx, color, ...])

Add a bar plot to the linked subplot.

candlestick(open, high, low, close[, dates, ...])

Add a candlestick plot to the linked subplot.

candlestick_from_df(df[, dates, ...])

Add a candlestick plot to the linked subplot.

finish()

Ensure c++ side is completely cleared.

line(y[, dates, linked_subplot_idx, color, ...])

Add a line plot to the linked subplot.

link_y_axes([on])

Link the y-axis across all linked subplots.

pin_y_axis([on, linked_subplot_idx])

Fix the y-axis zoom to the minimum and maximum values of the plot currently in view.

resize_linked_subplots(y_heights)

Resize the linked subplots.

scatter(x, y[, linked_subplot_idx, shape, ...])

Add a scatter plot to the linked subplot.

set_active_subplot(row, col)

Set the 'active' subplot to the subplot at index row, col.

set_background_color(color)

Set the background color for the subplot.

set_camera_settings([key_zoom_speed, ...])

Set the camera settings that control pan and zooming.

set_crosshair_settings([on, font, ...])

Settings for the crosshair that follows the mouse over the plot.

set_draw_line_settings([linewidth, color])

Control how lines drawn on the plot are displayed.

set_hover_value_settings([display_mode, ...])

Control how the pop-up label that appears on mouse hover over plot is displayed.

set_legend(label_names[, ...])

Set a legend on a linked subplot.

set_title(text[, font, weight, font_size, color])

Set a title on the subplot.

set_x_axis_settings([min_num_ticks, ...])

Control how the x-axis is displayed.

set_x_label(text[, font, weight, font_size, ...])

Set a label on the x-axis for the subplot.

set_x_limits(min, max)

Set the minimum and maximum values for the x-axis.

set_y_axis_settings([min_num_ticks, ...])

Control how the y-axis is displayed.

set_y_label(text[, font, weight, font_size, ...])

Set a label on the y-axis for the subplot.

set_y_limits([min, max, linked_subplot_idx])

Set minimum and / or maximum values for the y-axis.

start()

Start the event loop to display and interact with plots.

is_number
Parameters:

  • width (int)

  • height (int)

  • color_mode (Literal['light', 'dark'])

  • anti_aliasing_samples (int)

  • axis_tick_label_font (FontType)

  • axis_tick_label_font_size (int)

  • axis_right (bool)

  • width_margin_size (int)

  • height_margin_size (int)

start()[source]#

Start the event loop to display and interact with plots.

finish()[source]#

Ensure c++ side is completely cleared.

This ensures you can the below and avoid seg faults.: plotter = Plotter() plotter.finish() plotter = Plotter()

set_background_color(color)[source]#

Set the background color for the subplot.

color

Array of length 1 to 4 setting RGBA color values. Missing values are set to 0.0f for color and 1.0f for alpha. e.g. {0.1f, 0.2f} sets {0.1f, 0.2f, 0.0f, 1.0f}.

Parameters:

color (list | tuple | numpy.ndarray)

set_camera_settings(key_zoom_speed=2.5, mouse_zoom_speed=0.004, key_pan_speed=0.35, mouse_pan_speed=0.7, wheel_speed=0.002, lock_most_recent_date=False, fix_zoom_at_edge=False)[source]#

Set the camera settings that control pan and zooming.

Parameters:

  • key_zoom_speed (float) – Controls the speed of zoom by key-press (Q, E, Z, C).

  • mouse_zoom_speed (float) – Controls the speed of zoom by mouse move (right-click).

  • key_pan_speed (float) – Controls the speed of panning by key-press (A, D, W, X).

  • mouse_pan_speed (float) – Controls the speed of panning by mouse move (left-click).

  • wheel_speed (float) – Controls the speed of zoom by the mouse wheel.

  • lock_most_recent_date (bool) – If true, the axis zoom / pan is locked to the largest x-axis position.

  • fix_zoom_at_edge (bool) – All zooming will be fixed to the y-axis (right or left depending on PlotterArgs.axisRight).

set_crosshair_settings(on=True, font='arial', font_size=10, linewidth=1.0, line_color=None, background_color=None, font_color=None)[source]#

Settings for the crosshair that follows the mouse over the plot.

Parameters:

  • on (bool) – If False, the crosshair is turned off.

  • font (Literal['consola', 'arial']) – Font of the label that appears in the axis.

  • font_size (int) – Font size of the label that appears in the axis.

  • linewidth (float) – Crosshair line width.

  • line_color (Union[list, tuple, ndarray, None]) – Crosshair line color (array-like, length 1-4, RGBA). Default is based on ColorMode.

  • background_color (Union[list, tuple, ndarray, None]) – Background color (array-like, length 1-4, RGBA) of the label that appears in the axis. Default is based on ColorMode.

  • font_color (Union[list, tuple, ndarray, None]) – Color (array-like, length 1-4, RGBA) of the font that appears in the axis. Default is based on ColorMode.

set_draw_line_settings(linewidth=0.25, color=None)[source]#

Control how lines drawn on the plot are displayed.

Parameters:

  • linewidth (float) – Width of the drawn line.

  • color (Union[list, tuple, ndarray, None]) – Color (array-like, length 1-4, RGBA) of the drawn line. Default blue.

set_hover_value_settings(display_mode='always_show', font='arial', font_size=10, font_color=None, background_color=None, border_color=None)[source]#

Control how the pop-up label that appears on mouse hover over plot is displayed.

Parameters:

  • display_mode (Literal['always_show', 'only_under_mouse', 'off']) – “always_show” will always display the pop-up. “only_under_mouse” will show only when mouse is hovered over the plot. Otherwise, “off”.

  • font (Literal['consola', 'arial']) – Font of the hover label.

  • font_size (int) – Font size of the hover label.

  • font_color (Union[list, tuple, ndarray, None]) – Font color (array-like, length 1-4, RGBA) of the hover label. Default is based on ColorMode.

  • background_color (Union[list, tuple, ndarray, None]) – Background color (array-like, length 1-4, RGBA) of the hover label. Default is based on ColorMode.

  • border_color (Union[list, tuple, ndarray, None]) – Border color (array-like, length 1-4, RGBA) of the hover label. Default is based on ColorMode.

set_x_axis_settings(min_num_ticks=6, max_num_ticks=12, init_num_ticks=8, show_ticks=True, tick_linewidth=1.0, tick_size=0.025, show_gridline=True, gridline_width=0.4, axis_linewidth=1.0, gridline_color=None, axis_color=None, font_color=None, linked_subplot_idx=None)[source]#

Control how the x-axis is displayed.

Parameters:

  • min_num_ticks (int) – Minimum number of ticks that should be displayed. Should be a multiple of 2. If too close to max_num_ticks, a flickering artifact may be observed.

  • max_num_ticks (int) – Maximum number of ticks that should be displayed. Should be a multiple of 2. If too close to min_num_ticks, a flickering artifact may be observed.

  • init_num_ticks (int) – Initial number of ticks, must be a multiple of two and between min / max num ticks.

  • show_ticks (bool) – If true, small tick-lines will be displayed.

  • tick_linewidth (float) – Width of the tick line. May have no effect on some GPUs.

  • tick_size (float) – Length of the tick line.

  • show_gridline (bool) – If true, grid lines (that extend the tick line across the plot) are displayed.

  • gridline_width (float) – Width of the grid line. May have no effect on some GPUs.

  • axis_linewidth (float) – Width of the axis line. May have no effect on some GPUs.

  • gridline_color (Union[list, tuple, ndarray, None]) – Grid line (array-like, length 1-4, RGBA) color, if None uses the default according to ColorMode.

  • axis_color (Union[list, tuple, ndarray, None]) – Axis color (array-like, length 1-4, RGBA) , if None uses the default according to ColorMode.

  • font_color (Union[list, tuple, ndarray, None]) – Axis tick label color(array-like, length 1-4, RGBA), if None uses the default according to ColorMode.

  • linked_subplot_idx (int | None) – The linked subplot on which to set the settings. If None, will be applied to all linked subplots.

set_y_axis_settings(min_num_ticks=6, max_num_ticks=12, init_num_ticks=12, show_ticks=False, tick_linewidth=1.0, tick_size=0.025, show_gridline=True, gridline_width=0.4, axis_linewidth=1.0, tick_label_decimal_places=2, gridline_color=None, axis_color=None, font_color=None, linked_subplot_idx=None)[source]#

Control how the y-axis is displayed.

Parameters:

  • min_num_ticks (int) – Minimum number of ticks that should be displayed. Should be a multiple of 2. If too close to max_num_ticks, a flickering artifact may be observed.

  • max_num_ticks (int) – Maximum number of ticks that should be displayed. Should be a multiple of 2. If too close to min_num_ticks, a flickering artifact may be observed.

  • init_num_ticks (int) – Initial number of ticks, must be a multiple of two and between min / max num ticks.

  • show_ticks (bool) – If true, small tick-lines will be displayed.

  • tick_linewidth (float) – Width of the tick line. May have no effect on some GPUs.

  • tick_size (float) – Length of the tick line.

  • show_gridline (bool) – If true, grid lines (that extend the tick line across the plot) are displayed.

  • gridline_width (float) – Width of the grid line. May have no effect on some GPUs.

  • axis_linewidth (float) – Width of the axis line. May have no effect on some GPUs.

  • tick_label_decimal_places (int) – Controls the number of decimal places for the y-axis tick labels.

  • gridline_color (Union[list, tuple, ndarray, None]) – Grid line color, if None uses the default according to ColorMode.

  • axis_color (Union[list, tuple, ndarray, None]) – Axis color (array-like, length 1-4, RGBA) , if None uses the default according to ColorMode.

  • font_color (Union[list, tuple, ndarray, None]) – Axis tick label color (array-like, length 1-4, RGBA) , if None uses the default according to ColorMode.

  • linked_subplot_idx (int | None) – The linked subplot on which to set the settings. If None, will be applied to all linked subplots.

pin_y_axis(on=True, linked_subplot_idx=None)[source]#

Fix the y-axis zoom to the minimum and maximum values of the plot currently in view.

Parameters:

  • on (bool) – If False, y-axis is unpinned and can be zoomed freely.

  • linked_subplot_idx (int | None) – The linked subplot to pin. If None, will be applied to all linked subplots.

set_y_limits(min=None, max=None, linked_subplot_idx=None)[source]#

Set minimum and / or maximum values for the y-axis.

Only has an effect if pin_y_axis() is set to False.

Parameters:

  • min (float | None) – Minimum value for the y-axis, if None is set to -inf.

  • max (float | None) – Maximum value for the y-axis, if None is set to inf.

  • linked_subplot_idx (int | None) – The linked subplot on which to limit the y-axis view. If None, will be applied to all linked subplots.

set_x_limits(min, max)[source]#

Set the minimum and maximum values for the x-axis.

Must be the same type as the x-axis data. x-axis values should be unique.

Parameters:

  • min (int | str | datetime | None) – Minimum value for the x-axis, if None is set to the minimum x value. Must be the same type as dates used for the plot.

  • max (int | str | datetime | None) – Maximum value for the x-axis, if None is set to the maximum x value. Must be the same type as dates used for the plot.

Link the y-axis across all linked subplots.

on

If true, zooming on one plot will zoom on all linked subplots.

Parameters:

on (bool)

set_y_label(text, font='arial', weight='bold', font_size=12, color=None)[source]#

Set a label on the y-axis for the subplot.

Parameters:

  • text (str) – Text to set as the label.

  • font (Literal['consola', 'arial']) – Font of the label.

  • weight (Literal['thin', 'extralight', 'light', 'normal', 'regular', 'medium', 'demibold', 'bold', 'extrabold', 'black']) – Weight of the label font.

  • font_size (int) – Point size of the label font.

  • color (Union[list, tuple, ndarray, None]) – Color (array-like, length 1-4, RGBA) of the label text.

set_x_label(text, font='arial', weight='bold', font_size=12, color=None)[source]#

Set a label on the x-axis for the subplot.

Parameters:

  • text (str) – Text to set as the label.

  • font (Literal['consola', 'arial']) – Font of the label.

  • weight (Literal['thin', 'extralight', 'light', 'normal', 'regular', 'medium', 'demibold', 'bold', 'extrabold', 'black']) – Weight of the label font.

  • font_size (int) – Point size of the label font.

  • color (Union[list, tuple, ndarray, None]) – Color (array-like, length 1-4, RGBA) of the label text.

set_title(text, font='arial', weight='extrabold', font_size=12, color=None)[source]#

Set a title on the subplot.

Parameters:

  • text (str) – Text to set as the title.

  • font (Literal['consola', 'arial']) – Font of the title.

  • weight (Literal['thin', 'extralight', 'light', 'normal', 'regular', 'medium', 'demibold', 'bold', 'extrabold', 'black']) – Weight of the title font.

  • font_size (int) – Point size of the title font.

  • color (Union[list, tuple, ndarray, None]) – Color (array-like, length 1-4, RGBA) of the title text

set_legend(label_names, linked_subplot_idx=-1, legend_size_scalar=1.0, x_box_pad=10.0, y_box_pad=2.0, line_width=35.0, line_height=7.5, x_line_pad_left=5.0, x_line_pad_right=5.0, x_text_pad_right=2.0, y_inter_item_pad=5.0, y_item_pad=2.0, font='arial', font_size=15, font_color=None, box_color=(1.0, 1.0, 1.0, 0.0))[source]#

Set a legend on a linked subplot.

Parameters:

  • label_names (list[str]) – A list of label names for the legend. Must be the same length as the number of plots in the linked subplot.

  • linked_subplot_idx (int) – Linked subplot on which to add the legend.

  • legend_size_scalar (float) – A convenient scalar by which to increase or decrease the legend size. Other settings add further customization to the legend size.

  • x_box_pad (float) – X position of the legend expressed as distance from the right of the plot.

  • y_box_pad (float) – Y position of the legend expressed as distance from the top of the plot.

  • line_width (float) – Width of the legend item colored lines.

  • line_height (float) – Height of the legend items colored lines.

  • x_line_pad_left (float) – Padding between the edge of the legend box and the text (left)

  • x_line_pad_right (float) – Padding between the legend item colored line (left) i.e. between the line text.

  • x_text_pad_right (float) – Padding between the text (right) i.e. the text and the item colored line.

  • y_inter_item_pad (float) – Vertical padding between legend items.

  • y_item_pad (float) – Padding between the legend items (top and bottom) and the legend box.

  • font (Literal['consola', 'arial']) – Font for the legend item text.

  • font_size (int) – Font size for the legend item text.

  • font_color (Union[list, tuple, ndarray, None]) – Font color (array-like, length 1-4, RGBA) for the legend item text.

  • box_color (Union[list, tuple, ndarray]) – Background color (array-like, length 1-4, RGBA) for the legend box.

add_subplot(row, col, row_span, col_span)[source]#

Add a new subplot to the figure.

After adding, all calls on Plotter will operate on the added subplot. To change, use set_active_subplot.

Specify the row and col index at which to add the subplot, as well as how many rows and columns it spans. For example, to add a second subplot when there is 1 existing plot: (0, 1, 1, 1) will add a new subplot to the right of the existing plot. (1, 0, 1, 1) will add the new subplot underneath the existing plot.

Note that a ‘subplot’ is a different entity to a ‘linked subplot’. All linked subplots share the x-axis, while a subplot is a completely separate set of plots.

Parameters:

  • row (int) – Index of the row in which to add the subplot.

  • col (int) – Index of the column in which to add the subplot.

  • row_span (int) – Number of rows the subplot will span.

  • col_span (int) – Number of columns the subplot will span.

set_active_subplot(row, col)[source]#

Set the ‘active’ subplot to the subplot at index row, col.

All calls to Plotter e.g. Plotter.candlestick() operate on the active subplot. Row, Col should be the top-left corner of the subplot in the case it is spanned.

Parameters:

  • row (int) – Row of the subplot to set active

  • col (int) – Column of the subplot to set active

resize_linked_subplots(y_heights)[source]#

Resize the linked subplots.

Parameters:

y_heights (Union[list, tuple, ndarray]) – A vector of height proportions. Length must equal the number of linked subplots on the plot and must sum to 1.

add_linked_subplot(height_as_proportion)[source]#

Add a linked subplot to the subplot.

A ‘linked subplot’ is a subplot that shares the x-axis with the current plot. This is in contrast to a ‘subplot’ which is an entirely separate plot.

Parameters:

height_as_proportion (float) – The height of the new linked subplot as a proportion of the plot (in range [0, 1]).

candlestick_from_df(df, dates=None, linked_subplot_idx=-1, up_color=(0.0314, 0.6, 0.506, 1.0), down_color=(0.957, 0.204, 0.266, 1.0), mode='no_caps', candle_width_ratio=0.75, cap_width_ratio=0.5, line_mode_linewidth=1.0, line_mode_miter_limit=3.0, line_mode_basic_line=False)[source]#

Add a candlestick plot to the linked subplot.

Parameters:

  • df (DataFrame) – A Pandas dataframe either columns “Open”, “High”, “Low”, “Close” (all lowercase accepted e.g. “open”).

  • dates (Union[list[str], list[datetime], Series, DatetimeIndex, None]) – A list of string (labels) or datetime (must be UTC) to use as x-axis labels. If None, index will be displayed. If pd.Series, it will be converted to a list internally.

  • linked_subplot_idx (int) – The index of the linked subplot on which to plot the candlesticks. By default, it is the most recently added linked subplot.

  • up_color (Union[list, tuple, ndarray]) – Color (array-like, length 1-4, RGBA) for candles when close price is higher than open price.

  • down_color (Union[list, tuple, ndarray]) – Color (array-like, length 1-4, RGBA) for candles when open price is lower than close price.

  • mode (Literal['full', 'no_caps', 'body_only', 'line_open', 'line_closed']) – Control how candles are displayed (see CandlestickMode).

  • candle_width_ratio (float) – Ratio between candle and gap width, a float between (0, 1] e.g. 1 is no space between candles.

  • cap_width_ratio (float) – Ratio between candle and cap width, a double between (0, 1] e.g. 1 the cap is the width of the candle.

  • line_mode_linewidth (float) – Line width for open-line and close-line mode for the candlestick plot.

  • line_mode_miter_limit (float) – Miter limit controls the maximum line-segment connection length, for open-line and close-line mode.

  • line_mode_basic_line (bool) – If true, a simple line plot with fixd width is used (width and miterLimit have no effect). This is much faster.

candlestick(open, high, low, close, dates=None, linked_subplot_idx=-1, up_color=(0.0314, 0.6, 0.506, 1.0), down_color=(0.957, 0.204, 0.266, 1.0), mode='no_caps', candle_width_ratio=0.75, cap_width_ratio=0.5, line_mode_linewidth=1.0, line_mode_miter_limit=3.0, line_mode_basic_line=False)[source]#

Add a candlestick plot to the linked subplot.

Parameters:

  • open (ndarray) – Vector of candle open prices.

  • high (ndarray) – Vector of candle high prices.

  • low (ndarray) – Vector of candle low prices.

  • close (ndarray) – Vector of candle close prices.

  • dates (Union[list[str], list[datetime], Series, DatetimeIndex, None]) – A list of string (labels) or datetime (must be UTC) to use as x-axis labels. If None, index will be displayed. If pd.Series, it will be converted to a list internally.

  • linked_subplot_idx (int) – The index of the linked subplot on which to plot the candlesticks. By default, it is the most recently added linked subplot.

  • up_color (Union[list, tuple, ndarray]) – Color (array-like, length 1-4, RGBA) for candles when close price is higher than open price.

  • down_color (Union[list, tuple, ndarray]) – Color (array-like, length 1-4, RGBA) for candles when open price is lower than close price.

  • mode (Literal['full', 'no_caps', 'body_only', 'line_open', 'line_closed']) – Control how candles are displayed (see CandlestickMode).

  • candle_width_ratio (float) – Ratio between candle and gap width, a float between (0, 1] e.g. 1 is no space between candles.

  • cap_width_ratio (float) – Ratio between candle and cap width, a double between (0, 1] e.g. 1 the cap is the width of the candle.

  • line_mode_linewidth (float) – Line width for open-line and close-line mode for the candlestick plot.

  • line_mode_miter_limit (float) – Miter limit controls the maximum line-segment connection length, for open-line and close-line mode.

  • line_mode_basic_line (bool) – If true, a simple line plot with fixd width is used (width and miterLimit have no effect). This is much faster.

line(y, dates=None, linked_subplot_idx=-1, color=(0.5, 0.5, 0.5, 1.0), width=0.5, miter_limit=3.0, basic_line=False)[source]#

Add a line plot to the linked subplot.

Parameters:

  • y (np.ndarray | pd.Series) – Numpy array of float datapoints to plot.

  • dates (Dates | None) – A list of string (labels) or datetime (must be UTC) to use as x-axis labels. If None, index will be displayed. If pd.Series, it will be converted to a list internally.

  • linked_subplot_idx (int) – The index of the linked subplot on which to plot the line plot. By default, it is the most recently added linked subplot.

  • color (Array | None) – Color (array-like, length 1-4, RGBA) of the line plot.

  • width (float) – Line width for the plot.

  • miter_limit (float) – Miter limit controls the maximum line-segment connection length, for open-line and close-line mode.

  • basic_line (bool) – If true, a simple line plot with fixd width is used (width and miterLimit have no effect). This is much faster.

bar(y, dates=None, linked_subplot_idx=-1, color=(0.03137, 0.6, 0.50588, 0.75), width_ratio=0.5, min_value=None)[source]#

Add a bar plot to the linked subplot.

Parameters:

  • y (np.ndarray | pd.Series) – Vector of float datapoints to plot.

  • dates (Dates | None) – A list of string (labels) or datetime (must be UTC) to use as x-axis labels. If None, index will be displayed. If pd.Series, it will be converted to a list internally.

  • linked_subplot_idx (int) – The index of the linked subplot on which to plot the bar plot. By default, it is the most recently added linked subplot.

  • color (Array | None) – Color (array-like, length 1-4, RGBA) of the bar plot.

  • width_ratio (float) – Ratio between the bar width and inter-bar gap, a float between (0, 1] e.g. 1 is no space between bars.

  • min_value (float | None) – Minimum value of the bar plot. By default, the minimum number in y minus 1% of max y - min y as padding.

scatter(x, y, linked_subplot_idx=-1, shape='circle', color=(0.12, 0.46, 0.7, 1.0), fixed_size=True, marker_size_fixed=0.025, marker_size_free=10.0)[source]#

Add a scatter plot to the linked subplot.

Parameters:

  • x (np.ndarray | Dates) – A numpy array of indexes, or list of string or datetimes (UTC) of x-axis position of the scatter points. The type must match the current x tick label type.

  • y (np.ndarray | pd.Series) – Vector of floats containing y-axis data. Must match x in length.

  • linked_subplot_idx (int) – The index of the linked subplot on which to plot the scatter plot. By default, it is the most recently added linked subplot.

  • shape (ScatterShapeType) – Shape of the scatter marker (see ScatterShapeType)

  • color (Array) – Color (array-like, length 1-4, RGBA) of the scatter marker.

  • fixed_size (bool) – If true, size of the scatter marker is the same at all zooms. If False, the size of the marker will decrease when zoomed out.

  • marker_size_fixed (float) – Size of the scatter marker when fixed_size is true.

  • marker_size_free (float) – Size of the scatter marker when fixed_size if False.

is_number(x)[source]#