viz

viz.py

A module that defines the Viz class for creating and manipulating matplotlib-based visualizations with a consistent interface. Includes plotting methods (e.g., bar, line, scatter), layout utilities, and tools for combining multiple plots into a single figure.

class viz.Viz(ax=None, fig=None)[source]

Bases: _PlotMixin, _LayoutMixin, _VizCore

Viz class for plotting on a matplotlib axis.

Parameters:

ax (matplotlib.axes.Axes) – The axis on which the plot will be drawn.
fig (matplotlib.figure.Figure, optional) – The figure containing the axis. Defaults to None, in which case ax.figure is used.

add_subplot(*args, \*\*kwargs): Adds a new subplot to the figure.

add_subplot(*args, **kwargs)

Adds a new subplot to the figure.

Parameters:

args (tuple) – Arguments for fig.add_subplot(), such as (nrows, ncols, index).
kwargs (dict, optional) – Additional keyword arguments passed to fig.add_subplot().

Returns:

A new Viz object wrapping the new subplot.

Return type:

annotate(*args, **kwargs)

Adds an annotation to the plot.

Parameters:

args (tuple) – The annotation arguments, typically (text, xy).
kwargs (dict, optional) – Additional keyword arguments passed to ax.annotate(), such as: - xytext : tuple, optional (position of annotation text) - arrowprops : dict, optional (properties of the arrow, e.g., {‘arrowstyle’: ‘->’}) - fontsize : int, optional (font size of the annotation text)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

aspect(value='auto')

Sets the aspect ratio of the plot.

Parameters:: value (str or float, optional, default='auto') – The aspect ratio to set: - ‘auto’ (default): automatic aspect ratio based on the data - ‘equal’: equal scaling on both axes - float: fixed aspect ratio, e.g., 1.0 for equal scaling - ‘scaled’: scaled based on the data range
Returns:: self – The Viz object itself, allowing for method chaining.
Return type:: Viz

bar(*args, **kwargs)

Creates a bar plot.

Parameters:

args (tuple) – The data to plot as bars. The first element is the x-data (positions), and the second is the y-data (height).
kwargs (dict, optional) – Additional keyword arguments passed to ax.bar(), such as: - color : str, optional (e.g., ‘red’, ‘blue’, etc.) - width : float, optional (width of bars) - align : {‘center’, ‘edge’}, optional (alignment of bars)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

clear()

Clears the current axis.

Returns:: self – The Viz object itself, allowing for method chaining.
Return type:: Viz

close()

Closes the figure.

Returns:: self – The Viz object itself, allowing for method chaining.
Return type:: Viz

static combine_viz(viz_list, nrows=None, ncols=None)

Combines multiple Viz objects into a single figure with subplots.

Parameters:

viz_list (list) – A list of Viz objects to combine.
nrows (int, optional) – The number of rows for the subplot grid (default is None).
ncols (int, optional) – The number of columns for the subplot grid (default is None).

Returns:

A new Viz object containing the combined plots.

Return type:

contour(*args, **kwargs)

Creates a contour plot.

Parameters:

args (tuple) – The contour data, typically (X, Y, Z) where Z represents the contour levels.
kwargs (dict, optional) – Additional keyword arguments passed to ax.contour(), such as: - levels : int or array-like, optional (specific contour levels) - colors : str or array-like, optional (colors for the contours) - linewidths : float, optional (width of contour lines)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

figsize(size)

Sets the figure size.

Parameters:: size (tuple) – The size of the figure as (width, height) in inches.
Returns:: self – The Viz object itself, allowing for method chaining.
Return type:: Viz

grid(flag=True, **kwargs)

Enables or disables the grid on the plot.

Parameters:

flag (bool, optional, default True) – If True, the grid is enabled, otherwise it is disabled.
kwargs (dict, optional) – Additional keyword arguments passed to ax.grid(), such as: - color : str, optional (e.g., ‘gray’, ‘blue’, etc.) - linestyle : {‘-’, ‘–’, ‘-.’, ‘:’}, optional - linewidth : float, optional (line thickness) - which : {‘major’, ‘minor’}, optional (gridlines for major or minor ticks)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

hlines(*args, **kwargs)

