---
title: "Run the 'JWSACruncher' with rjwsacruncher"
date: "`r Sys.Date()`"
output: 
  html_document:
    toc: true
    toc_depth: 2
    toc_float: true
vignette: >
  %\VignetteIndexEntry{Run the 'JWSACruncher' with rjwsacruncher}
  %\VignetteEngine{knitr::rmarkdown}
  \usepackage[utf8]{inputenc}
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, size = "small")
library(knitr)
library(rjwsacruncher)
```


# Launch the 'JWSACruncher"

To use `rjwsacruncher` you need to download the JWACruncher. 
It is available on <https://github.com/jdemetra/jdemetra-app/releases> (for JDemetra+ 2.x.y versions) or <https://github.com/jdemetra/jdplus-main/releases> (for JDemetra+ 3.x.y versions).
It can also be downloaded with the function `download_cruncher()`:
```{r, eval = FALSE}
library(rjwsacruncher)
# Directory where to save the JWSACruncher:
directory <- tempdir()
download_cruncher(directory)
# for JDemetra+ 3.x.y versions :
download_cruncher(directory, v3 = TRUE)
```

To configure the JWSACruncher with a portable version of Java you can use the function `configure_jwsacruncher()`. 
See `?configure_jwsacruncher` for more informations.

To run the JWSACruncher you need three files:

- a ".param" file containing the refresh policy and the items of the seasonal adjustment to export;  
- a valid JDemetra+ workspace;
- the path to the JWSACruncher.

In rjwsacruncher, there are four functions associated to run the JWSACruncher:  

- `create_param_file()` or `list2param_file()` to create the ".param" parameter file;  
- `cruncher()` to run the JWSACruncher on a workspace from a parameter file;  
- `cruncher_and_param()` to run the 'JWSACruncher' on a workspace while creating the parameter file;
- `update_workspace()` to update a workspace without exporting the results.

## Create the parameter file with `create_param_file()`

The parameters of the function `create_param_file()` are those described in the wiki of the JWSACruncher: <https://github.com/jdemetra/jwsacruncher/wiki>. 
The three most important parameters of `create_param_file()` are:  

1. `policy` the refresh policy (see table below).

```{r,echo=FALSE}
refresh_policy <- data.frame(`Option on JDemetra+` = c(
  "Current[AO]: fixed model + AO for new data",
  "Fixed model", 
"Estimate regression coefficients", 
"Estimate regression coefficients + MA parameters of the ARIMA model", 
"Estimate regression coefficients + Arima parameters", 
"Estimate regression coefficients + Last outliers", 
"Estimate regression coefficients + all outliers", 
"Estimate regression coefficients + Arima model", 
"Concurrent"), 
`Option for the JWSACruncher` = c(
  "current", "fixed", "fixedparameters",  "fixedarparameters",
"parameters (by default)", "lastoutliers", "outliers", 
"stochastic", "complete (or concurrent)"),
`Short name` = c(
  "n", "f", "fp", "farp", "p", "l", "o", "s", "c"
),
Description = c(
   "The ARIMA model, outliers and other regression parameters are not re-identified and the values of all parameters are fixed. The transformation type remains unchanged. An additive outlier (AO) is added for new data. (since v.2.2.3)",
  "The ARIMA model, outliers and other regression parameters are not re-identified and the values of all parameters are fixed. The transformation type remains unchanged. (since v.2.2.3)", 
"The ARIMA model, outliers and other regression parameters are not re-identified. The coefficients of the ARIMA model are fixed, other coefficients are re-estimated. The transformation type remains unchanged.", 
"The ARIMA model, outliers and other regression parameters are not re-identified. The AR coefficients of the ARIMA model are fixed, other coefficients are re-estimated (MA coefficients + regressors). The transformation type remains unchanged. (since v.3.4.0)", 
"The ARIMA model, outliers and other regression parameters are not re-identified. All parameters of the RegARIMA model are re-estimated. The transformation type remains unchanged.", 
"The ARIMA model, outliers (except from the outliers in the last year of the sample) and other regression parameters are not re-identified. All parameters of the RegARIMA model are re-estimated. The outliers in the last year of the sample are re-identified. The transformation type remains unchanged.", 
"The ARIMA model and regression parameters, except from outliers) are not re-identified. All parameters of the RegARIMA model are re-estimated. All outliers are re-identified. The transformation type remains unchanged.", 
"Re-identification of the ARIMA model, outliers and regression variables, except from the calendar variables. The transformation type remains unchanged.", 
"Re-identification of the whole RegARIMA model."), 
check.names = FALSE
)

refresh_policy[-c(1, nrow(refresh_policy)), 1] <-  paste("Partial concurrent adjustment ->", refresh_policy[-c(1, nrow(refresh_policy)), 1])
kable(refresh_policy, caption = "Refresh policies",
      booktabs = TRUE)
