R: Read a TRIM command file

read_tcf {rtrim}

R Documentation

Read a TRIM command file

Description

Read TRIM Command Files, compatible with the Windows TRIM programme.

Usage

read_tcf(file, encoding = getOption("encoding"), simplify = TRUE)

Arguments

`file`	Location of TRIM command file.
`encoding`	The encoding in which the file is stored.
`simplify`	Return a single `trimcommand` object if only one model is specified in the TRIM command file.

Value

A trimcommand object, or in the case of multiple models in a single TRIM command file, a list of trimcommand objects. In the latter case, a useful summary can be printed with summary.trimbatch.

TRIM Command file format

TRIM command files are text files that specify a TRIM job, where a job consists of one or more models to be computed on a single data input file. TRIM command files are commonly stored with the extension .tcf, but this is not a strict requirement.

A TRIM command file consists of two parts. The first part describes the data file to be read, the second part describes the model(s) to be run. A TRIM command file can only contain a single data specification part, but multiple models may be specified.

Each command starts on a new line with a keyword, followed by at least one space and at least one option value, where multiple option values are separated by spaces. All commands must be written on a single line, except the LABELS command (to set labels for covariates). The latter command starts with LABELS on a single line, followed by a newline, followed by a new label on each following line. The keyword END (at the beginning of a line) signals the end of the labels command.

The keyword RUN (at the beginning of a single line) ends the specification of a single model. After this a new model can be specified. Parameters not specified in the current model will be copied from the previous one.

TRIM commands

The commands are identical to those in the original TRIM software. Commands that represent a simple toggle (on/off, present/absent) are translated to a logical upon reading. Below we give commands in upper case, but the commands are parsed case insensitively.

Data
`FILE`	data filename and path.
`TITLE`	A title (appears in output when exported).
`NTIMES`	[positive integer] Number of time points in data file.
`NCOVARS`	[nonnegative integer] Number of covariates in data file.
`LABELS`	Covariate labels (multiline command).
`END`	Signals end of `LABELS` command.
`MISSING`	missing value indicator.
`WEIGHT`	[`present`, `absent`] Indicates whether weights are present in the data file [translated to `logical`].
Model
`COMMENT`	A comment for the current model.
`WEIGHTING`	[`on`,`off`] Switch use of weights for current model [translated to `logical`].
`SERIALCOR`	[`on`,`off`] Switch use of serial correlation for current model [translated to `logical`].
`OVERDISP`	[`on`,`off`] Switch use of overdispersion for current model [translated to `logical`].
`BASETIME`	[integer] Index of base time-point.
`MODEL`	[`1`, `2`, `3`] Choose the current model
`COVARIATES`	[integers] indices of covariates to use (1st covariate has index 1)
`CHANGEPOINTS`	[integers] indices of changepoints
`STEPWISE`	[`on`,`off`] Switch stepwise selection of changepoints [translated to `logical`].
`AUTODELETE`	[`on`, `off`] Delete changepoints when the corresponding time segment has to litte observations.
`OVERALLCHANGEPOINTS`	[integers] indices of overall changepoints
`RUN`	Signals end of current model specification.
Output
`IMPCOVOUT`	[`on`, `off`] Switch to save variance-covariance matrix
`COVIN`	[`on`, `off`] Switch to read variance-covariance matrix

Encoding issues

To read files containing non-ASCII characters encoded in a format that is not native to your system, specifiy the encoding option. This causes R to re-encode to native encoding upon reading. Input encodings supported for your system can be listed by calling iconvlist(). For more information on Encoding in R, see Encoding.

Note on filenames

If the file is specified using backslashes to separate directories (Windows style), this will be converted to a filename using forward slashes (POSIX style, as used by R).