module NumRu::GGraph and others in ggraph.rb

Index

module NumRu::GGraph
- margin_info Sets the strings to appear in the bottom margin.
- 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).
- sim_trn? Returns whether the current coordinate transformation is a rectangular curvelinear coordinate.
- polar_coordinate_boundaries Draw boundaries in a polar coordinate.
- map_trn? Returns whether the current coordinate transformation is a map projection.
- map (For map projection) Draws map grid and/or lim and/or coast lines etc.
- set_map Change the default option values for map.
- next_map Set the option values effective only in the next call of map
- line Plot a poly-line by selecting the first dimension (with GPhys#first1D) if gphys is more than 2D.
- mark Similar to line but plots marks instead of drawing a poly-line.
- scatter Scatter diagram (using uumrkz, as in mark).
- color_scatter Scatter diagram colored by values.
- tone_and_contour Calls tone and contour successively.
- contour Contour plot by selecting the first 2 dimensions (with GPhys#first2D) if gphys is more than 3D.
- set_contour Set options for contour in general.
- next_contour Set options for contour in general, which is applied only to the next call.
- 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 GPhys#first2D) if gphys is more than 3D.
- color_bar Color bar
- set_tone_levels Set tone levels for tone explicitly by values.
- set_tone Set options for tone in general.
- next_tone Set options for tone in general, which is applied only to the next call.
- 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.
- vector 2-D vector plot using DCL_Ext::flow_vect

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

margin_info(program=nil, data_source=nil, char_height=nil, date=nil, xl=0.0, xr=0.0, yb=nil, yt=0.0)

Sets the strings to appear in the bottom margin.

This method sets margin widths as DCL.slmgn(xl, xr, yb, yt), and sets the 1st and 2nd margin strings as program and data.

ARGUMENTS

program (String or nil) : String to be put on the left side in the bottom margin. This is meant to represent the name of the execution program. Therefore, if it is nil, the full path of $0 is used.
data_source (String or nil) : String to be put on the right side in the bottom margin. This is meant to represent the data file name or the directory in which the data are situated. If nil, the full path of the current directory is used (but nothing is shown if it is equal to the directory of the program).
date (true, false, nil) : whether to put todays date -- true: always, nil: if program.length is short enough, false: never
char_height (Float or nil) : height of the string to appear in the V coordinate. If nil, internally defined.
xl, xr, yb, yl (Float --- nil is available for yb) : margin size in the V coordinate. The margin is set as DCL.slmgn(xl, xr, yb, yt). If yb is nil, it is determined internally as 2.0 * char_height.

title(string)

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

RETURN VALUE

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

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

Define a figure by setting viewport, window, and coordinate transform id (itr) from two 1D VArrays xax and yax (which are not needed if a map projection is specified with the optional parameter 'itr').

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

ARGUMENTS

xax (VArray): (Used only if not map projection) 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): (Used only if not map projection) 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)
"no_new_fig"  false   # If true, neither DCL.grfrm nor DCL.grfig
                      # is called (overrides new_frame) -- Then, you need
                      # to call one of them in advance. Convenient to set
                      # DCL parameters that are reset by grfrm or grfig.
"itr"         1       # coordinate transformation number
"viewport"    [0.2, 0.8, 0.2, 0.8]    # [vxmin, vxmax, vymin, vymax]
"eqdistvpt"   false   # modify viewport to equidistant for x and y
                      # (only for itr=1--4)
"window"      nil     # (for itr<10,>50) [uxmin, uxmax, uymin, uymax],
                      # each element allowed nil (only for itr<5,>50)
"xreverse"    "positive:down,units:hPa"       # (for itr<10,>50) Assign
                      # max value to UXMIN and min value to UXMAX if
                      # condition is satisfied (nil:never, true:always,
                      # String: when an attibute has the value specified
                      # ("key:value,key:value,..")
"yreverse"    "positive:down,units:hPa"       # (for itr<10,>50) Assign
                      # max value to UYMIN and min value to UYMAX if
                      # condition is satisfied (nil:never, true:always,
                      # String: when an attibute has the value specified
                      # ("key:value,key:value,..")
"round0"      false   # expand window range to good numbers (effective
                      # only to internal window settings)
"round1"      false   # expand window range to good numbers (effective
                      # even when "window" is explicitly specified)
"similar"     nil     # (for rectangular curvilinear coordinate only)
                      # 3-element float array for similar transformation
                      # in a rectangular curvilinear coordinate, which
                      # is fed in DCL:grssim:[simfac,vxoff,vyoff],where
                      # simfac and [vxoff,vyoff] represent scaling
                      # factor and origin shift, respectively.
