Module Reference

Trainer extensions

class chainerui.extensions.CommandsExtension(trigger=(1, 'iteration'), receivers={}, file_name='commands')

Trainer extension to enable command operation by output file

This extension monitors a file for command created on trainer.out path, and execute each command when append the file.

Asset summaries

chainerui.summary.set_out(path)

Set output path.

Summary module requires output directory. Once set output path using this function, summary module shares the path.

Parameters:path (str) – directory path of output.

chainerui.summary.image(images, name=None, ch_axis=1, row=0, mode=None, batched=True, out=None, subdir='', timeout=5, **kwargs)

Summarize images to visualize.

Array of images are converted as image format (PNG format on default), saved to output directory, and reported to the ChainerUI server. The images are saved every called this function. The images will be shown on assets endpoint vertically. If need to aggregate images in a row, use reporter().

Examples of how to set arguments:

>>> from chainerui import summary
>>> summary.set_out('path/to/log')  # same as 'log' file directory
>>>
>>> x = np.zeros((10, 3, 5, 5))  # = [Batchsize, Channel, Height, Width]
>>> summary.image(x, name='test')  # images are tiled as 1x10
>>> summary.image(x, name='test', row=2)  # images are tiled as 2x5
>>>
>>> x = np.zeros((3, 5, 5))  # = [C, H, W]
>>> # need to set as a non-batched image and channel axis explicitly
>>> summary.image(x, name='test', ch_axis=0, batched=False)
>>>
>>> x = np.zeros((10, 5, 5, 3))  # = [B, H, W, C]
>>> # need to set channel axis explicitly
>>> summary.image(x, name='test', ch_axis=-1, row=2)
>>>
>>> x = np.zeros((5, 5, 3))  # = [H, W, C]
>>> # need to set as a non-batched image
>>> summary.image(x, name='test', ch_axis=-1, batched=False)
>>>
>>> x = np.zeros((10, 5, 5))  # = [B, H, W], grayscale images
>>> summary.image(x, name='test')  # image are tiled as 1x10
>>> summary.image(x, name='test', row=2)  # image are tiled as 2x5
>>>
>>> x = np.zeros((5, 5)) # = [H, W], a grayscale image
>>> # need to set as a non-bathed image
>>> summary.image(x, name='test', batched=False)

Add description about the image:

>>> summary.image(x, name='test', epoch=1, iteration=100)
>>> # 'epoch' and 'iteration' column will be shown.

Parameters:

• images (numpy.ndarray or cupy.ndarray or chainer.Variable) – batch of images. If Number of dimension is 3 (or 2 when set batched=False), the pixels assume as black and white image.
• name (str) – name of image. set as column name. when not setting, assigned 'image'.
• ch_axis (int) – index number of channel dimension. set 1 by default. if the images don’t have channel axis, this parameter is ignored.
• row (int) – row size to visualize batched images. when set 0, show on unstuck. if images set only one image, the row size will be ignored.
• mode (str) – if the images are not RGB or RGBA space, set their color space code. ChainerUI supports ‘HSV’.
• batched (bool) – if the image is not batched, set False.
• out (str) – directory path of output.
• subdir (str) – sub-directory path of output.
• **kwargs (dict) – key-value pair to show as description. regardless of empty or not, timestamp on created the image is added.

chainerui.summary.audio(audio, sample_rate, name=None, out=None, subdir='', timeout=5, **kwargs)

Summarize audio files to listen on a browser.

An sampled array is converted as WAV audio file, saved to output directory, and reported to the ChainerUI server. The audio file is saved every called this function. The audio file will be listened on assets endpoint vertically. If need to aggregate audio files in row, use reporter().

Example of how to set arguments:

>>> from chainerui import summary
>>> summary.set_out('path/to/output')
>>> rate = 44100
>>>
>>> sampled_array = np.random.uniform(-1, 1, 16000)
>>> summary.audio(sampled_array, rate, name='test')
>>> # sampled_array can be listened on a browser.

Add description about the audio file:

>>> summary.audio(
...     sampled_array, rate, name='test', epoch=1, iteration=100)
>>> # 'epoch' and 'iteration' column will be shown.

Parameters:

• audio (numpy.ndarray or cupy.ndarray or chainer.Variable) – sampled wave array.
• sample_rate (int) – sampling rate.
• name (str) – name of image. set as column name. when not setting, assigned 'audio'.
• out (str) – directory path of output.
• subdir (str) – sub-directory path of output.
• **kwargs (dict) – key-value pair to show as description. regardless of empty or not, timestamp on created the image is added.

chainerui.summary.text(text, name=None, out=None, timeout=5, **kwargs)

Summarize texts to show on a browser.

Texts generated by training model is saved as asset and reported to the ChainerUI.

Parameters:

• text (str) – generated text.
• name (str) – name of text. set as column name. when not setting, assigned 'text'.
• out (str) – directory path of output.
• **kwargs (dict) – key-value pair to show as description. regardless of empty or not, timestamp on created the text is added.

chainerui.summary.reporter(prefix=None, out=None, subdir='', timeout=5, **kwargs)

Summarize media assets to visualize.

reporter function collects media assets by the with statement and aggregates in same row to visualize. This function returns an object which provides the following methods.

• image(): collect images. almost same as image()
• audio(): collect audio. almost same as audio()
• text(): collect text. almost same as text()

Example of how to set several assets:

>>> from chainerui import summary
>>> summary.set_out('path/to/output')  # same as 'log' file directory
>>>
>>> image_array1 = np.zeros((1, 3, 224, 224))
>>> image_array2 = np.zeros((1, 3, 224, 224))
>>> audio_array = np.random.uniform(-1, 1, 16000)
>>>
>>> from chainerui.summary import reporter
>>> with reporter(epoch=1, iteration=10) as r:
...     r.image(image_array1)
...     r.image(image_array2)
...     r.audio(audio_array, 44100)
>>> # image_array1 and image_array2 are visualized on a browser
>>> # audio_array can be listened on a browser

Parameters:

• prefix (str) – prefix of column name.
• out (str) – directory path of output.
• subdir (str) – sub-directory path of output.
• **kwargs (dict) – key-value pair to show as description. regardless of empty or not, timestamp is added.

_Reporter.image(images, name=None, ch_axis=1, row=0, mode=None, batched=True, subdir='')

Summarize images to visualize.

Parameters:

• images (numpy.ndarray or cupy.ndarray or chainer.Variable) – batch of images. If Number of dimension is 3 (or 2 when set batched=False), the pixels assume as black and white image.
• name (str) – name of image. set as column name. when not setting, assigned 'image' + sequential number.
• ch_axis (int) – index number of channel dimension. set 1 by default. if the images don’t have channel axis, this parameter is ignored.
• row (int) – row size to visualize batched images. when set 0, show on unstuck. if images set only one image, the row size will be ignored.
• mode (str) – if the images are not RGB or RGBA space, set their color space code. ChainerUI supports ‘HSV’.
• batched (bool) – if the image is not batched, set False.
• subdir (str) – sub-directory path of output.

_Reporter.audio(audio, sample_rate, name=None, subdir='')

Summarize audio to listen on web browser.

Parameters:

• audio (numpy.ndarray or cupy.ndarray or chainer.Variable) – sampled wave array.
• sample_rate (int) – sampling rate.
• name (str) – name of image. set as column name. when not setting, assigned 'audio' + sequential number.
• subdir (str) – sub-directory path of output.

_Reporter.text(text, name=None)

Summarize texts to show on a browser.

Parameters:

• text (str) – generated text.
• name (str) – name of text. set as column name. when not setting, assigned 'text'.

Web client

chainerui.init(url=None, project_name=None, result_name=None, overwrite_result=False, crawlable=False, conditions=None)

Initialize client tools

Initialize client object, then setup project and result. Even if some errors are occurred, client object is set None and without exception.

Parameters:

• url (str) – ChainerUI server URL. set 'localhost:5000' on default.
• project_name (str) – project name is set from project path, working directory on default. If set, ChainerUI shows the name instead the project path.
• result_name (str) – result name is set project path + start time on default. If set, ChainerUI shows the name + start time instead the path.
• overwrite_result (bool) – the client tool make different job results every time on default. If set True, the client tool posts logs on the same result.
• crawlable (bool) – to inform server not to crawl physical logs.
• conditions (argparse.Namespace or dict) – Experiment conditions to show on a job table. Keys are show as table header and values are show at a job row.

chainerui.log_reporter()

Log reporter via POST API

Return a callback function to post a log to a ChainerUI server. If the initialization (see chainerui.init()) is failed, the callback function do nothing when called. If the initialization is done but fail to send the log by some kind of error, the log is cached and try to post it next time with new one.

The callback function is expected to use with postprocess option of Chainer LogReport extension:

>>> chainerui.init()
>>>
>>> trainer = chainer.training.Trainer(...)
>>> trainer.extend(
>>>     extensions.LogReport(postprocess=chainerui.log_reporter()))

Returns:function. Return type:func

chainerui.log(value)

Send log

Send log data and will be shown ad training log on web browser.

Example:

>>> chainerui.init()
>>> # ...
>>> stats = {
>>>     'epoch': epoch,
>>>     'train/loss': loss,
>>>     }
>>> chainerui.log(stats)

Parameters:value (dict) – target log.

Utilities

class chainerui.utils.LogReport(out_path, conditions=None)

Util class to output ‘log’ file.

This class supports to output ‘log’ file. The file spec follows chainer.extensions.LogReport, however, ‘epoch’ and ‘iteration’ are not set automatically, and need to set these values.

Parameters:

• out_path (str) – Output directory name to save conditions.
• conditions (argparse.Namespace or dict) – Experiment conditions to show on a job table. Keys are show as table header and values are show at a job row.

chainerui.utils.save_args(conditions, out_path)

A util function to save experiment condition for job table.

Parameters:

• conditions (argparse.Namespace or dict) – Experiment conditions to show on a job table. Keys are show as table header and values are show at a job row.
• out_path (str) – Output directory name to save conditions.

External library support

class chainerui.contrib.ignite.handler.OutputHandler(tag, metric_names=None, output_transform=None, another_engine=None, global_step_transform=None, interval_step=-1)

Handler for ChainerUI logger

A helper for handler to log engine’s output, specialized for ChainerUI. This handler sets ‘epoch’, ‘iteration’ and ‘elapsed_time’ automatically, these are default x axis to show.

from chainerui.contrib.ignite.handler import OutputHandler
train_handler = OutputHandler(
    'train', output_transform=lambda o: {'param': o})
val_handler = OutputHandler('val', metric_names='all')

Parameters:

• tag (str) – use for a prefix of parameter name, will show as {tag}/{param}
• metric_names (str or list) – keys names of list to monitor. set 'all' to get all metrics monitored by the engine.
• output_transform (func) – if set, use this function to convert output from engine.state.output
• another_engine (ignite.engine.Engine) – if set, use for getting global step. This option is deprecated from 0.3.
• global_step_transform (func) – if set, use this to get global step.
• interval_step (int) – interval step for posting metrics to ChainerUI server.

class chainerui.contrib.ignite.handler.ChainerUILogger

Logger handler for ChainerUI

A helper logger to post metrics to ChainerUI server. Attached handlers are expected using chainerui.contrib.ignite.handler.OutputHandler. A tag name of handler must be unique when attach several handlers.

from chainerui.contrib.ignite.handler import OutputHandler
train_handler = OutputHandler(...)
val_handler = OutputHandler(...)

from ignite.engine.engine import Engine
train_engine = Engine(...)
eval_engine = Engine(...)

from chainerui.contrib.ignite.handler import ChainerUILogger
logger = ChainerUILogger()
logger.attach(
    train_engine, log_handler=train_handler,
    event_name=Events.EPOCH_COMPLETED)
logger.attach(
    eval_engine, log_handler=val_handler,
    event_name=Event.EPOCH_COMPLETED)