../lib/numru/ggraph.rb

# module NumRu::GGraph and others in ggraph.rb

## Index

- class NumRu::GPhys (methods added)
  - first1D Returns a 1D subset selecting the first elements of 2nd, 3rd, .. dimensions, i.e., self[true, 0, 0, ...].
  - first2D Returns a 2D subset selecting the first elements of 3rd, 4th, .. dimensions, i.e., self[true, true, 0, 0, ...].
- module NumRu::GGraph
  - title Shows title by `DCL.uxmttl('t',string,0.0)`. Graphic methods such as contour calls this by default.
  - annotate Show texts on the right margin of the viewport. Graphic methods such as contour calls this by default.
  - fig Define a figure by setting viewport, window, and coordinate transform id (itr) from two 1D VArrays `xax` and `yax`.
  - set_fig Change the default option values for fig.
  - next_fig Set the option values effective only in the next call of fig (cleared then).
  - axes Draw axes using (by default) info in `xax` and `yax` if non-nil.
  - set_axes Change the default option values for axes.
  - next_axes Set the option values effective only in the next call of axes (cleared then).
  - line Plot a poly-line by selecting the first dimension (with first1D) if `gphys` is more than 2D.
  - mark Similar to line but plots marks instead of drawing a poly-line.
  - contour Contour plot by selecting the first 2 dimensions (with first2D) if `gphys` is more than 3D.
  - set_contour_levels Set contour levels for contour explicitly by values with the option `levels`.
  - clear_contour_levels Clear contour levels set by set_contour_levels.
  - set_linear_contour_options Change the default option values regarding linear contour level setting in contour.
  - next_linear_contour_options Similar to set_linear_contour_options but the setting is effective only for the next call of contour.
  - tone Color tone or shading by selecting the first 2 dimensions (with first2D) if `gphys` is more than 3D.
  - set_tone_levels Set tone levels for tone explicitly by values.
  - clear_tone_levels Clear tone levels set by set_tone_levels.
  - set_linear_tone_options Change the default option values regarding linear tone level setting in tone.
  - next_linear_tone_options Similar to set_linear_tone_options but the setting is effective only for the next call of tone.
- module NumRu::DCLExt
  - gl_set_params Calls `DCL.glpset` multiple times (for each key and val of `hash`).
  - sg_set_params Calls `DCL.sgpset` multiple times (for each key and val of `hash`).
  - sl_set_params Calls `DCL.slpset` multiple times (for each key and val of `hash`).
  - sw_set_params Calls `DCL.swpset` multiple times (for each key and val of `hash`).
  - uz_set_params Calls `DCL.uzpset` multiple times (for each key and val of `hash`).
  - ul_set_params Calls `DCL.ulpset` multiple times (for each key and val of `hash`).
  - uc_set_params Calls `DCL.ucpset` multiple times (for each key and val of `hash`).
  - uu_set_params Calls `DCL.uupset` multiple times (for each key and val of `hash`).
  - us_set_params Calls `DCL.uspset` multiple times (for each key and val of `hash`).
  - ud_set_params Calls `DCL.udpset` multiple times (for each key and val of `hash`).
  - ud_set_linear_levs Set contour levels with a constant interval
  - ud_set_contour Set contours of at specified levels.
  - ud_add_contour Same as ud_set_contour, but does not clear the contour levels that have been set.
  - ue_set_params Calls `DCL.uepset` multiple times (for each key and val of `hash`).
  - ue_set_linear_levs Set tone levels with a constant interval
  - ue_set_tone Set tone levels and patterns.
  - ue_add_tone Same as ue_set_tone, but does not clear the tone levels that have been set.
  - ug_set_params Calls `DCL.ugpset` multiple times (for each key and val of `hash`). See gl_set_params for usage.
  - um_set_params Calls `DCL.umpset` multiple times (for each key and val of `hash`).

# class NumRu::GPhys (methods added)

The following methods are added to GPhys.

## Instance Methods

#### `first1D`

  Returns a 1D subset selecting the first elements of 2nd, 3rd, .. dimensions, i.e., self[true, 0, 0, ...].

  ARGUMENTS

  - (none)

  RETURN VALUE

  - a GPhys

#### `first2D`

  Returns a 2D subset selecting the first elements of 3rd, 4th, .. dimensions, i.e., self[true, true, 0, 0, ...].

  ARGUMENTS

  - (none)

  RETURN VALUE

  - a GPhys

