s2dv
===============
s2dv is the advanced version of package 's2dverification'. It is intended for
'seasonal to decadal' (s2d) climate forecast verification, but it can also be
used in other kinds of forecasts or general climate analysis.

This package is specially designed for the comparison between the experimental
and observational datasets. The functionality of the included functions covers
from data retrieval, data post-processing, skill scores against obeservation,
to visualization. Compared to 's2dverification', 's2dv' adopts the regime of
package 'multiApply'. Therefore, it is compatible with the package 'startR', 
able to use multiple cores for computation and handle multi-dimensional arrays 
with a higher flexibility than s2dverification.

Find more information about its previous package s2dverification on GitLab
<https://earth.bsc.es/gitlab/es/s2dverification/> or on the
CRAN website at
<https://cran.r-project.org/web/packages/s2dverification/index.html>.

A review of s2dverification package was published in the Environmental Modelling & Software journal.

> Manubens, N., L.-P. Caron, A. Hunter, O. Bellprat, E. Exarchou, N.S. Fučkar, J. Garcia-Serrano, F. Massonnet, M. Ménégoz, V. Sicardi, L. Batté, C. Prodhomme, V. Torralba, N. Cortesi, O. Mula-Valls, K. Serradell, V. Guemas, F.J. Doblas-Reyes (2018). An R Package for Climate Forecast Verification. Environmental Modelling & Software, 103, 29-42, doi:10.1016/j.envsoft.2018.01.018


Installation
------------

s2dv has a system dependency, the CDO libraries, for interpolation of grid data
and retrieval of metadata. Make sure you have these libraries installed in the
system or download and install from
<https://code.zmaw.de/projects/cdo>.

You can then install the public released version of s2dverification from CRAN:
```r
install.packages("s2dv")
```
Or the development version from the GitLab repository:
```r
# install.packages("devtools")
devtools::install_git("https://earth.bsc.es/gitlab/es/s2dv.git")
```

Overview
--------

The s2dv scheme is composed of four modules:  
**Data retrieval** -> **Statistics** -> **Verification** -> **Visualisation**  

- [**Data retrieval**](vignettes/data_retrieval.md) module: The first step is to gather and homogenize NetCDF data 
files from forecasts, hindcasts or observations stored in a local or remote file 
system. Some simple previous steps are required, however, to set up some 
configuration parameters so that the module can locate the source files and 
recognize the variables of interest.

- [**Statistics**](vignettes/statistics.md) module: Once the data has been loaded into an R object, some
statistics can be computed, such as drift-corrected anomalies, trend removal, 
frequency filtering and more.

- [**Verification**](vignettes/ScoringForecast.md) module: Either after computing statistics or directly from 
the original data, the verification functions allow you to compute deterministic 
and probabilistic scores and skill scores such as root mean square error and 
correlation with reliability indicators such as p-values and confidence intervals.

- [**Visualization**](vignettes/visualisation.md) module: Plotting functions are also provided to plot the 
results obtained from any of the modules above.

If it's your first time using s2dv you can check an 
[**Example**](vignettes/example.md) 
of use spanning its four modules or review the 
[**Tutorial**](vignettes/tutorial.md).  
You will find more detailed examples in the documentation page of each module.  

One important feature of s2dv is the named dimension of the data array. All the 
data input of the functions should have names for all the dimensions. It should 
not be a problem since the data retrieved by s2dv::Load or startR::Start have 
named dimension inherently. Take the sample data in s2dv as an example:  
```r
sampleData <- s2dv:::.LoadSampleData('tos', c('experiment'), c('observation'), 
                                     '19901101', leadtimemin = 1, leadtimemax = 4,
                                     output = 'lonlat',
                                     latmin = 27, latmax = 48,
                                     lonmin = -12, lonmax = 40)
# It returns an object 'sampleData'
dim(sampleData$mod)
dataset  member   sdate   ftime     lat     lon 
      1       3       1       4       2       3 
dim(sampleData$obs)
dataset  member   sdate   ftime     lat     lon 
      1       1       1       4       2       3 
```
The feature provides security during the analysis, ensuring that the dimensions 
under operation are the desired ones.


Contribute
----------

If you have a function to share in this package of do you want to improve a function, your contribution will be very welcomed to the package.

Please, in order to achieve our goal, follow these steps:

1. Open an issue to contact the maintainers (@abatalla) and agree in the suitability of your development in the package.
2. Create a branch with an identificative name: starting by 'develop-' and followed by a word releated to the development (e.g.: 'develop-Persistance' for function Persistance)
3. Add you function to folder R and create the documentation in roxyegen2 format or modify a function in the package following the discussion on the previous issue.
4. Do as many modifications and pushes as needed to achieve the desired result.
5. Open a merge request and tag the maintainers to review the function or to contact an expert to carry the review.
6. Keep working on the modification until the final result is obtained.
7. Let the maintainers know the development is finished to let them finalize the standarization with master branch.

More information on questions, contributions and bug reports can be found in  [**CONTRIBUTING.md**](CONTRIBUTING.md).
