Function Description

This module provides a collection of reusable plotting functions with consistent styling, scaling, and formatting behavior. Each function wraps around a base plotting interface to simplify usage and unify customization via keyword arguments.

Available Plot Types:

• BarHPlot : Horizontal bar plot for categorical or binned data.

• BarPlot : Vertical bar plot for categorical or binned data.

• BoxPlot : Statistical box plot for visualizing distributions.

• HistogramPlot : Histogram for visualizing frequency distributions.

• LinearPlot : Standard linear X-Y plot.

• PseudoColorPlot : Heatmap-like pseudocolor mesh plotting.

• SemiLogXPlot : Semi-logarithmic plot with logarithmic scaling on the X-axis.

• SemiLogYPlot : Semi-logarithmic plot with logarithmic scaling on the Y-axis.

Available Accessories:

• VLinePlot : Draws a vertical line with an optional label at a specified X position.

• HLinePlot : Draws a horizontal line with an optional label at a specified Y position.

• FillPlot : Creates a filled area between two curves or between a curve and zero.

• RectanglePlot : Adds a rectangular patch to the plot at a specified center and span.

All functions accept a list of plot definitions and standardized axis label formatting.

chrispytools.plot.BarHPlot(ax, Plot_list, X_label, Y_label, **kwargs)

Plots a horizontal bar chart using a standardized plotting interface.

This function renders horizontal bars with support for axis scaling, user-defined matplotlib style arguments, and optional legend handling via chrispytools.plot.base.BasePlot().

Parameters:

• ax (matplotlib.axes.Axes) – The matplotlib axis object to render the plot on.

• Plot_list (list) –

  A list of plot definitions. Each plot should be a list or tuple with the form: [YData, XData, Label, style_string (optional)]

  • YData (array-like): Bar positions on the Y-axis.

  • XData (array-like): Lengths of the bars (X-direction).

  • Label (str): Legend label for the bars.

  • style_string (str, optional): A comma-separated string of matplotlib style parameters, e.g., "color=blue,height=0.3,align=center".

• X_label (list) – A 2- or 3-element list defining the X-axis label and unit: [Label (str), Unit (str), Scale (float, optional)]

• Y_label (list) – A 2- or 3-element list defining the Y-axis label and unit: [Label (str), Unit (str), Scale (float, optional)]

• **kwargs (dict) – Additional keyword arguments passed to chrispytools.plot.base.BasePlot().

Returns:

The updated axis object with the horizontal bar chart rendered.

Return type:

matplotlib.axes.Axes

chrispytools.plot.BarPlot(ax, Plot_list, X_label, Y_label, **kwargs)

Plots a standard bar chart using a consistent plotting interface.

This function wraps a bar chart with rescaling support, custom styles, and optional legend control using chrispytools.plot.base.BasePlot().

Parameters:

• ax (matplotlib.axes.Axes) – The matplotlib axis object to render the plot on.

• Plot_list (list) –

  A list of plot definitions. Each plot should be a list or tuple with the form: [XData, YData, Label, style_string (optional)]

  • XData (array-like): Bar positions on the X-axis.

  • YData (array-like): Heights of the bars.

  • Label (str): Legend label for the bars.

  • style_string (str, optional): A comma-separated string of matplotlib style parameters, e.g., "color=green,width=0.5,align=center".

• X_label (list) – A 2- or 3-element list defining the X-axis label and unit: [Label (str), Unit (str), Scale (float, optional)]

• Y_label (list) – A 2- or 3-element list defining the Y-axis label and unit: [Label (str), Unit (str), Scale (float, optional)]

• **kwargs (dict) – Additional keyword arguments passed to chrispytools.plot.base.BasePlot().

Returns:

The updated axis object with the bar chart rendered.

Return type:

matplotlib.axes.Axes

chrispytools.plot.BoxPlot(ax, Plot_list, X_label, Y_label, **kwargs)

Prepares a box plot using a standardized plot wrapper.

This function supports label scaling, user-defined styles via a string parser, and integrates with the chrispytools.plot.base.BasePlot() backend.

It calculates automatic box widths if none are provided, and handles consistent color formatting for all box components. The legend is automatically constructed for each trace based on its label.

Parameters:

• ax (matplotlib.axes.Axes) – The matplotlib axis object to render the plot on.

