class NumRu::GPhys

Class Methods

GPhys.new(grid, data)

Constructor.

ARGUMENTS

grid (a Grid) : the grid
data (a VArray) : the data. grid and data must have the same shape.

RETURN VALUE

a GPhys

NOTE

the arguments are NOT duplicated to construct a GPhys.

GPhys.each_along_dims(gphyses, *loopdims){...} # a block is expected

Iterator to process GPhys objects too big to read on memory at once.

Makes a loop (loops) by dividing the GPhys object(s) (gphyses) with the dimension(s) specified by loopdims. If the return value of the block is an Array, it is assumed to consist of GPhys objects, and the return value of this method is an Array in which the whole of the results are reconstructed as if no iteration is made, which is the same behavior as GPhys::IO.each_along_dims_write. If the return value of the block is not an Array, this methods returns nil.

WARNING: Unlike GPhys::IO.each_along_dims_write, the results of this method is NOT written in file(s), so be careful about memory usage if you put an Array of GPhys as the return value of the block. You will probably need to have the size of them smaller than input data.

ARGUMENTS

gphyses (GPhys or Array of GPhys): GPhys object(s) to be processed. All of them must have dimensions specified with loopdims, and their lengths must not vary among files. Other dimensions are arbitrary, so, for example, gphyses could be [a(lon,lat,time), b(lat,time)] as long as loopdims==["time"].
loopdims (Array of String or Integer) : name (when String) or count starting from zero (when Integer)
expected block : Number of arguments == number of GPhys objects in gphyses.

RETURN VALUE

If the return value of the block is an Array, GPhys objects in which the whole results are written in (the Array must consist of GPhys objects). If the return value of the block is NOT an Array, nil is returned.

ERRORS

The following raise exceptions (in addition to errors in arguments).

Dimensions specified by loopdims are not shared among GPhys objects in gphyses.
Return value of the block is an Array, but it does not consist of GPhys objects.
(Only when the return value of the block is an Array): Dimension(s) used for looping (loopdims) is(are) eliminated from the returned GPhys objects.

USAGE

See the manual of GPhys::IO.each_along_dims_write.

GPhys.join_md_nocheck(gpnary)

Join multiple GPhys objects that are ordered perfectly in a NArray.

LIMITATION (as of 2013-03-04)

joining assoc_coords is yet to be supported; Currently assoc_coords are ignored if any.

ARGUMENT

gpnarray [NArray of GPhys] having the same rank with that of its component GPhys objects. multiple GPhys objects are joined along the dimension with multiple elements (the order is kept).

RETURN VALUE

a GPhys

GPhys.join_md(gpnary)

Join multiple GPhys objects (ordered in a NArray).

Like GPhys.join_md_nocheck but it supports insersion of omitted 1-element dimensions and transpose for gpnary (the input NArray). It means that the rank of gpnary can be smaller than that of its compoent GPhys objects, and the order of dimensions can be arbitrary. Also, the order of coordinate values along each dimension does not have to be monotonic; the method supports sorting and spliting along dimensions. For example, if gpnary == NArray.object(2):[gp0, gp1], where the first object gp0 has the 1st coordinate [0,1,7,8] and the second object gp1 has the 1st coordinate [3,4,5,6], gpnary is restructured as [ gp0[0..1,false], gp1, gp0[2..3,false] ], and join is made by using GPhys.join_md_nocheck.

This method is generally faster than GPhys.join unless the split is one-dimensional.

ARGUMENT

gpnarray [NArray of GPhys]

RETURN VALUE

a GPhys

GPhys.join(gpary)

Join multiple GPhys objects (no need for any pre-ordering).

ARGUMENT

gpnarray [Array (or 1D NArray) of GPhys]

RETURN VALUE

a GPhys

GPhys.concat(gpary, axis_or_ary, name=nil, attr=nil)

Concatenate an Array (or 1D NArray) of GPhys objects along the new dimension specified by the 2nd to 4th arguments. The rank of the result (a GPhys) is one plus the rank of the GPhys objects.

