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