• Plot_list (list) –

  A list of plot entries. Each entry must be a list or tuple of the form: [XData, YData, Label, style_string (optional)]

  • XData (array-like): Positions on the X-axis for each box.

  • YData (list of array-like): Box data for each X point.

  • Label (str): Legend label for the box group.

  • style_string (str, optional): Comma-separated string of box style arguments such as "color=blue,widths=0.5".

• X_label (list) – A list of 2 or 3 elements for labeling the X-axis: [Label (str), Unit (str), Scale (float, optional)]

• Y_label (list) – A list of 2 or 3 elements for labeling the Y-axis: [Label (str), Unit (str), Scale (float, optional)]

• **kwargs (dict) – Additional keyword arguments passed to chrispytools.plot.base.BasePlot().

Returns:

The axis object with the rendered box plots.

Return type:

matplotlib.axes.Axes

chrispytools.plot.FillPlot(ax, XAxis, YAxis1, YAxis2=None, XLimits=None, StickyLimits=True, minor_gridcolor='#e8e8e8', major_gridcolor='#d0d0d0', major_gridlw=1.2, minor_gridlw=1.0, minor_gridzorder=0, major_gridzorder=0, FlatGridPlot=False, **kwargs)

Fills the area between two curves or between a curve and baseline on the given axis. Optionally applies a custom flat grid overlay with major and minor grid lines.

Parameters:

• ax (matplotlib.axes.Axes) – The axis to draw on.

• XAxis (array-like) – X-axis data points.

• YAxis1 (array-like) – Y-axis data points for the first curve.

• YAxis2 (array-like or None, optional) – Y-axis data points for the second curve. If None, defaults to zero line (default).

• XLimits (list or tuple of two floats, optional) – Range [start, end] on X-axis to limit the fill area (default is None, use all).

• StickyLimits (bool, optional) – If True, keeps the original axis limits after plotting (default is True).

