entrez

Documentation

Overview

Package entrez provides support for interaction with the NCBI Entrez Utility Programs (E-utilities).

Please see http://www.ncbi.nlm.nih.gov/books/n/helpeutils/chapter2/ for the E-utility usage policy.

Required parameters are specified by name in the function call. Optional parameters are passed via Parameter and History values. See the 'Entrez Programming Utilities Help' at http://www.ncbi.nlm.nih.gov/books/NBK25501/ for detailed explanation of the use of these programs.

The following two parameters should be included in all E-utility requests.

tool   Name of application making the E-utility call. Its value must be a string with no
       internal spaces.

email  E-mail address of the E-utility user. Its value must be a string with no internal
       spaces, and should be a valid e-mail address.

Index

• Constants
• Variables
• func DoCitMatch(query map[string]CitQuery, tool, email string) (map[string]int, error)
• func Fetch(db string, p *Parameters, tool, email string, h *History, id ...int) (io.ReadCloser, error)
• type CitQuery
• type Global
  • func DoGlobal(query, tool, email string) (*Global, error)
• type History
• type Info
  • func DoInfo(db, tool, email string) (*Info, error)
• type Link
  • func DoLink(fromDb, toDb, cmd, query string, p *Parameters, tool, email string, h *History, ...) (*Link, error)
• type Parameters
• type Post
  • func DoPost(db, tool, email string, h *History, id ...int) (*Post, error)
• type Search
  • func DoSearch(db, query string, p *Parameters, h *History, tool, email string) (*Search, error)
• type Spell
  • func DoSpell(db, query string, tool, email string) (*Spell, error)
• type Summary
  • func DoSummary(db string, p *Parameters, tool, email string, h *History, id ...int) (*Summary, error)

Constants

const (
	// Base is the base URL for the NCBI Entrez Programming Utilities (E-utilities) API.
	Base = "http://eutils.ncbi.nlm.nih.gov/entrez/eutils/"

	//  * Provides a list of the names of all valid Entrez databases.
	//  * Provides statistics for a single database, including lists of indexing fields and available
	//    link names.
	InfoUri = ncbi.Util(Base + "einfo.fcgi")

	//  * Provides a list of UIDs matching a text query.
	//  * Posts the results of a search on the History server.
	//  * Downloads all UIDs from a dataset stored on the History server.
	//  * Combines or limits UID datasets stored on the History server.
	//  * Sorts sets of UIDs.
	SearchUri = ncbi.Util(Base + "esearch.fcgi")

	//  * Uploads a list of UIDs to the Entrez History server.
	//  * Appends a list of UIDs to an existing set of UID lists attached to a Web Environment.
	PostUri = ncbi.Util(Base + "epost.fcgi")

	//  * Returns document summaries (DocSums) for a list of input UIDs.
	//  * Returns DocSums for a set of UIDs stored on the Entrez History server.
	SummaryUri = ncbi.Util(Base + "esummary.fcgi")

	//  * Returns formatted data records for a list of input UIDs.
	//  * Returns formatted data records for a set of UIDs stored on the Entrez History server.
	FetchUri = ncbi.Util(Base + "efetch.fcgi")

	//  * Returns UIDs linked to an input set of UIDs in either the same or a different Entrez database.
	//  * Returns UIDs linked to other UIDs in the same Entrez database that match an Entrez query.
	//  * Checks for the existence of Entrez links for a set of UIDs within the same database.
	//  * Lists the available links for a UID.
	//  * Lists LinkOut URLs and attributes for a set of UIDs.
	//  * Lists hyperlinks to primary LinkOut providers for a set of UIDs.
	//  * Creates hyperlinks to the primary LinkOut provider for a single UID.
	LinkUri = ncbi.Util(Base + "elink.fcgi")

	//  * Provides the number of records retrieved in all Entrez databases by a single text query.
	GlobalUri = ncbi.Util(Base + "egquery.fcgi")

	//  * Provides spelling suggestions for terms within a single text query in a given database.
	SpellUri = ncbi.Util(Base + "espell.fcgi")

	//  * Retrieves PubMed IDs (PMIDs) that correspond to a set of input citation queries.
	CitMatchUri = ncbi.Util(Base + "ecitmatch.cgi")
)

Variables

var (
	ErrNoIdProvided = errors.New("entrez: no id provided")
	ErrNoQuery      = errors.New("entrez: no query")
)

var Limit = ncbi.NewLimiter(time.Second / 3)

Limit is a package level limit on requests that can be sent to the Entrez server. This limit is mandated by chapter 2 of the E-utilities manual. Limit is exported to allow reuse of http.Requests provided by NewRequest without overrunning the Entrez request limit. Changing the the value of Limit to allow more frequent requests may result in IP blocking by the Entrez servers.

Functions

func DoCitMatch

func DoCitMatch(query map[string]CitQuery, tool, email string) (map[string]int, error)

DoCitMatch returns a map[string]int associating keys provided in the query to the citations requested in the query. If email is set, the response will also be sent to that address.

func Fetch

func Fetch(db string, p *Parameters, tool, email string, h *History, id ...int) (io.ReadCloser, error)

Fetch returns an io.ReadCloser that reads from the stream returned by an EFetch of the the given id list or history. It is the responsibility of the caller to close this if it is not nil. A non-nil error is returned for any http status code other than 200.

