R/param_file.R

In AQLT/JDCruncheR: Interface between the JDemetra+ cruncher and R, and quality report generator

#' Création du fichier des paramètres du cruncher
#'
#' Pour fonctionner, le cruncher a besoin d'un fichier de paramètres : \code{create_param_file} permet de le créer
#'
#' @param dir_file_param répertoire du dossier qui contiendra le fichier parametres.param des paramètres.
#' @param bundle nombre maximum de séries dans un fichier de sortie. Par défaut \code{bundle = 10000}.
#' @param csv_layout mise en page du fichier de sortie. Par défaut, \code{csv_layout = "list"}. Autres
#' options : \code{csv_layout = "vtable"} ou \code{csv_layout = "htable"}.
#' @param csv_separator séparateur de colonnes utilisé dans le fichier csv. Par défaut, \code{csv_separator = ";"}.
#' @param ndecs nombre de décimales dans les sorties (6 par défaut).
#' @param policy méthode de rafraîchissement utilisée. Par défaut, \code{policy = "parameters"} (paramètres re-estimés).
#' Les autres méthodes possibles sont :
#' \code{"outliers"} (les outliers sont identifiés et les paramètres ré-estimés) ;
#' \code{"lastoutliers"} (les outliers sont ré-identifiés sur la dernière année et les paramètres ré-estimés) ;
#' \code{"stochastic"} (le modèle arima et les outliers sont identifiés et les paramètres ré-estimés) ;
#' \code{"complete"} (le modèle est complétement ré-estimé).
#' @param output dossier où sont exportés les résultats. Par défaut, (\code{output = NULL}) et un dossier "Output" est créé à l'adresse du workspace.
#' @param matrix_item chaîne de caractères contenant les noms des paramètres à exporter (voir le manuel de JDemetra+).
#' Les paramètres par défaut sont obtenus en exécutant la commande \code{getOption("default_matrix_item")} (cette option
#' est initialisée aux mêmes paramètres par défaut que ceux de JDemetra+).
#' @param tsmatrix_series chaîne de caractères contenant les séries temporelles à exporter (voir le manuel de JDemetra+).
#'  Les paramètres par défaut sont obtenus en exécutant la commande \code{getOption("default_tsmatrix_series")} (cette option
#' est initialisée aux mêmes paramètres par défaut que ceux de JDemetra+)
#' @param paths_path chemins vers les fichiers d'entrée (Excel, xml...).
#' @return L'adresse du fichier de paramètres.
#' @encoding UTF-8
#' @keywords internal
#' @name fr-create_param_file
NULL
#> NULL


#' Creation of the .params file for the cruncher
#'
#' To operate, the cruncher needs a parameter file. It can be generated by the function \code{create_param_file}.
#'
#' @param dir_file_param path to the folder that will store the .param parameter file.
#' @param bundle maximum number of series in an output file. By default, \code{bundle = 10000}.
#' @param csv_layout layout of the output file. By default, \code{csv_layout = "list"}. Other options are: \code{csv_layout = "vtable"} or \code{csv_layout = "htable"}.
#' @param csv_separator column separator for the csv file. By default, \code{csv_separator = ";"}.
#' @param ndecs number of decimals in the output (6 by default).
#' @param policy refresh policy used. By default, \code{policy = "parameters"} (the model coefficients are re-estimated).
#' The other methods available are:
#'
#' \code{"current"} or \code{"n"} (fixed model + all new data are classified as additive outliers)
#'
#' \code{"fixed"} or \code{"f"} (fixed model: the model is stictly unchanged)
#'
#' \code{"fixedparameters"} or \code{"fp"} (re-estimation of the regression coefficients)
#'
#' \code{"parameters"} or \code{"p"} (above + re-estimation of the arima coefficients)
#'
#' \code{"lastoutliers"} or \code{"l"} (above + re-identification of the outliers over the last year)
#'
#' \code{"outliers"} or \code{"o"} (above + re-identification of the outliers over the whole series span)
#'
#' \code{"stochastic"} or \code{"s"} (above + re-estimation of the arima model (orders))
#'
#' \code{"complete"} or \code{"c"} (the model is completely re-estimated).
#'
#' @param output folder where the results are stored. By default, (\code{output = NULL}) and a new "Output" folder is created in the workspace folder.
#' @param matrix_item string speciying the parameters to export (cf. JDemetra+ documentation).
#' To get the default parameters, compile \code{getOption("default_matrix_item")}. This option is initially set to JDemetra+'s default value.
#' @param tsmatrix_series string specifying the time series to export (cf. JDemetra+ documentation).
#' To get the default parameters, compile \code{getOption("default_tsmatrix_series")}. This option is initially set to JDemetra+'s default value.
#' @param paths_path paths to the input files (Excel, xml...).
#' @return The parameters file address.
#' @encoding UTF-8
#' @family Cruncher functions
#' @seealso [Traduction française][fr-create_param_file()]
#' @export
create_param_file <- function(dir_file_param = getwd(), bundle = 10000, csv_layout = "list", csv_separator = ";",
                              ndecs = 6, policy = "parameters", output = NULL,
                              matrix_item = getOption("default_matrix_item"),
                              tsmatrix_series = getOption("default_tsmatrix_series"),
                              paths_path = NULL) {
    first_line <- "<?xml version=\"1.0\" encoding=\"UTF-8\" standalone=\"yes\"?>"
    param_line <- paste("<wsaConfig bundle=", bundle, " csvlayout=", csv_layout, " csvseparator=",
        csv_separator, " ndecs=", ndecs, ">",
        sep = "\""
    )
    policy_line <- paste0("    <policy>", policy, "</policy>")

    output_line <- matrix_lines <- tsmatrix_lines <- path_lines <- NULL

    if (!is.null(output)) {
        output <- normalizePath(output)
        output_line <- paste0("    <output>", gsub("/", "\\", output, fixed = TRUE), "</output>")
    }

    if (!is.null(matrix_item)) {
        matrix_lines <- c(
            "    <matrix>",
            paste0("        <item>", matrix_item, "</item>"),
            "    </matrix>"
        )
    }

    if (!is.null(tsmatrix_series)) {
        tsmatrix_lines <- c(
            "    <tsmatrix>",
            paste0("        <series>", tsmatrix_series, "</series>"),
            "    </tsmatrix>"
        )
    }

    if (!is.null(paths_path)) {
        path_lines <- c(
            "    <paths>",
            paste0("        <path>", gsub("/", "\\", paths_path, fixed = TRUE), "</path>"),
            "    </paths>"
        )
    }

    file_param <- c(
        first_line, param_line, policy_line, output_line,
        matrix_lines, tsmatrix_lines, path_lines,
        "</wsaConfig>"
    )
    writeLines(file_param, con = paste0(dir_file_param, "/parametres.param"))
    return(invisible(paste0(dir_file_param, "/parametres.param")))
}