energytrackr.plot.builtin_plot_objects package¶

Submodules¶

energytrackr.plot.builtin_plot_objects.bollinger_bands module¶

Bollinger Bands (SMA ± n_std x rolling std) around a moving average.

class energytrackr.plot.builtin_plot_objects.bollinger_bands.BollingerBands(**kwargs: dict)[source]¶

Bases: PlotObj, Configurable[OutlierFilterConfig]

Draws Bollinger Bands (SMA ± n_std x rolling std) around a moving average.

add(ctx: Context, fig: figure) → None[source]¶

Adds Bollinger Bands and a Simple Moving Average (SMA) line to the given Bokeh figure.

This method computes the SMA and standard deviation over a rolling window from the median values in the provided context statistics. It then calculates the upper and lower Bollinger Bands, creates a data source, and adds a shaded area (band) between the bands and a line for the SMA. A hover tool is also added to display commit and SMA values.

Parameters:

ctx (Context) – The plotting context containing statistics and labels.
fig (figure) – The Bokeh figure to which the Bollinger Bands and SMA will be added.

class energytrackr.plot.builtin_plot_objects.bollinger_bands.OutlierFilterConfig(window: int = 20, n_std: float = 2.0, band_color: str = 'orange', ma_color: str = 'navy', line_width: int = 2, legend: str = 'Bollinger Bands', default_visible: bool = True)[source]¶

Bases: object

Configuration for bollinger bands.

band_color: str = 'orange'¶

default_visible: bool = True¶

legend: str = 'Bollinger Bands'¶

line_width: int = 2¶

ma_color: str = 'navy'¶

n_std: float = 2.0¶

window: int = 20¶

energytrackr.plot.builtin_plot_objects.candlestick module¶

Candlestick - optional object that shows min/max & open/close per commit.

class energytrackr.plot.builtin_plot_objects.candlestick.Candlestick(**params: dict[str, Any])[source]¶

Bases: PlotObj, Configurable[CandlestickConfig]

Draws a candlestick chart: open, close, low, high per commit.

add(ctx: Context, fig: figure) → None[source]¶

Adds a candlestick plot to the given context’s figure using statistical data.

This method constructs a candlestick chart by computing the open, close, low, and high values from the provided medians and distributions. It then creates a Bokeh ColumnDataSource with these values and draws the candlestick bodies using the quad glyph and the wicks using the segment glyph.

Side Effects:: Modifies the figure in the context by adding candlestick and wick glyphs. Logs a debug message indicating whether the candlestick is visible.

Parameters:

ctx (Context) – The plotting context containing statistical data and the figure to plot on. - ctx.stats[“x_indices”]: Sequence of x-axis indices for each candlestick. - ctx.stats[“medians”]: Sequence of median values for each candlestick. - ctx.artefacts[“distributions”]: Sequence of distributions (arrays) for each candlestick.
fig (figure) – The Bokeh figure to which the candlestick plot will be added.

class energytrackr.plot.builtin_plot_objects.candlestick.CandlestickConfig(default_visible: bool = False, body_width: float = 0.6)[source]¶

Bases: object

Configuration for the candlestick plot object.

body_width: float = 0.6¶

default_visible: bool = False¶

energytrackr.plot.builtin_plot_objects.change_events module¶

ChangeEventMarkers - Draws regression/improvement markers and optional level circles.

class energytrackr.plot.builtin_plot_objects.change_events.ChangeEventMarkers(**params: dict[str, Any])[source]¶

Bases: PlotObj, Configurable[ChangeEventMarkersConfig]

Draws regression/improvement markers and optional level circles.

add(ctx: Context, fig: figure) → None[source]¶

Adds visual markers for change events to the plot in the given context.

This method retrieves change events from the context’s artefacts and adds box annotations to the plot to indicate regressions (in red) and improvements (in green) at the corresponding indices. If self.show_levels is True, it also adds circles at the median values for each event, colored and sized according to their level.

Side Effects:: Modifies the plot in ctx.fig by adding box annotations and, optionally, level circles. Logs information and debug messages about the process.

Parameters:

ctx (Context) – The plotting context containing artefacts, statistics, and the figure.
fig (figure) – The Bokeh figure to which the change event markers will be added.

class energytrackr.plot.builtin_plot_objects.change_events.ChangeEventMarkersConfig(show_levels: bool = True, radius_base: float = 6)[source]¶

Bases: object

Configuration for ChangeEventMarkers.

radius_base: float = 6¶

show_levels: bool = True¶

energytrackr.plot.builtin_plot_objects.distribution_scatter module¶

Distribution scatter plot object.

class energytrackr.plot.builtin_plot_objects.distribution_scatter.DistributionScatter(**params: dict[str, Any])[source]¶

Bases: PlotObj, Configurable[DistributionScatterConfig]

Scatter-plots each raw measurement point per commit.

add(ctx: Context, fig: figure) → None[source]¶

Add the distribution scatter plot to the figure.

Parameters:

ctx (Context) – The context object containing artefacts and figure. It should contain the following artefacts: - “distributions”: List of distributions for each commit. - “normality_flags”: List of booleans indicating if the distribution is normal or not.
fig (figure) – The Bokeh figure to which the scatter plot will be added.

class energytrackr.plot.builtin_plot_objects.distribution_scatter.DistributionScatterConfig(normal_color: str = 'blue', nonnormal_color: str = 'orange', radius: float = 0.3, alpha: float = 0.5, normal_visible: bool = False, normal_label: str = 'Normal', nonnormal_label: str = 'Non-Normal')[source]¶

Bases: object

Configuration for the distribution scatter plot.

alpha: float = 0.5¶

nonnormal_color: str = 'orange'¶

nonnormal_label: str = 'Non-Normal'¶

normal_color: str = 'blue'¶

normal_label: str = 'Normal'¶

normal_visible: bool = False¶

radius: float = 0.3¶

class energytrackr.plot.builtin_plot_objects.distribution_scatter.DistributionScatterStyle(normal_color: str = 'blue', nonnormal_color: str = 'orange', radius: float = 0.3, alpha: float = 0.5, normal_visible: bool = False, normal_label: str = 'Normal', nonnormal_label: str = 'Non-Normal')[source]¶

Bases: object

Style for the distribution scatter plot.

alpha: float = 0.5¶

nonnormal_color: str = 'orange'¶

nonnormal_label: str = 'Non-Normal'¶

normal_color: str = 'blue'¶

normal_label: str = 'Normal'¶

normal_visible: bool = False¶

radius: float = 0.3¶

energytrackr.plot.builtin_plot_objects.dynamic_ticks module¶

DynamicTicks - Adaptive x-axis ticks + label overrides using commit hashes.

class energytrackr.plot.builtin_plot_objects.dynamic_ticks.DynamicTicks(**params: dict[str, Any])[source]¶

Bases: PlotObj, Configurable[DynamicTicksConfig]

Adaptive x-axis ticks + label overrides using commit hashes.

add(ctx: Context, fig: figure) → None[source]¶

Adds dynamic tick labeling to the x-axis of the plot based on the current view range.

This method initializes the x-axis with a fixed set of ticks and label overrides using short hashes. It also attaches a JavaScript callback to the x-axis range, so that when the user pans or zooms, the tick positions are recalculated to maintain a readable number of ticks, and the labels are updated accordingly.

Parameters:

ctx (Context) – The plotting context containing the figure and statistics.
fig (figure) – The Bokeh figure to which the dynamic ticks will be added.

class energytrackr.plot.builtin_plot_objects.dynamic_ticks.DynamicTicksConfig(max_ticks: int = 30)[source]¶

Bases: object

Configuration for DynamicTicks.

max_ticks: int = 30¶

energytrackr.plot.builtin_plot_objects.ema_line module¶

Plotting object for Exponential Moving Average (EMA) line.

class energytrackr.plot.builtin_plot_objects.ema_line.EMALine(**params: dict[str, Any])[source]¶

Bases: SeriesLine[EMALineConfig]

Draws an exponential moving average over the median values.

compute(series: Series) → Series[source]¶

Compute the exponential moving average of the series.

Parameters:: series – Input median series.
Returns:: EMA series with the same index.

