squareform: add BISTs, improve docstring and input validation, #417

Author: pr0m1th3as

inst/squareform.m

@@ -1,5 +1,6 @@
 ## Copyright (C) 2015 Carnë Draug <carandraug@octave.org>
 ## Copyright (C) 2026 Andreas Bertsatos <abertsatos@biol.uoa.gr>
+## Copyright (C) 2026 Avanish Salunke <avanishsalunke16@gmail.com>
 ##
 ## This file is part of the statistics package for GNU Octave.
 ##
@@ -31,18 +32,18 @@
 ## @code{pdist} into a distance matrix.  It performs the opposite operation
 ## if input is a matrix.
 ##
-## If @var{x} is a numeric or logical vector, its number of elements must fit into the
-## triangular part of a matrix (main diagonal excluded).  In other words,
-## @code{numel (@var{x}) = @var{n} * (@var{n} - 1) / 2} for some integer
+## If @var{x} is a numeric or logical vector, its number of elements must fit
+## into the triangular part of a matrix (main diagonal excluded).  In other
+## words, @code{numel (@var{x}) = @var{n} * (@var{n} - 1) / 2} for some integer
 ## @var{n}.  The resulting matrix will be @var{n} by @var{n}.
 ##
-## If @var{x} is a numeric or logical distance matrix, it must be square and the diagonal entries
-## of @var{x} must all be zeros.  If @var{x} is not symmetric, only the lower
-## triangular part is used.
+## If @var{x} is a numeric or logical distance matrix, it must be square and the
+## diagonal entries of @var{x} must all be zeros.  If @var{x} is not symmetric,
+## only the lower triangular part is used.
 ##
-## The second argument is used to specify the output type in case there
-## is a single element.  Accepted values are @qcode{"tomatrix"} (or @qcode{"tom"})
-## and @qcode{"tovector"} (or @qcode{"tov"}).  It will default to
+## The second argument is used to specify the output type in case the distance
+## input is a scalar.  Accepted values are @qcode{'tomatrix'} (or @qcode{'tom'})
+## and @qcode{'tovector'} (or @qcode{'tov'}).  If not specified, it defaults to
 ## @qcode{"tomatrix"} otherwise.
 ##
 ## @seealso{pdist}
@@ -53,27 +54,36 @@
   if (nargin < 1 || nargin > 2)
     print_usage ();
   elseif (! isnumeric (x) && ! islogical (x))
-    error ("squareform: Y or Z must be either numeric or logical.");
+    error ("squareform: distance input must be either numeric or logical.");
   elseif (! ismatrix (x))
-    error ("squareform: Y or Z must be either a vector or a matrix.");
+    error ("squareform: distance input must be either a vector or a matrix.");
   endif
 
   if (nargin == 1)
     ## This is ambiguous when numel (x) == 1, but that's the whole reason
     ## why the "method" option exists.
     if (isvector (x))
-      method = "tomatrix";
+      method = 'tomatrix';
     else
-      method = "tovector";
+      method = 'tovector';
     endif
+  elseif (isstring (method))
+    if (! isscalar (method))
+      error (strcat ("squareform: second argument must be either", ...
+                     " a character vector or a string scalar."));
+    endif
+    method = char (method);
+  elseif (! ischar (method))
+    error (strcat ("squareform: second argument must be either", ...
+                   " a character vector or a string scalar."));
   endif
 
   switch (tolower (method))
     case {'tovector', 'tov'}
       if (! issquare (x))
-        error ("squareform: Z is not a square matrix.");
+        error ("squareform: distance input is not a square matrix.");
       elseif (any (diag (x) != 0))
-        error ("squareform: Z is not a hollow matrix.");
+        error ("squareform: distance input is not a hollow matrix.");
       endif
 
       y = vec (tril (x, -1, "pack"), 2);