"map_axis"    nil     # (for all map projections) 3-element float
                      # array to be fed in DCL::umscnt: [uxc, uxy, rot],
                      # where [uxc, uyc] represents the tangential point
                      # (or the pole at top side for cylindrical
                      # projections), and rot represents the rotation
                      # angle. If nil, internally determined. (units:
                      # degrees)
"map_radius"  nil     # (for itr>=20: conical/azimuhal map
                      # projections) raidus around the tangential point.
                      # (units: degrees)
"map_fit"     nil     # (Only for itr=10(cylindrical) and 11 (Mercator))
                      # true: fit the plot to the data window
                      # (overrides map_window and map_axis); false: do
                      # not fit (then map_window and map_axis are used);
                      # nil: true if itr==10, false if itr==11
"map_rsat"    nil     # (Only for itr=30) satellite distance from the
                      # earth's center (Parameter "RSAT" for sgpack)
"map_window"  [-180, 180, -75, 75]    # (for itr<20: cylindrical
                      # map projections) lon-lat window [lon_min,
                      # lon_max, lat_min, lat_max ] to draw the map
                      # (units: degres)
"help"        false   # show help message if true

RETURN VALUE

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

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.

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)
"xtickint"    nil     # Interval of x axis tickmark
                      #                 (if nil, internally determined)
"ytickint"    nil     # Interval of y axis tickmark
                      #                 (if nil, internally determined)
"xlabelint"   nil     # Interval of x axis label
                      #                 (if nil, internally determined)
"ylabelint"   nil     # Interval of y axis label
                      #                 (if nil, internally determined)
"xloglabelall" false  # Show lavels for all log-level tick marks
                      # (x-axes) (e.g.,1000,900,800,... inseatd of
                      # 1000,500,200,...)
"yloglabelall" false  # Show lavels for all log-level tick marks
                      # (y-axes) (e.g.,1000,900,800,... inseatd of
                      # 1000,500,200,...)
"xmaplabel"   nil     # If "lon"("lat"), use
                      # DCLExt::lon_ax(DCLExt::lat_ax) to draw xaxes;
                      # otherwise, DCL::usxaxs is used.
"ymaplabel"   nil     # If "lon"("lat"), use
                      # DCLExt::lon_ax(DCLExt::lat_ax) to draw yaxes;
                      # otherwise, DCL::usyaxs is used.
"time_ax"     nil     # Type of calendar-type time axis: nil (=> auto
                      # slection), false (do not use the time axis even
                      # if the units of the axis is a time one with since
                      # field), "h" (=> like nil, but always use the
                      # hour-resolving datetime_ax method in
                      # dclext_datetime_ax.rb), or "ymd" (=> like "h" but
                      # for y-m-d type using DCL.uc[xy]acl)
"help"        false   # show help message if true

RETURN VALUE

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

POSSIBLE EXCEPTIONS

see axes.

sim_trn?

Returns whether the current coordinate transformation is a rectangular curvelinear coordinate. A coordinate transformation must have been established with fig or DCL::grstrf. Mainly for internal usage, but a user can use it too.

RETURN VALUE

true or false

polar_coordinate_boundaries(xax=nil,yax=nil)

Draw boundaries in a polar coordinate.

ARGUMENTS

xax (VArray): Grid points of the radial coordinate.
yax (VArray): Grid points of the azimuthal coordinate.

RETURN VALUE

map_trn?

Returns whether the current coordinate transformation is a map projection.

A coordinate transformation must have been established with fig or DCL::grstrf. Mainly for internal usage, but a user can use it too.

RETURN VALUE

true or false

map(options=nil)

(For map projection) Draws map grid and/or lim and/or coast lines etc.

ARGUMENTS

option name   default value   # description:
"lim"         true    # draw map lim (t or f)
"grid"        true    # draw map grid (t or f)
"vpt_boundary" false  # draw viewport boundaries (f, t or
                      # 1,2,3.., representing the line width)
"wwd_boundary" false  # draw worksation window boundaries (f, t
                      # or 1,2,3.., representing the line width)
"fill"        false   # fill the map if coast_world or coast_japan is
                      # true (t or f)
