pField: Create a pField object

In EarthSystemDiagnostics/pfields: An R Package to Analyse Gridded Field Data

Description

This function takes supplied vectors of time points, latitudes and longitudes to create an empty or convert given data into a "pField" object.

Usage

pField(
  data = NULL,
  time = 1,
  lat = NA,
  lon = NA,
  name = "",
  history = "",
  date = TRUE,
  kTol = 1/400
)

Arguments

data	input data; can be NULL, a numeric vector or an array of any dimension, but note the assumed order of observations (see details). If NULL or a single value (length-1 vector), an empty "pfield" object or a "pfield" object filled with the single value is created with dimensions according to the information (i.e., lengths) in time, lat and lon.
time	vector of observation time points, must be equidistant.
lat	vector of (unique) latitudes.
lon	vector of (unique) longitudes.
name	character string with the name of the "pField" object to be generated.
history	character string to append to the history attribute of the "pField" object (optional).
date	logical, whether or not to append the current date to the history attribute; defaults to TRUE.
kTol	tolerance to check for equidistance of time steps; defaults to 1/400.

Details

The function creates or shapes given data into a "pfield" object:

• The return object is a two-dimensional array of class "pfield" with columns corresponding to the spatial dimension (latitude-longitude pair) and rows corresponding to the time points of the observations.

• Each time series at a spatial location is a ts object.

• Longitude and latitude information are included as attributes along with a history attribute for change log information.

• If no input data is supplied, an empty matrix is created according to the information provided in time, lat and lon.

• If data is supplied of length > 1, its total number of observation points must match the product of the lengths of time, lat and lon.

• Note that the order of observations in the input data is assumed to follow the typical structure of netcdf files, i.e. the observations are incremented first along longitudes, then along latitudes, and finally along time.

Value

A two-dimensional array of class "pField".

Author(s)

Thomas Laepple; adapted by Thomas Münch

Source

Function copied from "proxytype.R" in paleolibary/src/

Examples

# Create an empty pfield object covering two latitudes, three longitudes and
# four time steps:

lat <- c(-75, -80)
lon <- c(0, 135, 215)
time <- 1 : 4

pf1 <- pField(lat = lat, lon = lon, time = time)

# Now fill the object with data:
# the important assumption is that the order of observations follows
# increments first along longitudes, then along latitudes, and finally along
# time (structure of netcdf files). Here, we let the values increase with
# latitude and time only:

space <- c(1, 1, 1, 2, 2, 2)
spacetime <- c(space, 10 * space, 100 * space, 1000 * space)

pf2 <- pField(data = spacetime, lat = lat, lon = lon, time = time)

# Note that in this case, the number of data points must match the number of
# observations defined by lat, lon and time:

## Not run: 
x <- pField(data = spacetime, lat = -75, lon = lon, time = time)

## End(Not run)

# Since R starts to read any array along its first dimension, all of the
# following array shapes are identical with respect to the pfield object
# created:

# i) Matrix with rows corresponding to space and columns to time
data <- spacetime
dim(data) <- c(6, 4)
pf3 <- pField(data, lat = lat, lon = lon, time = time)

# ii) Vice versa
data <- spacetime
dim(data) <- c(4, 6)
pf4 <- pField(data, lat = lat, lon = lon, time = time)

# iii) Array with first dimension being longitude, second dimension being
#      latitude, and third dimension being time:
data <- spacetime
dim(data) <- c(3, 2, 4)
pf5 <- pField(data, lat = lat, lon = lon, time = time)

# However, note that if you change the order of observations in the input,
# the resulting pfield object will be different from the above examples!

data <- spacetime
dim(data) <- c(6, 4)
data <- t(data) # order of observations changes

pf.different <- pField(data, lat = lat, lon = lon, time = time)

EarthSystemDiagnostics/pfields documentation built on Jan. 10, 2022, 10:37 p.m.