ncdf4Utils version 0.5-1

-------------------------

*Removed functions:*
@nc_open.R@ -- is no longer necessary since ncdf4 package (version >= 1.6.1) considers
             _FillValue as attribute holding missing values

@plotmap_rot.R@ -- the new plotmap.R function includes rotated coordinates

*Changed functions:*
@geo2rot.R@ -- calculates the special case pollat=90.,pollon=0.,polgam=0. (i.e. same geographical coordinates)
               now logically (no longer pollat=90.,pollon=180.,polgam=0. or pollat=90.,pollon=0.,polgam=180.
               for geographical coordinates)

@plotmap.R@ -- this function has been re-written and includes (and thus replaces) the former
               plotmap.R and plotmap_rot.R functions. The new function now decides on the
               existance and value of the grid mapping parameter in the netCDF file .
             A new grid mapping for multiple rotated pole has been added.
             A new option is available: "na.col". The colour of undefined grid pixels is defined
               by this option. By default it is transparent.

*New functions:*
@geo2multirot.R@ -- transforms geographical to multiple rotated pole coordinates (usage: geo2multirot)
                  or multiple rotated pole to geographical coordinates (usage: multirot2geo)

ChangeLog

+ncdf4Utils version 0.5-1
+-------------------------
+
+*Removed functions:*
+@nc_open.R@ -- is no longer necessary since ncdf4 package (version >= 1.6.1) considers 
+             _FillValue as attribute holding missing values
+             
+@plotmap_rot.R@ -- the new plotmap.R function includes rotated coordinates
+
+*Changed functions:*
+@geo2rot.R@ -- calculates the special case pollat=90.,pollon=0.,polgam=0. (i.e. same geographical coordinates)
+               now logically (no longer pollat=90.,pollon=180.,polgam=0. or pollat=90.,pollon=0.,polgam=180. 
+               for geographical coordinates) 
+
+@plotmap.R@ -- this function has been re-written and includes (and thus replaces) the former 
+               plotmap.R and plotmap_rot.R functions. The new function now decides on the 
+               existance and value of the grid mapping parameter in the netCDF file .
+             A new grid mapping for multiple rotated pole has been added.
+             A new option is available: "na.col". The colour of undefined grid pixels is defined
+               by this option. By default it is transparent.
+
+*New functions:*
+@geo2multirot.R@ -- transforms geographical to multiple rotated pole coordinates (usage: geo2multirot)
+                  or multiple rotated pole to geographical coordinates (usage: multirot2geo)
+
 
 ncdf4Utils version 0.4-10
 -------------------------

DESCRIPTION

 Package: ncdf4Utils
 Type: Package
 Title: provides plot functions to use with NetCDF data
-Version: 0.4-10
-Date: 2010-11-22
+Version: 0.5-1
+Date: 2011-07-31
 Author: Jonas Bhend <jonas.bhend@env.ethz.ch>, with contributions 
     from Burkhardt Rockel <burkhardt.rockel@hzg.de>
 Maintainer: Jonas Bhend <jonas.bhend@env.ethz.ch>
@@ -15,4 +15,4 @@ Description: This package contains numerous functions to plot
 License: GPL
 LazyLoad: yes
 LazyData: true
-Packaged: Mon November 22 14:11:000 2010; rockel
+Packaged: Mon July 31 15:49:000 2010; rockel

R/geo2multirot.R

