OpenRepGrid (version 0.1.18)

importTxt: Import grid data from a text file.

Description

You can define a grid using a standard text editor and saving it as a .txt file. The Details section describes the required format of the .txt file. However, you may also consider using the Excel format instead, as it has a more intuitive format (see importExcel()).

Usage

importTxt(file, dir = NULL, min = NULL, max = NULL)

Value

   A single `repgrid` object in case one file and
           a list of `repgrid` objects in case multiple files are imported.

Arguments

file

A vector of filenames including the full path if file is not in current working directory. File can also be a complete URL. The file suffix has to be .txt.

dir

Alternative way to supply the directory where the file is located (default NULL).

min

Optional argument (numeric, default NULL) for minimum rating value in grid.

max

Optional argument (numeric, default NULL) for maximum rating value in grid.

Details

The .txt file has to be in a fixed format. There are three mandatory blocks each starting and ending with a predefined tag in uppercase letters. The first block starts with ELEMENTS and ends with END ELEMENTS. It contains one element per line. The other mandatory blocks are CONSTRUCTS and RATINGS (see below). In the block containing the constructs the left and right pole are separated by a colon (:). To define missing values use NA. The block PREFERRED is optional. Each line indicated the preferred construct pole. Allowed values are left, right, none (no pole preferred), and NA (unknown). The block RANGE is optional but recommended. It gives the rating scale range defined by two numbers. The order of the blocks is arbitrary. All text oustide the blocks is discarded and can be used for comments.

The content of a sample .txt file is shown below. The package also contains a sample file (see Examples).

---------------- sample .txt file -------------------
    Note: anything outside the tag pairs is discarded
ELEMENTS
element 1
element 2
element 3
END ELEMENTS
CONSTRUCTS
left pole 1 : right pole 1
left pole 2 : right pole 2
left pole 3 : right pole 3
left pole 4 : right pole 4
END CONSTRUCTS
PREFERRED
left
left
right
none
END PREFERRED
RATINGS
1 3 2
4 1 1
1 4 4
3 1 1
END RATINGS
RANGE
1 4
END RANGE
------------------ end of file ------------------

Note that the maximum and minimum value has to be defined using the min and max arguments if no RANGE block is contained in the data file. Otherwise the scaling range is inferred from the available data and a warning is issued as the range may be erroneous. This may effect other functions that depend on knowing the correct range and it is thus strongly recommended to set the scale range correctly.

See Also

Import data importDataframe(), importExcel(), importGridcor(), importGridstat(), importGridsuite(), importScivesco()

Examples

# Import a .txt file delivered along with the package
file <- system.file("extdata", "grid_01.txt", package = "OpenRepGrid")
rg <- importTxt(file)

# To see the structure of the file, try opening it as follows.
# (may not work on all systems)
if (FALSE) {
file.show(file)
}

# Import more than one .txt file
files <- system.file("extdata", c("grid_01.txt", "grid_02.txt"), package = "OpenRepGrid")
rgs <- importTxt(files)