update July 18, 2020
NAME

ncbiquery.py - Send an Entrez query to NCBI and return the result

SYNOPSIS
ncbiquery.py  --db database [--qfile qfile_name] --query entrez_query_statement [--filter entrez_filter_statement] [--maxcount integer] --format sequence_format --out outfile
ncbiquery.py  --qfile qfile_name --related [--maxcount integer] --format sequence_format --out outfile
ncbiquery.py  --qfile qfile_name --target database [-maxcount integer] --format sequence_format --out outfile

DESCRIPTION
ncbiquery sends a query to an NCBI database using the Entrez query syntax. Results are returned to outfile in the specified format.The -qfile option makes it possible to use the document summary from a previous search to further refine the search with a new query term.

ncbiquery.py is a wrapper that hides the individual BioPython Bio::Entrez functions behind a single command line. It is specifically intended to simplify running the Entrez Eutilities from BioLegato.

If the environment variables $BL_EMAIL and $NCBI_ENTREZ_KEY are set, all requests to the Entrez Eutils will be processed using the user's Entrez API key.

OPTIONS
  --qfile qfile_name - output from a previous ncbiquery.py run. This run will refine the previous search.
  --query entrez_query_statement - search parameters
  --filter entrez_filter_statement - limit search based on other parameters
  --related - call elink to look up neighbors in current database
  --target database - call elink to find links in a different database
  --maxcount integer - (default=500) If the number of hits exceeds maxcount, do not retrieve entries, but just display the search metadata.
  --format sequence_format -  (default= docsum) format as defined by NCBI EUtilities.
  --db database - NCBI database as defined for EUtilities
  --out output_file  

EXAMPLES

1. Search for entries in the NCBI core nucleotide database in which the author is Fristensky and the organism contains the word Pisum. Write output to a file in the docsum XML format.

Note: ncbiquery is a bash shell script that runs ncbiquery.py. It sets PYTHONPATH, as described below.


ncbiquery --db nuccore --query 'Fristensky [AUTH] AND Pisum [ORGN]' --format docsum --out FristenskyPisum.ncbiquery

2. In the core nucleotide database, find sequences related to those found in example 1.

ncbiquery --qfile FristenskyPisum.ncbiquery --related --format docsum --out FristenskyPisumRelated.ncbiquery

3. From the sequences found in example 1, find linked sequences in the protein database

ncbiquery --qfile FristenskyPisum.ncbiquery --target protein --format docsum --out FristenskyPisumProtLink.ncbiquery

ENVIRONMENT
PYTHONPATH (required) - Path to BioPython. ncbiquery sets PYTHONPATH to a platform specific directory containing BioPython, and then runs ncbiquery.py. If you run ncbiquery.py directly, you need to set PYTHONPATH manually.

BL_EMAIL (required) - Email address to accompany requests to NCBI Entrez. Required by NCBI

NCBI_ENTREZ_KEY (optional) - Unique identifier for requests to NCBI Entrez. If no key is supplied, you may get slower retrieval times. If you do a large number of requests (eg. more than 3 per minute) you must supply a key, or NCBI will ramp down your future requests. See NCBI Eutil API keys.

REFERENCES
New API Keys for the E-utilities
https://ncbiinsights.ncbi.nlm.nih.gov/2017/11/02/new-api-keys-for-the-e-utilities/
NCBI Entrez Help Manual at http://www.ncbi.nlm.nih.gov/books/NBK3837/#EntrezHelp.Entrez_Searching_Options.

NCBI E-utilities Quick Start http://www.ncbi.nlm.nih.gov/books/NBK25500

BioPython Bio::Entrez at http://biopython.org/DIST/docs/api/Bio.Entrez-module.html

INSTALLATION NOTE
The ncbiquery.py script expects that xtract from the NCBI EDirect Package (http://www.ncbi.nlm.nih.gov/books/NBK179288/) is present in the execution PATH. In BIRCH, this script is found in $BIRCH/script. xtract is called by ncbiquery.py to extract specific fields from DocumentSummary output generated by NCBI Entrez tools.

AUTHOR
Dr. Brian Fristensky
Department of Plant Science
University of Manitoba
Winnipeg, MB  Canada R3T 2N2
frist@cc.umanitoba.ca
http://home.cc.umanitoba.ca/~frist