+
+geo2multirot <- function(loncent, latcent, lon, lat, false_easting=0, false_northing=0, earth_radius=NULL){
+
+    if (is.null(earth_radius)){
+      rearth <- 2.E7/pi
+    } else {
+      rearth <- earth_radius
+    }
+    zpir18 <- pi/180
+    zrpi18 <- 180/pi
+
+    latpol <- asin( cos(latcent*zpir18) ) * zrpi18
+
+    if (latcent > 0) {
+      lonpol <- loncent -180
+      longn  <- 0
+    } else {
+       lonpol <- loncent
+       longn  <- 180
+    }
+
+    tmp <- geo2rot(lonpol, latpol, lon, lat, longn) 
+    lonh <- zpir18*tmp$x
+    lath <- zpir18*tmp$y
+
+    zarg1 <- -cos(lonh)
+    zarg2 = tan(lath)
+    zarg2[zarg2 == 0] <- 1.0e-20
+    ypol <- abs(atan(zarg1/zarg2))
+    yr = pi/2. - ypol
+    ind <- lath < 0 & !is.na(lath)
+    yr[ind] <- -yr[ind]
+    zarg1 = - sin(lonh) *cos(lath)
+    zarg2[ind] = -sin(ypol[ind])*cos(lath[ind])*cos(lonh[ind]) + cos(ypol[ind])*sin(lath[ind])
+    ind <- lath >= 0 & !is.na(lath)
+    zarg2[ind] = -sin(ypol[ind])*cos(lath[ind])*cos(lonh[ind]) - cos(ypol[ind])*sin(lath[ind])
+    zarg2[zarg2 == 0] <- 1.0e-20
+    xr = abs(atan(zarg1/zarg2))
+    ind <- lonh < 0 & !is.na(lonh)
+    xr[ind] <- -xr[ind]
+  
+#...  radians on earths surface into Cartesian distances
+
+    xc = xr * rearth + false_easting
+    yc = yr * rearth + false_northing
+
+    out     <- list(x=xc, y=yc)
+    out
+}
+
+##########################################################
+
+multirot2geo <- function(loncent, latcent, xc, yc, false_easting=0, false_northing=0, earth_radius=NULL){
+
+    if (is.null(earth_radius)){
+      rearth <- 2.E7/pi
+    } else {
+      rearth <- earth_radius
+    }
+    zpir18 <- pi/180
+    zrpi18 <- 180/pi
+
+    xr <- (xc - false_easting) / rearth
+    yr <- (yc - false_northing) / rearth
+
+    lath <- asin ( cos( xr ) * sin( yr ) ) *zrpi18
+    lonh <- atan2( tan( xr ) , cos( yr ) ) *zrpi18
+
+    latpol <- asin( cos(latcent*zpir18) ) *zrpi18
+
+    if (latcent > 0) {
+      lonpol <- loncent - 180
+      longn  <- 0
+    } else {
+       lonpol <- loncent
+       longn  <- 180
+    }
+
+    out <- rot2geo(lonpol, latpol, lonh, lath, longn)
+
+}

R/geo2rot.R

@@ -49,29 +49,36 @@
     #   Transformation formulas for converting between these two systems.
     #
     
-    # convert to -180 to 180
-    ind         <- rlarot > 180 & !is.na(rlarot)
-    rlarot[ind]    <- rlarot[ind] - 360
+    if (polphi == 90) {
     
-    # convert to -pi to pi
-    polphi      <- polphi / 180 * pi
-    pollam      <- pollam / 180 * pi
-    polgam      <- polgam / 180 * pi
-    phirot      <- phirot / 180 * pi
-    rlarot      <- rlarot / 180 * pi
-    
-    zsinpol     <- sin(polphi)
-    zcospol     <- cos(polphi)
- 
-    # adjust for switched north pole
-    if (polgam != 0){
-        zarg    <- zsinpol * sin(phirot) + zcospol * cos(phirot) *
-            (cos(rlarot)*cos(polgam) - sin(polgam) * sin(rlarot))
+      phirot2phi = phirot
+      
     } else {
-        zarg    <- zcospol * cos(phirot) * cos(rlarot) + zsinpol * sin(phirot)
+      # convert to -180 to 180
+      ind         <- rlarot > 180 & !is.na(rlarot)
+      rlarot[ind]    <- rlarot[ind] - 360
+      
+      # convert to -pi to pi
+      polphi      <- polphi / 180 * pi
+      pollam      <- pollam / 180 * pi
+      polgam      <- polgam / 180 * pi
+      phirot      <- phirot / 180 * pi
+      rlarot      <- rlarot / 180 * pi
+      
+      zsinpol     <- sin(polphi)
+      zcospol     <- cos(polphi)
+   
+      # adjust for switched north pole
+      if (polgam != 0){
+          zarg    <- zsinpol * sin(phirot) + zcospol * cos(phirot) *
+              (cos(rlarot)*cos(polgam) - sin(polgam) * sin(rlarot))
+      } else {
+          zarg    <- zcospol * cos(phirot) * cos(rlarot) + zsinpol * sin(phirot)
+      }
+      
+      phirot2phi  <- asin(zarg) * 180 / pi
     }
-    
-    out         <- asin(zarg) * 180 / pi
+    phirot2phi
 }
 
 
