module NumRu::GPhys::IO

A module to handle file IO regarding GPhys.

Many of the functionality of this module is implemented in the modules for specific file types such as NumRu::GPhys::NetCDF_IO, to which this module directs operations.

For example, GPhys::IO.open(file, name) simply calls GPhys::*_IO.open(file, name), where '*' is NetCDF, GrADS, or grib.

Module functions

open(file, varname)

Opens a GPhys in file having the name varname.

ARGUMENTS

• file (String, NetCDF, GRIB,.. etc, or Array, NArray, Regexp) : Specifies the file. Path if String; a File pointer if NetCDF etc.. The processing is forwarded to open_multi, if this argument is an Array, NArray, or Regexp.
• varname (String) : name of the variable

RETURN VALUE

• a GPhys

open_multi(files, varname)

Opens a GPhys by combining a variable across multiple files. It initializes GPhys objects over the files by calling open and unites them into a single GPhys object by using GPhys.join or GPhys.join_md.

ARGUMENTS

• files (Array, NArray (NArray.object), or Regexp) : Specifies the files.
  • when Array, it must consist of paths or file pointers (that are accepted by open). All coordinates of the variable in the files are scanned, and a joined object is constructed properly. Thus, you can simply put subsets of a 2D tiling in a simple non-nested 1D Array. GPhys.join is used in this case.

  • when NArray, it must consist of paths or file pointers (that are accepted by open). Each dimension with multiple elements must correspond to a dimension along which joining is made. For example, a 2D tiling can be specified as

    files = NArray.to_na([['f00.nc','f10.nc'],['f01.nc','f11.nc']])
    gp = GPhys::IO.open_multi( files, "f" )

    GPhys.join_md is used in this case.

  • When Regexp, similar to when NArray, but expresses the paths. The dimensions to join is specified by "captures" (parentheses). For example, the above 2D tiling can be specified as

    files = /f(\d)(\d).nc/
    gp = GPhys::IO.open_multi( files, "f" )

    The regexp can contain a directory path (e.g., /dir\/sub\/f(\d)(d).nc/), but the directory part must be unique (i.e., a simple string), so only a single directly can be specified. All captures must be in the part representing the file names (in the directory). GPhys.join_md is used in this case.

• varname (String) : name of the variable

RETURN VALUE

• a GPhys

write(file, gphys, name=nil)

Writes a GPhys object in a file

ARGUMENTS

• file (NetCDF, GRIB,.. etc) : the file. Writing must be permitted. To close (finalize) it after writing is left to the user.
• gphys (GPhys) : the GPhys object to write
• name (String; optional) : if specified, this name is used in the file rather than the name of gphys

write_grid(file, grid_or_gphys)

each_along_dims_write(gphyses, files, *loopdims){...} # a block is expected

var_names(file)

var_names_except_coordinates(file)

See the manual of NumRu::GPhys::NetCDF_IO for the methods listed above.

file2type(file)

Figures out the file type supported in this module.

ARGUMENTS

• file (String, NetCDF, Grib, or GrADS_Gridded) : What to return is of course obvious if it is NetCDF, Grib, or GrADS_Gridded. If it is a String, it is assumed to be a path of a file, and the file type is determined by its suffix when 'nc', 'ctl', or 'grib'; In other cases, the type is figured out by reading in a few bytes from the beginning.

RETURN VALUE

• GPhys::IO::NETCDF, GPhys::IO::GRIB, or GPhys::IO::GRADS, which are string constants.

file2specific_module(file)

Same as file2type, but returns GPhys::NetCDF_IO, GPhys::GrADS_IO, or GPhys::Grib_IO.

file2file_class(file)

Same as file2type, but returns NetCDF, GrADS_Gridded, or Grib.

parse_gturl(gturl)

Parses GTOOL4-type URLs to specify path, variable name, and optionally subsets, whose format is path[@|/]varname[,dimname=pos1[:pos2[:thinning_intv]][,dimname=...]]

ARGUMENTS

• gturl (String) GTOOL4 URL, whose format is path[@|/]varname[,dimname=pos1[:pos2[:thinning_intv]][,dimname=...]]

RETURN VALUES

• An Array consisting of [file, var, slice, cut_slice, thinning], where
  • file (String) : path
  • var (String) : variable name
  • slice (Array) : subset specifier by the grid numbers to be used as GPhys#[slice].
  • cut_slice (Array) : subset specifier in physical coordinate to be used as GPhys#cut[cut_slice].
  • thinning (Array) : additional subset specifier for thinning with uniform intervals if needed to be used GPhys#[thinning] after appling GPhys#cut.

open_gturl(gturl)

a GPhys constructor from a Gtool4-type URL. See parse_gturl for its format.

RETURN VALUE

• a GPhys

str2gphys(str)

Open a GPhys from a slash("/")-separated String such as "U.nc/U" and "U.nc".

• Aimed to help quick jobs with interactive sessions -- This method do not handle a GPhys across multiple files.
• if the variable path is ommited such as "U.nc", try to find the variable in it -- read the file and if only one variable is found, assume that is the variable specified; otherwise, an exception is raised.
• URL is accepted, but it's only thru NetCDF assuming OPeNDAP.

ARGUMENTS

• a String (file_path[/variable_path]) e.g. "U.nc/U", "U.nc", "http://.../U.nc/U"

RETURN VALUE

• a GPhys

Module constants

GTURLfmt

The format of Gtool4URL.