PedigreeUtils {FamAgg} | R Documentation

## Basic pedigree utilities

### Description

Utility functions to access, modify or subset pedigrees. Most of these functions can be applied to simple `data.frame` in pedigree format or `pedigree` or `pedigreeList` objects defined in the `kinship2` package.

### Usage

    ## S4 method for signature 'missing'
    cliques(object, ...)

    connectedSubgraph(graph, nodes, mode="all", all.nodes=TRUE, ifnotfound)

    ## S4 method for signature 'FAData'
    countGenerations(object, id=NULL, direction="down", ...)

    ## S4 method for signature 'FAData'
    estimateGenerations(object, family=NULL, ...)

    ## S4 method for signature 'FAData'
    findFounders(object, family=NULL, id = NULL, ...)

    ## S4 method for signature 'FAData'
    generationsFrom(object, id=NULL, ...)

    ## S4 method for signature 'FAData'
    getAncestors(object, id=NULL, max.generations=3, ...)

    ## S4 method for signature 'FAData'
    getChildren(object, id=NULL, max.generations=16, ...)

    ## S4 method for signature 'FAData'
    getCommonAncestor(object, id, method="min.dist")

    ## S4 method for signature 'FAData'
    getFounders(object, ...)

    ## S4 method for signature 'FAData'
    getMissingMate(object, id=NULL, ...)

    ## S4 method for signature 'FAData'
    getSiblings(object, id=NULL, ...)

    ## S4 method for signature 'FAData'
    getSingletons(object, ...)

    ped2graph(ped)

    ## S4 method for signature 'FAData'
    removeSingletons(object, ...)

    ## S4 method for signature 'data.frame'
    removeSingletons(object, ...)

    subPedigree(ped, id=NULL, all=TRUE)

    ## S4 method for signature 'FAData'
    shareKinship(object, id)

### Arguments

(in alphabetic order)

`all` | For `subPedigree`: if all individuals have to be present in the sub-pedigree.
`all.nodes` | For `connectedSubgraph`: if all nodes have to be present in the resulting graph, or only those that are connected with each other.
`direction` | For `countGenerations`: whether the number of ancestor (`"up"`) generations or offspring (`"down"`) generation should be counted.
`family` | A character or numeric representing the family id. For `doFindFounders`: the id of the family in the pedigree for which the founders should be identified. Uses the first family in the pedigree if not specified. For `estimateGenerations`: optional id of the family if generation numbers should only be calculated for one family. Otherwiseif, the generations are estimated for all families (separately) in the object.
`graph` | An `igraph` graph object.
`id` | A character or numeric vector length 1 or longer specifying the id(s) of the individual(s). For `generationsFrom` and `findFounders` only a single id should be submitted.
`ifnotfound` | For `connectedSubgraph`: if not defined, the function throws an error if no subgraph can be specified. If defined, its value is returned if no subgraph was found.
`max.generations` | For `getAncestors` and `getChildren`: the maximal number of ancestor or offspring generations that should be returned.
`method` | For `getCommonAncestor`: the method by which the closest common ancestor sould be identified. Either `"min.dist"` (ancestor with the minimal distance to any of the individuals) or `"smallest.mean.dist"` (ancestor with the smallest mean distance to any of the individuals).
`mode` | For `connectedSubgraph`: either `"all"`, `"in"`, `"out"` specifying how distances and paths between individual nodes should be determined. See help for function `shortest_paths` in package `igraph` for more details.
`nodes` | For `connectedSubgraph`: A character vector of node (vertex) names for which the subgraph should be defined.
`object` | For `cliques`: passed to the `cliques` function from the `igraph` package. For all other methods: either a `FAData` object (or any object inheriting from it), a `data.frame`, `pedigree` or `pedigreeList` objects (the latter being defined in the `kinship2` package).
`ped` | Either a `data.frame` or a `pedigree` object specifying the pedigree. If a `data.frame` is submitted, the columns `id`, `family`, `father`, `mother` and `sex` are required.
`...` | For `cliques`: additional arguments passed to the `cliques` function from the `igraph` package.

### Value

Refer to the method and function description above for detailed information on the returned result object.

### Basic pedigree utilities

countGenerations

  Count the generations up- or down the pedigree for the specified individual(s), i.e. determine the number of ancestor or offspring generations defined in the pedigree for the specified individual(s). Returns a named numeric vector, names corresponding to the individual's id, with the number of generations for each specified individual.

findFounders

  Identifies the founder couple with the largest number of offspring generations in the pedigree. The provided pedigree object/data.frame can contain pedigrees of multiple families, thus, to identify the founder pair for a family its ID can be provided with the `family` parameter. Alternatively, the ID of an individual can be specified, in which case the founder pair of the (full) pedigree of the specified individual is identified. If two or more couples have the same, largest number of offspring generations, the first couple is selected. Returns a character vector of length 2 with the ids of the founder individuals.

getFounders

  Returns the ids of all founders in the pedigree. A founder is an individual from which neither father nor mother is known in the pedigree.

getSingletons

  Returns the ids of all singletons, i.e. individuals in the pedigree that are not connected to any other individual (have no parents in the pedigree and no children).

getAncestors

  Identify and return the ids of ancestor generations (up to `max.generations`) for the specified individual(s).

getChildren

  Identify and return the ids of offspring generations (up to `max.generations`) for the specified individual(s).

getCommonAncestor

  Finds the closest common ancestor between specified individuals (2 or more ids are required). Returns a character vector with the ids of the ancestors or `NA` if no common ancestor was found.

getMissingMate

  The function evaluates if in the sub-pedigree defined by the specified ids one or more mates (spouse) are missing and if so it returns their ids.

