Plotting Utility Functions

This module provides access to functions to perform plotting and visualization operations.

plots_enhancer(fontsize=22, fontfamily='sans-serif', fontweight='bold', usetex=True)

Basic manipultation of matplotlib plotting parameters

show_axis_grids(ax, show_major=True, show_minor=True, major_color='black', minor_color='gray', major_alpha=0.75, minor_alpha=0.5)

Given an axis, show the major/minor axis grids

unique_colors(size, random_seed=2456, gradual=False)

get uniqe random colors on the format (R, G, B) to be used for plotting with many lines

draw_curly_brace(ax, span, draw_on='x', location='low', padding=None, padding_scale=0.11, brace_scale=0.04, curl_scale=0.12, linewidth=3, color='black', text=None, text_color='black', text_rotation=None, text_position=None, text_padding_scale=0.1)

Draw a curly brace with optional text on a given range on either x or y axis. This is very useful to define double axes, and range of values, etc.

All positions and sizes are in axes units (i.e., following x-values or y-values based on`draw_on`)

Parameters:

• ax – matplotlib axis to draw curly brace on (one of it’s plot axes (x/y))

• span (tuple) – (from, to) points to draw the curly brace (on either x or y axis)

• draw_on (str) – either ‘x’ to draw on x-axis or ‘y’ for y-axis

• location (str) – either ‘low’ or ‘high’ to draw at the lower level of values or the high levels; on x-axis this is bottom vs. top of the figure Note that if the axis is flipped (e.g., imshow is used, you need to invert the axis first, then invert it againQ)

• padding – exact padding; values to push the brace away from the axis

• padding_scale (float) – fraction used to push the brace away from the axis; padding value is evaluated as a fraction of the opposite axis span/values ignored if padding is not None

• brace_scale (float) – scale the brace by a factor after calculation if needed; default 1.0

• curl_scale (float) – fraction of the opposit axis to use for calculating the curl/radius (rounded curve) of the brace.

• linewidth (float) – linewidth parameter for line plotting

• color – line color

• text – text to add to the brace (can be put anywhere) if not None

• text_color – color of the text

• text_rotation – rotation angle of the text; default is 0 if draw_on is ‘x’, 90 if ‘draw_on’ is ‘y’

• text_position – position (x, y) for the text

• text_padding_scale – used if text_position is None; padding is this percentage (from text center) multiplied by the hight (e.g., for x-axis plotting) of the brace

plot_sampling_results(sample, log_density=None, map_estimate=None, xlim=None, ylim=None, title=None, grid_size=200, labels=None, linewidth=0.5, markersize=2, fontsize=18, fontweight='bold', keep_plots=False, output_dir=None, filename_prefix='Sampling_Results', verbose=False)

Visualize a sample collected from a specific distribution with the passed log_density function

Parameters:

• sample (list) – a list of sample points

• log_density (callable) – the logarithm of the density function where sample is collected from

• map_estimate – a sample point that estimates the maximum aposteriori (MA) point

• xlim – x-limit of plots (only used for 2D case)

• ylim – y-limit of plots (only used for 2D case)

• title – title to be added to created plot(s)

• grid_size – number of discretization grid points to create 2D mesh for plots (only used for 2D case)

• labels – iterable of labels to be used for the variables on plots (X_i auto used if not passed)

• linewidth – width of lines (e.g., for contour plots)

• markersize – markers in scatter plots

• fontsize – general font size on all plots

• fontweight – font weighti

• keep_plots – if False all plots will be closed by calling matplotlib.pyplot.close('all')()

• output_dir – location to save all generated files. If None, the current working directory is used.

• filename_prefix – Prefix for file naming

• verbose (bool) – screen verbosity

Remarks:

Set keep_plots to True, for example, if you are doing interactive plotting or using a notebook to show plots.

plot_sensors(sensors_coordinates, ax=None, clean_xy_ticks=False, xlim=None, ylim=None, zlim=None, title=None, legend_title=None, fontsize=16, show_grid=True, grid_linewidth=0.01, grid_linecolor='#000C67', grid_alpha=0.5, active_sensors_coordinates=None, annotate_sensors=False, show_axis_frame=True, show_legend=True, save_to_file=None, keep_plots=True, verbose=False)

Plot the domain, with optional buildings, and optional sensor locations and prediction coordinates (for goal-oriented work)

Parameters:

• sensors_coordinates – list of 2-len entries [(x, y)] of sensor locations.

• ax – either None or a matplotlib axis to plot on. If None, a new figure is created.

• xy_ticks (bool clean) – whether to show the x and y ticks. Default is True

• xlim – tuple of (xmin, xmax) to set the x-axis limits. Default is None

• ylim – tuple of (ymin, ymax) to set the y-axis limits. Default is None

• zlim – tuple of (zmin, zmax) to set the z-axis limits.

• title – string to set the title of the plot. Default is None

• show_grid (bool) – whether to show the mesh. Default is True

• grid_linewidth (float) – linewidth of the mesh. Default is 0.4

• grid_linecolor (str) – color of the mesh. Default is #000C67

• grid_alpha (float) – alpha value of the mesh. Default is 0.5

• fontsize (int) – fontsize of the plot. Default is 16

• active_sensors_coordinates – a list of 2-len entries [(x, y)] of active sensor locations to highlight.

• annotate_sensors (bool) – whether to annotate the sensors. Default is None.

• show_axis_frame (bool) – whether to show the axis frame. Default is False

• show_legend (bool) – Default True