Types

type CitQuery

type CitQuery struct {
	JournalTitle string
	Year         string
	Volume       string
	FirstPage    string
	AuthorName   string
}

CitQuery represents a single element of a CitMatch citation query.

type Global

type Global struct {
	Query   string          `xml:"Term"`
	Results []global.Result `xml:"eGQueryResult>ResultItem"`
}

A Global holds the deserialised results of an EGQuery request.

func DoGlobal

func DoGlobal(query, tool, email string) (*Global, error)

DoGlobal returns a Global filled with the response from an EGQuery query.

type History

type History struct {
	QueryKey int    `xml:"QueryKey"`
	WebEnv   string `xml:"WebEnv"`
}

History stores an Entrez Web Environment and query key. The zero values of QueryKey and WebEnv indicate unset values.

type Info

type Info struct {
	DbList []string     `xml:"DbList>DbName"`
	DbInfo *info.DbInfo `xml:"DbInfo"`
	Err    string       `xml:"ERROR"`
}

An Info holds the deserialised results of an EInfo request.

func DoInfo

func DoInfo(db, tool, email string) (*Info, error)

DoInfo returns an Info filled with data obtained from an EInfo query of the specified db or all databases if db is an empty string.

type Link

type Link struct {
	LinkSets []link.LinkSet `xml:"LinkSet"`
	Err      *string        `xml:"ERROR"`
}

A Link holds the deserialised results of an ELink request.

func DoLink

func DoLink(fromDb, toDb, cmd, query string, p *Parameters, tool, email string, h *History, ids ...[]int) (*Link, error)

DoLink returns a Link filled with the response from an ELink action on the specified ids list. If h is not nil and its fields are non-zero, its field values are passed to ESummary. DoSummary returns an error if both h is nil and ids has length zero.

type Parameters

type Parameters struct {
	RetMode    string `param:"retmode"`
	RetType    string `param:"rettype"`
	RetStart   int    `param:"retstart"`
	RetMax     int    `param:"retmax"`
	Strand     int    `param:"strand"`
	SeqStart   int    `param:"seqstart"`
	SeqStop    int    `param:"seqstop"`
	Complexity int    `param:"complexity"`
	LinkName   string `param:"linkname"`
	Holding    string `param:"holding"`
	DateType   string `param:"datetype"`
	RelDate    string `param:"reldate"`
	MinDate    string `param:"mindate"`
	MaxDate    string `param:"maxdate"`
}

Parameters is used to pass optional parameters to E-utility programs. The relevant documentation for each of these parameters is at http://www.ncbi.nlm.nih.gov/books/n/helpeutils/chapter4/.

type Post

type Post struct {
	InvalidIds []int `xml:"InvalidIdList>Id"`
	*History
	Err *string `xml:"ERROR"`
}

A Post holds the deserialised results of an EPost request.

func DoPost

func DoPost(db, tool, email string, h *History, id ...int) (*Post, error)

DoPost returns a Post filled with the response from an EPost action on the specified id list. If h is not nil, its WebEnv field is passed as the E-utilies webenv parameter, and if h.QueryKey is zero, h will be filled with the history result from the EPost request.

type Search

type Search struct {
	Database string
	Count    int `xml:"Count"`
	RetMax   int `xml:"RetMax"`
	RetStart int `xml:"RetStart"`
	*History
	IdList           []int                   `xml:"IdList>Id"`
	Translations     []search.Translation    `xml:"TranslationSet>Translation"`
	TranslationStack search.TranslationStack `xml:"TranslationStack"`
	QueryTranslation *string                 `xml:"QueryTranslation"`
	Err              *string                 `xml:"ERROR"`
	NotFound         *search.NotFound        `xml:"ErrorList"`
	Warnings         *search.Warnings        `xml:"WarningList"`
}

A Search holds the deserialised results of an ESearch request.

func DoSearch

func DoSearch(db, query string, p *Parameters, h *History, tool, email string) (*Search, error)

DoSearch returns a Search filled with data obtained from an ESearch query of the specified db. If h is not nil the search will use the Entrez history server and will be filled with the history results of the ESearch query. If h.WebEnv is not empty, it will be passed to ESearch as the web environment and if h.QueryKey is not zero, it will be passed as the query key.

type Spell

type Spell struct {
	Database  string             `xml:"Database"`
	Query     string             `xml:"Query"`
	Corrected string             `xml:"CorrectedQuery"`
	Replace   spell.Replacements `xml:"SpelledQuery"`
	Err       string             `xml:"ERROR"`
}

A Spell holds the deserialised results of an ESpell request.

func DoSpell

func DoSpell(db, query string, tool, email string) (*Spell, error)

DoSpell returns a Spell filled with the response from an ESpell query.

type Summary

type Summary struct {
	Database  string
	Documents []summary.Document `xml:"DocSum"`
	Err       []string           `xml:"ERROR"`
}

A Summary holds the deserialised results of an ESummary request.

func DoSummary

func DoSummary(db string, p *Parameters, tool, email string, h *History, id ...int) (*Summary, error)

DoSummary returns a Summary filled with the response from an ESummary query on the specified id list. If h is not nil and its fields are non-zero, its field values are passed to ESummary. DoSummary returns an error if both h is nil and id has length zero.