# Author: An-Chi Ho
# Date: 20th Aug. 2020
#---------------------------------------------------------------------
# This script tells you how to use the parameter 'metadata_dims' in Start()
# to get the complete variable metadata. You will see four difference cases
# and there are some rules can be followed:
# (1) If the length of 'dat'/'var' is more than 1, you need to assign that
#     file dimension in 'metadata_dims'
# (2) If there is more than one 'dat', the metadata will be stored under 
#     $<dat_name> in the attributes.
# (3) If there is only one 'dat', or 'dat' is not in 'metadata_dims', the 
#     metadata will be stored under $common in the attributes.
# You can find more explanation in FAQ How-to-20.

#---------------------------------------------------------------------
library(startR)

# Case 1: One dat, one var

  repos <- "/esarchive/exp/ecmwf/system5_m1/monthly_mean/$var$_f6h/$var$_$sdate$.nc"
  data <- Start(dat = list(list(name = 'system5_m1', path = repos)),
                var = 'tas',
                sdate = '20170101',
                ensemble = indices(1),
                time = indices(1),
                lat = indices(1:10),
                lon = indices(1:10),
                synonims = list(lat = c('lat', 'latitude'),
                                lon = c('lon', 'longitude')),
                return_vars = list(time = 'sdate',
                                   longitude = 'dat',
                                   latitude = 'dat'),
                metadata_dims = 'dat',  # it can be omitted since it is automatically specified as 'dat'
                retrieve = T
               )

str(attr(data, 'Variables'))
# 'tas' is under $common
List of 2
 $ common    :List of 2
  ..$ time: POSIXct[1:1], format: "2017-02-01"
  ..$ tas :List of 12
  .. ..
  .. ..
  .. ..
 $ system5_m1:List of 2
  ..$ longitude: num [1:10(1d)] 0 0.278 0.556 0.833 1.111 ...
  .. ..
  .. .. 
  .. .. 
  ..$ latitude : num [1:10(1d)] 89.8 89.5 89.2 88.9 88.7 ...
  .. ..
  .. ..


# Case 2: One dat, two vars
  repos <- 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_185001-185012.nc')
  var <- c('tas', 'clt')
  sdate <- '20170101'

  data <- Start(dat = repos,
                var = var,
                time = indices(1),
                lat = indices(1:10),
                lon = indices(10:19),
                return_vars = list(lat = NULL, lon = NULL),
                metadata_dims = 'var',
                synonims = list(lat = c('lat', 'latitude'),
                                lon = c('lon', 'longitude')),
                retrieve = TRUE
               )

str(attr(data, 'Variables'))
# 'tas' and 'clt' are under $common
List of 2
 $ common:List of 4
  ..$ lat: num [1:10(1d)] -89.5 -88.8 -88.1 -87.4 -86.7 ...
  .. ..
  ..$ lon: num [1:10(1d)] 6.33 7.03 7.73 8.44 9.14 ...
  .. ..
  ..$ tas:List of 17
  .. ..
  ..$ clt:List of 16
  .. ..
 $ dat1  : NULL

# NOTE: If the above script is changed to metadata_dims = 'dat', you can only find
#       'tas' under $common


# Case 3: Two dats, one var
  repos <- "/esarchive/exp/ecmwf/system5_m1/monthly_mean/$var$_f6h/$var$_$sdate$.nc"
  repos2 <- "/esarchive/exp/ecmwf/system4_m1/monthly_mean/$var$_f6h/$var$_$sdate$.nc"

  data <- Start(dat = list(list(name = 'system4_m1', path = repos2),
                           list(name = 'system5_m1', path = repos)),
                var = 'tas',
                sdate = '20170101',
                ensemble = indices(1),
                time = indices(1),
                lat = indices(1:10),
                lon = indices(1:10),
                synonims = list(lat = c('lat', 'latitude'),
                                lon = c('lon', 'longitude')),
                return_vars = list(time = 'sdate',
                                   longitude = 'dat',
                                   latitude = 'dat'),
                metadata_dims = 'dat',  # it can be omitted since it is automatically specified as 'dat'
                retrieve = T
               )

str(attr(data, 'Variables'))
# 'tas' is under both $system4_m1 and $system5_m1
List of 3
 $ common    :List of 1
  ..$ time: POSIXct[1:1], format: "2017-02-01"
 $ system4_m1:List of 3
  ..$ longitude: num [1:10(1d)] 0 0.703 1.406 2.109 2.812 ...
  .. ..
  ..$ latitude : num [1:10(1d)] 89.5 88.8 88.1 87.4 86.7 ...
  .. ..
  ..$ tas      :List of 11
  .. ..
 $ system5_m1:List of 3
  ..$ longitude: num [1:10(1d)] 0 0.278 0.556 0.833 1.111 ...
  .. ..
  ..$ latitude : num [1:10(1d)] 89.8 89.5 89.2 88.9 88.7 ...
  .. ..
  ..$ tas      :List of 12
  .. ..


# Case 4: Two dats, two vars
  repos <- "/esarchive/exp/ecmwf/system5_m1/monthly_mean/$var$_f6h/$var$_$sdate$.nc"
  repos2 <- "/esarchive/exp/ecmwf/system4_m1/monthly_mean/$var$_f6h/$var$_$sdate$.nc"

  data <- Start(dat = list(list(name = 'system4_m1', path = repos2),
                           list(name = 'system5_m1', path = repos)),
                var = c('tas', 'sfcWind'),
                sdate = '20170101',
                ensemble = indices(1),
                time = indices(1),
                lat = indices(1:10),
                lon = indices(1:10),
                synonims = list(lat = c('lat', 'latitude'),
                                lon = c('lon', 'longitude')),
                return_vars = list(time = 'sdate',
                                   longitude = 'dat',
                                   latitude = 'dat'),
                metadata_dims = c('dat', 'var'),
                retrieve = T
               )

str(attr(data, 'Variables'))
# 'tas' and 'sfcWind' are under both $system4_m1 and $system5_m1
List of 3
 $ common    :List of 1
  ..$ time: POSIXct[1:1], format: "2017-02-01"
 $ system4_m1:List of 3
  ..$ longitude: num [1:10(1d)] 0 0.703 1.406 2.109 2.812 ...
  .. ..
  ..$ latitude : num [1:10(1d)] 89.5 88.8 88.1 87.4 86.7 ...
  .. ..
  ..$ tas      :List of 11
  .. ..
  ..$ sfcWind  :List of 11
  .. ..
 $ system5_m1:List of 4
  ..$ longitude: num [1:10(1d)] 0 0.278 0.556 0.833 1.111 ...
  .. ..
  ..$ latitude : num [1:10(1d)] 89.8 89.5 89.2 88.9 88.7 ...
  .. ..
  ..$ tas      :List of 12
  .. ..
  ..$ sfcWind  :List of 12
  .. ..

#NOTE: If metadata_dims = 'dat', only 'tas' is under each dat.
#      If metadata_dims = 'var', 'tas' and 'sfcWind' will be under $common.