Draws horizontal lines across the plot.

Parameters:

args (tuple) – Arguments passed to ax.hlines(), typically: - y : scalar or array-like (y positions of the lines) - xmin : scalar, optional (left limit for the line) - xmax : scalar, optional (right limit for the line)
kwargs (dict, optional) – Additional keyword arguments passed to ax.hlines(), such as: - color : str, optional (line color) - linewidth : float, optional (thickness of the line) - linestyle : {‘-’, ‘–’, ‘-.’, ‘:’}, optional (line style)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

imshow(*args, **kwargs)

Displays an image on the plot.

Parameters:

args (tuple) – The image data (e.g., a 2D array representing pixel intensities).
kwargs (dict, optional) – Additional keyword arguments passed to ax.imshow(), such as: - cmap : str, optional (colormap for displaying the image) - interpolation : str, optional (method for interpolation, e.g., ‘nearest’, ‘bilinear’) - alpha : float, optional (transparency, from 0 to 1)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

invert_x()

Inverts the x-axis.

Returns:: self – The Viz object itself, allowing for method chaining.
Return type:: Viz

invert_y()

Inverts the y-axis.

Returns:: self – The Viz object itself, allowing for method chaining.
Return type:: Viz

legend(**kwargs)

Adds a legend to the plot.

Parameters:: kwargs (dict, optional) – Additional keyword arguments passed to ax.legend(), such as: - loc : str or int, optional (location of the legend, e.g., ‘best’, ‘upper left’, 0) - fontsize : int or float, optional - title : str, optional (title of the legend) - shadow : bool, optional (whether to add shadow) - bbox_to_anchor : tuple, optional (to specify a custom position for the legend)
Returns:: self – The Viz object itself, allowing for method chaining.
Return type:: Viz

plot(*args, **kwargs)

Plots data on the axis.

Parameters:

args (tuple) – The data to plot. The first element is typically the x-data, and the second is the y-data.
kwargs (dict, optional) – Additional keyword arguments passed to ax.plot(), such as: - label : str, optional (label for the plot, used in legend) - linestyle : {‘-’, ‘–’, ‘-.’, ‘:’}, optional - color : str, optional (e.g., ‘red’, ‘blue’, etc.) - marker : {‘o’, ‘x’, ‘s’, ‘^’, etc.}, optional (marker style) - linewidth : float, optional (line thickness)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

save(path, **kwargs)

Saves the figure to a file.

Parameters:

path (str) – The file path to save the figure.
kwargs (dict, optional) – Additional keyword arguments passed to fig.savefig(), such as: - dpi : int, optional (dots per inch for image resolution) - bbox_inches : str or ‘tight’, optional (to adjust bounding box) - transparent : bool, optional (if True, the background is transparent)

scatter(*args, **kwargs)

Creates a scatter plot.

Parameters:

args (tuple) – The data to plot as scatter. The first element is typically the x-data, and the second is the y-data.
kwargs (dict, optional) – Additional keyword arguments passed to ax.scatter(), such as: - color : str, optional (e.g., ‘red’, ‘blue’, etc.) - marker : {‘o’, ‘x’, ‘s’, ‘^’, etc.}, optional (marker style) - s : scalar or array-like, optional (size of markers) - alpha : float, optional (transparency, from 0 to 1)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

set_title(txt, **kwargs)

Sets the title of the plot.

Parameters:

txt (str) – The title text.
kwargs (dict, optional) – Additional keyword arguments passed to ax.set_title(), such as: - fontsize : int or float, optional - fontweight : {‘normal’, ‘bold’, ‘heavy’, ‘light’, ‘ultrabold’, ‘ultralight’}, optional - color : str, optional (e.g., ‘red’, ‘blue’, etc.) - pad : float, optional (distance from the top of the axes)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

set_xlim(*args, **kwargs)

Sets the limits for the x-axis.

Parameters:

args (tuple) – The limits to set as (min, max).
kwargs (dict, optional) – Additional keyword arguments passed to ax.set_xlim(), such as: - xmin : float, optional (minimum limit for x-axis) - xmax : float, optional (maximum limit for x-axis)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

set_xticks(ticks, **kwargs)

