R: Convert Ploidy Format of a Dataset

reformatPloidies {polysat} | R Documentation

## Convert Ploidy Format of a Dataset

### Description

This function changes the class of the object in the `Ploidies` slot of a `"gendata"` object. (See the four subclasses described in `"ploidysuper"`.) Existing ploidy data can either be erased or, if possible, used in the new format.

### Usage

    reformatPloidies(object, output = "collapse", na.rm = FALSE, erase = FALSE)

### Arguments

`object` | A `"gendata"` object.
`output` | A character string indicating the desired result of the conversion: `"matrix"` if ploidies should be indexed by both sample and locus, `"sample"` if ploidies should be indexed only by sample, `"locus"` if ploidies should be indexed only by locus, `"one"` if there should be one ploidy for the entire dataset, or `"collapse"` if ploidies should be converted to the simplest possible format.
`na.rm` | Boolean. If `FALSE`, `NA` is treated as a unique ploidy. If `TRUE`, `NA` values are ignored assuming that each sample and/or locus has only one ploidy otherwise. This argument is passed directly to `plCollapse`.
`erase` | Boolean. If `TRUE`, the new `Ploidies` slot is simply filled with `NA` instead of existing ploidy values from `object`.

### Details

This is a versatile function that can accomplish several tasks relating to the format of ploidies in the dataset:

If you wish to change how ploidy is indexed, but don't care about keeping any data in the `Ploidies` slot, set `erase=TRUE` and `output` to `"matrix"`, `"sample"`, `"locus"`, or `"one"`.

If you wish to keep ploidy data while moving from a simpler format to a more complex format (i.e. from `"one"` to any other format, or from `"sample"` or `"locus"` to `"matrix"`), leave `erase=FALSE` and set `output` to the desired format. Existing data will be duplicated to fill out the new format. For example, if ploidies were indexed by sample and you change to matrix format, the ploidy that had previously been recorded for each sample will be duplicated for each locus.

If you wish to keep ploidy data while performing any other format conversions (e.g. `"matrix"` to `"sample"` or `"sample"` to `"locus"`), the function will check that there is one unique ploidy for each sample, locus, or the entire dataset (as appropriate), and will produce an error if the conversion cannot be done without a loss of information.

If you wish to keep ploidy data and convert to the simplest possible format, set `output="collapse"`. The function will automatically determine the simplest format for conversion without loss of data. (The `read` functions in polysat that take ploidy data from the input file use this option.)

### Value

A `"gendata"` object that is a copy of `object` but with the `Ploidies` slot converted to a new class.

### Author(s)

Lindsay V. Clark

### See Also

`plCollapse`, `"ploidysuper"`

### Examples

    # Make a new "genambig" object for this example
    testdata <- new("genambig")
    Ploidies(testdata)

    ## If you need to reformat before you have entered any ploidy
    ## information:

    # convert from matrix to sample format
    testdata <- reformatPloidies(testdata, output="sample")
    Ploidies(testdata)

    ## If you have entered ploidy information but realized you can use a
    ## simpler format:

    # Enter some ploidies
    Ploidies(testdata)[1] <- 2
    Ploidies(testdata)

    # Convert from "sample" to "one" with na.rm=TRUE
    testdata <- reformatPloidies(testdata, na.rm=TRUE, output="one")
    Ploidies(testdata)

    ## If you change your mind and want to go back to a more complex format

    # Convert from "one" to "locus"
    testdata <- reformatPloidies(testdata, output="locus")
    Ploidies(testdata)

[Package polysat version 1.7-6 Index]