GTOOL

Platform	File
Linux (x86_64) Static Executable	gtool_v0.7.5_x86_64.tgz
Linux (x86_64) Dynamic Executable	gtool_v0.7.5_x86_64_dynamic.tgz
Mac OS X 10.6 (Intel)	gtool_v0.7.5_MacOSX_10.7_Intel.tgz

Please fill out the registration form to receive emails about updates to this software

To unpack the files use a command such as

tar zxvf gtool_vX.X.X_x86_64.tgz

This will create an executable called gtool and a directory /example that contains the following example data files

example.gen	A genotype file (containing data for 11 SNPs and 5 samples).
example.sample	A sample file.
rs_id.txt	A file containing a list of rs_ids.
sample_id.txt	A file containing a list of sample_ids.
exclusion.txt	A file containing a list of rs_ids.
sample_excl.txt	A file containing a list of sample_ids.
example.ped	An example PED file.
example.map	An example MAP file.
example10,11,12.gen	Example genotype files for merging.
example10,11,12.sample	Example sample files for merging.

You will also find the LICENCE file, which describes the conditions of use of this software.

Parameters	Type	Description
-S		Subset mode
--g	File	Input genotype file
--s	File	Input sample file
--og	File	Output genotype file. Default, append .subset to genotype file name
--os	File	Output sample file. Default, append .subset to sample file name
--sample_id	File	Define a subset of genotypes from a list of sample_ids
--start	Integer	Define a subset of SNPs by position (in basepairs) in the range start ≤ position ≤ end
--end	Integer	Define a subset of SNPs by position (in basepairs) in the range start ≤ position ≤ end
--inclusion	File	Define a subset of SNPs to include. The --inclusion file should be a single column file with a SNP ID on each line
--exclusion	File	Define a subset of SNPs to exclude. The --exclusion file should be a single column file with a SNP ID on each line
--missing	Double	Define a missingness threshold over which to exclude SNPs
--threshold	Double	Define a threshold for calling genotypes for calculating missing data
-P		PED to GEN Conversion mode
--ped	File	PED format genotype file
--map	File	MAP SNP file which accompanies the --ped file
--og	File	Output genotype file. Default, append .gen to PED file name
--os	File	Output sample file. Default, append .sample to PED file name
--binary_phenotype	Flag	If set, the phenotype in the output sample file is 'B'
--family	Flag	If set, use the family id from the PED file as ID_1 in the SAMPLE file
--snptest1	Flag	If set, output the SAMPLE file in SNPTEST1 format
--num_snps	Integer	Number of SNPs in PED file
--num_samples	Integer	Number of samples in PED file
-G		GEN to PED Conversion mode
--g	File	Input genotype file
--s	File	Input sample file
--ped	File	Output PED file. Default, append.ped to genotype file name
--map	File	Output MAP file. Default, append .map to genotype file name
--phenotype	String	Name of the phenotype column in the SAMPLE file to output to PED. Default -9 (Unknown)
--sex	String	Name of the sex column in the SAMPLE file to output to PED. If unspecified will look for a column named "sex" or "gender". Default -9 (Unknown)
--threshold	Double	Threshold for merging genotypes from GEN probability. Default 0.9
--num_snps	Integer	Number of SNPs in GEN file
--num_samples	Integer	Number of samples in GEN file
--chr	String	Chromomsome for first column of MAP file
--snp	Flag
-M		Merge mode
--g	File	List of input genotype files
--s	File	List of input sample files
--og	File	Output genotype file. Default format File1_File2_...FileN.gen
--os	File	Output sample file. Default File1_File2_...FileN.sample
--threshold	Double	Threshold for calling genotypes from GEN probability. Default >1 (strictcomparison).
-O		Orient mode
--g	File	List of input genotype files
--strand	File	List of SNP positions and orientations (+,-)
--og	File	Output genotype file
--excl	Flag	If set, then SNPs with no entry in the strand file will be excluded from the output.
--order	Flag	If set,alleles/probabilities will be output in alphabetical order A,C,G,T. If not set, alleles will be output in same order as in GEN file
--log	File	Name of log file. Use with -S,-P,-G,-M. Default gtool.log

