'rd.tab.txt' reads data from a text file.  The default assumes that the file is tab-delimited, but other delimiters can be specified.  It is assumed that the data is organized as a matrix except possibly for a header section that may contain any sort of text.  RECOMMENDATION: In Excel, create the data text file by first deleting all irrelevant rows (usually at the top of the file) and irrelevant columns (often comments at the right side of particular rows in the file).  Then save the text file as a tab-deliminated text file.  This makes the rest of the work easier.

The 'rd.tab.txt' function operates in 1 of 4 `mmode`s (the argument is written as 'mmode' to avoid conflict with the R function 'mode').  Instructions for using these modes to read in data are given at the end of this documentation.

ARGUMENTS:

'dfile.name' = path and name of the tab-delimited data file.

'mmode = 1' (default) if the desired output is a character vector;

'mmode = 2' if the desired output is a character matrix;

'mmode = 3' if the desired output is a matrix that makes it easy to see the correspondence between variable names and column numbers.  This output is useful when the user needs to find the column numbers of the string variables, the factors, and the numeric variables.

'mmode = 4' if the desired output is a dataframe.  The column names are taken from the header row of the text input if it has a header row.  If not, the column names are simply 'x1', 'x2', .... The columns of the dataframe can be ordered identically to the columns of the input (minus any columns that are dropped), or ordered with all string variables first, all factor variables second, and all numeric variables third.

'ttrunc' truncates the initial input to X characters per element, where X = 12 by default.  If 'ttrunc' is set to NA (default), then no truncation of input is performed.  Truncating the input is useful for producing output that is easy to scan visually, e.g., if some fields contain very long strings, e.g., 70 characters, these elements create output that is difficult to view.

'd.col' specifies the indices in the initial string vector of the first ('col.1') and last ('col.2') column name (or data column in the case where the file does not have an initial row of variable names (column names).  E.g., suppose that the data are initially scanned into a character vector 'tm0'.  Then 'd.col = c(3, 8)' indicates that 'tm0[ 3:8 ]' are the column names for 6 columns of data, or if the input data does not have column names at its head, then 'tm0[ 3:8 ]' is the first row of data (6 items in this row).  Typically, 'd.col' will have the form, e.g., 'd.col = c(1, 5)', indicating that the column names or initial row are the first 5 entries.  

'has.var.header = TRUE' if the data matrix is preceded by a row of variable names.  If 'has.var.header = TRUE' (default), then the first row of the character matrix is interpreted as a vector of variable (column) labels for the dataframe.  If 'has.var.header = FALSE', then the first row of the character matrix is interpreted as data like all other rows of the character matrix.

'sstring', 'ffactor', 'nnum' are three vectors indicating the column numbers of the string, factor and numeric variables, respectively.

'ddrop' is a vector indicating the column number of columns to be omitted from the output.

'ssep' specifies the separation character.  It defaults to tab ('\t').  Specify `ssep = ' '` to delimit with any white space. 

'qquote' specifies the quoting character(s).  It defaults to NULL.  specify `qquote = double-quote character` to specify the double quote character as the quote character.

'skip.lines = 0' (default) means that 0 lines are skipped at the beginning of the file.  If, e.g., 'skip.lines = 5, then the first 5 lines are skipped.  

'var.order = `as.is`' if the outputted dataframe has variables ordered in the same order as the inputted textfile (minus dropped variables); 'var.order = `grouped`' if the columns of the dataframe have all string variables first, all factor variables second, and all numeric variables third.

TO USE THE 'rd.tab.txt' FUNCTION

1.  Create a tab-delimited text or comma-delimited data file. If you are converting an Excel file, it is a good idea to (a) highlight the data area in the work sheet; (b) copy the data; (c) paste the data into a blank worksheet; (d) give a name to this data area like 'data'; and (e) save this worksheet as a tab-delimited file.  The reason for this is that Excel worksheet sometimes have unneeded columns that are treated as data.  By copying exactly the data area to a new worksheet, you guarantee that only the real data area will be saved into the tab-delimited file.  This avoids annoying problems.

2.  Run the function in mmode = 1 to get a long character vector of the entire file.  E.g., 

out.vec = rd.tab.txt(dfile.name = 'my.dat', mmode = 1)

stores the input in a single long character vector.  Use 'out.vec[m:n]' to examine the vector from m to n.  What you want to find is the indices of the first and last variable names in text file that has a header, or the indices of the first and last elements in the first data record (usually first data row) in the file.

3.   Running the function in mmode = 2 is not strictly necessary, but it lets you see the initial matrix that is created internally in the function.  The first row of the matrix is the header of variable names.  All subsequent rows are data in string format.  It is a good idea to check the subject identifier column of this matrix to make sure that it contains the expected kinds of numbers.  This is a diagnostic for the situation where the matrix of data has loaded improperly, with the data not lining up in appropriate columns, as in:

out.vec = rd.tab.txt(dfile.name = 'my.dat', mmode = 2, d.col = c(117,174)))

This indicates that the column names occupy positions 117:174 of the input, and that the data occupy positions 175:length(input).  In this case, the data will have 174 - 117 + 1 = 58 columns.  

4.   To create a dataframe (mmode = 4), you first need to identify which columns represent string variables, factor variables, numeric variables, and which columns should be dropped.  Running 'rd.tab.txt' in mmode = 3 produces output that makes it easy to see which columns should be designated as string, factor, numeric or dropped variables, as in:

out.vec = rd.tab.txt(dfile.name = 'my.dat', mmode = 3, d.col = c(117,174)))

5.   Having determined which columns are string, factor, numeric or dropped variables, one can produce a dataframe output with variables ordered 'as.is', or 'grouped'.  E.g.

tmd4 = rd.tab.txt(dfile.name = 'my.dat', mmode = 4, 
   d.col = c(117, 174), sstring = c(1:3, 47:57), ffactor = NA, 
   nnum = 4:46, ddrop = 58), var.order = 'as.is') 

produces a dataframe output with the variables ordered as in the input file.