"coast_world" false   # draw world coast lines (t or f)
"border_world" false  # draw nation borders (t or f)
"plate_world" false   # draw plate boundaries (t or f)
"state_usa"   false   # draw state boundaries of US (t or f)
"coast_japan" false   # draw japanese coast lines (t or f)
"pref_japan"  false   # draw japanese prefecture boundaries (t or
                      # f)
"dgridmj"     nil     # the interval between the major lines of
                      # latitudes and longitudes. If nil, internally
                      # determined. (units: degrees) (this is a UMPACK
                      # parameter, which is nullified when uminit or
                      # grfrm is called)
"dgridmn"     nil     # the interval between the minor lines of
                      # latitudes and longitudes. If nil, internally
                      # determined. (units: degrees) (this is a UMPACK
                      # parameter, which is nullified when uminit or
                      # grfrm is called)
"help"        false   # show help message if true

RETURN VALUE

POSSIBLE EXCEPTIONS

if called when the coordinate tansformation has not been established or the transformation is not a map projection.
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_map(options)

Change the default option values for map.

ARGUMENTS

options (Hash) : The usage is the same as options for map.

RETURN VALUE

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

POSSIBLE EXCEPTIONS

see map.

next_map(options)

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

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

ARGUMENTS

options (Hash) : The usage is the same as options for map.

RETURN VALUE

POSSIBLE EXCEPTIONS

see map.

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

Plot a poly-line by selecting the first dimension (with GPhys#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).

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
"label"       nil     # if a String is given, it is shown as the label
"max"         nil     # maximum data value
"min"         nil     # minimum data value
"legend"      nil     # legend to annotate the line type and index. nil
                      # (defalut -- do not show); a String as the legend;
                      # true to use the name of the GPhys as the legend
"legend_vx"   nil     # (effective if legend) viewport x values of
                      # the lhs of the legend line (positive float); or
                      # nil for automatic settting (shown to the right of
                      # vpt); or move it to the left relatively (negtive
                      # float)
"legend_dx"   nil     # (effective if legend) length of the legend
                      # line
"legend_vy"   nil     # (effective if legend) viewport y value of the
                      # legend (Float; or nil for automatic settting)
"legend_size" nil     # (effective if legend) character size of the
                      # legend
"map_axes"    false   # [USE IT ONLY WHEN itr=10 (cylindrical)] If
                      # true, draws axes by temprarilly switching to
                      # itr=1 and calling GGraph::axes.
"slice"        nil    # An Array to be pathed to the GPhys#[] method to
                      # subset the data before plotting (order applied:
                      # slice -> cut -> mean)
"cut"          nil    # An Array or Hash to be pathed to the GPhys#cut
                      # method to subset the data before plotting (order
                      # applied: slice -> cut -> mean)
"mean"         nil    # An Array to be pathed to the GPhys#mean method to
                      # take mean of the data before plotting (order
                      # applied: slice -> cut -> mean)
"help"        false   # show help message if true

RETURN VALUE

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).

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
"max"         nil     # maximum data value
"min"         nil     # minimum data value
"legend"      nil     # legend to annotate the mark type, index, and
                      # size. nil (defalut -- do not to show); a String
                      # as the legend; true to use the name of the GPhys
                      # as the legend
"legend_vx"   nil     # (effective if legend) viewport x values of
                      # the lhs of the legend line (positive float); or
                      # nil for automatic settting (shown to the right of
                      # vpt); or move it to the left relatively (negtive
                      # float)
"legend_vy"   nil     # (effective if legend) viewport y value of the
                      # legend (Float; or nil for automatic settting)
"legend_size" nil     # (effective if legend) character size of the
                      # legend
"map_axes"    false   # [USE IT ONLY WHEN itr=10 (cylindrical)] If
                      # true, draws axes by temprarilly switching to
                      # itr=1 and calling GGraph::axes.
"slice"        nil    # An Array to be pathed to the GPhys#[] method to
                      # subset the data before plotting (order applied:
                      # slice -> cut -> mean)
"cut"          nil    # An Array or Hash to be pathed to the GPhys#cut
                      # method to subset the data before plotting (order
                      # applied: slice -> cut -> mean)
"mean"         nil    # An Array to be pathed to the GPhys#mean method to
                      # take mean of the data before plotting (order
                      # applied: slice -> cut -> mean)
"help"        false   # show help message if true

RETURN VALUE

scatter(fx, fy, newframe=true, options=nil)

Scatter diagram (using uumrkz, as in mark).

ARGUMENTS

fx, fy (GPhys) : x and y locations.
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.

option name  default value  # description:
"title"      ""       # Title of the figure(if nil, internally determined)
"annotate"   true     # if false, do not put texts on the right
                      # margin even when newframe==true
