histc() reforged 45/19045/12
Samuel GOUGEON [Mon, 6 Feb 2017 19:30:11 +0000 (20:30 +0100)]
* BC 100 % ensured with all preexisting syntaxes
* syntaxes of histplot() reforged will be aligned with histc() ones.
  BC will be 100% ensured as well (+ fixing the bugs)
* histc() unit tests: ~400 tests added.
* Help page rewritten, render. in PDF. Please remove it before merging

* Input data:
  - extension to sparses, complex numbers, texts, and polynomials
  - Data becomes the first input argument (Matlab-like). Back-compatibility ensured.
  - %inf and -%inf values are now accepted. They yielded an error.
  - In ranging mode, %nan values are now properly filtered out.

* Binning:
  - Specification becomes the second input argument.  Back-compatibility ensured.
  - input bins become optional: automatic binning modes are now available:
    - polynomials, texts: (discrete) categorial bins generated from data
    - numbers: sqrt (default), freediac, sturges methods are now available.
  - "discrete" categorial mode added, for all types of input data.
  - Numbers: a fixed bins width can now be specified
  - Numbers and texts: marginal bins can now be specified with -%inf and %inf
    or with "" and "~~" on both histogram wings.

* Histogram scales:
  - boolean "normalization" option replaced. Back-compatibility fully ensured.
  - "counts" (default) and "countsNorm" options added for all input data types
    "density" and "densityNorm" options added for data numbers in ranging mode.
  - Management of special values (jokers) added: Nan, Inf, zeros in sparse, ""
    - are excluded from the continuous histogram
    - For each joker, an option can be used to take its counts into
      account for normalized scales

* Results:
  - Bins indices of data are now returned in 4th position. Back-compatibility ensured.
  - Counts of jokers are now returned:
      * integers: [leftout, rightout] (range) or [out] (discrete)
      * decimal or complex numbers, full or sparse:
            range: [leftout, rightout, zeros, nan, inf]
         discrete: [out, 0, zeros, nan, inf]
      * polynomials: [out, 0, 0, nan, inf]
      * texts: range: [leftout, rightout, ""]; discrete: [out, 0, ""]
  - Actual bins values or edges are now returned.

Change-Id: Ia9ef2f4bcefab81c5a5852610136daa56900d0fc

29 files changed:
scilab/modules/graphics/macros/histplot.sci
scilab/modules/helptools/etc/images_md5.txt
scilab/modules/helptools/images/_LaTeX_histc.xml_1.png
scilab/modules/helptools/images/_LaTeX_histplot.xml_1.png
scilab/modules/helptools/images/histc_1.png
scilab/modules/helptools/images/histc_en_US_2.png [deleted file]
scilab/modules/helptools/images/histc_en_US_3.png [deleted file]
scilab/modules/helptools/images/histc_en_US_4.png [deleted file]
scilab/modules/helptools/images/histc_fr_FR_2.png [deleted file]
scilab/modules/helptools/images/histc_fr_FR_3.png [deleted file]
scilab/modules/helptools/images/histc_fr_FR_4.png [deleted file]
scilab/modules/helptools/images/histc_ja_JP_2.png [deleted file]
scilab/modules/helptools/images/histc_ja_JP_3.png [deleted file]
scilab/modules/helptools/images/histc_ja_JP_4.png [deleted file]
scilab/modules/helptools/images/histc_pt_BR_2.png [deleted file]
scilab/modules/helptools/images/histc_pt_BR_3.png [deleted file]
scilab/modules/helptools/images/histc_pt_BR_4.png [deleted file]
scilab/modules/helptools/images/histc_ru_RU_2.png [deleted file]
scilab/modules/helptools/images/histc_ru_RU_3.png [deleted file]
scilab/modules/helptools/images/histc_ru_RU_4.png [deleted file]
scilab/modules/statistics/help/en_US/4_distribution_empirical_shape/histc.xml
scilab/modules/statistics/help/en_US/histc.pdf [new file with mode: 0644]
scilab/modules/statistics/help/fr_FR/4_distribution_empirical_shape/histc.xml [deleted file]
scilab/modules/statistics/help/ja_JP/4_distribution_empirical_shape/histc.xml [deleted file]
scilab/modules/statistics/macros/histc.sci
scilab/modules/statistics/tests/nonreg_tests/bug_13490.tst [deleted file]
scilab/modules/statistics/tests/nonreg_tests/bug_6306.dia.ref [deleted file]
scilab/modules/statistics/tests/nonreg_tests/bug_6306.tst
scilab/modules/statistics/tests/unit_tests/histc.tst

index 13cfe89..42b6606 100644 (file)
@@ -4,7 +4,7 @@
 // Copyright (C) 2010 - Samuel Gougeon
 // Copyright (C) 2012 - Scilab Enterprises - Adeline CARNIS
 // Copyright (C) 2013 - A. Khorshidi (new option)
-// Copyright (C) 2013 - Scilab Enterpriss - Paul Bignier: added output
+// Copyright (C) 2013 - Scilab Enterprises - Paul Bignier: added output
 // Copyright (C) 2016 - Samuel GOUGEON
 //
 // Copyright (C) 2012 - 2016 - Scilab Enterprises