class energytrackr.plot.builtin_plot_objects.ema_line.EMALineConfig(span: int = 20, color: str = 'green', line_width: int = 2, radius: float = 0.3, legend: str = 'EMA', default_visible: bool = True)[source]¶

Bases: object

Configuration for the Exponential Moving Average (EMA) line plot object.

color: str = 'green'¶

default_visible: bool = True¶

legend: str = 'EMA'¶

line_width: int = 2¶

radius: float = 0.3¶

span: int = 20¶

energytrackr.plot.builtin_plot_objects.error_bars module¶

ErrorBars - vertical segments showing ±sigma around the median.

class energytrackr.plot.builtin_plot_objects.error_bars.ErrorBars(**params: dict[str, Any])[source]

Bases: PlotObj, Configurable[ErrorBarsConfig]

A plot object for rendering error bars on a plot.

line_width

Width of the error bar lines.

Type:: int

color

Color of the error bars.

Type:: str

legend

Label for the error bars in the plot legend.

Type:: str

add(ctx: Context, **params: Any) -> None: Adds error bars to the given plot context using median values and their associated errors. The error bars are drawn as vertical segments from (x, median - error) to (x, median + error). Uses data from ctx.stats: “x_indices”, “medians”, and “y_errors”.

add(ctx: Context, fig: figure) → None[source]

Adds vertical error bars to the plot using the provided context.

Retrieves x-coordinates, median y-values, and y-error values from the context’s statistics. Computes the lower and upper bounds for the error bars, constructs a data source, and adds the error bars as vertical segments to the figure.

Parameters:

ctx (Context) – The plotting context containing figure and statistical data.
fig (figure) – The Bokeh figure to which the error bars will be added.

class energytrackr.plot.builtin_plot_objects.error_bars.ErrorBarsConfig(line_width: int = 2, color: str = 'black', legend: str = 'Error Bars')[source]

Bases: object

Configuration for error bars in a plot.

line_width

Width of the error bar lines.

Type:: int

color

Color of the error bars.

Type:: str

legend

Label for the error bars in the plot legend.

Type:: str

color: str = 'black'

legend: str = 'Error Bars'

line_width: int = 2

energytrackr.plot.builtin_plot_objects.legend_policy module¶

LegendPolicy - sets click_policy on all legend entries.

class energytrackr.plot.builtin_plot_objects.legend_policy.LegendPolicy(**params: dict[str, Any])[source]

Bases: PlotObj, Configurable[LegendPolicyConfig]

A PlotObj that sets click_policy on all legend entries.

add(ctx: Context, fig: figure) → None[source]

Adds legend policy and styling to the figure’s legends in the given context.

This method sets the click_policy and label_text_font attributes for each Legend object found in the figure associated with the provided context.

Parameters:

ctx (Context) – The plotting context containing the figure (fig) to modify.
fig (figure) – The Bokeh figure to which the legend policy will be applied.

class energytrackr.plot.builtin_plot_objects.legend_policy.LegendPolicyConfig(policy: Literal['none', 'hide', 'mute'] = 'hide')[source]

Bases: object

Configuration for LegendPolicy.

policy

The click policy for the legend. Options are “hide”, “mute”, or “disable”.

Type:: LegendClickPolicyType

policy: Literal['none', 'hide', 'mute'] = 'hide'

energytrackr.plot.builtin_plot_objects.macd_line module¶

Plotting object for MACD (Moving Average Convergence Divergence) line.

class energytrackr.plot.builtin_plot_objects.macd_line.MACDConfig(fast_span: int = 12, slow_span: int = 26, signal_span: int = 9, macd_color: str = 'purple', signal_color: str = 'black', line_width: int = 2, default_visible: bool = True)[source]¶

Bases: object

Configuration for MACD calculation and styling.

default_visible: bool = True¶

fast_span: int = 12¶

line_width: int = 2¶

macd_color: str = 'purple'¶

signal_color: str = 'black'¶

signal_span: int = 9¶

slow_span: int = 26¶

class energytrackr.plot.builtin_plot_objects.macd_line.MACDLine(**params: dict[str, Any])[source]¶

