octave_packages/m/plot/plotmatrix.m

   1 ## Copyright (C) 2008-2012 David Bateman
   2 ##
   3 ## This file is part of Octave.
   4 ##
   5 ## Octave is free software; you can redistribute it and/or modify it
   6 ## under the terms of the GNU General Public License as published by
   7 ## the Free Software Foundation; either version 3 of the License, or (at
   8 ## your option) any later version.
   9 ##
  10 ## Octave is distributed in the hope that it will be useful, but
  11 ## WITHOUT ANY WARRANTY; without even the implied warranty of
  12 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 ## General Public License for more details.
  14 ##
  15 ## You should have received a copy of the GNU General Public License
  16 ## along with Octave; see the file COPYING.  If not, see
  17 ## <http://www.gnu.org/licenses/>.
  18
  19 ## -*- texinfo -*-
  20 ## @deftypefn  {Function File} {} plotmatrix (@var{x}, @var{y})
  21 ## @deftypefnx {Function File} {} plotmatrix (@var{x})
  22 ## @deftypefnx {Function File} {} plotmatrix (@dots{}, @var{style})
  23 ## @deftypefnx {Function File} {} plotmatrix (@var{h}, @dots{})
  24 ## @deftypefnx {Function File} {[@var{h}, @var{ax}, @var{bigax}, @var{p}, @var{pax}] =} plotmatrix (@dots{})
  25 ## Scatter plot of the columns of one matrix against another.  Given the
  26 ## arguments @var{x} and @var{y}, that have a matching number of rows,
  27 ## @code{plotmatrix} plots a set of axes corresponding to
  28 ##
  29 ## @example
  30 ## plot (@var{x} (:, i), @var{y} (:, j)
  31 ## @end example
  32 ##
  33 ## Given a single argument @var{x}, then this is equivalent to
  34 ##
  35 ## @example
  36 ## plotmatrix (@var{x}, @var{x})
  37 ## @end example
  38 ##
  39 ## @noindent
  40 ## except that the diagonal of the set of axes will be replaced with the
  41 ## histogram @code{hist (@var{x} (:, i))}.
  42 ##
  43 ## The marker to use can be changed with the @var{style} argument, that is a
  44 ## string defining a marker in the same manner as the @code{plot}
  45 ## command.  If a leading axes handle @var{h} is passed to
  46 ## @code{plotmatrix}, then this axis will be used for the plot.
  47 ##
  48 ## The optional return value @var{h} provides handles to the individual
  49 ## graphics objects in the scatter plots, whereas @var{ax} returns the
  50 ## handles to the scatter plot axis objects.  @var{bigax} is a hidden
  51 ## axis object that surrounds the other axes, such that the commands
  52 ## @code{xlabel}, @code{title}, etc., will be associated with this hidden
  53 ## axis.  Finally @var{p} returns the graphics objects associated with
  54 ## the histogram and @var{pax} the corresponding axes objects.
  55 ##
  56 ## @example
  57 ## plotmatrix (randn (100, 3), "g+")
  58 ## @end example
  59 ##
  60 ## @end deftypefn
  61
  62 function [h, ax, bigax, p, pax] = plotmatrix (varargin)
  63
  64   [bigax2, varargin, nargin] = __plt_get_axis_arg__ ("plotmatrix", varargin{:});
  65
  66   if (nargin > 3 || nargin < 1)
  67     print_usage ();
  68   else
  69     oldh = gca ();
  70     unwind_protect
  71       axes (bigax2);
  72       newplot ();
  73       [h2, ax2, p2, pax2, need_usage] = __plotmatrix__ (bigax2, varargin{:});
  74       if (need_usage)
  75         print_usage ();
  76       endif
  77       if (nargout > 0)
  78         h = h2;
  79         ax = ax2;
  80         bigax = bigax2;
  81         p = p2;
  82         pax = pax2;
  83       endif
  84       axes (bigax2);
  85       ctext = text (0, 0, "", "visible", "off",
  86                     "handlevisibility", "off", "xliminclude", "off",
  87                     "yliminclude", "off", "zliminclude", "off",
  88                     "deletefcn", {@plotmatrixdelete, [ax2; pax2]});
  89       set (bigax2, "visible", "off");
  90     unwind_protect_cleanup
  91       axes (oldh);
  92     end_unwind_protect
  93   endif
  94 endfunction
  95
  96 %!demo
  97 %! clf
  98 %! plotmatrix (randn (100, 3), 'g+')
  99
 100 function plotmatrixdelete (h, d, ax)
 101   for i = 1 : numel (ax)
 102     hc = ax(i);
 103     if (ishandle (hc) && strcmp (get (hc, "type"), "axes")
 104         && strcmpi (get (hc, "beingdeleted"), "off"))
 105       parent = get (hc, "parent");
 106       ## If the parent is invalid or being deleted, then do nothing
 107       if (ishandle (parent) && strcmpi (get (parent, "beingdeleted"), "off"))
 108         delete (hc);
 109       endif
 110     endif
 111   endfor
 112 endfunction
 113
 114 function [h, ax, p, pax, need_usage] = __plotmatrix__ (bigax, varargin)
 115   need_usage = false;
 116   have_line_spec = false;
 117   have_hist = false;
 118   parent = get (bigax, "parent");
 119   for i = 1 : nargin - 1
 120     arg = varargin{i};
 121     if (ischar (arg) || iscell (arg))
 122       [linespec, valid] = __pltopt__ ("plotmatrix", varargin{i}, false);
 123       if (valid)
 124         have_line_spec = true;
 125         linespec = varargin(i);
 126         varargin(i) = [];
 127         nargin = nargin - 1;
 128         break;
 129       else
 130         need_usage = true;
 131         returm;
 132       endif
 133     endif
 134   endfor
 135
 136   if (nargin == 2)
 137     X = varargin{1};
 138     Y = X;
 139     have_hist = true;
 140   elseif (nargin == 3)
 141     X = varargin{1};
 142     Y = varargin{2};
 143   else
 144     need_usage = true;
 145     returm;
 146   endif
 147
 148   if (rows(X) != rows(Y))
 149     error ("plotmatrix: dimension mismatch in the arguments");
 150   endif
 151
 152   [dummy, m] = size (X);
 153   [dummy, n] = size (Y);
 154
 155   h = [];
 156   ax = [];
 157   p = [];
 158   pax = [];
 159
 160   xsize = 0.9 / m;
 161   ysize = 0.9 / n;
 162   xoff = 0.05;
 163   yoff = 0.05;
 164   border = [0.130, 0.110, 0.225, 0.185] .* [xsize, ysize, xsize, ysize];
 165   border(3:4) = - border(3:4) - border(1:2);
 166
 167   for i = 1 : n
 168     for j = 1 : m
 169       pos = [xsize * (j - 1) + xoff, ysize * (n - i) + yoff, xsize, ysize];
 170       tmp = axes ("outerposition", pos, "position", pos + border,
 171                   "parent", parent);
 172       if (i == j && have_hist)
 173         pax = [pax ; tmp];
 174         [nn, xx] = hist (X(:, i));
 175         tmp = bar (xx, nn, 1.0);
 176         p = [p; tmp];
 177       else
 178         ax = [ax ; tmp];
 179         if (have_line_spec)
 180           tmp = plot (X (:, i), Y (:, j), linespec);
 181         else
 182           tmp = plot (X (:, i), Y (:, j), ".");
 183         endif
 184         h = [h ; tmp];
 185       endif
 186     endfor
 187   endfor
 188 endfunction