---
title: Pedigree_constructor_details
author: Terry Therneau, Elizabeth Atkinson
date: '`r format(Sys.time(),"%d %B, %Y")`'
output:
  rmarkdown::html_vignette:
    toc: yes
    toc_depth: 2
header-includes: \usepackage{tabularx}
vignette: |
  %\VignetteIndexEntry{Pedigree_constructor_details}
  %\VignetteEncoding{UTF-8}
  %\VignetteEngine{knitr::rmarkdown}
---

Introduction
===============

The pedigree routines came out of a simple need -- to quickly draw a
pedigree structure on the screen, within R, that was ``good enough'' to
help with debugging the actual routines of interest, which were those for
fitting mixed effecs Cox models to large family data.  As such the routine
had compactness and automation as primary goals; complete annotation
(monozygous twins, multiple types of affected status) and most certainly
elegance were not on the list.  Other software could do that much
better.
        
It therefore came as a major surprise when these routines proved useful
to others.  Through their constant feedback, application to more
complex pedigrees, and ongoing requests for one more feature, the routine has 
become what it is today.  This routine is still not 
suitable for really large pedigrees, nor for heavily inbred ones such as in
animal studies, and will likely not evolve in that way.  The authors fondest
hope is that others will pick up the project.
        
Pedigree Constructor
========================
The pedigree function is the first step, creating an object of class pedigree.  
It accepts the following input
\begin{description}
\item[id] A numeric or character vector of subject identifiers.
\item[dadid] The identifier of the father.
\item[momid] The identifier of the mother.
\item[sex] The gender of the individual.  This can be a numeric variable
with codes of 1=male, 2=female, 3=unknown, 4=terminated, or NA=unknown.
A character or factor variable can also be supplied containing
the above; the string may be truncated and of arbitrary case.  A sex
value of 0=male 1=female is also accepted.
\item[status] Optional, a numeric variable with 0 = censored and 1 = dead.
\item[relationship] Optional, a matrix or data frame with three columns.
The first two contain the identifier values of the subject pairs, and
the third the code for their relationship: 1 = Monozygotic twin, 2=Dizygotic twin,
3= Twin of unknown zygosity, 4 = Spouse.  
\item[famid] Optional, a numeric or character vector of family identifiers.
\end{description}
        
The [[famid]] variable is placed last as it was a later addition to the
code; thus prior invocations of the function that use positional 
arguments will not be affected.                                      
If present, this allows a set of pedigrees to be generated, one per
family.  The resultant structure will be an object of class
[[pedigreeList]].
        
Note that a factor variable is not listed as one of the choices for the
subject identifier. This is on purpose.  Factors
were designed to accomodate character strings whose values came from a limited
class -- things like race or gender, and are not appropriate for a subject
identifier.  All of their special properties as compared to a character
variable turn out to be backwards for this case, in particular a memory
of the original level set when subscripting is done.

However, due to the awful decision early on in S to automatically turn every
character into a factor --- unless you stood at the door with a club to
head the package off --- most users have become ingrained to the idea of
using them for every character variable. 
(I encourage you to set the global option stringsAsFactors=FALSE to turn
            off autoconversion -- it will measurably improve your R experience).
Therefore, to avoid unnecessary hassle for our users 
the code will accept a factor as input for the id variables, but
the final structure does not retain it.  
Gender and relation do become factors.  Status follows the pattern of the 
survival routines and remains an integer.

We will describe the code in a set of blocks.

## Data Checks and Errors

### Errors1
The code starts out with some checks on the input data.  
Is it all the same length, are the codes legal, etc. Checks for ids being non-missing,
and for sex to be as expected of the codes 1-4 for female/male/unknown/terminated.
          
### Errors2
Create the variables descibing a missing father and/or mother,
which is what we expect both for people at the top of the
pedigree and for marry-ins, \emph{before} adding in the family
id information.  It is easier to do it first.
If there are multiple families in the pedigree, make a working set of
identifiers that are of the form `family/subject'.
Family identifiers can be factor, character, or numeric.

### Errors3-Parents

Next check that any mother or father identifiers are found in the identifier
list, and are of the right sex.
Subjects who don't have a mother or father are founders.  For those people 
both of the parents should be missing.

## Creation of Pedigrees
Now, paste the parts together into a basic pedigree.
The fields for father and mother are not the identifiers of
the parents, but their row number in the structure.

## Finish Object                  

The final structure will be in the order of the original data, and all the
components except [[relation]] will have the same number of rows as the original data.
                
                
Subscipting
==================
                
Subscripting of a pedigree list extracts one or more families from the
list.  We treat character subscripts in the same way that dimnames on
a matrix are used.  Factors are a problem though: assume that we
have a vector x with names ``joe'', ``charlie'', ``fred'', then
[[x['joe']]] is the first element of the vector, but
[[temp <- factor('joe', 'charlie', 'fred'); z <- temp[1]; x[z] ]] will
be the second element! 
R is implicitly using as.numeric on factors when they are a subscript;
this caught an early version of the code when an element of a data
frame was used to index the pedigree: characters are turned into factors
when bundled into a data frame.
                
              Note:
                  \begin{enumerate}
                \item What should we do if the family id is a numeric: when the user
                says [4] do they mean the fourth family in the list or family '4'?
                  The user is responsible to say ['4'] in this case.
                \item  In a normal vector invalid subscripts give an NA, e.g. (1:3)[6], but
                since there is no such object as an ``NA pedigree'', we emit an error
                for this.
                \item The [[drop]] argument has no meaning for pedigrees, but must to be
                a defined argument of any subscript method; we simply ignore it.
                \item Updating the father/mother is a minor nuisance;
                since they must are integer indices to rows they must be
                recreated after selection.  Ditto for the relationship matrix.  
                \end{enumerate}
                  For a pedigree, the subscript operator extracts a subset of individuals.
                We disallow selections that retain only 1 of a subject's parents, since    %'
                they cause plotting trouble later.
                Relations are worth keeping only if both parties in the relation were
                selected.

As Data.Frame for Pedigree
=============================
                
                Convert the pedigree to a data.frame so it is easy to view when removing or
                trimming individuals with their various indicators.  
                The relation and hints elements of the pedigree object are not easy to
                put in a data.frame with one entry per subject. These items are one entry 
                per subject, so are put in the returned data.frame:  id, findex, mindex, 
                sex, affected, status.  The findex and mindex are converted to the actual id
                of the parents rather than the index.
                
                Can be used with as.data.frame(ped) or data.frame(ped). Specify in Namespace
                file that it is an S3 method.
                
                
                This function is useful for checking the pedigree object with the
                $findex$ and $mindex$ vector instead of them replaced with the ids of 
                the parents.  This is not currently included in the package.

Printing Pedigree
===================
                It usually doesn't make sense to print a pedigree, since the id is just   %'
                a repeat of the input data and the family connections are pointers.
                Thus we create a simple summary.
