alf.summary#

alf.summary.render#

class Image(img)[source]#

Bases: object

A simple image class.

Parameters: img (np.ndarray) – a numpy array image of shape [H,W] (gray-scale) or [H,W,3] (RGB).

property data#: Return the image numpy array which is always RGB.

classmethod from_pyplot_fig(fig, dpi=200)[source]#

Generate an Image instance from a pyplot figure instance.

Parameters

fig (pyplot.figure) – a pyplot figure instance
dpi (int) – resolution of the generated image

Returns

Return type

Image

classmethod pack_image_nest(imgs)[source]#

Given a nest of images, pack them into a larger image so that it has an area as small as possible. This problem is generally known as “rectangle packing” and its optimal solution is NP-complete.

Here we just rely on a third-party lib rpack that is used for building CSS sprites, for an approximate solution.

Parameters: imgs (nested Image) – a nest of Image instances
Returns: the big mosaic image
Return type: Image

resize(height=None, width=None)[source]#

Resize the image in-place given the desired width and/or height.

Parameters

height (int) – the desired output image height. If None, this will be scaled to keep the original aspect ratio if width is provided.
width (int) – the desired output image width. If None, this will be scaled to keep the original aspect ratio if height is provided.

property shape#: Return the shape of the image.

classmethod stack_images(imgs, horizontal=True)[source]#

Given a list/tuple of images, stack them in order either horizontally or vertically.

Parameters

imgs (list[Image]|tuple[Image]) – a list/tuple of Image instances
horizontal (bool) – if True, stack images horizontally, otherwise vertically.

Returns

the stacked big image

Return type

Image

enable_rendering(flag=True)[source]#

Enable rendering by flag.

Parameters: flag (bool) – True to enable, False to disable

is_rendering_enabled()[source]#: Return whether rendering is enabled.

render_action(name, action, action_spec, **kwargs)[source]#

An action renderer that plots agent’s action at one time step in a bar plot.

Parameters

name (str) – rendering identifier
action (nested Tensor) – a nested tensor where each element is a rank-1 (discrete) or rank-2 (continuous) tensor of batch size 1.
action_spec (nested TensorSpec) – a nested tensor spec with the same structure with action.
**kwargs – all other arguments will be directed to render_bar().

Returns

a structure same with action

Return type

nested Image

render_action_distribution(name, act_dist, action_spec, n_samples=500, n_bins=20, **kwargs)[source]#

An action distribution renderer that plots agent’s action distribution at one time step in a curve plot. Assuming action dims are independent, each action dim’s 1D distribution corresponds to a separate curve in the plot.

Parameters

name (str) – rendering identifier
act_dist (Distribution) – a nested tensor where each element is a action distribution of batch size 1.
action_spec (nested TensorSpec) – a nested tensor spec with the same structure with act_dist
n_samples (int) – number of samples for approximation
n_bins (int) – how many histogram bins used for approximation
**kwargs – all other arguments will be directed to render_curve()

render_bar(name, data, width=0.8, y_range=None, x_ticks=None, x_label=None, y_label=None, legends=None, legend_kwargs={}, annotate_format='%.2f', img_height=None, img_width=None, dpi=300, figsize=(2, 2), **kwargs)[source]#

Render bar plots.

Parameters

name (str) – rendering identifier
data (Tensor|np.ndarray) – a rank-1 or rank-2 tensor/np.array. Each value is the height of a bar. If rank-2, each row represents an array of bars. Bars of multiple rows will stack on each other.
width (float) – bar width
y_range (tuple[float]) – a tuple of (min_y, max_y) for showing on the figure. If None, then it will be decided according to the y values.
x_ticks (list[float]) – x ticks shown along x axis
x_label (str) – shown besides x-axis
y_label (str) – shown besides y-axis
legends (list[str]) – label for each curve. No legends are shown if None.
legend_kwargs (dict) – optional legend kwargs
annotate_format (str) – The format of the annotations on the bars to show the actual value represented by each bar. This should either use the string format method, e.g. “%.2f”, or be a matplotlib.ticker.Formatter.
img_height (int) – height of the output image
img_width (int) – width of the output image
dpi (int) – resolution of each rendered image
figsize (tuple[int]) – figure size. For the relationship between dpi and figsize, please refer to this post.
**kwargs – all other arguments to ax.bar().

Returns

an output image rendered for the tensor

Return type

Image

render_contour(name, data, x_ticks=None, y_ticks=None, x_label=None, y_label=None, font_size=7, img_height=None, img_width=None, dpi=300, figsize=(2, 2), flip_y_axis=True, **kwargs)[source]#

Render a 2D tensor as a contour.

Parameters

