R/utils.R

In rjd3workspace: Wrangling 'JDemetra+ 3.x' Workspaces

#' @importFrom rJava .jpackage .jcall .jnull .jarray .jevalArray .jcast .jcastToArray .jinstanceof is.jnull .jnew .jclass
#' @import rjd3toolkit
NULL


#' Read a Tramo specification file
#'
#' @description
#'
#' The specification file is a xml file like the one JDemetra+ would write when
#' defining a specification in the Graphical User Interface.
#'
#' @param file xml format,
#'
#' @returns list
#'
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' file <- system.file("workspaces", "workspace_test", "TramoSpec",
#'                     "TramoSpec-1.xml", package = "rjd3workspace")
#' my_spec<- tramo_read_spec(file)
#' class(my_spec)
#' str(my_spec)
#' @export
tramo_read_spec <- function(file) {
    jspec <- .jcall(
        obj = "jdplus/tramoseats/base/workspace/Utility",
        returnSig = "Ljdplus/tramoseats/base/api/tramo/TramoSpec;",
        method = "readTramoSpec",
        as.character((file))
    )
    if (is.jnull(jspec)) {
        return(NULL)
    }
    return(rjd3tramoseats::.jd2r_spec_tramo(jspec))
}

#' Write a Tramo specification file
#'
#' @description
#' The specification file is a xml file like the one JDemetra+ would write when
#' defining a specification in the Graphical User Interface.
#'
#' @param spec a specification created with `rjd3tramoseats::tramo_spec`
#' @param file xml format
#'
#' @returns \code{NULL} returned invisibly
#'
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' # Creating a spec from default
#' tramo_spec <- rjd3tramoseats::tramo_spec("tr3")
#'
#' # Forcing multiplicative model
#' tramo_spec_d <- rjd3toolkit::set_transform(
#'     tramo_spec ,
#'     fun = "Log",
#'     outliers = TRUE
#' )
#'
#' # Writing the specification in a xml file
#' spec_path <- tempfile(fileext = ".xml")
#' tramo_write_spec(tramo_spec_d, file = spec_path)
#'
#' @export
tramo_write_spec <- function(spec, file) {
    .jcall(
        "jdplus/tramoseats/base/workspace/Utility",
        "V",
        "writeTramoSpec",
        rjd3tramoseats::.r2jd_spec_tramo(spec),
        as.character((file))
    )
}
#' Read a Tramo-Seats specification file
#'
#' @description
#'
#' The specification file is a xml file like the one JDemetra+ would write when
#' defining a specification in the Graphical User Interface.
#'
#' @param file xml format,
#'
#' @returns list
#'
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' file <- system.file("workspaces", "workspace_test", "TramoSeatsSpec",
#'                     "TramoSeatsSpec-1.xml", package = "rjd3workspace")
#' my_spec<- tramoseats_read_spec(file)
#' class(my_spec)
#' str(my_spec)
#' @export
tramoseats_read_spec <- function(file) {
    jspec <- .jcall(
        obj = "jdplus/tramoseats/base/workspace/Utility",
        returnSig = "Ljdplus/tramoseats/base/api/tramoseats/TramoSeatsSpec;",
        method = "readTramoSeatsSpec",
        as.character(file)
    )
    if (is.jnull(jspec)) {
        return(NULL)
    }
    return(rjd3tramoseats::.jd2r_spec_tramoseats(jspec))
}

#' Write a Tramo-Seats specification file
#'
#' @description
#' The specification file is a xml file like the one JDemetra+ would write when
#' defining a specification in the Graphical User Interface.
#'
#' @param spec a specification created with `rjd3tramoseats::tramoseats_spec`
#' @param file xml format
#'
#' @returns \code{NULL} returned invisibly
#'
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' # Creating a spec from default
#' tramoseats_spec <- rjd3tramoseats::tramoseats_spec("tr3")
#'
#' # Forcing multiplicative model
#' tramoseats_spec_d <- rjd3toolkit::set_transform(
#'     tramoseats_spec ,
#'     fun = "Log",
#'     outliers = TRUE
#' )
#'
#' # Writing the specification in a xml file
#' spec_path <- tempfile(fileext = ".xml")
#' tramoseats_write_spec(tramoseats_spec_d, file = spec_path)
#'
#' @export
tramoseats_write_spec <- function(spec, file) {
    .jcall(
        "jdplus/tramoseats/base/workspace/Utility",
        "V",
        "writeTramoSeatsSpec",
        rjd3tramoseats::.r2jd_spec_tramoseats(spec),
        as.character(file)
    )
}

