R Graphical Manual

Browse All

Last data update: 2014.03.03

R: Read in variable values from Models3-formatted files

get.M3.var

R Documentation

Read in variable values from Models3-formatted files

Description

Read in variable values from Models3-formatted files.

Usage

get.M3.var(file, var, lcol, ucol, lrow, urow, llay, ulay,
                ldatetime, udatetime, hz.units)

Arguments

`file`	Name of Models3-formatted file to be read.
`var`	Name (character string) or number (positive integer) of variable whose values are to be read.
`lcol`	Lower column bound (positive integer) to be read. The default is to read all columns.
`ucol`	Upper column bound (positive integer) to be read. The default is to read all columns.
`lrow`	Lower row bound (positive integer) to be read. The default is to read all rows.
`urow`	Upper row bound (positive integer) to be read. The default is to read all rows.
`llay`	Lower layer bound (positive integer) to be read. The default is to read the first layer only.
`ulay`	Upper layer bound (positive integer) to be read. The default is to read the first layer only.
`ldatetime`	Starting date-time (Date or POSIX class) in GMT.
`udatetime`	Starting date-time (Date or POSIX class) in GMT.

The default is to read all date-times. If the file is time-independent, the one available time step will be read and user input for ldatetime and udatetime will be disregarded.

hz.units

Units associated with grid cell horizontal dimensions. Default is degrees ("deg") if the data is indexed according to longitude/latitude and kilometers ("km") otherwise. If the file is not indexed according to longitude/latitude, the user could choose meters ("m").

Details

This function assumes that the projection is either Lambert conic conformal or polar stereographic projection. It also assumes that the Models3-formatted file is either time-independent or time-stepped; it cannot be of type circular-buffer.

Value

List with the following components:

`data`	Array holding the specified variable values. Array is four-dimensional, unless the Models3-formatted file is time-independent (which we assume if TSTEP attribute is 0), in which case it is three-dimensional. Dimensions are columns, rows, layers, date-time steps.
`data.units`	Contains the units associated with `data`.
`x.cell.ctr`	X-coordinates of grid cell centers, in units given by `hz.units`.
`y.cell.ctr`	Y-coordinates of grid cell centers, in units given by `hz.units`.
`hz.units`	Contains the units associated with the horizontal dimensions of the grid cells (km, m, or deg). These are the units in which `x.cell.ctr` and `y.cell.ctr` are given.
`rows`	Row numbers extracted.
`cols`	Column numbers extracted.
`layers`	Layer numbers extracted.
`datetime`	Date-time steps (in POSIX format) associated with the variable, if the file is not time-independent. For time-independent files, element datetime is set to NULL.

Note