@@ -83,7 +93,7 @@
       ## length (x) = (sy - 1) * (sy / 2)
       sy = (1 + sqrt (1 + 8 * numel (x))) / 2;
       if (fix (sy) != sy)
-        error ("squareform: the numel of Y cannot form a square matrix.");
+        error ("squareform: distance input vector cannot form a square matrix.");
       endif
 
       y = zeros (sy, class (x));
@@ -103,7 +113,7 @@
 
 %!shared v, m
 %! v = 1:6;
-%! m = [0 1 2 3;1 0 4 5;2 4 0 6;3 5 6 0];
+%! m = [0, 1, 2, 3; 1, 0, 4, 5; 2, 4, 0, 6; 3, 5, 6, 0];
 
 ## make sure that it can go both directions automatically
 %!test
@@ -118,12 +128,12 @@
 ## handle 1 element input properly
 %!test
 %!assert (squareform (1), [0 1;1 0])
-%!assert (squareform (1, "tomatrix"), [0 1; 1 0])
-%!assert (squareform (0, "tovector"), zeros (1, 0))
+%!assert (squareform (1, 'tomatrix'), [0 1; 1 0])
+%!assert (squareform (0, 'tovector'), zeros (1, 0))
 
 ## confirm that it respects input class
 %!test
-%! for c = {@single, @double, @uint8, @uint32, @uint64, @logical}
+%! for c = {@single, @double, @uint8, @uint16, @uint32, @uint64, @logical}
 %!   f = c{1};
 %!   assert (squareform (f (v)), f (m))
 %!   assert (squareform (f (m)), f (v))
@@ -137,18 +147,27 @@
 %! assert (squareform (m_log), v_log);
 
 ## test partial string matching and case insensitivity
-%!test
-%! assert (squareform (v, "tom"), m);
-%! assert (squareform (m, "tov"), v);
-%! assert (squareform (v, "TOMATRIX"), m);
+%!assert (squareform (v, 'tom'), m);
+%!assert (squareform (m, 'tov'), v);
+%!assert (squareform (v, 'TOMATRIX'), m);
+%!assert (squareform (v, string ('tomatrix')), m);
+%!assert (squareform (m, string ('tovector')), v);
 
 ## input validations
-%!error <squareform: Y or Z must be either numeric or logical.> squareform ("string")
-%!error <squareform: Y or Z must be either numeric or logical.> squareform ({1, 2, 3})
-%!error <squareform: Z is not a square matrix.> squareform ([1, 2, 3; 4, 5, 6], "tovector")
-%!error <squareform: Z is not a hollow matrix.> squareform (eye (3), "tovector")
-%!error <squareform: the numel of Y cannot form a square matrix.> squareform ([1, 2, 3, 4], "tomatrix")
-%!error <squareform: invalid METHOD 'to'> squareform ([1, 2, 3], "to")
-%!error <squareform: invalid METHOD 'invalid'> squareform ([1, 2, 3], "invalid")
+%!error <squareform: distance input must be either numeric or logical.> ...
+%! squareform ('string')
+%!error <squareform: distance input must be either numeric or logical.> ...
+%! squareform ({1, 2, 3})
+%!error <squareform: distance input is not a square matrix.> ...
+%! squareform ([1, 2, 3; 4, 5, 6], 'tovector')
+%!error <squareform: distance input is not a hollow matrix.> ...
+%! squareform (eye (3), 'tovector')
+%!error <squareform: second argument must be either a character vector or a string scalar.> ...
+%! squareform ([1, 2, 3; 4, 5, 6], string ({'tomatrix', 'tomatrix'}))
+%!error <squareform: second argument must be either a character vector or a string scalar.> ...
+%! squareform ([1, 2, 3; 4, 5, 6], true)
+%!error <squareform: distance input vector cannot form a square matrix.> ...
+%! squareform ([1, 2, 3, 4], 'tomatrix')
+%!error <squareform: invalid METHOD 'invalid'> squareform ([1, 2, 3], 'invalid')