#' Read a Reg-Arima specification file
#'
#' @description
#'
#' The specification file is a xml file like the one JDemetra+ would write when
#' defining a specification in the Graphical User Interface.
#'
#' @param file xml format,
#'
#' @returns list
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' file <- system.file("workspaces", "workspace_test", "RegArimaSpec",
#'                     "RegArimaSpec-1.xml", package = "rjd3workspace")
#' my_spec<-regarima_read_spec(file)
#' class(my_spec)
#' str(my_spec)
#'
#' @export
regarima_read_spec <- function(file) {
    jspec <- .jcall(
        "jdplus/x13/base/workspace/Utility",
        "Ljdplus/x13/base/api/regarima/RegArimaSpec;",
        "readRegArimaSpec",
        as.character((file))
    )
    if (is.jnull(jspec)) {
        return(NULL)
    }
    return(rjd3x13::.jd2r_spec_regarima(jspec))
}

#' Write a Reg-Arima specification file
#'
#' @description
#' The specification file is a xml file like the one JDemetra+ would write when
#' defining a specification in the Graphical User Interface.
#'
#' @param spec a specification created with `rjd3x13::regarima_spec`
#' @param file xml format
#'
#' @returns \code{NULL} returned invisibly
#'
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' # Creating a spec from default
#' regarima_spec <- rjd3x13::regarima_spec("rg3")
#'
#' # Forcing multiplicative model
#' regarima_spec_d <- rjd3toolkit::set_transform(
#'     regarima_spec ,
#'     fun = "Log",
#'     outliers = TRUE
#' )
#'
#' # Writing the specification in a xml file
#' spec_path <- tempfile(fileext = ".xml")
#' regarima_write_spec(regarima_spec_d, file = spec_path)
#'
#' @export
regarima_write_spec <- function(spec, file) {
    .jcall(
        "jdplus/x13/base/workspace/Utility",
        "V",
        "writeRegArimaSpec",
        rjd3x13::.r2jd_spec_regarima(spec),
        as.character(file)
    )
}

#' Read a X13 specification file
#'
#' @description
#' The specification file is a xml file like the one JDemetra+ would write when
#' defining a specification in the
#' Graphical User Interface.
#'
#' @param file xml format,
#'
#' @returns list
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' file <- system.file("workspaces", "workspace_test", "X13Spec",
#'                     "X13Spec-1.xml", package = "rjd3workspace")
#' my_spec<-x13_read_spec(file)
#' class(my_spec)
#' str(my_spec)
#' @export
x13_read_spec <- function(file) {
    jspec <- .jcall(
        obj = "jdplus/x13/base/workspace/Utility",
        returnSig = "Ljdplus/x13/base/api/x13/X13Spec;",
        method = "readX13Spec",
        file
    )
    if (is.jnull(jspec)) {
        return(NULL)
    }
    return(rjd3x13::.jd2r_spec_x13(jspec))
}

#' Write a X13 specification file
#'
#' @description
#' The specification file is a xml file like the one JDemetra+ would write when
#' defining a specification in the Graphical User Interface.
#'
#' @param spec a specification created with `rjd3x13::x13_spec`
#' @param file xml format
#' @returns \code{NULL} returned invisibly
#'
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' # Creating a spec from default
#' x13_spec <- rjd3x13::x13_spec("rsa3")
#'
#' # Forcing multiplicative model
#' x13_spec_d <- rjd3toolkit::set_transform(
#'     x13_spec ,
#'     fun = "Log",
#'     outliers = TRUE
#' )
#'
#' # Writing the specification in a xml file
#' spec_path <- tempfile(fileext = ".xml")
#' x13_write_spec(x13_spec_d, file = spec_path)
#'
#' @export
x13_write_spec <- function(spec, file) {
    .jcall(
        "jdplus/x13/base/workspace/Utility",
        "V",
        "writeX13Spec",
        rjd3x13::.r2jd_spec_x13(spec),
        as.character(file)
    )
}

#' Read a Calendar file
#'
#' @param file path to a calendar file (in xml format)
#'
#' @description
#' The calendar file is a xml file like the one JDemetra+ would write when
#' defining a calendar in the Graphical User Interface.
#'
#' @returns a list of `JD3_CALENDAR` objects
#'
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#'
#' \donttest{
#' file <- system.file("workspaces", "workspace_test", "Calendars",
#'                     "Calendars.xml", package = "rjd3workspace")
#' my_calendar <- read_calendars(file)
#' my_calendar
#' }
#'
#' @export
read_calendars <- function(file) {
    jspec <- .jcall(
        obj = "jdplus/toolkit/base/workspace/file/Utility",
        returnSig = "Ljdplus/toolkit/base/api/timeseries/calendars/CalendarManager;",
        method = "readCalendars",
        file
    )
    if (is.jnull(jspec)) {
        return(NULL)
    }
    return(rjd3toolkit::.jd2r_calendars(jspec))
}