@@ -90,7 +90,13 @@ function [y, ind] = histplot(n,data,style,strf,leg,rect,nax,logflag,frameflag,ax
             opt_arg_seq = opt_arg_seq +","+ opt_arg + "=" + opt_arg
         end
     end
-    [y, ind] = histc(n, data, normalization);
+
+    if normalization then
+        tmp = "densityNorm,normWith: all"
+    else
+        tmp = "counts"
+    end
+    [y, tmp, tmp, ind] = histc(data, n, tmp);
 
     if length(n) == 1 then  // The number of classes is provided
         x = linspace(min(data), max(data), n+1); // Class boundary
index 6946d84..257ebbf 100644 (file)
@@ -302,7 +302,7 @@ _LaTeX_floor.xml_ru_RU_1.png=1d5ba78bbbafd3226f371146bc348363
 _LaTeX_grand.xml_1.png=dd59088e24bed7a6af5a6ccd16e58616
 _LaTeX_grand.xml_2.png=4065036eed5d60beaa7f246c013cbff0
 _LaTeX_hank.xml_1.png=fc6c604bc8c86af20a8f0673047332db
-_LaTeX_histc.xml_1.png=f1c5acc5939d55326dfab4af50e13f97
+_LaTeX_histc.xml_1.png=86e9e40df666b60dcf23b351b0d7ede9
 _LaTeX_histplot.xml_1.png=f1c5acc5939d55326dfab4af50e13f97
 _LaTeX_interp.xml_1.png=b99c07a3557a83033fdeedd84352b082
 _LaTeX_interp.xml_10.png=e257b3b19cc16006687169337c38dc2a
@@ -766,21 +766,12 @@ hist3d_ja_JP_1.png=9031d249fda1aeea0a14f05417e56bd7
 hist3d_pt_BR_1.png=9031d249fda1aeea0a14f05417e56bd7
 hist3d_ru_RU_1.png=9031d249fda1aeea0a14f05417e56bd7
 histc_1.png=e3160e15b52c7a263abc6dffd75986a2
-histc_en_US_2.png=9070537a80a0375317b25d3e8dae7cbb
-histc_en_US_3.png=031002528265de6488daf495e8099e50
-histc_en_US_4.png=b5f6b23a1b1ffc07f7f757b99de417f3
 histc_fr_FR_2.png=b88f7da2f29e4e54dade1ab37f25673f
 histc_fr_FR_3.png=9f67b78a341f6cb6fbd2bfd01af6445e
 histc_fr_FR_4.png=d59a06a8473a3c642c457580794688a3
 histc_ja_JP_2.png=aa5b81880d39e95eed5d46c4fe4fa16d
 histc_ja_JP_3.png=031002528265de6488daf495e8099e50
 histc_ja_JP_4.png=dfee4e3b15874ce09f823a25821d9e43
-histc_pt_BR_2.png=9070537a80a0375317b25d3e8dae7cbb
-histc_pt_BR_3.png=031002528265de6488daf495e8099e50
-histc_pt_BR_4.png=b5f6b23a1b1ffc07f7f757b99de417f3
-histc_ru_RU_2.png=9070537a80a0375317b25d3e8dae7cbb
-histc_ru_RU_3.png=031002528265de6488daf495e8099e50
-histc_ru_RU_4.png=b5f6b23a1b1ffc07f7f757b99de417f3
 histplot_1.png=becfb3115ba4cd9eaee18c2535dc557a
 histplot_en_US_2.png=8117e3f08f726740eb7a4e19b7c80cf1
 histplot_en_US_3.png=cd3e60e8f0a028549da7547fbf4b7222
index fabd3db..b35bdd0 100644 (file)
Binary files a/scilab/modules/helptools/images/_LaTeX_histc.xml_1.png and b/scilab/modules/helptools/images/_LaTeX_histc.xml_1.png differ
index fabd3db..9d87e36 100644 (file)
Binary files a/scilab/modules/helptools/images/_LaTeX_histplot.xml_1.png and b/scilab/modules/helptools/images/_LaTeX_histplot.xml_1.png differ
index 825aac7..d608045 100644 (file)
Binary files a/scilab/modules/helptools/images/histc_1.png and b/scilab/modules/helptools/images/histc_1.png differ
diff --git a/scilab/modules/helptools/images/histc_en_US_2.png b/scilab/modules/helptools/images/histc_en_US_2.png
deleted file mode 100644 (file)
index 720151e..0000000
Binary files a/scilab/modules/helptools/images/histc_en_US_2.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_en_US_3.png b/scilab/modules/helptools/images/histc_en_US_3.png
deleted file mode 100644 (file)
index d6fbc74..0000000
Binary files a/scilab/modules/helptools/images/histc_en_US_3.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_en_US_4.png b/scilab/modules/helptools/images/histc_en_US_4.png
deleted file mode 100644 (file)
index b680853..0000000
Binary files a/scilab/modules/helptools/images/histc_en_US_4.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_fr_FR_2.png b/scilab/modules/helptools/images/histc_fr_FR_2.png
deleted file mode 100644 (file)
index 7847584..0000000
Binary files a/scilab/modules/helptools/images/histc_fr_FR_2.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_fr_FR_3.png b/scilab/modules/helptools/images/histc_fr_FR_3.png
deleted file mode 100644 (file)
index 4bfbda0..0000000
Binary files a/scilab/modules/helptools/images/histc_fr_FR_3.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_fr_FR_4.png b/scilab/modules/helptools/images/histc_fr_FR_4.png
deleted file mode 100644 (file)
index aafcf94..0000000
Binary files a/scilab/modules/helptools/images/histc_fr_FR_4.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_ja_JP_2.png b/scilab/modules/helptools/images/histc_ja_JP_2.png
deleted file mode 100644 (file)
index d880c3c..0000000
Binary files a/scilab/modules/helptools/images/histc_ja_JP_2.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_ja_JP_3.png b/scilab/modules/helptools/images/histc_ja_JP_3.png
deleted file mode 100644 (file)
index b09a126..0000000
Binary files a/scilab/modules/helptools/images/histc_ja_JP_3.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_ja_JP_4.png b/scilab/modules/helptools/images/histc_ja_JP_4.png
deleted file mode 100644 (file)
index c3d3377..0000000
Binary files a/scilab/modules/helptools/images/histc_ja_JP_4.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_pt_BR_2.png b/scilab/modules/helptools/images/histc_pt_BR_2.png
deleted file mode 100644 (file)
index 0d0e434..0000000
Binary files a/scilab/modules/helptools/images/histc_pt_BR_2.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_pt_BR_3.png b/scilab/modules/helptools/images/histc_pt_BR_3.png
deleted file mode 100644 (file)
index 9ea1cef..0000000
Binary files a/scilab/modules/helptools/images/histc_pt_BR_3.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_pt_BR_4.png b/scilab/modules/helptools/images/histc_pt_BR_4.png
deleted file mode 100644 (file)
index 3ae7637..0000000
Binary files a/scilab/modules/helptools/images/histc_pt_BR_4.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_ru_RU_2.png b/scilab/modules/helptools/images/histc_ru_RU_2.png
deleted file mode 100644 (file)
index 0d0e434..0000000
Binary files a/scilab/modules/helptools/images/histc_ru_RU_2.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_ru_RU_3.png b/scilab/modules/helptools/images/histc_ru_RU_3.png
deleted file mode 100644 (file)
index 9ea1cef..0000000
Binary files a/scilab/modules/helptools/images/histc_ru_RU_3.png and /dev/null differ
diff --git a/scilab/modules/helptools/images/histc_ru_RU_4.png b/scilab/modules/helptools/images/histc_ru_RU_4.png
deleted file mode 100644 (file)
index 3ae7637..0000000
Binary files a/scilab/modules/helptools/images/histc_ru_RU_4.png and /dev/null differ
index bc05410..0a2960e 100644 (file)
@@ -1,9 +1,9 @@
 <?xml version='1.0' encoding='UTF-8'?>
 <!--
  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
  * Copyright (C) 2012 - 2016 - Scilab Enterprises
- * Copyright (C) 2018 - Samuel GOUGEON
+ * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
+ * Copyright (C) 2017 - 2018 - Samuel GOUGEON
  *
  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  * For more information, see the COPYING file which you should have received
  * along with this program.
  *
- --><!-- This document was created with Syntext Serna Free. -->
+ -->
 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
           xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
           xml:lang="en" xml:id="histc">
     <refnamediv>
         <refname>histc</refname>
-        <refpurpose>computes an histogram</refpurpose>
+        <refpurpose>computes the histogram of a simple series of data</refpurpose>
     </refnamediv>
     <refsynopsisdiv>
         <title>Syntax</title>
         <synopsis>
-            h = histc(n, data)
-            h = histc(x, data)
-            h = histc(.., normalization)
+            Heights = histc(Data)
+            Heights = histc(Data, nbins)
+            Heights = histc(Data, -binsWidth)
+            Heights = histc(Data, binsAlgo)
+            Heights = histc(Data, binsEdges)
+            Heights = histc(Data, binsValues [, "discrete"])
+            Heights = histc(Data,    , Options)
+            Heights = histc(Data, .. , Options)
+            [Heights, jokers]              = histc(Data, ..)
+            [Heights, jokers, bins]        = histc(Data, ..)
+            [Heights, jokers, bins, inBin] = histc(Data, ..)
         </synopsis>
     </refsynopsisdiv>
-    <refsection role="parameters">
+    <refsection role="arguments">
         <title>Arguments</title>
-        <variablelist>
-            <varlistentry>
-                <term>n</term>
-                <listitem>
-                    <para>positive integer (number of classes)</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>x</term>
-                <listitem>
-                    <para>
-                        increasing vector defining the classes (<literal>x</literal> may have at
-                        least 2 components)
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>data</term>
-                <listitem>
-                    <para>
-                        vector (data to be analysed)
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>h</term>
-                <listitem>
-                    <para>
-                      <itemizedlist>
-                        <listitem>
-                            <para>
-                            If <varname>normalization</varname> is %T: Probability densities on the
-                            bins defined by <varname>n</varname> or <varname>x</varname>, such that
-                            the bins areas are proportional to their populations.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-                            If <varname>normalization</varname> is %F: Numbers of elements in the bins.
-                            </para>
-                        </listitem>
-                      </itemizedlist>
-                    </para>
-                </listitem>
-            </varlistentry>
-          <!--
-            <varlistentry>
-                <term>ind</term>
-                <listitem>
-                    <para>
-                        vector or matrix of same size as <varname>data</varname>,
-                        representing the respective belonging of each element of data <varname>data</varname>
-                        to the classes defined by <varname>n</varname> or <varname>x</varname>
-                    </para>
-                </listitem>
-            </varlistentry>
-           -->
-            <varlistentry>
-                <term>normalization</term>
-                <listitem>
-                    <para>
-                      scalar boolean (default = %T), setting the type of output
-                      (see <varname>h</varname>).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection role="description">
-        <title>Description</title>
-        <para>
-            This function computes a histogram of the <literal>data</literal> vector using the
-            classes <literal>x</literal>. When the number <literal>n</literal> of classes is provided
-            instead of <literal>x</literal>, the classes are chosen equally spaced and
-            <emphasis>x(1) = min(data) &lt; x(2) = x(1) + dx &lt; ... &lt; x(n+1) = max(data)</emphasis>
-            with <emphasis>dx = (x(n+1)-x(1))/n</emphasis>.
-        </para>
-        <para>
-            The classes are defined by <literal>C1 = [x(1), x(2)]</literal> and <literal>Ci = ( x(i), x(i+1)]</literal> for i &gt;= 2.
-            Noting <literal>Nmax</literal> the total number of <literal>data</literal> (Nmax = length(data))
-            and <literal>Ni</literal> the number of <literal>data</literal> components falling in
-            <literal>Ci</literal>, the value of the histogram for <literal>x</literal> in
-            <literal>Ci</literal> is equal to <emphasis>Ni/(Nmax (x(i+1)-x(i)))</emphasis> when
-            <literal>"normalized"</literal> is selected and else, simply equal to <emphasis>Ni</emphasis>.
-            When normalization occurs the histogram verifies:
-        </para>
-        <para>
-            <latex style="display"><![CDATA[ \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1 ]]></latex>
-        </para>
-        <para>
-            when <emphasis>x(1)&lt;=min(data)</emphasis> and <emphasis>max(data) &lt;= x(n+1)</emphasis>
-        </para>
+        <refsect2>
+            <title>Input arguments</title>
+            <variablelist>
+                <varlistentry>
+                    <term>Data</term>
+                    <listitem>
+                        <para>
+                            vector, matrix or hypermatrix of encoded integers, decimal numbers,
+                            complex numbers, polynomials, or texts. Sparse-encoded matrices are accepted.
+                            <itemizedlist>
+                                <listitem>
+                                    <literal>Data</literal> must have at least 2 components.
+                                    <literal>histc([],..)</literal> returns <literal>[]</literal>
+                                    for every output argument.
+                                </listitem>
+                                <listitem>
+                                    Numerical <literal>Data</literal> may include
+                                    <literal>Inf</literal>inite or <literal>NaN</literal> values.
+                                    However,
+                                    <literal>NaN</literal> values are never binned in the histogram;
+                                    <literal>Inf</literal>inite values can be binned only in categorial
+                                    histograms.
+                                </listitem>
+                                <listitem>
+                                    Textual <literal>Data</literal> may include empty texts
+                                    <literal>""</literal> or extended-ascii or UTF-8 characters.
+                                </listitem>
+                            </itemizedlist>
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>Binning:</term>
+                    <listitem>
+                        <para>
+                            <literal>histc</literal> allows to define the set of histogram bins in
+                            several ways depending on the <literal>Data</literal> type and on the need.
+                            Two major binning types / histogram modes can be used:
+                            <itemizedlist>
+                                <listitem>
+                                    <para>
+                                        <emphasis role="bold">
+                                            continuous contiguous ranging bins
+                                        </emphasis>
+                                        :this is meaningful
+                                        whether <varname>Data</varname> values are sortable. This is
+                                        the case for encoded integers, decimal numbers, and texts.
+                                        <important>
+                                            <itemizedlist>
+                                                <listitem>
+                                                    <literal>histc()</literal> continuously bins complex
+                                                    numbers considering only their real parts.
+                                                </listitem>
+                                                <listitem>
+                                                    Any number with either a real or imaginary part set to
+                                                    <literal>%nan</literal>, <literal>-%inf</literal>, or to
+                                                    <literal>+%inf</literal> is excluded from bins and from
+                                                    the histogram.
+                                                </listitem>
+                                                <listitem>
+                                                    For sparse-encoded <varname>Data</varname>, the zero
+                                                    value is not taken into account to define the whole
+                                                    binning range.
+                                                </listitem>
+                                            </itemizedlist>
+                                        </important>
+                                    </para>
+                                    <para>
+                                        In this case, bins are defined by their edges. For a given bin,
+                                        any data value being between the bin's edges belongs to it.
+                                    </para>
+                                </listitem>
+                                <listitem>
+                                    <para>
+                                        <emphasis role="bold">
+                                            discrete / categorial binning mode
+                                        </emphasis>
+                                        :this can be used for any <literal>Data</literal>
+                                        type. It is the only binning mode available for polynomial data.
+                                    </para>
+                                    <para>
+                                        A categorial bin -- aka category -- is defined by its value:
+                                        any data belongs to the bin if its value
+                                        <emphasis role="italic">is equal to</emphasis> the bin's value.
+                                        <important>
+                                            Any <literal>Data</literal> or bin's value being
+                                            <literal>NaN</literal> is canceled before computing the
+                                            categorial histogram.
+                                        </important>
+                                    </para>
+                                </listitem>
+                            </itemizedlist>
+                            <variablelist>
+                                <varlistentry>
+                                    <term>(default)</term>
+                                    <listitem>
+                                        <para>
+                                            When no binning specification is provided,
+                                            <itemizedlist>
+                                                <listitem>
+                                                    For integers, decimal, or complex numbers, the
+                                                    <literal>"sqrt"</literal> binning algorithm is used
+                                                    See here-below for more informations.
+                                                </listitem>
+                                                <listitem>
+                                                    For texts and polynomials: the histogram is
+                                                    computed in <literal>"discrete"</literal> mode, with
+                                                    as many bins as there are distinct data entries.
+                                                </listitem>
+                                            </itemizedlist>
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>nbins</term>
+                                    <listitem>
+                                        <para>
+                                            single positive integer: required number of contiguous
+                                            bins of equal widths covering the whole range of
+                                            non-infinite <literal>Data</literal> values.
+                                            <warning>
+                                                This binning specification can't be used for texts
+                                                <literal>Data</literal>
+                                            </warning>
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>binsWidth</term>
+                                    <listitem>
+                                        <para>
+                                            Single decimal number > 0 specifying the bins width for all
+                                            bins. Its opposite <literal>-binsWidth &lt; 0</literal>
+                                            must be provided in input (to not get confused with
+                                            <literal>nbins</literal> that is already a single positive
+                                            number).
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>binsAlgo</term>
+                                    <listitem>
+                                        <para>
+                                            Single text word among the ones described here-below. These
+                                            automatic binning modes can be used for encoded integers,
+                                            decimal, or complex numbers. None of them can be used for
+                                            texts or polynomial data.
+                                        </para>
+                                        <para>
+                                            For these 3 modes, the whole range of data values is shared
+                                            into nB bins of equal widths. nB is set according to the
+                                            chosen algorithm as follows.
+                                        </para>
+                                        <para>
+                                            <table>
+                                                <tr>
+                                                    <td valign="top">
+                                                        <emphasis role="bold">"sqrt"</emphasis>:
+                                                    </td>
+                                                    <td>
+                                                        <para>
+                                                            nB is set to the square-root of the number
+                                                            <literal>Nvalid</literal> of
+                                                            valid data in <varname>Data</varname>, in such a
+                                                            way that there are as many bins as the
+                                                            average number of counts in bins. The vertical
+                                                            average relative resolution
+                                                            <literal>1 count / nB counts = 1/nB</literal>
+                                                            of the histogram is then similar to the
+                                                            horizontal one
+                                                            <literal>binWidth/range = (range/nB)/range = 1/nB</literal>
+                                                        </para>
+                                                        <para>
+                                                            However, for encoded integers data, if the
+                                                            data range
+                                                            <literal>dR=max(Data)-min(Data)+1</literal>
+                                                            is narrower than nB, nB is then set to dR,
+                                                            so setting the bins width to 1. Bins are then
+                                                            automatically centered on integer values in the
+                                                            range.
+                                                        </para>
+                                                    </td>
+                                                </tr>
+                                                <tr>
+                                                    <td valign="top">
+                                                        <emphasis role="bold">"freediac"</emphasis>:
+                                                    </td>
+                                                    <td>
+                                                        Freedmann - Diaconis binning criterion:
+                                                        <code>nB = round(strange(Data)/binWidth)</code>
+                                                        with
+                                                        <code>binsWidth = 2*iqr(Data)* Nvalid^(-1/3)</code>.
+                                                    </td>
+                                                </tr>
+                                                <tr>
+                                                    <td valign="top">
+                                                        <emphasis role="bold">"sturges"</emphasis>:
+                                                    </td>
+                                                    <td>
+                                                        Sturges binning criterion:
+                                                        <literal>nB = ceil(1 + log2(Nvalid))</literal>
+                                                    </td>
+                                                </tr>
+                                            </table>
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>binsEdges</term>
+                                    <listitem>
+                                        <para>
+                                            Vector of values sorted in strict increasing order (without
+                                            duplicates). N bins edges define N-1 bins.
+                                            For encoded integers <varname>Data</varname>,
+                                            <varname>binsEdges</varname> can be decimal numbers. For
+                                            complex numbers <varname>Data</varname>, decimal numbers are
+                                            expected in <varname>binsEdges</varname>: only the distribution
+                                            of real parts is considered.
+                                        </para>
+                                        <para>
+                                            <itemizedlist>
+                                                <listitem>
+                                                    First bin: Any non-infinite <varname>Data</varname>
+                                                    component belonging to the closed interval
+                                                    <literal>[binsEdges(1), binsEdges(2)]</literal>
+                                                    belongs to the first bin and is accounted in
+                                                    the <literal>Heights(1)</literal> count.
+                                                </listitem>
+                                                <listitem>
+                                                    Next bins # i>1: Any non-infinite
+                                                    <varname>Data</varname> component belonging to
+                                                    the semi-open interval
+                                                    <literal>]binsEdges(i), binsEdges(i+1)]</literal>
+                                                    belongs to the bin #i and is accounted in
+                                                    the <literal>Heights(i)</literal> count.
+                                                </listitem>
+                                            </itemizedlist>
+                                        </para>
+                                        <para>
+                                            <emphasis role="bold">Marginal bins:</emphasis>
+                                        </para>
+                                        <para>
+                                            For numerical and text <varname>Data</varname>, the first
+                                            or/and the last <varname>binsEdges</varname> components
+                                            may be set to collect and count
+                                            in marginal bins all non-infinite <varname>Data</varname>
+                                            components
+                                            remaining in the left and right wings of the complete
+                                            histogram:
+                                            <itemizedlist>
+                                                <listitem>
+                                                    <emphasis role="italic">Left wing:</emphasis> set
+                                                    <itemizedlist>
+                                                        <listitem>
+                                                            <literal>binsEdges(1) =
+                                                                <emphasis role="bold">-%inf</emphasis>
+                                                            </literal>
+                                                            ,
+                                                            or
+                                                        </listitem>
+                                                        <listitem>
+                                                            <literal>binsEdges(1) = ""</literal>
+                                                        </listitem>
+                                                    </itemizedlist>
+                                                    Then,
+                                                    <itemizedlist>
+                                                        <listitem>
+                                                            <varname>Data</varname> entries such that
+                                                            <literal>Data &lt; binsEdges(2)</literal> are
+                                                            counted in <literal>Heights(1)</literal>.
+                                                        </listitem>
+                                                        <listitem>
+                                                            The actual <literal>bins(1)</literal> edge
+                                                            is set to <literal>min(Data)</literal>.
+                                                        </listitem>
+                                                    </itemizedlist>
+                                                </listitem>
+                                                <listitem>
+                                                    <para></para>
+                                                    <emphasis role="italic">Right wing:</emphasis> set
+                                                    <itemizedlist>
+                                                        <listitem>
+                                                            <literal>binsEdges($) =
+                                                                <emphasis role="bold">%inf</emphasis>
+                                                            </literal>
+                                                            ,
+                                                            or
+                                                        </listitem>
+                                                        <listitem>
+                                                            <literal>binsEdges($) = "~~"</literal> (for
+                                                            texts in standard ascii,
+                                                            <literal>ascii(126)=="~"</literal> is the
+                                                            last printable character)
+                                                        </listitem>
+                                                    </itemizedlist>
+                                                    Then,
+                                                    <itemizedlist>
+                                                        <listitem>
+                                                            <varname>Data</varname> entries such that
+                                                            <literal>Data > binsEdges($-1)</literal> are
+                                                            counted in <literal>Heights($)</literal>.
+                                                        </listitem>
+                                                        <listitem>
+                                                            The actual <literal>bins($)</literal> edge
+                                                            is set to <literal>max(Data)</literal>.
+                                                        </listitem>
+                                                    </itemizedlist>
+                                                </listitem>
+                                            </itemizedlist>
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>binsValues</term>
+                                    <listitem>
+                                        <para>
+                                            For polynomial <varname>Data</varname> or when the
+                                            <varname>"discrete"</varname> option is used,
+                                            <varname>binsValues</varname> provides values whose
+                                            occurrences in <varname>Data</varname> must be counted.
+                                        </para>
+                                        <para>
+                                            <itemizedlist>
+                                                <listitem>
+                                                    Duplicates and <literal>%nan</literal> values are
+                                                    priorly removed from <varname>binsValues</varname>.
+                                                </listitem>
+                                                <listitem>
+                                                    <varname>binsValues</varname> may include some
+                                                    <literal>%inf</literal> values. However,
+                                                    for encoded integers <varname>Data</varname>,
+                                                    any <literal>%inf</literal> value is removed
+                                                    before processing.
+                                                </listitem>
+                                                <listitem>
+                                                    Components of <varname>binsValues</varname> may be
+                                                    unsorted: the order of <varname>binsValues</varname>
+                                                    components is kept as is in the
+                                                    <varname>Heights</varname> output vector.
+                                                </listitem>
+                                            </itemizedlist>
+
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                            </variablelist>
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>Options</term>
+                    <listitem>
+                        <para>
+                            <literal>Options</literal> is either a vector of textual flags, or equivalently
+                            a single word of <emphasis role="italic">comma-separated</emphasis>
+                            concatenated flags, or both. All flags are
+                            <emphasis role="italic">case-insensitive</emphasis> and can be specified
+                            <emphasis role="italic">in any order</emphasis>.
+                        </para>
+                        <para>
+                            Examples: The following options specifications are equivalent:
+                            <literal>["discrete" "countsNorm" "normWith: Out Inf"]</literal>, or
+                            <literal>["countsNORM" "NORMwith: inf out" "Discrete" ]</literal>, or
+                            <literal>["normWith: INF OUT", "discrete, countsNorm" ]</literal>, or simply
+                            <literal>"discrete,countsNorm,normWith: inf out"</literal>.
+                        </para>
+                        <para>
+                            <variablelist>
+                                <varlistentry>
+                                    <term>"discrete"</term>
+                                    <listitem>
+                                        <para>
+                                            This flag must be used when a discrete / categorial histogram is
+                                            required. Then, the vector provided in argument #2 with at
+                                            least 2 components sets
+                                            <emphasis role="italic">bins values</emphasis> instead of
+                                            <emphasis role="italic">bins edges</emphasis> (by default).
+                                            <note>
+                                                Presently, polynomial <varname>Data</varname> are always
+                                                processed in a categorial way. The <varname>"discrete"</varname>
+                                                flag looks then useless. However, in a future release, polynomials
+                                                could become sortable. Using the <varname>"discrete"</varname>
+                                                flag does not hurt and would avoid future back-compatibility
+                                                issues.
+                                            </note>
+                                        </para>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>Histogram scale:</term>
+                                    <listitem>
+                                        <table>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"counts"</emphasis>
+                                                </td>
+                                                <td>
+                                                    <para>
+                                                        This mode is the default one: Whatever is each bin's width, the
+                                                        <emphasis role="italic">height</emphasis> of the bin is equal
+                                                        to the number of <varname>Data</varname> components falling in it.
+                                                    </para>
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"countsNorm"</emphasis>
+                                                </td>
+                                                <td>
+                                                    <para>
+                                                        Whatever is each bin's width and position, the
+                                                        <emphasis role="italic">height</emphasis> of the bin is equal
+                                                        to the <emphasis role="italic">relative</emphasis> number of
+                                                        <varname>Data</varname> components falling in it,
+                                                        over all counted components.
+                                                        Then, unless the <literal>"normWith:.."</literal>
+                                                        option is used, the cumulated bins heights is equal to 1:
+                                                        <literal>sum(Heights)==1</literal>.
+                                                    </para>
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"density"</emphasis>
+                                                </td>
+                                                <td>
+                                                    <para>
+                                                        The <emphasis role="italic">area</emphasis> of each bin is equal
+                                                        to the number of <varname>Data</varname> components falling in it.
+                                                        This scaling mode is meaningless and ignored in case of
+                                                        <emphasis role="italic">categorial</emphasis> histogram.
+                                                    </para>
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"densityNorm"</emphasis>
+                                                </td>
+                                                <td>
+                                                    <para>
+                                                        The <emphasis role="italic">area</emphasis> of each bin is equal
+                                                        to the <emphasis role="italic">relative</emphasis> number of
+                                                        <varname>Data</varname> components falling in it. Then, unless
+                                                        the <literal>"normWith:.."</literal> option is used, the whole
+                                                        area of the histogram is equal to 1:
+                                                        <para>
+                                                            <latex style="display"><![CDATA[ \int_{binsEdges(1)}^{binsEdges(\$)}h(x)\,\mathrm{d}x=1 ]]></latex>
+                                                        </para>
+                                                    </para>
+                                                    <para>
+                                                        This scaling mode is meaningless and ignored in case of
+                                                        <emphasis role="italic">categorial</emphasis> histogram.
+                                                    </para>
+                                                </td>
+                                            </tr>
+                                        </table>
+                                    </listitem>
+                                </varlistentry>
+                                <varlistentry>
+                                    <term>"normWith:.."</term>
+                                    <listitem>
+                                        <para>
+                                            When the <literal>"countsNorm"</literal> or <literal>"densityNorm"</literal>
+                                            option is used, it is possible to provide additional informations about which
+                                            components of <varname>Data</varname> out of bins should be considered
+                                            for the total number N of counts over which the normalization is computed.
+                                        </para>
+                                        <para>
+                                            After the <literal>"normWith:"</literal> option's header, a
+                                            <emphasis role="italic">space-separated</emphasis> list of
+                                            <emphasis role="italic">case-insensitive</emphasis> flags can be provided
+                                            <emphasis role="italic">in any order</emphasis>. If several concurrent
+                                            flags are provided, only the last specified one is taken into account.
+                                            Unrelevant flags for the given <literal>Data</literal> type are ignored.
+                                            Available flags and their relative priorities are described here-below.
+                                            Examples:
+                                            <literal>"normWith: all"</literal>,
+                                            <literal>"normWith: out inf"</literal>,
+                                            <literal>"normWith: Nan inf"</literal>,
+                                            <literal>"normWith: rightout inf"</literal>, etc.
+                                        </para>
+                                        <table>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"all"</emphasis>
+                                                </td>
+                                                <td>
+                                                    All components of <varname>Data</varname> are considered:
+                                                    <literal>N = size(Data,"*")</literal>. If <literal>"all"</literal>
+                                                    is used, all other <literal>"normWith:.."</literal> options are ignored.
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"out"</emphasis>
+                                                </td>
+                                                <td>
+                                                    All <varname>Data</varname> out of <varname>bins</varname> that are
+                                                    not <literal>Nan</literal> or <literal>Inf</literal> or
+                                                    <literal>""</literal> are accounted.
+                                                    If <varname>Data</varname> is sparse-encoded, zeros remain excluded
+                                                    unless the option <literal>"normWith: zeros"</literal> is used.
+                                                    If <literal>"out"</literal> is used, <literal>"leftout"</literal>
+                                                    and <literal>"rightout"</literal> options are ignored.
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"leftout"</emphasis>
+                                                </td>
+                                                <td>
+                                                    As with <literal>"out"</literal>, but only for
+                                                    <literal>Data &lt; binsEdges(1)</literal>.
+                                                    This flag is ignored in discrete/categorial mode.
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"rightout"</emphasis>
+                                                </td>
+                                                <td>
+                                                    As with <literal>"out"</literal>, but only for
+                                                    <literal>Data > binsEdges($)</literal>.
+                                                    This flag is ignored in discrete/categorial mode.
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"NaN"</emphasis>
+                                                </td>
+                                                <td>
+                                                    <literal>NaN</literal> data are accounted, in addition to
+                                                    other ones.
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"Inf"</emphasis>
+                                                </td>
+                                                <td>
+                                                    <literal>Inf</literal> data are accounted, in addition to
+                                                    other ones.
+                                                    <para>
+                                                        In discrete/categorial mode, <literal>Inf</literal>
+                                                        values are not specific and are processed as other ones.
+                                                        This flag is then ignored.
+                                                    </para>
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"zeros"</emphasis>
+                                                </td>
+                                                <td>
+                                                    If <varname>Data</varname> is sparse-encoded, by default only
+                                                    non-zero elements are considered (otherwise, zeros are not specific
+                                                    and are processed as other values). Nevertheless, it's possible
+                                                    to take them into account in the normalization by using this
+                                                    <literal>"normWith: zeros"</literal> flag.
+                                                    <important>
+                                                        Using this flag does not credit the <literal>Heights</literal>
+                                                        of the bin covering the zero value (if any).
+                                                    </important>
+                                                </td>
+                                            </tr>
+                                            <tr>
+                                                <td valign="top">
+                                                    <emphasis role="bold">"empty"</emphasis>
+                                                </td>
+                                                <td>
+                                                    <literal>""</literal> empty texts in <varname>Data</varname>
+                                                    are accounted, in addition to other ones.
+                                                </td>
+                                            </tr>
+                                        </table>
+                                    </listitem>
+                                </varlistentry>
+                            </variablelist>
+                        </para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </refsect2>
+        <refsect2>
+            <title>Results</title>
+            <variablelist>
+                <varlistentry>
+                    <term>Heights</term>
+                    <listitem>
+                        <para>
+                            vector of decimal numbers whose values depend on the histogram scaling mode
+                            set with each dedicated option.
+                            See the description of the <literal>Histogram scales</literal> options
+                            here-above. In brief:
+                            <itemizedlist>
+                                <listitem>
+                                    <literal>"counts"</literal> mode: <varname>Heights(i)</varname>
+                                    is the number of <varname>Data</varname> components equal to the
+                                    <literal>bins(i)</literal> value (categorial), or belonging to the
+                                    <literal>]bins(i), bins(i+1)]</literal> interval (continuous histogram).
+                                </listitem>
+                                <listitem>
+                                    <literal>"countsNorm"</literal> mode: <varname>Heights(i)</varname>
+                                    is as for <literal>"counts"</literal>, divided by the total number
+                                    <literal>N</literal> of considered <varname>Data</varname> components.
+                                    <literal>N</literal> is the sum of counts in all bins, plus
+                                    possibly the number of counts of some special jokers values
+                                    (<literal>%inf, %nan, 0, ""</literal>), according to the
+                                    <literal>normWith:</literal> option used.
+                                </listitem>
+                            </itemizedlist>
+                        </para>
+                        <para>
+                            In continuous mode, statistical densities may be returned in the vector
+                            <varname>Heights</varname> instead of integer numbers of counts: Let's
+                            call <literal>counts(i)</literal> the number of counts in the
+                            bin #i defined by its edges. Then
+                            <itemizedlist>
+                                <listitem>
+                                    In <literal>"density"</literal> mode: <varname>Heights(i)</varname>
+                                    is set such that the <emphasis role="italic">area</emphasis> of
+                                    the bin is equal to its population:
+                                    <literal>Heights(i) * (binsEdges(i+1) - binsEdges(i)) == counts(i)</literal>.
+                                </listitem>
+                                <listitem>
+                                    In <literal>"densityNorm"</literal> mode: the
+                                    <literal>"density"</literal> results are divided by the total number
+                                    <literal>N</literal> of considered counts
+                                    (see <literal>"countsNorm"</literal>).
+                                </listitem>
+                            </itemizedlist>
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>jokers</term>
+                    <listitem>
+                        <para>
+                            Row vector of 1 to 5 decimal numbers indicating the frequency of special
+                            values in <literal>Data</literal>. Let's define the following numbers:
+                            <itemizedlist>
+                                <listitem>
+                                    <literal>Nnan</literal>: number of <literal>NaN</literal> objects
+                                    in <literal>Data</literal>.
+                                </listitem>
+                                <listitem>
+                                    <literal>Ninf</literal>: number of <literal>Inf</literal> objects
+                                    in <literal>Data</literal>.
+                                </listitem>
+                                <listitem>
+                                    <literal>Nzeros</literal>: number of null values in
+                                    <literal>Data</literal>.
+                                </listitem>
+                                <listitem>
+                                    <literal>Nempty</literal>: number of empty texts "" in
+                                    <literal>Data</literal>.
+                                </listitem>
+                                <listitem>
+                                    <literal>Nleftout</literal>: number of <literal>Data</literal>
+                                    components not equal to <literal>-%inf</literal> nor to
+                                    <literal>""</literal>, such that
+                                    <literal>Data &lt; binsEdges(1)</literal>.
+                                </listitem>
+                                <listitem>
+                                    <literal>Nrightout</literal>: number of <literal>Data</literal>
+                                    components not equal to <literal>%inf</literal> such that
+                                    <literal>Data > binsEdges($)</literal>.
+                                </listitem>
+                                <listitem>
+                                    <literal>Nout</literal>: number of <literal>Data</literal>
+                                    components out of bins, non-infinite, not being
+                                    <literal>Nan</literal>, not being empty text <literal>""</literal>,
+                                    and for sparse <literal>Data</literal>: not equal to zero.
+                                </listitem>
+                            </itemizedlist>
+                        </para>
+                        <para>
+                            In unnormalized <literal>"counts"</literal> and <literal>"density"</literal>
+                            histogram scales, <varname>jokers</varname> returns the integer
+                            <emphasis role="italic">counts</emphasis> numbers of special values.
+                        </para>
+                        <para>
+                            In normalized <literal>"countsNorm"</literal> and <literal>"densityNorm"</literal>
+                            histogram scales, <varname>jokers</varname> returns
+                            <emphasis role="italic">countsNorm</emphasis> frequencies of special values.
+                        </para>
+                        <para>
+                            Then, according to the <literal>Data</literal> type and the
+                            <emphasis role="italic">continuous</emphasis> or
+                            <emphasis role="italic">categorial</emphasis> histogram mode,
+                            <varname>jokers</varname> is made of the following:
+                            <orderedlist>
+                                <listitem>
+                                    <emphasis role="italic">Encoded integers:</emphasis>
+                                    <itemizedlist>
+                                        <listitem>
+                                            continuous: <literal>[Nleftout, Nrightout]</literal>
+                                        </listitem>
+                                        <listitem>
+                                            categorial: <literal>[Nout]</literal>
+                                        </listitem>
+                                    </itemizedlist>
+                                </listitem>
+                                <listitem>
+                                    <emphasis role="italic">
+                                        Decimal or complex numbers, full or sparse:
+                                    </emphasis>
+                                    <itemizedlist>
+                                        <listitem>
+                                            continuous:
+                                            <literal>[Nleftout, Nrightout, Nzeros, Nnan, Ninf]</literal>
+                                        </listitem>
+                                        <listitem>
+                                            categorial: <literal>[Nout, 0, Nzeros, Nnan, Ninf]</literal>
+                                        </listitem>
+                                    </itemizedlist>
+                                </listitem>
+                                <listitem>
+                                    <emphasis role="italic">Polynomials:</emphasis>
+                                    <literal>[Nout, 0, 0, Nnan, Ninf]</literal>
+                                </listitem>
+                                <listitem>
+                                    <emphasis role="italic">Texts:</emphasis>
+                                    <itemizedlist>
+                                        <listitem>
+                                            continuous: <literal>[Nleftout, Nrightout, Nempty]</literal>
+                                        </listitem>
+                                        <listitem>
+                                            categorial: <literal>[Nout, 0, Nempty]</literal>
+                                        </listitem>
+                                    </itemizedlist>
+                                </listitem>
+                            </orderedlist>
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>bins</term>
+                    <listitem>
+                        <para>
+                            Row vector of bins edges or of bins values actually used to build the histogram.
+                            <literal>histc()</literal> allows using many semi-automatic or automatic
+                            binning modes for which no explicit or incomplete <varname>binsEdges</varname>
+                            or <varname>binsValues</varname> vector is provided as input.
+                            <itemizedlist>
+                                <listitem>
+                                    Continuous binning mode:
+                                    <itemizedlist>
+                                        <listitem>
+                                            The actual <varname>binsEdges</varname> is returned in
+                                            <varname>bins</varname>. It has the
+                                            <varname>Heights</varname> number of components, + 1
+                                            (position of the closing edge).
+                                        </listitem>
+                                        <listitem>
+                                            <para>
+                                                For encoded integers, decimal numbers, and complex numbers
+                                                <varname>Data</varname>, <varname>bins</varname> is of
+                                                decimal type. For text <varname>Data</varname>,
+                                                <varname>bins</varname> is of type text as well.
+                                            </para>
+                                        </listitem>
+                                        <listitem>
+                                            <para>
+                                                When marginal bins are required (see the
+                                                <varname>binsEdges</varname> description)
+                                                <literal>bins(1)</literal> and <literal>bins($)</literal>
+                                                return the actual boundaries of the whole binning range
+                                                used.
+                                            </para>
+                                        </listitem>
+                                    </itemizedlist>
+                                </listitem>
+                                <listitem>
+                                    Discrete categorial mode:
+                                    <para>
+                                        For polynomial <varname>Data</varname>, or
+                                        for other <varname>Data</varname> types used with the
+                                        <varname>"discrete"</varname> option: if no explicit
+                                        <varname>binsValues</varname> vector is provided,
+                                        <literal>histc()</literal> sets it to
+                                        <literal>unique(Data)(:)'</literal> and returns it as
+                                        <varname>bins</varname>.
+                                    </para>
+                                </listitem>
+                            </itemizedlist>
+                        </para>
+                    </listitem>
+                </varlistentry>
+                <varlistentry>
+                    <term>inBin</term>
+                    <listitem>
+                        <para>
+                            Array of decimal integers having the sizes of <varname>Data</varname>.
+                            If <varname>Data</varname> is sparse-encoded, <varname>inBin</varname>
+                            is so as well.
+                        </para>
+                        <para>
+                            <literal>inBin(i,j)</literal> returns the index of the <varname>bins</varname>
+                            which <literal>Data(i,j)</literal> belongs to. If the value of
+                            <literal>Data(i,j)</literal> is out of bins, <literal>inBin(i,j)=0</literal>.
+                            Otherwise, <literal>Data(i,j)</literal> increments the
+                            <literal>Heights(inBin(i,j))</literal> counts by one unit.
+                        </para>
+                    </listitem>
+                </varlistentry>
+            </variablelist>
+        </refsect2>
     </refsection>