getSiblings

  Get siblings for the specified id(s). Returns their ids as character, or numeric vector.

removeSingletons

  Removes all unconnected individuals (i.e. singletons) from the pedigree. Returns a `data.frame` with the pedigree cleaned from all singletons. Note that, due to internal sanitizing, columns `"father"` and `"mother"` in the resulting `data.frame` have a `NA` for individuals for which the father or mother is not known in the pedigree.

subPedigree

  Finds the smallest pedigree containing all specified individuals. Depending on the input, a `data.frame`, `pedigree` or `pedigreeList`.

### Advanced pedigree methods

estimateGenerations

  Estimates generation levels/numbers for each, or only one, family in the object. Generation numbers are always relative to the founder couple (defined by `findFounders`). Returns (always) a named list of generation numbers. The names of the list represent the family id, the names of the numeric vector of generations the id of the individuals in the family.

generationsFrom

  Determine generations starting from the specified individual. Siblings including their mates and all other in the same generation () are assigned generation 0, ancestor generations (all their parents etc) negative generation numbers, decreasing with ancestor level and their offspring positive numbers, increasing with each generation. Generations are only estimated within the family of the individual, also, if the pedigree consists of un-connected sub-pedigree, generation numbers will only be calculated for the sub-pedigree containing the specified individual. The function returns a named numeric vector of generation numbers, the names corresponding to the ids of the individuals in the specified individual's family. Not connected individuals in the family get a `NA` generation number.

shareKinship

  Finds all related individuals (individuals sharing kinship with the individual) for the specified individual(s) in the pedigree and returns their ids as a character vector.

### Graph theory related functions

cliques

  Wrapper method passing all arguments to the `cliques` function from the `igraph` package.

connectedSubgraph

  Finds the (eventually smallest) connected subgraph of all specified nodes. Returns an `igraph` object representing the subgraph of the specified nodes.

ped2graph

  Transforms the pedigree into a (directed) graph with the direction of the edges being always from parent to child. An `igraph` object.

### Author(s)

Johannes Rainer.

### See Also

`pedigree`, `FAData`, `FAProbResults`, `FAKinGroupResults`, `FAKinSumResults`, `PedigreeAnalysis`

### Examples

    ##########################
    ##
    ##  Defining a small pedigree
    ##
    ## load the Minnesota Breast Cancer record and subset to the
    ## first families.
    data(minnbreast)
    mbsub <- minnbreast[minnbreast$famid==4 | minnbreast$famid==5, ]
    mbped <- mbsub[, c("famid", "id", "fatherid", "motherid", "sex")]
    ## renaming column names
    colnames(mbped) <- c("family", "id", "father", "mother", "sex")

    ## plot the pedigree for family 4 to get an overview.
    switchPlotfun(method="ks2paint")
    fam4 <- mbped[mbped$family==4, ]
    doPlotPed(individual=fam4$id, father=fam4$father, mother=fam4$mother,
              gender=fam4$sex, device="plot")

    ## find the closest common ancestor between individuals 23, 3 and 8
    getCommonAncestor(fam4, id=c(23, 3, 8))

    ## create the smallest sub-pedigree for individuals 21, 22 and 25
    subPedigree(fam4, id=c(21, 22, 25))
    ## plot that
    fam4sub <- subPedigree(fam4, id=c(21, 22, 25))
    doPlotPed(individual=fam4sub$id, father=fam4sub$father, mother=fam4sub$mother,
              gender=fam4sub$sex, device="plot")

    #########################
    ##
    ##  Basic pedigree utils
    ##
    ## Note: the same methods can be applied to a data.frame representing
    ## a pedigree, or a FAData, pedigree or pedigreeList object.

    ## Find the founder couple for family 4
    findFounders(fam4, family=4)

    ## Alternatively, find the founders for the pedigree in which ibdividual 20 is a
    ## member
    findFounders(fam4, id = 20)

    ## Return all founders in the pedigree.
    getFounders(fam4)

    ## Get all founders without children (i.e. singletons).
    getSingletons(fam4)

    ## Clean the pedigree from all singletons
    fam4noS <- removeSingletons(fam4)
    nrow(fam4)
    nrow(fam4noS)

    ## Count the offspring generations for individual "4"
    countGenerations(fam4, id="4")

    ## Get the ids of all ancestors for that individual
    getAncestors(fam4, id="4")

    ## Get the ids of the children of this individual
    getChildren(fam4, id="4", max.generations=1)

    ## Get the ids of the complete offspring for this individuals
    getChildren(fam4, id="4")

    ## Create a FAData object from the pedigree data.frame
    fad <- FAData(fam4)
    ## get the list of all ids sharing kinship with individuals
    ## 5 and 9
    shareKinship(fad, id=c("5", "9"))

    ## Count the numbers of generations of ancestors for individual 12
    countGenerations(fad, id="12", direction="up")

    ## Count the numbers of offspring generations for individuals 2 and 29
    countGenerations(fad, id=c("2", "29"))

    ## Get all brothers/sisters for individual 9
    getSiblings(fad, id="9")

    ## Determine generation levels starting from individual "9"
    generationsFrom(fad, id="9")

    ## Estimate generations relative to the founder couple for each
    ## family in the submitted object, a data.frame in the example below
    estimateGenerations(mbped)

    #########################
    ##
    ##  Graph utilities
    ##
    ## Convert the pedigree into a graph
    pgraph <- ped2graph(fam4)
    plot(pgraph)

    ## Make a subgraph containing nodes 10, 22, 12 and 14
    sgraph <- connectedSubgraph(pgraph, c("10", "22", "12", "14"))
    plot(sgraph)

[Package FamAgg version 1.15.1 Index]