# Usecase scripts

In this document, you can link to the example scripts for various demands. For the beginners, it is highly recommended to read the [practical guide](inst/doc/practical_guide.md) carefully first. You can find basic scripts and the configuration for different machines there.

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. [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 
   twist the dimensions to make them 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)  
      Like ex1_2, it shows how to retrieve the experimental data and observational data 
in a comparable structure. It also shows how to use parameters `xxx_tolerance`, `xxx_across`, `merge_across_dims`, `merge_across_dims_narm`, and `split_multiselected_dims`.  
It is recommended reading ex1_2 first since there is more explanation.
   
   4. [Checking impact of start date order in the number of members](inst/doc/usecase/ex1_4_variable_nmember.R)  
      Mixing start dates of different months can lead to load different number of members, check the code provided and the [FAQ 10](/inst/doc/faq.md).

   5. [Use reorder functions to get desired lat/lon region](inst/doc/usecase/ex1_5_latlon_reorder.R)  
      This script shows you how to use reorder function (`Sort()`, `CircularSort()`) to 
get the desired longitude and latitude region. See [FAQ How-to-#11](inst/doc/faq.md#11-select-the-longitudelatitude-region)
for more explanation.

   6. [Loading gridpoint data](inst/doc/usecase/ex1_6_gridpoint_data.R)  
      **Start** can be used to load single point data by providing a vector of longitudes and latitudes. This use case also ilustrates how to reformat it to get a 'gridpoint' dimension.

   7. [Use split and merge parameters together](inst/doc/usecase/ex1_7_split_merge.R)  
      This usecase shows the things to be noticed when the parameters 'split_multiselected_dims' and 'merge_across_dims' are both used. 
The problem may occur when the dimension number of the splitted selector is more than two. If you are not familiar with the usage of these parameters, please see usecases ex1_2 and ex1_3 first, which are less complicated. You can also go to FAQ How-to-#17 for more explanation.

   8. [Loading tas and tos from Decadal Predictions performed with the EC-Earth model](inst/doc/usecase/ex1_8_tasandtos.R)  
      Some climate indices needs to be computed loading 'tas' (air temperature at 2m) over land and 'tos' (ocean surface temperature) over sea. Using **startR**, you can load these data in a unique **Start** call or with multiple calls separately for each variable.

   9. [Use glob expression * to define the path](inst/doc/usecase/ex1_9_path_glob_permissive.R)  
      This script shows you how to use glob expression '*' and the parameter 'path_glob_permissive' of Start(). You can also find information in [FAQ How-to-18](inst/doc/faq.md#18-use-glob-expression-to-define-the-file-path).

   10. [Use 'metadata_dims' to retrieve complete variable metadata](inst/doc/usecase/ex1_10_metadata_dims.R)  
       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 learn the rules. You can find more explanation in FAQ [How-to-20](inst/doc/faq.md#20-use-metadata_dims-to-retrieve-variable-metadata).

   11. [Three methods to load experimental files with different member and version](inst/doc/usecase/ex1_11_expid_member_version.R)  
       This script shows three ways to load the data with different expid - member - version combination. It is useful for climate prediction of multiple experiments.

   12. [Load and plot data in rotated coordintaes](inst/doc/usecase/ex1_12_rotated_coordinates.R)  
       This script shows how to load and plot data in rotated coordinates using **Monarch-dust** simulations.  

       <img src="inst/doc/figures/Rotated_Coordinates.png" width="400" /> 

   13. [Use value array as selector to express dependency](inst/doc/usecase/ex1_13_implicit_dependency.R)  
       This script shows how to use a value array as the inner dimension selector to express dependency on a file dimension. By this means, we do not need to specify the *_across parameter and Start() can recognize this dependecy relationship.

   14. [Specify the dependency between file dimensions](inst/doc/usecase/ex1_14_file_dependency.R)  
       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).

   15. [Load irregular grid data](inst/doc/usecase/ex1_15_irregular_grid_CDORemap.R)  
       This script shows how to use Start() to load irregular grid data , then regrid it by s2dv::CDORemap. 

   16. [Merge files with different time dimension length](inst/doc/usecase/ex1_16_files_different_time_dim_length.R)  
       This script shows how to use Start() to load files with different time dimension length and reshape the array without undesired NAs.



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)  
      Using attributes is only available in startR_v0.1.3 or above.

   3. [Use function CDORemap for interpolation](inst/doc/usecase/ex2_3_cdo.R)  
      Using parameter `CDO_module` is only available in startR_v0.1.3 or above. Interpolate data by using `s2dv::CDORemap` in the workflow. 

   4. [Use two functions in workflow](inst/doc/usecase/ex2_4_two_func.R)  

   5. [RainFARM precipitation downscaling](https://earth.bsc.es/gitlab/es/startR/-/blob/develop-RainFARMCase/inst/doc/usecase/ex2_5_rainFARM.R)  
      This example shows how to apply a statistical downscaling function with startR and simultaneously (considering the memory size if unnecessary dimensions are included) saves the data by chunks (e.g., chunking those dimensions which are not required for downscaling) in the esarchive format. It is not recommended to save big outputs. Consider to perform some analysis and then retrieve the result instead of saving data. This is a simplified example of RainFARM for more information visit: https://www.medscope-project.eu/products/data/. 
Find more explanation of this use case in FAQ [How-to-27](inst/doc/faq.md#27-utilize-chunk-number-in-the-function).

   6. [Use external parameters in atomic function](inst/doc/usecase/ex2_6_ext_param_func.R)  

   7. [Calculate the ensemble-adjusted Continuous Ranked Probability Score (CRPS)](inst/doc/usecase/ex2_7_seasonal_forecast_crps.R)  
      Use `SpecsVerification::EnsCrps` to calculate the ensemble-adjusted Continuous Ranked Probability Score (CRPS) for ECWMF experimental data, and do ensemble mean. Use `s2dv::PlotEquiMap` to plot the CRPS map.  

   8. [Use CSTools Calibration function](inst/doc/usecase/ex2_8_calibration.R)  
      Use `CSTools:::.cal`, the interior function of `CSTools::CST_Calibration`, to do the bias adjustment for ECMWF experimental monthly mean data. 

   9. [Use a mask to apply different methods to different gridpoints](inst/doc/usecase/ex2_9_mask.R)  
      If you need to apply your analysis in a few gridpoints, you may want to consider use case 1.6, but if you need to load a lot of grid points, maybe this a better solution.

   10. [Apply an existing mask on data](inst/doc/usecase/ex2_10_existing_mask.R)  
       This use case shows you how to apply the existing mask file on your data. If you need to create the mask file on your own, go to ex2_9_mask.R.

   11. [Two datasets with different length of target dimensions](inst/doc/usecase/ex2_11_two_dat_inconsistent_target_dim.R)  
       This use case uses experimental and the corresponding observational data to calculate the temporal mean and spatial weighted mean. Notice that the spatial resolutions of the two datasets are different, but it still works because lat and lon are target dimensions.

   12. [Transform and chunk spatial dimensions](inst/doc/usecase/ex2_12_transform_and_chunk.R)  
       This use case provides an example of transforming and chunking latitude and longitude dimensions. 

   13. [Load irregular grid data and interpolate it in the workflow](inst/doc/usecase/ex2_13_irregular_regrid.R)
      This script shows how to load irregular grid data by Start(), then regrid it
by s2dv::CDORemap in the workflow. It is a solution before Start() can deal with irregular regridding directly.

3. **Verification workflows**
  1. [Weekly ECV Subseasonal Hindcast Verification](inst/doc/usecase/ex3_1_SubseasonalECVHindcast.md)
      This is a practical case to compute monthly skill scores for the ECMWF/S2S-ENSForhc 
subseasonal hindcast using as a reference dataset ERA5. The ECV is air temperature at surface level (tas). 
Note that since this case is practical, it is heavy and takes much time to finish running.

