\title{Save multidimensional R arrays into NetCDF files}
\description{This function takes as input one or a list of multidimensional R arrays and stores them in a NetCDF file, using the \code{ncdf4} package. The full path and name of the resulting file must be specified. Metadata can be attached to the arrays and propagated into the NetCDF file in 3 possible ways:\cr
...
...
@@ -7,7 +7,7 @@
\item{Via the list names if a list of arrays is provided:}{Each name in the input list, corresponding to one multidimensional array, will be interpreted as the name of the variable it contains.\cr
\item{Via the attribute 'variables' of each provided array:}{The arrays can be provided with metadata in an attribute named 'variables', which is expected to be a named list of named lists, where the names of the container list are the names of the variables present in the provided array, and where each sub-list contains metadata for each of the variables. The attribute names and values supported in the sub-lists must follow the same format the package \code{ncdf4} uses to represent the NetCDF file headers.\cr
...
...
@@ -31,17 +31,17 @@ metadata <- list(
)
attr(a, 'variables') <- metadata
names(dim(a)) <- c('lat', 'lon', 'time', 'var')
ArrayToNetCDF(a, 'tmp.nc')
ArrayToNc(a, 'tmp.nc')
}
}
}
The special dimension names are 'var'/'variable' and 'time'.\cr
If a dimension is named 'var' or 'variable', \code{ArrayToNetCDF} will interpret each array entry along such dimension corresponds to a separate new variable, hence will create a new variable inside the NetCDF file and will use it to store all the data in the provided array for the corresponding entry along the 'var'/'variable' dimension.\cr
If a dimension is named 'var' or 'variable', \code{ArrayToNc} will interpret each array entry along such dimension corresponds to a separate new variable, hence will create a new variable inside the NetCDF file and will use it to store all the data in the provided array for the corresponding entry along the 'var'/'variable' dimension.\cr
If a dimension is named 'time', by default it will be interpreted and built as an unlimited dimension. The 'time' dimension must be the last dimension of the array (the right-most). If a 'var'/'variable' dimension is present, the 'time' dimension can be also placed on its left (i.e. the one before the last dimension). The default behaviour of creating the 'time' as unlimited dimension can be disabled by setting manually the attribute \code{unlim = FALSE}, as shown in the previous example.\cr\cr
Computes seasonal means on timeseries organized in a array of any number of dimensions up to 10 dimensions where the time dimension is one of those 10 dimensions.
Close a \code{ncdf4} open connection to a file.
}
\usage{
Season(var, posdim = 4, monini, moninf, monsup)
NcClose(file_object)
}
\arguments{
\item{var}{
Array containing the timeseries along one of its dimensions.
}
\item{posdim}{
Dimension along which to compute seasonal means = Time dimension
}
\item{monini}{
First month of the time series: 1 to 12.
}
\item{moninf}{
Month when to start the seasonal means: 1 to 12.
}
\item{monsup}{
Month when to stop the seasonal means: 1 to 12.
\item{file_object}{
NetCDF object as returned by \code{ncdf4::nc_open}.
}
}
\value{
Array with the same dimensions as var except along the posdim dimension whose length corresponds to the number of seasons. Partial seasons are not accounted for.
Computes seasonal means on timeseries organized in a array of any number of dimensions up to 10 dimensions where the time dimension is one of those 10 dimensions.
Silently opens a NetCDF file with \code{ncdf4::nc_open}. Returns NULL on failure.
}
\usage{
Season(var, posdim = 4, monini, moninf, monsup)
NcOpen(file_path)
}
\arguments{
\item{var}{
Array containing the timeseries along one of its dimensions.
\item{file_path}{
Character string with the path to the file to be opened.
}
\item{posdim}{
Dimension along which to compute seasonal means = Time dimension
}
\item{monini}{
First month of the time series: 1 to 12.
}
\item{moninf}{
Month when to start the seasonal means: 1 to 12.
}
\item{monsup}{
Month when to stop the seasonal means: 1 to 12.
}
}
\value{
Array with the same dimensions as var except along the posdim dimension whose length corresponds to the number of seasons. Partial seasons are not accounted for.
A NetCDF object as returned by \code{ncdf4::nc_open} or NULL on failure.
Reads the dimension names and sizes of a set of variables in a NetCDF file, using the package \code{ncdf4}. The different variables in the file are considered to be stored along a dimension called 'var', so reading the dimensions of a variable 'foo' with dimensions 'lat' and 'lon' would result in a vector with the format c('var' = 1, 'lat' = n_lats, 'lon' = n_lons).
}
\usage{
NcReadDims(file_to_read, var_names = NULL)
}
\arguments{
\item{file_to_read}{
Path to the file to be read or a NetCDF object as returned by \code{easyNCDF::NcOpen} or \code{ncdf4::nc_open}.
}
\item{var_names}{
Vector of character strings with the names of the variables which to read the dimensions for. If multiple variables are requested, their dimensions will be merged and returned in a single vector.
}
}
\value{
Named numeric vector with the names and sizes of the dimensions for the requested variables.
}
\examples{
}
\author{
History:\cr
0.0 - 2017-03 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Original code
Reads one or a set of variables together with metadata items from a NetCDF file into an R array. Indices to retrieve (not necessarily consecutive) can be specified for each of the dimensions. Depending on the format of the request, the variables will be merged in into a single extended array or returned in a list with an array for each variable. The different variables in the file are considered to be stored along a dimension called 'var', so reading a variable 'foo' with dimensions 'lat' and 'lon' would result in an array with the dimensions c('var' = 1, 'lat' = n_lats, 'lon' = n_lons).
Path to the file to be read or a NetCDF object as returned by \code{easyNCDF::NcOpen} or \code{ncdf4::nc_open}.
}
\item{dim_indices}{
Named list with numeric vectors of indices to take for each dimension. The names should correspond to the dimension names which to take the indices for. Non-consecutive indices can be specified. If \code{expect_all_indices = FALSE} (default), it is not mandatory to specify the indices for all (or even any of) the dimensions. In that case all the indices along such dimensions will be read in. If \code{expect_all_indices = TRUE}, then indices for all the dimensions have to be specified for the function to return a data array. In that case, \code{NA} can be used to request all indices for a dimension if desired.
\cr\cr
Since this function considers the variables in a NetCDF file are stored along a 'var' dimension, indices for the (actually non-existing) 'var'/'variable' dimension can be specified. They can be specified in 3 ways:\cr
- A vector of numeric indices: e.g. \code{list(var = c(1, 3, 5))} to take the 1st, 3rd and 5th found variables.\cr
- A vector of character strings with variable names: e.g. \code{list(var = c('foo', 'bar'))}.\cr
- A list of vectors with numeric indices or character strings: e.g. \code{list(var = list(c(1, 3, 'foo'), c(2, 'bar')))}\cr
Vectors with combined numeric indices and character strings are accepted.\cr
Whereas the first two options will return a single extended array with the merged variables, the second option will return a list with an array for each requested variable.
}
\item{drop_var_dim}{
Whether to drop the 'var' dimension this function assumes (read description). If multiple variables are requested in a vector and \code{unlist = TRUE}, the drop won't be performed (not possible).
}
\item{unlist}{
Whether to merge the resulting array variables into a single array if possible (default) or not. Otherwise a list with as many arrays as requested variables is returned.
}
\item{expect_all_indices}{
Whether the function should stop if indices are not provided for all the dimensions of any of the requested variables rather than assuming that all the indices are requested for the unspecified dimensions. By default the later is done.
}
\item{allow_out_of_range}{
Whether to allow indices out of range (simply disregard them) or to stop if indices out of range are found.
}
}
\value{
Array or list of arrays with the data for one or more than one of the requested variables (depending on the parameters). The dimensions are named. The arrays contain the attribute 'variables' with the metadata items found in the NetCDF file.
}
\examples{
}
\author{
History:\cr
0.0 - 2017-03 (N. Manubens, \email{nicolau.manubens at bsc.es}) - Original code
Computes seasonal means on timeseries organized in a array of any number of dimensions up to 10 dimensions where the time dimension is one of those 10 dimensions.
}
\usage{
Season(var, posdim = 4, monini, moninf, monsup)
}
\arguments{
\item{var}{
Array containing the timeseries along one of its dimensions.
}
\item{posdim}{
Dimension along which to compute seasonal means = Time dimension
}
\item{monini}{
First month of the time series: 1 to 12.
}
\item{moninf}{
Month when to start the seasonal means: 1 to 12.
}
\item{monsup}{
Month when to stop the seasonal means: 1 to 12.
}
}
\value{
Array with the same dimensions as var except along the posdim dimension whose length corresponds to the number of seasons. Partial seasons are not accounted for.
Computes seasonal means on timeseries organized in a array of any number of dimensions up to 10 dimensions where the time dimension is one of those 10 dimensions.
}
\usage{
Season(var, posdim = 4, monini, moninf, monsup)
}
\arguments{
\item{var}{
Array containing the timeseries along one of its dimensions.
}
\item{posdim}{
Dimension along which to compute seasonal means = Time dimension
}
\item{monini}{
First month of the time series: 1 to 12.
}
\item{moninf}{
Month when to start the seasonal means: 1 to 12.
}
\item{monsup}{
Month when to stop the seasonal means: 1 to 12.
}
}
\value{
Array with the same dimensions as var except along the posdim dimension whose length corresponds to the number of seasons. Partial seasons are not accounted for.
