changeset 29763:5113ae64136b stable

hist.m: improve handling and docstring for third "norm" parameter (bug #60783) * scripts/plot/draw/hist.m: Explicitly check for the shape of "norm", it can be either a positive scalar or a vector of positive scalars of length "column (y)". Improve docstring. BIST added.
author Kai T. Ohlhus <k.ohlhus@gmail.com>
date Wed, 16 Jun 2021 15:49:50 +0900
parents e04b4706ca18
children 83ca5801187b fe06c183cc4e
files scripts/plot/draw/hist.m
diffstat 1 files changed, 29 insertions(+), 2 deletions(-) [+]
line wrap: on
line diff
--- a/scripts/plot/draw/hist.m	Mon Jun 14 10:39:32 2021 -0400
+++ b/scripts/plot/draw/hist.m	Wed Jun 16 15:49:50 2021 +0900
@@ -47,8 +47,20 @@
 ## of the bins.  The width of the bins is determined from the adjacent values
 ## in the vector.  The total number of bins is @code{numel (@var{x})}.
 ##
-## If a third argument is provided, the histogram is normalized such that
-## the sum of the bars is equal to @var{norm}.
+## If a third argument @var{norm} is provided, the histogram is normalized.
+## In case @var{norm} is a positive scalar, the resulting bars are normalized
+## to @var{norm}.  If @var{norm} is a vector of positive scalars of length
+## @code{columns (@var{y})}, then the resulting bar of @code{@var{y}(:,i)} is
+## normalized to @code{@var{norm}(i)}.
+##
+## @example
+## @group
+## [nn, xx] = hist (rand (10, 3), 5, [1 2 3]);
+## sum (nn, 1)
+## @result{} ans =
+##       1   2   3
+## @end group
+## @end example
 ##
 ## The histogram's appearance may be modified by specifying property/value
 ## pairs to the underlying patch object.  For example, the face and edge color
@@ -176,6 +188,11 @@
     if (! isnumeric (norm) || ! all (norm > 0))
       error ("hist: NORM must be a numeric constant > 0");
     endif
+    if (! isvector (norm) ...
+        || ! (length (norm) == 1 || length (norm) == columns (y)))
+      error ("hist: NORM must be scalar or vector of length 'columns (y)'");
+    endif
+    norm = norm (:).';  # Ensure vector orientation.
   endif
 
   ## Perform histogram calculation
@@ -283,8 +300,17 @@
 %! assert (nn, [0,5,0]);
 %! assert (xx, [0,1,2]);
 %!assert (size (hist (randn (750,240), 200)), [200, 240])
+
+## Test normalization
 %!assert <*42394> (isempty (hist (rand (10,2), 0:5, 1)), false)
 %!assert <*42394> (isempty (hist (rand (10,2), 0:5, [1 1])), false)
+%!test <*60783>
+%! [nn, xx] = hist (rand (10, 3), 5, 1);
+%! assert (sum (nn, 1), [1 1 1], 2*eps);
+%! [nn, xx] = hist (rand (10, 3), 5, [1 2 3]);
+%! assert (sum (nn, 1), [1 2 3], 2*eps);
+%! [nn, xx] = hist (rand (10, 3), 5, [1 2 3]');
+%! assert (sum (nn, 1), [1 2 3], 2*eps);
 
 %!test <*47707>
 %! y = [1  9  2  2  9  3  8  9  1  7  1  1  3  2  4  4  8  2  1  9  4  1 ...
@@ -401,3 +427,4 @@
 %!error <bin specification must be a scalar or vector> hist (1, ones (2,2))
 %!error <NORM must be a numeric constant> hist (1,1, {1})
 %!error <NORM must be a numeric constant . 0> hist (1,1, -1)
+%!error <NORM must be scalar or vector> hist (1,1, ones (4))