# module NumRu::GGraph

A graphic library for GPhys using RubyDCL.

This module uses GPhys but is not a part of it. More specifically, even though this module is included in the GPhys distribution, the class NumRu::GPhys knows nothing about it, and GGraph accesses GPhys only though public methods. So GGraph is not an insider, and you can make another graphic library if you like.

## Module Functions

#### `title(string)`

  Shows title by `DCL.uxmttl('t',string,0.0)`. Graphic methods such as contour calls this by default.

  RETURN VALUE

  - nil

#### `annotate(str_ary)`

  Show texts on the right margin of the viewport. Graphic methods such as contour calls this by default.

  ARGUMENTS

  - str_ary (Array of String) :

  RETURN VALUE

  - nil

#### `fig(xax, yax, options=nil)`

  Define a figure by setting viewport, window, and coordinate transform id (itr) from two 1D VArrays `xax` and `yax`.

  `DCL.grfrm` or `DCL.grfig` is called depending options provided.

  ARGUMENTS

  - xax (VArray): a VArray representing the x (horizontal) coordinate of the figure. The x range of the window (UXMIN & UYMAX in DCL) are determined with the max and min of `xax.val`. By default, the min and max values are assigned to the left and right boundaries, respectively, but it is reversed if `xax` has a 'positive' attribute and its value is 'down' etc (see `options`).
  - yax (VArray): similar to `xax` but for the y (vertical) coordinate of the figure.

  - options (Hash) : options to change the default behavior if specified. It is a Hash with option names (String) as keys and their values. Options are interpreted by a NumRu::Misc::KeywordOptAutoHelp, so you can shorten the keys (by omitting tails) as long as it is unambiguous.

        option name   default value   # description:
        "new_frame"   true    # whether to define a new frame by DCL.grfrm
                              # (otherwise, DCL.grfig is called)
        "window"      nil     # [uxmin, uxmax, uymin, uymax]
        "viewport"    [0.2, 0.8, 0.2, 0.8]    # [vxmin, vxmax, vymin, vymax]
        "itr"         1       # coordinate transformation number
        "xreverse"    "positive:down,units:hPa"       # Assign max value to
                              # UXMIN and min value to UXMAX if condition is
                              # satisfied (nil:never, true:always, String: when
                              # an attribute has the value specified
                              # ("key:value,key:value,..")
        "yreverse"    "positive:down,units:hPa"       # Assign max value to
                              # UYMIN and min value to UYMAX if condition is
                              # satisfied (nil:never, true:always, String: when
                              # an attribute has the value specified
                              # ("key:value,key:value,..")
        "help"        false   # show help message if true

  RETURN VALUE

  - nil

  POSSIBLE EXCEPTIONS

  - those from NumRu::DCL if any / TypeError if any
  - options has a key that does not match any of the option names.
  - options has a key that is ambiguous

#### `set_fig(options)`

  Change the default option values for fig.

  ARGUMENTS

  - options (Hash) : The usage is the same as `options` for fig.

  RETURN VALUE

  - a Hash containing the values replaced (the ones before calling this method)

  POSSIBLE EXCEPTIONS

  - see fig.

#### `next_fig(options)`

  Set the option values effective only in the next call of fig (cleared then).

  These value are overwritten if specified explicitly in the next call of fig.

  ARGUMENTS

  - options (Hash) : The usage is the same as `options` for fig.

  RETURN VALUE

  - nil

  POSSIBLE EXCEPTIONS

  - see fig.

