# module NumRu::DCLExt

An extension of RubyDCL.

## Index

Original methods

- lon_ax Draw longitude axis. (label format: degrees + 'E' or 'W')
- lat_ax Draw latitude axis. (label format: degrees + 'N' or 'S')
- unit_vect Show the "unit vector", which indicate the vector scaling.
- unit_vect_single Draw a unit vector (only one arrow is drawn).
- set_unit_vect_options Change the default option values for unit_vect.
- next_unit_vect_options Set the option values effective only in the next call of unit_vect
- flow_vect 2D Vector plot. Unlike `DCL::ugvect`, scaling are made in term of the physical (or "U") coordinate.
- flow_vect_anyproj flow_vect available in any coordinate projections
- flow_itr5 2D Vector plot on the 2-dim polar coodinate.
- color_bar Color Bar
- set_color_bar_options
- legend Annotates line/mark type and index (and size if mark).
- quasi_log_levels_z Driver of quasi_log_levels with data values
- quasi_log_levels Returns approximately log-scaled contour/tone levels.

MATH1

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

GRPH1

- sgpack
  - sg_set_params Calls `DCL.sgpset` multiple times (for each key and val of `hash`).
- slpack
  - sl_set_params Calls `DCL.slpset` multiple times (for each key and val of `hash`).
- swpack
  - sw_set_params Calls `DCL.swpset` multiple times (for each key and val of `hash`).

GRPH2

- uzpack
  - uz_set_params Calls `DCL.uzpset` multiple times (for each key and val of `hash`).
- ulpack
  - ul_set_params Calls `DCL.ulpset` multiple times (for each key and val of `hash`).
- ucpack
  - uc_set_params Calls `DCL.ucpset` multiple times (for each key and val of `hash`).
- uupack
  - uu_set_params Calls `DCL.uupset` multiple times (for each key and val of `hash`).
- uspack
  - us_set_params Calls `DCL.uspset` multiple times (for each key and val of `hash`).
- udpack
  - 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.
- uepack
  - 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.
- ugpack
  - ug_set_params Calls `DCL.ugpset` multiple times (for each key and val of `hash`). See gl_set_params for usage.
- umpack
  - um_set_params Calls `DCL.umpset` multiple times (for each key and val of `hash`).

## 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'  99       (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 it is an Array and its length is shorter than that of `levels`, the same Array is repeated (so for instance [1,1,3] is interpreted as [1,1,3,1,1,3,1,1,3,...]). 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 it is an Array and its length is shorter than that of `levels`, the same Array is repeated. 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 it is an Array and its length is shorter than that of `levels`, the same Array is repeated. 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 it is an Array and its length is shorter than that of `levels`, the same Array is repeated. 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.

## Original methods:

### Longitude/Latitude Axes

#### `lon_ax( options=nil )`

  Draw longitude axis. (label format: degrees + 'E' or 'W')

  ARGUMENTS

  - 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:
        "yax"         false   # true => draw y-axis, false => draw x-axis
        "cside"       nil     # "b", "t", "l", "r",
                              # nil (=>left/bottom), or false (=>right/top)
        "dtick1"      nil     # Interval of small tickmark
                              #             (if nil, internally determined)
        "dtick2"      nil     # Interval of large tickmark with labels
                              #             (if nil, internally determined)

#### `lat_ax( options=nil )`

  Draw latitude axis. (label format: degrees + 'N' or 'S')

  ARGUMENTS

  - 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:
        "xax"         false   # true => draw x-axis, false => draw y-axis
        "cside"       nil     # "b", "t", "l", "r",
                              # nil (=>left/bottom), or false (=>right/top)
        "dtick1"      nil     # Interval of small tickmark
                              #             (if nil, internally determined)
        "dtick2"      nil     # Interval of large tickmark with labels
                              #             (if nil, internally determined)

### Vectors