@@ -89,20 +96,26 @@
     #
     #------------------------------------------------------------------------------
 
-    zsinpol     <- sin(polphi / 180 * pi)
-    zcospol     <- cos(polphi / 180 * pi)
-    zlampol     <- pollam / 180 * pi
-    zphi        <- phi / 180 * pi
+    if (polphi == 90) {
     
-    ind         <- rla > 180 & !is.na(rla)
-    rla[ind]    <- rla[ind] - 360
-    zrla        <- rla / 180 * pi
-
-    zarg1       <- sin(zphi) * zsinpol
-    zarg2       <- cos(zphi) * zcospol * cos(zrla - zlampol)
-
-    phi2phirot  <- asin(zarg1 + zarg2) * 180 / pi
+      phi2phirot = phi
+      
+    } else {
+      zsinpol     <- sin(polphi / 180 * pi)
+      zcospol     <- cos(polphi / 180 * pi)
+      zlampol     <- pollam / 180 * pi
+      zphi        <- phi / 180 * pi
+      
+      ind         <- rla > 180 & !is.na(rla)
+      rla[ind]    <- rla[ind] - 360
+      zrla        <- rla / 180 * pi
+  
+      zarg1       <- sin(zphi) * zsinpol
+      zarg2       <- cos(zphi) * zcospol * cos(zrla - zlampol)
+  
+      phi2phirot  <- asin(zarg1 + zarg2) * 180 / pi
     
+    } 
     phi2phirot
 
 }
@@ -123,6 +136,12 @@
     #   Transformation formulas for converting between these two systems.
     #
     
+    if (polphi == 90) {
+
+      rlarot2rla = rlarot - pollam - polgam
+ 
+    } else {
+
     zpir18      <- pi/180
     zrpi18      <- 180/pi
     
@@ -156,6 +175,12 @@
     zarg2[zarg2 == 0] <- 1.0e-20
 
     rlarot2rla  <- zrpi18 * atan2(zarg1, zarg2)
+
+    }
+
+    ind         <- rlarot2rla < -180 & !is.na(rlarot2rla)
+    rlarot2rla[ind] <- rlarot2rla[ind] + 360
+
     rlarot2rla
 }
 
@@ -174,33 +199,42 @@
     #
     #------------------------------------------------------------------------------
 