name (str) – rendering identifier
data (Tensor|np.ndarray) – a tensor/np.array of shape [H,W]. Note that the rows of data correspond to y (inverted) and columns correspond to x in the contour figure.
x_ticks (np.array) – A list of length W with x ticks.
y_ticks (np.array) – A list (from 0 to H-1) of length H with y ticks.
x_label (str) – label shown besides x-axis
y_label (str) – label shown besides y-axis
font_size (int) – font size for the numbers on the contour
img_height (int) – height of the output image
img_width (int) – width of the output image
dpi (int) – resolution of each rendered image
figsize (tuple[int]) –
figure size. For the relationship between dpi and figsize, please refer to this post.
flip_y_axis (bool) – whether flip the y axis. Flipping makes this consistent with heatmap regarding y axis.
**kargs – All other arguments that are forwarded to ax.contour.

Returns

an output image rendered for the tensor

Return type

Image

render_curve(name, data, x_range=None, y_range=None, x_label=None, y_label=None, legends=None, legend_kwargs={}, img_height=None, img_width=None, dpi=300, figsize=(2, 2), **kwargs)[source]#

Plot 1D curves.

Parameters

name (stor) – rendering identifier
data (Tensor|np.ndarray) – a rank-1 or rank-2 tensor/np.array. If rank-2, then each row represents an individual curve.
x_range (tuple[float]) – min/max for x values. If None, x is the index sequence of curve points. If provided, x is evenly spaced by (x_range[1] - x_range[0]) / (N - 1).
y_range (tuple[float]) – a tuple of (min_y, max_y) for showing on the figure. If None, then it will be decided according to the y values. Note that this range won’t change y data; it’s only used by matplotlib for drawing y limits.
x_label (str) – shown besides x-axis
y_label (str) – shown besides y-axis
legends (list[str]) – label for each curve. No legends are shown if None.
legend_kwargs (dict) – optional legend kwargs
img_height (int) – height of the output image
img_width (int) – width of the output image
dpi (int) – resolution of each rendered image
figsize (tuple[int]) –
figure size. For the relationship between dpi and figsize, please refer to this post.
**kwargs – all other arguments to ax.plot().

Returns

an output image rendered for the tensor

Return type

Image

render_heatmap(name, data, val_label='', row_ticks=None, col_ticks=None, row_labels=None, col_labels=None, cbar_kw={}, annotate_format='%.2f', font_size=7, img_height=None, img_width=None, dpi=300, figsize=(2, 2), **kwargs)[source]#

Render a 2D tensor as a heatmap.

Parameters

name (str) – rendering identifier
data (Tensor|np.ndarray) – a tensor/np.array of shape [H, W]
val_label (str) – The label for the rendered values.
row_ticks (list[float]) – List of row (y-axis) tick locations.
col_ticks (list[float]) – List of column (x-axis) tick locations.
row_labels (list[str]) – A list labels for the rows. Its length should be equal to that of row_ticks if row_ticks is not None. Otherwise, it should have a length of H.
col_labels (list[str]) – A list of labels for the columns. Its length should be equal to that of col_ticks if col_ticks is not None. Otherwise, it should have a length of W.
cbar_kw (dict) – A dictionary with arguments to matplotlib.Figure.colorbar.
annotate_format (str) – The format of the annotations on the heatmap to show the actual value represented by each heatmap cell. This should either use the string format method, e.g. “%.2f”, or be a matplotlib.ticker.Formatter. No annotation on the heatmap if this argument is ‘’.
font_size (int) – the font size of annotation on the heatmap
img_height (int) – height of the output image
img_width (int) – width of the output image
dpi (int) – resolution of each rendered image
figsize (tuple[int]) –
figure size. For the relationship between dpi and figsize, please refer to this post.
**kwargs – All other arguments that are forwarded to ax.imshow. For example, to specify the value range on the heatmap, we can use vmin and vmax.

Returns

an output image rendered for the tensor

Return type

Image

render_text(name, data, font_size=10, fig_width_per_char=0.1, fig_height=0.4, img_height=None, img_width=None, dpi=200, **kwargs)[source]#

Render a text string.

Parameters

name (str) – name of the text
data (str) – the string to be rendered
font_size (int) – text font size
fig_width_per_char (float) – the width of each character measured by figsize of plt.subplots().
fig_height (float) – the height of the text label measured by figsize of plt.subplots().
img_height (int) – height of the output image
img_width (int) – width of the output image
**kwargs – extra arguments forwarded to ax.text.

alf.summary.summary_ops#

Summary related functions.

class EnsureSummary[source]#

Bases: object

Ensure summaries are generated in an infrequent code block.

Sometime, a code block runs infrequently or with different frequencey compared to the summary_interval. This can lead to the problem that the summaries in this code block are not generated or generated rarely. This class is a helper to solve this problem.

# initialization. For example, in __init__
self.ensure_summary = EnsureSummary()

# Add the following line at somewhere where it can be reached at very global step
self.ensure_summary.tick()

# Run the infrequent code block in the ensure_summary context:
with self.ensure_summary:
    # the infrequent code block

tick()[source]#

create_summary_writer(summary_dir, flush_secs=10, max_queue=10)[source]#

Ceates a SummaryWriter that will write out events to the event file.

Parameters

summary_dir (str) –
flush_secs (int) – and summaries to disk. Default is every 10 seconds.
max_queue (int) – before one of the ‘add’ calls forces a flush to disk. Default is ten items.

