Transform the columns of the given matrix into a block format. More...

#include <columns_to_blocks.hpp>

Public Member Functions
	ColumnsToBlocks (size_t rows, size_t cols, size_t blockHeight=0, size_t blockWidth=0)
	Constructor a ColumnsToBlocks object with the given parameters. More...

void	Transform (const arma::mat &maximalInputs, arma::mat &output)
	Transform the columns of the input matrix into blocks. More...

void	BlockHeight (const size_t value)
	Set the height of each block; see the constructor for more details.

size_t	BlockHeight () const
	Get the block height.

void	BlockWidth (size_t value)
	Set the width of each block; see the constructor for more details.

size_t	BlockWidth () const
	Get the block width.

void	BufSize (const size_t value)
	Modify the buffer size (the size of the margin around each column of the input). More...

size_t	BufSize () const
	Get the buffer size.

void	BufValue (const double value)
	Modify the value used for buffer cells; the default is -1.

double	BufValue () const
	Get the value used for buffer cells.

void	MaxRange (const double value)
	Set the maximum of the range the input will be scaled to, if scaling is enabled (see Scale()). More...

double	MaxRange () const
	Get the maximum of the range the input will be scaled to, if scaling is enabled (see Scale()). More...

void	MinRange (const double value)
	Set the minimum of the range the input will be scaled to, if scaling is enabled (see Scale()). More...

double	MinRange () const
	Get the minimum of the range the input will be scaled to, if scaling is enabled (see Scale()). More...

void	Scale (const bool value)
	Set whether or not scaling is enabled (see also MaxRange() and MinRange()). More...

bool	Scale () const
	Get whether or not scaling is enabled (see also MaxRange() and MinRange()). More...

void	Rows (const size_t value)
	Set the number of blocks per row.

size_t	Rows () const
	Modify the number of blocks per row.

void	Cols (const size_t value)
	Set the number of blocks per column.

size_t	Cols () const
	Return the number of blocks per column.

Detailed Description

Transform the columns of the given matrix into a block format.

This could be useful with the mlpack::nn::MaximalInputs() function, if your training samples are images. Roughly speaking, given a matrix

[[A] [B] [C] [D]]

then the ColumnsToBlocks class can transform this to something like

[[m m m m m] [m A m B m] [m m m m m] [m C m D m] [m m m m m]]

where A through D are vectors and may themselves be reshaped by ColumnsToBlocks.

An example usage of the ColumnsToBlocks class with the output of MaximalInputs() is given below; this assumes that the images are square, and will return a matrix with a one-element margin, with each maximal input (that is, each column of the maximalInput matrix) as a square block in the output matrix. 5 rows and columns of blocks will be in the output matrix.

// We assume we have a sparse autoencoder 'encoder'.
arma::mat maximalInput; // Store the features learned by sparse autoencoder
mlpack::nn::MaximalInputs(encoder.Parameters(), maximalInput);
arma::mat outputs;
const bool scale = true;
ColumnsToBlocks ctb(5, 5);
arma::mat output;
ctb.Transform(maximalInput, output);
// You can save the output as a pgm, this may help you visualize the training
// results.
output.save(fileName, arma::pgm_binary);

Another example of usage is given below, on a sample matrix.

// This matrix has two columns.
arma::mat input;
input = { { -1.0000, 0.1429 },
          { -0.7143, 0.4286 },
          { -0.4286, 0.7143 },
          { -0.1429, 1.0000 } };
arma::mat output;
ColumnsToBlocks ctb(1, 2);
ctb.Transform(input, output);
// The columns of the input will be reshaped as a square which is
// surrounded by padding value -1 (this value could be changed with the
// BufValue() method):
// -1.0000  -1.0000  -1.0000  -1.0000  -1.0000  -1.0000  -1.0000
// -1.0000  -1.0000  -0.4286  -1.0000   0.1429   0.7143  -1.0000
// -1.0000  -0.7143  -0.1429  -1.0000   0.4286   1.0000  -1.0000
// -1.0000  -1.0000  -1.0000  -1.0000  -1.0000  -1.0000  -1.0000
// Now, let's change some parameters; let's have each input column output not
// as a square, but as a 4x1 vector.
ctb.BlockWidth(1);
ctb.BlockHeight(4);
ctb.Transform(input, output);
// The output here will be similar, but each maximal input is 4x1:
// -1.0000 -1.0000 -1.0000 -1.0000 -1.0000
// -1.0000 -1.0000 -1.0000  0.1429 -1.0000
// -1.0000 -0.7143 -1.0000  0.4286 -1.0000
// -1.0000 -0.4286 -1.0000  0.7143 -1.0000
// -1.0000 -0.1429 -1.0000  1.0000 -1.0000
// -1.0000 -1.0000 -1.0000 -1.0000 -1.0000