-    zpir18      <- pi/180
-    zrpi18      <- 180/pi
-    
-    zsinpol     <- sin(zpir18 * polphi)
-    zcospol     <- cos(zpir18 * polphi)
-    zlampol     <- zpir18 * pollam
-    zphi        <- zpir18 * phi
-
-    # convert everything to -180 to 180
-    ind         <- rla > 180 & !is.na(rla)
-    rla[ind]    <- rla[ind] - 360
-    zrla        <- zpir18 * rla
+    if (polphi == 90) {
 
-    zarg1       <- - sin(zrla-zlampol) * cos(zphi)
-    zarg2       <- - zsinpol * cos(zphi) * cos(zrla-zlampol) + 
-        zcospol * sin(zphi)
+      rla2rlarot= rla + pollam + polgam
 
-    zarg2[zarg2 == 0] <- 1.0e-20
+    } else {
 
-    rla2rlarot  <- zrpi18 * atan2(zarg1,zarg2)
+      zpir18      <- pi/180
+      zrpi18      <- 180/pi
+      
+      zsinpol     <- sin(zpir18 * polphi)
+      zcospol     <- cos(zpir18 * polphi)
+      zlampol     <- zpir18 * pollam
+      zphi        <- zpir18 * phi
+  
+      # convert everything to -180 to 180
+      ind         <- rla > 180 & !is.na(rla)
+      rla[ind]    <- rla[ind] - 360
+      zrla        <- zpir18 * rla
+  
+      zarg1       <- - sin(zrla-zlampol) * cos(zphi)
+      zarg2       <- - zsinpol * cos(zphi) * cos(zrla-zlampol) + 
+          zcospol * sin(zphi)
+  
+      zarg2[zarg2 == 0] <- 1.0e-20
+  
+      rla2rlarot  <- zrpi18 * atan2(zarg1,zarg2)
+  
+      if (polgam != 0) {
+          rla2rlarot   <- polgam + rla2rlarot
+      }
 
-    if (polgam != 0) {
-        rla2rlarot   <- polgam + rla2rlarot
     }
+
     ind         <- rla2rlarot > 180 & !is.na(rla2rlarot)
     rla2rlarot[ind] <- rla2rlarot[ind] - 360
-    
+
     rla2rlarot
 }
 

man/geo2rot.Rd

@@ -15,7 +15,7 @@
 \arguments{
   \item{pollon}{Longitude of the rotated pole in degrees}
   \item{pollat}{Latitude of the rotated pole in degrees}
-  \item{polgam}{Switch for mirrored rotation (0 or -180 deg.)}
+  \item{polgam}{Rotation angle about the North-South-Pole axis in the rotated system}
   \item{lon}{A vector of longitudes}
   \item{lat}{A vector of latitudes}
   \item{rlon}{A vector of longitudes on the rotated grid}

man/geomulti2rot.Rd

+\name{geo2multirot}
+\alias{geo2multirot}
+\alias{multirot2geo}
+%- Also NEED an '\alias' for EACH other topic documented here.
+\title{Function to convert }
+\description{
+  Functions to convert multi-rotated latitudes and longitudes to positions on regular grids and vice versa.
+}
+\usage{
+  geo2multirot(loncent, latcent, lon, lat, false_easting=0, false_northing=0, earth_radius=NULL)
+
+  multirot2geo(loncent, latcent, xc, yc, false_easting=0, false_northing=0, earth_radius=NULL)
+}
+
+\arguments{
+  \item{loncent}{center longitude of the transformed system in degrees}
+  \item{latcent}{center latitude of the transformed system in degrees}
+  \item{lon}{A vector of longitudes}
+  \item{lat}{A vector of latitudes}
+  \item{xc}{A vector of x-coordinates in the transformed system in meters}
+  \item{yc}{A vector of y-coordinates in the transformed system in meters}
+  \item{false_easting}{false easting of x, i.e. shift of x-coordinate}
+  \item{false_northing}{false northing of y, i.e. shift of y-coordinate}
+  \item{earth_radius}{earth radius in meter, default is 2.E7/pi}
+}
+\value{
+  Returns a list with two vectors:
+  \item{x}{Processed longitudes}
+  \item{y}{Processed latitudes}
+}
+\note{
+  These functions are based on the respective fortran code for the TRIMNP model at Helmholtz-Zentrum Geesthacht).
+}
+\references{missing reference to TRIMNP code}
+\author{Burkhardt Rockel: burkhardt.rockel@hzg.de}
+\examples{
+    # Location of c(0,0) in rotated coordinates
+    multirot2geo(7.8, 54.1, 0, 0)
+}
+% Add one or more standard keywords, see file 'KEYWORDS' in the
+% R documentation directory.
+\keyword{ manip }
+\keyword{ utilities }% __ONLY ONE__ keyword per line

man/ncdf4Utils-package.Rd