"index"      1        # mark index
"type"   2            # mark type
"size"   0.01         # marks size
"map_axes" false      # [USE IT ONLY WHEN itr=10 (cylindrical)] If
                      # true, draws axes by temprarilly switching to
                      # itr=1 and calling GGraph::axes.
"xintv"  1            # interval of data sampling in x
"yintv"  1            # interval of data sampling in y
"slice"  nil          # An Array to be pathed to the GPhys#[] method to
                      # subset the data before plotting (order applied:
                      # slice -> cut -> mean)
"cut"    nil          # An Array or Hash to be pathed to the GPhys#cut
                      # method to subset the data before plotting (order
                      # applied: slice -> cut -> mean)
"mean"   nil          # An Array to be pathed to the GPhys#mean method to
                      # take mean of the data before plotting (order
                      # applied: slice -> cut -> mean)
"help"   false        # show help message if true

color_scatter(fx, fy, fz, newframe=true, options=nil)

Scatter diagram colored by values.

Coloring is made with respoect to fz just like in (<<tone>>). You can draw a color bar by calling (<<color_bar>>) after calling this method.

ARGUMENTS

fx, fy (GPhys) : x and y locations.
fz (GPhys) : value on which colors are based.
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.

option name  default value  # description:
"title"      ""       # Title of the figure(if nil, internally determined)
"annotate"   true     # if false, do not put texts on the right
                      # margin even when newframe==true
"index"      3        # mark index (1-9)
"type"   10           # mark type
"size"   0.01         # marks size
"map_axes" false      # [USE IT ONLY WHEN itr=10 (cylindrical)] If
                      # true, draws axes by temprarilly switching to
                      # itr=1 and calling GGraph::axes.
"clr_min"  nil        # if an integer (in 10..99) is specified, used as
                      # the color number for the minimum data values.
                      # (the same can be done by setting the uepack
                      # parameter "icolor1")
"clr_max"  nil        # if an integer (in 10..99) is specified, used as
                      # the color number for the maximum data values.
                      # (the same can be done by setting the uepack
                      # parameter "icolor2")
"keep"	false        # Use the tone levels and patterns used previously
"min"	nil          # minimum tone level
"max"	nil	     # maximum tone level
"nlev"	nil	     # number of levels
"interval"	nil  # contour interval
"help"	false        # show help message if true
"log"	nil	     # approximately log-scaled levels (by using
                      # DCLExt::quasi_log_levels)
"log_cycle"	3    # (if log) number of levels in one-order (1 or 2
                      # or 3)
"levels"	nil	     # tone levels  (Array/NArray of Numeric). Works
                      # together with patterns
"patterns"   nil  # Similar to the pattern option in (<<tone>>)),
                  # but here only the color part (4th and 5th 
                  # digitgs) is used. -- e.g, pattern 38999
                  # --> color 38.
"xintv"  1            # interval of data sampling in x
"yintv"  1            # interval of data sampling in y
"slice"  nil          # An Array to be pathed to the GPhys#[] method to
                      # subset the data before plotting (order applied:
                      # slice -> cut -> mean)
"cut"    nil          # An Array or Hash to be pathed to the GPhys#cut
                      # method to subset the data before plotting (order
                      # applied: slice -> cut -> mean)
"mean"   nil          # An Array to be pathed to the GPhys#mean method to
                      # take mean of the data before plotting (order
                      # applied: slice -> cut -> mean)
"help"   false        # show help message if true

add_mode_vectors(mean, modes, options)

This method overlays mode vectors on scatter plots. Call this method after scatter / color_scatter.

ARGUMENTS

mean : this determines the center of vectors
modes : two dimensional mode vectors (e.g. EOF modes) of the shape [2,2], [2,1], or [2].
```
the first mode is modes[true,0] and the second mode is modes[true,1].
```

options (Hash) : options to change the default behavior if specified.

option name  default value  # description:
'lineindex'  1              # line index
'linetype'   1              # line type
'fact'       2              # scaling factor (line length = stddev * fact for each side)
'style'      'line'         # style of displaying modes (line, arrow, ellipse)

tone_and_contour(gphys, newframe=true, options=nil)

Calls tone and contour successively. You can specify the options for any of these.

NOTE:

The option keys that are not existent in these methods are simply neglected -- thus no spell-check-like feedback is made, contrary to the indivisual call of contour or tone. Also, only the help menu of tone can be shown.
Requires numru-misc-0.0.6 or later.

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

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