#### `unit_vect( vxfxratio, vyfyratio, fxunit=nil, fyunit=nil, options=nil )`

  Show the "unit vector", which indicate the vector scaling.

  ARGUMENTS

  - vxfxratio (Float) : (V cood length)/(actual length) in x
  - vyfyratio (Float) : (V cood length)/(actual length) in y
  - fxunit (Float) : If specified, x unit vect len
  - fyunit (Float) : If specified, y unit vect len

  - 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:
        "vxunit"      0.05    # x unit vect len in V coord. Used only when
                              # fxunit is omitted (default)
        "vyunit"      0.05    # y unit vect len in V coord. Used only when
                              # fyunit is omitted (default)
        "vxuloc"      nil     # Starting x position of unit vect
        "vyuloc"      nil     # Starting y position of unit vect
        "vxuoff"      0.05    # Specify vxuloc by offset from right-bottom
                              # corner
        "vyuoff"      0.0     # Specify vyuloc by offset from right-bottom
                              # corner
        "inplace"     true    # Whether to print labels right by the unit
                              # vector (true) or below the x axis (false)
        "rsizet"      nil     # Label size(default taken from uz-parameter
                              # 'rsizel1')
        "index"       3       #  Line index of the unit vector
        "help"        false   # show help message if true
        "vertical"    true    # (used only in unit_vect_single) the unit vector
                              # is directed upward if true, to the right if not.

#### `unit_vect_single(vfratio, flen, options=nil )`

  Draw a unit vector (only one arrow is drawn). Suitable to called after flow_vect_anyproj.

  ARGUMENTS

  - vfratio (Numeric) : see flow_vect_anyproj.
  - flen (Numeric) : length of the unit vector
  - options (Hash) : see unit_vect.

#### `set_unit_vect_options(options)`

  Change the default option values for unit_vect.

#### `next_unit_vect_options(options)`

  Set the option values effective only in the next call of unit_vect

#### `flow_vect( fx, fy, factor=1.0, xintv=1, yintv=1)`

  2D Vector plot. Unlike `DCL::ugvect`, scaling are made in term of the physical (or "U") coordinate.

  This method is meant to substitute `DCL::ugvect`. The scaling is made in terms of the U coordinate. This method is suitable to show vectors such as velocity, since the arrow direction represets the direction in the U coordinate. Also, one can re-scale the vector length easily by using the argument `factor`.

  Currently, this method is not compatible with map projection, since it calls `DCL::ugvect` internally.

  ARGUMENTS

  - fx, fy (2D NArray or Array) : the vector field.
  - factor (Integer) : factor to change the arrow length. By default, arrows are scaled so that the longest one match the grid interval.
  - xintv, yintv (Interger) : interval to thin out `fx` and `fy`, respectively. Useful if the grid points are too many.

#### `flow_vect_anyproj(fx, fy, xg, yg, factor=1.0, xintv=1, yintv=1, distvect_map=true, vfratio=nil)`

  flow_vect that can be used under any of the projections supported by DCL. Arrows drawn by this method have lengths proportional to sqrt(fx**2+fy**2), and their directions are properly directed locally (consistent with the local coordinate). A special treatment is made for map projections if distvect_map==true (see below). Singular points of the projection is heuristically handled (see the source code for details).

  ARGUMENTS

  - fx, fy [2D NArray or NArrayMiss] : the vector field.
  - xg, yg [1D (or 2D) NArray] : the grid points
  - factor (Integer) : factor to change the arrow length. By default, arrows are scaled so that the longest one matches the typical grid interval.
  - xintv, yintv (Integer) : interval to thin out `fx` and `fy`, respectively. Useful if the grid points are too many.
  - distvect_map [true/false] : (effective only for map projections) by default (true) it is assumed that the vector (fx,fy) is based on lengths (such as wind velocities in m/s, and fluxes in which wind velocities are incorporated [q*u, q*v]); set it to false if the vector is based on angles (such as the time derivatives of longitude and latitude). When true, a directional correction is made to match the scaling of DCL's window, which is based on angles (longitude and latitude).
  - vfratio [nil or Numeric] : if Numeric, specifies the ratio between the lengths of vectors in the V coordinate and the actual length (sqrt(fx**2+fy**2)). Good to unify the scaling over multiple plots

  RETURN VALUE

  - [ vfratio, flenmax ] :
  - vfratio : see above
  - flenmax : maximum of sqrt(fx**2+fy**2)

#### `flow_itr5( fx, fy, factor=1.0, unit_vect=false )`

  2D Vector plot on the polar coodinate.

  This method just perform rotatation of the vector in U-coordinate to N-coordinate and passed to DCL.ugvect.

  ARGUMENTS

  - fx, fy (2D GPhys) : the vector field.
  - factor (Integer) : factor for scaling in ugvect. When it equals 1, vector field will be scaled in DCL.ugvect automatically.
  - unit_vect() : Show the unit vector