ARGUMENTS

gpary [1D NArray or Array of GPhys]
axis_or_ary [an Axis or a 1D NArray or Array of floats]
name [String; optional] name of the coordinate; needed if axis_or_ary is not an Axis.
attr [Hash; optional] attributes of the coordinate; used if axis_or_ary is not an Axis.

RETURN VALUE

a GPhys

Instance Methods

data

Returns the data object

RETURN VALUE

a VArray

NOTE

the data object is NOT duplicated.

grid_copy

Returns a copy (deep clone) of the grid object.

RETURN VALUE

a Grid

NOTE

grid does not make a copy.

grid

Returns the grid object without copying.

RETURN VALUE

a Grid

NOTE

Use grid_copy to avoid side effects

copy

Make a deep clone onto memory

RETURN VALUE

a GPhys

name

Returns the name of the GPhys object, which is equal to the name of the data object in the GPhys object.

RETURN VALUE

a String

name=(nm)

Set the name of the GPhys object.

ARGUMENTS

nm (String)

RETURN VALUE

nm (the argument)

rename(nm)

Same as name=, but self is returned.

ARGUMENTS

nm (String)

RETURN VALUE

self

val

Returns data values

RETURN VALUE

a NArray or NArrayMiss. It is always a copy and to write in it will not affect self.

val=(v)

Writes in data values.

ARGUMENTS

v (NArray, NArrayMiss, or Numeric) : data to be written in.

RETURN VALUE

v (the argument)

NOTE

the contents of v are copied in, unlike replace_val

replace_val(v)

Replace the data values.

ARGUMENTS

v (NArray or NArrayMiss) : data to be written in.

RETURN VALUE

self

NOTE

This method is similar to val=, but the whole numeric data object is replaced with v. It is not very meaningful if the data is in a file: the file is not modified, but you just get an GPhys object on memory.

att_names

Returns attribute names of the data object.

RETURN VALUE

Array of String

get_att(name)

Get the value of the attribute named name.

ARGUMENTS

name (String)

RETURN VALUE

String, NArray, or nil

set_att(name, val)

put_att(name, val)

Set an attribute of the data object

ARGUMENTS

name (String)
val (String, NArray, or nil)

RETURN VALUE

self

del_att(name)

Delete an attribute of the data object.

ARGUMENTS

name (String)

RETURN VALUE

self

ntype

Returns the numeric type of the data object.

RETURN VALUE

String such as "float", and "sfloat"

NOTE

See also typecode.

typecode

Returns the numeric type of the data object.

RETURN VALUE

NArray constants such as NArray::FLOAT and NArray::SFLOAT.

NOTE

See also ntype.

units

Returns the units of the data object

RETURN VALUE

a Units

units=(units)

Changes the units of the data object

ARGUMENTS

units (Units or String)

RETURN VALUE

units (the argument)

convert_units(to)

Convert the units of the data object

ARGUMENTS

to (a Units)

RETURN VALUE

a GPhys

long_name

Returns the "long_name" attribute the data object

RETURN VALUE

a String

long_name=(to)

Changes/sets the "long_name" attribute the data object

ARGUMENTS

to (a String)

RETURN VALUE

to (the argument)

[]

Returns a subset.

ARGUMENTS

Same as those for NArray#[], NetCDFVar#[], etc.

RETURN VALUE

a GPhys

[] =

Sets values of a subset

RETURN VALUE

the data object on the rhs

cut

Similar to [], but the subset is specified by physical coordinate.

ARGUMENTS

pattern 1: similar to those for [], where the first argument specifies a subset for the first dimension.
pattern 2: by a Hash, in which keys are axis names.

EXAMPLES

Pattern 1
```
gphys.cut(135.5,0..20.5,false)
```
Pattern 2
```
gphys.cut({'lon'=>135.5,'lat'=>0..20})
```

RETURN VALUE

a GPhys

cut_rank_conserving

Similar to cut, but the rank is conserved by not eliminating any dimension (whose length could be one).

axnames

Returns the names of the axes

RETURN VALUE

an Array of String

rank

Returns the rank

RETURN VALUE

an Integer

axis(dim)

Returns the Axis object of a dimension.

ARGEMENTS

dim (Integer or String)

RETURN VALUE

an Axis

coord(dim)

coordinate(dim)

Returns the coordinate variable

ARGUMENTS

dim (Integer or String)

RETURN VALUE

a VArray

NOTE

coord(dim) is equivalent to axis(dim).pos

lost_axes

Returns info on axes eliminated during operations.

Useful for annotation in plots, for example (See the code of GGraph for an application).

RETURN VALUE

an Array of String

dim_index( dimname )

Returns the integer id (count from zero) of the dimension

ARGUMENT

dimname (String or Integer) : this method is trivial if is is an integer

RETURN VALUE

an Integer

integrate(dim)

Integration along a dimension.

RETURN VALUE

a GPhys

NOTE

Algorithm implementation is done in Axis class.

average(dim)

Averaging along a dimension.

RETURN VALUE

a GPhys

NOTE

Algorithm implementation is done in Axis class.

eddy(*dim)

Deviation from mean

ARGUMENT

a list of dimensions (including none) [Integer or String] along which the mean is taken.

RETURN VALUE

a GPhys

NOTE

Simply defined as

def eddy(*dim)
  self - self.mean(*dim)
end

first1D

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

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, ...]. (For graphics)

ARGUMENTS

(none)

RETURN VALUE

a GPhys

first3D

Returns a 3D subset selecting the first elements of 4th, 5th, .. dimensions, i.e., self[true, true, true, 0, ...]. (For graphics)

ARGUMENTS

(none)

RETURN VALUE

a GPhys

coerce(other)

You know what it is.

shape_coerce(other)

Like coerce, but just changes shape without changing numeric type by possibly inserting dimensions whose lengths are one (i.e., without changeing the total length of data).

shape_coerce_full(other)

Similar to shape_coerce but to return the gphyses having really the same shape with possible expansion by replication.

transpose(*dims)

Transpose.

ARGUMENTS

dims (integers) : for example, [1,0] to transpose a 2D object. For 3D objects, [1,0,2], [2,1,0], etc.etc.

RETURN VALUE

a GPhys

shape_current

Returns the current shape of the GPhys object.

RETURN VALUE

an Array of Integer

shape

Aliased to shape_current

cyclic_ext(dim_or_dimname)

Extend a dimension cyclically.

The extension is done only when adding one grid point makes a full circle. Thus, data at coordinate values [0,90,180,270] with modulo 360 are extended (to at [0,90,180,270,360]), but data at [0,90,180] are not extended with the same modulo: in this case, self is returned.

ARGUMENTS

dim_or_dimname (String or Integer)

RETURN VALUE

a GPhys (possibly self)

Math functions (instance methods)

sqrt, exp, log, log10, log2, sin, cos, tan, sinh, cosh, tanh, asin, acos, atan, asinh, acosh, atanh, csc, sec, cot, csch, sech, coth, acsc, asec, acot, acsch, asech, acoth

Binary operators

-, +, *, /, %, **, .add!, .sub!, .mul!, .div!, mod!, >, >=, <, <=, &, |, ^, .eq, .ne, .gt, .ge, .lt, .le, .and, .or, .xor, .not

gp00.set_assoc_coords([GPhys.new(Grid.new(xax0,yax0),VArray.new(x,nil,"A"))])
gp10.set_assoc_coords([GPhys.new(Grid.new(xax1,yax0),VArray.new(x,nil,"A"))])
gp01.set_assoc_coords([GPhys.new(Grid.new(xax0,yax1),VArray.new(x,nil,"A"))])
gp11.set_assoc_coords([GPhys.new(Grid.new(xax1,yax1),VArray.new(x,nil,"A"))])