3.1.7. Option visualization

3.1.7.1. Description

Applications that enable visualize data anywhere in any stages through minimal calling. Helpful for data diagnosis, position and orientation checking (specifically for medical images), making analysis and summary, as well as result export. Running of this module requires pyqtgraph and one of compatible backends. All object listed here have been integrated into the entry of info.vis.

GrpSettings	configuration for plotting group data.
FigConfigs	default figure configuration container.
Canvas	generic visualization utility.
ImageViewer	interactive viewer for 3D image.

3.1.7.2. Docstrings

class GrpSettings

configuration for plotting group data. arguments vary among groups should to be listed as the identical size as the number of groups.

Arguments:

Parameters:

kwargs (dict) – initiate using keywords and values; no assignment for empty dict {} as default

Variables:

~verbosity (bool) – show warning or not; False as default

Returns:

figure configuration dict

Return type:

GrpSettings

Raises:

TypeError – if name is not assigned properly

Property:

sub:

intrinsic number of groups for valid iteration.

groups:

tuple composed of plot configuration for each group. prompt UserWarning if self adaption run due to length of list container does not match self.sub if ~verbosity is True.

Methods:

update:

return a copy of self. can be updated from kwargs

Examples:

Code 3.134 customized scatter plot

from info.vis import visualization as vis
import pyqtgraph as pg
import numpy as np

# prepare data
mvn, r_mu, r_sigma = (np.random.multivariate_normal, (lambda: np.random.randint(0, 10, 2)),
                      (lambda: np.diag(np.random.random(2))))
groups = [mvn(mean=r_mu(), cov=r_sigma(), size=_).T for _ in [20, 40, 30]]
x, y = np.array([v for v, _ in groups], dtype=object), np.array([v for _, v in groups], dtype=object)

# assign plot configuration for 3 groups via GrpSettings:
config = vis.GrpSettings(**{'pen': [pg.mkPen((0, 0, 0, 0)) for _ in range(3)],
                            'symbol': ['star', 'd', '+'],
                            'symbolSize': 15,
                            'symbolBrush': [_ for _ in 'rgb'],
                            'name': [f"type_{_+1}" for _ in range(3)]})

# scatter with customized configuration:
app = vis.Canvas(fig_type='scatter', fig_configs=config, cvs_main='scatter figure',
                 cvs_left_label='y_value', cvs_bottom_label='x_value', cvs_legend=True)
app.view(data=(x, y))

The final plot will be:

Figure 3.1 canvas used for customized scatter plot

See also:

• Canvas

Logs:

Added in version 0.0.2.

– Created by Chen Zhang; Last updated on 01:34, 2025-09-06

class FigConfigs

default figure configuration container. support types of line, scatter, histogram, beeswarm, box, and image. all properties in FigConfigs are GrpSettings instances.

Arguments:

Returns:

a basic figure configuration container

Return type:

FigConfigs

Property:

Line:

basic figure configuration for line plot.

Scatter:

basic figure configuration for scatter plot.

Histogram:

basic figure configuration for histogram plot.

Beeswarm:

basic figure configuration for beeswarm plot.

Box:

basic figure configuration for box plot.

Radar:

basic figure configuration for radar plot.

Image:

basic figure configurations for image viewer.

Examples:

With FigConfigs, it is handy to visualize data via Canvas:

Code 3.135 scatter using default configuration

from info.vis import visualization as vis
import numpy as np

# prepare data
mvn, r_mu, r_sigma = (np.random.multivariate_normal, (lambda: np.random.randint(0, 10, 2)),
                      (lambda: np.diag(np.random.random(2))))
groups = [mvn(mean=r_mu(), cov=r_sigma(), size=_).T for _ in [20, 40, 30]]
x, y = np.array([v for v, _ in groups], dtype=object), np.array([v for _, v in groups], dtype=object)

# scatter with default configuration:
vis.Canvas.play(data=(x, y), fig_type='scatter', fig_configs=vis.FigConfigs.Scatter,
                cvs_main='scatter figure', cvs_left_label='y_value', cvs_bottom_label='x_value',
                cvs_legend=True)

Or customized some arguments based on FigConfigs. For example, use the default histogram configuration with width as 0.2.

Code 3.136 histogram with customized width

vis.Canvas.play(data=y, fig_type='histogram', fig_configs=vis.FigConfigs.Histogram.update(width=0.2),
                cvs_main='histogram figure', cvs_left_label='y_value', cvs_bottom_label='x_value',
                cvs_legend=True)

See also:

• GrpSettings

• Canvas

Logs:

Added in version 0.0.2.

Changed in version 0.0.3: include default configuration for radar plot.

– Created by Chen Zhang; Last updated on 01:34, 2025-09-06

class Canvas

generic visualization utility. making line, scatter, histogram, beeswarm, box, heatmap, radar, pie, contour figures for group and ungrouped data, or viewer for images.

Arguments:

Parameters:

• data (Union[numpy.ndarray, tuple[numpy.ndarray, numpy.ndarray]]) – specified data during initialize a Canvas instance; None as default

• fig_type (Literal[...]) – figure type for visualizer; should be option among 'line', 'scatter', 'histogram', 'beeswarm', 'box', 'heatmap', 'radar', 'pie', 'contour' and 'image'; 'line' as default

• fig_configs (GrpSettings) – instance of GrpSettings; FigConfigs is the collection of default configurations for all figure types; None as default will heuristically guess then configure from fig_type

• cvs_main (str) – main title for application window; 'info' as default

• cvs_size (tuple[int, int]) – main window size; None as default for applying (640, 480) on line, scatter, histogram, beeswarm, box plots or image viewer, (560, 560) on radar and pie plots

• cvs_background (str) – background color for canvas; 'w' as default

• cvs_grid (dict) – trigger to (un)enable grids of x and y in figure; {'x': True, 'y': True} as default

• cvs_title (str) – title of figure; None as default

• cvs_title_configs (dict) – configurations of figure title; {'color': 'k', 'size': '15pt'} as default

• cvs_left_label (str) – text content for left label; None as default

• cvs_bottom_label (str) – text content for bottom label; None as default

• cvs_label_configs (dict) – configurations of left and bottom labels; {'color': 'b', 'font-size': '13pt'} as default

• cvs_legend (bool) – trigger to (un)enable figure legend; False as default

• cvs_axes (dict[str, bool]) – (un)display axes triggers; {'left': True, 'top': False, 'right': False, 'bottom': True} as default

Returns:

a visualization application

Return type:

Canvas

Raises:

ValueError – invalid argument exists

Methods:

view:

show figure. data can be updated.

save:

static method; save_as to specify the file name for figure to be exported; figure.png as default

play:

static method; create a new canvas then show figure. all **kwargs assignment supported.

Examples:

Use Canvas to build line plot:

Code 3.137 Canvas for line plot

from info.vis import visualization as vis
import numpy as np

# prepare data
mvn, r_mu, r_sigma = (np.random.multivariate_normal, (lambda: np.random.randint(0, 10, 2)),
                      (lambda: np.diag(np.random.random(2))))
groups = [mvn(mean=r_mu(), cov=r_sigma(), size=_).T for _ in [20, 40, 30]]
x, y = np.array([v for v, _ in groups], dtype=object), np.array([v for _, v in groups], dtype=object)

vis.Canvas.play(data=y, fig_type='line', cvs_main='line figure', cvs_left_label='y_value', cvs_legend=True)

Figure 3.2 canvas used for line plot

And for scatter plot:

Code 3.138 Canvas for scatter plot

vis.Canvas.play(data=(x, y), fig_type='scatter', cvs_main='scatter figure', cvs_left_label='y_value',
                cvs_bottom_label='x_value', cvs_legend=True)

Figure 3.3 canvas used for scatter plot

And also for histogram plot:

Code 3.139 Canvas for histogram plot

vis.Canvas.play(data=y, fig_type='histogram', fig_configs=vis.FigConfigs.Histogram.update(width=0.2),
                cvs_main='histogram figure', cvs_left_label='y_value', cvs_bottom_label='x_value',
                cvs_legend=True)

Figure 3.4 canvas used for histogram plot

Also support for beeswarm plot:

Code 3.140 Canvas for beeswarm plot

vis.Canvas.play(data=y, fig_type='beeswarm', cvs_main='beeswarm figure', cvs_left_label='y_value',
                cvs_legend=True)

Figure 3.5 canvas used for beeswarm plot

For making box plot:

Code 3.141 Canvas for box plot

vis.Canvas.play(data=y, fig_type='box', cvs_main='box figure', cvs_left_label='y_value', cvs_legend=True)

Figure 3.6 canvas used for box plot

For making heatmap plot:

Code 3.142 Canvas for heatmap plot

vec, mat = np.random.random(10), np.random.random((10, 4))
config1 = vis.FigConfigs.Heatmap.update(tags=np.array([f"V{_+1}" for _ in range(10)]))
config2 = vis.FigConfigs.Heatmap.update(tags=np.array([f"S{_+1}" for _ in range(10)]))
vis.Canvas.play(data=vec, fig_type='heatmap', fig_configs=config1, cvs_main='heatmap figure 1')
vis.Canvas.play(data=mat, fig_type='heatmap', fig_configs=config2, cvs_main='heatmap figure 2')

Figure 3.7 canvas used for heatmap plot

For radar plot:

Code 3.143 Canvas for radar plot

# generic radar plot
vecs = np.array([np.random.randint(5, 10, 5) + np.random.random(5) for _ in range(3)])
vis.Canvas.play(data=vecs, fig_type='radar', cvs_main='radar figure', cvs_legend=True)