### Color bars

#### `set_color_bar_options(options)`

  To set options of color_bar effective in the rest.

#### `color_bar(options=nil)`

  - Descroption: Draws color bars

  - Example Here is the simplest case, where no argument is given to color_bar.

        DCL.uetone(hoge)
        DCL.usdaxs
        ...
        DCL.color_bar

    This draws a color bar by using the levels and tone patterns(colors) set previously. There are many parameters you can set manually, as introduced below:

  - Description of options

        option name   default value   # description:
        "levels"      nil     # tone levels (if omitted, latest ones are used)
        "patterns"    nil     # tone patterns (~colors) (if omitted, latest
                              # ones are used)
        "voff"        nil     # how far is the bar from the viewport in the V
                              # coordinate
        "vcent"       nil     # center position of the bar in the V coordinate
                              # (VX or VY)
        "vlength"     0.3     # bar length in the V coordinate
        "vwidth"      0.02    # bar width in the V coordinate
        "inffact"     2.25    # factor to change the length of triangle on the
                              # side for infinity (relative to 'vwidth')
        "landscape"   false   # if true, horizonlly long (along x axes)
        "portrait"    true    # if true, vertically long (along y axes)
        "top"         false   # place the bar at the top (effective if
                              # landscape)
        "left"        false   # place the bar in the left (effective if
                              # portrait)
        "units"       nil     # units of the axis of the color bar
        "units_voff"  0.0     # offset value for units from the default position
                              # in the V coordinate (only for 'units' != nil)
        "title"       nil     # title of the color bar
        "title_voff"  0.0     # offset value for title from the default position
                              # in the V coordinate (only for 'title' != nil)
        "tickintv"    1       # 0,1,2,3,.. to specify how frequently the
                              # dividing tick lines are drawn (0: no tick lines,
                              # 1: every time, 2: ever other:,...)
        "labelintv"   nil     # 0,1,2,3,.. to specify how frequently labels are
                              # drawn (0: no labels, 1: every time, 2: ever
                              # other:,... default: internally determined)
        "labels_ud"   nil     # user-defined labels for replacing the default
                              # labels (Array of String)
        "charfact"    0.9     # factor to change the label/units/title character
                              # size (relative to 'rsizel1')
        "log"         false   # set the color bar scale to logarithmic
        "constwidth"  false   # if true, each color is drawn with the same width
        "index"       nil     # line index of tick lines and bar frame
        "charindex"   nil     # line index of labels, units, and title
        "chval_fmt"   nil     # string to specify the DCL.chval format for
                              # labeling
        "help"        false   # show help message if true

### Others

#### `legend(str, type, index, line=false, size=nil, vx=nil, dx=nil, vy=nil, first=true, mark_size=nil)`

Annotates line/mark type and index (and size if mark). By default it is shown in the right margin of the viewport.

- str is a String to show
- line: true->line ; false->mark
- vx: vx of the left-hand point of legend line (or mark position).
  - nil : internally determined
  - Float && > 0 : set explicitly
  - Float && < 0 : move it relatively to the left from the default
- dx: length of the legend line (not used if mark).
  - nil : internally determined
  - Float && > 0 : set explicitly
- vy: vy of the legend (not used if !first -- see below).
  - nil : internally determined
  - Float && > 0 : set explicitly
  - Float && < 0 : move it relatively lower from the default
- first : if false, vy is moved lower relatively from the previous vy.
- mark_size : size of the mark. if nil, size is used.

#### `quasi_log_levels_z(vals, nlev=nil, max=nil, min=nil, cycle=1)`

Driver of quasi_log_levels with data values

#### `quasi_log_levels(lev0, lev1, cycle=1)`

Returns approximately log-scaled contour/tone levels as well as major/minor flags for contours. No DCL call is made in here.

- cycle (Integer; 1, or 2 or 3) : number of level in one-order. e.g. 1,10,100,.. for cycle==1; 1,3,10,30,.. for cycle==2; 1,2,5,10,20,50,.. for cycle==3
- lev0, lev1 (Float) : levels are set between this two params
  - if lev0 & lev1 > 0 : positive only
  - if lev0 & lev1 < 0 : negative only
  - if lev0 * lev1 < 0 : both positive and negative (usig +-[lev0.abs,lev1.abs])

RETURN VALUE:

- [ levels, mjmn ]