% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/makeAggregatedDataset.R
\name{makeAggregatedDataset}
\alias{makeAggregatedDataset}
\title{Create a dataset from a collection of (netCDF) files}
\usage{
makeAggregatedDataset(
  source.dir,
  ncml.file,
  file.ext = "nc",
  aggr.dim = "time",
  pattern = NULL,
  recursive = FALSE,
  verbose = TRUE,
  timeUnitsChange = TRUE
)
}
\arguments{
\item{source.dir}{Parent directory containing the files to be aggregated}

\item{ncml.file}{Full path of the output NcML file}

\item{file.ext}{Character string indicating the extension of the CDM datasets
to be aggregated. Default to \code{nc} (netCDF).}

\item{aggr.dim}{Character string indicating the dimension along which the 
files will be concatenated. Default to \code{"time"}.}

\item{pattern}{An optional regular expression. Only file names which match the
regular expression will be considered in the aggregation 
(see \link[base]{regexp}). This argument can be useful in order to save time
when only a particular subset of variables from the whole collection is 
needed. Default to \code{NULL}, meaning that all files in the search path
are included (See next argument). See Notes.}

\item{recursive}{Logical. Should the listing of files to be aggregated recurse
into directories?. Default to \code{FALSE}. This is useful for instance when 
each variable is stored in a sepparate subdirectory.}

\item{verbose}{Logical. Should additional information of the NcML file creation
steps be printed on screen?. Default to \code{TRUE}.}

\item{timeUnitsChange}{Logical. Set the timeUnitsChange option,
useful when aggregating many files across the time dimension which have relative time axis.
Default to \code{TRUE}.}
}
\value{
Creates a NcML file at the specified location.
}
\description{
Creates virtual datasets by modifying and combining other datasets via NcML.
}
\details{
The NetCDF Markup Language (NcML) is an XML dialect that allows creating
CDM datasets (i.e.: any collection of scientific data which can be accessed
through the NetCDF-Java / CDM library). The NcML document refers to
another dataset called the referenced CDM dataset, generally composed on a
number of netCDF files (but also grib, hdf or many other binary file formats)
containing the geo-referenced data. This function creates a NcML file from
multiple CDM files that are conveniently combined ("aggregated") along the
selected dimension.
The use of NcML is not only intended for CDM file combination, and this function considers just a particular case.
NcML is a powerful, yet relatively simple way of dealing with large, complex datasets in a straightforward manner.
Among other capabilitities, NcML files can be generated in order to add/delete
metadata and variables to be renamed, added, deleted and restructured.
This function is intended for a simple operation of aggregation of collections of netCDF files,
as it is the most common case of gridded climate datasets.
}
\note{
The current implementation of the function only considers datasets in which each file stores
one single variable. For other dataset configurations, please refer to the NcML tutorial.

\emph{Wildcards} (or \emph{globbing}) patterns as used by most shells can be mapped to regular expression in R 
using \code{\link[utils]{glob2rx}}.
}
\references{
NcML Tutorial \url{http://www.unidata.ucar.edu/software/thredds/current/netcdf-java/ncml/Tutorial.html}. (Last accessed 14 Mar 2016.).
}
\seealso{
Other loading: 
\code{\link{loadCircularGridData}()},
\code{\link{loadGridData}()},
\code{\link{loadStationData}()}
}
\author{
J. Bedia, with contributions of E. Tourigny and A. Cofi√±o
}
\concept{loading}
