Transformers

General transformers

class fuel.transformers.defaults.ToBytes(stream, **kwargs)

Bases: fuel.transformers.SourcewiseTransformer

Transform a stream of ndarray examples to bytes.

Notes

Used for retrieving variable-length byte data stored as, e.g. a uint8 ragged array.

transform_source_batch(batch, _)

Applies a transformation to a batch from a source.

Parameters:

• source_batch (numpy.ndarray) – A batch of examples from a source.
• source_name (str) – The name of the source being operated upon.

transform_source_example(example, _)

Applies a transformation to an example from a source.

Parameters:

• source_example (numpy.ndarray) – An example from a source.
• source_name (str) – The name of the source being operated upon.

fuel.transformers.defaults.rgb_images_from_encoded_bytes(which_sources)

fuel.transformers.defaults.uint8_pixels_to_floatX(which_sources)

Transformers for image

class fuel.transformers.image.ImagesFromBytes(data_stream, color_mode='RGB', **kwargs)

Bases: fuel.transformers.SourcewiseTransformer

Load from a stream of bytes objects representing encoded images.

Parameters:

• data_stream (instance of AbstractDataStream) – The wrapped data stream. The individual examples returned by this should be the bytes (in a bytes container, or a str on legacy Python) comprising an image in a format readable by PIL, such as PNG, JPEG, etc.
• color_mode (str, optional) – Mode to pass to PIL for color space conversion. Default is RGB. If None, no coercion is performed.

Notes

Images are returned as NumPy arrays converted from PIL objects. If there is more than one color channel, then the array is transposed from the (height, width, channel) dimension layout native to PIL to the (channel, height, width) layout that is pervasive in the world of convolutional networks. If there is only one color channel, as for monochrome or binary images, a leading axis with length 1 is added for the sake of uniformity/predictability.

This SourcewiseTransformer supports streams returning single examples as bytes objects (str on legacy Python) as well as streams that return iterables containing such objects. In the case of an iterable, a list of loaded images is returned.

transform_source_batch(batch, source_name)

Applies a transformation to a batch from a source.

Parameters:

• source_batch (numpy.ndarray) – A batch of examples from a source.
• source_name (str) – The name of the source being operated upon.

transform_source_example(example, source_name)

Applies a transformation to an example from a source.

Parameters:

• source_example (numpy.ndarray) – An example from a source.
• source_name (str) – The name of the source being operated upon.

class fuel.transformers.image.MinimumImageDimensions(data_stream, minimum_shape, resample='nearest', **kwargs)

Bases: fuel.transformers.SourcewiseTransformer, fuel.transformers.ExpectsAxisLabels

Resize (lists of) images to minimum dimensions.

Parameters:

• data_stream (instance of AbstractDataStream) – The data stream to wrap.
• minimum_shape (2-tuple) – The minimum (height, width) dimensions every image must have. Images whose height and width are larger than these dimensions are passed through as-is.
• resample (str, optional) – Resampling filter for PIL to use to upsample any images requiring it. Options include ‘nearest’ (default), ‘bilinear’, and ‘bicubic’. See the PIL documentation for more detailed information.

Notes

This transformer expects stream sources returning individual images, represented as 2- or 3-dimensional arrays, or lists of the same. The format of the stream is unaltered.

transform_source_batch(batch, source_name)

Applies a transformation to a batch from a source.

Parameters:

• source_batch (numpy.ndarray) – A batch of examples from a source.
• source_name (str) – The name of the source being operated upon.

transform_source_example(example, source_name)

Applies a transformation to an example from a source.

Parameters:

• source_example (numpy.ndarray) – An example from a source.
• source_name (str) – The name of the source being operated upon.

class fuel.transformers.image.Random2DRotation(data_stream, maximum_rotation=3.141592653589793, resample='nearest', **kwargs)

Bases: fuel.transformers.SourcewiseTransformer, fuel.transformers.ExpectsAxisLabels

Randomly rotate 2D images in the spatial plane.

Parameters:

• data_stream (AbstractDataStream) – The data stream to wrap.
• maximum_rotation (float, default math.pi) – Maximum amount of rotation in radians. The image will be rotated by an angle in the range [-maximum_rotation, maximum_rotation].
• resample (str, optional) – Resampling filter for PIL to use to upsample any images requiring it. Options include ‘nearest’ (default), ‘bilinear’, and ‘bicubic’. See the PIL documentation for more detailed information.