The ColumnsToBlocks class can also, depending on the parameters, scale the input to a given range (useful for exporting to PGM, for instance), and also set the buffer size and value. See the Scale(), MinRange(), MaxRange(), BufSize(), and BufValue() methods for more details.

Constructor & Destructor Documentation

◆ ColumnsToBlocks()

mlpack::math::ColumnsToBlocks::ColumnsToBlocks	(	size_t	rows,
		size_t	cols,
		size_t	blockHeight = `0`,
		size_t	blockWidth = `0`
	)

Constructor a ColumnsToBlocks object with the given parameters.

The rows and cols parameters control the number of blocks per row and column of the output matrix, respectively, and the blockHeight and blockWidth parameters control the size of the individual blocks. If blockHeight and blockWidth are specified, then (blockHeight * blockWidth) must be equal to the number of rows in the input matrix when Transform() is called. If blockHeight and blockWidth are not specified, then the square root of the number of rows of the input matrix will be taken when Transform() is called and that will be used as the block width and height.

Note that the ColumnsToBlocks object can also scale the inputs to a given range; see Scale(), MinRange(), and MaxRange(), and the buffer (margin) size can also be set with BufSize(), and the value used for the buffer can be set with BufValue().

Parameters

rows	Number of blocks in each column of the output matrix.
cols	Number of blocks in each row of the output matrix.
blockHeight	Height of each block.
blockWidth	Width of each block.

Warning: blockHeight * blockWidth must be equal to maximalInputs.n_rows.

Member Function Documentation

◆ BufSize()

void mlpack::math::ColumnsToBlocks::BufSize ( const size_t value )

inline

Modify the buffer size (the size of the margin around each column of the input).

The default value is 1.

◆ MaxRange() [1/2]

void mlpack::math::ColumnsToBlocks::MaxRange ( const double value )

inline

Set the maximum of the range the input will be scaled to, if scaling is enabled (see Scale()).

◆ MaxRange() [2/2]

double mlpack::math::ColumnsToBlocks::MaxRange ( ) const

inline

Get the maximum of the range the input will be scaled to, if scaling is enabled (see Scale()).

◆ MinRange() [1/2]

void mlpack::math::ColumnsToBlocks::MinRange ( const double value )

inline

Set the minimum of the range the input will be scaled to, if scaling is enabled (see Scale()).

◆ MinRange() [2/2]

double mlpack::math::ColumnsToBlocks::MinRange ( ) const

inline

Get the minimum of the range the input will be scaled to, if scaling is enabled (see Scale()).

◆ Scale() [1/2]

void mlpack::math::ColumnsToBlocks::Scale ( const bool value )

inline

Set whether or not scaling is enabled (see also MaxRange() and MinRange()).

◆ Scale() [2/2]

bool mlpack::math::ColumnsToBlocks::Scale ( ) const

inline

Get whether or not scaling is enabled (see also MaxRange() and MinRange()).

◆ Transform()

void mlpack::math::ColumnsToBlocks::Transform	(	const arma::mat &	maximalInputs,
		arma::mat &	output
	)

Transform the columns of the input matrix into blocks.

If blockHeight and blockWidth were not specified in the constructor (and BlockHeight() and BlockWidth() were not called), then the number of rows in the input matrix must be a perfect square.

Parameters

maximalInputs	Input matrix to transform.
output	Matrix to store transformed output in.

The documentation for this class was generated from the following files:

src/mlpack/core/math/columns_to_blocks.hpp
src/mlpack/core/math/columns_to_blocks.cpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ ColumnsToBlocks()

Member Function Documentation

◆ BufSize()

◆ MaxRange() [1/2]

◆ MaxRange() [2/2]

◆ MinRange() [1/2]

◆ MinRange() [2/2]

◆ Scale() [1/2]

◆ Scale() [2/2]

◆ Transform()