This function relies on the R package ncdf4 to read information from Models3-formatted files, since the Models3 format is built on netCDF
(http://www.unidata.ucar.edu/software/netcdf).
It also relies on the rgdal interface with GDAL (Geospatial Data Abstraction Library,
http://www.gdal.org) to obtain the x,y-coordinates of the grid cell centers on the projection.

Author(s)

Jenise Swall

References

http://www.baronams.com/products/ioapi/VBLE.html,
http://www.baronams.com/products/ioapi/DATETIME.html

Examples

## Find the path to the first demo file (with polar
## stereographic projection).
polar.file <- system.file("extdata/surfinfo_polar.ncf", package="M3")

## Read in the terrain elevation variable.
elev <- get.M3.var(file=polar.file, var="HT")
## Make a plot.
image(elev$x.cell.ctr, elev$y.cell.ctr, elev$data[,,1],
      xlab="Projection x-coord (km)", ylab="Projection y-coord (km)",
      zlim=range(elev$data[,,1]), col=topo.colors(20))
## Find national boundaries on this projection, superimpose them on
## the plot.
world.bds <- get.map.lines.M3.proj(file=polar.file, database="world")$coords
lines(world.bds)

## Subset to a smaller geographic area in southwestern U.S.
subset.elev <- var.subset(elev, llx=-2100, urx=0, lly=-6500, ury=-4000)
## Make a plot of this subset.
image(subset.elev$x.cell.ctr, subset.elev$y.cell.ctr,
      subset.elev$data[,,1], xlab="Projection x-coord (km)",
      ylab="Projection y-coord (km)", zlim=range(subset.elev$data[,,1]),
      col=topo.colors(20))
## Find state boundaries on this projection, superimpose them on the plot.
state.bds <- get.map.lines.M3.proj(file=polar.file)$coords
lines(state.bds)



## Find the path to second demo file (with Lambert conic
## conformal projection).
lcc.file <- system.file("extdata/ozone_lcc.ncf", package="M3")

## Read in the ozone for July 4 for eastern U.S.
oz <- get.M3.var(file=lcc.file, var="O3", lcol=80, urow=95,
                      ldatetime=as.Date("2001-07-04"),
                      udatetime=as.Date("2001-07-04"))
## Make a plot.
image(oz$x.cell.ctr, oz$y.cell.ctr, oz$data[,,1,1],
      xlab="Projection x-coord (km)", ylab="Projection y-coord (km)",
      zlim=range(oz$data), col=heat.colors(15))

## Find map lines on this projection, superimpose them on the plot.
state.bds <- get.map.lines.M3.proj(file=lcc.file)$coords
lines(state.bds)

Results


R version 3.3.1 (2016-06-21) -- "Bug in Your Hair"
Copyright (C) 2016 The R Foundation for Statistical Computing
Platform: x86_64-pc-linux-gnu (64-bit)

R is free software and comes with ABSOLUTELY NO WARRANTY.
You are welcome to redistribute it under certain conditions.
Type 'license()' or 'licence()' for distribution details.

R is a collaborative project with many contributors.
Type 'contributors()' for more information and
'citation()' on how to cite R or R packages in publications.

Type 'demo()' for some demos, 'help()' for on-line help, or
'help.start()' for an HTML browser interface to help.
Type 'q()' to quit R.

> library(M3)
Loading required package: ncdf4
Loading required package: rgdal
Loading required package: sp
rgdal: version: 1.1-10, (SVN revision 622)
 Geospatial Data Abstraction Library extensions to R successfully loaded
 Loaded GDAL runtime: GDAL 1.11.3, released 2015/09/16
 Path to GDAL shared files: /usr/share/gdal/1.11
 Loaded PROJ.4 runtime: Rel. 4.9.2, 08 September 2015, [PJ_VERSION: 492]
 Path to PROJ.4 shared files: (autodetected)
 Linking to sp version: 1.2-3 
Loading required package: maps

 # maps v3.1: updated 'world': all lakes moved to separate new #
 # 'lakes' database. Type '?world' or 'news(package="maps")'.  #


Loading required package: mapdata
> png(filename="/home/ddbj/snapshot/RGM3/R_CC/result/M3/get.M3.var.Rd_%03d_medium.png", width=480, height=480)
> ### Name: get.M3.var
> ### Title: Read in variable values from Models3-formatted files
> ### Aliases: get.M3.var
> ### Keywords: IO
> 
> ### ** Examples
> 
> ## Find the path to the first demo file (with polar
> ## stereographic projection).
> polar.file <- system.file("extdata/surfinfo_polar.ncf", package="M3")
> 
> ## Read in the terrain elevation variable.
> elev <- get.M3.var(file=polar.file, var="HT")
Time independent file - reading only time step available.
> ## Make a plot.
> image(elev$x.cell.ctr, elev$y.cell.ctr, elev$data[,,1],
+       xlab="Projection x-coord (km)", ylab="Projection y-coord (km)",
+       zlim=range(elev$data[,,1]), col=topo.colors(20))
> ## Find national boundaries on this projection, superimpose them on
> ## the plot.
> world.bds <- get.map.lines.M3.proj(file=polar.file, database="world")$coords
> lines(world.bds)
> 
> ## Subset to a smaller geographic area in southwestern U.S.
> subset.elev <- var.subset(elev, llx=-2100, urx=0, lly=-6500, ury=-4000)
> ## Make a plot of this subset.
> image(subset.elev$x.cell.ctr, subset.elev$y.cell.ctr,
+       subset.elev$data[,,1], xlab="Projection x-coord (km)",
+       ylab="Projection y-coord (km)", zlim=range(subset.elev$data[,,1]),
+       col=topo.colors(20))
> ## Find state boundaries on this projection, superimpose them on the plot.
> state.bds <- get.map.lines.M3.proj(file=polar.file)$coords
> lines(state.bds)
> 
> 
> 
> ## Find the path to second demo file (with Lambert conic
> ## conformal projection).
> lcc.file <- system.file("extdata/ozone_lcc.ncf", package="M3")
> 
> ## Read in the ozone for July 4 for eastern U.S.
> oz <- get.M3.var(file=lcc.file, var="O3", lcol=80, urow=95,
+                       ldatetime=as.Date("2001-07-04"),
+                       udatetime=as.Date("2001-07-04"))
> ## Make a plot.
> image(oz$x.cell.ctr, oz$y.cell.ctr, oz$data[,,1,1],
+       xlab="Projection x-coord (km)", ylab="Projection y-coord (km)",
+       zlim=range(oz$data), col=heat.colors(15))
> 
> ## Find map lines on this projection, superimpose them on the plot.
> state.bds <- get.map.lines.M3.proj(file=lcc.file)$coords
> lines(state.bds)
> 
> 
> 
> 
> 
> dev.off()
null device 
          1 
>