# ---
# jupyter:
#   jupytext:
#     text_representation:
#       extension: .jl
#       format_name: light
#       format_version: '1.5'
#       jupytext_version: 1.14.4
#   kernelspec:
#     display_name: Julia 1.1.0
#     language: julia
#     name: julia-1.1
# ---
# # Tutorial of MendelGeneDropping
# ## Julia version
# Current code supports Julia version 1.0+ 
# ## Overview
# MendelGeneDropping is a component of the umbrella [OpenMendel](https://openmendel.github.io) project. This analysis option "drops" genes into a pedigree through the founders and propagates them through the pedigrees. In many circumstances, it is useful to simulate genetic data consistent with a postulated map. For example, you might want to generate p-values empirically or to estimate the power of a collection of pedigrees to detect linkage. Gene dropping randomly fills in genotypes subject to prescribed allele frequencies, a given genetic map, and Hardy-Weinberg and linkage equilibrium. After performing gene dropping the package generates a new Pedigree file for further analysis. The missing data pattern in the new pedigrees can mimic the input pedigrees, or the user can specify a new pattern.
# ## When to use MendelGeneDropping
# The raw material for gene dropping consists of sets of pedigrees and loci. People within the pedigrees must be assigned either blank phenotypes or Mendelian consistent phenotypes. Gene dropping is carried out independently of observed phenotypes at those loci common to the definition and map files. By varying the content of the map file, you can choose exactly which loci to subject to gene dropping. Phenotypes at the remaining loci of the definition file are left untouched. Simulated genotypes rather than simulated phenotypes are reported. There are no limits on the complexity of the pedigrees or the number of loci. You can use founders from different populations, provided these populations are defined. Each founder should be assigned to a population; any unassigned founders are assumed to come from the first population.
# ## Installation
#
# *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.*
#
# If you have not already installed the MendelGeneDropping, then within Julia, use the package manager to install MendelGeneDropping:
] add https://github.com/OpenMendel/MendelGeneDropping.jl.git
# or once the OpenMendel packages are registered simply use:
#
# `pkg> add MendelGeneDropping`
#
# This package supports Julia v1.0+
# ## Input Files
# The MendelGeneDropping analysis package accepts the following input files. Example input files can be found in the [data](https://github.com/OpenMendel/MendelGeneDropping.jl/tree/master/data) subfolder of the MendelGeneDropping project. (An analysis won't always need every file type below.)
#
# * [Control File](https://openmendel.github.io/MendelGeneDropping.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.
# * [Locus File](https://openmendel.github.io/MendelBase.jl/#locus-file): Names and describes the genetic loci in your data.
# * [Pedigree File](https://openmendel.github.io/MendelBase.jl/#pedigree-file): Gives information about your individuals, such as name, sex, family structure, and ancestry.
# * [Phenotype File](https://openmendel.github.io/MendelBase.jl/#phenotype-file): Lists the available phenotypes.
# ### Control file
# The Control file is a text file consisting of keywords and their assigned values. The format of the Control file is:
#
# 	Keyword = Keyword_Value(s)
#
# Below is an example of a simple Control file to run Gene Dropping:
#
# 	#
# 	# Input and Output files.
# 	#
# 	locus_file = genedropping LocusFrame.txt
# 	pedigree_file = genedropping PedigreeFrame.txt
# 	phenotype_file = genedropping PhenotypeFrame.txt
# 	new_pedigree_file = genedropping NewPedigreeFrame.txt
# 	output_file = genedropping Output.txt
# 	#
# 	# Analysis parameters for GeneDropping option.
# 	#
# 	repetitions = 2
# 	populations = European, African, Chinese
#
# In the example above, there are seven keywords. Three keywords specify the input files: *genedropping LocusFrame.txt*, *genedropping PedigreeFrame.txt*, and *genedropping PhenotypeFrame.txt*. Two keywords specify the output files: *genedropping Output.txt* is the results file and *genedropping NewPedigreeFrame.txt* is the new pedigree OpenMendel generates, with the added simulated genotypes. The last two keywords specify analysis parameters: *repetitions* (2), and *populations* (European, African, and Chinese). The text after the '=' are the keyword values.
# ## Keywords<a id="keywords-table"></a>
# This is a list of OpenMendel keywords specific to Gene Dropping. 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.)
#
# Keyword          |   Default Value    | Allowed Values |  Short Description       
# ----------------      |  ----------------       |  ----------------      |  ----------------
# gene_drop_output  | Unordered | Unordered, Ordered, Sourced, or Population |   Output format style for gene drop pedigrees 
# interleaved          | FALSE |  TRUE, FALSE  |  Whether or not genes are dropped into pedigrees sequentially or interleaved
# keep_founder_genotypes           | TRUE  |  TRUE, FALSE  |  Whether or not founder genotypes are retained
# missing_rate   | 0.0 |   Real     |       
# repetitions    |   1   |   integer     |       Repetitions for sharing statistics
# ## Data Files
# Gene Dropping 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. 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 Gene Dropping [data](https://github.com/OpenMendel/MendelGeneDropping.jl/tree/master/data) folder.
# ## Running the Analysis
# To run this analysis package, first launch Julia. Then load the package with the command:
#
# `julia> using MendelGeneDropping`
#
# Next, if necessary, change to the directory containing your files, for example,
#
# `julia> cd("~/path/to/data/files/")`
#
# Finally, to run the analysis using the parameters in your Control file, for example, Control_file.txt, use the command:
#
# `julia> GeneDropping("Control_file.txt")`
#
# *Note: The package is called* MendelGeneDropping *but the analysis function is called simply* GeneDropping.
# ## Output Files
# Each option will create output files specific to that option, and will save them to the same directory that holds the input data files. Running MendelGeneDropping will create a new pedigree file according to the parameters specified in your Control file.
# # Example 1: 
# ### Step 0: Load the OpenMendel package and then go to the directory containing the data files:
# First we load the MendelGeneDropping package.
using MendelGeneDropping
# In this example we go to the directory containing the example data files that come with this package.
cd(MendelGeneDropping.datadir())
pwd()
# ### Step 1: Preparing the Pedigree files:
# 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:
;head -10 "genedropping PedigreeFrame.txt"
# ### Step 2: Preparing the Control file
# A Control file gives specific instructions to `MendelGeneDropping`. A minimal Control file looks like the following:
;cat "genedropping Control.txt"
# ### Step 3: Run the analysis in Julia REPL or directly in notebook
#
GeneDropping("genedropping Control.txt")
# ### Step 4: Output File
# `MendelGeneDropping` should have generated two output files in your local directory: `genedropping Output.txt` and `genedropping Output PedigreeFrame.txt` Currently the file `genedropping Output.txt` has no content. The file `genedropping Output PedigreeFrame.txt` has the new pedigree created by the GeneDropping option (see below).
;cat "genedropping Output PedigreeFrame.txt"
# ### Step 5: Interpreting the result
#
# ## Citation
#
# If you use this analysis package in your research, please cite the following reference in the resulting publications:
#
# *<NAME>, <NAME>, <NAME>, <NAME>, <NAME>, <NAME> (2013) Mendel: The Swiss army knife of genetic analysis programs. Bioinformatics 29:1568-1570.*
# ## Acknowledgments
#
# This project is supported by the National Institutes of Health under NIGMS awards R01GM053275 and R25GM103774 and NHGRI award R01HG006139.