The module "mblk_fun" of the Mastrave modelling library

Copyright and license notice of the function mblk_fun

Copyright © 2009,2010,2011,2012 Daniele de Rigo

The file mblk_fun.m is part of Mastrave.

Mastrave is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

Mastrave is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with Mastrave. If not, see http://www.gnu.org/licenses/.

Function declaration

 blk_values = mblk_fun( values               , 
                        func                 ,
                        blk_size             ,
                        start_from = 'begin' ,
                        vals_size  = []      ,
                        same_size  = true    )

Description

Utility to downsample an array values to a series of arrays blk_values . Each element of those arrays is computed by applying the corresponding function of func to (hyper)rectangular blocks of values . The functions are expected to receive a numerical array (i.e. the i-th block of values ) and return a scalar (i.e. the i-th element of each downsampled array of blk_values .

Input arguments

 values             ::numeric::
                    Numeric vector, matrix or multidimensional-array.

 func               ::cellfunhandle::
                    Function handle of cell-array of function handles
                    each of them has to be applied to  values , block per
                    block.  The functions referred by  func  are expected
                    to receive one numeric input argument and to provide as
                    output one numeric argument (either scalar or with the 
                    same size of the blocks).

 blk_size           ::index::
                    Size of the (hyper)rectangular blocks of  values  the
                    information of each has to be summarized by applying
                    the function(s) of  func , block per block.
                    In case  vals_size  is not a multiple of  blk_size ,
                    incomplete blocks are used at the borders of  values 
                    (after it is reshaped to have size  vals_size ) for 
                    ensuring the partition of  values  to be complete.

 start_from         ::string|empty::
                    If  blk_size  is not submultiple of the size of 
                     values , incomplete blocks will be generated to 
                    partitioning  values  in blocks.
                    When this happens, complete blocks will start to 
                    partition  values  from different poins, depending 
                    on the value of  start_from .  
                    If omitted, the default value is: 'begin'.
                    If  start_from  is an empty array  [] , the default 
                    value is used.
                    Valid options are:

                         Option  │  Meaning
                       ──────────┼─────────────────────────────────────────
                        'begin'  │ Complete blocks will partition  values 
                        []       │ starting from its first index. 
                       ──────────┼─────────────────────────────────────────
                        'end'    │ Complete blocks will partition  values 
                                 │ starting from its last index.  
                       ──────────┼─────────────────────────────────────────
                        'center' │ Complete blocks will partition  values 
                        'middle' │ starting from its central part.

 vals_size          ::index::
                    Size to which reshape  values  before partitioning it
                    in blocks and applying  func  for each block.
                    A single dimension of  vals_size  can be unknown by
                    replacing the finite numeric value of it with  Inf.
                    If so,  values  will be reshaped by replacing  Inf
                    with the finite value required to ensure (if possible)
                     vals_size  is compatible with the size of  values .
                    If  vals_size  is an empty array  [] , the original 
                    size of  values  is used.
                    If omitted, the default value is  [].

 same_size          ::scalar,logical::
                    If set to  true, this flag requires to attempt
                    preserving the size of  value  in the output 
                     blk_values , if they have the same number of 
                    elements (default value: true).

Example of usage

   % Motivational example: downsampling an image
   M      = filter2( ones(10), filter2( ones(10), randn(400) ) );
   figure(1); imagesc( M ); title( 'High-resolution image' )
   m      = mblk_fun( M, @median, 9 );
   figure(2); imagesc( m ); title( 'Down-sampled image (median 9x9)' )
   decomp = @(x)reshape( [ mean(x), std(x), skewness(x) ], [1 1 3] )
   m3 = mblk_fun( M, decomp, 9, [],[],false);
   figure(3); imagesc( m3 ); title( 'Down-sampled image (3 channels 9x9)' )

   % Downsampling a matrix
   data2D = reshape( 1:55, 5, 11 )
   mblk_fun( data2D, @(x)min(x), 1 )
   mblk_fun( data2D, @(x)min(x), 2 )
   mblk_fun( data2D, @(x)min(x), 3 )

   % Downsampling a multi-dimensional array
   data3D = reshape( 1:99, 3, 11, 3 )
   mblk_fun( data3D, @(x)min(x), 1 )
   mblk_fun( data3D, @(x)min(x), 2 )
   mblk_fun( data3D, @(x)min(x), 3 )

   % Heterogeneous block size
   mblk_fun( data2D, @(x)min(x), [1 5]   )
   mblk_fun( data3D, @(x)min(x), [1 5 2] )

   % Multiple functions
   mblk_fun( data2D, { @(x)min(x), @numel }, 1 )
   mblk_fun( data2D, { @(x)min(x), @numel }, 2 )
   mblk_fun( data2D, { @(x)min(x), @numel }, 3 )

   mblk_fun( data3D, { @(x)min(x), @numel }, 1 )
   mblk_fun( data3D, { @(x)min(x), @numel }, 2 )
   mblk_fun( data3D, { @(x)min(x), @numel }, 3 )
   mblk_fun( data3D, { @(x)min(x), @numel }, [1 5 2] )

   % Passing  start_from     
   mblk_fun( data2D, @numel, 3, 'begin' )
   mblk_fun( data2D, @numel, 3, 'end' )
   mblk_fun( data2D, @numel, 3, 'middle' )

   % Reshaping the data (and output)
   mblk_fun( data2D, @(x)x , 1, 'begin', [11 , 5  ] )
   mblk_fun( data2D, @numel, 2, 'begin', [11 , 5  ] )
   mblk_fun( data2D, @numel, 2, 'begin', [inf, 5  ] )
   mblk_fun( data3D, @(x)x , 1, 'begin', [11 , 9  ] )
   mblk_fun( data3D, @numel, 2, 'begin', [11 , 9  ] )
   mblk_fun( data3D, @numel, 2, 'begin', [11 , inf] )


   % Motivational example: normalizing tile per tile an image
   r      = @(f,x)repmat( f(x), size(x) )
   Mstats = mblk_fun( M, { @(x)r(@mean,x), @(x)r(@std,x) }, 30 );
   figure(3); imagesc( ( M - Mstats{1} ) ./ Mstats{2} )
   title( 'Image normalized tile per tile (tiles of 30x30)' )

See also:
   mat2multi, multi2mat, mstream



Keywords:
   multidimensional-array, functional, sub-arrays



Version: 0.6.8

Support

The Mastrave modelling library is committed to provide reusable and general - but also robust and scalable - modules for research modellers dealing with computational science.  You can help the Mastrave project by providing feedbacks on unexpected behaviours of this module.  Despite all efforts, all of us - either developers or users - (should) know that errors are unavoidable.  However, the free software paradigm successfully highlights that scientific knowledge freedom also implies an impressive opportunity for collectively evolve the tools and ideas upon which our daily work is based.  Reporting a problem that you found using Mastrave may help the developer team to find a possible bug.  Please, be aware that Mastrave is entirely based on voluntary efforts: in order for your help to be as effective as possible, please read carefully the section on reporting problems.  Thank you for your collaboration.