Changes between Version 12 and Version 13 of EcomsUdg/RPackage/Functions


Ignore:
Timestamp:
May 17, 2013 12:37:49 PM (8 years ago)
Author:
juaco
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • EcomsUdg/RPackage/Functions

    v12 v13  
    2020''__Details__''
    2121
     22* All files of the same dataset should be put together in the same directory, indicated by the `source.dir` argument.
     23* Currently the function works only with netCDF (''.nc'') file collections.
     24* A number of useful recommendations regarding dataset naming are provided [http://www.unidata.ucar.edu/software/netcdf-java/reference/DatasetUrls.html#NcmlScan here]
     25
     26''__Value__''
     27
     28Creates a NcML file at the specified location
     29
     30''__Notes__''
     31
    2232A NcML file is a [http://en.wikipedia.org/wiki/XML XML] representation of netCDF metadata. This is approximately the same information one gets when dumping the header of a netCDF file (e.g. by typing on the terminal the command `ncdump -h`). By means of NcML it is possible to create virtual datasets by modifying and  aggregating other datasets, thus providing maximum flexibility and ease of access to data stored in collections of files containing data from different variables/time slices. The function `makeNcmlDataset` is intended to deal with reanalysis, forecasts and other climate data products, often consisting of collections of netCDF files corresponding to different variables and partitioned by years/decades or other time slices. It operates by applying to types of [http://www.unidata.ucar.edu/software/netcdf/ncml/v2.2/Aggregation.html aggregation operations]:
    2333
     
    2737
    2838
    29 * All files of the same dataset should be put together in the same directory, indicated by the `source.dir` argument.
    30 * Currently the function works only with netCDF (''.nc'') file collections.
    31 * A number of useful recommendations regarding dataset naming are provided [http://www.unidata.ucar.edu/software/netcdf-java/reference/DatasetUrls.html#NcmlScan here]
     39
     40
     41
     42
    3243
    3344== dataInventory ==
     
    4051
    4152{{{
    42 dataInventory(dataset)
     53dataInventory(ncml.file)
    4354}}}
    4455
     
    4657''__Arguments__''
    4758
    48 * `dataset`: a character string indicating the full path to the virtual dataset (the `NcML` file). This can be either a path containing the directory and name of the file, or an appropriate URL in case the dataset is remotely accessed (e.g., via the [https://www.meteo.unican.es/trac/meteo/wiki/SpecsEuporias/DataServer/THREDDS SPECS-EUPORIAS THREDDS]).
     59* `ncml.file`: a character string indicating the full path to the virtual dataset (the `NcML` file). This can be either a path containing the directory and name of the file, or an appropriate URL in case the dataset is remotely accessed (e.g., via the [https://www.meteo.unican.es/trac/meteo/wiki/SpecsEuporias/DataServer/THREDDS SPECS-EUPORIAS THREDDS]).
    4960
    50 
    51 ''__Details__''
    52 
    53 A common user's need prior to data analysis, is to get an overview of all data available and their structure (variables, dimensions, units, geographical extent, time span ...). The function provides an overview of the raw data as they are stored in the original data files. The characteristics of the loaded data after using any of the functions for data access (e.g., `loadSystem4.R`) may change (for instance, after data transformation temperature may be provided in ºC instead of the originally stored K, and so on).
    54 
     61''__Value__''
    5562
    5663The output of the function consists of a list of variable length, depending on the number of variables contained in the dataset, following this structure:
    5764
    5865    * `Description`: Description of the variable
    59     * `Name`: Character string. Long name of the variable
    6066    * `DataType`: Character string indicating data type (i.e. float ...)
    6167    * `Units`: Character string indicating the units of the variable
    62     * `Shape`: A vector of ''n'' integers, where ''n''=number of dimensions, specifying the length of each dimension
     68    * `TimeStep`: A `difftime` class object representing the time interval between consecutive values in the time dimension axis
    6369    * `Dimensions`: A list of length ''n'', containing the following information for each of the ''n'' dimensions:
    6470       * `Type`: Character vector indicating the type of dimension (e.g. Time, Lon, Pressure ...)
    6571       * `Units`: Character vector indicating the units of the dimension axis
    66        * `Values`: A vector containing all the dimension values. This might be a vector of `POSIXlt` class in case of time type dimension, or numeric in other cases.
     72       * `Values`: A vector containing all the dimension values. This might be a vector of `POSIXlt` class in case of a dimension of type ''time'', or numeric in other cases.
     73
     74''__Details__''
     75
     76A common need prior to data analysis is to get an overview of all data available and their structure (variables, dimensions, units, geographical extent, time span ...). Note that the function provides an overview of the raw data as they are stored in the original data files. The units may change after loading the function if conversions are applied via dictionary.
    6777
    6878
    6979
    70 '''__3. loadSystem4.R__'''
    7180
    72 The ''SPECS-EUPORIAS Data Portal'' can be remotely accessed from R via the [mtl:browser:MLToolbox/trunk/MLToolbox_experiments/antonio/system4/r/loadSystem4.R loadSystem4.R] function. Note that this function is part of a more comprehensive R package currently under development. This function automatically cares about the proper location of the right indices for data sub-setting across the different variable dimensions, given a few simple arguments for subset definition. In addition, instead of retrieving a NetCDF file that needs to be opened and read, the requested data is directly loaded into the current R working session, according to a particular structure described below, prior to data analysis and/or representation.
    7381
    74 A worked example describing a multi-model selection of a dataset is presented in the tutorial, which can be downloaded [https://www.meteo.unican.es/trac/meteo/attachment/wiki/SpecsEuporias/DataPortal_Tutorial.pdf here], or in the section [wiki:SpecsEuporias/RPackage/Examples Examples]. 
    7582
    76 The request is simply formulated via the `loadSystem4` function:
     83
     84== loadSystem4 ==
     85
     86''__Description__''
     87
     88Loads hindcast/forecast data from ECMWF's System4 model by remotely accessing the SPECS-EUPORIAS THREDDS Data Server.
     89
     90''__Usage__'' 
     91
    7792{{{
    78 > loadSystem4(dataset, var, members, lonLim, latLim, season, years, leadMonth)
     93loadSystem4(dataset, var, members, lonLim, latLim, season, years, leadMonth)
    7994}}}
    8095
    81 The arguments of the function are the next described:
     96''__Arguments__''
    8297
    83 * `dataset`: A character string indicating the full URL path to the OPeNDAP dataset. Currently, the accepted values correspond to the System4 datasets described in Section [https://www.meteo.unican.es/trac/meteo/wiki/SpecsEuporias/DataServer/Datasets Datasets], for instance `http://www.meteo.unican.es/tds5/dodsC/system4/System4_Seasonal_15Members.ncml`, but using the `System4_Seasonal_15Members.ncml`, `System4_Seasonal_51Members.ncml` or `System4_Annual_15Members.ncml` ending strings depending on the dataset of choice.
     98* `dataset`: A character string indicating the full URL path to the OPeNDAP dataset. Currently, the accepted values correspond to the available [https://www.meteo.unican.es/trac/meteo/wiki/SpecsEuporias/DataServer/Datasets Datasets System4 datasets]
     99
     100/System4_Seasonal_15Members.ncml`, but using the `System4_Seasonal_15Members.ncml`, `System4_Seasonal_51Members.ncml` or `System4_Annual_15Members.ncml` ending strings depending on the dataset of choice.
    84101* `var`: Variable code. Argument values currently accepted are `tas`, `tasmin`, `tasmax`, `pr` or `mslp`, as internally defined in the vocabulary for System4 following the nomenclature displayed in the table below. However, note that new variables and datasets will be progressively included. Note that depending on the time step of the variable the units might be referred to different time aggregations. For instance, currently `mslp` is 6-hourly, and thus the 6-hourly mean value is returned for each time step. Similarly, 24-h accumulated values are returned for `pr`, and so on. Note that the ''instantaneous'' and ''aggregated'' fields in table below refer to the potential time step values that the variables may take, which does not mean that the resolution provided by the System4 model is necessarily that.
    85102
     
    98115* `leadMonth`: Lead month forecast time corresponding to the first month of the specified season. Note that `leadMonth = 1` for `season = 1` (January) corresponds to the December initialization forecasts. In this way the effect of the lead time forecast in the analysis of a particular season can be analyzed by just changing this parameter.
    99116
     117
     118
     119The ''SPECS-EUPORIAS Data Portal'' can be remotely accessed from R via the [mtl:browser:MLToolbox/trunk/MLToolbox_experiments/antonio/system4/r/loadSystem4.R loadSystem4.R] function. Note that this function is part of a more comprehensive R package currently under development. This function automatically cares about the proper location of the right indices for data sub-setting across the different variable dimensions, given a few simple arguments for subset definition. In addition, instead of retrieving a NetCDF file that needs to be opened and read, the requested data is directly loaded into the current R working session, according to a particular structure described below, prior to data analysis and/or representation.
     120
     121A worked example describing a multi-model selection of a dataset is presented in the tutorial, which can be downloaded [https://www.meteo.unican.es/trac/meteo/attachment/wiki/SpecsEuporias/DataPortal_Tutorial.pdf here], or in the section [wiki:SpecsEuporias/RPackage/Examples Examples]. 
    100122The output returned by the function consists of a list with the following elements providing the necessary information for data representation and analysis:
    101123