@@ -12,20 +12,20 @@ Package for plotting and analysing NetCDF data
 \tabular{ll}{
 Package: \tab ncdf4Utils\cr
 Type: \tab Package\cr
-Version: \tab 0.4-10\cr
-Date: \tab 2010-07-26\cr
+Version: \tab 0.5-1\cr
+Date: \tab 2012-07-31\cr
 License: \tab GPL\cr
 LazyLoad: \tab yes\cr
 }
-  The time dimesion of NetCDF files can be read with:
+  The time dimension of NetCDF files can be read with:
   
   \code{nc <- nc_open("<path-to-netcdf-file>")}
   
   \code{times <- ncdf_times(nc)}
   
-  Data on rotated grids can be plotted with:
+  Data on geographic, rotated, and multiple rotated grids can be plotted with:
   
-  \code{plotmap_rot("<path-to-netcdf-file>")}
+  \code{plotmap("<path-to-netcdf-file>")}
   
   Fractional area within a given polygon can be computed via:
   
@@ -37,10 +37,11 @@ LazyLoad: \tab yes\cr
   
 }
 \author{
-  Maintainer: Jonas Bhend <jonas.bhend@env.ethz.ch>
+  Maintainer: Jonas Bhend, Burkhardt Rockel <Burkhardt.Rockel@hzg.de>
 }
 \keyword{ package }
 \seealso{
+  \code{\link[<akima>:<akima>-package]{<akima>}}, 
   \code{\link[<ncdf4>:<ncdf4>-package]{<ncdf4>}}, 
   \code{\link[<sp>:<sp>-package]{<sp>}}, 
   \code{\link[<maps>:<maps>-package]{<maps>}}, 

man/plot_colourbar.Rd

@@ -22,7 +22,7 @@
   \item{nn}{how many labels are set (every nn'th label is set)}
   \item{center}{switch for labelling in the middle of the colour box)}
   \item{sea.col}{colour for the lowest box, gets a different labelling)}
-  \item{x.list}{A list of class "plotmap" containing the levels and colours and additional information as returned by \code{plotmap} or \code{plotmap_rot}}
+  \item{x.list}{A list of class "plotmap" containing the levels and colours and additional information as returned by \code{plotmap}}
   \item{incl.units}{allows for the long-name and units attribute of the plotted variable to be added to the axis annotation)}
 }
 \details{
@@ -36,7 +36,7 @@
 }
 \author{Jonas Bhend: jonas.bhend@env.ethz.ch}
 