Returns

SummaryWriter

disable_summary()[source]#: Disable summary.

embedding(name, data, step=None, class_labels=None, label_imgs=None)[source]#

Add embeddings to summary. The potentially high-dimensional embeddings will be projected down to either 2D or 3D for visualization, with several projection techniques to choose from in Tensorboard.

The visualized embeddings can be seen in the “PROJECTOR” page of Tensorboard.

Note: if this function is called multiple times, on the page there will be multiple visualizations, each for every call.

Parameters

name (str) – data identifier
data (Tensor | numpy.array) – a matrix of shape [N, D], where D is the dimensionality of the embedding.
step (int) – global step value to record. None for using get_global_counter().
class_labels (list[str]) – an optional list of class labels of length N can be provided, where each label corresponds to an embedding.
label_imgs (Tensor) – an optional tensor of shape [N, C, H, W]. Each label img corresponds to an embedding. Use this if you want to associate each embedding with an image for visualization.

enable_summary(flag=True)[source]#

Enable summary.

Parameters: flag (bool) – True to enable, False to disable

enter_summary_scope(method)[source]#

A decorator to run the wrapped method in a new summary scope.

The class the method belongs to must have attribute ‘_name’ and it will be used as the name of the summary scope.

Instead of using with alf.summary.scope(self._name): inside a class method, we can use @alf.summary.enter_summary_scope to decorate the method to have the benefit of cleaner code.

get_global_counter()[source]#

Get the global counter

Returns: the global int64 Tensor counter

histogram(name, data, step=None, bins=None, walltime=None, max_bins=None)[source]#

Add histogram to summary.

Parameters

name (str) – Data identifier
data (Tensor | numpy.array | str/blobname) – Values to build histogram
step (int) – Global step value to record. None for using get_global_counter()
bins (int|str) – Number of buckets or one of {‘tensorflow’,’auto’, ‘fd’, …}. This determines how the bins are made. You can find other options in: https://docs.scipy.org/doc/numpy/reference/generated/numpy.histogram.html
walltime (float) – Optional override default walltime (time.time()) seconds after epoch of event

images(name, data, step=None, dataformat='NCHW', walltime=None)[source]#

Add image data to summary.

Parameters

name (str) – Data identifier
data (Tensor | numpy.array) – image data
step (int) – Global step value to record. None for using get_global_counter()
dataformat (str) – one of (‘NCHW’, ‘NHWC’, ‘CHW’, ‘HWC’, ‘HW’, ‘WH’)
walltime (float) – Optional override default walltime (time.time()) seconds after epoch of event

increment_global_counter()[source]#

is_summary_enabled()[source]#: Return whether summary is enabled.

class push_summary_writer(writer)[source]#: Bases: object

class record_if(cond)[source]#

Bases: object

Context manager to set summary recording on or off according to cond.

Create the context manager.

Parameters: cond (Callable) – a function which returns whether summary should be recorded.

reset_global_counter()[source]#: Reset the global counter to zero.

scalar(name, data, step=None, walltime=None)[source]#

Addd scalar data to summary.

Note that data will be changed to float value (i.e. possible loss of precision). See https://github.com/pytorch/pytorch/blob/877ab3afe33eeaa797296d2794317b59e5ac90f4/torch/utils/tensorboard/summary.py#L175

Parameters

name (str) – Data identifier
data (float) – Value to save
step (int) – Global step value to record. None for using get_global_counter()
walltime (float) – Optional override default walltime (time.time()) seconds after epoch of event

class scope(name)[source]#

Bases: object

A context manager for prefixing summary names.

Example: ``` with alf.summary.scope(“root”):

alf.summary.scalar(“val”, 1) # tag is “root/val” with alf.summary.scope(“train”):

alf.summary.scalar(“val”, 1) # tag is “root/train/val”

```

Create the context manager.

Parameters: name (str) – name of the scope

property name#: Get the name of the scope.

scope_name()[source]#: Get the full name of the current summary scope.

set_default_writer(writer)[source]#: Set the default summary writer.

set_global_counter(counter)[source]#

should_record_summaries()[source]#

Whether summary should be recorded.

Returns

False means that all calls to scalar(), text(), histogram() etc: are not recorded.

Return type

bool

should_summarize_output(flag=None)[source]#

Get or set summarize output flag.

Parameters: flag (bool or None) – when provided, sets the flag, otherwise, return the stored _summarize_output flag.
Returns: bool for getter or None for setter.

text(name, data, step=None, walltime=None)[source]#

Add text data to summary.

Note that the actual tag will be name + “/text_summary” because torch adds “/text_summary to tag. See https://github.com/pytorch/pytorch/blob/877ab3afe33eeaa797296d2794317b59e5ac90f4/torch/utils/tensorboard/summary.py#L477

Parameters

name (str) – Data identifier
data (str) – String to save
step (int) – Global step value to record. None for using get_global_counter()
walltime (float) – Optional override default walltime (time.time()) seconds after epoch of event