poppr (version 1.1.5)

gethierarchy: Access and manipulate the population hierarchy for genclone objects.

Description

The following methods allow the user to quickly change the hierarchy or population of a genclone object.

Usage

gethierarchy(x, formula = NULL, combine = TRUE)
sethierarchy(x, value)
sethierarchy(x) <- value
namehierarchy(x, value)
namehierarchy(x) <- value
splithierarchy(x, value, sep = "_")
splithierarchy(x) <- value
addhierarchy(x, value, name = "NEW")
addhierarchy(x) <- value

Arguments

x

a genclone object

formula

a nested formula indicating the order of the population hierarchy.

combine

if TRUE, the levels will be combined according to the formula argument. If it is FALSE, the levels will not be combined.

value

a data frame OR vector OR formula (see details).

sep

a character indicating the character used to separate hierarchical levels. This defaults to "_".

name

an optional name argument for use with addhierarchy if supplying a vector. Defaults to "NEW".

Details

Function Specifics{

• gethierarchy()- This will retrieve the data from thehierarchyslot in thegencloneobject. You have the option to choose specific heirarchical levels using a formula (see below) and you can choose to combine the hierarchical levels (default)
• sethierarchy()- Set or reset the hierarchical levels in yourgencloneobject.
• namehierarchy()- Rename the hierarchical levels.
• splithierarchy()- This is conceptually similar to the default method ofsplitcombine. It is often difficult to import files with several levels of hierarchy as most data formats do not allow unlimited population levels. This is circumvented by collapsing all hierarchical levels into a single population factor with a common separator for each observation. This function will then split those hierarchies for you, but it works best on a hierarchy that only has a single column in it. See the rootrot example below.
• addhierarchy()- Add levels to your population hierarchy. If you have extra hierarchical levels you want to add to your population hierarchy, you can use this method to do so. You can input a data frame or a vector, but if you put in a vector, you have the option to name it (if you are using the functional version and not the assignment version).

}

Argument Specifics{

These functions allow the user to seamlessly assign the hierarchical levels of their genclone object. Note that there are two ways of performing all methods (except for gethierarchy()). They essentially do the same thing except that the assignment method (the one with the "<-") will modify the object in place whereas the non-assignment method will not modify the original object. Due to convention, everything right of the assignment is termed value. To avoid confusion, here is a guide to the inputs:

• sethierarchy()This will be adata.framethat defines the hierarchy for each individual in the rows.
• namehierarchy()This will be either avectoror aformulathat will define the names.
• splithierarchy()This will be aformulaargument with the same number of levels as the hierarchy you wish to split.
• addhierarchy()This will be avectorordata.framewith the same length as the number of individuals in your data.

}

Details on Formulas{

The preferred use of these functions is with a formula object. Specifically, a hierarchical formula argument is used to assign the levels of the hierarchy. An example of a hierarchical formula would be: ~Country/City/Neighborhood or ~Country + Country:City + Country:City:Neighborhood of course, the first method is slightly easier to read. It is important to use hiearchical formulas when specifying hierarchies as other types of formulas (eg. ~Country*City*Neighborhood) might give spurious results.}

See Also

setpop genclone as.genclone

Examples

# let's look at the microbov data set:
data(microbov)
microgc <- as.genclone(microbov)
microgc

# We see that we have three vectors of different names here.
?microbov
# These are Country, Breed, and Species
names(other(microgc))

# Let's set the hierarchy
sethierarchy(microgc) <- data.frame(other(microgc))
microgc

# And change the names so we know what they are
namehierarchy(microgc) <- ~Country/Breed/Species

# let's see what the hierarchy looks like by Species and Breed:
head(gethierarchy(microgc, ~Breed/Species))

# Load our data set and convert it to a genclone object.
Aeut.gc <- read.genalex(system.file("files/rootrot.csv", package = "poppr"))

# we can see the hierarchy is set to Population_Subpopulation.
head(gethierarchy(Aeut.gc))

# We can use splithierarchy() to split them.
splithierarchy(Aeut.gc) <- ~Pop/Subpop
Aeut.gc
head(gethierarchy(Aeut.gc))

# We can also use gethierarchy to combine the hierarchy.
head(gethierarchy(Aeut.gc, ~Pop/Subpop))

# We can also give it a more descriptive name.
namehierarchy(Aeut.gc) <- ~Population/Subpopulation
Aeut.gc
Aeut.gc <- namehierarchy(Aeut.gc, ~Pop/Subpop)
Aeut.gc