GTOOL can be used to create subsets of datasets using the -S option in conjunction with several sub-options. These options are illustrated in the following examples. In these examples the genotype and sample files to be subsetted are specified using the --g and --s options. The genotype and sample files should be in the format specified by the FILE FORMAT webpage.

The output files can specified using the --og and --os options.

Selecting a subset of individuals specified by a list (--sample_id)

The --sample_id file should be a list of sample_ids, one per line.

gtool -S --g example/example.gen --s example/example.sample --og example/out.gen --os example/out.sample --sample_id example/sample_id.txt

Excluding a subset of individuals (--sample_excl)

The --sample_excl file should be a list of sample_ids, one per line.

gtool -S --g example/example.gen --s example/example.sample --og example/out.gen --os example/out.sample --sample_excl example/sample_excl.txt

Selecting a subset of SNPs specified by a list (--inclusion)

The --inclusion file should be a single column file with a SNP ID on each line.

gtool -S --g example/example.gen --s example/example.sample --og example/out.gen --os example/out.sample --inclusion example/rs_id.txt

Excluding subsets of SNPs (--exclusion)

The --exclusion file should be a single column file with a SNP ID on each line.

gtool -S --g example/example.gen --s example/example.sample --og example/out.gen --os example/out.sample --exclusion example/exclusion.txt

Selecting a subset of SNPs based on their base-pair position (--start, --end)

SNP subsets can be generated by position using the --start and --end flags. All SNPs in that range are included in the output. If --start is defined but not --end, --endis set as the last SNP in the data set. If --end is defined but not --start, --startis set as 0.

gtool -S --g example/example.gen --s example/example.sample --og example/out.gen --os example/out.sample --start 10015000 --end 10075000

Selecting a subset of SNPs using a missingness filter (--missing, --threshold)

SNP subsets can be generated by applying a missingness filter using the --missing and --threshold flags. A locus will be considered missing if the maximum of the three probabilities which make up the genotype is less than --threshold. For a given SNP if num_missing_loci / num_individuals > --missing then the SNP is excluded.

gtool -S --g example/example.gen --s example/example.sample --missing 0.05 --threshold 0.9

NOTE : The options described above can be used together to create subsets of SNPs and samples at the same time. The priority for SNP subsets from highest to lowest is: Inclusion > Exclusion > Position i.e. if a snp is selected by position but is on the exclusion list, then it is not output. If it is also on the inclusion list then it is output regardless.

GTOOL can be used to convert datasets stored in PED files into the FILE FORMAT used by SNPTEST and IMPUTE.

• PED and associated MAP files are specified using the --ped and --map options


• PED files usually use a genotype coding scheme of A,C,G,T,N or 1,2,3,4,0. GTOOL can use either.


• GTOOL assumes that the PED file contains has the following first 6 columns : Family ID, Individual ID, Paternal ID, Maternal ID, Sex (1=male; 2=female; other=unknown), Phenotype. The IDs are alphanumeric: the combination of family and individual ID should uniquely identify a person. A PED file must have 1 and only 1 phenotype in the sixth column. The phenotype can be either a quantitative trait or an affection status column.


• The usual MAP file format is:
  
  

  chromosome

  SNP_id

  genetic_distance

  position

  
  GTOOL will place the chromosome number in the first column of the GEN file. The genetic_distance values are not used.


• If you have allelic type information for the SNPs you can add it as extra columns in the MAP file e.g.
  
  

  chromosome	SNP_id	genetic_distance	position	allele1	allele2
  22	rs1234	0.001	1000000	A	G

  
  Otherwise, it will be inferred from the data and the output convention in the genotype file will be alphabetic order for the alleles.


• The names of the genotype and sample files to be created are specified using the --og and --os options.


• The --binary_phenotype flag is used to set the phenotype to 'B' rather than the default 'P'.


• The --family flag is used to create a unique ID_1 (and identical ID_2) from the Family ID and Individual ID in the PED file, 'Family ID'_'Individual ID'.


• The --snptest1 flag tells GTOOL to output using the SNPTEST v1 sample file format.

An example of using GTOOL to convert a PED/MAP pair.