#### `axes(xax=nil, yax=nil, options=nil)`

  Draw axes using (by default) info in `xax` and `yax` if non-nil.

  ARGUMENTS

  - xax (nil or VArray): if non-nil, attributes 'long_name' and 'units' are read to define `xtitle` and `xunits` (see below). These are overwritten by explicitly specifying `xtitle` and `xunits`.
  - yax (nil or VArray): if non-nil, attributes 'long_name' and 'units' are read to define `ytitle` and `yunits` (see below). These are overwritten by explicitly specifying `ytitle` and `yunits`.

  - options (Hash) : options to change the default behavior if specified. It is a Hash with option names (String) as keys and their values. Options are interpreted by a NumRu::Misc::KeywordOptAutoHelp, so you can shorten the keys (by omitting tails) as long as it is unambiguous.

        option name   default value   # description:
        "xside"       "tb"    # Where to draw xaxes (combination of t, b and u)
        "yside"       "lr"    # Where to draw yaxes (combination of l, r and u)
        "xtitle"      nil     # Title of x axis (if nil, internally determined)
        "ytitle"      nil     # Title of y axis (if nil, internally determined)
        "xunits"      nil     # Units of x axis (if nil, internally determined)
        "yunits"      nil     # Units of y axis (if nil, internally determined)
        "help"        false   # show help message if true

  RETURN VALUE

  - nil

  POSSIBLE EXCEPTIONS

  - those from NumRu::DCL if any / TypeError if any
  - options has a key that does not match any of the option names.
  - options has a key that is ambiguous

#### `set_axes(options)`

  Change the default option values for axes.

  ARGUMENTS

  - options (Hash) : The usage is the same as `options` for axes.

  RETURN VALUE

  - a Hash containing the values replaced (the ones before calling this method)

  POSSIBLE EXCEPTIONS

  - see axes.

#### `next_axes(options)`

  Set the option values effective only in the next call of axes (cleared then).

  These value are overwritten if specified explicitly in the next call of axes.

  ARGUMENTS

  - options (Hash) : The usage is the same as `options` for axes.

  RETURN VALUE

  - nil

  POSSIBLE EXCEPTIONS

  - see axes.

#### `line(gphys, newframe=true, options=nil)`

  Plot a poly-line by selecting the first dimension (with first1D) if `gphys` is more than 2D.

  ARGUMENTS

  - gphys (GPhys) : a GPhys whose data is plotted.
  - newframe (true/false) : if true, calls fig, axes, title, and annotate internally; if false, only the poly-line is drawn (overlaid to the exiting figure).

  - options (Hash) : options to change the default behavior if specified. It is a Hash with option names (String) as keys and their values. Options are interpreted by a NumRu::Misc::KeywordOptAutoHelp, so you can shorten the keys (by omitting tails) as long as it is unambiguous.

        option name   default value   # description:
        "title"       nil     # Title of the figure(if nil, internally
                              # determined)
        "annotate"    true    # if false, do not put texts on the right
                              # margin even when newframe==true
        "exchange"    false   # whether to exchange x and y axes
        "index"       1       # line/mark index
        "type"        1       # line type
        "help"        false   # show help message if true

  RETURN VALUE

  - nil

#### `mark(gphys, newframe=true, options=nil)`

  Similar to line but plots marks instead of drawing a poly-line.

  ARGUMENTS

  - gphys (GPhys) : a GPhys whose data is plotted.
  - newframe (true/false) : if true, calls fig, axes, title, and annotate internally; if false, only the poly-line is drawn (overlaid to the exiting figure).

  - options (Hash) : options to change the default behavior if specified. It is a Hash with option names (String) as keys and their values. Options are interpreted by a NumRu::Misc::KeywordOptAutoHelp, so you can shorten the keys (by omitting tails) as long as it is unambiguous.

        option name   default value   # description:
        "title"       nil     # Title of the figure(if nil, internally
                              # determined)
        "annotate"    true    # if false, do not put texts on the right
                              # margin even when newframe==true
        "exchange"    false   # whether to exchange x and y axes
        "index"       1       # mark index
        "type"        2       # mark type
        "size"        0.01    # marks size
        "help"        false   # show help message if true

  RETURN VALUE

  - nil

