metaSub.character {MIfuns}R Documentation

Create Replicate Text files with Systematic Substitutions

Description

metaSub() is generic. A method is defined for character; a convenience wrapper is provided for passing names of text files to be read and then resampled.

metaSub() collapses a character vector to one line of text. The vector is replicated as many times as there are elements in names, with flexible substitution of text fragments. If out is supplied, the replicates are saved as text files identified with names and a suffix.

metaSub.filename() will process multiple filenames, if x is as long as names.

Usage

        ## S3 method for class 'character':
        as.filename(x, ...)
        ## S3 method for class 'filename':
        metaSub(x, names, ...)
        ## S3 method for class 'character':
        metaSub(x, names, pattern = NULL,
   replacement = NULL, out = NULL, suffix = ".txt", fixed = TRUE, ...)

Arguments

x Atomic character, or (second form) filename(s). Multi-element character will be collapsed to one element, with newline as the separator.
names A list of (unique) names for resulting output elements. A vector of names will be coerced to character and to list.
pattern a character vector of text fragments to replace, optionally encoded as regular expressions (fixed==FALSE, See ?gsub, ?regex). Can also be a list. See details.
replacement A character vector of substitutions for patterns. The wildcard "*" is available to represent the corresponding value of names. Can also be a list with as many elements as pattern (see details). Expressions are supported (see details).
out A (path and) directory in which to write the resulting control streams.
suffix A file extension for filenames, if out is suppied.
fixed Passed to gsub: use FALSE if pattern contains regular expressions. Atomic, or same length as pattern.
... Extra arguments, available to expressions or passed to gsub().

Details

Typical usages are

                metaSub(x, names, ...)
                metaSub(as.filename(x), names, ...)
Replacement is performed by gsub(), so an element of pattern will be replaced everywhere it occurs in a line.

if pattern or replacement is a list, each element should be of length one, or as long as names. In the latter case, substitutions can be specific on a per-name basis. The wild card "*" is still available.

It is necessary that pattern and replacement be of the same length, but it is not necessary that their corresponding elements have equal lengths. Thus, one can specify name-specific replacements for a single pattern, or a single replacement for name-specific patterns.

An expression can be specified for replacement itself, or one of its pattern-wise elements, or one of the name-wise elements of a pattern-wise element. Expressions are evaluated in an environment containing "name" (same meaning as "*" above) and all other ... arguments. This is useful if extra arguments have a dimension indexed, at least loosely, by names. The evaluated expression is treated as character, and wildcard substitution is attempted.

NOTE: be very careful not to have trailing commas in your lists! An error results that is very hard to track. e.g. c(a,b,c,).

Value

an invisble named character vector. If out is supplied, Elements are written as files with corresponding names.

Note

In previous package versions, metaSub was resample.character, etc.

Author(s)

Tim Bergsma

References

This package developed under the auspices of Metrum Institute, http://metruminstitute.org

See Also

gsub, regex

Examples

data(ctl)
dir()
e <- metaSub(
        ctl,
        names=1:3,
        pattern=c(
                "PROBLEM 8",
                "data8.csv",
                "8.MSF"
        ),
        replacement=c(
                "PROBLEM *",
                "*.csv",
                "*.MSF"
        ),
        out=".",
        suffix=".ctl"
)
t <- metaSub(
        ctl,
        names=c("test1","test2"),
        pattern=c("PROBLEM 8","data8.csv","METH=0"),
        replacement=c("PROBLEM *","*.csv","METH=1"),
)

t <- metaSub(
        ctl,
        names=c("test1","test2"),
        pattern=c(
                "PROBLEM 8",
                "data8.csv",
                "METH=0"
        ),
        replacement=list(
                "PROBLEM *",
                "*.csv",
                c("METH=1","METH=2")
        ),
        out=".",
        suffix=".ctl"
)
#just a file copy...
metaSub(as.filename("1.ctl"),names="4",out=".",suffix=".ctl")

#using a (nonsense) replacement expression...
options <- data.frame(var=c(8,9),alt=c(10,11))
a <- metaSub(
        ctl,
        names=rownames(options),
        pattern="9999", 
        replacement=expression(
                options$var[rownames(options)==name]
        ),
        options=options
)
cat(a[[2]])

#replacement expression in a 'mixed' list...
b <- metaSub(
        ctl,
        names=rownames(options),
        pattern=list(
                "PRINT=2",
                "9999"
        ), 
        replacement=list(
                "PRINT=3",
                expression(options$var[rownames(options)==name])
        ),
        options=options
)
cat(b[[2]])

#replacement expressions on a per-name basis
d <- metaSub(
        ctl,
        names=rownames(options),
        pattern="9999",
        replacement=list(       #so that replacement is as long as pattern
                list(                   #with different options for each 'name'
                        expression(options$var[rownames(options)==name]),
                        expression(options$alt[rownames(options)==name])
                )
        ),
        options=options
)
cat(d[[2]])

[Package MIfuns version 3.2.9 Index]