• minor_gridcolor (str, optional) – Color for minor grid lines (default “#e8e8e8”).

• major_gridcolor (str, optional) – Color for major grid lines (default “#d0d0d0”).

• major_gridlw (float, optional) – Line width for major grid lines (default 1.2).

• minor_gridlw (float, optional) – Line width for minor grid lines (default 1.0).

• minor_gridzorder (int, optional) – Z-order for minor grid lines (default 0).

• major_gridzorder (int, optional) – Z-order for major grid lines (default 0).

• FlatGridPlot (bool, optional) – If True, draws a custom flat grid by manually plotting grid lines (default False).

• **kwargs – Additional keyword arguments passed to ax.fill_between().

Returns:

Modifies the axis in-place.

Return type:

None

chrispytools.plot.HLinePlot(ax, yValue, yLabel, xDistance=0.4, yDistance=0, xPos='right', fontsize=6, verticalalignment='center', color='r', TextBG='', TextBG_Pad=1.25, **kwargs)

Draws a horizontal line at a specified y-value on the given axis, with an optional label.

Parameters:

• ax (matplotlib.axes.Axes) – The axis to draw the horizontal line on.

• yValue (float) – The y-coordinate where the horizontal line will be drawn.

• yLabel (str) – The text label displayed near the horizontal line.

• xDistance (float, optional) – Distance multiplier for label positioning relative to the axis ticks (default is 0.4).

• yDistance (float, optional) – Vertical offset for the label positioning relative to the horizontal line (default is 0).

• xPos ({'left', 'right', 'center'}, optional) – Positioning of the label relative to the horizontal line: - ‘right’: right side of the axis (default) - ‘left’: left side of the axis - ‘center’: centered horizontally on the axis

• fontsize (int, optional) – Font size of the label text (default is 6).

• verticalalignment (str, optional) – Vertical alignment of the label text (default is ‘center’).

• color (str, optional) – Color of the line and label text (default is ‘r’ for red).

• TextBG (str, optional) – Background color for the label text box. If empty, no background is applied.

• TextBG_Pad (float, optional) – Padding for the text background box (default is 1.25).

• **kwargs (dict) – Additional keyword arguments passed to ax.axhline().

Return type:

None

chrispytools.plot.HistogramPlot(ax, Plot_list, X_label, Y_label, FreedmanDiacoins=True, **kwargs)

Plots histograms using a standardized plot wrapper.

This function supports label scaling, user-defined styles, and optionally applies the Freedman–Diaconis rule to determine optimal bin widths for the histogram. It integrates with chrispytools.plot.base.BasePlot() for consistent formatting and configuration.

Parameters:

• ax (matplotlib.axes.Axes) – The matplotlib axis object on which to draw the histogram.

• Plot_list (list) –

  A list of plot entries. Each entry must be a list or tuple of the form: [XData, YData, Label, style_string (optional)]

  • XData (array-like): Data values to be binned on the X-axis.

  • YData (array-like): Typically ignored in histogram plots, but kept for consistency.

  • Label (str): Legend label for the histogram trace.

  • style_string (str, optional): A comma-separated string of matplotlib style arguments, e.g., "color=blue,bins=30,alpha=0.6".

• X_label (list) – A list of 2 or 3 elements representing the X-axis labeling scheme: [Label (str), Unit (str), Scale (float, optional)]

• Y_label (list) – A list of 2 or 3 elements representing the Y-axis labeling scheme: [Label (str), Unit (str), Scale (float, optional)]

• FreedmanDiacoins (bool, default=True) – If True, the bin count is automatically computed using the Freedman–Diaconis rule: bin_width = 2 * IQR * n^(-1/3)

• **kwargs (dict) – Additional keyword arguments passed to chrispytools.plot.base.BasePlot().

Returns:

The updated axis object containing the histogram.

Return type:

matplotlib.axes.Axes

chrispytools.plot.LinearPlot(ax, Plot_list, X_label, Y_label, **kwargs)

Prepares a basic X-Y linear plot using a standardized plot wrapper.

This function handles optional label scaling, user-defined line styles, and passes additional configuration to the chrispytools.plot.base.BasePlot() backend.

Parameters:

• ax (matplotlib.axes.Axes) – The matplotlib axis object to render the plot on.

• Plot_list (list) –

  A list of plot entries, where each entry has the format: [XData, YData, Label, style_string (optional)]

  • XData (array-like): Data for the X-axis.

  • YData (array-like): Data for the Y-axis.

  • Label (str): Legend label for the plotted trace.

  • style_string (str, optional): A comma-separated string of matplotlib style arguments, e.g., "linestyle=--, color=red".

• X_label (list) – A 2- or 3-element list representing the X-axis label configuration: [Label (str), Unit (str), Scale (float, optional)]

• Y_label (list) – A 2- or 3-element list representing the Y-axis label configuration: [Label (str), Unit (str), Scale (float, optional)]

• **kwargs (dict) – Additional keyword arguments forwarded to chrispytools.plot.base.BasePlot().

Returns:

The updated axis object with the semi-logarithmic plot rendered.

Return type:

matplotlib.axes.Axes

chrispytools.plot.PseudoColorPlot(ax, Plot_list, X_label, Y_label, **kwargs)

Prepares a pseudo color (pcolor) X-Y plot using a standardized plot wrapper.

This function handles optional label scaling, user-defined line styles, and passes additional configuration to the chrispytools.plot.base.BasePlot() backend.

Parameters:

• ax (matplotlib.axes.Axes) – The matplotlib axis object to render the plot on.

• Plot_list (list) –

  A list of plot entries, where each entry has the format: [XData, YData, Label, style_string (optional)]

  • XData (array-like): Data for the X-axis.

  • YData (array-like): Data for the Y-axis.

  • Label (str): Legend label for the plotted trace.

  • style_string (str, optional): A comma-separated string of matplotlib style arguments, e.g., "linestyle=--, color=red".

• X_label (list) – A 2- or 3-element list representing the X-axis label configuration: [Label (str), Unit (str), Scale (float, optional)]

• Y_label (list) – A 2- or 3-element list representing the Y-axis label configuration: [Label (str), Unit (str), Scale (float, optional)]

• **kwargs (dict) – Additional keyword arguments forwarded to chrispytools.plot.base.BasePlot().

Returns:

The updated axis object with the semi-logarithmic plot rendered.

Return type:

matplotlib.axes.Axes

chrispytools.plot.RectanglePlot(ax, xCenter, xSpan, yCenter, ySpan, fullSpanY=False, StickyLimits=True, **kwargs)

Draws a rectangle patch centered at (xCenter, yCenter) with given width and height.

Parameters:

• ax (matplotlib.axes.Axes) – The axis to draw on.

• xCenter (float) – X-coordinate of the rectangle center.

• xSpan (float) – Width of the rectangle.

• yCenter (float) – Y-coordinate of the rectangle center.

• ySpan (float) – Height of the rectangle.

• fullSpanY (bool, optional) – If True, rectangle spans full current y-axis limits ignoring yCenter and ySpan (default False).

• StickyLimits (bool, optional) – If True, keeps the original axis limits after plotting (default True).

• **kwargs – Additional keyword arguments passed to matplotlib.patches.Rectangle().

Returns:

Modifies the axis in-place.

Return type:

None

chrispytools.plot.SemiLogXPlot(ax, Plot_list, X_label, Y_label, **kwargs)

Prepares a semi-logarithmic (log-x) X-Y plot using a standardized plot wrapper.

This function handles optional label scaling, user-defined line styles, and passes additional configuration to the chrispytools.plot.base.BasePlot() backend.

Parameters:

• ax (matplotlib.axes.Axes) – The matplotlib axis object to render the plot on.

• Plot_list (list) –

  A list of plot entries, where each entry has the format: [XData, YData, Label, style_string (optional)]

  • XData (array-like): Data for the X-axis.

  • YData (array-like): Data for the Y-axis.

  • Label (str): Legend label for the plotted trace.

  • style_string (str, optional): A comma-separated string of matplotlib style arguments, e.g., "linestyle=--, color=red".

• X_label (list) – A 2- or 3-element list representing the X-axis label configuration: [Label (str), Unit (str), Scale (float, optional)]

• Y_label (list) – A 2- or 3-element list representing the Y-axis label configuration: [Label (str), Unit (str), Scale (float, optional)]

• **kwargs (dict) – Additional keyword arguments forwarded to chrispytools.plot.base.BasePlot().

Returns:

The updated axis object with the semi-logarithmic plot rendered.

Return type:

matplotlib.axes.Axes

chrispytools.plot.SemiLogYPlot(ax, Plot_list, X_label, Y_label, **kwargs)

Prepares a semi-logarithmic (log-y) X-Y plot using a standardized plot wrapper.

This function handles optional label scaling, user-defined line styles, and passes additional configuration to the chrispytools.plot.base.BasePlot() backend.

Parameters:

• ax (matplotlib.axes.Axes) – The matplotlib axis object to render the plot on.

• Plot_list (list) –

  A list of plot entries, where each entry has the format: [XData, YData, Label, style_string (optional)]

  • XData (array-like): Data for the X-axis.

  • YData (array-like): Data for the Y-axis.

  • Label (str): Legend label for the plotted trace.

  • style_string (str, optional): A comma-separated string of matplotlib style arguments, e.g., "linestyle=--, color=red".

• X_label (list) – A 2- or 3-element list representing the X-axis label configuration: [Label (str), Unit (str), Scale (float, optional)]

• Y_label (list) – A 2- or 3-element list representing the Y-axis label configuration: [Label (str), Unit (str), Scale (float, optional)]

• **kwargs (dict) – Additional keyword arguments forwarded to chrispytools.plot.base.BasePlot().

Returns:

The updated axis object with the semi-logarithmic plot rendered.

Return type:

matplotlib.axes.Axes

chrispytools.plot.VLinePlot(ax, xValue, xLabel, yDistance=0.5, yPos='up', color='r', fontsize=6, horizontalalignment='center', **kwargs)

Draws a vertical line at a specified x-value on the given axis, with an optional label.

Parameters:

• ax (matplotlib.axes.Axes) – The axis to draw the vertical line on.

• xValue (float) – The x-coordinate where the vertical line will be drawn.

• xLabel (str) – The text label displayed near the vertical line.

• yDistance (float, optional) – Distance multiplier for label positioning relative to the axis ticks (default is 0.5).

• yPos ({'up', 'down', 'center'}, optional) – Positioning of the label relative to the vertical line: - ‘up’: above the axis upper limit (default) - ‘down’: below the axis lower limit - ‘center’: centered vertically on the axis

• color (str, optional) – Color of the line and label text (default is ‘r’ for red).

• fontsize (int, optional) – Font size of the label text (default is 6).

• horizontalalignment (str, optional) – Horizontal alignment of the label text (default is ‘center’).

• **kwargs (dict) – Additional keyword arguments passed to ax.axvline().

Return type:

None

Base Function

chrispytools.plot.base.BasePlot(func, ax, Plot_list, X_label, Y_label, Legend=True, LegendLoc=0, TwinX=None, TwinY=None, TwinReuseTicks='BOTH', Ylim=None, Xlim=None, XAutolim=True, fontsize=7, TicksEng=True, XTicksLabel=None, YTicksLabel=None, legendcol=1, fontsize_label=8, yaxis_pad=0, xaxis_pad=0, BlackWhite=False, grid=True, minor_gridcolor='#e8e8e8', major_gridcolor='#d0d0d0', LegendFrame=True, funcReturn=False, major_gridlw=1.2, minor_gridlw=1.0, minor_gridzorder=0, major_gridzorder=0, FlatGridPlot=False, **kwargs)

Prepares a plot using a specified plotting function and applies common layout settings.

Parameters:

• func (Callable) – Plotting function that takes (ax, plot, Y_label, X_label) as input (e.g. LinearPlot)

• ax (matplotlib.axes.Axes) – Axis to plot on.

• Plot_list (list) – A list of plot elements, e.g. [X, Y, label, optional args].

• X_label (str or tuple) – X-axis label, optionally (label, unit, scale).

• Y_label (str or tuple) – Y-axis label, optionally (label, unit, scale).

• Legend (bool, optional) – Show legend. Defaults to True.

• LegendLoc (int, optional) – Location code for legend. Defaults to 0.

• legendcol (int, optional) – Number of columns in legend. Defaults to 1.

• LegendFrame (bool, optional) – Show a box around the legend. Defaults to True.

• BlackWhite (bool, optional) – Enable monochrome color scheme. Defaults to False.

• fontsize (int, optional) – Font size for ticks and legend. Defaults to 7.

• fontsize_label (int, optional) – Font size for axis labels. Defaults to 8.

• xaxis_pad (int, optional) – Padding between X label and axis. Defaults to 0.

• yaxis_pad (int, optional) – Padding between Y label and axis. Defaults to 0.

• Xlim (tuple, optional) – Set X-axis limits. Defaults to None.

• Ylim (tuple, optional) – Set Y-axis limits. Defaults to None.

• XAutolim (bool, optional) – Automatically calculate X-axis limits. Defaults to True.

• TicksEng (bool, optional) – Enable engineering tick formatting. Defaults to True.

• XTicksLabel (int, optional) – Show every nth X-axis tick. Defaults to None.

• YTicksLabel (int, optional) – Show every nth Y-axis tick. Defaults to None.

• grid (bool, optional) – Enable major/minor grid lines. Defaults to True.

• major_gridcolor (str, optional) – Color of major grid lines. Defaults to “#d0d0d0”.

• minor_gridcolor (str, optional) – Color of minor grid lines. Defaults to “#e8e8e8”.

• major_gridlw (float, optional) – Line width of major grid. Defaults to 1.2.

• minor_gridlw (float, optional) – Line width of minor grid. Defaults to 1.0.

• major_gridzorder (int, optional) – Z-order of major grid. Defaults to 0.

• minor_gridzorder (int, optional) – Z-order of minor grid. Defaults to 0.

• FlatGridPlot (bool, optional) – Force static grid layout. Defaults to False.

• TwinX (Axes, optional) – Add a second X-axis. Defaults to None.

• TwinY (Axes, optional) – Add a second Y-axis. Defaults to None.

• TwinReuseTicks (str, optional) – Reuse tick locations (‘NONE’, ‘AX1’, ‘BOTH’). Defaults to “BOTH”.

• funcReturn (bool, optional) – Return values from plot function. Defaults to False.

• **kwargs – Additional keyword arguments passed to func.

Returns:

Axis object if funcReturn is False, otherwise a list of return values from func.

Return type:

matplotlib.axes.Axes or list

chrispytools.plot.base.AlignAxis(ax1, ax2, AxisType='Y', Method='NONE')

Aligns two Matplotlib axes (ax1 and ax2) along either the X or Y axis so that their ticks are harmonized.

This function is useful for twin-axis plots where both sides should share tick positions or spacing for visual consistency.

Parameters:

• ax1 (matplotlib.axes.Axes) – First axis to align.

• ax2 (matplotlib.axes.Axes) – Second axis to align.

• AxisType (str, optional) – Axis to align — either “Y” or “X”. Defaults to “Y”.

• Method (str, optional) –

  Tick alignment strategy:

  • ”NONE”: Do not align (no-op).

  • ”AX1”: Use ax1’s ticks as reference (not implemented).

  • ”BOTH”: Recalculate ticks for both axes symmetrically.

Returns:

This function modifies the axes in place.

Return type:

None

Note

Only the “BOTH” method is currently implemented. If “NONE” or unsupported combinations are selected, the function returns early.