.. highlightlang:: us

.. _histogram:

histogram
=========

.. index:: histogram

.. us.tag  histogram ENGLISH New530  math-base

:ref:`histogram` calculates the histogram of a vector.

.. function::  rmXY = histogram(rmY)
    rmXY = histogram(rmY, bins)
    rmXY = histogram(rmY, bins, nType)
    rmXY = histogram(rmY, bins, nType, bCenterBin)
    rmXY = histogram(rmY, bins, nType, bCenterBin, hLayer)

.. us.return

**Return Value**

*rmXY* is a matrix with two columns. Column 1 contains the bin center values 
and column 2 the number of points in each bin. If *hLayer* is specified and
greater of equal zero the function returns the handle of a dataset.

.. us.params

**Parameters**

.. uparam:: rmY

   *rmY* is a real matrix. The last matrix column is used to calculate the
   histogram.

.. uparam:: bins

   *bins* is a scalar value with the number of bins or a vector with bin limits
   or center points Default value is 10.

.. uparam:: nType

   *nType* sets the type of histogram:

   .. list-table::
      :header-rows: 1

      * - Typ
        - Description
      * - nType = 1
        - Absolute
      * - nType = 2
        - Percent
      * - nType = 3
        - cumulative (more than)
      * - nType = 4
        - cumulative in Percent (more than)
      * - nType = 5
        - cumulative (less than)
      * - nType = 6
        - cumulative in Percent (less than)

   Default value is 1.

.. uparam:: bCenterBin

   If *bCenterBin* is TRUE (1), the values in *bin* are treated as center points
   If *bCenterBin* is FALSE (0), the values in *bin* are treated as class limits. 
   Default value is FALSE;
   Example for *bCenterBin*  = TRUE:
   bins: 2,4,6,8  Bins: 1 to 3, 3 to 5, 5 to7, 7 to 9
   Example for *bCenterBin*  = FALSE:
   bins: 2,4,6,8  Bins: 2 to 4, 4 to 6, 6 to 8

.. uparam:: hLayer

   If *hLayer* is 0, an new diagram with the plot is created.
   If *hLayer* is greater 0, the histogram plot is added to the layer *hLayer*.
   For both cases the function returns the dataset handle in the parameter *rmXY*.
   If *hLayer* is -1 the function does not create a plot. Default value is -1;

.. us.example

**Example**

::

   * srand(0)
       1.0000
   * histogram(rand(10,1), 0:0.1:1, 1, TRUE)
   0.0000  0.0000
   0.1000  0.0000
   0.2000  2.0000
   0.3000  1.0000
   0.4000  0.0000
   0.5000  0.0000
   0.6000  1.0000
   0.7000  2.0000
   0.8000  3.0000
   0.9000  1.0000
   1.0000  0.0000

   * srand(0)
       1.0000
   * histogram(rand(10,1), 0:0.1:1, 1, FALSE)
   0.0500  0.0000
   0.1500  1.0000
   0.2500  2.0000
   0.3500  0.0000
   0.4500  0.0000
   0.5500  1.0000
   0.6500  1.0000
   0.7500  1.0000
   0.8500  4.0000
   0.9500  0.0000

   

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - 5.10.2
     - New Types: 5 cumulative (less than) and 6 cumulative in Percent (less than) added.
   * - 5.3.0
     - New.

.. seealso::
   :ref:`overview-mathematic`,
   :ref:`histc`,
   :ref:`sum`,
   :ref:`cumsum`

:sub:`id-694203`