-\seealso{\code{\link{plotmap}}, \code{\link{plotmap_rot}}}
+\seealso{\code{\link{plotmap}}}
 \examples{
   plot_colourbar(levs=0:11, col=rbfun(10), 
       xlab="imaginary units", sea.col="lightblue")

man/plotmap.Rd

+\name{plotmap}
+\alias{plotmap}
+\alias{plotmap}
+%- Also NEED an '\alias' for EACH other topic documented here.
+\title{Plot NetCDF data on rotated, multiple rotated or regular lonlat grids}
+\description{
+  This function reads in NetCDF data and produces a lon-lat plot of the specified variable.
+}
+\usage{
+plotmap(file, file.small = NULL, sponge = 8, 
+    sponge.small = 15, varname = NULL, 
+    lsm.file = NULL, lsm.file.small = NULL, col = NULL, 
+    levels = NULL, sea.col = NULL, na.col = NULL, rivers = T, cities = T, 
+    label = TRUE, minpop = NULL, ncities = 10, city.pch = 19, 
+    alt.contour = F, alt.lev = NULL, grid = TRUE, 
+    grid.txt = TRUE, grid.lty = 2, i.time = 1, i.lev = 1, 
+    map.lwd = 2, map.lty = 1, cex.axis = 1, cex.lab = 1, cex.main = 1, 
+    cex.txt = 1, main = "", xlab = "", ylab = "", 
+    colourplot = TRUE, hires = FALSE, interior = FALSE,
+    alt.poli=TRUE, add=TRUE, nlongrid=10, nlatgrid=5,
+    lon.ind, lat.ind)
+}
+%- maybe also 'usage' for other objects documented here.
+\arguments{
+  \item{file}{Path to the NetCDF file containing the data to plot}
+  \item{file.small}{... for the nest in the large region}
+  \item{sponge}{Number of grid cells to mask out at boundary}
+  \item{sponge.small}{... for the nest in the large region}
+  \item{varname}{Variable to plot (defaults to \code{HSURF} for orography or any variable with at least lon and lat dimensions)}
+  \item{lsm.file}{Additional file containing land-sea mask and/or altitude information in \code{FR\_LAND} and \code{HSURF}}
+  \item{lsm.file.small}{... for the nest in the large region}
+  \item{col}{Colours to use}
+  \item{levels}{Levels to use}
+  \item{sea.col}{Colour for masked out water grid points}
+  \item{na.col}{Colour for grid points with undefined values}
+  \item{rivers}{Switch for automatically added rivers}
+  \item{cities}{Switch for automatically added cities}
+  \item{label}{Switch for labels of cities}
+  \item{minpop}{Minimal population for cities to get drawn}
+  \item{ncities}{Number of cities to draw}
+  \item{city.pch}{Symbol for city points}
+  \item{cex.txt}{Character expansion for city labels}
+  \item{alt.contour}{Switch for usage of the coastline as in file or lsm.file}
+  \item{alt.lev}{Level at which to draw coastline (if alt.contour == TRUE) in units of "\code{FR\_LAND}"}
+  \item{grid}{Switch for inclusion of grid lines}
+  \item{grid.txt}{Switch for inclusion of grid axis labels at the border of the plot}
+  \item{grid.lty}{Line type for grid lines}
+  \item{i.time}{Time step to plot}
+  \item{i.lev}{Level to plot}
+  \item{map.lwd}{Line width for the coastline/ country border}
+  \item{map.lty}{Line type for the coastline/ country border}
+  \item{hires}{Use hi-resolution coastline}
+  \item{interior}{Draw political boundaries}
+  \item{colourplot}{Switch for colour or grayscale plot}
+  \item{alt.poli}{Switch to use alternative political boundaries}
+  \item{add}{Should plot be added to existing plot}
+  \item{nlongrid, nlatgrid}{Approximate number of longitude and latitude grid lines}
+  \item{lon.ind, lat.ind}{Sequence of longitudes (latitudes) at which to draw grid lines. Has to be increasing. Longitudes greater than 180 are converted.}
+}
+\value{
+  A List of class "plotmap" containing the following objects:
+  
+  For rotated pole grid mapping:
+  \item{pollon}{Longitude of the rotated pole}
+  \item{pollat}{Latitude of the rotated pole}
+  \item{polgam}{Rotation angle about the North-South-Pole axis in the rotated system}
+  For multiple rotated pole grid mapping:
+  \item{loncent}{center longitude of the transformed system in degrees}
+  \item{latcent}{center longitude of the transformed system in degrees}
+  \item{false_easting}{false easting of x, i.e. shift of x-coordinate}
+  \item{false_northing}{false northing of y, i.e. shift of y-coordinate}
+  \item{earth_radius}{earth radius in meter}
+ For all grid mappings:
+  \item{levs}{The levels used}
+  \item{col}{The colours used}
+  \item{sea.col}{The colour used for water grid points}
+  \item{longname}{The longname attribute of the variable plotted}
+  \item{units}{The units of the variable plotted}
+}
+\note{
+  This function chooses the grid mapping dependent on the existance of the parameter "rotated_pole" or "multiple_rotated_pole".
+  If none of them exists geographical coordinates are assumed.
+}
+\author{Jonas Bhend / Burkhardt Rockel: Burkhardt.Rockel@hzg.de}
+\seealso{\code{\link{plot_colourbar.plotmap}}}
+\examples{
+  print("Sorry no examples, too complex...")
+}
+% Add one or more standard keywords, see file 'KEYWORDS' in the
+% R documentation directory.
+\keyword{ aplot }