```

2. `matrix_item` character containing the items of the matrix output. By default, the items defined in the option `default_matrix_item` are exported. To change it we can change the option `default_matrix_item` or the parameter `matrix_item`:
```{r, eval = FALSE}
# To get the default parameters
getOption("default_matrix_item")
# To change the default parameters to, for example, only export
# the information criteria:
options(default_matrix_item = c("likelihood.aic",
                                "likelihood.aicc",
                                "likelihood.bic",
                                "likelihood.bicc"))
```

3. `tsmatrix_series` character containing the names of the times series to export. By default, the items defined in the option `default_tsmatrix_series` are exported. To change it we can change the option `default_tsmatrix_series` or the parameter `tsmatrix_series`:
```{r, eval = FALSE}
# To get the default parameters
getOption("default_tsmatrix_series")
# To change the default parameters to, for example, only export
# the seasonally adjusted series and its forecasts:
options(default_tsmatrix_series = c("sa", "sa_f"))
```

For more informations, see the help of the function: `?create_param_file`. 
Below some examples to create the parameter file:
```{r, eval = TRUE}
export_dir <- tempdir()
# To create the file parameters.params in the directory export_dir with
# the refresh policy "lastoutliers" and the others default parameters:
create_param_file(dir_file_param = export_dir,
                  policy = "lastoutliers")

# If the options "default_matrix_item" and "default_tsmatrix_series" were
# changed to only export the information criteria, the seasonally adjusted series and its forecasts, the previous code is equivalent to:
create_param_file(dir_file_param = export_dir,
                  policy = "lastoutliers",
                  matrix_item = c("likelihood.aic", "likelihood.aicc",
                                  "likelihood.bic", "likelihood.bicc"),
                  tsmatrix_series = c("sa", "sa_f"))
```

Parameter files can be read with `read_param_file()` which returns a list than can also be modified and exported with `list2param_file()`:

```{r, eval = TRUE}
param_f <- read_param_file(file.path(export_dir, "parameters.param"))
str(param_f)
```
The default parameters files of JDemetra+ 2.x.y and JDemetra+ 3.x.y can be retrieved with `default_param_file()`.

## To run the JWSACruncher

To run the JWSACruncher with `cruncher()` or `cruncher_and_param()`, you have to specify the path to the JWSACruncher (`cruncher_bin_directory` parameter) and the path to the workspace (`workspace` parameter).

By default, the path to the JWSACruncher is the value of the option `cruncher_bin_directory`: therefore you only have to change this option once so that it applies to all the future running. 
The path to specify is the folder containing the *jwsacruncher.bat* file which is under the "Bin" folder of the JWSACruncher. 
Thus, if it is installed in `D:\jdemetra-cli-2.2.2`, the file *jwsacruncher.bat* will be under `D:\jdemetra-cli-2.2.2\bin` and you have to change the `cruncher_bin_directory` option as follows:

```{r, eval = FALSE}
options(cruncher_bin_directory = "D:/jdemetra-cli-2.2.2/bin/")
```

If no workspace is specified, a dialog box opens to select it.

The `cruncher_and_param()` function allows to create a temporary parameter file with `create_param_file()` and then run the JWSACruncher with `cruncher()`. 
In addition to the parameters available in these two functions, `cruncher_and_param()` allows to rename the output folder containing the workspace results so that they are equal to the names of the multi-documents displayed in the JDemetra+ software with the parameter `rename_multi_documents` (equals to `FALSE` by default). 
Below are some examples:

```{r, eval = FALSE}
# The following code updates the workspace "workspace", that is under the folder D:/, 
# with the refresh policy "lastoutliers". Others parameters are the default ones of create_param_file().
# In particular, the exported parameters are those of the options
# "default_matrix_item" options and "default_tsmatrix_series" and the results 
# will be under D:/workspace/Output/.
cruncher_and_param(workspace = "D:/workspace.xml",
                   policy = "lastoutliers")

# Use the parameter "outpout" to change the folder that will contains the results
cruncher_and_param(workspace = "D:/workspace.xml",
                   output = "D:/Results/",
                   policy = "lastoutliers")

# To change the names of the folders containing the outputs so that they are equal
# to the names of the multi-documents displayed in JDemetra+, use the parameter
# "rename_multi_documents = TRUE". The parameter "delete_existing_file = TRUE"
# allows to delete any existing folders with the same name as the multi-documents.
cruncher_and_param(workspace = "D:/workspace.xml",
                   rename_multi_documents = TRUE,
                   delete_existing_file = TRUE,
                   policy = "lastoutliers")

# To see the other parameters:
?cruncher_and_param
```