Contour levels are determined as follows:

contour levels are set in this method if not set by set_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 (or map), title, and annotate internally; if false, only the poly-line is drawn (overlaid to the exiting figure).

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
"transpose"   false   # if true, exchange x and y axes
"exchange"    false   # same as the option transpose
"map_axes"    false   # [USE IT ONLY WHEN itr=10 (cylindrical)] If
                      # true, draws axes by temprarilly switching to
                      # itr=1 and calling GGraph::axes.
"keep"        false   # Use the contour levels used previously
"min"         nil     # minimum contour level
"max"         nil     # maximum contour level
"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 number for the
                      # minimum data values
"clr_max"     99      # (if coloring) maximum color number for the
                      # maximum data values
"help"        false   # show help message if true
"log"	     nil     # approximately log-scaled levels (by using
                      # DCLExt::quasi_log_levels)
"log_cycle"   3       # (if log) number of levels in one-order (1 or 2
                      # or 3)
"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.
"xintv"        1      # interval of data sampling in x
"yintv"        1      # interval of data sampling in y
"xcoord"       nil    # Name of the coordinate variable for x-axis
"ycoord"       nil    # Name of the coordinate variable for y-axis
"slice"        nil    # An Array to be pathed to the GPhys#[] method to
                      # subset the data before plotting (order applied:
                      # slice -> cut -> mean)
"cut"          nil    # An Array or Hash to be pathed to the GPhys#cut
                      # method to subset the data before plotting (order
                      # applied: slice -> cut -> mean)
"mean"         nil    # An Array to be pathed to the GPhys#mean method to
                      # take mean of the data before plotting (order
                      # applied: slice -> cut -> mean)

RETURN VALUE

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 GPhys#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 the option "levels" (and optionally, "patterns") is (are) specified explicitly.
When contour levels & patterns are set in this method,
- "levels" has the highest precedence. If it is specified, tone levels and patterns are determined by DCLExt::ue_set_tone. Here, tone patterns can be specified with the option "patterns".
- Currently, option "patterns" is effective only if "levels" is specified. Otherwise, it is ignored and patterns are determined internally (by using DCL.uegtlb).
- 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 (or map), title, and annotate internally; if false, only the poly-line is drawn (overlaid to the exiting figure).

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
"tonf"        false   # Use DCL.uetonf instead of DCL.uetone
"tonb"        false   # Use DCL.uetonb instead of DCL.uetone
"tonc"        false   # Use DCL.uetonc instead of DCL.uetone
"clr_min"     nil     # if an integer (in 10..99) is specified, used as
                      # the color number for the minimum data values.
                      # (the same can be done by setting the uepack
                      # parameter "icolor1")
"clr_max"     nil     # if an integer (in 10..99) is specified, used as
                      # the color number for the maximum data values.
                      # (the same can be done by setting the uepack
                      # parameter "icolor2")
"transpose"   false   # if true, exchange x and y axes
"exchange"    false   # same as the option transpose
"map_axes"    false   # [USE IT ONLY WHEN itr=10 (cylindrical)] If
                      # true, draws axes by temprarilly switching to
                      # itr=1 and calling GGraph::axes.
"keep"        false   # Use the tone levels and patterns used previously
"color_bar"   false   # Add a color bar: THIS IS ONLY FOR QUICK
                      # LOOK. Use the GGraph::color_bar method explicitly
                      # for full option control
"min"         nil     # minimum tone level
"max"         nil     # maximum tone level
"nlev"        nil     # number of levels
"interval"    nil     # contour interval
"help"        false   # show help message if true
"log"	     nil     # approximately log-scaled levels (by using
                      # DCLExt::quasi_log_levels)
"log_cycle"   3       # (if log) number of levels in one-order (1 or 2
                      # or 3)
"levels"      nil     # tone levels  (Array/NArray of Numeric). Works
                      # together with patterns
"patterns"    nil     # tone patters (Array/NArray of Numeric). Works
                      # together with levels
"xintv"        1      # interval of data sampling in x
"yintv"        1      # interval of data sampling in y
"xcoord"       nil    # Name of the coordinate variable for x-axis
"ycoord"       nil    # Name of the coordinate variable for y-axis
"slice"        nil    # An Array to be pathed to the GPhys#[] method to
                      # subset the data before plotting (order applied:
                      # slice -> cut -> mean)
"cut"          nil    # An Array or Hash to be pathed to the GPhys#cut
                      # method to subset the data before plotting (order
                      # applied: slice -> cut -> mean)