-    <refsection role="examples">
+     <refsection role="examples">
         <title>Examples</title>
-        <simplelist>
-            <member> Example #1: variations around a histogram of a gaussian random sample
-                <programlisting role="example"><![CDATA[
-// The gaussian random sample
-d = rand(1, 10000, 'normal');
+        <refsect2>
+            <title>with decimal numbers:</title>
+            <programlisting role="example"><![CDATA[
+data = [1 1 1 2 2 3 4 4 5 5 5 6 6 7 8 8 9 9 9];
+N = size(data,"*")   // ==19
 
-h = histc(20, d, normalization=%f);
-sum(h)   // = 10000
-// We use histplot to show a graphic representation
-clf(); histplot(20, d, normalization=%f);
+// Default binning; "sqrt": sqrt(19) => 4. .. => 4 bins
+[h, j, b, i] = histc(data)
+// expected: h = [6 5 3 5] = href
+// expected: b = [1 3 5 7 9] bins edges
+// expected: i = [1 1 1 1 1 1 2 2 2 2 2 3 3 3 4 4 4 4 4]  d memberships to bins
+histc(data, , "countsNorm")   // Expected: href/N
+histc(data, , "density")      // Expected: href/2, 2 being the bins width
+histc(data, , "densityNorm")  // Expected: href/N/2
 
-// Normalized histogram (probability density)
-h = histc(20, d);
-dx = (max(d)-min(d))/20;  sum(h)*dx   // = 1
-clf(); histplot(20, d);
-]]></programlisting>
-                <scilab:image>
-                    d = rand(1, 10000, 'normal');
-                    h = histc(20, d);
-                    clf(); histplot(20, d);
-                </scilab:image>
-            </member>
-            <member>
-                Example #2: histogram of a binomial (B(6,0.5)) random sample
-                <programlisting role="example"><![CDATA[
-d = grand(1000,1,"bin", 6, 0.5);
-c = linspace(-0.5,6.5,8);
-clf()
+// Automatic Sturges binning
+[h, j, b, i] = histc(data,"sturges")    // h = [5 1 5 2 1 5]
+                                        // b = [3 7 11 15 19 23 27] / 3
+                                        // i = [1 1 1 1 1 2 3 3 3 3 3 4 4 5 6 6 6 6 6]
 
-subplot(2,1,1)
-h = histc(c, d);
-histplot(c, d, style=2);
-xtitle(_("Normalized histogram"))
+// Explicit bins edges, with marginal bins
+// ---------------------------------------
+data = [1 1 1 2 2 3 4 4 5 5 5 6 6 7 8 8 9 9 9];
+be = [-%inf 3 5 7 %inf];
+[href, j, b, i] = histc(data, be)   // href = [6 5 3 5] => sum N = 19
+                                    // b = [1 3 5 7 9]  // bins completed with actual data bounds
+                                    // i = [1 1 1 1 1 1 2 2 2 2 2 3 3 3 4 4 4 4 4]
+histc(data, be, "countsNorm")       // href/N
+histc(data, be, "density")          // href/2   bins width = 2: see b
+histc(data, be, "densityNorm")      // href/N/2
 
-subplot(2,1,2)
-h = histc(c, d, normalization=%f);
-histplot(c, d, normalization=%f, style=5);
-xtitle(_("Non normalized histogram"))
-]]></programlisting>
-                <scilab:image localized="true">
-                    d = grand(1000,1,"bin", 6, 0.5);
-                    c = linspace(-0.5,6.5,8);
-                    clf()
-                    subplot(2,1,1)
-                    h = histc(c, d);
-                    histplot(c, d, style=2);
-                    xtitle(_("Normalized histogram"))
-                    subplot(2,1,2)
-                    h = histc(c, d, normalization=%f)
-                    histplot(c, d, normalization=%f, style=5);
-                    xtitle(_("Non normalized histogram"))
-                </scilab:image>
-            </member>
-            <member>
-                Example #3: histogram of an exponential random sample
-                <programlisting role="example"><![CDATA[
-lambda = 2;
-X = grand(100000,1,"exp", 1/lambda);
-Xmax = max(X);
-h = histc(40, X);
+// Explicit bins edges, with outsiders
+// -----------------------------------
+data = [1 1 1 2 2 3 4 4 5 5 5 6 6 7 8 8 9 9 9]; // still the same
+be = [2, 5.5, 7];   // Bins edges (2 bins)
+[href, jref, b, i] = histc(d, be)   // href = [8 3]   jref = [3 5 0 0 0] = [leftout, rightout, ..]
+                                    // i = [0 0 0 1 1 1 1 1 1 1 1 2 2 2 0 0 0 0 0]
+histc(data, be, "countsNorm")                       // href / 11
+histc(data, be, "countsNorm, normWith: leftout")    // href / 14
+histc(data, be, "countsNorm, normWith: rightout")   // href / 16
+histc(data, be, "countsNorm, normWith: out")        // href / 19
+histc(data, be, "density")                          // href ./ diff(be)
+histc(data, be, "densityNorm")                      // href ./ diff(be) / 11
+histc(data, be, "densityNorm, normWith: leftout")   // href ./ diff(be) / 14
+histc(data, be, "densityNorm, normWith: rightout")  // href ./ diff(be) / 16
+histc(data, be, "densityNorm, normWith: all");      // href ./ diff(be) / 19
 
-clf()
-histplot(40, X, style=2);
-x = linspace(0, max(Xmax), 100)';
-plot2d(x, lambda*exp(-lambda*x), strf="000", style=5)
-legend([_("exponential random sample histogram") _("exact density curve")]);
-]]></programlisting>
-                <scilab:image localized="true">
-                    lambda = 2;
-                    X = grand(100000,1,"exp", 1/lambda);
-                    Xmax = max(X);
-                    h = histc(40, X);
-                    clf()
-                    histplot(40, X, style=2);
-                    x = linspace(0, max(Xmax), 100)';
-                    plot2d(x, lambda*exp(-lambda*x), strf="000", style=5)
-                    legend([_("exponential random sample histogram") _("exact density curve")]);
-                </scilab:image>
-            </member>
-            <member>
-                Example #4: the frequency polygon chart and the histogram of a gaussian random sample
-                <programlisting role="example"><![CDATA[
-n = 10;
-data = rand(1, 1000, "normal");
-h = histc(n, data);
+// With Nan and Inf values
+// -----------------------
+data = [1 1 1 2 2 3 4 4 5 5 5 6 6 7 8 8 9 9 9];
+data = [%nan %inf, data, %nan %nan -%inf];
+N = size(data,"*");         // 24
+be = [2, 4.5, 7];           // Set bins edges (2 bins)
+[href, jref, b, iref] = histc(data, be) //  href = [5 6]  jref = [3 5 0 3 2];
+                            // continuous mode: jokers = [leftout, rightout, zeros, nan, inf]
+                            // iref = [0 0 0 0 0 1 1 1 1 1 2 2 2 2 2 2 0 0 0 0 0 0 0 0]  memberships
+[h, j] = histc(data, be, "countsNorm")                          // Expected: href/11, jref/11
+[h, j] = histc(data, be, "countsNorm, normWith: nan")           // Expected: href/14, jref/14
+[h, j] = histc(data, be, "countsNorm, normWith: inf")           // Expected: href/13, jref/13
+[h, j] = histc(data, be, "countsNorm, normWith: inf nan")       // Expected: href/16, jref/16
+[h, j] = histc(data, be, "countsNorm, normWith: leftout nan")   // Expected: href/17, jref/17
+[h, j] = histc(data, be, "countsNorm, normWith: rightout inf")  // Expected: href/18, jref/18
+[h, j] = histc(data, be, "countsNorm, normWith: out inf")       // Expected: href/21, jref/21
+[h, j] = histc(data, be, "countsNorm, normWith: all")           // Expected: href/24, jref/24
+
+// Normalized densities over a Bins width = 2.5 (see be)
+[h, j] = histc(data, be, "densityNorm")                         // Expected: href/11/2.5, jref/11
+[h, j] = histc(data, be, "densityNorm, normWith: nan")          // Expected: href/14/2.5, jref/14
+[h, j] = histc(data, be, "densityNorm, normWith: inf")          // Expected: href/13/2.5, jref/13
+[h, j] = histc(data, be, "densityNorm, normWith: inf nan")      // Expected: href/16/2.5, jref/16
+[h, j] = histc(data, be, "densityNorm, normWith: leftout nan")  // Expected: href/17/2.5, jref/17
+[h, j] = histc(data, be, "densityNorm, normWith: rightout inf") // Expected: href/18/2.5, jref/18
+[h, j] = histc(data, be, "densityNorm, normWith: all")          // Expected: href/24/2.5, jref/24
+     ]]></programlisting>
+        </refsect2>
+        <refsect2>
+            <title>with texts:</title>
+            <programlisting role="example"><![CDATA[
+histc(["a" "c" "a" "a" "b" "c"])    //  [3 1 2]
+
+t = [
+"c" "n" "h" "i" "b" "i" "f" "i" "p" "l" "p" "d" "f" "i" "l"
+"b" "m" "e" "o" "o" "f" "p" "o" "h" "f" "h" "h" "c" "k" "o"
+"p" "f" "k" "a" "j" "o" "j" "d" "h" "h" "n" "m" "o" "l" "n"
+"h" "b" "o" "l" "j" "n" "o" "i" "g" "i" "a" "a" "j" "d" "p"
+ ];
+// With default discrete bins
+// --------------------------
+[h,j,b,i] = histc(t)  // h = [3  3 2 3 1 5 1 7 6 4 2 4 2 4 8 5]
+                      // b = "a" b c d e f g h i j k l m n o p
+iref = [
+3   14  8   9   2   9   6   9   16  12  16  4   6   9   12
+2   13  5   15  15  6   16  15  8   6   8   8   3   11  15
+16  6   11  1   10  15  10  4   8   8   14  13  15  12  14
+8   2   15  12  10  14  15  9   7   9   1   1   10  4   16
+];
+
+// With given discrete bins WITHOUT "" bins
+// ----------------------------------------
+t2 = t;
+t2([7 13 19 26 32 39 43]) = "";
+// --> t2  =
+// c  n  h     b  i  f  i  p  l  p  d  f  i  l
+// b  m  e  o  o  f     o  h  f  h  h  c  k  o
+// p     k  a     o  j  d  h        m  o  l  n
+// h  b  o  l  j  n  o     g  i  a  a  j  d  p
+//
+// b =  '' a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p
+// h =  7  3  3  2  3  1  4  1  6  4  3  2  4  2  3  8  4
+
+[h, j, b, i] = histc(t2, ["a" "e" "i" "o"], "discrete")
+                                            // h = [3 1 4 8];  N = 16
+                                            // j = [37 0 7] = [out, 0, #""]
+// i = [    // memberships
+// 0  0  0  0  0  3  0  3  0  0  0  0  0  3  0
+// 0  0  2  4  4  0  0  4  0  0  0  0  0  0  4
+// 0  0  0  1  0  4  0  0  0  0  0  0  4  0  0
+// 0  0  4  0  0  0  4  0  0  3  1  1  0  0  0
+// ];
 
-clf(), histplot(n, data, style=12, polygon=%t);
-legend([_("normalized histogram") _("frequency polygon chart")], "lower_caption");
+// With continuous and marginal bins: "" <=> -inf , "~~" <=> Inf (regular ascii)
+// -----------------------------------------------------------------------------
+[h,j,b,i] = histc(t, ["" "c" "e" "g" "i" "k" "m" "~~"])
+                    // h = [8 4 6 13 6 6 17]    j = [0 0 0]
+// i = [    // memberships
+// 1  7  4  4  1  4  3  4  7  6  7  2  3  4  6
+// 1  6  2  7  7  3  7  7  4  3  4  4  1  5  7
+// 7  3  5  1  5  7  5  2  4  4  7  6  7  6  7
+// 4  1  7  6  5  7  7  4  3  4  1  1  5  2  7
+// ];
+
+// Continuous bins. Data WITH ""
+// -----------------------------
+// t2  =
+// c  n  h     b  i  f  i  p  l  p  d  f  i  l
+// b  m  e  o  o  f     o  h  f  h  h  c  k  o
+// p     k  a     o  j  d  h        m  o  l  n
+// h  b  o  l  j  n  o     g  i  a  a  j  d  p
+//
+// b =  '' a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p
+// h =  7  3  3  2  3  1  4  1  6  4  3  2  4  2  3  8  4
+binsEdges = ["e" "f" "g" "h" "i" "j"];
+[href, jref, b, i] = histc(t2, binsEdges)   // href=[5 1 6 4 3]; N = sum(href) = 19
+                                            // jref=[11  23  7]; [leftout rightout ""]
+
+[h,j,b,i] = histc(t2, binsEdges, "countsNorm,normWith: leftout")
+                                            // h = href / (N+jref(1)),   j = jref / (N+jref(1))
+[h,j,b,i] = histc(t2, binsEdges, "countsNorm,normWith: rightout")
+                                            // h = href / (N+jref(2)),  j = jref / (N+jref(2))
+[h,j,b,i] = histc(t2, binsEdges, "countsNorm,normWith: out");
+                                            // h = href / sum([N jref(1:2)]), j = jref / sum([N jref(1:2)])
+[h,j,b,i] = histc(t2, binsEdges, "countsNorm,normWith: empty")
+                                            // h = href / (N+jref(3)), j = jref/(N+jref(3))
+[h,j,b,i] = histc(t2, binsEdges,"countsNorm,normWith: out empty")
+                                            // h = href / sum([N jref]), j = jref / sum([N jref])
+[h,j,b,i] = histc(t2, binsEdges, "countsNorm,normWith: all")
+                                            // h = href / sum([N jref]), j = jref/sum([N jref])
+     ]]></programlisting>
+        </refsect2>
+        <refsect2>
+            <title>with polynomials:</title>
+            <programlisting role="example"><![CDATA[
+histc([%z 2+%z %z])                                     // [2 1]
+histc([%z 2+%z %z],, "countsnorm")                      // [2 1] / 3
+histc([%z 2+%z %z %nan],, "countsnorm")                 // [2 1] / 3
+histc([%z 2+%z %z %nan],, "countsnorm, normWith: Nan")  // [2 1] / 4
+// Data order is kept:
+histc([2+%z %z %z ]) == [1 2]
 ]]></programlisting>
-                <scilab:image localized="true">
-                    n = 10;
-                    data = rand(1, 1000, "normal");
-                    h = histc(n, data);
-                    clf(); histplot(n, data, style=12, polygon=%t);
-                    legend([_("normalized histogram") _("frequency polygon chart")],"lower_caption");
-                </scilab:image>
-            </member>
-        </simplelist>
+        </refsect2>
+
     </refsection>
     <refsection role="see also">
         <title>See also</title>
@@ -235,11 +1032,32 @@ legend([_("normalized histogram") _("frequency polygon chart")], "lower_caption"
                 <link linkend="hist3d">hist3d</link>
             </member>
             <member>
-                <link linkend="plot2d">plot2d</link>
+                <link linkend="bar">bar</link>
+            </member>
+            <member>
+                <link linkend="barh">barh</link>
+            </member>
+            <member>
+                <link linkend="plot2d2">plot2d2</link>
             </member>
             <member>
                 <link linkend="dsearch">dsearch</link>
             </member>
+            <member>
+                <link linkend="members">members</link>
+            </member>
+            <member>
+                <link linkend="grep">grep</link>
+            </member>
+            <member>
+                <link linkend="strcmp">strcmp</link>
+            </member>
+            <member>
+                <link linkend="isnan">isnan</link>
+            </member>
+            <member>
+                <link linkend="isinf">isinf</link>
+            </member>
         </simplelist>
     </refsection>
     <refsection role="history">
@@ -248,7 +1066,68 @@ legend([_("normalized histogram") _("frequency polygon chart")], "lower_caption"
             <revision>
                 <revnumber>5.5.0</revnumber>
                 <revdescription>
-                    Introduction
+                    histc() introduced
+                </revdescription>
+            </revision>
+            <revision>
+                <revnumber>6.1.0</revnumber>
+                <revdescription>
+                    histc() reforged:
+                    <itemizedlist>
+                        <listitem>
+                            Data and nbins input arguments are commuted.
+                        </listitem>
+                        <listitem>
+                            New accepted Data types: complex numbers, sparse decimal or complex
+                            matrices, polynomials, texts.
+                        </listitem>
+                        <listitem>
+                            Histogram binning:
+                            <itemizedlist>
+                                <listitem>
+                                    binsWidth and binsAlgo = ["sqrt" "sturges" "freediac"] input
+                                    arguments added.
+                                </listitem>
+                                <listitem>
+                                    histc() can now build categorial histograms: "discrete" option
+                                    added; binsValues input arguments added.
+                                </listitem>
+                                <listitem>
+                                    Marginal bins are now handled with binsEdges(1)=-%inf and
+                                    binsEdges($)=%inf, or with binsEdges(1)="" and binsEdges($)="~"
+                                </listitem>
+                            </itemizedlist>
+                        </listitem>
+                        <listitem>
+                            Histogram scaling:
+                            <itemizedlist>
+                                <listitem>
+                                    normalization option removed
+                                </listitem>
+                                <listitem>
+                                    "counts", "countsNorm", "density" and "densityNorm" options added.
+                                </listitem>
+                                <listitem>
+                                    "normWith:" option added, with flags among "leftout",
+                                    "rightout", "out", "inf", "nan", "zeros", "empty", "all"
+                                    possible values.
+                                </listitem>
+                                <listitem>
+                                    "counts" is now the default scaling mode, instead of
+                                    "densityNorm" in Scilab 5.5.0 and 5.5.1, and
+                                    "countsNorm" in Scilab 5.5.2. The backward compatibility to the
+                                    former "densityNorm" default Scilab 5.5 mode is ensured.
+                                </listitem>
+                            </itemizedlist>
+                        </listitem>
+                        <listitem>
+                            jokers and bins output arguments are added and inserted after the
+                            histogram heights. The backward compatibility to Scilab 5.5 is ensured
+                            for the ind result.
+                        </listitem>
+                        <listitem>Extensive unit tests added.</listitem>
+                        <listitem>Help page rewritten.</listitem>
+                    </itemizedlist>
                 </revdescription>
             </revision>
         </revhistory>
diff --git a/scilab/modules/statistics/help/en_US/histc.pdf b/scilab/modules/statistics/help/en_US/histc.pdf
new file mode 100644 (file)
index 0000000..12f08c7
Binary files /dev/null and b/scilab/modules/statistics/help/en_US/histc.pdf differ
diff --git a/scilab/modules/statistics/help/fr_FR/4_distribution_empirical_shape/histc.xml b/scilab/modules/statistics/help/fr_FR/4_distribution_empirical_shape/histc.xml
deleted file mode 100644 (file)
index 1b92318..0000000
+++ /dev/null
@@ -1,253 +0,0 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- * Copyright (C) 2018 - Samuel GOUGEON
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- --><!-- This document was created with Syntext Serna Free. -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-        xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
-        xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
-        xml:lang="fr" xml:id="histc">
-    <refnamediv>
-        <refname>histc</refname>
-        <refpurpose>calcule un histogramme</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>Syntaxe</title>
-        <synopsis>
-            h = histc(n, data)
-            h = histc(x, data)
-            h = histc(.., normalization)
-        </synopsis>
-    </refsynopsisdiv>
-    <refsection role="parameters">
-        <title>Paramètres</title>
-        <variablelist>
-            <varlistentry>
-                <term>n</term>
-                <listitem>
-                    <para>entier positif (nombre de classes)</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>x</term>
-                <listitem>
-                    <para>
-                        vecteur croissant définissant les classes (<literal>x</literal> doit avoir au moins 2 éléments)
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>data</term>
-                <listitem>
-                    <para>
-                        vecteur (données à analyser)
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>h</term>
-                <listitem>
-                    <para>
-                        <itemizedlist>
-                            <listitem>
-                                Si <varname>normalization</varname> est %T: densités de probabilité sur
-                                les intervalles définis par <varname>n</varname> or <varname>x</varname>,
-                                telles que l'aire de chaque intervalle est proportionnelle à sa population.
-                            </listitem>
-                            <listitem>
-                                Si <varname>normalization</varname> est %F: nombres d'éléments peuplant
-                                les intervalles.
-                            </listitem>
-                        </itemizedlist>
-                    </para>
-                </listitem>
-            </varlistentry>
-            <!--
-            <varlistentry>
-                <term>ind</term>
-                <listitem>
-                    <para>
-                        vecteur ou matrice de même taille que <varname>data</varname>,
-                        représentant l'appartenance respective de chaque élément de <varname>data</varname>
-                        aux classes définies par <varname>n</varname> ou <varname>x</varname>
-                    </para>
-                </listitem>
-            </varlistentry>
-           -->
-            <varlistentry>
-                <term>normalization</term>
-                <listitem>
-                    <para>
-                        booléen simple (%T par défaut), déterminant le type de résultat
-                        (voir <varname>h</varname>).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection role="description">
-        <title>Description</title>
-        <para>
-            Cette fonction calcule un histogramme du vecteur <literal>data</literal> d'après les classes
-            <literal>x</literal>. Quand le nombre de classes <literal>n</literal> est fourni
-            au lieu de <literal>x</literal>, les classes sont choisies également espacées et
-            <emphasis>x(1) = min(data) &lt; x(2) = x(1) + dx &lt; ... &lt; x(n+1) = max(data)</emphasis>
-            avec <emphasis>dx = (x(n+1)-x(1))/n</emphasis>.
-        </para>
-        <para>
-            Les classes sont définies par <literal>C1 = [x(1), x(2)]</literal> et
-            <literal>Ci = ( x(i), x(i+1)]</literal> pour i &gt;= 2.
-            Si l'on note <literal>Nmax</literal> le nombre total de <literal>data</literal> (Nmax = length(data))
-            et <literal>Ni</literal> le nombre d'éléments de <literal>data</literal> tombant dans
-            <literal>Ci</literal>, la valeur de l'histogramme pour <literal>x</literal> dans
-            <literal>Ci</literal> est égal à <emphasis>Ni/(Nmax (x(i+1)-x(i)))</emphasis> quand
-            <literal>"normalized"</literal> est séléctionné et sinon, simplement égal à <emphasis>Ni</emphasis>.
-            Quand la normalisation a lieu, l'histogramme vérifie:
-        </para>
-        <para>
-            <latex style="display"><![CDATA[ \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1 ]]></latex>
-        </para>
-        <para>
-            quand <emphasis>x(1)&lt;=min(data)</emphasis> et <emphasis>max(data) &lt;= x(n+1)</emphasis>
-        </para>
-    </refsection>
-    <refsection role="examples">
-        <title>Exemples</title>
-        <simplelist>
-            <member> Exemple #1: variations sur l'histogramme d'un échantillon gaussien N(0,1)
-                <programlisting role="example"><![CDATA[
-// L'échantillon aléatoire gaussien
-d = rand(1, 10000, 'normal');
-
-h = histc(20, d, normalization=%f);
-sum(h)   // = 10000
-// On utilise histplot pour avoir une représentation graphique
-clf(); histplot(20, d, normalization=%f);
-
-// Histogramme d'aire normalisée (densité de probabilité)
-h = histc(20, d);
-dx = (max(d)-min(d))/20;  sum(h)*dx   // = 1
-clf(); histplot(20, d);
-]]></programlisting>
-                <scilab:image>
-                    d = rand(1, 10000, 'normal');
-                    h = histc(20, d);
-                    clf(); histplot(20, d);
-                </scilab:image>
-            </member>
-            <member>
-                Exemple #2: histogramme d'un échantillon de loi binomiale B(6,0.5)
-                <programlisting role="example"><![CDATA[
-d = grand(1000,1,"bin", 6, 0.5);
-c = linspace(-0.5,6.5,8);
-clf()
-
-subplot(2,1,1)
-h = histc(c, d);
-histplot(c, d, style=2);
-xtitle("Histogramme d''aire normalisée")
-
-subplot(2,1,2)
-h = histc(c, d, normalization=%f);
-histplot(c, d, normalization=%f, style=5);
-xtitle("Histogramme brut")
-]]></programlisting>
-                <scilab:image localized="true">
-                    d = grand(1000,1,"bin", 6, 0.5);
-                    c = linspace(-0.5,6.5,8);
-                    clf()
-                    subplot(2,1,1)
-                    h = histc(c, d);
-                    histplot(c, d, style=2);
-                    xtitle("Histogramme d''aire normalisée")
-                    subplot(2,1,2)
-                    h = histc(c, d, normalization=%f)
-                    histplot(c, d, normalization=%f, style=5);
-                    xtitle("Histogramme brut")
-                </scilab:image>
-            </member>
-            <member>
-                Exemple #3 : histogramme d'un échantillon de loi exponentielle E(lambda)
-                <programlisting role="example"><![CDATA[
-lambda = 2;
-X = grand(100000,1,"exp", 1/lambda);
-Xmax = max(X);
-h = histc(40, X);
-
-clf()
-histplot(40, X, style=2);
-x = linspace(0, max(Xmax), 100)';
-plot2d(x, lambda*exp(-lambda*x), strf="000", style=5)
-legend(["Histogramme d''un échantillon de distribution exponentielle" "Fonction densité exacte"]);
-]]></programlisting>
-                <scilab:image localized="true">
-                    lambda = 2;
-                    X = grand(100000,1,"exp", 1/lambda);
-                    Xmax = max(X);
-                    h = histc(40, X);
-                    clf()
-                    histplot(40, X, style=2);
-                    x = linspace(0, max(Xmax), 100)';
-                    plot2d(x, lambda*exp(-lambda*x), strf="000", style=5)
-                    legend(["Histogramme d''un échantillon de distribution exponentielle" "Fonction densité exacte"]);
-                </scilab:image>
-            </member>
-            <member>
-                Exemple #4 : polygône des fréquences et histogramme d'un échantillon gaussien
-                <programlisting role="example"><![CDATA[
-n = 10;
-data = rand(1, 1000, "normal");
-h = histc(n, data);
-
-clf(); histplot(n, data, style=12, polygon=%t);
-legend(["Histogramme d''aire normalisée" "Polygone des fréquences"], "lower_caption");
-]]></programlisting>
-                <scilab:image localized="true">
-                    n = 10;
-                    data = rand(1, 1000, "normal");
-                    h = histc(n, data);
-                    clf(); histplot(n, data, style=12, polygon=%t);
-                    legend(["Histogramme d''aire normalisée" "Polygone des fréquences"], "lower_caption");
-                </scilab:image>
-            </member>
-        </simplelist>
-    </refsection>
-    <refsection role="see also">
-        <title>Voir aussi</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="histplot">histplot</link>
-            </member>
-            <member>
-                <link linkend="hist3d">hist3d</link>
-            </member>
-            <member>
-                <link linkend="plot2d">plot2d</link>
-            </member>
-            <member>
-                <link linkend="dsearch">dsearch</link>
-            </member>
-        </simplelist>
-    </refsection>
-    <refsection role="history">
-        <title>Historique</title>
-        <revhistory>
-            <revision>
-                <revnumber>5.5.0</revnumber>
-                <revdescription>
-                    Introduction
-                </revdescription>
-            </revision>
-        </revhistory>
-    </refsection>
-</refentry>
diff --git a/scilab/modules/statistics/help/ja_JP/4_distribution_empirical_shape/histc.xml b/scilab/modules/statistics/help/ja_JP/4_distribution_empirical_shape/histc.xml
deleted file mode 100644 (file)
index 516b416..0000000
+++ /dev/null
@@ -1,259 +0,0 @@
-<?xml version='1.0' encoding='UTF-8'?>
-<!--
- * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
- * Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
- * Copyright (C) 2012 - 2016 - Scilab Enterprises
- * Copyright (C) 2018 - Samuel GOUGEON
- *
- * This file is hereby licensed under the terms of the GNU GPL v2.0,
- * pursuant to article 5.3.4 of the CeCILL v.2.1.
- * This file was originally licensed under the terms of the CeCILL v2.1,
- * and continues to be available under such terms.
- * For more information, see the COPYING file which you should have received
- * along with this program.
- *
- --><!-- This document was created with Syntext Serna Free. -->
-<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
-        xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML"
-        xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
-        xml:lang="ja" xml:id="histc">
-    <refnamediv>
-        <refname>histc</refname>
-        <refpurpose>ヒストグラムを計算</refpurpose>
-    </refnamediv>
-    <refsynopsisdiv>
-        <title>呼び出し手順</title>
-        <synopsis>
-            h = histc(n, data)
-            h = histc(x, data)
-            h = histc(.., normalization)
-        </synopsis>
-    </refsynopsisdiv>
-    <refsection role="parameters">
-        <title>引数</title>
-        <variablelist>
-            <varlistentry>
-                <term>n</term>
-                <listitem>
-                    <para>正の整数 (クラスの数)</para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>x</term>
-                <listitem>
-                    <para>
-                        クラスを定義する漸増ベクトル
-                        (<literal>x</literal>には最低2つの要素があります)
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>data</term>
-                <listitem>
-                    <para>
-                        ベクトル (解析対象のデータ)
-                    </para>
-                </listitem>
-            </varlistentry>
-            <varlistentry>
-                <term>h</term>
-                <listitem>
-                    <para>
-                      <itemizedlist>
-                        <listitem>
-                            <para>
-                            If <varname>normalization</varname> is %T: Probability densities on the
-                            bins defined by <varname>n</varname> or <varname>x</varname>, such that
-                            the bins areas are proportionnal to their populations.
-                            </para>
-                        </listitem>
-                        <listitem>
-                            <para>
-                            If <varname>normalization</varname> is %F: Numbers of elements in the bins.
-                            </para>
-                        </listitem>
-                      </itemizedlist>
-                    </para>
-                </listitem>
-            </varlistentry>
-            <!--
-            <varlistentry>
-                <term>ind</term>
-                <listitem>
-                    <para>
-                        <varname>data</varname>と同じ大きさのベクトルまたは行列で,
-                        データ<varname>data</varname>の各要素が
-                        <varname>n</varname>または<varname>x</varname>により定義された
-                        クラスに重複して属していることを示します
-                    </para>
-                </listitem>
-            </varlistentry>
-            -->
-            <varlistentry>
-                <term>normalization</term>
-                <listitem>
-                    <para>
-                      スカラー論理値 (デフォルト %T), setting the type of output
-                      (see <varname>h</varname>).
-                    </para>
-                </listitem>
-            </varlistentry>
-        </variablelist>
-    </refsection>
-    <refsection role="description">
-        <title>説明</title>
-        <para>
-            この関数は,クラス<literal>x</literal>により<literal>data</literal>ベクトルの
-            ヒストグラムを計算します.
-            <literal>x</literal>ではなくクラスの数 <literal>n</literal>が指定された場合,等間隔で
-            <emphasis>x(1) = min(data) &lt; x(2) = x(1) + dx &lt; ... &lt; x(n+1) = max(data)</emphasis>
-            (ただし, <emphasis>dx = (x(n+1)-x(1))/n</emphasis>)となるクラスが選択されます.
-        </para>
-        <para>
-            クラスは<literal>C1 = [x(1), x(2)]</literal> および <literal>Ci = ( x(i), x(i+1)]</literal>
-            (i &gt;= 2)で定義されます.
-            <literal>Nmax</literal>は<literal>data</literal>の総数 (Nmax = length(data)),
-            <literal>Ni</literal>は<literal>Ci</literal>に含まれる<literal>data</literal>要素の数,
-            <literal>Ci</literal>における<literal>x</literal>のヒストグラムの値は,
-            <literal>"normalized"</literal>が選択された場合は
-            <emphasis>Ni/(Nmax (x(i+1)-x(i)))</emphasis> となり,
-            そうでない場合は単に<emphasis>Ni</emphasis>となります.
-            正規化が行われた際,ヒストグラムは以下を確認します:
-        </para>
-        <para>
-            <latex style="display"><![CDATA[ \int_{x(1)}^{x(n+1)}h(x)\,\mathrm{d}x=1 ]]></latex>
-        </para>
-        <para>
-            <emphasis>x(1)&lt;=min(data)</emphasis> および <emphasis>max(data) &lt;= x(n+1)</emphasis>
-            の場合
-        </para>
-    </refsection>
-    <refsection role="examples">
-        <title>例</title>
-        <simplelist>
-            <member> 例 #1: ガウス乱数標本のヒストグラム周辺の変化
-                <programlisting role="example"><![CDATA[
-// ガウス乱数標本
-d = rand(1, 10000, 'normal');
-h = histc(20, d, normalization=%f);
-sum(h)   // = 10000
-// グラフィック表現を示すためにhistplotを使用
-clf(); histplot(20, d, normalization=%f);
-
-// Normalized histogram (probability density)
-h = histc(20, d);
-dx = (max(d)-min(d))/20;  sum(h)*dx   // = 1
-clf(); histplot(20, d);
-]]></programlisting>
-                <scilab:image>
-                    d = rand(1, 10000, 'normal');
-                    h = histc(20, d);
-                    clf(); histplot(20, d);
-                </scilab:image>
-            </member>
-            <member>
-                例 #2: 二項(B(6,0.5)) 乱数標本のヒストグラム
-                <programlisting role="example"><![CDATA[
-d = grand(1000,1,"bin", 6, 0.5);
-c = linspace(-0.5,6.5,8);
-clf()
-
-subplot(2,1,1)
-h = histc(c, d);
-histplot(c, d, style=2);
-xtitle(_("Normalized histogram"))
-
-subplot(2,1,2)
-h = histc(c, d, normalization=%f);
-histplot(c, d, normalization=%f, style=5);
-xtitle(_("Non normalized histogram"))
-]]></programlisting>
-                <scilab:image localized="true">
-                    d = grand(1000,1,"bin", 6, 0.5);
-                    c = linspace(-0.5,6.5,8);
-                    clf()
-                    subplot(2,1,1)
-                    h = histc(c, d);
-                    histplot(c, d, style=2);
-                    xtitle(_("Normalized histogram"))
-                    subplot(2,1,2)
-                    h = histc(c, d, normalization=%f);
-                    histplot(c, d, normalization=%f, style=5);
-                    xtitle(_("Non normalized histogram"))
-                </scilab:image>
-            </member>
-            <member>
-                例 #3: 指数乱数標本のヒストグラム
-                <programlisting role="example"><![CDATA[
-lambda = 2;
-X = grand(100000,1,"exp", 1/lambda);
-Xmax = max(X);
-h = histc(40, X);
-
-clf()
-histplot(40, X, style=2);
-x = linspace(0, max(Xmax), 100)';
-plot2d(x, lambda*exp(-lambda*x), strf="000", style=5)
-legend([_("exponential random sample histogram") _("exact density curve")]);
-]]></programlisting>
-                <scilab:image localized="true">
-                    lambda = 2;
-                    X = grand(100000,1,"exp", 1/lambda);
-                    Xmax = max(X);
-                    h = histc(40, X);
-                    clf()
-                    histplot(40, X, style=2);
-                    x = linspace(0, max(Xmax), 100)';
-                    plot2d(x, lambda*exp(-lambda*x), strf="000", style=5)
-                    legend([_("exponential random sample histogram") _("exact density curve")]);
-                </scilab:image>
-            </member>
-            <member>
-                例 #4: ガウス乱数標本の周波数ポリゴンチャートとヒストグラム
-                <programlisting role="example"><![CDATA[
-n = 10;
-data = rand(1, 1000, "normal");
-h = histc(n, data);
-
-clf(); histplot(n, data, style=12, polygon=%t);
-legend([_("normalized histogram") _("frequency polygon chart")], "lower_caption");
-]]></programlisting>
-                <scilab:image localized="true">
-                    n = 10;
-                    data = rand(1, 1000, "normal");
-                    h = histc(n, data);
-                    clf(); histplot(n, data, style=12, polygon=%t);
-                    legend([_("normalized histogram") _("frequency polygon chart")], "lower_caption");
-                </scilab:image>
-            </member>
-        </simplelist>
-    </refsection>
-    <refsection role="see also">
-        <title>参照</title>
-        <simplelist type="inline">
-            <member>
-                <link linkend="histplot">histplot</link>
-            </member>
-            <member>
-                <link linkend="hist3d">hist3d</link>
-            </member>
-            <member>
-                <link linkend="plot2d">plot2d</link>
-            </member>
-            <member>
-                <link linkend="dsearch">dsearch</link>
-            </member>
-        </simplelist>
-    </refsection>
-    <refsection role="history">
-        <title>履歴</title>
-        <revhistory>
-            <revision>
-                <revnumber>5.5.0</revnumber>
-                <revdescription>
-                    Introduction
-                </revdescription>
-            </revision>
-        </revhistory>
-    </refsection>
-</refentry>
index 8781a7c..5c8b758 100644 (file)
@@ -1,7 +1,5 @@
 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
-// Copyright (C) 2013 - A. Khorshidi
-// Copyright (C) 2012 - 2016 - Scilab Enterprises
-// Copyright (C) 2018 - Samuel GOUGEON
+// Copyright (C) 2017 - 2020 - Samuel GOUGEON
 //
 // This file is hereby licensed under the terms of the GNU GPL v2.0,
 // pursuant to article 5.3.4 of the CeCILL v.2.1.
 // For more information, see the COPYING file which you should have received
 // along with this program.
 
-function [cf, ind] = histc(n, data, normalization)
 
-    // Example:
-    //     n = 10;
-    //     data = rand(1, 1000, "normal");
-    //     [class_freq, ind] = histc(n, data)
+function [heights, jokers, binsOut, ind] = histc(data, bins, options)
+// Scilab 5.5:
+//  1) histc(bins, data, normalization)
+//  2) By défaut, histc() worked in "densityNorm,normWith:all" mode
+// Scilab 6.0:
+//  1) histc(data, bins, options)
+//  2) By default, histc() works in "counts" mode
 
-    rhs = argn(2);
+//    histc(data)
+//    histc(data, nbins)
+//    histc(data, binsWidth<0)
+//    histc(data, binsEdges)
+//    histc(data, binsValues [, "discrete"])
+//    histc(data, binsAlgo)
+//    histc(data, ..., options)
+//    histc(nbins, data)                        // deprecated
+//    histc(binsEdges, data)                    // deprecated
+//    histc(binsEdges, data, normalization=%t)  // deprecated
+//     heights                        = histc(data ..)
+//    [heights, jokers]               = histc(data ..)
+//    [heights, jokers, binsOut]      = histc(data ..)
+//    [heights, jokers, binsOut, ind] = histc(data ..)
+//
+//    Binning algorithm:
+//      "sqrt" | "sturges" | "freediac"
+//    Binning options:
+//      "discrete"  // , "smartbins"
+//    Scale options:
+//      "counts" (default) | "countsNorm" | "density" | "densityNorm"
+//    Normalization "normWith: " options:  Priorities: "all" > "out" > ..
+//     decimal, complex numbers: "leftout rightout out inf nan zeros all"
+//                     integers: "leftout rightout (out=) all"
+//                         Text: "empty out all"
+//                  polynomials: "(out=) all"
+//       vector or single string with space-separated flags (case-unsensitive)
+//
+//    Complex numbers are sorted by real parts, then by imaginary parts
+//    jokers =
+//      * integers: [leftout, rightout] (continuous) or [out] (discrete)
+//      * decimal or complex numbers, full or sparse:
+//            continuous: [leftout, rightout, zeros, nan, inf]
+//              discrete: [out, 0, zeros, nan, inf]
+//      * polynomials: [out, 0, 0, nan, inf]
+//      * texts: continuous: [leftout, rightout, ""]; discrete: [out, 0, ""]
+//
+
+    [lhs, rhs] = argn();
+    fname = "histc"
+    [heights, jokers, binsOut, ind] = ([],[],[],[])
+    [Nout, Nleftout, Nzeros, Nrightout, Ninf, Nnan] = (0,0,0,0,0,0)
 
-    if rhs < 2
-        error(msprintf(_("%s: Wrong number of input argument(s): At least %d expected.\n"), "histc", 2));
+    // PARSING INPUT ARGUMENTS
+    // =======================
+    if rhs<1 | rhs>3 then
+        msg = _("%s: Wrong number of input arguments: %d to %d expected.\n")
+        error(msprintf(msg, fname, 1, 3))
     end
+    // Old 5.5.x mode management
+    // -------------------------
+    mode55 = %f
+    // Check for Scilab 5.5 back-compatibility
+    if (isdef("data","l") & isdef("bins", "l") & type(bins)>0) & ..
+        size(data,"*")< size(bins,"*") & or(type(data)==[1 8]) & type(bins)~=10
+        msg = _("%s: data are now expected in argument #1 => arguments #1 and #2 switched\n")
+        warning(msprintf(msg, fname))
+        mode55 = %t
+        [data, bins] = (bins, data)
+        tmp = isdef("options","l") && type(options)==4
+        normarg = %f
+        norma = %f
+        if isdef("normalization","l")
+            normarg = %t
+            if type(normalization)==4 then
+                norma = normalization(1)
+            end
+        else
+            if rhs<3 then
+                norma = %t
+            else
+                if isdef("options","l") & type(options)==4
+                    normarg = %t
+                    norma = options(1)
+                end
+            end
+        end
+        if norma then
+            options = ["densityNorm" "normWith:all"]
+        else
+            options = "counts"
+        end
+        if normarg
+            msg = _("%s: ""normalization"" boolean argument #3 is obsolete. ""%s"" option used.\n")
+            warning(msprintf(msg, fname, options(1)))
+        end
+    end
+    // -----------------------
+    if ~isdef("data","l") | type(data)==0 then
+        msg = _("%s: Argument #%d: %s\n")
+        error(msprintf(msg, fname, 1, "data array missing"))
+    end
+    if ~isdef("bins","l") | type(bins)==0 then
+        bins = []
+    end
+    if ~isdef("options","l") then
+        options = "counts"
+    end
+    // Now, bins, data and options are defined. Let's check their types and sizes
 
-    if rhs == 3 & exists("normalization", "local") then
-        if type(normalization) ~= 4 | size(normalization, "*") ~= 1 then
-            error(msprintf(_("%s: Wrong type of input argument #%d: A single boolean expected.\n"), "histc", 3));
+    // CHECKING INPUT ARGUMENTS AND SETTING DEFAULTS
+    // =============================================
+    // Options
+    // -------
+    if options~=[]
+        if type(options)~=10 then
+            msg = _("%s: Argument #%d: Text expected.\n")
+            error(msprintf(msg, fname, 3))
         end
-    else
-        // By default, normalize the result
-        normalization = %t
+        options = tokens(strcat(convstr(options),","),",")
     end
+    discrete = grep(options, "discrete")~=[] | type(data)==2 // polynomials
 
-    if type(n) ~= 1 & type(n) ~= 8
-        error(msprintf(_("%s: Wrong type for input argument #%d: A real matrix expected.\n"),"histc",1));
+    // Data
+    // ----
+    if isempty(data) then
+        return
+    end
+    if ~or(type(data)==[1 2 5 8 10]) then
+        msg = _("%s: Data in argument #%d: Numbers or polynomials or texts expected.\n")
+        error(msprintf(msg, fname, 1))
     end
-    if type(n) == 8 then
-        n = iconvert(n, 0); // To pass to dsearch
+    data0 = data    // Saving
+    // If encoded integers (including u-int64): => decimal (for dsearch(), etc)
+    if type(data) == 8 then
+        data = double(data)
+    end
+    // If sparse numbers: we remove zeros
+    if type(data)==5
+        [IJ, data] = spget(data)
+    end
+    // If there are only %inf or %nan => return ==!!!!!!!!!!!!!!!!!!!!!!!!!!!
+    if ~discrete & or(type(data0)==[1 5]) then
+        L = data
+        tmp = isnan(data)
+        Nnan = sum(tmp)
+        L(tmp) = []
+        tmp = isinf(data)
+        Ninf = sum(tmp)
+        L(tmp) = []
+        if data==[]
+            msg = _("%s: data have only %inf or/and %nan values.\n")
+            warning(msprintf(msg, fname))
+            if type(data0)==1
+                Nzeros = sum(data==0)
+            else
+                Nzeros = size(data0,"*") - Nnan - Ninf
+            end
+            Nleftout = 0
+            Nrightout = 0
+            if length(bins)>1
+                b = bins(~isinf(bins))
+                if 0<min(b)
+                    Nleftout = Nzeros
+                end
+                if 0 > max(b)
+                    Nrightout = Nzeros
+                end
+            end
+            jokers = [Ninf Nnan Nzeros Nleftout Nrightout]
+            return
+        end
     end
+    // Polynomials: setting Nan and Ninf
+    if type(data)==2
+        L = data
+        tmp = isnan(L)
+        Nnan = sum(tmp)
+        L(tmp) = []     // to ensure excluding any intersection
+        tmp = isinf(L)
+        Ninf = sum(tmp)
+    end
+
+    // Bins
+    // ----
+    // Setting a default binning mode
+    if bins==[] then
+        // histc(data): Default bins:
+        //  * strings: discrete, from unique()
+        //  * polynomials: discrete, from defBins set hereabove
+        //  * encoded integers: "sqrt". if strange() < "sqrt" => binsWidth = 1
+        //  * decimal, complex: binMethod option or default "sqrt"
+        if type(data)==10       // texts
+            discrete = %t
+            bins = unique(data)(:)'
+            bins = bins(:)'
+
+        elseif type(data)==2    // Polynomials
+            L = data
+            tmp = isnan(L)
+            L(tmp) = []
+            bins = []
+            while L~=[]
+                bins = [bins L(1)]
+                L(L==L(1)) = []
+            end
+            clear L
 
-    if type(data) ~= 1 & type(data) ~= 8
-        error(msprintf(_("%s: Wrong type for input argument #%d: A real matrix expected.\n"),"histc",2))
+        else    // decimals, complexes, encoded integers
+            if ~discrete
+                bins = "sqrt"
+            else
+                bins = unique(data)(:).'
+            end
+        end
     end
-    if type(data) == 8 then
-        data = iconvert(data, 0); // To pass to dsearch
+    //
+    if ~discrete
+        if type(bins)==8 | (type(bins)==1 & ~isreal(bins))
+            bins = real(double(bins))
+        end
+        if size(bins,"*")==1 & type(bins)==10 then
+            // binsAlgo
+            // --------
+            if ~or(convstr(bins)==["sqrt" "sturges" "freediac"])
+                msg = _("%s: Argument #%d: wrong value for binning algo")
+                error(msprintf(msg, fname, 2))
+            end
+            // We set the number of bins. Their edges are set later.
+            Nvalid = size(data,"*") - Nnan - Ninf
+            select bins
+            case "sturges"
+                bins = ceil(1 + log2(Nvalid))
+            case "freediac"
+                tmp = real(data)
+                binWidth = 2*iqr(tmp)* Nvalid^(-1/3)
+                if binWidth~=0
+                    bins = round((max(tmp) - min(tmp)) / binWidth)
+                else
+                    bins = 2
+                end
+            else  // "sqrt"
+                bins = max(1, round(sqrt(Nvalid)))
+            end
+        end
+
+        if length(bins)==1 & type(bins)==1  then
+            // The number of bins or their width is provided
+            if type(data)==10   // texts
+                msg = _("%s: Argument #2: Please provide bins edges or values or leave choosing default bins.\n")
+                error(msprintf(msg, fname))
+            end
+            // Case polynomials: not possible here <= discrete previously set to %t
+            // Cases: Encoded integers, decimal or complex numbers
+            if bins>=0 & (bins~=floor(bins) | bins==0) | isnan(bins) | bins==%inf
+                msg = _("%s: Argument #%d: non-zero decimal integer expected.\n")
+                error(msprintf(msg, fname, 2))
+            elseif bins==-%inf
+                msg = _("%s: Argument #%d: decimal number > -Inf expected.\n")
+                error(msprintf(msg, fname, 2))
+            end
+
+            // If data are complex-encoded, they will be sorted by increasing
+            //  real parts, then by increasing imaginary parts.
+            b = data(~isnan(data) & ~isinf(data))
+            b = real(b)
+            mind = min(b)
+            maxd = max(b)
+            if type(data0)==1
+                if bins > 0
+                    // Required number of bins
+                    if (mind == maxd) then
+                        mind = mind*(1 - 0.5/bins);
+                        maxd = maxd*(1 + 0.5/bins);
+                    end
+                    bins = linspace(mind, maxd, bins+1);          // Bins edges
+                else
+                    // Required bins width
+                    if (mind == maxd) then
+                        bins = mind + [1 -1]*bins/2
+                    else
+                        // Edges set à 0.0, width = |bins|, from mind- to maxd+
+                        tmp = -bins
+                        bins = (floor(mind/tmp):ceil(maxd/tmp))*tmp
+                    end
+                end
+            else
+                // Encoded integers
+                if bins > 0
+                    // Required number of bins
+                    tmp = maxd - mind + 1
+                    if tmp <= bins & tmp <= 2^16  // integer-centered bins of width==1
+                        bins = (mind:(maxd+1)) - 0.5              // Bins edges
+                    else
+                        ds = (maxd - mind)/bins/2
+                        bins = linspace(mind-ds, maxd+ds, bins+1) // Bins edges
+                    end
+                else
+                    // Required bins width
+                    tmp = max(round(-bins),1) // Bins edges @ -0.5 modulo |int(bins)|
+                    bins = (floor(mind/tmp):ceil(maxd/tmp))*tmp - 0.5 // Bins edges
+                end
+            end
+
+        else
+            // Bins edges are provided: we check that edges are sorted
+            // Texts
+            // -----
+            if type(data0)==10
+                if type(bins)~=10
+                    msg = _("%s: Arguments #%d and #%d: Same types expected.\n")
+                    error(msprintf(msg, fname, 1, 2))
+                end
+                if ~and(bins==unique(bins))
+                    msg = _("%s: Argument #%d: Elements must be sorted in increasing order.\n")
+                    error(msprintf(msg, fname, 1))
+                end
+
+            // Numbers
+            // -------
+            else
+                if ~or(type(bins)==[1 8])
+                    msg = _("%s: Arguments #%d and #%d: Same types expected.\n")
+                    error(msprintf(msg, fname, 1, 2))
+                end
+                bins = bins(~isnan(bins))
+                if min(diff(bins)) <= 0 then
+                    msg = _("%s: Argument #%d: Elements must be in increasing order.\n")
+                    error(msprintf(msg, fname, 1))
+                end
+                // We manage -%inf open left bin
+                if bins(1)==-%inf
+                    tmp = min(data(~isinf(data)))
+                    if bins(2)<=tmp
+                        bins(1) = []
+                    else
+                        bins(1) = tmp
+                    end
+                end
+                // We manage %inf open right bin
+                if bins($)==%inf
+                    tmp = max(data(~isinf(data)))
+                    if bins($-1)>=tmp
+                        bins($) = []
+                    else
+                        bins($) = tmp
+                    end
+                end
+            end
+        end
+         // if ~discrete
+
+    else    // if discrete
+        if type(data0)==10
+            if type(bins)~=10
+                msg = _("%s: Arguments #%d and #%d: Same types expected.\n")
+                error(msprintf(msg, fname, 1, 2))
+            end
+            [bins, dataOrder] = unique(bins)
+
+        elseif or(type(data)==[1 8])
+            if ~or(type(bins)==[1 8])
+                msg = _("%s: Arguments #%d and #%d: Same types expected.\n")
+                error(msprintf(msg, fname, 1, 2))
+            end
+            bins = real(double(bins))
+            bins(isnan(bins)) = []
+            [bins, dataOrder] = unique(bins)
+        end
+    end
+    binsOut = bins
+
+    // PROCESSING
+    // ==========
+    // jokers =
+    //  * integers: [leftout, rightout] (continuous) or [out] (discrete)
+    //  * decimal or complex numbers, full or sparse:
+    //       continuous: [inf, nan, zeros, leftout, rightout]
+    //         discrete: [inf, nan, zeros, out]
+    //  * polynomials: [inf, nan, out]
+    //  * texts: continuous: [empty, leftout, rightout]; discrete: [empty, out]
+    if type(data0)~=2 then
+        hmode = "c"            // continuous
+        if discrete then
+            hmode = "d"        // discrete
+        end
+        if or(type(data0)==[1 5])
+            if type(data0)==1
+                tmp = data0
+            else
+                tmp = data     // sparse
+            end
+            tmp1 = isinf(real(tmp))
+            tmp2 = isinf(imag(tmp))
+            tmp3 = isnan(tmp) | (tmp1 & tmp2)
+            if ~discrete & ~isreal(tmp,0)
+                data(tmp1 | tmp2) = %inf
+                data(tmp3) = %nan
+            end
+            clear tmp tmp1 tmp2 tmp3
+            data = real(data)
+        end
+        [ind, heights] = dsearch(data, bins, hmode)
+                                     // ind: bin's number of each data component
+
+        if discrete
+            // We restore the original order of binsValues:
+            [tmp, k]  = gsort(dataOrder, "g","i")
+            [tmp, k2] = gsort(k,"g","i")
+            bins = bins(k)
+            binsOut = bins
+            heights = heights(k)
+            tmp2 = ind~=0
+            ind(tmp2) = k2(ind(tmp2))
+        end
+
+    else // Polynomials
+        // Counts (and location)
+         ind = zeros(data)
+         heights = []
+         for i = 1:size(bins,"*")
+             tmp = data==bins(i)
+             heights(1,i) = sum(tmp)
+             ind(tmp) = i
+         end
+         tmp = Ninf - sum(heights(isinf(bins)))     // inf out of the selection
+         Nout = size(data,"*") - sum(heights) - Nnan - tmp// excludes all nan and inf not in the selection
+         jokers = [Nout, 0, 0, Nnan, Ninf]
     end
 
-    if length(n) == 1 then  // The number of classes is provided
-        if n < 1
-            error(msprintf(_("%s: Wrong value for input argument #%d: Must be in the interval %s.\n"),"histc",1,"[1, oo)"));
-        elseif n ~= floor(n)
-            error(msprintf(_("%s: Wrong type for input argument #%d: Integer expected.\n"),"histc",1))
+    // POST-PROCESSING
+    // ===============
+    // Counting jokers
+    // ---------------
+    if or(type(data0)==[1 5])        // Real and complex numbers, sparse or not
+        inf = isinf(data)
+        Ninf = sum(inf)
+        Nnan = sum(isnan(data))
+        if type(data0)==1
+            Nzeros = sum(data==0)
+        else
+            Nzeros = size(data0,"*") - nnz(data0)
         end
-        mind = min(data);
-        maxd = max(data);
-        if (mind == maxd) then
-            mind = mind - floor(n/2);
-            maxd = maxd + ceil(n/2);
+        if ~discrete                 // Sparses: 0 is not taken into account
+            Nleftout  = sum(data(~inf) < bins(1))
+            Nrightout = sum(data(~inf) > bins($))
+            jokers = [Nleftout Nrightout Nzeros Nnan Ninf]
+        else
+            Nout = size(data0,"*") - sum(heights) - Nnan - Ninf
+            binsinf = isinf(bins)
+            if or(binsinf)
+                Nout = Nout + sum(heights(binsinf))
+            end
+            if type(data0)==5
+                Nout = Nout - Nzeros
+            end
+            jokers = [Nout 0 Nzeros Nnan Ninf]
         end
-        cb = linspace(mind, maxd, n+1); // Class boundary
-    else // The classes are provided
-        cb = matrix(n, 1, -1);   // Force row form
-        if min(diff(cb)) <= 0 then
-            error(msprintf(_("%s: Wrong values for input argument #%d: Elements must be in increasing order.\n"),"histc",1))
+
+    elseif type(data0)==8            // Encoded integers
+        if ~discrete
+            Nleftout  = sum(data < bins(1))
+            Nrightout = sum(data > bins($))
+            jokers = [Nleftout Nrightout]
+            Nout = Nleftout + Nrightout
+        else
+            Nout = size(data,"*") - sum(heights)
+            jokers = Nout
+        end
+
+    elseif type(data0)==10           // Texts
+        Nempty = sum(data0=="")
+        Nout = size(data0,"*") - sum(heights)
+        if ~discrete
+            tmp = gsort(data,"g","i")
+            Nleftout = sum(find(strcmp(tmp,bins(1))<0)($)) - Nempty
+            tmp = sum(find(strcmp(tmp,bins($))>0)(1))
+            if ~tmp
+                Nrightout = 0
+            else
+                Nrightout = size(data,"*") - tmp + 1
+            end
+            clear tmp
+            jokers = [Nleftout, Nrightout, Nempty]
+        else
+            if ~or(bins=="")
+                Nout = Nout - Nempty
+            end
+            jokers = [Nout, 0, Nempty]
         end
+
+    // Polynomials: jokers already set when setting bins
     end
 
-    [ind, cf, info] = dsearch(data, cb); // cf: class frequency, ind: class number of each count
+    // Tuning the histogram scale
+    // --------------------------
+    histmode = "counts"
+    if discrete then
+        tmp = grep(options, ["counts" "countsnorm"])
+    else
+        tmp = grep(options, ["counts" "countsnorm" "density" "densitynorm"])
+    end
+    if tmp~=[] then
+        histmode = options(tmp($))
+    end
+    // jokers =
+    //  * integers: [leftout, rightout] (continuous) or [out] (discrete)
+    //  * decimal or complex numbers, full or sparse:
+    //       continuous: [leftout, rightout, zeros, nan, inf]
+    //         discrete: [out, 0, zeros, nan, inf]
+    //  * polynomials: [out, 0, 0, nan, inf].
+    //  * texts: continuous: [leftout, rightout, empty]; discrete: [out, empty]
+
+    // Number of components to take into account:
+    // Parsing the option "normWith:
+    //  Continuous: " leftout rightout inf nan zeros"
+    //    Discrete: " out inf nan zeros"
+    if grep(histmode, "norm") then
+        N = sum(heights)
+        tmp = grep(options, "normwith")
+        normMode = options(tmp)
+        if normMode~=[]
+            gh = "/[\:|\s+]"    // grep() header
+            if ~discrete
+                if or(type(data0)==[1 2 5])
+                    if grep(normMode, gh+["inf" "all"]+"/", "r")~=[]
+                        N = N + Ninf
+                    end
+                    if grep(normMode, gh+["nan" "all"]+"/", "r")~=[]
+                        N = N + Nnan
+                    end
+                    if type(data0)==5 & ..
+                       grep(normMode,gh+["zeros" "all"]+"/", "r")~=[]
+                        N = N + Nzeros
+                    end
+                end
+                if grep(normMode, gh+["leftout" "out" "all"]+"/", "r")~=[]
+                    N = N + Nleftout
+                end
+                if grep(normMode, gh+["rightout" "out" "all"]+"/", "r")~=[]
+                    N = N + Nrightout
+                end
+                if type(data0)==10 & grep(normMode, gh+["empty" "all"]+"/", "r")~=[]
+                    N = N + Nempty
+                end
+            // Normalized discrete mode:
+            else
+                if grep(normMode, gh+"all/", "r")
+                    N = size(data0,"*")
+                else
+                    if grep(normMode, gh+"out/", "r")
+                        N = N + Nout
+                    end
+                    if or(type(data0)==[1 2 5])
+                        if grep(normMode, gh+"nan/", "r")
+                            N = N + Nnan
+                        end
+                        if grep(normMode, gh+"inf/", "r")
+                            N = N + Ninf
+                            // Inf already in bins must not be counted twice:
+                            binsinf = isinf(bins)
+                            if or(binsinf)
+                                N = N - sum(heights(binsinf))
+                            end
+                        end
+                        if type(data0)==5 & and(bins~=0) & ..
+                           grep(normMode, gh+"zeros/", "r")~=[]
+                            N = N + Nzeros
+                        end
+                    end
+                    if type(data0)==10 & ~or(bins=="") & ..
+                        grep(normMode, gh+"empty/", "r")~=[]
+                        N = N + Nempty
+                    end
+                end
+            end
+        //else    // all (but zeros for sparses)
+        //    N = size(data,"*")
+        end
+        heights = heights / N
+        jokers = jokers / N
+    end
+    if grep(histmode, "density") then
+        heights = heights ./ (bins(2:$) - bins(1:($-1)))
+    end
+
+    // Formatting outputs for sparse input data
+    // ----------------------------------------
+    if type(data0)==5 then
+        ind = sparse(IJ, ind, size(data0))
+    end
 
-    // Normalization
-    nd = size(data, "*"); // Number of data values
-    if normalization
-        cw = cb(2:$)-cb(1:$-1); // Bins widths
-        cf = cf./(nd*cw)        // ==> Normalized density == Density probability function
+    // Shifting argouts in Scilab 5.5 compatibility mode
+    // -------------------------------------------------
+    if mode55 then
+        jokers = ind
     end
 endfunction
diff --git a/scilab/modules/statistics/tests/nonreg_tests/bug_13490.tst b/scilab/modules/statistics/tests/nonreg_tests/bug_13490.tst
deleted file mode 100644 (file)
index 5446a29..0000000
+++ /dev/null
@@ -1,27 +0,0 @@
-// =============================================================================
-// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
-// Copyright (C) 2014 - Scilab Enterprises - Paul Bignier
-//
-//  This file is distributed under the same license as the Scilab package.
-// =============================================================================
-//
-// <-- CLI SHELL MODE -->
-// <-- NO CHECK REF -->
-//
-// <-- Non-regression test for bug 13490 -->
-//
-// <-- Bugzilla URL -->
-// http://bugzilla.scilab.org/13490
-//
-// <-- Short Description -->
-// histc now matches its help description (by default, normalizes the result),
-// normalization is now done properly (in total area).
-// =============================================================================
-
-myprob = [1 2 2 3 3 3];
-
-withNorm    = histc(3, myprob);
-withoutNorm = histc(3, myprob, normalization=%f);
-
-assert_checkalmostequal(withNorm, (1:3)/4);
-assert_checkequal(withoutNorm, 1:3);
diff --git a/scilab/modules/statistics/tests/nonreg_tests/bug_6306.dia.ref b/scilab/modules/statistics/tests/nonreg_tests/bug_6306.dia.ref
deleted file mode 100644 (file)
index 06d1f52..0000000
+++ /dev/null
@@ -1,53 +0,0 @@
-// =============================================================================
-// Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
-// Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
-//
-//  This file is distributed under the same license as the Scilab package.
-// =============================================================================
-//
-// <-- TEST WITH GRAPHIC -->
-//
-// <-- Non-regression test for bug 6306 -->
-//
-// <-- Bugzilla URL -->
-// http://bugzilla.scilab.org/show_bug.cgi?id=6306
-//
-// <-- Short Description -->
-// It was not possible to retrieve the data computed by histplot.
-// Also, new function histc to compute histogram data instead of plotting it.
-d = rand(1, 10000, "normal");
-[cfC, indC] = histc(20, d);
-[cfP, indP] = histplot(20, d);
-assert_checkequal(indC, indP);
-assert_checkalmostequal(cfC, cfP);
-[cfC, indC] = histc(20, d, normalization=%f);
-[cfP, indP] = histplot(20, d, normalization=%f);
-assert_checkequal(indC, indP);
-assert_checkalmostequal(cfC, cfP);
-[cfC, indC] = histc([-1 0 1], d);
-[cfP, indP] = histplot([-1 0 1], d);
-assert_checkequal(indC, indP);
-assert_checkalmostequal(cfC, cfP);
-[cfC, indC] = histc([-1 0 1], d, normalization=%f);
-[cfP, indP] = histplot([-1 0 1], d, normalization=%f);
-assert_checkequal(indC, indP);
-assert_checkalmostequal(cfC, cfP);
-grand("setsd", 0);
-lambda = 2;
-D = grand(100000, 1, "exp", 1/lambda);
-[cfC, indC] = histc(40, D);
-[cfP, indP] = histplot(40, D);
-assert_checkequal(indC, indP);
-assert_checkalmostequal(cfC, cfP);
-[cfC, indC] = histc(40, D, normalization=%f);
-[cfP, indP] = histplot(40, D, normalization=%f);
-assert_checkequal(indC, indP);
-assert_checkalmostequal(cfC, cfP);
-[cfC, indC] = histc([0 7], D);
-[cfP, indP] = histplot([0 7], D);
-assert_checkequal(indC, indP);
-assert_checkalmostequal(cfC, cfP);
-[cfC, indC] = histc([0 7], D, normalization=%f);
-[cfP, indP] = histplot([0 7], D, normalization=%f);
-assert_checkequal(indC, indP);
-assert_checkalmostequal(cfC, cfP);
index d50eae4..8356b52 100644 (file)
@@ -6,6 +6,7 @@
 // =============================================================================
 //
 // <-- TEST WITH GRAPHIC -->
+// <-- NO CHECK REF -->
 //
 // <-- Non-regression test for bug 6306 -->
 //
 // Also, new function histc to compute histogram data instead of plotting it.
 
 d = rand(1, 10000, "normal");
-[cfC, indC] = histc(20, d);
+normHist = "densityNorm,normWith:all";
+[cfC, tmp, tmp, indC] = histc(d, 20, normHist);
 [cfP, indP] = histplot(20, d);
 
 assert_checkequal(indC, indP);
 assert_checkalmostequal(cfC, cfP);
 
-[cfC, indC] = histc(20, d, normalization=%f);
+[cfC, tmp, tmp, indC] = histc(d, 20);
 [cfP, indP] = histplot(20, d, normalization=%f);
 
 assert_checkequal(indC, indP);
 assert_checkalmostequal(cfC, cfP);
 
-[cfC, indC] = histc([-1 0 1], d);
+[cfC, tmp, tmp, indC] = histc(d,[-1 0 1], normHist);
 [cfP, indP] = histplot([-1 0 1], d);
 
 assert_checkequal(indC, indP);
 assert_checkalmostequal(cfC, cfP);
 
-[cfC, indC] = histc([-1 0 1], d, normalization=%f);
+[cfC, tmp, tmp, indC] = histc(d, [-1 0 1]);
 [cfP, indP] = histplot([-1 0 1], d, normalization=%f);
 
 assert_checkequal(indC, indP);
@@ -46,13 +48,13 @@ assert_checkalmostequal(cfC, cfP);
 grand("setsd", 0);
 lambda = 2;
 D = grand(100000, 1, "exp", 1/lambda);
-[cfC, indC] = histc(40, D);
+[cfC, tmp, tmp, indC] = histc(D, 40, normHist);
 [cfP, indP] = histplot(40, D);
 
 assert_checkequal(indC, indP);
 assert_checkalmostequal(cfC, cfP);
 
-[cfC, indC] = histc(40, D, normalization=%f);
+[cfC, tmp, tmp, indC] = histc(D, 40);
 [cfP, indP] = histplot(40, D, normalization=%f);
 
 assert_checkequal(indC, indP);
@@ -64,7 +66,7 @@ assert_checkalmostequal(cfC, cfP);
 assert_checkequal(indC, indP);
 assert_checkalmostequal(cfC, cfP);
 
-[cfC, indC] = histc([0 7], D, normalization=%f);
+[cfC, tmp, tmp, indC] = histc(D, [0 7]);
 [cfP, indP] = histplot([0 7], D, normalization=%f);
 
 assert_checkequal(indC, indP);
index 2509d01..1880096 100644 (file)
-// =============================================================================
+// ========================================================================
 // Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 // Copyright (C) 2013 - Scilab Enterprises - Paul Bignier
+// Copyright (C) 2017 - Samuel GOUGEON
 //
 //  This file is distributed under the same license as the Scilab package.
-// =============================================================================
+// ========================================================================
 //
 //<-- CLI SHELL MODE -->
 //<-- NO CHECK REF -->
+//
+// ==========================
+// CHECKING FORMAT OF RESULTS
+// ==========================
+[h,j,b,i] = histc([]);
+assert_checkequal(list(h,j,b,i), list([],[],[],[]));
+d = rand(2,9);
+[h,j,b,i] = histc(d, 6);
+assert_checkequal(size(h),[1,6]);
+assert_checkequal(size(j),[1,5]);
+assert_checkequal(size(b),[1,7]);
+assert_checkequal(size(i),[2,9]);
+[h,j,b,i] = histc(d, [-%inf 0.3 0.5 0.6 %inf]);
+assert_checkequal(size(h),[1,4]);
+assert_checkequal(size(b),[1,5]);
+d = grand(2,9,"uin",0,9);
+[h,j,b,i] = histc(d, [1 3 5], "discrete");
+assert_checkequal(size(h),[1,3]);
+assert_checkequal(size(j),[1,5]);
+assert_checkequal(size(b),[1,3]);
+assert_checkequal(size(i),[2,9]);
+c = d + %i*d;
+[h,j,b,i] = histc(c, 4);
+assert_checkequal(size(h),[1,4]);
+assert_checkequal(size(j),[1,5]);
+assert_checkequal(size(b),[1,5]);
+assert_checkequal(size(i),[2,9]);
+d = int8(d);
+[h,j,b,i] = histc(d, 6);
+assert_checkequal(size(h),[1,6]);
+assert_checkequal(size(j),[1,2]);
+assert_checkequal(size(b),[1,7]);
+assert_checkequal(size(i),[2,9]);
+[h,j,b,i] = histc(d, [0 3 5 8], "discrete");
+assert_checkequal(size(h),[1,4]);
+assert_checkequal(size(j),[1,1]);
+assert_checkequal(size(b),[1,4]);
+assert_checkequal(size(i),[2,9]);
+d = sparse(double(d));
+[h,j,b,i] = histc(d, 6);
+assert_checkequal(size(h),[1,6]);
+assert_checkequal(size(j),[1,5]);
+assert_checkequal(size(b),[1,7]);
+assert_checkequal(size(i),[2,9]);
+[h,j,b,i] = histc(d, [1 3 5], "discrete");
+assert_checkequal(size(h),[1,3]);
+assert_checkequal(size(j),[1,5]);
+assert_checkequal(size(b),[1,3]);
+assert_checkequal(size(i),[2,9]);
+d = d + %i*d;
+[h,j,b,i] = histc(d, 4);
+assert_checkequal(size(h),[1,4]);
+assert_checkequal(size(j),[1,5]);
+assert_checkequal(size(b),[1,5]);
+assert_checkequal(size(i),[2,9]);
+// Texts
+t = matrix(asciimat(grand(20,1,"uin",ascii("a"), ascii("z"))), 2, 10);
+[h,j,b,i] = histc(t, ["e" "i" "o" "u"]);
+assert_checkequal(size(h),[1,3]);
+assert_checkequal(size(j),[1,3]);
+assert_checkequal(size(b),[1,4]);
+assert_checkequal(size(i),[2,10]);
+[h,j,b,i] = histc(t, ["e" "i" "o" "u"], "discrete");
+assert_checkequal(size(h),[1,4]);
+assert_checkequal(size(j),[1,3]);
+assert_checkequal(size(b),[1,4]);
+assert_checkequal(size(i),[2,10]);
+// Polynomials
+z = %z;
+p = [-z z z z z 2*z 2*z 2*z z^2 z^2];
+[h,j,b,i] = histc(p);
+assert_checkequal(size(h),[1,4]);
+assert_checkequal(size(j),[1,5]);
+assert_checkequal(size(b),[1,4]);
+assert_checkequal(size(i),[1,10]);
+p = [z+%inf -z z z z z 2*z 2*z 2*z z^2 z^2];
+[h,j,b,i] = histc(p);
+assert_checkequal(size(h),[1,5]);
+assert_checkequal(size(j),[1,5]);
+assert_checkequal(size(b),[1,5]);
+
+// =====================================================
+// CHECKING RESULTS WITH DECIMAL REAL OR COMPLEX NUMBERS
+// =====================================================
+assert_checkequal(histc(37), 1);
+d = [1 1 1 2 2 3 4 4 5 5 5 6 6 7 8 8 9 9 9];
+N = size(d,"*");
+// Default binning
+[h,j,b,i] = histc(d);
+href = [6 5 3 5];
+assert_checkequal(h, href);
+assert_checkequal(b, 1:2:9);
+assert_checkequal(i, [1 1 1 1 1 1 2 2 2 2 2 3 3 3 4 4 4 4 4]);
+assert_checkequal(histc(d,,"countsNorm"), href/N);
+assert_checkequal(histc(d,,"density"), href/2);
+assert_checkequal(histc(d,,"densityNorm"), href/2/N);
+// Fixed number of bins
+[h,j,b,i] = histc(d,3);
+href = [6 7 6];
+assert_checkequal(h, href);
+assert_checkequal(b, [3 11 19 27]/3);
+assert_checkequal(i, [1 1 1 1 1 1 2 2 2 2 2 2 2 3 3 3 3 3 3]);
+assert_checkequal(histc(d, 3,"countsNorm"), href/N);
+assert_checkalmostequal(histc(d, 3,"density"), href/(8/3));
+assert_checkalmostequal(histc(d, 3,"densityNorm"), href/(8/3)/N);
+// Fixed bins width
+[h,j,b,i] = histc(d,-2.5);
+href = [5 6 3 5];
+assert_checkequal(h, href);
+assert_checkequal(b, (0:4)*2.5);
+assert_checkequal(i, [1 1 1 1 1 2 2 2 2 2 2 3 3 3 4 4 4 4 4]);
+assert_checkequal(histc(d, -2.5, "countsNorm"), href/N);
+assert_checkalmostequal(histc(d, -2.5, "density"), href/2.5);
+// Automatic Sturges binning
+[h,j,b,i] = histc(d,"sturges");
+href = [5 1 5 2 1 5];
+assert_checkequal(h, href);
+assert_checkalmostequal(b, [3 7 11 15 19 23 27]/3);
+assert_checkequal(i, [1 1 1 1 1 2 3 3 3 3 3 4 4 5 6 6 6 6 6]);
+assert_checkequal(histc(d,"sturges","countsNorm"), href/N);
+assert_checkalmostequal(histc(d,"sturges","density"), href/(4/3));
+assert_checkalmostequal(histc(d,"sturges","densityNorm"), href/(4/3)/N);
+// Automatic Freedman-Diaconis binning
+[h,j,b,i] = histc(d, "freediac");
+href = [11 8];
+assert_checkequal(h, href);
+assert_checkalmostequal(b, [1 5 9]);
+assert_checkequal(i, [1 1 1 1 1 1 1 1 1 1 1 2 2 2 2 2 2 2 2]);
+assert_checkequal(histc(d, "freediac", "countsNorm"), href/N);
+assert_checkalmostequal(histc(d, "freediac", "density"), href/4);
+assert_checkalmostequal(histc(d, "freediac", "densityNorm"), href/4/N);
+// Explicit bins edges, without outsiders
+sb = [1 4 6 9];
+[h,j,b,i] = histc(d,sb);
+href = [8 5 6];
+assert_checkequal(h, href);
+assert_checkalmostequal(b, sb);
+assert_checkequal(i, [1 1 1 1 1 1 1 1 2 2 2 2 2 3 3 3 3 3 3]);
+assert_checkequal(histc(d, sb, "countsNorm"), href/N);
+assert_checkalmostequal(histc(d, sb, "density"), href./diff(sb));
+assert_checkalmostequal(histc(d, sb, "densityNorm"), href/N./diff(sb));
+// Explicit bins edges, with marginal bins
+sb = [-%inf 3 5 7 %inf];
+[h,j,b,i] = histc(d,sb);
+href = [6 5 3 5];
+assert_checkequal(h, href);
+assert_checkalmostequal(b, [1 3 5 7 9]);
+assert_checkequal(i, [1 1 1 1 1 1 2 2 2 2 2 3 3 3 4 4 4 4 4]);
+assert_checkequal(histc(d, sb, "countsNorm"), href/N);
+assert_checkalmostequal(histc(d, sb, "density"), href/2);
+assert_checkalmostequal(histc(d, sb, "densityNorm"), href/N/2);
+// Explicit bins edges, with useless/empty extra marginal bins
+sb = [-%inf 1 3 5 7 10 %inf];
+[h,j,b,i] = histc(d,sb);
+href = [6 5 3 5];
+assert_checkalmostequal(b, [1 3 5 7 10]);
+assert_checkequal(i, [1 1 1 1 1 1 2 2 2 2 2 3 3 3 4 4 4 4 4]);
+assert_checkequal(histc(d, sb, "countsNorm"), href/N);
+assert_checkalmostequal(histc(d, sb, "density"), href./[2 2 2 3]);
+assert_checkalmostequal(histc(d, sb, "densityNorm"), href/N./[2 2 2 3]);
+// Explicit bins edges, with outsiders
+// d = [1 1 1 2 2 3 4 4 5 5 5 6 6 7 8 8 9 9 9];
+sb = [2 5.5 7];
+[h,j,b,i] = histc(d,sb);
+href = [8 3];
+jref = [3 5 0 0 0];
+assert_checkequal(h, href);
+assert_checkequal(j, jref);
+assert_checkalmostequal(b, sb);
+assert_checkequal(i, [0 0 0 1 1 1 1 1 1 1 1 2 2 2 0 0 0 0 0]);
+[h, j] = histc(d, sb, "countsNorm");
+assert_checkequal(h, href/11);
+assert_checkequal(j, jref/11);
+[h, j] = histc(d, sb, "countsNorm,normWith: leftout");
+assert_checkequal(h, href/14);
+assert_checkequal(j, jref/14);
+[h, j] = histc(d, sb, "countsNorm,normWith: rightout");
+assert_checkequal(h, href/16);
+assert_checkequal(j, jref/16);
+[h, j] = histc(d, sb, "countsNorm,normWith: out");
+assert_checkequal(h, href/19);
+assert_checkequal(j, jref/19);
+[h, j] = histc(d, sb, "countsNorm,normWith: all");
+assert_checkequal(h, href/19);
+assert_checkequal(j, jref/19);
+[h, j] = histc(d, sb, "density");
+assert_checkalmostequal(h, href./diff(sb));
+assert_checkalmostequal(j, jref);
+[h, j] = histc(d, sb, "densityNorm");
+assert_checkalmostequal(h, href./diff(sb)/11);
+assert_checkalmostequal(j, jref/11);
+[h, j] = histc(d, sb, "densityNorm,normWith: leftout");
+assert_checkalmostequal(h, href./diff(sb)/14);
+assert_checkalmostequal(j, jref/14);
+[h, j] = histc(d, sb, "densityNorm,normWith: rightout");
+assert_checkalmostequal(h, href./diff(sb)/16);
+assert_checkalmostequal(j, jref/16);
+[h, j] = histc(d, sb, "densityNorm,normWith: all");
+assert_checkalmostequal(h, href./diff(sb)/19);
+assert_checkalmostequal(j, jref/19);
+
+// With Nan and Inf
+// ----------------
+// continuous: [leftout, rightout, zeros, nan, inf]
+//d = [1 1 1 2 2 3 4 4 5 5 5 6 6 7 8 8 9 9 9];
+d = [%nan %inf d %nan %nan -%inf];
+N = size(d,"*");
+sb = [2 4.5 7];
+[h,j,b,i] = histc(d, sb);
+href = [5 6];
+jref = [3 5 0 3 2];
+assert_checkequal(h, href);
+assert_checkequal(j, jref);
+assert_checkequal(i, [0 0 0 0 0 1 1 1 1 1 2 2 2 2 2 2 0 0 0 0 0 0 0 0]);
+[h, j] = histc(d, sb,"countsNorm");
+assert_checkequal(h, href/11);
+assert_checkequal(j, jref/11);
+[h, j] = histc(d, sb,"countsNorm,normWith: nan");
+assert_checkequal(h, href/14);
+assert_checkequal(j, jref/14);
+[h, j] = histc(d, sb,"countsNorm,normWith: inf");
+assert_checkequal(h, href/13);
+assert_checkequal(j, jref/13);
+[h, j] = histc(d, sb,"countsNorm,normWith: inf nan");
+assert_checkequal(h, href/16);
+assert_checkequal(j, jref/16);
+[h, j] = histc(d, sb,"countsNorm,normWith: leftout nan");
+assert_checkequal(h, href/17);
+assert_checkequal(j, jref/17);
+[h, j] = histc(d, sb,"countsNorm,normWith: rightout inf");
+assert_checkequal(h, href/18);
+assert_checkequal(j, jref/18);
+[h, j] = histc(d, sb,"countsNorm,normWith: out inf");
+assert_checkequal(h, href/21);
+assert_checkequal(j, jref/21);
+[h, j] = histc(d, sb,"countsNorm,normWith: all");
+assert_checkequal(h, href/24);
+assert_checkequal(j, jref/24);
+
+[h, j] = histc(d, sb,"densityNorm");
+assert_checkequal(h, href/11/2.5);
+assert_checkequal(j, jref/11);
+[h, j] = histc(d, sb,"densityNorm,normWith: nan");
+assert_checkequal(h, href/14/2.5);
+assert_checkequal(j, jref/14);
+[h, j] = histc(d, sb,"densityNorm,normWith: inf");
+assert_checkequal(h, href/13/2.5);
+assert_checkequal(j, jref/13);
+[h, j] = histc(d, sb,"densityNorm,normWith: inf nan");
+assert_checkequal(h, href/16/2.5);
+assert_checkequal(j, jref/16);
+[h, j] = histc(d, sb,"densityNorm,normWith: leftout nan");
+assert_checkequal(h, href/17/2.5);
+assert_checkequal(j, jref/17);
+[h, j] = histc(d, sb,"densityNorm,normWith: rightout inf");
+assert_checkequal(h, href/18/2.5);
+assert_checkequal(j, jref/18);
+[h, j] = histc(d, sb,"densityNorm,normWith: all");
+assert_checkequal(h, href/24/2.5);
+assert_checkequal(j, jref/24);
+
+// CATEGORIAL MODE
+// The order of binsValues matters and is kept
+// a) sorted, no duplicate:
+d = [
+1  7  4  4  1  4  3  4  8  6  8  2  3  4  6
+1  6  2  7  7  3  8  7  4  3  4  4  1  5  7
+];
+[h,j,b,i] = histc(d, [1 2 4 7] , "discrete");
+href = [4 2 8 5];
+assert_checkequal(h, href);
+assert_checkequal(b, [1 2 4 7]);
+iref = [
+1  4  3  3  1  3  0  3  0  0  0  2  0  3  0
+1  0  2  4  4  0  0  4  3  0  3  3  1  0  4
+];
+assert_checkequal(i, iref);
+// b) sorted main bins values, but duplicates
+[h,j,b,i] = histc(d, [1 2 1 4 2 7 4] , "discrete");
+assert_checkequal(h, href);
+assert_checkequal(b, [1 2 4 7]);
+assert_checkequal(i, iref);
+
+// c) puzzled bins values, no duplicates:
+[h,j,b,i] = histc(d, [2 7 1 4] , "discrete");
+href = [2 5 4 8];
+assert_checkequal(h, href);
+assert_checkequal(b, [2 7 1 4]);
+iref = [
+3  2  4  4  3  4  0  4  0  0  0  1  0  4  0
+3  0  1  2  2  0  0  2  4  0  4  4  3  0  2
+];
+assert_checkequal(i, iref);
+// d) puzzled and duplicates bins values:
+[h,j,b,i] = histc(d, [2 7 2 7 1 7 2 4 1 4] , "discrete");
+assert_checkequal(h, href);
+assert_checkequal(b, [2 7 1 4]);
+assert_checkequal(i, iref);
 
+// e) bins with %inf and %nan
+d = [
+1 1 1 1 1 2 2 2 2 3 3 3 4 4 5
+6 7 7 8 8 8 9 9 9 9 0 0 0 0 0
+];
+uns = [1 1 1 1 1];
+d = [d ; [-uns uns uns*0]*%inf];
+//   1    1    1    1    1    2   2   2   2   3   3   3   4   4   5
+//   6    7    7    8    8    8   9   9   9   9   0   0   0   0   0
+//  -Inf -Inf -Inf -Inf -Inf Inf Inf Inf Inf Inf Nan Nan Nan Nan Nan
+[h,j,b,i] = histc(d, [1 2 4 7 %nan -%inf] , "discrete");
+bref = [1  2  4  7 -%inf]
+href = [5  4  2  2  5 ];
+jref = [17 0  5  5 10 ];
+iref = [
+1  1  1  1  1  2  2  2  2  0  0  0  3  3  0
+0  4  4  0  0  0  0  0  0  0  0  0  0  0  0
+5  5  5  5  5  0  0  0  0  0  0  0  0  0  0
+];
+assert_checkequal(h, href);
+assert_checkequal(j, jref);
+assert_checkequal(b, bref);
+assert_checkequal(i, iref);
+// e.2) = normalized by counted
+[h,j,b,i] = histc(d, [1 2 4 7 %nan -%inf] , "discrete,countsNorm");
+assert_checkequal(h, href/sum(href));
+assert_checkequal(j, jref/sum(href));
+// e.3) = normalized by all
+options = "discrete,countsNorm,normwith: all";
+[h,j,b,i] = histc(d, [1 2 4 7 %nan -%inf], options);
+assert_checkequal(h, href/size(d,"*"));
+assert_checkequal(j, jref/size(d,"*"));
+// e.3) = normalized including out
+options = "discrete,countsNorm,normwith: out";
+[h,j,b,i] = histc(d, [1 2 4 7 %nan -%inf], options);
+assert_checkequal(h, href/(sum(href)+jref(1)));
+assert_checkequal(j, jref/(sum(href)+jref(1)));
+// e.4) normalized including Inf: should change nothing, since Inf and -Inf
+//      are already included.
+options = "discrete,countsNorm,normwith: inf";
+[h,j,b,i] = histc(d, [1 2 4 7 %nan -%inf], options);
+assert_checkequal(h, href/(sum(href)+5));
+assert_checkequal(j, jref/(sum(href)+5));
+// e.5) normalized including Nan
+options = "discrete,countsNorm,normwith: nan";
+[h,j,b,i] = histc(d, [1 2 4 7 %nan -%inf], options);
+assert_checkequal(h, href/(sum(href)+jref(4)));
+assert_checkequal(j, jref/(sum(href)+jref(4)));
+
+// =============================
+// WITH SPARSE MATRIX OF NUMBERS
+// =============================
+
+
+// =====================
+// WITH ENCODED INTEGERS
+// =====================
+assert_checkequal(histc(int16(37)), 1);
+
+// ==========
+// WITH TEXTS
+// ==========
+// Discrete bins
+// -------------
+assert_checkequal(histc("abcd"), 1);
+assert_checkequal(histc("abcd",["a" "b"]), 1);
+assert_checkequal(histc("cbcd",["a" "b"]), 0);
+assert_checkequal(histc(["a" "c" "a" "a" "b" "c"]), [3 1 2]);
+
+t = [
+"c" "n" "h" "i" "b" "i" "f" "i" "p" "l" "p" "d" "f" "i" "l"
+"b" "m" "e" "o" "o" "f" "p" "o" "h" "f" "h" "h" "c" "k" "o"
+"p" "f" "k" "a" "j" "o" "j" "d" "h" "h" "n" "m" "o" "l" "n"
+"h" "b" "o" "l" "j" "n" "o" "i" "g" "i" "a" "a" "j" "d" "p"
+];
+// With default discrete bins:
+[h,j,b,i] = histc(t);
+assert_checkequal(h, [3 3 2 3 1 5 1 7 6 4 2 4 2 4 8 5]);
+assert_checkequal(j, [0 0 0]);
+assert_checkequal(b, asciimat((97:112)')');
+iref = [
+3   14  8   9   2   9   6   9   16  12  16  4   6   9   12
+2   13  5   15  15  6   16  15  8   6   8   8   3   11  15
+16  6   11  1   10  15  10  4   8   8   14  13  15  12  14
+8   2   15  12  10  14  15  9   7   9   1   1   10  4   16
+];
+assert_checkequal(i, iref);
+// With given discrete bins WITHOUT "" bins:
+t2 = t;
+t2([7 13 19 26 32 39 43]) = "";
+// --> t2  =
+// c  n  h     b  i  f  i  p  l  p  d  f  i  l
+// b  m  e  o  o  f     o  h  f  h  h  c  k  o
+// p     k  a     o  j  d  h        m  o  l  n
+// h  b  o  l  j  n  o     g  i  a  a  j  d  p
+//
+// b =  '' a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p
+// h =  7  3  3  2  3  1  4  1  6  4  3  2  4  2  3  8  4
+href = [3 1 4 8];
+N = sum(href);
+jref = [37 0 7];
+bref = ["a" "e" "i" "o"];
+iref = [
+0  0  0  0  0  3  0  3  0  0  0  0  0  3  0
+0  0  2  4  4  0  0  4  0  0  0  0  0  0  4
+0  0  0  1  0  4  0  0  0  0  0  0  4  0  0
+0  0  4  0  0  0  4  0  0  3  1  1  0  0  0
+];
+[h,j,b,i] = histc(t2, bref, "discrete");
+assert_checkequal(h, href);
+assert_checkequal(j, jref);
+assert_checkequal(i, iref);
+// With given discrete bins WITHOUT "" bins: Normalized
+[h,j,b,i] = histc(t2, bref, "discrete,countsNorm");
+assert_checkequal(h, href/16);
+assert_checkequal(j, jref/16);
+[h,j,b,i] = histc(t2, bref, "discrete,countsNorm,normWith: empty");
+assert_checkequal(h, href/(16+7));
+assert_checkequal(j, jref/(16+7));
+[h,j,b,i] = histc(t2, bref, "discrete,countsNorm,normWith: all");
+assert_checkequal(h, href/60);
+assert_checkequal(j, jref/60);
+[h,j,b,i] = histc(t2, bref, "discrete,countsNorm,normWith: out");
+assert_checkequal(h, href/(N+jref(1)));
+assert_checkequal(j, jref/(N+jref(1)));
+// With given discrete bins WITH "" bins: Normalized
+href = [3 1 4 8 7];
+N = sum(href);
+jref = [37 0 7];
+[h,j,b,i] = histc(t2, [bref ""], "discrete,countsNorm");
+assert_checkequal(h, href/N);
+assert_checkequal(j, jref/N);
+[h,j,b,i] = histc(t2, [bref ""], "discrete,countsNorm,normWith: empty");
+assert_checkequal(h, href/N);
+assert_checkequal(j, jref/N);
+[h,j,b,i] = histc(t2, [bref ""], "discrete,countsNorm,normWith: out");
+assert_checkequal(h, href/60);
+assert_checkequal(j, jref/60);
+
+// Continuous bins. Data WITHOUT ""
+// --------------------------------
+[h,j,b,i] = histc(t, ["a" "c" "e" "g" "i" "k" "m" "o" "q"]);
+assert_checkequal(h, [8  4  6  13  6  6  12  5]);
+assert_checkequal(j, [0 0 0]);
+iref = [
+1  7  4  4  1  4  3  4  8  6  8  2  3  4  6
+1  6  2  7  7  3  8  7  4  3  4  4  1  5  7
+8  3  5  1  5  7  5  2  4  4  7  6  7  6  7
+4  1  7  6  5  7  7  4  3  4  1  1  5  2  8
+];
+assert_checkequal(i, iref);
+// With continuous bins and outsiders:
+[h,j,b,i] = histc(t, ["c" "e" "g" "i" "k" "m"]);
+assert_checkequal(h, [6 6 13 6 6]);
+assert_checkequal(j, [6 17 0]);
+iref = [
+1  0  3  3  0  3  2  3  0  5  0  1  2  3  5
+0  5  1  0  0  2  0  0  3  2  3  3  1  4  0
+0  2  4  0  4  0  4  1  3  3  0  5  0  5  0
+3  0  0  5  4  0  0  3  2  3  0  0  4  1  0
+];
+assert_checkequal(i, iref);
+// With continuous and marginal bins: "" <=> -inf , "~~" <=> Inf (regular ascii)
+[h,j,b,i] = histc(t, ["" "c" "e" "g" "i" "k" "m" "~~"]);
+assert_checkequal(h, [8 4 6 13 6 6 17]);
+assert_checkequal(j, [0 0 0]);
+iref = [
+1  7  4  4  1  4  3  4  7  6  7  2  3  4  6
+1  6  2  7  7  3  7  7  4  3  4  4  1  5  7
+7  3  5  1  5  7  5  2  4  4  7  6  7  6  7
+4  1  7  6  5  7  7  4  3  4  1  1  5  2  7
+];
+assert_checkequal(i, iref);
+
+// Continuous bins. Data WITH ""
+// ------------------------------
+// t2  =
+// c  n  h     b  i  f  i  p  l  p  d  f  i  l
+// b  m  e  o  o  f     o  h  f  h  h  c  k  o
+// p     k  a     o  j  d  h        m  o  l  n
+// h  b  o  l  j  n  o     g  i  a  a  j  d  p
+//
+// b =  '' a  b  c  d  e  f  g  h  i  j  k  l  m  n  o  p
+// h =  7  3  3  2  3  1  4  1  6  4  3  2  4  2  3  8  4
+[h,j,b,i] = histc(t2, ["e" "f" "g" "h" "i" "j"]);
+href = [5 1 6 4 3]; N = sum(href);
+jref = [11  23  7];
+[h,j,b,i] = histc(t2, ["e" "f" "g" "h" "i" "j"],"countsNorm,normWith: leftout");
+assert_checkequal(h, href/(N+jref(1)));
+assert_checkequal(j, jref/(N+jref(1)));
+[h,j,b,i] = histc(t2, ["e" "f" "g" "h" "i" "j"],"countsNorm,normWith: rightout");
+assert_checkequal(h, href/(N+jref(2)));
+assert_checkequal(j, jref/(N+jref(2)));
+[h,j,b,i] = histc(t2, ["e" "f" "g" "h" "i" "j"],"countsNorm,normWith: out");
+assert_checkequal(h, href/sum([N jref(1:2)]));
+assert_checkequal(j, jref/sum([N jref(1:2)]));
+[h,j,b,i] = histc(t2, ["e" "f" "g" "h" "i" "j"],"countsNorm,normWith: empty");
+assert_checkequal(h, href/(N+jref(3)));
+assert_checkequal(j, jref/(N+jref(3)));
+[h,j,b,i] = histc(t2, ["e" "f" "g" "h" "i" "j"],"countsNorm,normWith: out empty");
+assert_checkequal(h, href/sum([N jref]));
+assert_checkequal(j, jref/sum([N jref]));
+[h,j,b,i] = histc(t2, ["e" "f" "g" "h" "i" "j"],"countsNorm,normWith: all");
+assert_checkequal(h, href/sum([N jref]));
+assert_checkequal(j, jref/sum([N jref]));
+
+
+// ================
+// WITH POLYNOMIALS
+// ================
+assert_checkequal(histc(%z), 1);
+assert_checkequal(histc([%z %z 2+%z]), [2 1]);
+assert_checkequal(histc([%z %z 2+%z],,"countsnorm"), [2 1]/3);
+assert_checkequal(histc([%z %z 2+%z %nan],,"countsnorm"), [2 1]/3);
+assert_checkequal(histc([%z %z 2+%z %nan],,"countsnorm,normWith: Nan"), [2 1]/4);  // A VOIR
+// Data order is kept
+assert_checkequal(histc([2+%z %z %z ]), [1 2]);
+
+
+// ==============================
+// CHECKING ERRORS AND TOLERANCES
+// ==============================
+t = ["c" "n" "h" "i" "b" "i" "f" "i" "p" "l" "p" "d" "f" "i" "l"];
+// Wrong number of arguments
+msg = _("%s: Wrong number of input arguments: %d to %d expected.\n");
+msg = msprintf(msg, "histc", 1, 3);
+assert_checkerror("histc()", msg);
+// Too many input arguments
+assert_checkfalse(execstr("histc(1,2,3,4)", "errcatch")==0);
+// Too many output arguments
+assert_checkfalse(execstr("[a,b,c,d,e] = histc(rand(1,100))", "errcatch")==0);
+// Wrong Data types
+msg = _("%s: Argument #%d: %s\n");
+msg = msprintf(msg, "histc", 1, "data array missing");
+assert_checkerror("histc(,,3)", msg);
+msg = _("histc: Data in argument #1: Numbers or polynomials or texts expected.");
+assert_checkerror("histc(rand(1,100)<0.5)", msg);       // boolean
+assert_checkerror("histc(sprand(1,100,0.1)>0.5)", msg); // sparse booleans
+assert_checkerror("histc(list(%pi, 1, %e))", msg);      // list
+assert_checkerror("histc({1, 2, 3, 4})", msg);          // cells
+s(1:3).r = %pi;
+assert_checkerror("histc(s)", msg);                     // structs
+// Number of bins must be integer > 0:
+msg = _("%s: Argument #%d: non-zero decimal integer expected.\n");
+msg = msprintf(msg, "histc", 2);
+assert_checkerror("histc(rand(1,100), 1.5)", msg);
+assert_checkerror("histc(rand(1,100), 0)", msg);
+assert_checkerror("histc(rand(1,100), %inf)", msg);
+assert_checkerror("histc(rand(1,100), %nan)", msg);
+// Bins width must not be %inf
+msg = _("%s: Argument #%d: decimal number > -Inf expected.\n");
+msg = msprintf(msg, "histc", 2);
+assert_checkerror("histc(rand(1,100), -%inf)", msg);
+
+// Mismatching Data and binsEdges types
+msg = _("%s: Arguments #%d and #%d: Same types expected.\n")
+msg = msprintf(msg, "histc", 1, 2);
+assert_checkerror("histc(t, 1:3)", msg);
+assert_checkerror("histc(rand(1,100), [""a"" ""b"" ""c""])", msg);
+assert_checkerror("histc(int8(rand(1,100)*100), [""a"" ""b"" ""c""])", msg);
+// Mismatching Data and binsValues types
+assert_checkerror("histc(t, 1:3, ""discrete"")", msg);
+assert_checkerror("histc(rand(1,100), [""a"" ""b""], ""discrete"")", msg);
+assert_checkerror("histc(int8(rand(1,100)*100), [""a"" ""b""], ""discrete"")", msg);
+// Wrong algo name
+msg = msprintf(_("%s: Argument #%d: wrong value for binning algo"),"histc",2);
+assert_checkerror("histc(rand(1,100), ""foo"")", msg);
+// Unapplicable binning modes:
+msg = msprintf( _("%s: Argument #2: Please provide bins edges or values or leave choosing default bins.\n"), "histc");
+assert_checkerror("histc(t, ""sqrt"")", msg);
+assert_checkerror("histc(t, 3)", msg);
+assert_checkerror("histc(t, -3)", msg);
+// Wrong options type
+msg = _("%s: Argument #%d: Text expected.\n");
+msg = msprintf(msg, "histc", 3);
+assert_checkerror("histc(rand(1,100),,%t)", msg);
+assert_checkerror("histc(rand(1,100),,1)", msg);
+assert_checkerror("histc(rand(1,100),,int8(1))", msg);
+// Unexisting options are ignored
+assert_checkequal(execstr("histc(rand(1,1000),,""foo"")", "errcatch"), 0);
+// Unrelevant options are ignored
+tmp = "histc(t,,""density"")";
+assert_checkequal(execstr(tmp, "errcatch"), 0);
+// Duplicate options are ignored
+tmp = "histc(grand(1,100,""uin"",0,20),,""discrete,discrete"")";
+assert_checkequal(execstr(tmp, "errcatch"), 0);
+// Useless option is ignored
+tmp = "histc([%z 2*%z %z],,""discrete"")";
+assert_checkequal(execstr(tmp, "errcatch"), 0);
+// Useless normWith: flags are ignored
+tmp = "histc(rand(1,100),,""counts,normWith: inf"")";
+assert_checkequal(execstr(tmp, "errcatch"), 0);
+// Bad normWith: flags are ignored
+tmp = "histc(rand(1,100),,""countsNorm,normWith: foo"")";
+assert_checkequal(execstr(tmp, "errcatch"), 0);
+
+// ===========================================================================
+//                                  SCILAB 5.5
+// ===========================================================================
 rand("seed", 0);
 d = rand(1, 10000, "normal");
 [cfC, indC] = histc(20, d);
@@ -73,7 +671,7 @@ assert_checkequal(cfC, refCF);
 
 // With x instead of n as first argument
 cfC = histc([-5 0 5], d);
-refCF = [0.09982   0.10018];
+refCF = [0.4991 0.5009]/5;
 assert_checkequal(cfC, refCF);
 cfC = histc(int8([-5 0 5]), d);
 assert_checkequal(cfC, refCF);
@@ -81,6 +679,7 @@ cfC = histc(int16([-5 0 5]), d);
 assert_checkequal(cfC, refCF);
 cfC = histc(int32([-5 0 5]), d);
 assert_checkequal(cfC, refCF);
+assert_checkequal(sum(cfC)*5, 1);
 cfC = histc([-5 0 5], d, %f);
 assert_checkequal(sum(cfC), 10000); // -5 > d > 5, and d has 10000 elements.
 
@@ -141,6 +740,7 @@ assert_checkalmostequal(cfC, refCF, 1e-7);
 
 // Same test, without normalization
 [cfC, indC] = histc(40, D, normalization=%f);
+assert_checkequal(size(indC), [100000 1]);
 
 refCF = [
 26929
@@ -201,34 +801,3 @@ cfC = histc(int32([0 7]), D);
 assert_checkalmostequal(cfC, refCF);
 cfC = histc([0 7], D, %f);
 assert_checkequal(cfC, 100000); // 0 > D > 7, and D has 100000 elements.
-
-// Error checks
-refMsg = msprintf(_("%s: Wrong number of input argument(s): At least %d expected.\n"), "histc", 2);
-assert_checkerror("histc(1)", refMsg);
-assert_checkerror("histc()", refMsg);
-
-refMsg = msprintf(_("%s: Wrong type of input argument #%d: A single boolean expected.\n"), "histc", 3);
-assert_checkerror("histc(1, 1, normalization=[%t %t])", refMsg);
-assert_checkerror("histc(1, 1, [%t %t])", refMsg);
-assert_checkerror("histc(1, 1, """")", refMsg);
-assert_checkerror("histc(1, 1, 1)", refMsg);
-
-refMsg = msprintf(_("%s: Wrong value for input argument #%d: Must be in the interval %s.\n"), "histc", 1, "[1, oo)");
-assert_checkerror("histc(0, 1, %t)", refMsg);
-assert_checkerror("histc(-1, 1)", refMsg);
-
-refMsg = msprintf(_("%s: Wrong type for input argument #%d: Integer expected.\n"), "histc", 1);
-assert_checkerror("histc(1.5, 1, %t)", refMsg);
-
-refMsg = msprintf(_("%s: Wrong values for input argument #%d: Elements must be in increasing order.\n"), "histc", 1);
-assert_checkerror("histc([2 1], 1, %t)", refMsg);
-assert_checkerror("histc([1 1], 1, %t)", refMsg);
-
-refMsg = msprintf(_("%s: Wrong type for input argument #%d: A real matrix expected.\n"), "histc", 1);
-assert_checkerror("histc(list(), 1)", refMsg);
-assert_checkerror("histc("""", 1)", refMsg);
-assert_checkerror("histc(%t, 1)", refMsg);
-refMsg = msprintf(_("%s: Wrong type for input argument #%d: A real matrix expected.\n"), "histc", 2);
-assert_checkerror("histc(1, list())", refMsg);
-assert_checkerror("histc(1, """")", refMsg);
-assert_checkerror("histc(1, %t)", refMsg);