octave_packages/m/linear-algebra/vech.m

   1 ## Copyright (C) 1995-2012 Kurt Hornik
   2 ## Copyright (C) 2009 VZLU Prague
   3 ##
   4 ## This file is part of Octave.
   5 ##
   6 ## Octave is free software; you can redistribute it and/or modify it
   7 ## under the terms of the GNU General Public License as published by
   8 ## the Free Software Foundation; either version 3 of the License, or (at
   9 ## your option) any later version.
  10 ##
  11 ## Octave is distributed in the hope that it will be useful, but
  12 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  13 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 ## General Public License for more details.
  15 ##
  16 ## You should have received a copy of the GNU General Public License
  17 ## along with Octave; see the file COPYING.  If not, see
  18 ## <http://www.gnu.org/licenses/>.
  19
  20 ## -*- texinfo -*-
  21 ## @deftypefn {Function File} {} vech (@var{x})
  22 ## Return the vector obtained by eliminating all supradiagonal elements of
  23 ## the square matrix @var{x} and stacking the result one column above the
  24 ## other.  This has uses in matrix calculus where the underlying matrix
  25 ## is symmetric and it would be pointless to keep values above the main
  26 ## diagonal.
  27 ## @seealso{vec}
  28 ## @end deftypefn
  29
  30 ## See Magnus and Neudecker (1988), Matrix differential calculus with
  31 ## applications in statistics and econometrics.
  32
  33 ## Author KH <Kurt.Hornik@wu-wien.ac.at>
  34 ## Created: 8 May 1995
  35 ## Adapted-By: jwe
  36
  37 function v = vech (x)
  38
  39   if (nargin != 1)
  40     print_usage ();
  41   endif
  42
  43   if (! issquare (x))
  44     error ("vech: X must be square");
  45   endif
  46
  47   n = rows (x);
  48   slices = cellslices (x(:), (1:n) + n*(0:n-1), n*(1:n));
  49   v = vertcat (slices{:});
  50
  51 endfunction
  52
  53 %!assert(all (vech ([1, 2, 3; 4, 5, 6; 7, 8, 9]) == [1; 4; 7; 5; 8; 9]));
  54
  55 %!error vech ();
  56
  57 %!error vech (1, 2);
  58