#### `contour(gphys, newframe=true, options=nil)`

  Contour plot by selecting the first 2 dimensions (with first2D) if `gphys` is more than 3D.

  Contour levels are determined as follows:

  - contour levels are set in this method if not set by contour_levels or the option `"levels"` is specified explicitly.
  - When contour levels are set in this method, the option `"levels"` has the highest precedence. If it is specified, options `"index"`, `"line_type"`, `"label"`, and `"label_height"` are used. If `"levels"` are not specified, contour levels with a linear increment are set by using the options `"min"`, `"max"`, `"nlev"`, `"interval"`, `"nozero"`, `"coloring"`, `"clr_min"`, and `"clr_max"`, which are interpreted by DCLExt::ud_set_linear_levs. The default values of the linear level setting can be changed with set_linear_contour_options.

  ARGUMENTS

  - gphys (GPhys) : a GPhys whose data is plotted.
  - newframe (true/false) : if true, calls fig, axes, title, and annotate internally; if false, only the poly-line is drawn (overlaid to the exiting figure).

  - options (Hash) : options to change the default behavior if specified. It is a Hash with option names (String) as keys and their values. Options are interpreted by a NumRu::Misc::KeywordOptAutoHelp, so you can shorten the keys (by omitting tails) as long as it is unambiguous.

        option name   default value   # description:
        "title"       nil     # Title of the figure(if nil, internally
                              # determined)
        "annotate"    true    # if false, do not put texts on the right
                              # margin even when newframe==true
        "min"         nil     # minimum contour value
        "max"         nil     # maximum contour value
        "nlev"        nil     # number of levels
        "interval"    nil     # contour interval
        "nozero"      nil     # delete zero contour
        "coloring"    false   # set color contours with ud_coloring
        "clr_min"     13      # (if coloring) minimum color id
        "clr_max"     100     # (if coloring) maximum color id
        "help"        false   # show help message if true
        "levels"      nil     # contour levels (Array/NArray of Numeric)
        "index"       nil     # (if levels) line index(es) (Array/NArray of
                              # integers, Integer, or nil)
        "line_type"   nil     # (if levels) line type(s) (Array/NArray of
                              # integers, Integer, or nil)
        "label"       nil     # (if levels) contour label(s) (Array/NArray of
                              # String, String, true, false, nil). nil is
                              # recommended.
        "label_height"  nil   # (if levels) label height(s)
                              # (Array/NArray of Numeric, Numeric, or nil).
                              #  nil is recommended.

  RETURN VALUE

  - nil

#### `set_contour_levels(options)`

  Set contour levels for contour explicitly by values with the option `levels`.

  ARGUMENTS

  - options (Hash) : options to change the default behavior. The option `"levels"` is mandatory (so it is not optional!). Supported options are `"levels"`, `"index"`, `"line_type"`, `"label"`, and `"label_height"`. See contour for their description.

#### `clear_contour_levels`

  Clear contour levels set by set_contour_levels.

#### `set_linear_contour_options(options)`

  Change the default option values regarding linear contour level setting in contour.

  ARGUMENTS

  - options (Hash) : The usage is the same as `options` for contour but supported options here are limited to `"min"`, `"max"`, `"nlev"`, `"interval"`, `"nozero"`, `"coloring"`, `"clr_min"`, and `"clr_max"`.

  RETURN VALUE

  - a Hash containing the values replaced (the ones before calling this method)

#### `next_linear_contour_options(options)`

  Similar to set_linear_contour_options but the setting is effective only for the next call of contour.

#### `tone(gphys, newframe=true, options=nil)`

  Color tone or shading by selecting the first 2 dimensions (with first2D) if `gphys` is more than 3D.

  Tone levels are determined as follows:

  - Tone levels are set in this method if not set by set_tone_levels or both the options two `"levels"` and `"patterns"` are specified explicitly.
  - When contour levels & patterns are set in this method,
    - The combination of `"levels"` and `"patterns"` have the highest precedence. If they are specified, tone levels and patterns are determined by DCLExt::ue_set_tone.
    - If not, a linear tone levels are set if `"ltone"=true` (this is the default), or shading is made if `"ltone"=false`. Shading is determined by following the parameters in the UDPACK in DCL. Therefore, coloring is made if DCL.udpget('ltone')==true regardless the option `"ltone"=false` here. When linear levels are set in this method, options `"min"`, `"max"`, `"nlev"`, and `"interval"` are used if specified, which are interpreted by DCLExt::ue_set_linear_levs. Their default values can be changed by set_linear_tone_options.

  ARGUMENTS

  - gphys (GPhys) : a GPhys whose data is plotted.
  - newframe (true/false) : if true, calls fig, axes, title, and annotate internally; if false, only the poly-line is drawn (overlaid to the exiting figure).

  - options (Hash) : options to change the default behavior if specified. It is a Hash with option names (String) as keys and their values. Options are interpreted by a NumRu::Misc::KeywordOptAutoHelp, so you can shorten the keys (by omitting tails) as long as it is unambiguous.

        option name   default value   # description:
        "title"       nil     # Title of the figure(if nil, internally
                              # determined)
        "annotate"    true    # if false, do not put texts on the right
                              # margin even when newframe==true
        "ltone"       true    # Same as udpack parameter ltone
        "min"         nil     # minimum contour value
        "max"         nil     # maximum contour value
        "nlev"        nil     # number of levels
        "interval"    nil     # contour interval
        "help"        false   # show help message if true
        "levels"      nil     # tone levels  (Array/NArray of Numeric). Works
                              # together with patterns
        "patterns"    nil     # tone patters (Array/NArray of Numeric). Works
                              # together with levels

  RETURN VALUE

  - nil

