internal-interpolate: Internal helper functions for generating interpolation grids...

In RobAStRDA: Interpolation Grids for Packages of the 'RobASt' - Family of Packages

Internal helper functions for generating interpolation grids for speed up in package RobAStRDA

Description

These functions are used internally to generate interpolation grids, for Lagrange multipliers or LDEstimators in package RobAStRDA, to be stored in the respective ‘sysdata.rda’ file.

Usage

.versionSuff(name)

.MakeSmoothGridList(thGrid, Y, df = NULL, gridRestrForSmooth = NULL)

.readGridFromCSV(fromFileCSV)

.generateInterpolators(Grid, approxOrspline = "spline", extrapol = c(NA,NA))

.saveGridToRda(fromFileCSV, toFileRDA = "sysdata.rda", withMerge = FALSE,
               withPrint = TRUE, withSmooth = TRUE, df = NULL,
               gridRestrForSmooth = NULL)

.mergeGrid(Grid1, Grid2)

.computeInterpolators(sysdataFiles, toFileRDA = "sysdata.rda",
      includeGrids = NULL, includeNams = NULL,
      excludeGrids = NULL, excludeNams = NULL,
      withPrint = TRUE, withSmoothFct = FALSE,
      approxOrspline = "spline", extrapol = c(NA,NA))

.mergeF(file,envir, includeGrids = NULL, includeNams = NULL,
        excludeGrids = NULL, excludeNams = NULL)

.copy_smoothGrid(gridEntry = NULL, rdafileOld, gridnamOld, FamnamOld, rdafileNew,
                 gridnamNew, FamnamNew, withSmooth = FALSE, df = NULL,
                 gridRestrForSmooth = NULL)

.renameGridName(rdafileOld, gridnamOld, FamnamOld, rdafileNew, gridnamNew,
                FamnamNew)

Arguments

name	Grid name to append a suffix according to the R-version.
thGrid	numeric; grid values.
Y	in case .MakeGridList: array or matrix; in case .saveInterpGrid array or NULL; if non-null, contains precomputed y-values, so that call to getFun resp. optFct can be omitted.
df	argument df of smooth.spline; if NULL (default) it is omitted (and the default of smooth.spline used); controls the degree to which we smooth; can be vectorized; to allow for NULL-entries in some (of the 13) LMs, it can also be a list of length 13, some entries being NULL, some numeric.
gridRestrForSmooth	an expression that can be used as index in theta[gridRestrForSmooth] to restrict the grid-values to be smoothed; the excluded grid values are left unchanged. If the argument is NULL no restriction is used. Can be a matrix of same dimension as the Y-grid to allow for column-individual restrictions, or a list of same length as number of columns of Y with columnwise restrictions of Y (and NULL entries are interpreted as no restriction).
fromFileCSV	character; names of the csv files from which the grids are read.
Grid, gridEntry	matrix; grid to be used.
approxOrspline	character; if approxOrspline=="spline" (default), splinefun is used for generating the interpolators, otherwise we use approxfun.
extrapol	numeric of length 2; lower and upper bound, upto which extrapolation is done; beyond, the interpolator returns NA; if one (or both) entries of extrapol are NA, we extrapolate beyond limit.
toFileRDA	character; the ‘.rda’-file to which the interpolators are saved.
withMerge	logical of length 1: in case a respective grid already exists, shall we merge the new contents into it, or overwrite the object (default)?
withPrint	logical of length 1: shall we issue diagnostic prints?
withSmooth	logical of length 1: shall a smoothing spline be used?
Grid1, Grid2	matrices; grids to be merged.
sysdataFiles	character; filenames of ‘sysdata.rda’ files from where to extract the interpolation grids.
includeGrids	character (or NULL); if non-NULL, explicit restriction to grids used for computation of interpolators.
includeNams	character (or NULL); if non-NULL, explicit restriction to families used for computation of interpolators.
excludeGrids	character (or NULL); grids to be excluded from computation of interpolators.
excludeNams	character (or NULL); families to be excluded from computation of interpolators.
withSmoothFct	logical of length 1: shall a smoothed grid be used for interpolators?
file	character; the name of a file to be read out.
envir	an environment.
gridnamOld	character; name of the grid to be renamed (from).
FamnamOld	character; name of the parametric family to be renamed (from).
rdafileOld	character; filename of the ‘sysdata.rda’-type file to be read out.
gridnamNew	character; name of the grid to be renamed (to). If missing, it is set to gridnamOld internally.
FamnamNew	character; name of the parametric family to be renamed (to). If missing, it is set to FamnamOld internally.
rdafileNew	character; filename of the ‘sysdata.rda’-type file to be written on. If missing, it is set to rdafileOld internally.

Details

.versionSuff, according to the current R-version, appends a suffix ".O" for R<2.16 and ".N" otherwise to argument name. Needed as the return values of splinefun and approxfun are incompatible in these two situations: i.e., a function with body of type .C("R_splinefun", as.double(x),....) respectively a function with body of type .splinefun(....))); a similar case happens with approxfun.

