View on GitHub

Ferret

A user-friendly tool to extract data from the 1000 Genomes Project

Download Ferret

About Ferret

Ferret is a user-friendly tool to quickly extract human genetic variation data from the latest release of the 1000 Genomes (1KG) Project. Ferret was developed as a straightforward Java application to be accessible even for non-specialists who are not adept at bioinformatics. By converting the 1KG vcf files to a format that can be read by popular pre-existing tools (e.g. Plink and HaploView), Ferret offers easy manipulation and visualization of the 1KG SNP and indel data, easy access to allelic frequency, linkage disequilibrium and haplotype information, and eventually tagSNP design.

What does Ferret do?


*1KG, 1000 Genomes; ESP, Exome Sequencing Project; LD, linkage disequilibrium; CHROM, chromosome; POS, position; NB_CHR, number of chromosomes; A1, allele 1; A2, allele 2; FREQ, frequency.

Ferret unique features:

Ferret options

The user can access the Settings panel in the Ferret tab and can set the following options:


  • 1000 Genomes version: Phase 3 (default) or Phase 1
  • Human genome version: hg19/GRCh37 (default) or hg38/GRCh38
  • Minor allele frequency (MAF) threshold for variants to output
  • Output file format: Plink/HaploView files + allele frequency file, or allele frequency file only, or .vcf file

Ferret runtime

Several factors can impact runtime, such as the computer specs, the network quality, or the 1KG server access (e.g. running a large query at 2pm EST takes longer than at 9pm EST), so the numbers below are given for guidance only. The population size does not significantly impact Ferret runtimes.

Ferret output files size

The reference population(s) size is the main factor impacting output file size:

Contact

Developed by Sophie Limou and Andrew Taverner: ferret@nih.gov.
We encourage user community feedback to elicit new features.

Citation

Limou S, Taverner AM, Winkler CA. Ferret: a user-friendly Java tool to extract data from the 1000 Genomes project. Bioinformatics 2016, doi: 10.1093/bioinformatics/btw147 (View publication).

Download Ferret

Download Ferret

Ferret’s only pre-requisite is to have Java JRE 8 installed on your computer. In addition, Ferret requires Java JDK 8 to retrieve allelic frequencies from the Exome Sequencing Project.

Download Ferret Java source code Download Ferret perl script

For queries from a Terminal console and for integration into pipelines, we also provide Ferret perl script and Java source code.

Version history

2016, November 23

Ferret was updated due to the recent NCBI security switch to HTTPS only.


2016, February 19

The usability and flexibility of Ferret were improved for this version:


2015, August 12

This version was presented at the ASHG 2015 meeting and includes several new features:


2013, October 23

This initial version corresponds to the version presented at the ASHG 2013 meeting, allowing to retrieve 1KG data from a locus of interest.

Future directions

We are currently working on the development of the following features:

FAQ

  1. How to report a bug or ask a question?
  2. Which Java version does Ferret require to run on my computer?
  3. Which Ferret version do I have on my computer? How do I get the latest Ferret update?
  4. Ferret is not working: nothing is happening when hitting the ‘Run’ button.
  5. How can I get Ferret to run on a Linux/Ubuntu environment?
  6. I’m getting an error when trying to retrieve allelic frequencies from the Exome Sequencing Project. Why?
  7. Why is my gene or my variant not retrieved by Ferret?
  8. How do I get the allelic frequencies in two different populations?
  9. How do I input more than one gene?
  10. How do I input more than one SNP?
  11. What 1000 Genomes version does Ferret query?
  12. What human genome version does Ferret expect?
  13. A lot of reported variants are monomorphic in my population(s) of interest. Can I set a minor allelic frequency (MAF) threshold?
  14. What can I do with the output files?
  15. In the .frq file, what do the 1KG_A1_FREQ and 1KG_A2_FREQ fields correspond to?
  16. In the .frq file, what do the ESP6500_EA_A1_FREQ and ESP6500_EA_A1_FREQ fields correspond to?
  17. Why do I get more SNPs in the output files than input in the SNP tab?
  18. Why do I get CNV information in the .frq file and not in the Plink/HaploView files?
  19. Why do the indels appear as A/T SNP in Plink/HaploView?
  20. Can Ferret generate data in a different output format?
  21. Why are the gene coordinates different from the 1000 Genomes browser?