Sets the ticks on the x-axis.

Parameters:

ticks (list) – A list of positions where ticks should appear on the x-axis.
kwargs (dict, optional) – Additional keyword arguments passed to ax.set_xticks(), such as: - minor : bool, optional (if True, the minor ticks are set instead of the major ones)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

set_ylim(*args, **kwargs)

Sets the limits for the y-axis.

Parameters:

args (tuple) – The limits to set as (min, max).
kwargs (dict, optional) – Additional keyword arguments passed to ax.set_ylim(), such as: - ymin : float, optional (minimum limit for y-axis) - ymax : float, optional (maximum limit for y-axis)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

set_yticks(ticks, **kwargs)

Sets the ticks on the y-axis.

Parameters:

ticks (list) – A list of positions where ticks should appear on the y-axis.
kwargs (dict, optional) – Additional keyword arguments passed to ax.set_yticks(), such as: - minor : bool, optional (if True, the minor ticks are set instead of the major ones)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

show(clear=False)

Displays the plot.

Parameters:: clear (bool, optional) – If True, the previous output is cleared before showing the plot.

style(style_name='seaborn-v0_8-whitegrid')

Applies a matplotlib style to the plot.

Parameters:: style_name (str, optional, default='seaborn-v0_8-whitegrid') – The style to apply. For example, ‘seaborn-darkgrid’, ‘ggplot’, etc.
Returns:: self – The Viz object itself, allowing for method chaining.
Return type:: Viz

suptitle(txt, **kwargs)

Sets the title for the entire figure.

Parameters:

txt (str) – The title text.
kwargs (dict, optional) – Additional keyword arguments passed to fig.suptitle(), such as: - fontsize : int or float, optional (size of the title text) - fontweight : {‘normal’, ‘bold’, ‘heavy’, ‘light’, ‘ultrabold’, ‘ultralight’}, optional - color : str, optional (e.g., ‘red’, ‘blue’, etc.)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

tight_layout(**kwargs)

Adjusts the layout to prevent overlap of plot elements.

Parameters:: kwargs (dict, optional) – Additional keyword arguments passed to fig.tight_layout(), such as: - pad : float, optional (padding between plot elements) - h_pad : float, optional (height padding) - w_pad : float, optional (width padding) - rect : tuple, optional (the area to which the layout is confined, e.g., (left, bottom, right, top))
Returns:: self – The Viz object itself, allowing for method chaining.
Return type:: Viz

twinx()

Creates a twin axis sharing the same x-axis but different y-axis.

Returns:: A new Viz object with the twin axis.
Return type:: Viz

vlines(*args, **kwargs)

Draws vertical lines across the plot.

Parameters:

args (tuple) – Arguments passed to ax.vlines(), typically: - x : scalar or array-like (x positions of the lines) - ymin : scalar, optional (bottom limit for the line) - ymax : scalar, optional (top limit for the line)
kwargs (dict, optional) – Additional keyword arguments passed to ax.vlines(), such as: - color : str, optional (line color) - linewidth : float, optional (thickness of the line) - linestyle : {‘-’, ‘–’, ‘-.’, ‘:’}, optional (line style)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

xlabel(txt, **kwargs)

Sets the label for the x-axis.

Parameters:

txt (str) – The label text for the x-axis.
kwargs (dict, optional) – Additional keyword arguments passed to ax.set_xlabel(), such as: - fontsize : int or float, optional - fontweight : {‘normal’, ‘bold’, ‘heavy’, ‘light’, ‘ultrabold’, ‘ultralight’}, optional - color : str, optional (e.g., ‘red’, ‘blue’, etc.)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type:

ylabel(txt, **kwargs)

Sets the label for the y-axis.

Parameters:

txt (str) – The label text for the y-axis.
kwargs (dict, optional) – Additional keyword arguments passed to ax.set_ylabel(), such as: - fontsize : int or float, optional - fontweight : {‘normal’, ‘bold’, ‘heavy’, ‘light’, ‘ultrabold’, ‘ultralight’}, optional - color : str, optional (e.g., ‘red’, ‘blue’, etc.)

Returns:

self – The Viz object itself, allowing for method chaining.

Return type: