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

# class NumRu::VArray

VArray is a Virtual Array class, in which a multi-dimensional array data is stored on memory (NArray, NArrayMiss) or in file (NetCDFVar etc). The in-file data handling is left to subclasses such as VArrayNetCDF, and this base class handles the following two cases:

1. Data are stored on memory using NArray
2. Subset of another VArray (possibly a subclass such as VArrayNetCDF).

Perhaps the latter case needs more explanation. Here, a VArray is defined as a subset of another VArray, so the current VArray has only the link and info on how the subset is mapped to the other VArray.

A VArray behaves just like a NArray, i.e., a numeric multi-dimensional array. The important difference is that a VArray has a name and can have "attributes" like a NetCDF variable. Therefore, VArray can perfectly represent a NetCDFVar, which is realized by a sub-class VArrayNetCDF.

NOMENCLATURE

- value(s): The multi-dimensional numeric array contained in the VArray, or its contents
- attribute(s): A combination of name and data that describes a VArray. Often realized by NumRu::Attribute class (or it is a NetCDFAttr in VArrayNetCDF). The name must be a string, and the type of attribute values is restricted to a few classes for compatibility with NetCDFAttr (See NumRu::Attribute)

## Class Methods

#### `VArray.new(narray=nil, attr=nil, name=nil)`

  A constructor

  ARGUMENTS

  - narray (NArray or NArrayMiss; default:nil) The array to be held. (nil is used to initialize a mapping to another VArray by a protected method).
  - attr (NumRu::Attribute; default:nil) Attributes. If nil, an empty

      attribute object is created and stored.

  - name (String; default nil) Name of the VArray. If nil, it is named "noname".

  RETURN VALUE

  - a VArray

  EXAMPLE

      na = NArray.int(6,3).indgen!
      va1 = VArray.new( na, nil, "test" )

#### `VArray.new2(ntype, shape, attr=nil, name=nil)`

  Another constructor. Uses parameters to initialize a NArray to hold.

  ARGUMENTS

  - ntype (String or NArray constants): Numeric type of the NArray to be held (e.g., "sfloat", "float", NArray::SFLOAT, NArray::FLOAT)
  - shape (Array of Integers): shape of the NArray
  - attr (Attribute; default:nil) Attributes. If nil, an empty attribute object is created and stored.
  - name (String; default nil) Name of the VArray.

  RETURN VALUE

  - a VArray

## Instance Methods

#### `val`

  Returns the values as a NArray (or NArrayMiss).

  This is the case even when the VArray is a mapping to another. Also, this method is to be redefined in subclasses to do the same thing.

  ARGUMENTS -- none

  RETURN VALUE

  - a NArray (or NArrayMiss)

#### `val=(narray)`

  Set values.

  The whole values are set. If you want to set partly, use []=. In this method, values are read from narray and set into the internal value holder. Thus, for exampled, the numeric type is not changed regardress the numeric type of narray. Use replace_val to replace entirely with narray.

  ARGUMENTS

  - narray (NArray or NArrayMiss or Numeric): If Numeric, the whole values are set to be equal to it. If NArray (or NArrayMiss), its shape must agree with the shape of the VArray.

#### `replace_val(narray)`

  Replace the internal array data with the object narray. Use val= if you want to copy the values of narray.

  ARGUMENTS

  - narray (NArray or NArrayMiss): as pxlained above. Its shape must agree with the shape of the VArray (self).

  RETURN VALUE

  - if (self.class == VArray), self; otherwise (if self.class is a subclass of VArray), a new VArray.

#### `[]`

  Get a subset. Its usage is the same as NArray#[]

#### `[] =`

  Set a subset. Its usage is the same as NArray#[]=

#### `attr`

  To be undefined.

#### `ntype`

  Returns the numeric type.

  ARGUMENTS -- none

  RETURN VALUE

  - a String ("byte", "sint", "int", "sfloat", "float", "scomplex" "complex", or "obj"). It can be used in NArray.new to initialize another NArray.

#### `rank`

  Returns the rank (number of dimensions)

#### `shape`

  Returns the shape

#### `shape_current`

  aliased to shape.

#### `length`

  Returns the length of the VArray

#### `typecode`

  Returns the NArray typecode

#### `name`

  Returns the name

  RETURN VALUE

  - (String) name of the VArray

#### `name=(nm)`

  Changes the name.

  ARGUMENTS

  - nm(String): the new name.

  RETURN VALUE

  - nm

#### `rename!(nm)`

  Changes the name (Same as name=, but returns self)

  ARGUMENTS

  - nm(String): the new name.

  RETURN VALUE

  - self

#### `rename(nm)`

  Same as rename! but duplicate the VArray object and set its name.

  This method may not be supported in sub-classes, since it is sometimes problematic not to change the original.

#### `copy(to=nil)`

  Copy a VArray. If to is nil, works as the deep cloning (duplication of the entire object).

  Both the values and the attributes are copied.

  ARGUMENTS

  - to (VArray (possibly a subclass) or nil): The VArray to which the copying is made.

#### `reshape!( *shape )`

  Changes the shape without changing the total size. May not be available in subclasses.

  ARGUMENTS

  - shape (Array of Integer): new shape

  RETURN VALUE

  - self

  EXAMPLE

      vary = VArray.new2( "float", [10,2])
      vary.reshape!(5,4)   # changes the vary
      vary.copy.reshape!(2,2,5)  # make a deep clone and change it
            # This always works with a VArray subclass, since vary.copy
            # makes a deep clone to VArray with NArray.

#### `file`

  Returns a file object if the data of the VArray is in a file, nil if it is on memory

  ARGUMENTS

  - none

  RETURN VALUE

  - an object representing the file in which data are stored. Its class depends on the file type. nil is returned if the data is not in a file.

#### `transpose(*dims)`

  Transpose. Argument specification is as in NArray.

#### `reshape(*shape)`

  Reshape. Argument specification is as in NArray.

#### `axis_draw_positive`

  Returns the direction to plot the axis (meaningful only if self is a coordinate variable.)

  The current implementation is based on NetCDF conventions, so REDEFINE IT IN SUBCLASSES if it is not appropriate.

  RETURN VALUE

  - one of the following:
    - true: axis should be drawn in the increasing order (to right/upward)
    - false: axis should be drawn in the decreasing order
    - nil: not specified

#### `axis_cyclic?`

  Returns whether the axis is cyclic (meaningful only if self is a coordinate variable.)

  The current implementation is based on NetCDF conventions, so REDEFINE IT IN SUBCLASSES if it is not appropriate.

  RETURN VALUE

  - one of the following:
    - true: cyclic
    - false: not cyclic
    - nil: not specified

#### `axis_modulo`

  Returns the modulo of a cyclic axis (meaningful only if self is a coordinate variable and it is cyclic.)

  The current implementation is based on NetCDF conventions, so REDEFINE IT IN SUBCLASSES if it is not appropriate.

  RETURN VALUE

  - one of the following:
    - Float if the modulo is defined
    - nil if modulo is not found

#### `coerce(other)`

  For Numeric operators. (If you do not know it, see a manual or book of Ruby)

## Methods compatible with NArray

VArray is a numeric multi-dimensional array, so it supports most of the methods and operators in NArray. Here, the name of those methods are just quoted. See the documentation of NArray for their usage.

### Math functions

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

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

### Other methods

These methods returns a NArray (not a VArray).

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