#' Write a Calendar file
#'
#' @description
#' The calendar file is a xml file like the one JDemetra+ would write when
#' defining a calendar in the Graphical User Interface.
#' Calendars can be defined with `rjd3toolkit::national_calendar`
#'
#' @param calendars list of calendars or a `JD3_CALENDAR` object
#' @param file xml format
#'
#' @returns \code{NULL} returned invisibly
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' library("rjd3toolkit")
#' BE <- national_calendar(list(
#'     fixed_day(7, 21),
#'     special_day("NEWYEAR"),
#'     special_day("CHRISTMAS"),
#'     special_day("MAYDAY"),
#'     special_day("EASTERMONDAY"),
#'     special_day("ASCENSION"),
#'     special_day("WHITMONDAY"),
#'     special_day("ASSUMPTION"),
#'     special_day("ALLSAINTSDAY"),
#'     special_day("ARMISTICE")
#' ))
#'
#' calendar_path <- tempfile(pattern = "calendar", fileext = ".xml")
#'
#' write_calendars(BE, file = calendar_path)
#' write_calendars(list(BEL_cal = BE), file = calendar_path)
#' @export
write_calendars <- function(calendars, file) {
    if (inherits(calendars, "JD3_CALENDAR")) {
        calendars <- list(cal = calendars)
    } else if (
        !(is.list(calendars) &&
            all(sapply(calendars, inherits, "JD3_CALENDAR")) &&
            !is.null(names(calendars)) &&
            all(nzchar(names(calendars))))
    ) {
        stop(
            "calendars must be a `JD3_CALENDAR` or a named list of `JD3_CALENDAR` objects"
        )
    }
    jcal <- rjd3toolkit::.r2jd_calendars(calendars)
    .jcall(
        "jdplus/toolkit/base/workspace/file/Utility",
        "V",
        "writeCalendars",
        jcal,
        as.character(file)
    )
}

#' @title Read auxiliary regressors file
#'
#' @description
#' The variables (regressors) file is a xml file like the one JDemetra+ would
#' write when setting-up user defined regressors in the Graphical User
#' Interface.
#'
#' @param file xml format
#'
#' @returns A named list of time series objects.
#'
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#' file <- system.file("workspaces", "workspace_test", "Variables",
#'                     "Vars-1.xml", package = "rjd3workspace")
#' my_regressors <- read_variables(file)
#' class(my_regressors)
#' str(my_regressors)
#'
#' @export
#'
read_variables <- function(file) {
    jspec <- .jcall(
        obj = "jdplus/toolkit/base/workspace/file/Utility",
        returnSig = "Ljdplus/toolkit/base/api/timeseries/regression/TsDataSuppliers;",
        method = "readData",
        file
    )
    if (is.jnull(jspec)) {
        return(NULL)
    }
    return(rjd3toolkit::.jd2r_variables(jspec))
}

#' @title Write regressors file
#'
#' @param vars A named list of `ts` objects.
#' @param file Path to the output XML file.
#'
#' @returns No return value (\code{NULL} returned invisibly). This function
#' writes variables to file for use in JD+.
#'
#' @examplesIf rjd3jars::check_java_version(silent = TRUE)
#'
#' # Load a Workspace
#' file <- system.file("workspaces", "workspace_test.xml",
#'                     package = "rjd3workspace")
#' \donttest{
#' jws <- jws_open(file)
#'
#' # Get context
#' my_context <- get_context(jws)
#' vars <- my_context$variables[[1L]]
#'
#' # Writing the regressors in a xml file
#' variable_path <- tempfile(fileext = ".xml")
#' write_variables(vars, file = variable_path)
#' }
#'
#' @export
write_variables <- function(vars, file) {
    jvars <- rjd3toolkit::.r2jd_variables(vars)
    .jcall(
        "jdplus/toolkit/base/workspace/file/Utility",
        "V",
        "writeData",
        jvars,
        as.character(file)
    )
}

#' @title Converts a jspec to a spec
#'
#' @param jspec Specification in java format
#'
#' @returns Specification in R format
#'
#' @export
#' @importFrom rjd3x13 .jd2r_spec_x13
#' @importFrom rjd3tramoseats .jd2r_spec_tramoseats
.jd2r_spec <- function(jspec) {
    if (is.null(jspec)) {
        return(NULL)
    } else if (
        .jinstanceof(
            jspec,
            "jdplus/tramoseats/base/api/tramoseats/TramoSeatsSpec"
        )
    ) {
        spec <- jspec |>
            .jcast("jdplus/tramoseats/base/api/tramoseats/TramoSeatsSpec") |>
            rjd3tramoseats::.jd2r_spec_tramoseats()
    } else if (.jinstanceof(jspec, "jdplus/x13/base/api/x13/X13Spec")) {
        spec <- jspec |>
            .jcast("jdplus/x13/base/api/x13/X13Spec") |>
            rjd3x13::.jd2r_spec_x13()
    }
    return(spec)
}