1. How to report a bug or ask a question?
First, make sure that you have the latest version installed on your computer (see #2 and 3). Then, please check carefully the website and FAQ to be sure that your problem was not already solved. Finally, you can send us an email (ferret@nih.gov) and we’ll do our best to answer you in a timely manner. Please provide us with the following information so we can better assist you:

2. Which Java version does Ferret require to run on my computer?
Ferret’s only pre-requisite is to have Java JRE 8 installed on your computer. In addition, if you are interested in querying the Exome Sequencing Project, be sure to also install Java JDK 8. The Java installations require administrative privileges. For Linux/Ubuntu users, the Java JRE/JDK installation can be tricky but you can find help online from the active Linux community (like here for Debian Linux, which includes Ubuntu).

3. Which Ferret version do I have on my computer? How do I get the latest Ferret update?
To find the version of Ferret installed on your computer, launch Ferret and the version number will appear in the window title (e.g. Ferret v2.1). You can also find the information in Help/About Ferret.
To check if a new Ferret version was released, go to Ferret/Check for updates: Ferret will check our website and invite you to download the latest version if necessary.

4. Ferret is not working: nothing is happening when hitting the ‘Run’ button.
Please make sure that your Internet connection is working properly, as Ferret needs to connect to the 1000 Genomes FTP and/or NCBI servers. Both servers are extensively accessed everyday all over the world, so please try again later to ensure that the problem does not come from overuse of NCBI and/or 1000 Genomes servers, rather than from Ferret itself. If the problem persists, do not hesitate to contact us (see #1).

5. How can I get Ferret to run on a Linux/Ubuntu environment?
If double-clicking the Ferret.jar file does not work, launch Ferret from a terminal window by typing the following command line: java –jar Path/to/Ferret.jar. If the problem persists, do not hesitate to contact us (see #1) and along with your Linux distribution, indicate the outputs generated from the following commands: java –version and javac –version.

6. I’m getting an error when trying to retrieve allelic frequencies from the Exome Sequencing Project. Why?
Be sure that you have Java JRE and JDK installed (see #2), and that you haven't renamed the Ferret application. If the problem persists, do not hesitate to contact us (see #1) and indicate whether a temporary file called evsClient0_15.jar is created in the same folder Ferret_vX.jar is installed in.

7. Why is my gene or my variant not retrieved by Ferret?
Ferret cannot currently report data from the sexual or mitochondrial chromosomes. Also, be sure to check that your gene or variant of interest is annotated on the human genome version being queried (hg19/GRCh37 by default).

8. How do I get the allelic frequencies in two different populations?
The allelic frequencies information is summarized in the .frq file (see #14).
If you are interested in the allelic frequencies in the combined group of two 1000 Genomes reference populations (e.g. CEU + TSI), just select simultaneously the two populations as input.
If you want to access the data from two populations independently (e.g. CEU and TSI separately), you will have to run two independent queries in Ferret (aka, first on CEU, and second on TSI).

9. How do I input more than one gene?
You have two options:

Important: do not forget to indicate if your input corresponds to gene name or gene ID.

10. How do I input more than one SNP?
You have two options:

Important: indicate only the unique rs number without the letters ‘rs’ (e.g. 2395029 for rs2395029).

11. What 1000 Genomes version does Ferret query?
By default, Ferret queries the most recent 1000 Genomes Phase 3. Alternatively, the user can query the Phase 1 release (go to Ferret/Settings).

12. What human genome version does Ferret expect?
By default, Ferret expects hg19/GRCh37 human genome version coordinates, as stated in the locus tooltip. Alternatively, the user can opt for the hg38/GRCh38 genome coordinates to query the 1KG Phase 3 release (go to Ferret/Settings).
Note: The Exome Sequencing Project data have not been converted to the hg38/GRCh38 genome version so far.

13. A lot of reported variants are monomorphic in my population(s) of interest. Can I set a minor allelic frequency (MAF) threshold?
Yes, you can set-up Ferret to only output variants with a frequency above a certain threshold (go to Ferret/Settings). The MAF threshold is applied to the selected 1KG populations. Alternatively, you can also apply the MAF threshold to the Exome Sequencing Project populations: variants respecting the MAF threshold in the selected 1KG populations, or in the Exome Sequencing Project African American or European American populations will then be printed out.

14. What can I do with the output files?
Ferret generates 4 output files:

The .map, .ped and .info files allow you to open, visualize and manipulate the genotype data with the popular Plink and HaploView tools. You can then easily access linkage disequilibrium and haplotype information for the 1KG SNPs and indels, merge the 1KG data with your own datasets, design tagSNPs, etc.

15. In the .frq file, what do the 1KG_A1_FREQ and 1KG_A2_FREQ fields correspond to?
For each variant, the 1KG_A1_FREQ and 1KG_A2_FREQ fields correspond to the allelic frequency in the input population(s) for allele 1 and allele 2, respectively.
If you have selected to output the allelic frequencies from the Exome Sequencing Project (ESP) as well (see #16), only the 1KG_A1_FREQ field will appear in the .frq file.

16. In the .frq file, what do the ESP6500_EA_A1_FREQ and ESP6500_EA_A1_FREQ fields correspond to?
These fields only appear in the .frq file if you selected to output Exome Sequencing Project (ESP) frequencies. For each variant, the ESP6500_EA_A1_FREQ and ESP6500_AA_A1_FREQ fields correspond to allele 1 frequency in the European American and African American ESP6500 datasets, respectively. The last ESP release is based on 6500 US individuals, including 4300 European Americans and 2203 African Americans (for more details, see the ESP website). ESP only provides allele and genotype counts, and does not provide genotype data: as a consequence, the Plink/HaploView files only contain the 1000 Genomes Project data.

17. Why do I get more SNPs in the output files than input in the SNP tab?
If you input a variant, it is possible to get more than one variant in the output files if your SNP of interest is overlapping with another variant (e.g. indel or CNV). Alternatively, you can get more variants if you elect to include surrounding variants in a certain base-pair window range around your SNP of interest.

18. Why do I get CNV information in the .frq file and not in the Plink/HaploView files?
Plink and HaploView do not support CNV data. However, we included CNV information in the .frq file, as it can be useful when studying a region of interest (e.g. for primer design).

19. Why do the indels appear as A/T SNPs in Plink/HaploView?
Plink and HaploView do not support indels. We transformed the small indels into A/T SNPs so Plink and HaploView can read them. To get the allele correspondence, report to the variant ID: the first allele corresponds to A when the second allele corresponds to T (e.g. indel_rs136158_AT/A for rs136158, where the first allele AT has been transformed in A, and the second allele A has been transformed in T).
The indel representation follows the vcf format coding where AT/A corresponds to a T/- deletion, and C/CA corresponds to a -/A insertion.

20. Can Ferret generate data in a different output format?
If you are not interested in the genotype data, Ferret can generate the .frq file only.
For more advanced users, we also offer to output the 1KG data in the .vcf format, which can then be merged with the user’s dataset, or used to filter out specific variants using VCFtools, or to annotate variants (e.g. gene location, functional prediction, GWAS catalog) using Annovar. Note: the Exome Sequencing Project does not provide genotype data and hence cannot be included in the .vcf output.
At this stage, Ferret does not offer other output formats. However, if you are interested in the popular binary Plink (.bed/.bim/.fam) or Oxford (.gen/.sample) genomic file format, we recommend converting them from our default Plink outputs using the --make-bed Plink option and the -P GTOOL option.

21. Why are the gene coordinates different from the 1000 Genomes browser?
For gene coordinates, Ferret queries the curated and non-redundant NCBI’s RefSeq database, when the 1000 Genomes browser is based on the Ensembl human gene annotations. The coordinates reported in these two databases are greatly overlapping, however some minor discrepancies can still occur.