# or be more customized
import pyqtgraph as pg
rescale_vecs, rescale_params = vis.rescale_radar(data=vecs, scale_base=2.3)
cus_pen = pg.mkPen(color="#6a6da9", style=pg.QtGui.Qt.PenStyle.DashLine)
vis.Canvas.play(data=rescale_vecs, fig_type='radar', cvs_main='radar figure', cvs_legend=True,
                fig_configs=vis.FigConfigs.Radar.update(name=['var1', 'var2', 'var3'],
                                                        rescale_labels=rescale_params,
                                                        dim_names=['d1', 'd2', 'd3', 'd4', 'd5'],
                                                        n_grids=5, pen_grids=cus_pen))

Figure 3.8 canvas used for radar plot

For pie plot:

Code 3.144 Canvas for pie plot

frac = np.array([20, 15, 40, 25])
vis.Canvas.play(data=frac, fig_type='pie', cvs_main='pie figure', cvs_legend=True)

Figure 3.9 canvas used for pie plot

For contour plot:

Code 3.145 Canvas for iso-contour plot

_cont = (lambda x1, x2: (1-x1/2+x1**5+x2**3)*np.exp(-x1**2-x2**2))
dens = _cont(*np.meshgrid(*[np.linspace(-3, 3, 256) for _ in range(2)]))
vis.Canvas.play(data=dens, fig_type='contour', fig_configs=vis.FigConfigs.Contour.update(rect=(-3, -3, 6, 6)))

Figure 3.10 canvas used for contour plot

Use as an image viewer:

Code 3.146 Canvas as image viewer

from info.ins import datasets
vis.Canvas.play(data=datasets.cat(), fig_type='image', cvs_main='image viewer')

Figure 3.11 canvas used for image viewer

Note:

If IndexError raised, reassign name in fig_configs by GrpSettings, or by updating default configuration set FigConfigs.

See Also:

• GrpSettings

• FigConfigs

Logs:

Added in version 0.0.2.

Changed in version 0.0.3: support heatmap, radar, and pie plot. heuristically guess and configuration of fig_configs.

Changed in version 0.0.4: support writing image via save method. no limitation for 10 groups of data in maximum anymore.

Changed in version 0.0.5: support iso contour plot. attach interactive color bar item to heatmap and contour plot. add logic of length check, as well as horizontal label trigger for tags in heatmap.

– Created by Chen Zhang; Last updated on 01:34, 2025-09-06

class ImageViewer

interactive viewer for 3D image.

Arguments:

Parameters:

gui_size (tuple[int, int]) – size for main window of application; (1000, 1000) as default

Returns:

an ImageViewer instance

Return type:

ImageViewer

Methods:

view:

view 3D image.

Variables:

• data (ndarray) – 3-dimensional ndarray

• mask (Optional[list[ndarray]]) – list of bool ndarray with 3 dimension; None as default for no mask

• spacing (Iterable[Numeric]) – iterable object with length of 3 to specify spacing values; (1, 1, 1) as default

• origin (Iterable[Numeric]) – iterable object with length of 3 to specify origin values; (0, 0, 0) as default

• img_title (Optional[str]) – title to be displayed in main window; None as default

• levels (tuple[Numeric, Numeric]) – initial low and high values of grey level; values should be numeric; if those values range from 0. to 1. simultaneously, grey level percentage will be applied; (0.688, 0.997) as default

• palettes (Optional[list[tuple[Numeric, ...]]]) – RGB shader colors if mask was assigned; value ranges from 0.0 to 1.0 in each channel; None as default for random colors; if specified, substitution for mask shaders takes places sequentially

play:

static method; create a new ImageViewer then view 3D image. all parameters defined the same as those when calling view.

Examples:

Code 3.147 interactively view 3D image

from info.vis import ImageViewer
img, spacing, origin = ...  # ndarray, len(spacing) == 3, len(origin) == 3

# simple 3D image viewer:
ImageViewer.play(data=img)

# 3D image viewer with spacing:
ImageViewer.play(data=img, spacing=spacing)

# 3D image viewer with spacing and origin
ImageViewer.play(data=img, spacing=spacing, origin=origin)

Following figure for preview:

Figure 3.12 ImageViewer for 3D image

Or if the images have the corresponding segmentations:

Code 3.148 interactively view 3D image with segmentation

segs = ...  # list of bool ndarray

# 3D image viewer with image and segmentations:
ImageViewer.play(data=img, spacing=spacing, origin=origin, mask=[segs])

Figure 3.13 ImageViewer for 3D image with segmentation

Logs:

Added in version 0.0.2.

Changed in version 0.0.4: Implementation uses linked views, instead of projection with sliced segmentation line. Support origin, colored segmentations, and 3D visualization with OpenGL rendering.

Changed in version 0.0.5: No limitation for mask numbers during visualization (3 in maximum the former); fix the exception raised in sequential playing.

– Created by Chen Zhang; Last updated on 01:34, 2025-09-06

---

Authors:

Chen Zhang

Version:

0.0.5

Created on:

Jun 29, 2023