#### `set_tone_levels(options)`

  Set tone levels for tone explicitly by values.

  ARGUMENTS

  - options (Hash) : options to change the default behavior. Supported options are `"levels"` and `"patterns"`. Both of them must be specified explicitly (so they are not optional!).

#### `clear_tone_levels`

  Clear tone levels set by set_tone_levels.

#### `set_linear_tone_options(options)`

  Change the default option values regarding linear tone level setting in tone.

  ARGUMENTS

  - options (Hash) : The usage is the same as `options` for tone but supported options here are limited to `"min"`, `"max"`, `"nlev"`, and `"interval"`.

  RETURN VALUE

  - a Hash containing the values replaced (the ones before calling this method)

#### `next_linear_tone_options(options)`

  Similar to set_linear_tone_options but the setting is effective only for the next call of tone.

# module NumRu::DCLExt

Collection of various compound DCL functions for convenience. This module is to be separated but temporarily included in ggraph.rb while it is premature.

## Index

MATH1

- glpack

GRPH1

- sgpack
- slpack
- swpack

GRPH2

- uzpack
- ulpack
- ucpack
- uupack
- uspack
- udpack
- uepack
- ugpack
- umpack

## Module Functions

### glpack

#### `gl_set_params(hash)`

  Calls `DCL.glpset` multiple times (for each key and val of `hash`).

  ARGUMENTS

  - hash (Hash) : combinations of parameter names and values for udpset

  RETURN VALUE

  - a Hash containing the parameter names and their old values that were replaced.

  EXAMPLES

  - You can modify parameters temporarily as follows.

        before = DCLExt.gl_set_params('lmiss'=>true,'rmiss'=>9999.0)
        ....
        DCLExt.gl_set_params(before)     # reset the change

### sgpack

#### `sg_set_params(hash)`

  Calls `DCL.sgpset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.

### slpack

#### `sl_set_params(hash)`

  Calls `DCL.slpset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.

### swpack

#### `sw_set_params(hash)`

  Calls `DCL.swpset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.

### uzpack

#### `uz_set_params(hash)`

  Calls `DCL.uzpset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.

### ulpack

#### `ul_set_params(hash)`

  Calls `DCL.ulpset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.

### ucpack

#### `uc_set_params(hash)`

  Calls `DCL.ucpset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.

### uupack

#### `uu_set_params(hash)`

  Calls `DCL.uupset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.

### uspack

#### `us_set_params(hash)`

  Calls `DCL.uspset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.

### udpack

#### `ud_set_params(hash)`

  Calls `DCL.udpset` multiple times (for each key and val of `hash`).

  ARGUMENTS

  - hash (Hash) : combinations of parameter names and values for udpset

  RETURN VALUE

  - a Hash containing the parameter names and their old values that were replaced.

  EXAMPLES

  - You can modify parameters temporarily as follows.

        before = DCLExt.ud_set_params('indxmj'=>4,'lmsg'=>false)
        DCL.udcntz(data)
        DCLExt.ud_set_params(before)     # reset the change

#### `ud_set_linear_levs(v, options)`

  Set contour levels with a constant interval

  ARGUMENTS

  - v : Data values to be fed to udcnt[rz]

  - options (Hash) : option specification by keys and values. Available options are

        name   default value   description
        'min'      nil       minimum contour value (Numeric)
        'max'      nil       maximum contour value (Numeric)
        'nlev'     nil       number of levels (Integer)
        'interval' nil       contour interval (Numeric)
        'nozero'   nil       delete zero contour (true/false)
        'coloring' false     set color contours with ud_coloring (true/false)
        'clr_min'  13        (if coloring) minimum color id (Integer)
        'clr_max'  100       (if coloring) maximum color id (Integer)

    Here, `interval` has a higher precedence over `nlev`. Since all the default values are nil, only those explicitly specified are interpreted. If no option is provided, the levels generated will be the default ones set by udcnt[rz] without any level specification.

