R: Load ABI Output Files

load.abi {TRAMPR}

R Documentation

Load ABI Output Files

Description

These functions help convert data from Applied Biosystems Gene Mapper (ABI) output format into TRAMPsamples objects for analysis. Note that this operates on the summarised output (a text file), rather than the .fsa files containing data for individual runs.

Details of the procedure of this function are given below, and a worked example is given in the package vignette; type vignette("TRAMPRdemo") to view it.

The function peakscanner.to.genemapper is an experimental function to convert from peakscanner output to abi genemapper output. The peakscanner output is very slightly different in format, and currently load.abi is very fussy about the input file's structure. Eventially load.abi will be made more tolerant, but as an interim solution, run peakscanner.to.genemapper on your file. By default, running peakscanner.to.genemapper(myfile.csv) will produce a file myfile.txt. This can then be loaded using load.abi as described below, specifying myfile.txt as the file argument.

Usage

load.abi(file, file.template, file.info, primer.translate, ...)
load.abi.create.template(file, file.template)
load.abi.create.info(file, file.template, file.info)

peakscanner.to.genemapper(filename, output)

Arguments

`file`	The name of the file from which the ABI data are to be read from.
`file.template`	The name of the file containing the “template” file (see Details).
`file.info`	(Optional) the name of the file containing extra information associated with each sample (see Details).
`primer.translate`	List used to translate dye codes into primers. The same codes are assumed to apply across the whole file. See Details for format.
`...`	Additional objects to incorportate into a `TRAMPsamples` object. See `TRAMPsamples` for details.
`filename`	In `peakscanner.to.genemapper`, the name of the csv file containing output.
`output`	In `peakscanner.to.genemapper`, the name of the file to be output in abi format (if omitted, this will be automatically generated).

Details

Some terminology: a “sample” refers to a physical sample (e.g. a root tip), while a “run” refers to an individual TRFLP run (i.e. one enzyme and one primer). Because two primers are run at once, each “runfile” contains information on two “runs”, but each “sample” may contain more than one “runfile”. Runfiles are distinguished by different sample.file.name values in the ABI file, while different samples are distinguished by different sample.fk/sample.pk values.

primer.translate is a list used to translate between the dyes recorded in the ABI file and the primers used. Each element corresponds to a different primer, and is a vector of different colour dyes. The list:

list(ITS1F="B", ITS4="G")

would translate all dyes with the value "B" to "ITS1F", and all dyes with the value "G" to "ITS4". The list:

list(ITS1F="B", ITS4=c("G", "Y"))

would do the same, except that both "G" and "Y" dyes would be converted to "ITS4". If a dye is used in the data that is not represented within primer.translate, then it will be excluded (e.g., all rows of data with dye as "R" will be excluded).

The procedure for loading in ABI data is:

Create the “template” file. Template files are required to record which enzymes were used for each run, since that is not included in the ABI output, and to group together separate runs (typically different enzymes) that apply to the same individual. The function load.abi.create.template will create a template that contains all the unique file names found in the ABI file (as sample.file.name), and blank columns titled enzyme and sample.index. Running

load.abi.create.template(x)

where x is the name of your ABI file will create a template file in the same directory as the ABI file. The function will print the name and location of the template file to the console.
Edit the template file and save. The enzyme and sample.index columns are initially empty and need filling in, which can be done in Excel, or another spreadsheet program. The sample.index column links sample.file.name back to an individual sample; multiple sample.file.names that share sample.index values come from the same individual sample. (If editing with Excel, ignore all the warnings about incompatible file formats when saving.) sample.index should be a positive integer (but see Note below).
Optionally create an “info” file, which is useful if you want to associate extra information against your samples. The function load.abi.create.info will create an info file that contains all the unique values of sample.index, and an empty column titled species. The species column can be filled in where the species is known (e.g. from collections of sporocarps). Any additional columns may be added. Running

load.abi.create.info(x)

where x is the name of your ABI file will create an info file in the same directory as the ABI file. The function will print the name and location of the info file to the console. Edit and save this file.
Create the TRAMPsamples object by running load.abi. This loads your ABI data, plus the new template file, plus an optional information file. Running

my.samples <- load.abi(x, primer.translate=primer.translate)

will create an object “my.samples” containing your data.

By default, the filenames of the template and info files will be automatically generated: <prefix>.<ext> becomes <prefix>_template.csv or <prefix>_info.csv. If you choose to specify file.template or file.info manually when running load.info.create.template or load.info.create.info, you must use the same values of file.template and file.info when running load.abi.

Warning

Do not change the names of any columns produced by load.abi.create.template or load.abi.create.info.

Note

There is no reason that data from other types of output files could not be manually imported using TRAMPsamples. We welcome contributions for other major data formats.

When creating sample.index values, these should be positive integers. If you enter strings (e.g. a1, b1), these will be automatically converted into integers. Once loaded, sample.pk/sample.fk is always a positive integer key, but sample.index will be retained as your string keys.