R: Accessor and Replacement Functions for "gendata" Objects

Accessors {polysat} | R Documentation

## Accessor and Replacement Functions for "gendata" Objects

### Description

The accessor functions return information that is contained, either directly or indirectly, in the slots of a `gendata` object. The replacement functions alter information in one or more slots as appropriate.

### Usage

    Samples(object, populations, ploidies)
    Samples(object) <- value
    Loci(object, usatnts, ploidies)
    Loci(object) <- value
    PopInfo(object)
    PopInfo(object) <- value
    PopNames(object)
    PopNames(object) <- value
    PopNum(object, popname)
    PopNum(object, popname) <- value
    Ploidies(object, samples, loci)
    Ploidies(object) <- value
    Usatnts(object)
    Usatnts(object) <- value
    Description(object)
    Description(object) <- value
    Missing(object)
    Missing(object) <- value
    Present(object)
    Present(object) <- value
    Absent(object)
    Absent(object) <- value
    Genotype(object, sample, locus)
    Genotype(object, sample, locus) <- value
    Genotypes(object, samples = Samples(object), loci = Loci(object))
    Genotypes(object, samples = Samples(object), loci = Loci(object)) <- value

### Arguments

`object` | An object of the class `gendata` or one of its subclasses.
`populations` | A character or numeric vector indicating from which populations to return samples. (optional)
`ploidies` | A numeric vector indicating ploidies, if only samples or loci with a certain ploidy should be returned. (optional)
`sample` | A character string or number indicating the name or number of the sample whose genotype should be returned.
`locus` | A character string or number indicating the name or number of the locus whose genotype should be returned.
`samples` | A character or numeric vector indicating samples for which to return genotypes or ploidies. (optional)
`loci` | A character or numeric vector indicating loci for which to return genotypes or ploidies. (optional)
`usatnts` | A numeric vector indicating microsatellite repeat lengths, where only loci of those repeat lengths should be returned. (optional)
`popname` | Chacter string or vector. The name(s) of the population(s) for which to retrieve or replace the corresponding `PopInfo` number(s). The replacement function should only be used for one population at a time.
`value` | For `Samples`: a character vector of sample names. For `Loci`: a character vector of locus names. For `PopInfo`: A numeric vector (integer or can be coerced to integer) indicating the population identities of samples. For `PopNames`: A character vector indicating the names of populations. For `PopNum`: A number (integer or can be coerced to integer) that should be the new population number associated with `popname`. For `Ploidies`: A numeric vector or matrix (integer or can be coerced to integer) indicating the ploidy of each sample, locus, and/or the dataset. See `reformatPloidies` and `"ploidysuper"`. For `Usatnts`: A numeric vector (integer or can be coerced to integer) indicating the repeat type of each microsatellite locus. Dinucleotide repeats should be represented with `2`, trinucleotide repeat with `3`, and so on. If the alleles for a given locus are already stored in terms of repeat number rather than fragment length in nucleotides, the `Usatnts` value for that locus should be `1`. For `Description`: A character string or character vector describing the dataset. For `Missing`: A symbol (usually an integer) to be used to indicate missing data. For `Present`: A symbol (usually an integer) to be used to indicate the presence of an allele. For `Absent`: A symbol (usually an integer) to be used to indicate the absence of an allele. For `Genotype`: a vector of alleles, if the object is of class `genambig`. For `Genotypes`: A list of vectors (genotypes), of the same dimensionality as `c(length(samples), length(loci))`, if the object is of class `genambig`. If the object is of class `genbinary`, `value` should be a matrix, with column names of the form `"locus.allele"`. See `Genotypes<-,genbinary-method` for more information.

### Details

`Samples<-` and `Loci<-` can only be used to change sample and locus names, not to add or remove samples and loci from the dataset.

For slots that require integer values, numerical values used in replacement functions will be coerced to integers. The replacement functions also ensure that all slots remain properly indexed.

The `Missing<-` function finds any genotypes with the old missing data symbol and changes them to the new missing data symbol, then assigns the new symbol to the slot that indicates what the missing data symbol is. `Present<-` and `Absent<-` work similarly for the `genbinary` class.