Notes

This transformer expects to act on stream sources which provide one of

• Single images represented as 3-dimensional ndarrays, with layout (channel, height, width).
• Batches of images represented as lists of 3-dimensional ndarrays, possibly of different shapes (i.e. images of differing heights/widths).
• Batches of images represented as 4-dimensional ndarrays, with layout (batch, channel, height, width).

The format of the stream will be un-altered, i.e. if lists are yielded by data_stream then lists will be yielded by this transformer.

transform_source_batch(source, source_name)

Applies a transformation to a batch from a source.

Parameters:

• source_batch (numpy.ndarray) – A batch of examples from a source.
• source_name (str) – The name of the source being operated upon.

transform_source_example(example, source_name)

Applies a transformation to an example from a source.

Parameters:

• source_example (numpy.ndarray) – An example from a source.
• source_name (str) – The name of the source being operated upon.

class fuel.transformers.image.RandomFixedSizeCrop(data_stream, window_shape, **kwargs)

Bases: fuel.transformers.SourcewiseTransformer, fuel.transformers.ExpectsAxisLabels

Randomly crop images to a fixed window size.

Parameters:

• data_stream (AbstractDataStream) – The data stream to wrap.
• window_shape (tuple) – The (height, width) tuple representing the size of the output window.

Notes

This transformer expects to act on stream sources which provide one of

• Single images represented as 3-dimensional ndarrays, with layout (channel, height, width).
• Batches of images represented as lists of 3-dimensional ndarrays, possibly of different shapes (i.e. images of differing heights/widths).
• Batches of images represented as 4-dimensional ndarrays, with layout (batch, channel, height, width).

The format of the stream will be un-altered, i.e. if lists are yielded by data_stream then lists will be yielded by this transformer.

transform_source_batch(source, source_name)

Applies a transformation to a batch from a source.

Parameters:

• source_batch (numpy.ndarray) – A batch of examples from a source.
• source_name (str) – The name of the source being operated upon.

transform_source_example(example, source_name)

Applies a transformation to an example from a source.

Parameters:

• source_example (numpy.ndarray) – An example from a source.
• source_name (str) – The name of the source being operated upon.

Transformers for sequences

class fuel.transformers.sequences.NGrams(ngram_order, *args, **kwargs)

Bases: fuel.transformers.sequences.Window

Return n-grams from a stream.

This data stream wrapper takes as an input a data stream outputting sentences. From these sentences n-grams of a fixed order (e.g. bigrams, trigrams, etc.) are extracted and returned. It also creates a targets data source. For each example, the target is the word immediately following that n-gram. It is normally used for language modeling, where we try to predict the next word from the previous n words.

Note

Unlike the Window stream, the target returned by NGrams is a single element instead of a window.

Parameters:

• ngram_order (int) – The order of the n-grams to output e.g. 3 for trigrams.
• data_stream (DataStream instance) – The data stream providing sentences. Each example is assumed to be a list of integers.
• target_source (str, optional) – This data stream adds a new source for the target words. By default this source is ‘targets’.

get_data(*args, **kwargs)

Request data from the dataset or the wrapped stream.

Parameters:request (object) – A request fetched from the request_iterator.

Notes

It is possible to build a usable stream in terms of underlying streams for the purposes of training by only implementing get_epoch_iterator, thus this method is optional.

class fuel.transformers.sequences.Window(offset, source_window, target_window, overlapping, data_stream, target_source='targets', **kwargs)

Bases: fuel.transformers.Transformer

Return pairs of source and target windows from a stream.

This data stream wrapper takes as an input a data stream outputting sequences of potentially varying lengths (e.g. sentences, audio tracks, etc.). It then returns two sliding windows (source and target) over these sequences.

For example, to train an n-gram model set source_window to n, target_window to 1, no offset, and overlapping to false. This will give chunks [1, N] and [N + 1]. To train an RNN you often want to set the source and target window to the same size and use an offset of 1 with overlap, this would give you chunks [1, N] and [2, N + 1].

Parameters:

• offset (int) – The offset from the source window where the target window starts.
• source_window (int) – The size of the source window.
• target_window (int) – The size of the target window.
• overlapping (bool) – If true, the source and target windows overlap i.e. the offset of the target window is taken to be from the beginning of the source window. If false, the target window offset is taken to be from the end of the source window.
• data_stream (DataStream instance) – The data stream providing sequences. Each example is assumed to be an object that supports slicing.
• target_source (str, optional) – This data stream adds a new source for the target words. By default this source is ‘targets’.

get_data(request=None)

Request data from the dataset or the wrapped stream.

Parameters:request (object) – A request fetched from the request_iterator.

Notes

It is possible to build a usable stream in terms of underlying streams for the purposes of training by only implementing get_epoch_iterator, thus this method is optional.

Other

class fuel.transformers.AgnosticSourcewiseTransformer(data_stream, produces_examples, which_sources=None, **kwargs)

Bases: fuel.transformers.AgnosticTransformer, fuel.transformers.SourcewiseTransformer

A sourcewise transformer that operates the same on examples or batches.

Subclasses must implement the transform_any_source method, which is to be applied to both examples and batches. This is useful when the example and batch implementation of a sourcewise transformation are the same.

transform_any(data)

Transforms the input, which can either be an example or a batch.

transform_any_source(source_data, source_name)

Applies a transformation to a source.

The data can either be an example or a batch of examples.

Parameters:

• source_data (numpy.ndarray) – Data from a source.
• source_name (str) – The name of the source being operated upon.

class fuel.transformers.AgnosticTransformer(data_stream, produces_examples=None, **kwargs)

Bases: fuel.transformers.Transformer

A transformer that operates the same on examples or batches.

Subclasses must implement the transform_any method, which is to be applied to both examples and batches. This is useful when the example and batch implementation of a transformation are the same.

transform_any(data)

Transforms the input, which can either be an example or a batch.

transform_batch(batch)

Transforms a batch of examples.

transform_example(example)

Transforms a single example.

class fuel.transformers.BackgroundProcess(data_stream, max_batches)

Bases: object

A background process that reads batches and stores them in a queue.

The main() method needs to be called in order to start reading batches into the queue. Note that this process will run infinitely; start it as a daemon to make sure it will get killed when the main process exits.

Parameters:

• data_stream (DataStream or Transformer) – The data stream from which to read batches.
• max_batches (int) – The maximum number of batches to store in the queue. If reached, the process wil block until a batch is popped from the queue.

get_next_data()

main()

class fuel.transformers.Batch(data_stream, iteration_scheme, strictness=0, **kwargs)

Bases: fuel.transformers.Transformer

Creates minibatches from data streams providing single examples.

Some datasets only return one example at at time e.g. when reading text files a line at a time. This wrapper reads several examples sequentially to turn those into minibatches.

Parameters:

• data_stream (AbstractDataStream instance) – The data stream to wrap.
• iteration_scheme (BatchSizeScheme instance) – The iteration scheme to use; should return integers representing the size of the batch to return.
• strictness (int, optional) – How strictly the iterator should adhere to the batch size. By default, the value 0 means that the last batch is returned regardless of its size, so it can be smaller than what is actually requested. At level 1, the last batch is discarded if it is not of the correct size. At the highest strictness level, 2, an error is raised if a batch of the requested size cannot be provided.

get_data(request=None)

Get data from the dataset.

class fuel.transformers.Cache(data_stream, iteration_scheme, **kwargs)

Bases: fuel.transformers.Transformer

Cache examples when sequentially reading a dataset.

Given a data stream which reads large chunks of data, this data stream caches these chunks and returns smaller batches from it until exhausted.

Parameters:iteration_scheme (IterationScheme) – Note that this iteration scheme must return batch sizes (integers), which must necessarily be smaller than the child data stream i.e. the batches returned must be smaller than the cache size.

cache

This attribute holds the cache at any given point. It is a list of the same size as the sources attribute. Each element in this list in its turn a list of examples that are currently in the cache. The cache gets emptied at the start of each epoch, and gets refilled when needed through the get_data() method.

Type:list of lists of objects

get_data(request=None)

Request data from the dataset or the wrapped stream.

Parameters:request (object) – A request fetched from the request_iterator.

Notes

It is possible to build a usable stream in terms of underlying streams for the purposes of training by only implementing get_epoch_iterator, thus this method is optional.

get_epoch_iterator(**kwargs)

