.. highlightlang:: us

.. index:: plotcategory

.. _plotcategory:

plotcategory
============

.. us.tag plotcategory ENGLISH New5600

:ref:`plotcategory` plots a category plot with grouped bars.

.. function::  rvData = plotcategory(svCategoryLabel, rmData)
    rvData = plotcategory(svCategoryLabel, rmData, oParameter)

.. us.return

**Return Value**

*rvData* is a vector with dataset handles.

.. us.params

**Parameters**

.. uparam:: svCategoryLabel

   *svCategoryLabel* is a string vector with category labels.

.. uparam:: rmData

   *rmData* is a real matrix. Each column creates a dataset. The number
   of rows should match the number of elements of *svCategoryLabel*.

.. uparam:: oParameter

   *oParameter* is an object with optional parameters.

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

      * - Element Name
        - Description
        - Default Value
      * - hLayer
        - Layer handle. 0: a new layer will be created
        - 0
      * - rvStacked = [0,1,1,0]
        - A real vector with 0 (grouped) or 1 (stacked). The number of elements
          should match the number of datasets.
        - 0: grouped
      * - gapwidth
        - gap between categories in the range 0 to 5 (0 to 500 percent or bar width).
        - 1.0
      * - overlap
        - bar overlap in the range -1 to 1 (-100 to 100 percent or bar width).
        - -0.2
      * - bAutoscale;
        - autoscale axes
        - 1
      * - bReplot
        - replot page
        - 1
      * - b100percent;
        - scale stacked bars to 100 percent.
        - 0
      * - xTitle
        - x axis title
        - "" (do not modify title)
      * - yTitle
        - y axis title
        - "" (do not modify title)
      * - color_scale
        - color scale, see :ref:`ColorScale_GetNames`
          Example: ``color_scale = 'Blues'``
        - Purpels
      * - bLabel
        - Show or hide bar labels
        - 1 (show label)
      * - nLabelPosition
        - Label position: 1: inside bottom, 2: inside center, 3: inside top, 
          4: outside top
        - 3 (inside top)

.. us.example

**Example**

The following example will create a diagram with a random data. 6 datasets
with 4 values. 

::

   svCategoryLabel = "";
   rmData = rand(4,6);
   o = [. rvStacked = [1,1,1,0,1,1], xTitle = "Period", yTitle = "Value in %"];
   plotcategory(svCategoryLabel, rmData, o)

.. seealso::
   :ref:`DocCreate`,
   :ref:`PageCreate`,
   :ref:`PageGetParentDocument`,
   :ref:`LayerCreate`,
   :ref:`XYCreate`,
   :ref:`NC_plotcategory`,
   :ref:`GetParent`,
   :ref:`ColorScale_GetNames`

:sub:`id-2043309`