Skip to content

Commit 7619ccb

Browse files
sarah-jisarah-ji
authored
Merge pull request #1 from OpenMendel/master
updating my openmendel tutorials repository
2 parents 4b812d8 + 2af3fec commit 7619ccb

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

54 files changed

+337925
-575258
lines changed

‎AimSelection.ipynb

+330
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,330 @@
1+
{
2+
"cells": [
3+
{
4+
"cell_type": "markdown",
5+
"metadata": {},
6+
"source": [
7+
"# Tutorial of MendelAimSelection"
8+
]
9+
},
10+
{
11+
"cell_type": "markdown",
12+
"metadata": {},
13+
"source": [
14+
"## Julia version\n",
15+
"\n",
16+
"Current code supports Julia version 1.0+ "
17+
]
18+
},
19+
{
20+
"cell_type": "markdown",
21+
"metadata": {},
22+
"source": [
23+
"\n",
24+
"## When to use MendelAimSelection\n",
25+
"\n",
26+
"This [Julia](http://julialang.org/) package selects the SNPs that are most informative at predicting ancestry for your data — the best Ancestry Informative Markers (AIMs). \n",
27+
"\n",
28+
"MendelAimSelection is one component of the umbrella [OpenMendel](https://openmendel.github.io) project."
29+
]
30+
},
31+
{
32+
"cell_type": "markdown",
33+
"metadata": {},
34+
"source": [
35+
"## Background\n",
36+
"Modern genetic studies often include people of many ethnicities or of mixed ethnicity. The potential for confounding ethnicity with disease risk is well known. MendelAimSelection uses an extension of an algorithm described by [Rosenberg et al.](https://www.ncbi.nlm.nih.gov/pubmed/14631557) to quickly find the N most informative AIMs within the data set.\n",
37+
"\n",
38+
"*Rosenberg NA, Li LM, Ward R, Pritchard JK (2003) Informativeness of genetic markers\n",
39+
"for inference of ancestry. Amer J Hum Genet 73:1402–1422.*"
40+
]
41+
},
42+
{
43+
"cell_type": "markdown",
44+
"metadata": {},
45+
"source": [
46+
"## Installation\n",
47+
"\n",
48+
"*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",
49+
"\n",
50+
"If you have not already installed the MendelAimSelection, then within Julia, use the package manager to install MendelAimSelection:"
51+
]
52+
},
53+
{
54+
"cell_type": "code",
55+
"execution_count": null,
56+
"metadata": {},
57+
"outputs": [],
58+
"source": [
59+
"] add https://github.com/OpenMendel/MendelAimSelection.jl.git"
60+
]
61+
},
62+
{
63+
"cell_type": "markdown",
64+
"metadata": {},
65+
"source": [
66+
"or once the OpenMendel packages are registered simply use:\n",
67+
"\n",
68+
"`pkg> add MendelAimSelection`\n",
69+
"\n",
70+
"This package supports Julia v1.0+"
71+
]
72+
},
73+
{
74+
"cell_type": "markdown",
75+
"metadata": {},
76+
"source": [
77+
"## Input Files\n",
78+
"The MendelAimSelection analysis package accepts the following input files. Example input files can be found in the [data](https://github.com/OpenMendel/MendelAimSelection.jl/tree/master/data) subfolder of the MendelAimSelection project. An analysis won't always need every file type below. The input for all examples in this tutorial were obtained from the 1000 genome project.\n",
79+
"\n",
80+
"* [Control File](https://openmendel.github.io/MendelAimSelection.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",
81+
"* [Locus File](https://openmendel.github.io/MendelBase.jl/#locus-file): Names and describes the genetic loci in your data.\n",
82+
"* [Pedigree File](https://openmendel.github.io/MendelBase.jl/#pedigree-file): Gives information about your individuals, such as name, sex, family structure, and ancestry.\n",
83+
"* [Phenotype File](https://openmendel.github.io/MendelBase.jl/#phenotype-file): Lists the available phenotypes.\n",
84+
"* [SNP Definition File](https://openmendel.github.io/MendelBase.jl/#snp-definition-file): Defines your SNPs with information such as SNP name, chromosome, position, allele names, allele frequencies.\n",
85+
"* [SNP Data File](https://openmendel.github.io/MendelBase.jl/#snp-data-file): Holds the genotypes for your data set. Must be a standard binary PLINK BED file in SNP major format. If you have a SNP data file you must have a SNP definition file."
86+
]
87+
},
88+
{
89+
"cell_type": "markdown",
90+
"metadata": {},
91+
"source": [
92+
"## Control file\n",
93+
"The Control file is a text file consisting of keywords and their assigned values. The format of the Control file is:\n",
94+
"\n",
95+
"\tKeyword = Keyword_Value(s)\n",
96+
"\n",
97+
"Below is an example of a simple Control file to run AIM Selection:\n",
98+
"\n",
99+
"\t#\n",
100+
"\t# Input and Output files.\n",
101+
"\t#\n",
102+
"\tfield_separator = ' '\n",
103+
"\tpedigree_file = 1000genomes_chr1_eas.ped\n",
104+
"\t\n",
105+
"\tplink_field_separator = '\t'\n",
106+
"\tplink_input_basename = 1000genomes_chr1_eas\n",
107+
"\t\n",
108+
"\toutput_field_separator = ','\n",
109+
"\toutput_file = 1000genomes_chr1_eas Output.txt\n",
110+
"\t#\n",
111+
"\t# Analysis parameters for AIM Selection option.\n",
112+
"\t#\n",
113+
" \n",
114+
"In the example above, the four keywords specify the input and output files: *1000genomes_chr1_eas.bed*, *1000genomes_chr1_eas.snp*, *1000genomes_chr1_eas.ped* and *1000genomes_chr1_eas Output.txt*. The text after the '=' are the keyword values. The names of keywords are *not* case sensitive. (The keyword values *may* be case sensitive.) A list of OpenMendel keywords common to most analysis package can be found [here](https://openmendel.github.io/MendelBase.jl/#keywords-table)."
115+
]
116+
},
117+
{
118+
"cell_type": "markdown",
119+
"metadata": {},
120+
"source": [
121+
"## Data Files\n",
122+
"AIM Selection 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. Mendel AIM Selection will also accept [PLINK format](http://zzz.bwh.harvard.edu/plink) FAM and BIM files. 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 AIM Selection [data](https://github.com/OpenMendel/MendelAIMSelection.jl/tree/master/data) folder."
123+
]
124+
},
125+
{
126+
"cell_type": "markdown",
127+
"metadata": {},
128+
"source": [
129+
"## Using PLINK compressed file as input\n",
130+
"\n",
131+
"MendelAimSelection accepts [PLINK binary format](https://www.cog-genomics.org/plink2/formats#bed) as input, in which case the triplets (`data.bim`, `data.bed`, `data.fam`) must all be present. In this tutorial, there are no examples that use PLINK binary format to import pedigree and SNP information. But if available, one can import the data by specifying the following in the control file:\n",
132+
"\n",
133+
"`plink_input_basename = data` \n",
134+
"\n",
135+
"However, sometimes the PLINK .fam file contains non-unique person ids (2nd column of .fam file) across different pedigrees, which is currently **not** permitted in OpenMendel. A person's id cannot be repeated in other pedigrees, even if it is contextually clear that they are different persons. This will be fixed in the near future."
136+
]
137+
},
138+
{
139+
"cell_type": "markdown",
140+
"metadata": {},
141+
"source": [
142+
"## Running the Analysis\n",
143+
"\n",
144+
"To run this analysis package, first launch Julia. Then load the package with the command:\n",
145+
"\n",
146+
"`julia> using MendelAimSelection`\n",
147+
"\n",
148+
"Next, if necessary, change to the directory containing your files, for example,\n",
149+
"\n",
150+
"`julia> cd(\"~/path/to/data/files/\")`\n",
151+
"\n",
152+
"Finally, to run the analysis using the parameters in your Control file, for example, Control_file.txt, use the command:\n",
153+
"\n",
154+
"`julia> AimSelection(\"Control_file.txt\")`\n",
155+
"\n",
156+
"*Note: The package is called* MendelAimSelection *but the analysis function is called simply* AimSelection."
157+
]
158+
},
159+
{
160+
"cell_type": "markdown",
161+
"metadata": {},
162+
"source": [
163+
"## Output Files\n",
164+
"Each option will create output files specific to that option, and will save them to the same directory that holds the input data files."
165+
]
166+
},
167+
{
168+
"cell_type": "markdown",
169+
"metadata": {},
170+
"source": [
171+
"# Example 1: "
172+
]
173+
},
174+
{
175+
"cell_type": "markdown",
176+
"metadata": {},
177+
"source": [
178+
"### Step 0: Load the OpenMendel package and then go to the directory containing the data files:\n",
179+
"First we load the MendelEstimateFrequencies package."
180+
]
181+
},
182+
{
183+
"cell_type": "code",
184+
"execution_count": null,
185+
"metadata": {},
186+
"outputs": [],
187+
"source": [
188+
"using MendelAimSelection"
189+
]
190+
},
191+
{
192+
"cell_type": "markdown",
193+
"metadata": {},
194+
"source": [
195+
"In this example we go to the directory containing the example data files that come with this package."
196+
]
197+
},
198+
{
199+
"cell_type": "code",
200+
"execution_count": null,
201+
"metadata": {},
202+
"outputs": [],
203+
"source": [
204+
"cd(MendelAimSelection.datadir())\n",
205+
"pwd()"
206+
]
207+
},
208+
{
209+
"cell_type": "markdown",
210+
"metadata": {},
211+
"source": [
212+
"### Step 1: Preparing the pedigree files:\n",
213+
"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:"
214+
]
215+
},
216+
{
217+
"cell_type": "code",
218+
"execution_count": null,
219+
"metadata": {
220+
"scrolled": true
221+
},
222+
"outputs": [],
223+
"source": [
224+
";head -10 \"1000genomes_chr1_eas.ped\""
225+
]
226+
},
227+
{
228+
"cell_type": "markdown",
229+
"metadata": {},
230+
"source": [
231+
"In this example we have unrelated individuals who were genotyped as part of the [1000 Genomes Project](http://www.internationalgenome.org/about). They come from 5 different ethnic groups, Southern Han Chinese (CHS),Chinese Dai in Xishuangbanna, China (CDX), Kinh in Ho Chi Minh City, Vietnam (KHV), Han Chinese in Beijing, China (CHB) and Japanese in Tokyo, Japan (JPT). We want to find SNPs that differ in their allele frequencies among two or more of these groups."
232+
]
233+
},
234+
{
235+
"cell_type": "markdown",
236+
"metadata": {},
237+
"source": [
238+
"### Step 2: Preparing the control file\n",
239+
"A control file gives specific instructions to `MendelAimSelection`. To select the SNPs that are most informative at predicting ancestry for your data — the best Ancestry Informative Markers, a minimal control file looks like the following (in this example the data come from chromosome 1):"
240+
]
241+
},
242+
{
243+
"cell_type": "code",
244+
"execution_count": null,
245+
"metadata": {},
246+
"outputs": [],
247+
"source": [
248+
";cat \"AIM 1000genomes_chr1 Control.txt\""
249+
]
250+
},
251+
{
252+
"cell_type": "markdown",
253+
"metadata": {},
254+
"source": [
255+
"### Step 3: Run the analysis in Julia REPL or directly in notebook\n"
256+
]
257+
},
258+
{
259+
"cell_type": "code",
260+
"execution_count": null,
261+
"metadata": {},
262+
"outputs": [],
263+
"source": [
264+
"AimSelection(\"AIM 1000genomes_chr1 Control.txt\")"
265+
]
266+
},
267+
{
268+
"cell_type": "markdown",
269+
"metadata": {},
270+
"source": [
271+
"### Step 4: Output File\n",
272+
"\n",
273+
"`MendelAimSelection` should have generated the file `1000genomes_chr1_eas Output.txt` in your local directory. This file lists your markers, and gives an AIMRank for each marker (see below)."
274+
]
275+
},
276+
{
277+
"cell_type": "code",
278+
"execution_count": null,
279+
"metadata": {},
280+
"outputs": [],
281+
"source": [
282+
";cat \"1000genomes_chr1_eas Output.txt\""
283+
]
284+
},
285+
{
286+
"cell_type": "markdown",
287+
"metadata": {},
288+
"source": [
289+
"### Step 5: Interpreting the result\n",
290+
"\n",
291+
"`MendelAimSelection` uses the genotypes and ethnicities in your pedigree to assign a score - the *AIMRank* - to each marker. The higher the AIMRank, the better the marker at differentiating two or more of the ethnic groups. Note that the rankings may change if the ethnic groups in your pedigree change."
292+
]
293+
},
294+
{
295+
"cell_type": "markdown",
296+
"metadata": {},
297+
"source": [
298+
"## Citation\n",
299+
"\n",
300+
"If you use this analysis package in your research, please cite the following reference in the resulting publications:\n",
301+
"\n",
302+
"*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.*"
303+
]
304+
},
305+
{
306+
"cell_type": "markdown",
307+
"metadata": {},
308+
"source": [
309+
"## Acknowledgments\n",
310+
"\n",
311+
"This project is supported by the National Institutes of Health under NIGMS awards R01GM053275 and R25GM103774 and NHGRI award R01HG006139."
312+
]
313+
}
314+
],
315+
"metadata": {
316+
"kernelspec": {
317+
"display_name": "Julia 1.1.0",
318+
"language": "julia",
319+
"name": "julia-1.1"
320+
},
321+
"language_info": {
322+
"file_extension": ".jl",
323+
"mimetype": "application/julia",
324+
"name": "julia",
325+
"version": "1.1.0"
326+
}
327+
},
328+
"nbformat": 4,
329+
"nbformat_minor": 2
330+
}

0 commit comments

Comments
 (0)