#### `ud_set_contour(levels,index=nil,line_type=nil,label=nil,label_height=nil)`

  Set contours of at specified levels.

  Normally you do not have to specify `label` and `label_height`.

  It calls DCL.udsclv for each level. So the arguments are basically the same as DCL.udsclv, but only levels are mandatory here.

  ARGUMENTS

  - levels (Array, NArray, or Numeric) : contour levels to be set. If Numeric, a single level is set.
  - index (Array of integers, Integer, or nil) : index(es) of the contours. If Array (or NArray), the length must agree with that of `levels`. If it is a single Integer, all the contour will have the same index.

      If nil, the value of 'indxmn' is used.

  - line_type (Array of integers, Integer, or nil) : line type(s) of the contours. If Array (or NArray), the length must agree with that of `levels`. If it is a single Integer, all the contour will have the same type. If nil, set to be 1.
  - label (Array of String, String, true, false, nil) : Label(s) of the contours. If Array (or NArray), the length must agree with that of `levels`. If it is a single String, all the contour will have the same label. If true, all the contours will have the labels representing the levels. If false, no label will be drawn (set to ""). If nil, same as true for the contours whose index is equal to "INDXMJ", and same as false otherwise.
  - label_height (Array of Numeric, Numeric, or nil) : Heigh of Labels. Normally you do not have to use this. If Array (or NArray), the length must agree with that of `levels`. If nil, the default value ("RSIZEL") is used for non-empty labels. If a single Numeric, the same value is used for all the contours. Note that it is recommended to not to use this parameter but use DCL.udpset('RZISEL'. label_height), since a positive value here always means to draw labels even when the label is empty.

  RETURN VALUE

  - nil

#### `ud_add_contour(levels,index=nil,line_type=nil,label=nil,label_height=nil)`

  Same as ud_set_contour, but does not clear the contour levels that have been set.

### uepack

#### `ue_set_params(hash)`

  Calls `DCL.uepset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.

#### `ue_set_linear_levs(v, options)`

  Set tone levels with a constant interval

  ARGUMENTS

  - v : Data values to be fed to udcnt[rz]

  - options (Hash) : option specification by keys and values. Available options are

        name   default value   description
        'min'      nil         minimum tone level (Numeric)
        'max'      nil         maximum tone level (Numeric)
        'nlev'     nil         number of levels (Integer)
        'interval' nil         tone-level interval (Numeric)

    Here, `interval` has a higher precedence over `nlev`. Since all the default values are nil, only those explicitly specified are interpreted. If no option is provided, the levels generated will be the default ones set by udcnt[rz] without any level specification.

#### `ue_set_tone(levels, patterns)`

  Set tone levels and patterns.

  patterns are set between levels as follows:

      when (levels.length == patterns.length+1)

        levels[0]  |  levels[1]  |  levels[2]  ...  |  levels[-2]  |  levels[-1]
               patterns[0]   patterns[1]   ...  patterns[-2]   patterns[-1]

      when (levels.length == patterns.length)

        levels[0]  |  levels[1]  |  levels[2]  ...  |  levels[-1]  |  +infty
               patterns[0]   patterns[1]   ...  patterns[-2]   patterns[-1]

      when (levels.length == patterns.length-1)

        -infty  |  levels[0]  |  levels[1]  ...  |  levels[-1]  |  +infty
            patterns[0]   patterns[1]   ...  patterns[-2]   patterns[-1]

      else
        error (exception raised)

  ARGUMENTS

  - levels (Array or NArray of Numeric) : tone levels. Its length must be either 1 larger than, equal to, or 1 smaller than the length of patterns
  - patterns (Array or NArray of Numeric) : tone patterns

  RETURN VALUE

  - nil

#### `ue_add_tone(levels, patterns)`

  Same as ue_set_tone, but does not clear the tone levels that have been set.

### ugpack

#### `ug_set_params(hash)`

  Calls `DCL.ugpset` multiple times (for each key and val of `hash`). See gl_set_params for usage.

### umpack

#### `um_set_params(hash)`

  Calls `DCL.umpset` multiple times (for each key and val of `hash`).

  See gl_set_params for usage.