Bases: PlotObj, Configurable[MACDConfig]

Draws MACD (fast EMA - slow EMA) plus its signal line (EMA of MACD).

add(ctx: Context, fig: figure) → None[source]¶

Adds MACD (Moving Average Convergence Divergence) and signal lines to the given Bokeh figure.

This method computes the MACD and signal lines from the median values in the provided context, creates a data source for plotting, and adds the corresponding lines to the figure. It also attaches a hover tool to display commit hashes and line values.

Parameters:

ctx (Context) – The context containing statistical data, including medians and commit hashes.
fig (figure) – The Bokeh figure to which the MACD and signal lines will be added.

property legend_macd: str¶

Generate the legend label for the MACD line using the configured fast and slow spans.

Returns:: A string representing the MACD legend in the format ‘MACD(fast_span,slow_span)’.
Return type:: str

property legend_signal: str¶

Returns the legend label for the signal line in the MACD plot.

The label includes the signal span value from the configuration.

Returns:: The formatted legend label for the signal line.
Return type:: str

energytrackr.plot.builtin_plot_objects.median_line module¶

MedianLine - default line/glyph object for the modular plot system.

class energytrackr.plot.builtin_plot_objects.median_line.MedianLine(**params: dict[str, Any])[source]¶

Bases: SeriesLine[MedianLineConfig]

Draws median points connected by a line (identity series).

class energytrackr.plot.builtin_plot_objects.median_line.MedianLineConfig(color: str = 'blue', line_width: int = 1, radius: float = 0.3, legend: str = 'Median', default_visible: bool = True)[source]¶

Bases: object

Configuration for the Median line plot object.

color: str = 'blue'¶

default_visible: bool = True¶

legend: str = 'Median'¶

line_width: int = 1¶

radius: float = 0.3¶

energytrackr.plot.builtin_plot_objects.series_line module¶

Moving-average plotting objects: a generic base plus EMA and SMA implementations.

class energytrackr.plot.builtin_plot_objects.series_line.SeriesLine(config_cls: type[ConfigT], **params: dict[str, Any])[source]¶

Bases: PlotObj, Configurable, Generic

Base class for line plot objects over a single Pandas Series.

add(ctx: Context, fig: figure) → None[source]¶

Add the line, markers, and hover tool to the Bokeh figure.

Parameters:

ctx (Context) – The plotting context containing figure and statistical data.
fig (figure) – The Bokeh figure to which the line and markers will be added.

compute(series: Series) → Series[source]¶

Transform the input series before plotting; default is identity.

Parameters:: series (pd.Series) – The input series to transform.
Returns:: The transformed series.
Return type:: pd.Series

class energytrackr.plot.builtin_plot_objects.series_line.SeriesLineConfigProtocol(*args, **kwargs)[source]¶

Bases: Protocol

Protocol that all series line configs must follow.

property color: str¶: Color of the line and markers.

property default_visible: bool¶: Default visibility of the line and markers.

property legend: str¶: Label for the legend.

property line_width: int¶: Width of the line.

property radius: float¶: Radius of the markers.

energytrackr.plot.builtin_plot_objects.sma_line module¶

SMA line plot object.

class energytrackr.plot.builtin_plot_objects.sma_line.SMALine(**params: dict[str, Any])[source]¶

Bases: SeriesLine[SMALineConfig]

Draws a rolling-window simple moving average over the median values.

compute(series: Series) → Series[source]¶

Compute the simple moving average of the series.

Parameters:: series – Input median series.
Returns:: SMA series with the same index.

class energytrackr.plot.builtin_plot_objects.sma_line.SMALineConfig(window: int = 50, color: str = 'orange', line_width: int = 2, radius: float = 0.3, legend: str = 'SMA', default_visible: bool = True)[source]¶

Bases: object

Configuration for the Simple Moving Average (SMA) line plot object.

color: str = 'orange'¶

default_visible: bool = True¶

legend: str = 'SMA'¶

line_width: int = 2¶

radius: float = 0.3¶

window: int = 50¶

Module contents¶

Builtin plot objects for energytrackr.