"mean"         nil    # An Array to be pathed to the GPhys#mean method to
                      # take mean of the data before plotting (order
                      # applied: slice -> cut -> mean)

RETURN VALUE

color_bar (options=nil)

Descroption: Draws color bars. Calls DCLext.color_bar.

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.

set_unit_vect_options(options)

next_unit_vect_options(options)

vector(fx, fy, newframe=true, options=nil)

2-D vector plot using DCL_Ext::flow_vect, which scales vectors in physical ("U") coordinates.

ARGUMENTS

fx, fy (GPhys) : represent vectors
newframe (true/false) : if true, calls fig, axes (or map), title, and annotate internally; if false, only the poly-line is drawn (overlaid to the exiting figure).

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
"transpose"   false   # if true, exchange x and y axes
"exchange"    false   # same as the option transpose
"map_axes"    false   # [USE IT ONLY WHEN itr=10 (cylindrical)] If
                      # true, draws axes by temprarilly switching to
                      # itr=1 and calling GGraph::axes.
"flow_vect"   true    # If true, use DCLExt::flow_vect to draw
                      # vectors; otherwise, DCL::ugvect is used.
"flow_itr5"   false   # If true, use DCLExt::flow_itr5 to draw
                      # vectors; otherwise, DCLExt::flow_vect or
                      # DCL::ugvect is used.
"keep"        false   # Use the same vector scaling as in the previous
                      # call. -- Currently, works only when "flow_vect"
                      # is true
"xintv"       1       # (Effective only if flow_vect) interval of data
                      # sampling in x
"yintv"       1       # (Effective only if flow_vect) interval of data
                      # sampling in y
"factor"      1.0     # (Effective only if flow_vect) scaling factor to
                      # strech/reduce the arrow lengths
"unit_vect"   false   # Show the unit vector
"max_unit_vect"       false   # (Effective only if flow_vect &&
                      # unit_vect) If true, use the maximum arrows to
                      # scale the unit vector; otherwise, normalize in V
                      # coordinate.
"ux_unit"     nil     # (If Numeric) length of the x direction unit
                      # vector (precedence of this option is lower than
                      # max_unit_vect)
"uy_unit"     nil     # (If Numeric) length of the y direction unit
                      # vector (precedence of this option is lower than
                      # max_unit_vect)
"help"        false   # show help message if true
"xcoord"       nil    # Name of the coordinate variable for x-axis
"ycoord"       nil    # Name of the coordinate variable for y-axis
"slice"        nil    # An Array to be pathed to the GPhys#[] method to
                      # subset the data before plotting (order applied:
                      # slice -> cut -> mean)
"cut"          nil    # An Array or Hash to be pathed to the GPhys#cut
                      # method to subset the data before plotting (order
                      # applied: slice -> cut -> mean)
"mean"         nil    # An Array to be pathed to the GPhys#mean method to
                      # take mean of the data before plotting (order
                      # applied: slice -> cut -> mean)

RETURN VALUE

set_regression_line(options)

Change the default option values for regression_line.

ARGUMENTS

options (Hash) : The usage is the same as options for regression_line.

RETURN VALUE

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

next_regression_line(options)

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

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

ARGUMENTS

options (Hash) : The usage is the same as options for regression_line.

RETURN VALUE

regression_line(x,y, options=nil)

Draw a linear regression line in the current viewport.

A figure must have been drawn. Good to call after scatter or color_scatter. You can also use this method after any scatter plot (passively under non-GPhys environment), since the argument x,y can be NArray etc unlike other draw methods in GGraph.

ARGUMENTS

x, y (GPhys or VArray or NArray or NArrayMiss or Array) : x and y values

option name      default value	# description:
"x_given_y"   false   # If false (default), regress y for given x.
                      # If true, x given y.
"annot_slope"  nil    # Whether to show the slope on the right
                      # margin. nil: show when itr=1,4, do not show when
                      # itr=2,3; true: show; false: not show
"annot_intercept" false # [Meaningful only when itr=1 (linear
                      # scaling plot)] if true, show the intercept on the
                      # right margin
"limit"      false    # If true, regression line is shown only over the
                      # range between max and min of the independent
                      # variable. If false, regression line is written
                      # over the whole range of the independent variable
"clip"        true    # If true, use DCL's clipping not to show the line
                      # outside the viewport
"index"          1    # line index
"type"           1    # line type
"help"       false    # show help message if true