reshape2matrix(X,DIM,SIZE)

function [X,SIZE] = reshape2matrix(X,DIM,SIZE)
%RESHAPE2MATRIX   Reshape multidimensional array into a matrix or viceversa.
%
%   SYNTAX:
%            Y = reshape2matrix(X,DIM);        % to matrix (2-dim)
%     [Y,SIZE] = reshape2matrix(X,DIM);        % to matrix (2-dim)
%            X = reshape2matrix(Y,DIM,SIZE);   % to n-dim
%
%   INPUT:
%     X    - N-dimensional array or ...
%     Y    - 2-dimensional matrix.
%     DIM  - Dimension of X to be put on the columns of Y or viceversa.
%     SIZE - Size of X array.
%
%   OUTPUT:
%     Y    - 2-dimensional matrix with dimension DIM of X in its columns
%            or ... 
%     X    - N-dimensional array of size "SIZE" with the columns of Y in
%            its DIM dimension.
%     SIZE - Size of array X.
%
%   DESCRIPTION:
%     Some MATLAB or users defined functions do not work through an
%     specific dimension in a multidimensional array, whether because its
%     not supported like in FILTFILT or the output is a matrix like in
%     CORRCOEF. 
%
%     A workaround on this problem is to specify the elements of X in the 
%     specific dimension we like to work (DIM) with some index. Another one
%     is to transform this multidimensional array into a simple
%     2-dimensional matrix with the vectors of the DIM dimensions as its
%     columns.
%
%     This latter is exactly what this little program does. Besides, after
%     working with the generated matrix, you can get the original
%     multidimensional shape by calling once again this function with the
%     third input SIZE of the original array.
%
%   NOTE:
%     * Optional outputs may or not be called.
%
%   EXAMPLE:
%     % Generates a 3-D array:
%     SIZE = [4 3 2];
%     X    = reshape(1:prod(SIZE),SIZE)
%     %     X(:,:,1) =             X(:,:,2) =  
%     %       1  5   9               13  17  21
%     %       2  6  10               14  18  22
%     %       3  7  11               15  19  23
%     %       4  8  12               16  20  24
%     % Puts its rows vectors (DIM=2) as columns of a matrix:
%     reshape2matrix(X,2)
%     %    ans =
%     %         1   2   3   4  13  14  15  16
%     %         5   6   7   8  17  18  19  20
%     %         9  10  11  12  21  22  23  24
%     % Puts its 3rd dimension vectors as columns of a matrix:
%     reshape2matrix(X,3)
%     %    ans =
%     %         1   2   3   4   5   6   7   8   9  10  11  12
%     %        13  14  15  16  17  18  19  20  21  22  23  24
%     % Now, get it back and compare it with the original X:
%     isequal(X,reshape2matrix(ans,3,SIZE))
%     %    ans = 
%     %         1
%
%   SEE ALSO:
%     RESHAPE, PERMUTE, IPERMUTE, SIZE.
%
%
%   ---
%   MFILE:   reshape2matrix.m
%   VERSION: 1.0 (Oct 02, 2009) (<a href="matlab:web('http://www.mathworks.com/matlabcentral/fileexchange/authors/11258')">download</a>) 
%   MATLAB:  7.7.0.471 (R2008b)
%   AUTHOR:  Carlos Adrian Vargas Aguilera (MEXICO)
%   CONTACT: [e-mail]

%   REVISIONS:
%   1.0      Released. (Oct 02, 2009)

%   DISCLAIMER:
%   reshape2matrix.m is provided "as is" without warranty of any kind,
%   under the revised BSD license.

%   Copyright (c) 2009 Carlos Adrian Vargas Aguilera


% INPUTS CHECK-IN
% -------------------------------------------------------------------------

% Checks number of inputs and outputs.
if     nargin<2
 error('CVARGAS:reshape2matrix:notEnoughInputs',...
  'At least 2 inputs are required.')
elseif nargin>3
 error('CVARGAS:reshape2matrix:tooManyInputs',...
  'At most 3 inputs are allowed.')
elseif nargout>2
 error('CVARGAS:reshape2matrix:tooManyOutputs',...
  'At most 2 outputs are allowed.')
end


% -------------------------------------------------------------------------
% MAIN
% -------------------------------------------------------------------------

if nargin<3
 % FORWARDS
 % Multidimensional to matrix.
 SIZE = size(X);          % Size of X.
 LDIM = SIZE(DIM);        % Length of X in DIM dimension: 
                          % number of Y columns.
 NDIM = length(SIZE);     % Number of X dimensions.
 LCOL = prod(SIZE)/LDIM;  % Number of vectors in X DIM dimension: 
                          % number of Y rows.
 % Permutes.
 X    = reshape(permute(X,[DIM 1:DIM-1 DIM+1:NDIM]),LDIM,LCOL);
else
 % BACKWARDS
 % Matrix to multidimensional.
 NDIM = length(SIZE);  % Number of X dimensions.
 LCOL = size(X,1);     % Number of Y rows: 
                       % number of vectors in X DIM dimension.
 % Permutes.
 X = ipermute(reshape(X,[LCOL SIZE([DIM+1:NDIM 1:DIM-1])]), ...
                                                 [DIM 1:DIM-1 DIM+1:NDIM]);
end


% [EOF]   reshape2matrix.LDIM