gtool -P --ped example/example.ped --map example/example.map --og example/out.gen --os example/out.sample

An example of using GTOOL to convert a PED/MAP pair, using the default values for --og and --os, and the --binary_phenotype flag, is given below.

gtool -P --ped example/example.ped --map example/example.map --binary_phenotype 1

An example of using --family to preserve the family_id in the SAMPLE file.

gtool -P --ped example/example.ped --map example/example.map --family

GTOOL can be used to convert datasets stored in GEN file format into PED files.

In the GEN format each SNP is represented as a set of three probabilities which correspond to the allele pairs AA,AB,BB. If the largest of the probabilities is over the threshold specified by --threshold, then the genotype in the PED file is expressed as the corresponding allele pair. The genotypes are expressed as pairs of 1,2,0 where 1 corresponds to alleleA from the GEN file and 2 corresponds to alleleB. If none of the probabilities are over the calling threshold then the pair is unknown, 0 0. This should allow the conversion of indels and other biallelic structural variants from the 1000 Genomes. If the data is entirely comprised single nucleotide polymorphisms then the --snp flag can be set and the genotypes are expressed as pairs of A,C,G,T and unknowns are represented as N N.

You can use any one of the phenotypes in the SAMPLE file as the phenotype in the PED file. The name of the phenotype is specified with --phenotype. This should correspond to a field on the first line of the SAMPLE file. If the phenotype does not exist or you don't wish to set a phenotype, the phenotype is given a value of -9 in the PED file. The name of the sex column in the SAMPLE file is specified using the --sex option. If unspecified will look for a column named "sex" or "gender". If no column is found then the sex column in the PED file will be set to -9.

An example of using GTOOL to convert a GEN and sample file pair is given below.

gtool -G --g example/example.gen --s example/example.sample --ped example/out.ped --map example/out.map --phenotype phenotype_1 --threshold 0.9

If --chr is defined then the first column of the output MAP file will have this value for all loci in the file. Alternatively, if the first column of the GEN file contains the chromosome number of each SNP in the file, of the form 1-24,X,Y,M, then these numbers are placed in the chromosome column of the generated MAP file. Otherwise, the column in filled with zeros. The following example illustrates this.

gtool -G --g example/example_chr.gen --s example/example.sample --ped example/out.ped --map example/out.map --phenotype phenotype_1 --threshold 0.9

An example of using GTOOL to convert a GEN and sample file pair, using the default values for --ped,--map,--phenotype,--sex and --threshold, is given below.

gtool -G --g example/example.gen --s example/example.sample

GTOOL can be used to merge two or more datasets stored in GEN file format.

SNPs in the output GEN file are ordered by position. Samples are output in the order that they are read in. Missing data is represented as 0 0 0. If a SNP is not in a dataset, then it is represented as missing in those samples which are uniquely in the dataset.

If a given locus (SNP + Sample) occurs in more than one file, when merging, there are four possible outcomes:

• Identical e.g. FileA 0 0 1 FileB 0 0 1. In this case the output is 0 0 1.
• Different. e.g. FileA 0 0 1 FileB 1 0 0. In this case the output would be set as 0 0 0.
• Similar e.g. FileA 0 0 1 FileB 0.03 0 0.97. In this case apply the threshold (--threshold). Say we set the threshold as 0.9, then the output would be 0 0 1.
• Different, but in one of the data sets there is missing data e.g. FileA 0 0 0 FileB 0 0 1. In this case the output would be 0 0 1.

If a SNP occurs in more than one file but the allele type information (alleleA and alleleB,columns 4 and 5 in the GEN file) is different then there are four possible outcomes:

• Reverse e.g. FileA C T FileB T C. In this case the probabilities in FileB are reversed, so 0 0 1 → 1 0 0 and vice versa.
• Reverse-Complement e.g. FileA C T FileB A G. In this case the probabilities in FileB are reversed.
• Complement e.g. FileA C T FileB G A. In this case the probabilities in FileB are unchanged.
• Different e.g. FileA C T FileB G T. In this case the SNP is removed from the output.