• save_to_file – string of the path to save the plot to. Default is None

• keep_plots – if False all plots will be closed by calling matplotlib.pyplot.close('all')()

• verbose (bool) – screen verbosity

Returns:

ax, the axis on which the plot is created. This is set to None if keep_plots is set to False

add_circle_to_axis(ax, origin, radius, facecolor='#FF0000', edgecolor='#000000', fill=True, label=None, alpha=1, circle_hatch=None, zorder=1)

Add a circle with the passed specificication to axis.

Parameters:

• ax (matplotlib.pyplot.Axes) – the axis whose dimensions are to be checked.

• origin – a tuble containing the three coordinates of the origin (x0, y0, …)

• radius

• facecolor

• edgecolor

• fill

• label

• alpha

• circle_hatch

• zorder

Returns:

the passed axis ax

Raises:

TypeError if the pssed axis ax is not an instance of matplotlib.pyplot.Axes.

Raises:

TypeError if the origin does not match the dimensions/projection of the plot. origin is expected to be a iterable (e.g., tuble of length 2 if projection is 2d, and a tuple of length 3 for 3d projection. Some flexibility is allowed here; see the note below.

Note:

We allow some flexibility in the origin where origin of length 2 can be passed for 3d plot. In this case, we set the third entry to 1.

axis_cartesian_dimensions(ax)

Given an axis (instance of matplotlib.pyplot.Axes), check the number of dimensions, assuming a cartesian grid. This checks if the axis has get_zlim attribute or not, since there is no built-in function to do that.

Parameters:

ax (matplotlib.pyplot.Axes) – the axis whose dimensions are to be checked.

Returns:

an integer set to either 2 (if 2d projection), or 3 (if 3d projection) as the number of cartesian dimensions of the axis

Raises:

TypeError if the pssed axis ax is not an instance of matplotlib.pyplot.Axes.

add_box_to_axis(ax, origin, width, depth, height=0, facecolor='#111111', edgecolor='#000000', fill=True, label=None, box_hatch='x', box_text=None, round_corners=False, alpha=1, zorder=1)

construct the 4 faces of a box-base given it’s origin and width (across x axis), depth (across y axix). The constructed rectangle is to be added the axis of the passed figure handle

Parameters:

• ax (matplotlib.pyplot.Axes) – the axis whose dimensions are to be checked.

• origin – a tuble containing the three coordinates of the origin (x0, y0, …)

• depth

• height

• facecolor

• edgecolor

• fill

• label

• box_hatch

• box_text

• round_corners

• alpha

• zorder

Parm width:

Returns:

the passed axis ax

Raises:

TypeError if the pssed axis ax is not an instance of matplotlib.pyplot.Axes.

Raises:

TypeError if the origin does not match the dimensions/projection of the plot. origin is expected to be a iterable (e.g., tuble of length 2 if projection is 2d, and a tuple of length 3 for 3d projection. Some flexibility is allowed here; see the note below.

Note:

We allow some flexibility in the origin where origin of length 2 can be passed for 3d plot. In this case, we set the third entry to 1.

add_cube_to_axis(ax, origin, width, depth, height, color='blue', alpha=0.75, plot_corners=False, zorder=1)

construct the 8 faces of a cube given it’s origin and width (across x axis), depth (across y axix), and height (across z axis). The constructed cube is to be added the axis of the passed figure handle

Parameters:

• ax (matplotlib.pyplot.Axes) – the axis whose dimensions are to be checked.

• origin – a tuble containing the three coordinates of the origin (x0, y0, …)

• depth

• height

• color

• alpha

• plot_corners

• zorder

Parm width:

Returns:

the passed axis ax

Raises:

TypeError if the pssed axis ax is not an instance of matplotlib.pyplot.Axes.

Raises:

TypeError if the projection of the pssed axis ax is not ‘3d’.

Raises:

TypeError if the origin does not match the dimensions/projection of the plot. origin is expected to be a iterable (e.g., tuble of length 2 if projection is 2d, and a tuple of length 3 for 3d projection. Some flexibility is allowed here; see the note below.

Note:

We allow some flexibility in the origin where origin of length 2 can be passed for 3d plot. In this case, we set the third entry to 1.

add_3D_cylinder_to_axis(ax, x_center, y_center, radius, height, elevation=0, resolution=50, color='r', alpha=0.75, rstride=20, cstride=10, lable=None, zorder=1)

Plot/Add 3D cylinder to the passed asix (ax)

Parm ax:

axis handle

Parm x_center:

Parm y_center:

Parm radius:

Parm height:

Parm elevation:

Parm resolution:

Parm color:

Parm rstride:

Parm cstride:

Parm label:

string label to add on top of the cylinder

Returns:

the passed axis ax

Raises:

TypeError if the pssed axis ax is not an instance of matplotlib.pyplot.Axes.

Raises:

TypeError if the projection of the pssed axis ax is not ‘3d’.

ridgeline(ax, data, overlap=0, fill=True, labels=None, n_points=150)

Creates a standard ridgeline plot.

Parameters:

• ax – matplotlib axis to plot on.

• data – iterable of iterables, this can be a list of lists, a list of arrays, or a 2D numpy array, etc.

• overlap – overlap between distributions. 1 max overlap, 0 no overlap. Default is 0.

• fill – matplotlib color to fill the distributions. Default is True.

• labels – list of values to place on the y axis to describe the distributions.

• n_points – number of points to evaluate each distribution function. Default is 150.