Get an epoch iterator for the wrapped data set.

Notes

This default implementation assumes that the epochs of the wrapped data stream are less or equal in length to the original data stream. Implementations for which this is not true should request new epoch iterators from the child data set when necessary.

class fuel.transformers.Cast(data_stream, dtype, **kwargs)

Bases: fuel.transformers.AgnosticSourcewiseTransformer

Casts selected sources as some dtype.

Incoming sources will be treated as numpy arrays (i.e. using numpy.asarray).

Parameters:dtype (str) – Data type to cast to. Can be any valid numpy dtype, or ‘floatX’, in which case fuel.config.floatX is used.

transform_any_source(source_data, _)

Applies a transformation to a source.

The data can either be an example or a batch of examples.

Parameters:

• source_data (numpy.ndarray) – Data from a source.
• source_name (str) – The name of the source being operated upon.

class fuel.transformers.ExpectsAxisLabels

Bases: object

Mixin for transformers, used to verify axis labels.

Notes

Provides a method verify_axis_labels() that should be called with the expected and actual values for an axis labels tuple. If actual is None, a warning is logged; if it is non-None and does not match expected, a AxisLabelsMismatchError is raised.

The check is only performed on the first call; if the call succeeds, an attribute is written to skip further checks, in the interest of speed.

verify_axis_labels(expected, actual, source_name)

Verify that axis labels for a given source are as expected.

Parameters:

• expected (tuple) – A tuple of strings representing the expected axis labels.
• actual (tuple or None) – A tuple of strings representing the actual axis labels, or None if they could not be determined.
• source_name (str) – The name of the source being checked. Used for caching the results of checks so that the check is only performed once.

Notes

Logs a warning in case of actual=None, raises an error on other mismatches.

class fuel.transformers.Filter(data_stream, predicate, **kwargs)

Bases: fuel.transformers.Transformer

Filters samples that meet a predicate.

Parameters:

• data_stream (instance of DataStream) – The filtered data stream.
• predicate (callable) – Should return True for the samples to be kept.

get_epoch_iterator(**kwargs)

Get an epoch iterator for the wrapped data set.

Notes

This default implementation assumes that the epochs of the wrapped data stream are less or equal in length to the original data stream. Implementations for which this is not true should request new epoch iterators from the child data set when necessary.

class fuel.transformers.FilterSources(data_stream, sources, **kwargs)

Bases: fuel.transformers.AgnosticTransformer

Selects a subset of the stream sources.

Order of data stream’s sources is maintained. The order of sources given as parameter to FilterSources does not matter.

Parameters:

• data_stream (AbstractDataStream or Transformer.) – The data stream.
• sources (tuple of strings) – The names of the data sources returned by this transformer. Must be a subset of the sources given by the stream.

transform_any(data)

Transforms the input, which can either be an example or a batch.

class fuel.transformers.Flatten(data_stream, **kwargs)

Bases: fuel.transformers.SourcewiseTransformer

Flattens selected sources.

If the wrapped data stream produces batches, they will be flattened along all but the first axis.

Incoming sources will be treated as numpy arrays (i.e. using numpy.asarray).

transform_source_batch(source_batch, _)

Applies a transformation to a batch from a source.

Parameters:

• source_batch (numpy.ndarray) – A batch of examples from a source.
• source_name (str) – The name of the source being operated upon.

transform_source_example(source_example, _)

Applies a transformation to an example from a source.

Parameters:

• source_example (numpy.ndarray) – An example from a source.
• source_name (str) – The name of the source being operated upon.

class fuel.transformers.ForceFloatX(data_stream, **kwargs)

Bases: fuel.transformers.AgnosticSourcewiseTransformer

Force all floating point numpy arrays to be floatX.

transform_any_source(source_data, _)

Applies a transformation to a source.

The data can either be an example or a batch of examples.

Parameters:

• source_data (numpy.ndarray) – Data from a source.
• source_name (str) – The name of the source being operated upon.

class fuel.transformers.Mapping(data_stream, mapping, add_sources=None, mapping_accepts=<type 'list'>, **kwargs)

Bases: fuel.transformers.Transformer

Applies a mapping to the data of the wrapped data stream.

Parameters:

