Utils

import pyblaze.nn as xnn
import pyblaze.utils as U

This utility documentation encompasses contents from two modules, namely the nn.utils as well as the utils module.

Estimator

class pyblaze.nn.Estimator

Estimators are meant to be mixins for PyTorch modules. They extend the module with three additional methods:

• fit(…)

  This function optimizes the parameters of the model given some (input and output) data.

• evaluate(…)

  This function estimates the performance of the model by returning some suitable metric based on some (input and output) data. This metric is usually used in the fit method as well (e.g. an appropriate loss).

• predict(…)

  This function performs inference based on some (input) data. This method is usually tightly coupled with the model’s forward method, however, opens additional possibilities such as easy GPU support.

Usually, the module does not implement these method itself, unless training is tightly coupled with the model parameters. An example might be a linear regression module. Normally, however, the module is expected to implement the engine property-method. This engine class acts as a default engine to which the methods delegate their implementation. The arguments for the functions therefore depend on the particular engine that is being used.

property engine

Returns the engine for this model.

Returns

The engine class initialized with this model.

Return type

pyblaze.nn.BaseEngine

fit(*args, **kwargs)

Optimizes the parameters of the model based on input and output data. The parameters are passed to the train method of the model’s engine.

evaluate(*args, **kwargs)

Estimates the performance of the model by returning some metric based on input and output data. The parameters are passed to the evaluate method of the model’s engine.

predict(*args, **kwargs)

Performs inference based on some input data. The parameters are passed to the predict method of the model’s engine.

prepare_input(data)

Prepares the input for the engine. This enables passing other types of data instead of PyTorch data loaders when it is appropriate, making it easier to e.g. provide a Sklearn- like interface. By default, the data object is simply returned but subclasses may override this function as appropriate.

Parameters

data (object) – The data object passed to fit, evaluate or predict.

Returns

The iterable dataset to use for the engine’s data.

Return type

iterable

Training History

class pyblaze.nn.engine._history.History

This class summarizes metrics obtained during training of a model. This class should never be initialized outside of this framework.

classmethod load(file)

Loads the history object from the specified file.

Parameters

file (str) – The JSON file to load the history object from.

save(file)

Saves the history object to the specified file as JSON.

Parameters

file (str) – The file (with .json extension) to save the history to.

property keys

Returns the available keys that this history object provides. The keys are returned as sorted list.

property duration

Returns the duration that this history object recorded for the duration of the training.

inspect(metric)

Returns all the datapoints recorded for the specified metric along with their timestamps. If the timestamps are not required, the metric may also be accessed by simple dot notation on the history object.

Parameters

metric (str) – The name of the metric.

Returns

• list of object – The values recorded.

• list of float – The timestamps at which the values were recorded. Has the same length as the other list.

Progress

class pyblaze.utils.ProgressBar(iterable=None, denom=None, file=None, verbose=True)

The progress bar can be used to print progress for a specific task where either a specified number of work items or an iterable has to be processed. The progress bar also measures the execution time and provides an estimated remaining time for the operation. A common use case for the progress bar are for-loops where one work item is completed per iteration.

Examples

Iterate over a range of integers

for i in ProgressBar(4): # equivalently initialized as ProgressBar(range(4))
    time.sleep(2.5)

Iterate over an iterable of known length

l = [1, 5, 7]
for i in ProgressBar(l):
    time.sleep(2.5)

Iterate over an iterable of unknown size

it = (x + 1 for x in range(3))
for i in ProgressBar(it):
    time.sleep(1.5)

Visualize some complex manual progress

with ProgressBar() as p:
    time.sleep(3)
    p.step()
    for _ in range(10):
        time.sleep(0.1)
        p.step()
    for _ in range(5):
        time.sleep(0.4)
        p.step()

__init__(iterable=None, denom=None, file=None, verbose=True)

Initializes a new progress bar with the given number of work items.

Parameters

• iterable (int or iterable, default: None) – Either the number of work items to be processed or an iterable whose values are returned when iterating over this progress bar. If no value is given, this iterable can not be used within for-loops.

• denom (int, default: None) – If the first parameter is an integer, this value may also be given. In that case, the first parameter acts as the numerator and the second parameter as the denominator. The rounded up division of these two values is used as the number of work items.

• file (str, default: None) – If given, defines the file where the progress bar should write to instead of the command line. Intermediate directories are created automatically.

• verbose (bool, default: True) – Whether to actually log anything. This is useful in cases where logging should be turned of dynamically without introducing additional control flow.

start()

Starts to record the progress of the operation. Time measuring is initiated and the beginning of the operation is indicated on the command line.

Note

This method should usually not be called explicitly. It is implicitly called at the beginning of a with statement.

step()

Tells the progress bar that one work item has been processed. The command line output is updated as well as the estimated finishing time of the operation.

If used from within a with statement, this method must be called explicitly, otherwise, it should not be called.

finish(kv=None)

Stops the progress bar and prints the total duration of the operation. If metrics are given, these will be printed along with the elapsed time and the number of iterations per second. Metrics may be provided in the form <name>__<format specifier> to e.g. format floating point numbers with a fixed number of decimal points.

If key value pairs are given, this method must be called explicitly, otherwise, it is implicitly called at the end of a with statement or for loop.

Note

If this method is called mutliple times with not calls to start() in between, all but the first call are no-ops.

Parameters

metrics (dict, default: None) – The metrics to print as key-value pairs. Usually, they provide more information about the operation whose progress has been tracked.