# Author: An-Chi Ho
# Date: 13th July 2021
#--------------------------------------------------------------------------------
# This script shows how to define the dependency between file dimensions.
# Note that ex1_13 is for the dependency between one inner dimension and one file
# dimension (i.e., the usage of *_across), while this use case is for two file 
# dimensions (i.e., the usage of *_depends).

# The first case simply use indices() or 'all' to define the depending file dimension.
# In the second case, we use values() to define both the depended and depending 
# dimensions. The depending dimension should be a list with names that are the values
# of depended dimensions.
#--------------------------------------------------------------------------------

library(startR)

path <- paste0('/esarchive/exp/CMIP6/dcppA-hindcast/hadgem3-gc31-mm/',
               'cmip6-dcppA-hindcast_i1p1/DCPP/MOHC/HadGEM3-GC31-MM/dcppA-hindcast/',
               'r1i1p1f2/Omon/tos/gn/v20200417/',
               '$var$_Omon_HadGEM3-GC31-MM_dcppA-hindcast_s$sdate$-r1i1p1f2_gn_$chunk$.nc')

sdates <- c('2016', '2017', '2018')

# Case 1: Define the depending dimension ('chunk') by indices or 'all'

data1 <- Start(dat = path,
               var = 'tos',
               sdate = sdates,
               chunk = indices(2:4), # 'all' if you want to read all the files
               chunk_depends = 'sdate',
               time = 'all',
               i = indices(450:500),
               j = indices(650:700),
               time_across = 'chunk',
               merge_across_dims = TRUE,
               return_vars = list(time = 'sdate'),
               retrieve = TRUE)


dim(data1)
#  dat   var sdate  time     i     j 
#    1     1     3    36    51    51 
data1[1, 1, 1:3, 1:5, 1, 1]
#         [,1]     [,2]     [,3]     [,4]     [,5]
#[1,] 29.26021 29.73614 29.67156 29.61240 29.59503
#[2,] 29.37948 29.38624 29.73120 29.97264 29.89160
#[3,] 30.43721 30.58396 30.06479 30.51131 29.81269

#=====================================================================

# Case 2: Define the depended ('sdate') and depending ('chunk') dimensions by values
sdates <- c('2016', '2017', '2018')
chunks <- array(dim = c(chunk = 3, sdate = 3))
chunks[, 1] <- c("201701-201712", "201801-201812", "201901-201912")
chunks[, 2] <- c("201801-201812", "201901-201912", "202001-202012")
chunks[, 3] <- c("201901-201912", "202001-202012", "202101-202112")


data2 <- Start(dat = path,
               var = 'tos',
               sdate = sdates,
               # the names should be the values of the depended dimension 
               chunk = list('2016' = chunks[, 1], '2017' = chunks[, 2], '2018' = chunks[ ,3]),
               chunk_depends = 'sdate',
               time = 'all',
               i = indices(450:500),
               j = indices(650:700),
               time_across = 'chunk',
               merge_across_dims = TRUE,
               return_vars = list(time = 'sdate'),
               retrieve = TRUE)

dim(data2)
#  dat   var sdate  time     i     j 
#    1     1     3    36    51    51 

all.equal(as.vector(data1), as.vector(data2))
#[1] TRUE