• data_stream (instance of DataStream) – The wrapped data stream.
• mapping (callable) – The mapping to be applied. The mapping function is supposed to accept a tuple and return a tuple by default. If mapping_accepts is set to dict, the function is expected to work with ordered dictionaries where source names are the keys.
• add_sources (tuple of str, optional) – When given, the data produced by the mapping is added to original data under source names add_sources.
• mapping_accepts (type, optional) – Input and output type of the mapping function list by default, can be changed to dict.

get_data(request=None)

Request data from the dataset or the wrapped stream.

Parameters:request (object) – A request fetched from the request_iterator.

Notes

It is possible to build a usable stream in terms of underlying streams for the purposes of training by only implementing get_epoch_iterator, thus this method is optional.

sources

class fuel.transformers.Merge(data_streams, sources, axis_labels=None)

Bases: fuel.streams.AbstractDataStream

Merges several datastreams into a single one.

Parameters:

• data_streams (iterable) – The data streams to merge.
• sources (iterable) – A collection of strings, determining what sources should be called.

Examples

>>> from fuel.datasets import IterableDataset
>>> english = IterableDataset(['Hello world!'])
>>> french = IterableDataset(['Bonjour le monde!'])
>>> from fuel.streams import DataStream
>>> streams = (DataStream(english),
...            DataStream(french))
>>> merged_stream = Merge(streams, ('english', 'french'))
>>> merged_stream.sources
('english', 'french')
>>> next(merged_stream.get_epoch_iterator())
('Hello world!', 'Bonjour le monde!')

close()

Gracefully close the data stream, e.g. releasing file handles.

get_data(request=None)

Request data from the dataset or the wrapped stream.

Parameters:request (object) – A request fetched from the request_iterator.

Notes

It is possible to build a usable stream in terms of underlying streams for the purposes of training by only implementing get_epoch_iterator, thus this method is optional.

get_epoch_iterator(**kwargs)

next_epoch()

Switch the data stream to the next epoch.

reset()

Reset the data stream.

class fuel.transformers.MultiProcessing(data_stream, max_store=100, **kwargs)

Bases: fuel.transformers.Transformer

Cache batches from the stream in a separate process.

To speed up training of your model, it can be worthwhile to load and process data in separate process. This is a simple implementation of such an approach that makes use of Python’s multiprocessing module.

Parameters:

• data_stream (DataStream or Transformer) – The data stream to read batches from in the separate process.
• max_store (int, optional) – The maximum number of batches to keep in the queue.

Notes

This approach incurs an overhead from the need to serialize batches in order to send them to the main process. This should be acceptable if your model’s training calls take significantly longer than reading a batch of data does, but for fast models or slow data pipelines a more robust approach might need to be considered.

get_data(request=None)

Request data from the dataset or the wrapped stream.

Parameters:request (object) – A request fetched from the request_iterator.

Notes

It is possible to build a usable stream in terms of underlying streams for the purposes of training by only implementing get_epoch_iterator, thus this method is optional.

class fuel.transformers.Padding(data_stream, mask_sources=None, mask_dtype=None, **kwargs)

Bases: fuel.transformers.Transformer

Adds padding to variable-length sequences.

When your batches consist of variable-length sequences, use this class to equalize lengths by adding zero-padding. To distinguish between data and padding masks can be produced. For each data source that is masked, a new source will be added. This source will have the name of the original source with the suffix _mask (e.g. features_mask).

Elements of incoming batches will be treated as numpy arrays (i.e. using numpy.asarray). If they have more than one dimension, all dimensions except length, that is the first one, must be equal.

Parameters:

• data_stream (AbstractDataStream instance) – The data stream to wrap
• mask_sources (tuple of strings, optional) – The sources for which we need to add a mask. If not provided, a mask will be created for all data sources
• mask_dtype (str, optional) – data type of masks. If not provided, floatX from config will be used.

sources

transform_batch(batch)

Transforms a batch of examples.

class fuel.transformers.Rename(data_stream, names, on_non_existent='raise', **kwargs)

Bases: fuel.transformers.AgnosticTransformer

Renames the sources of the stream.

Parameters:

• data_stream (DataStream or Transformer.) – The data stream.
• names (dict) – A dictionary mapping the old and new names of the sources to rename.
• on_non_existent (str, optional) – Desired behaviour when a source specified as a key in names is not provided by the streams: see on_overwrite above for description of possible values. Default is ‘raise’.

