../lib/numru/gphys/gphys.rb

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

## 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

  - There is a PROTECTED method grid, which returns the grid object without duplicating.

#### `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.

#### `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

#### `coerce(other)`

  You know what it is.

#### `shape_coerce(other)`

  Like coerce, but just changes shape without changing numeric type.

#### `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, modulo)`

  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)
  - modulo (Numeric)

  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

### Unary operators

#### ~ - +

### Mean etc (instance methods)

#### mean, sum, stddev, min, max, median

### Other instance methods

These methods returns a NArray (not a GPhys).

#### all?, any?, none?, where, where2, floor, ceil, round, to_f, to_i, to_a