The `Genotype` access and replacement functions deal with individual genotypes, which are vectors in the `genambig` class. The `Genotypes` access and replacement functions deal with lists of genotypes.

The `PopInfo<-` replacement function also adds elements to `PopNames(object)` if necessary in order to have names for all of the populations. These will be of the form `"Pop"` followed by the population number, and can be later edited using `PopNames<-`.

The `PopNum<-` replacement function first finds all samples in the population `popname`, and replaces the number in `PopInfo(object)` for those samples with `value`. It then inserts `NA` into the original `PopNames` slot that contained `popname`, and inserts `popname` into `PopNames(object)[value]`. If this results in two populations being merged into one, a message is printed to the console.

### Value

`PopInfo`, `PopNames`, `Missing`, `Description`, `Usatnts`, `Ploidies` and `Genotypes` simply return the contents of the slots of the same names (or in the case of `Ploidies`, `object@Ploidies@pld` is returned). `Samples` and `Loci` return character vectors taken from the `names` of other slots (`PopInfo` and `Usatnts`, respectively; the initialization and replacement methods ensure that these slots are always named according to samples and loci). `PopNum` returns an integer vector indicating the population number(s) of the population(s) named in `popname`. `Genotype` returns a single genotype for a given sample and locus, which is a vector whose exact form will depend on the class of `object`.

### Author(s)

Lindsay V. Clark

### See Also

`deleteSamples`, `deleteLoci`, `viewGenotypes`, `editGenotypes`, `isMissing`, `estimatePloidy`, `merge,gendata,gendata-method`, `gendata`

### Examples

    # create a new genambig (subclass of gendata) object to manipulate
    mygen <- new("genambig", samples=c("a", "b", "c"), loci=c("locG",
    "locH"))

    # retrieve the sample and locus names
    Samples(mygen)
    Loci(mygen)

    # change some of the sample and locus names
    Loci(mygen) <- c("lG", "lH")
    Samples(mygen)[2] <- "b1"

    # describe the dataset
    Description(mygen) <- "Example dataset for documentation."

    # name some populations and assign samples to them
    PopNames(mygen) <- c("PopL", "PopK")
    PopInfo(mygen) <- c(1,1,2)
    # now we can retrieve samples by population
    Samples(mygen, populations="PopL")
    # we can also adjust the numbers if we want to make them
    # match another dataset
    PopNum(mygen, "PopK") <- 3
    PopNames(mygen)
    PopInfo(mygen)
    # change the population identity of just one sample
    PopInfo(mygen)["b1"] <- 3

    # indicate that both loci are dinucleotide repeats
    Usatnts(mygen) <- c(2,2)

    # indicate that all samples are tetraploid
    Ploidies(mygen) <- 4
    # or
    Ploidies(mygen) <- rep(4, times = length(Samples(mygen)) * length(Loci(mygen)))
    # actually, one sample is triploid
    Ploidies(mygen)["c",] <- 3
    # view ploidies
    Ploidies(mygen)

    # view the genotype array as it currently is: filled with missing
    # values
    Genotypes(mygen)
    # fill in the genotypes
    Genotypes(mygen, loci="lG") <- list(c(120, 124, 130, 136), c(122, 120),
                                        c(128, 130, 134))
    Genotypes(mygen, loci="lH") <- list(c(200, 202, 210), c(206, 208, 210,
                                                            214),
                                        c(208))
    # genotypes can also be edited or retrieved by sample
    Genotypes(mygen, samples="a")
    # fix a single genotype
    Genotype(mygen, "a", "lH") <- c(200, 204, 210)
    # retrieve a single genotype
    Genotype(mygen, "c", "lG")

    # change a genotype to being missing
    Genotype(mygen, "c", "lH") <- Missing(mygen)
    # show the current missing data symbol
    Missing(mygen)
    # an example of genotypes where one contains the missing data symbol
    Genotypes(mygen, samples="c")
    # change the missing data symbol
    Missing(mygen) <- as.integer(-1)
    # now look at the genotypes
    Genotypes(mygen, samples="c")

[Package polysat version 1.7-6 Index]