.MakeSmoothGridList smoothes out a given grid (x is contained in thGrid, y in Y) by smooth.spline; the degree of smoothing is controlled by df.

.readGridFromCSV reads in a grid from a csv file together with the information given in the corresponding ‘.txt’ file. More specifically, when generating a ‘.csv’ file in e.g.\ RobExtremes by .writeGridToCSV, in addition to writing the interpolation grid to the ‘.csv’ file, a corresponding ‘.txt’ file is created containing information on the parametric family and the grid name. This information is read in again as well here.

.generateInterpolators for a given grid according to argument approxOrspline produces a list of interpolators by calls to either splinefun or approxfun (i.e., one function per y-column). In addition, in case of (x-)values outside the range of the grid, in the interpolators, we use linear extrapolation.

.saveGridToRda for a vector of files in argument fromFileCSV reads in the grids and writes them to a ‘sysdata.rda’ file. If ‘sysdata.rda’ already exists and corresponding grids already exist in ‘sysdata.rda’, argument withMerge controls whether the grids are merged or overwritten. In addition, by argument withSmooth, one may generate smoothed out grids as well. So in the end, the ‘sysdata.rda’ file contains grid objects with names by default starting with a dot, say .Sn or .OMSE. These are lists with parametric families as items (with the names of the parametric families as names of the list items). Each family item is again a list with (possible) entries grid (the original grid read out from the ‘.csv’-file), gridS (the smoothed out grid), fct.O, the interpolator generated in R<2.16, fct.N, the interpolator generated in R>2.16. .saveGridToRda only generates the grid entries, whereas the interpolators are created in .computeInterpolators.

.mergeGrid merges two grids according to the respective rows of the matrices.

.computeInterpolators for a vector of input ‘sysdata.rda’ files contained in argument sysdataFiles goes through the contained grids and produces respective interpolators by calls to .generateInterpolators. If withSmoothFct == TRUE (and a respective gridS entry exists in the current grid-family combination) it uses the gridS entry, otherwise the grid entry. By means of optional arguments includeGrids, includeNams, excludeGrids, excludeNams one may explicitely restrict the grid-family combinations for which the interpolators are generated.

.mergeF merges the contents of file file into environment envir in the sense, that if both file and envir contain a list object a also the items of a are merged, where—as for objects themselves— contents of file overwrite contents of envir. By means of optional arguments includeGrids, includeNams, excludeGrids, excludeNams one may explicitely restrict the grid-family combinations for which the interpolators are generated.

.copy_smoothGrid can be used to modify single grid / gridS entries in an existing grid-family combination in an existing ‘sysdata.rda’-file; in particular grid entries can be replaced and gridS entries can be created (or overwritten). To this end, .copy_smoothGrid takes out a respective item FamnamOld (i.e., a parametric family) of grid gridnamOld from file rdafileOld. If argument gridEntry is non-NULL, it replaces the respective grid-entry by gridEntry, otherwise it uses the one present in combination gridnamOld-FamnamOld. If argument withSmooth == TRUE, it also creates a gridS entry, smoothing out the entries of the grid-entry. The results are copies it to a new grid-family combination gridnamNew-FamnamNew which is saved to file rdafileNew.

.renameGridName is a utility to rename grids and items from a grid. It takes grid gridnamOld from file rdafileOld and takes the name FamnamOld of a respective item (i.e., a parametric family), renames the grid-family combination to gridnamNew, FamnamNew and writes the result back to file rdafileNew.

Value

.versionSuff	A character with appended suffix.
.MakeSmoothGridList	the grid, i.e.; a matrix with x and y values .
.readGridFromCSV	a list with the read-in items, i.e., an item Grid with the grid, an item namPFam with the name of the parametric family, and namInSysdata, the name of the read in grid.
.generateInterpolators	a list with items grid (the grid, i.e.; a matrix with x and y values), and fct (the list of interpolators, i.e.; a list of functions).
.saveGridToRda	invisible(NULL).
.mergeGrid	the merged grid, i.e.; a matrix.
.computeInterpolators	invisible(NULL).
.mergeF	invisible(NULL).
.copy_smoothGrid	invisible(NULL).
.renameGridName	invisible(NULL).

Note

These functions are only meant for the developers of package ROptEst (or respective packages). They can be used to speed up things by interpolation. Our use case is a speed up for further scale-shape families (or enhance existing speed-ups) such that the respective grids are stored in a ‘sysdata.rda’ file of the present package RobAStRDA —see mail exchange P.Ruckdeschel - U.Ligges on R-devel— https://stat.ethz.ch/pipermail/r-devel/2013-February/065794.html. Special attention has to be paid for R-versions pre and post R-2.16 which is why we use .versionSuff.

RobAStRDA documentation built on May 8, 2023, 3:01 p.m.