transform_any(data)

Transforms the input, which can either be an example or a batch.

class fuel.transformers.ScaleAndShift(data_stream, scale, shift, **kwargs)

Bases: fuel.transformers.AgnosticSourcewiseTransformer

Scales and shifts selected sources by scalar quantities.

Incoming sources will be treated as numpy arrays (i.e. using numpy.asarray).

Parameters:

• scale (float) – Scaling factor.
• shift (float) – Shifting factor.

transform_any_source(source_data, _)

Applies a transformation to a source.

The data can either be an example or a batch of examples.

Parameters:

• source_data (numpy.ndarray) – Data from a source.
• source_name (str) – The name of the source being operated upon.

class fuel.transformers.SortMapping(key, reverse=False)

Bases: object

Callable class for creating sorting mappings.

This class can be used to create a callable that can be used by the Mapping constructor.

Parameters:

• key (callable) – The mapping that returns the value to sort on. Its input will be a tuple that contains a single data point for each source.
• reverse (boolean value that indicates whether the sort order should) – be reversed.

class fuel.transformers.SourcewiseTransformer(data_stream, produces_examples, which_sources=None, **kwargs)

Bases: fuel.transformers.Transformer

Applies a transformation sourcewise.

Subclasses must define transform_source_example (to transform examples), transform_source_batch (to transform batches) or both.

Parameters:

• data_stream (instance of DataStream) – The wrapped data stream.
• which_sources (tuple of str, optional) – Which sources to apply the mapping to. Defaults to None, in which case the mapping is applied to all sources.

transform_batch(batch)

Transforms a batch of examples.

transform_example(example)

Transforms a single example.

transform_source_batch(source_batch, source_name)

Applies a transformation to a batch from a source.

Parameters:

• source_batch (numpy.ndarray) – A batch of examples from a source.
• source_name (str) – The name of the source being operated upon.

transform_source_example(source_example, source_name)

Applies a transformation to an example from a source.

Parameters:

• source_example (numpy.ndarray) – An example from a source.
• source_name (str) – The name of the source being operated upon.

class fuel.transformers.Transformer(data_stream, produces_examples=None, **kwargs)

Bases: fuel.streams.AbstractDataStream

A data stream that wraps another data stream.

Subclasses must define a transform_batch method (to act on batches), a transform_example method (to act on individual examples), or both methods.

Typically (using the interface mentioned above), the transformer is expected to have the same output type (example or batch) as its input type. If the transformer subclass is going from batches to examples or vice versa, it should override get_data instead. Overriding get_data is also necessary when access to request is necessary (e.g. for the Cache transformer).

child_epoch_iterator

When a new epoch iterator is requested, a new epoch creator is automatically requested from the wrapped data stream and stored in this attribute. Use it to access data from the wrapped data stream by calling next(self.child_epoch_iterator).

Type:iterator type

produces_examples

Whether this transformer produces examples (as opposed to batches of examples).

Type:bool

close()

Gracefully close the data stream, e.g. releasing file handles.

get_data(request=None)

Request data from the dataset or the wrapped stream.

Parameters:request (object) – A request fetched from the request_iterator.

Notes

It is possible to build a usable stream in terms of underlying streams for the purposes of training by only implementing get_epoch_iterator, thus this method is optional.

get_epoch_iterator(**kwargs)

Get an epoch iterator for the wrapped data set.

Notes

This default implementation assumes that the epochs of the wrapped data stream are less or equal in length to the original data stream. Implementations for which this is not true should request new epoch iterators from the child data set when necessary.

next_epoch()

Switch the data stream to the next epoch.

reset()

Reset the data stream.

sources

transform_batch(batch)

Transforms a batch of examples.

transform_example(example)

Transforms a single example.

class fuel.transformers.Unpack(data_stream, **kwargs)

Bases: fuel.transformers.Transformer

Unpacks batches to compose a stream of examples.

This class is the inverse of the Batch class: it turns a minibatch into a stream of examples.

Parameters:data_stream (AbstractDataStream instance) – The data stream to unpack

get_data(request=None)

Request data from the dataset or the wrapped stream.

Parameters:request (object) – A request fetched from the request_iterator.

Notes

It is possible to build a usable stream in terms of underlying streams for the purposes of training by only implementing get_epoch_iterator, thus this method is optional.