diff --git a/inst/doc/usecase.md b/inst/doc/usecase.md index 880020d990e607a97631d80007bd84c3f91a6f79..8f02b8e1628a0911a394b4019be1970b26e29c7e 100644 --- a/inst/doc/usecase.md +++ b/inst/doc/usecase.md @@ -4,12 +4,22 @@ In this document, you can link to the example scripts for various demands. For t 1. **Retrieve data (use `Start()` only)** 1. [Interpolation in Start()](inst/doc/usecase/ex1_1_tranform.R) - Do the interpolation within Start(), and compare with Load() result. When the Start() parameter `transform_extra_cells = 2`, the two results will be the same. - 2. [Use s2dverification map plotting functions for exp and obs data](inst/doc/usecase/ex1_2_plotmap.R) - Use `s2dverification::PlotEquiMap, PlotStereoMap, PlotLayout` to visualize load-in data, and use the experimental data attributes to load in associated observational data. It also shows how to use parameters `xxx_reorder`, `xxx_across`, `merge_across_dims`, `split_multiselected_dims`. - 3. [Use experimental data attribute to load in oberservational data](inst/doc/usecase/ex1_3_attr_loadin.R) + Do the interpolation within Start(), and compare with Load() result. When the Start() parameter `transform_extra_cells = 2`, the two results will be the same. + + 2. [Load experimental and observational data with same dimension structure](inst/doc/usecase/ex1_2_exp_obs_attr.R) + This script tells you how to load experimental and observational data in a + consistent way, facilating the following comparison. In this case, experimental + data is one file per year, each file contains 12 months (time = 12). However, + observational data is one file per month, each file contains only one time step. + You can learn how to select all the required year and month for observation, and + tweak the dimension to make it consistent with experiment. + The highlight paramters used in this usecase are: **'*_across'**, + **'merge_across_dims'**, and **'split_multiselected_dims'**. + + 3. [Use experimental data attribute to load in oberservational data](inst/doc/usecase/ex1_3_attr_loadin.R) Load the experimental data first (with `retrieve = FALSE`), then retreive its dates and time attributes to use in the observational data load-in. It also shows how to use parameters `xxx_tolerance`, `xxx_across`, `merge_across_dims`, `split_multiselected_dims`. + 2. **Execute computation (use `Compute()`)** 1. [Function working on time dimension](inst/doc/usecase/ex2_1_timedim.R) 2. [Function using attributes of the data](inst/doc/usecase/ex2_2_attr.R) diff --git a/inst/doc/usecase/ex1_2_exp_obs_attr.R b/inst/doc/usecase/ex1_2_exp_obs_attr.R new file mode 100644 index 0000000000000000000000000000000000000000..de1926e426d74ed719950c8ea785a1f2c458c47b --- /dev/null +++ b/inst/doc/usecase/ex1_2_exp_obs_attr.R @@ -0,0 +1,117 @@ +#--------------------------------------------------------------------- +# This script tells you how to load experimental and observational data in a +# consistent way, facilating the following comparison. + +# First, we load the experimental data. Because the latitude order of observation +# is opposite with experiment, and the sdate/time dimension is also different, we +# use the attributes (sdate and latitude) of experimental data to define the +# selectors for observation. + +# You can see how to use parameter '*_across', 'merge_across_dims', and +# 'split_multiselected_dims' to create the consistent dimension as experiment. + +#--------------------------------------------------------------------- +library(startR) + +# exp +repos_exp <- paste0('/esarchive/exp/ecearth/a1tr/cmorfiles/CMIP/EC-Earth-Consortium/', + 'EC-Earth3/historical/r24i1p1f1/Amon/$var$/gr/v20190312/', + '$var$_Amon_EC-Earth3_historical_r24i1p1f1_gr_$sdate$01-$sdate$12.nc') + +exp <- Start(dat = repos_exp, + var = 'tas', + sdate = as.character(c(2005:2008)), + time = indices(1:3), + lat = 'all', + lon = 'all', + synonims = list(lat = c('lat', 'latitude'), + lon = c('lon', 'longitude')), + return_vars = list(lon = NULL, + lat = NULL, + time = 'sdate'), + retrieve = FALSE) + +# Retrieve attributes for the following observation. +# Because latitude order in experiment is [-90, 90] but in observation is [90, -90], +# latitude values need to be retrieved and used below. +lats <- attr(exp, 'Variables')$common$lat +# The 'time' attribute is dependent on 'sdate'. You can see the dimension below. +dates <- attr(exp, 'Variables')$common$time +# dim(dates) +#sdate ftime +# 4 3 + +#------------------------------------------- + +# obs +# 1. For lat, use experiment attribute. For lon, it is not necessary because they have +# same values. +# 2. For dimension 'date', it is a vector involving the first 3 months (ftime) of the four years (sdate). +# 3. Dimension 'time' is assigned by the matrix, so we can seperate 'sdate' and 'time' +# using 'split_multiselected_dims' later. +# 4. Because the 'time' is actually across all the files, so we need to specify +# 'time_across'. Then, use 'merge_across_dims' to make dimension 'date' disappears. +# At this moment, the dimension is 'time = 12'. +# 5. However, we want to seperate year and month (which are 'sdate' and 'ftime' in +# experimental data). So we use 'split_multiselected_dims' to split the two dimensions +# of dimension 'time'. + +repos_obs <- '/esarchive/recon/ecmwf/erainterim/monthly_mean/$var$_f6h/$var$_$date$.nc' + +obs <- Start(dat = repos_obs, + var = 'tas', + date = unique(format(dates, '%Y%m')), + time = values(dates), #dim: [sdate = 4, time = 3] + lat = values(lats), + lon = 'all', + time_across = 'date', + merge_across_dims = TRUE, + split_multiselected_dims = TRUE, + synonims = list(lat = c('lat', 'latitude'), + lon = c('lon', 'longitude')), + return_vars = list(lon = NULL, + lat = NULL, + time = 'date'), + retrieve = FALSE) + +#========================== +# Check attributes +#========================== + +##-----dimension----- +print(attr(exp, 'Dimensions')) +# dat var sdate time lat lon +# 1 1 4 3 256 512 + +print(attr(obs, 'Dimensions')) +# dat var sdate time lat lon +# 1 1 4 3 256 512 + +##-----time----- +print(attr(exp, 'Variables')$common$time) +# [1] "2005-01-16 13:14:44 CET" "2006-01-16 13:14:44 CET" +# [3] "2007-01-16 13:14:44 CET" "2008-01-16 13:14:44 CET" +# [5] "2005-02-15 01:14:44 CET" "2006-02-15 01:14:44 CET" +# [7] "2007-02-15 01:14:44 CET" "2008-02-15 13:14:44 CET" +# [9] "2005-03-16 13:14:44 CET" "2006-03-16 13:14:44 CET" +#[11] "2007-03-16 13:14:44 CET" "2008-03-16 13:14:44 CET" + +print(attr(obs, 'Variables')$common$time) +# [1] "2005-01-31 18:00:00 CET" "2006-01-31 18:00:00 CET" +# [3] "2007-01-31 18:00:00 CET" "2008-01-31 18:00:00 CET" +# [5] "2005-02-28 18:00:00 CET" "2006-02-28 18:00:00 CET" +# [7] "2007-02-28 18:00:00 CET" "2008-02-29 18:00:00 CET" +# [9] "2005-03-31 19:00:00 CEST" "2006-03-31 19:00:00 CEST" +#[11] "2007-03-31 19:00:00 CEST" "2008-03-31 19:00:00 CEST" + +##-----lat----- +print(attr(exp, 'Variables')$common$lat[1:3]) +#[1] -89.46282 -88.76695 -88.06697 +print(attr(exp, 'Variables')$common$lat[256]) +#[1] 89.46282 + +print(attr(obs, 'Variables')$common$lat[1:3]) +#[1] -89.46282 -88.76695 -88.06697 +print(attr(obs, 'Variables')$common$lat[256]) +#[1] 89.46282 + diff --git a/inst/doc/usecase/ex1_2_plotmap.R b/inst/doc/usecase/ex1_2_plotmap.R deleted file mode 100644 index f6230b4ccc16f19e0d3e17f0a4afd5121fcb7356..0000000000000000000000000000000000000000 --- a/inst/doc/usecase/ex1_2_plotmap.R +++ /dev/null @@ -1,130 +0,0 @@ -#--------------------------------------------------------------------- -# 1. Check the data with s2dverification map plotting functions -# 2. Read associated data of another data set matching the dates of the first one -# 3. How to use paramters `xxx_reorder`, `xxx_across`, `merge_across_dims`, `split_multiselected_dims` -#--------------------------------------------------------------------- -library(startR) -library(s2dverification) - -path <- '/esarchive/exp/ecearth/a0lg/monthly_mean/$var$_*/' -repos <- paste0(path, '$var$_*_S$sdate$_$member$_$chunk$.nc') -header <- Start(dat = repos, - var = 'tas', - member = indices(1:5), - sdate = indices(1:21 * 2), - chunk = 'all', - ftime = indices(1:3), - lat = 'all', - lon = 'all', - lat_reorder = Sort(), - lon_reorder = CircularSort(0, 360), - chunk_depends = 'sdate', - ftime_across = 'chunk', - merge_across_dims = TRUE, - split_multiselected_dims = TRUE, - synonims = list(ftime = 'time', - lat = c('lat', 'latitude'), - lon = c('lon', 'longitude')), - return_vars = list(lon = NULL, - lat = NULL, - time = 'sdate') - ) - -# ------ Check exp data ------ - attr(header, 'Dimensions') -# dat var member sdate ftime lat lon -# 1 1 5 21 3 256 512 -# ---------------------------- - -lon <- attr(header, 'Variables')$common$lon -lat <- attr(header, 'Variables')$common$lat - -data <- eval(header) #retrieve data - - -# check 5 members -PlotLayout(PlotEquiMap, - c('lon', 'lat'), - Subset(data, c('dat', 'var', 'sdate', 'ftime'), list(1, 1, 1, 1)), - lon, - lat, - fill = FALSE - ) - -# check 3 ftimes -PlotLayout(PlotEquiMap, - c('lon', 'lat'), - Subset(data, c('dat', 'var', 'sdate', 'member'), list(1, 1, 1, 1)), - lon, - lat, - fill = FALSE - ) - -# check 21 sdates -PlotLayout(PlotStereoMap, - c('lon', 'lat'), - Subset(data, c('dat', 'var', 'ftime', 'member'), list(1, 1, 1, 1)), - lon, - lat, - fill = FALSE - ) - - -#----------------------------- -# Associated obs data -#----------------------------- -dates <- attr(header, 'Variables')$common$time #use date attributes in exp data -#> dim(dates) -#sdate ftime -# 21 3 - -path <- '/esarchive/recon/ecmwf/erainterim/monthly_mean/$var$_*/' -repos <- paste0(path, '$var$_$date$.nc') -data_obs <- Start(dat = repos, - var = 'tas', - date = unique(format(dates, '%Y%m')), - ftime = values(dates), - lat = 'all', - lon = 'all', - lat_reorder = Sort(), - lon_reorder = CircularSort(0, 360), - # ftime continues along date - ftime_across = 'date', - # merge ftime and date into one dim - merge_across_dims = TRUE, - # separate ftime dimension, which is [sdate = 21, ftime = 3] - split_multiselected_dims = TRUE, - synonims = list(ftime = 'time', - lat = c('lat', 'latitude'), - lon = c('lon', 'longitude')), - return_vars = list(lon = NULL, - lat = NULL, - ftime = 'date') - ) -# ------ Check obs data ------ - attr(data_obs, 'Dimensions') -# dat var sdate ftime lat lon -# 1 1 21 3 256 512 -# ---------------------------- - -# retrieve obs data into workstation -data_obs <- eval(data_obs) - -# check 3 ftimes -PlotLayout(PlotEquiMap, - c('lon', 'lat'), - Subset(data_obs, c('dat', 'var', 'sdate'), list(1, 1, 1)), - attr(data_obs, 'Variables')$common$lon, - attr(data_obs, 'Variables')$common$lat, - fill = FALSE - ) - -# check 2 sdates -PlotLayout(PlotEquiMap, - c('lon', 'lat'), - Subset(data_obs, c('dat', 'var', 'sdate', 'ftime'), list(1, 1, 1:2, 1)), - attr(data_obs, 'Variables')$common$lon, - attr(data_obs, 'Variables')$common$lat, - fill = FALSE - ) -