GTOOL is unable to determine the relative strand of AT,CG SNPs, which may lead to some SNPs of this type having missing data. A solution for this is being developed.

The sample information for the genotypes including phenotype and covariate information are also merged. If a sample occurs in two datasets, if there are different phenotype and covariate information in each file, the union of the sets of information are output to the Sample (--os) file. If a sample occurs in two datasets but has different values for the same fields, it is set to -9 in the output.

An example of using GTOOL to merge two files is given below.

gtool -M --g example/example10.gen example/example11.gen --s example/example10.sample example/example11.sample --log example/example10_example11.log

A further example,

./gtool -M --g example/example11.gen example/example12.gen --s example/example11.sample example/example12.sample --threshold 0.9 --log example/example11_example12.log

GTOOL can be used to orient the SNPs in a GEN file using a strand file.

The format of a strand file is:

position

orientation

Orientation can be + or -. For GTOOL, - means complement alleleA and alleleB in the GEN file. If the order_alleles flag is set, then the alleles and probabilities of all SNPs are flipped where necessary so that alleleA and alleleB are in alphabetical order. In a real scenario, the orientation is typically defined relative to the '+' strand of the reference sequence.

If a SNP from the GEN file is not present in the strand file, then it is either excluded from the output (default), or it is assumed to be + and the output is the same as the input (--noexcl).

An example of using GTOOL to orient a GEN file is given below.

gtool -O --g example/example.gen --strand example/example.strand --og example/example_orient.gen --log example/example_orient.log

0.7.5 - 05-04-2012 - In GEN to PED, genotypes are output as 1,2,0 by default rather than A,C,G,T to support indels from 1000G. GEN to PED now outputs the genotype pair for the max probability that is over than the calling threshold. Appropriate errors are displayed when input files are missing. In PED to GEN the sex/gender column in the output sample file is labelled sex with type 'D'. 0.7.0 - 15-08-2011 - Fixed high memory bug GEN to PED and PED to GEN, can use >2Gb memory. In GEN to PED mode, put GEN ID2 in Family_ID column of PED. Added optional parameters to tell GTOOL the number of SNPs and samples in a data set in GEN to PED and PED to GEN modes.
0.6.7 - 25-03-2011 - Missingness is now a proportion rather than a count in PED to GEN and Merge. Addition of the --binary_phenotype flag in PED to GEN. Remove the --discrete_phenotype flag.
0.6.6 - 25-08-2010 - Fix to GEN to PED mode to output rs_id in map file, for cases where the chromosome is unknown.
0.6.5 - 11-08-2010 - PED to GEN mode compliant with SNPTEST2. Added --family and --snptest1 flags, --discrete_phenotype is now an optional flag, in PED to GEN mode.
0.6.1 - 30-07-2009 - Addition of missingness filter (--missing) in Subset mode. Fixed header titles in merged sample files.
0.6.0 - 06-07-2009 - Addition of Orient mode (-O). Fixed merge mode memory bug which caused a crash on some systems.
0.5.0 - 28-07-2008 - Addition of Merge mode (-M). Addition of logging and --log option. Missing data is represented by 0 0 0. Samples can be excluded in Subset mode (--sample_excl). Bug fix for PED to GEN, if a SNP in the PED file was e.g. 22 44 22 22 then in GEN alleles were (C -) not (C T).
0.4.1 - 12-02-2008 - Addition of --sex option to specify which column of the SAMPLE file is used for sex when converting GEN to PED files.
0.4.0 - 10-01-2008 - Read and write gzipped files. Bug fix for space/tab discrimination issue. Pass chromosome field between formats, if applicable.
0.3.0 - 07-09-2007 - Addition of the GEN to PED conversion option. Default output file names.
0.2.0 - 17-07-2007 - Addition of conversion option. Change made to sample file format to be in-line with the FILE FORMAT used for SNPTEST and IMPUTE.
0.1.6 - 07-06-2007 - First version made available

The following people have contributed to the development of the methodology and software for GTOOL
Colin Freeman, Jonathan Marchini

If you have any questions regarding the use of this program please send an email to Dr Colin Freeman (cfreeman <at> well <dot> ox <dot> ac <dot> uk)