GameteCompetition.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Tutorial of MendelGameteCompetition"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Julia version\n",
    "Current code supports Julia version 1.0+ "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Overview\n",
    "Mendel Gamete Competition is a component of the umbrella [OpenMendel](https://openmendel.github.io) project. The gamete competition model is an application of the Bradley-Terry model and can be considered a parametric form of the TDT for use with pedigree data because, besides getting p-values, we also get a measure of the strength of the allelic associations. The Bradley-Terry model was originally applied to problems such as ranking teams in a sports league based on the intra-league win/loss records. In genetics, alleles assume the role of teams, and transmission parameters (the τ's) assume the role of the winning propensities [2](https://openmendel.github.io/MendelGameteCompetition.jl/#2), [3](https://openmendel.github.io/MendelGameteCompetition.jl/#3). As implemented in this version of OpenMendel, the gamete competition is an affected only association analysis and we assume the allele frequencies for the marker are known without error.  Let allele i be assigned a segregation parameter *τ<sub>i</sub>*, then the probability that a heterozygous parent with genotype *i = j* transmits allele i is the ratio *τ<sub>i</sub>/(τ<sub>i</sub>+τ<sub>j</sub>)*.  Because this ratio is invariant when *τ<sub>i</sub>* and *τ<sub>j</sub>* are multiplied by the same constant c, we need to impose the constraint that the most frequent allele k has segregation parameter *τ<sub>k</sub>* = 1. These propensities replace the normally used Mendelian segregation parameters for heterozygous parents' transmissions in the Elston-Stewart-Ott representation of the likelihood of the pedigrees.  In fact, under the null of no association between the marker and the trait in the gamete competition, Mendelian segregation ratios hold for heterozygous parents' transmissions so that *τ<sub>i</sub>*=1 is true for all alleles i and the likelihood reverts to the standard one. Note that the transmissions for homozygous parents always conform to standard Mendelian segregation ratios both under the null or alternative thus, like the TDT, only heterozygous parents are informative.  To test whether Mendelian segregation can be rejected, we estimate these τ's by maximum likelihood and conduct a likelihood ratio test. P-values are calculated assuming that the likelihood ratio test statistic is asymptotically chi square distributed. The degrees of freedom are equal to the number of alleles minus 1."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## When to use MendelGameteCompetition\n",
    "The Gamete Competition model applies to pedigrees, including those with missing marker data. With too many marker alleles computational efficiency suffers and large sample statistical assumptions become suspect. We recommend consolidating alleles until at most eight alleles remain and each has a frequency of 0.05 or greater. If the fraction of missing data is large, ethnic stratification may come into play. One remedy is to limit analysis to a single ethnic group; another is to use ethnic-specific allele frequencies. If you opt for the latter strategy, then you cannot simultaneously estimate allele frequencies and transmission parameters."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Installation\n",
    "\n",
    "*Note: Since the OpenMendel packages are not yet registered, the three OpenMendel packages (1) [SnpArrays](https://openmendel.github.io/SnpArrays.jl/latest/), (2) [MendelSearch](https://openmendel.github.io/MendelSearch.jl), and (3) [MendelBase](https://openmendel.github.io/MendelBase.jl) **must** be installed before any other OpenMendel package is installed. It is easiest if these three packages are installed in the above order.*\n",
    "\n",
    "If you have not already installed the MendelGameteCompetition, then within Julia, use the package manager to install MendelGameteCompetition:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "] add https://github.com/OpenMendel/MendelGameteCompetition.jl.git"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "or once the OpenMendel packages are registered simply use:\n",
    "\n",
    "`pkg> add MendelGameteCompetition`\n",
    "\n",
    "This package supports Julia v1.0+"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Input Files\n",
    "The MendelGameteCompetition analysis package accepts the following input files. Example input files can be found in the [data](https://github.com/OpenMendel/MendelGameteCompetition.jl/tree/master/data) subfolder of the MendelGameteCompetition project. (An analysis won't always need every file type below.)\n",
    "\n",
    "* [Control File](https://openmendel.github.io/MendelGameteCompetition.jl/#control-file): Specifies the names of your data input and output files and any optional parameters (*keywords*) for the analysis. (For a list of common keywords, see [Keywords Table](https://openmendel.github.io/MendelBase.jl/#keywords-table)). The Control file is optional. If you don't use a Control file you will enter your keywords directly in the command line.\n",
    "* [Locus File](https://openmendel.github.io/MendelBase.jl/#locus-file): Names and describes the genetic loci in your data.\n",
    "* [Pedigree File](https://openmendel.github.io/MendelBase.jl/#pedigree-file): Gives information about your individuals, such as name, sex, family structure, and ancestry.\n",
    "* [Phenotype File](https://openmendel.github.io/MendelBase.jl/#phenotype-file): Lists the available phenotypes."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Control file\n",
    "The Control file is a text file consisting of keywords and their assigned values. The format of the Control file is:\n",
    "\n",
    "`Keyword = Keyword_Value(s)`\n",
    "\n",
    "Below is an example of a simple Control file to run Gamete Competition:\n",
    "\n",
    "    #\n",
    "    # Input and Output files.\n",
    "\t#\n",
    "\tlocus_file = gamete competition LocusFrame.txt\n",
    "\tpedigree_file = gamete competition PedigreeFrame.txt\n",
    "\toutput_file = gamete competition Output.txt\n",
    "\t#\n",
    "\t# Analysis parameters for Gamete Competition option.\n",
    "\t#\n",
    "\tdisease_status = ACE\n",
    "\taffected_designator = 1\n",
    "\tstandard_errors = true\n",
    "\n",
    "In the example above, there are six keywords. The first three keywords specify the input and output files: *gamete competition LocusFrame.txt*, *gamete competition PedigreeFrame.txt*, and *gamete competition Output.txt*. The last three keywords specify the analysis parameters: *disease_status*, *affected_designator*, and *standard_errors*. The text after the '=' are the keyword values."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Keywords<a id=\"keywords-table\"></a>\n",
    "This is a list of OpenMendel keywords specific to Gamete Competition. A list of OpenMendel keywords common to most analysis package can be found [here](https://openmendel.github.io/MendelBase.jl/#keywords-table). The names of keywords are *not* case sensitive. (The keyword values *may* be case sensitive.)\n",
    "\n",
    "\n",
    "|Keyword          |   Default Value    | Allowed Values |  Short Description       \n",
    "|----------------      |  ----------------       |  ----------------      |  ----------------\n",
    "|GameteCompetition_output_file  |GameteCompetition_Output_File.txt | User defined output file name |   Creates a lod score table output file \n",
    "|repetitions\n",
    "|xlinked_analysis  |  FALSE  |  TRUE, FALSE  |  Whether or not markers are on the X chromosome"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Data Files\n",
    "Gamete Competition requires a [Control file](https://openmendel.github.io/MendelBase.jl/#control-file), and a [Pedigree file](https://openmendel.github.io/MendelBase.jl/#pedigree-file). Genotype data can be included in the Pedigree file, in which case a [Locus file](https://openmendel.github.io/MendelBase.jl/#locus-file) is required. Alternatively, genotype data can be provided in a [SNP data file](https://openmendel.github.io/MendelBase.jl/#snp-data-file), in which case a [SNP Definition File](https://openmendel.github.io/MendelBase.jl/#snp-definition-file) is required. Details on the format and contents of the Control and data files can be found on the [MendelBase](https://openmendel.github.io/MendelBase.jl) documentation page. There are example data files in the Gamete Competition [data](https://github.com/OpenMendel/MendelGameteCompetition.jl/tree/master/data) folder."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Running the Analysis\n",
    "To run this analysis package, first launch Julia. Then load the package with the command:\n",
    "\n",
    "`julia> using GameteCompetition`\n",
    "\n",
    "Next, if necessary, change to the directory containing your files, for example,\n",
    "\n",
    "`julia> cd(\"~/path/to/data/files/\")`\n",
    "\n",
    "Finally, to run the analysis using the parameters in your Control file, for example, Control_file.txt, use the command:\n",
    "\n",
    "`julia> GameteCompetition(\"Control_file.txt\")`\n",
    "\n",
    "*Note: The package is called* MendelGameteCompetition *but the analysis function is called simply* GameteCompetition."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Output Files\n",
    "Each option will create output files specific to that option, and will save them to the same directory that holds the input data files."
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# Example 1: "
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 0: Load the OpenMendel package and then go to the directory containing the data files:\n",
    "First we load the MendelEstimateFrequencies package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "using MendelGameteCompetition"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "In this example we go to the directory containing the example data files that come with this package."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "cd(MendelGameteCompetition.datadir())\n",
    "pwd()"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 1: Preparing the Pedigree files:\n",
    "Recall the structure of a [valid pedigree structure](https://openmendel.github.io/MendelBase.jl/#pedigree-file). Note that we require a header line. Let's examine the first few lines of such an example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {
    "scrolled": true
   },
   "outputs": [],
   "source": [
    ";head -10 \"gamete competition PedigreeFrame.txt\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 2: Preparing the Control file\n",
    "A Control file gives specific instructions to `MendelGameteCompetition`. A minimal Control file looks like the following:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    ";cat \"gamete competition Control.txt\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 3: Run the analysis in Julia REPL or directly in notebook\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    "GameteCompetition(\"gamete competition Control.txt\")"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 4: Output File\n",
    "`GameteCompetition` should have generated two output files in your local directory: `gamete competition Output.txt` and `gamete competition Output Table.txt`. The output file has detailed information on the analysis, and the output table creates a data frame with the results of the analysis that can be used in other analyses (see below)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    ";cat \"gamete competition Output Table.txt\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "### Step 5: Interpreting the result\n",
    "In the example above, for each marker, the allele with the smallest transmission, its corresponding *τ*, the allele with the largest transmission, and its corresponding *τ* are provided along with the p-value for the test of association of the marker with the trait. In the example provided, the CT Marker is the most associated with the trait because it has the smallest p-value.  The most frequent allele is the 1 allele so it is assigned *τ1* = 1.  The 2 allele is ~8.51 times more likely to be transmitted from a 1/2 parent than the 1 allele.  Details of the analysis are provided in the output text file. In this file, the iterations of the numeric loglikelihood maximization, the maximum likelihood estimates at the maximum log likelihood, their standard errors and their correlations are provided for each marker (see below)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "metadata": {},
   "outputs": [],
   "source": [
    ";cat \"gamete competition Output.txt\""
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Citation\n",
    "\n",
    "If you use this analysis package in your research, please cite the following reference in the resulting publications:\n",
    "\n",
    "*Lange K, Papp JC, Sinsheimer JS, Sripracha R, Zhou H, Sobel EM (2013) Mendel: The Swiss army knife of genetic analysis programs. Bioinformatics 29:1568-1570.*"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Acknowledgments\n",
    "\n",
    "This project is supported by the National Institutes of Health under NIGMS awards R01GM053275 and R25GM103774 and NHGRI award R01HG006139."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Julia 1.1.0",
   "language": "julia",
   "name": "julia-1.1"
  },
  "language_info": {
   "file_extension": ".jl",
   "mimetype": "application/julia",
   "name": "julia",
   "version": "1.1.0"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}