BioGo NCBI

https://pkg.go.dev/github.com/biogo/ncbi
Admin
BioGo NCBI is a Go package providing API interfaces to NCBI services including Entrez Utility...
Tokens:25,789
Snippets:269
Trust Score:9.6
Update:5 months ago
Show doc for...
Tokens:
Raw
### Install biogo/ncbi Package

Source: https://pkg.go.dev/github.com/biogo/ncbi

Use 'go get' to install the biogo/ncbi package. Ensure you have a functioning Go compiler installed.

```bash
    $ go get github.com/biogo/ncbi/...

```

--------------------------------

### Get string representation of SearchInfo

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Returns the string representation of the SearchInfo object.

```go
func (s *SearchInfo) String() string
```

--------------------------------

### Util.GetResponse

Source: https://pkg.go.dev/github.com/biogo/ncbi

Performs an HTTP GET request and returns the raw http.Response.

```APIDOC
## (ut Util) GetResponse

### Description
Performs an HTTP GET request and returns the raw http.Response.

### Function Signature
```go
func (ut Util) GetResponse(v url.Values, tool, email string, l *Limiter) (*http.Response, error)
```

### Parameters
- **v** (url.Values) - The URL query parameters.
- **tool** (string) - The application name making the call.
- **email** (string) - The email address of the user.
- **l** (*Limiter) - The limiter to enforce request frequency.

### Returns
- **(*http.Response, error)** - The http.Response object and an error if the request fails.
```

--------------------------------

### Util.GetXML Method

Source: https://pkg.go.dev/github.com/biogo/ncbi

Performs a GET or POST request and unmarshals the response stream into the provided interface. The method choice depends on URL length.

```go
func (ut Util) GetXML(v url.Values, tool, email string, l *Limiter, d interface{}) error
```

--------------------------------

### Retrieve Sequences with Entrez Utility Programs

Source: https://pkg.go.dev/github.com/biogo/ncbi

This example demonstrates retrieving a large set of sequences using Entrez Utility Programs. It requires email and a query, and allows specifying output format, maximum records per request, destination file, and retries. The code handles retries for fetching and buffering data.

```go
package main

import (
	"bytes"
	"flag"
	"io"
	"log"
	"os"

	"github.com/biogo/ncbi"
	"github.com/biogo/ncbi/entrez"
)

const (
	db   = "protein"
	t   tool = "entrez.example"
)

var (
	clQuery = flag.String("query", "", "query specifies the search query for record retrieval (required).")
	   rettype = flag.String("rettype", "fasta", "rettype specifies the format of the returned data.")
	retmax  = flag.Int("retmax", 500, "retmax specifies the number of records to be retrieved per request.")
	out     = flag.String("out", "", "out specifies destination of the returned data (default to stdout).")
	email   = flag.String("email", "", "email specifies the email address to be sent to the server (required).")
	retries = flag.Int("retry", 5, "retry specifies the number of attempts to retrieve the data.")
	help    = flag.Bool("help", false, "help prints this message.")
)

func main() {
	ncbi.SetTimeout(0)

	flag.Parse()

	if *help {
		flag.Usage()
		os.Exit(0)
	}
	if *email == "" || *clQuery == "" {
		flag.Usage()
		os.Exit(1)
	}

	h := entrez.History{}
	s, err := entrez.DoSearch(db, *clQuery, nil, &h, tool, *email)
	if err != nil {
		log.Printf("error: %v\n", err)
		os.Exit(1)
	}
	log.Printf("will retrieve %d records.\n", s.Count)

	var of *os.File
	if *out == "" {
		of = os.Stdout
	} else {
		of, err = os.Create(*out)
		if err != nil {
			log.Printf("error: %v\n", err)
			os.Exit(1)
		}
		defer of.Close()
	}

	var (
		buf   = &bytes.Buffer{}
		p     = &entrez.Parameters{RetMax: *retmax, RetType: *rettype, RetMode: "text"}
		bn, n int64
	)
	for p.RetStart = 0; p.RetStart < s.Count; p.RetStart += p.RetMax {
		log.Printf("attempting to retrieve %d records starting from %d with %d retries.\n", p.RetMax, p.RetStart, *retries)
		var t int
		for t = 0; t < *retries; t++ {
			buf.Reset()
			var (
				r   io.ReadCloser
				_bn int64
			)
			r, err = entrez.Fetch(db, p, tool, *email, &h)
			if err != nil {
				if r != nil {
					r.Close()
				}
				log.Printf("failed to retrieve on attempt %d... error: %v ... retrying.\n", t, err)
				continue
			}
			_bn, err = io.Copy(buf, r)
			bn += _bn
			r.Close()
			if err == nil {
				break
			}
			log.Printf("failed to buffer on attempt %d... error: %v ... retrying.\n", t, err)
		}
		if err != nil {
			os.Exit(1)
		}

		log.Printf("retrieved records with %d retries... writing out.\n", t)
		_n, err := io.Copy(of, buf)
		n += _n
		if err != nil {
			log.Printf("Error: %v\n", err)
			os.Exit(1)
		}
	}
	if bn != n {
		log.Printf("writethrough mismatch: %d != %d\n", bn, n)
	}
}

```

--------------------------------

### Util.Get Method

Source: https://pkg.go.dev/github.com/biogo/ncbi

Performs a GET or POST request to an NCBI service. The method choice depends on URL length. The caller must close the returned io.ReadCloser.

```go
func (ut Util) Get(v url.Values, tool, email string, l *Limiter) (io.ReadCloser, error)
```

--------------------------------

### Get string representation of Rid

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Returns the string representation of the Rid object.

```go
func (r *Rid) String() string
```

--------------------------------

### Util.GetResponse Method

Source: https://pkg.go.dev/github.com/biogo/ncbi

Performs a GET or POST request to an NCBI service and returns the http.Response. The caller must close the response body.

```go
func (ut Util) GetResponse(v url.Values, tool, email string, l *Limiter) (*http.Response, error)
```

--------------------------------

### Rid.GetOutput

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Returns an Output filled with data obtained from a Get request for the request corresponding to the Rid.

```APIDOC
## Rid.GetOutput

### Description
Returns an Output filled with data obtained from a Get request for the request corresponding to the Rid.

### Method
```go
func (r *Rid) GetOutput(p *GetParameters, tool, email string) (*Output, error)
```

### Parameters
* `p` (*GetParameters) - Parameters for the Get request.
* `tool` (string) - The name of the tool submitting the request.
* `email` (string) - The email address of the user submitting the request.

### Returns
* `*Output` - An Output object containing the BLAST results.
* `error` - An error if retrieving the output fails.
```

--------------------------------

### GetMethodLimit Variable

Source: https://pkg.go.dev/github.com/biogo/ncbi

Defines the maximum URL length for GET method requests in the high-level API.

```go
var GetMethodLimit = 2048
```

--------------------------------

### Util.Get

Source: https://pkg.go.dev/github.com/biogo/ncbi

Performs an HTTP GET request with the given URL values, tool, email, and limiter. It returns a ReadCloser for the response body.

```APIDOC
## (ut Util) Get

### Description
Performs an HTTP GET request with the given URL values, tool, email, and limiter. It returns a ReadCloser for the response body.

### Function Signature
```go
func (ut Util) Get(v url.Values, tool, email string, l *Limiter) (io.ReadCloser, error)
```

### Parameters
- **v** (url.Values) - The URL query parameters.
- **tool** (string) - The application name making the call.
- **email** (string) - The email address of the user.
- **l** (*Limiter) - The limiter to enforce request frequency.

### Returns
- **(io.ReadCloser, error)** - A ReadCloser for the response body and an error if the request fails.
```

--------------------------------

### Util.GetXML

Source: https://pkg.go.dev/github.com/biogo/ncbi

Performs a GET or POST request and unmarshals the response stream directly into a provided interface.

```APIDOC
## Util.GetXML

### Description
Performs a GET or POST method call to the URI in ut, passing the parameters in v, tool and email. The returned stream is unmarshaled into d. The decision on which method to use is based on the length of the constructed URL the value of GetMethodLimit.

### Method
GET or POST (determined by URL length and GetMethodLimit)

### Parameters
- **v** (url.Values) - Parameters to be passed in the request.
- **tool** (string) - The tool name for the request.
- **email** (string) - The email address of the user.
- **l** (*Limiter) - A limiter to control request frequency.
- **d** (interface{}) - The interface to unmarshal the response into.

### Returns
- **error** - An error if the request or unmarshaling fails.
```

--------------------------------

### GetParameters Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Defines parameters for the Get command in the BLAST API. Refer to the NCBI documentation for detailed parameter explanations.

```go
type GetParameters struct {
	FormatType string `param:"FORMAT_TYPE"` // Ignored by GetOutput: "HTML", "Text", "ASN.1" or "XML".

	Alignments           int     `param:"ALIGNMENTS"`
	AlignmentView        string  `param:"ALIGNMENT_VIEW"`
	Descriptions         int     `param:"DESCRIPTIONS"`
	EntrezLinksNewWindow bool    `param:"ENTREZ_LINKS_NEW_WINDOW"`
	ExpectLow            float64 `param:"EXPECT_LOW"`
	ExpectHigh           float64 `param:"EXPECT_HIGH"`
	FormatEntrezQuery    string  `param:"FORMAT_ENTREZ_QUERY"`
	FormatObject         string  `param:"FORMAT_OBJECT"`
	NcbiGi               bool    `param:"NCBI_GI"`
	ResultsFile          bool    `param:"RESULTS_FILE"`
	Service              string  `param:"SERVICE"`
	ShowOverview         *bool   `param:"SHOW_OVERVIEW"`
}
```

--------------------------------

### Util.Get

Source: https://pkg.go.dev/github.com/biogo/ncbi

Performs a GET or POST method call to the URI. Returns an io.ReadCloser for the response. The caller is responsible for closing the reader.

```APIDOC
## Util.Get

### Description
Performs a GET or POST method call to the URI in ut, passing the parameters in v, tool and email. The decision on which method to use is based on the length of the constructed URL the value of GetMethodLimit. An io.ReadCloser is returned for a successful request. It is the caller's responsibility to close this.

### Method
GET or POST (determined by URL length and GetMethodLimit)

### Parameters
- **v** (url.Values) - Parameters to be passed in the request.
- **tool** (string) - The tool name for the request.
- **email** (string) - The email address of the user.
- **l** (*Limiter) - A limiter to control request frequency.

### Returns
- **io.ReadCloser** - A reader for the response body.
- **error** - An error if the request fails.
```

--------------------------------

### Util.GetXML

Source: https://pkg.go.dev/github.com/biogo/ncbi

Performs an HTTP GET request and unmarshals the XML response into the provided interface.

```APIDOC
## (ut Util) GetXML

### Description
Performs an HTTP GET request and unmarshals the XML response into the provided interface.

### Function Signature
```go
func (ut Util) GetXML(v url.Values, tool, email string, l *Limiter, d interface{}) error
```

### Parameters
- **v** (url.Values) - The URL query parameters.
- **tool** (string) - The application name making the call.
- **email** (string) - The email address of the user.
- **l** (*Limiter) - The limiter to enforce request frequency.
- **d** (interface{}) - The interface to unmarshal the XML response into.

### Returns
- **error** - An error if the request or unmarshalling fails.
```

--------------------------------

### Util.GetResponse

Source: https://pkg.go.dev/github.com/biogo/ncbi

Performs a GET or POST method call to the URI and returns the raw http.Response. The caller must close the response body.

```APIDOC
## Util.GetResponse

### Description
Performs a GET or POST method call to the URI in ut, passing the parameters in v, tool and email. The decision on which method to use is based on the length of the constructed URL the value of GetMethodLimit. An http.Response is returned for a successful request. It is the caller's responsibility to close the response body.

### Method
GET or POST (determined by URL length and GetMethodLimit)

### Parameters
- **v** (url.Values) - Parameters to be passed in the request.
- **tool** (string) - The tool name for the request.
- **email** (string) - The email address of the user.
- **l** (*Limiter) - A limiter to control request frequency.

### Returns
- **http.Response** - The HTTP response object.
- **error** - An error if the request fails.
```

--------------------------------

### Rid.GetReadCloser

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Returns an io.ReadCloser that reads from the stream returned by a Get request corresponding to the Rid.

```APIDOC
## Rid.GetReadCloser

### Description
Returns an io.ReadCloser that reads from the stream returned by a Get request corresponding to the Rid. It is the responsibility of the caller to close the returned stream.

### Method
```go
func (r *Rid) GetReadCloser(p *GetParameters, tool, email string) (io.ReadCloser, error)
```

### Parameters
* `p` (*GetParameters) - Parameters for the Get request.
* `tool` (string) - The name of the tool submitting the request.
* `email` (string) - The email address of the user submitting the request.

### Returns
* `io.ReadCloser` - An io.ReadCloser for the BLAST results stream.
* `error` - An error if retrieving the stream fails.
```

--------------------------------

### Get expected time of execution for BLAST job

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Returns the estimated time until the BLAST request can be satisfied.

```go
func (r *Rid) TimeOfExecution() time.Duration
```

--------------------------------

### Util.Prepare Method

Source: https://pkg.go.dev/github.com/biogo/ncbi

Constructs a URL using the base provided by Util and the given parameters.

```go
func (ut Util) Prepare(v url.Values, tool, email string) (*url.URL, error)
```

--------------------------------

### Util.Prepare

Source: https://pkg.go.dev/github.com/biogo/ncbi

Prepares a URL with the given values, tool, and email.

```APIDOC
## (ut Util) Prepare

### Description
Prepares a URL with the given values, tool, and email.

### Function Signature
```go
func (ut Util) Prepare(v url.Values, tool, email string) (*url.URL, error)
```

### Parameters
- **v** (url.Values) - The URL query parameters.
- **tool** (string) - The application name making the call.
- **email** (string) - The email address of the user.

### Returns
- **(*url.URL, error)** - The prepared URL object and an error if preparation fails.
```

--------------------------------

### Util.Prepare

Source: https://pkg.go.dev/github.com/biogo/ncbi

Constructs a URL with the base provided by the Util receiver and the given parameters.

```APIDOC
## Util.Prepare

### Description
Prepare constructs a URL with the base provided by ut and the parameters provided by v, tool and email.

### Parameters
- **v** (url.Values) - URL parameters.
- **tool** (string) - The tool name for the request.
- **email** (string) - The email address of the user.

### Returns
- **url.URL** - The constructed URL.
- **error** - An error if the URL construction fails.
```

--------------------------------

### Create a new Summary for BLAST output

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast/graphic

Returns a Summary object initialized with the provided BLAST output. This is the constructor for the Summary type.

```go
func NewSummary(o blast.Output) Summary
```

--------------------------------

### Util.NewRequest

Source: https://pkg.go.dev/github.com/biogo/ncbi

Prepares a new HTTP request with the specified method, database, URL values, tool, email, and limiter.

```APIDOC
## (ut Util) NewRequest

### Description
Prepares a new HTTP request with the specified method, database, URL values, tool, email, and limiter.

### Function Signature
```go
func (ut Util) NewRequest(method, db string, v url.Values, tool, email string, l *Limiter) (*http.Request, error)
```

### Parameters
- **method** (string) - The HTTP method (e.g., GET, POST).
- **db** (string) - The database to query.
- **v** (url.Values) - The URL query parameters.
- **tool** (string) - The application name making the call.
- **email** (string) - The email address of the user.
- **l** (*Limiter) - The limiter to enforce request frequency.

### Returns
- **(*http.Request, error)** - The prepared http.Request object and an error if the request preparation fails.
```

--------------------------------

### New type String method

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/spell

Returns the string representation of the New type.

```go
func (r New) String() string
```

--------------------------------

### DoSpell

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Performs an ESpell query to get spelling suggestions for a given query in a specified database.

```APIDOC
## DoSpell

### Description
Performs an ESpell query to obtain spelling suggestions for a given search query within a specified NCBI database. It returns a Spell object containing the corrected query and any replacement suggestions.

### Function Signature
```go
func DoSpell(db, query string, tool, email string) (*Spell, error)
```

### Parameters
- **db** (string) - The NCBI database for which to get spelling suggestions.
- **query** (string) - The query string to check for spelling.
- **tool** (string) - The name of the tool making the request.
- **email** (string) - The email address of the user making the request.

### Returns
- **(*Spell, error)** - A Spell object containing spelling suggestions and an error if the request failed.
```

--------------------------------

### Render Method

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast/graphic

Renders the Summary to a vg.Canvas. The provided function `cf` is responsible for creating a canvas of a specified width and height.

```APIDOC
## Method: Render

```go
func (s Summary) Render(cf func(w, h vg.Length) vg.Canvas) vg.Canvas
```

Render returns a vg.Canvas that has had the receiver's summary information rendered to it. The function cf must return a vg.Canvas that is w by h in size.
```

--------------------------------

### History Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Stores Entrez Web Environment and query key information. Zero values for QueryKey and WebEnv indicate unset states.

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

--------------------------------

### DoSpell Function Signature

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Function signature for performing an ESpell query to get query spelling suggestions.

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

--------------------------------

### Create a New Limiter

Source: https://pkg.go.dev/github.com/biogo/ncbi

Initializes a Limiter that enforces a specified duration between calls to Wait.

```go
func NewLimiter(d time.Duration) *Limiter

```

--------------------------------

### Get BLAST search status information

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Retrieves status information for a BLAST search request associated with the Rid.

```go
func (r *Rid) SearchInfo(tool, email string) (*SearchInfo, error)
```

--------------------------------

### DoPost Function

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Executes an EPost action on a specified list of IDs. If history is provided, its WebEnv is used, and if QueryKey is zero, history is updated with the response. Returns a Post struct.

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

--------------------------------

### New Type

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/spell

Represents a segment of replaced text in a query. It is a string type with methods to get its string representation and type.

```APIDOC
## Type: New

```
type New string
```

A New string contains a segment of replaced text of a query.

### Methods

#### String()

```
func (r New) String() string
```

#### Type()

```
func (r New) Type() string
```
```

--------------------------------

### Render Summary to a vg.Canvas

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast/graphic

Renders the receiver's summary information onto a provided vg.Canvas. The canvas must be created by the cf function, which specifies the desired width and height.

```go
func (s Summary) Render(cf func(w, h vg.Length) vg.Canvas) vg.Canvas
```

--------------------------------

### Util.NewRequest Method

Source: https://pkg.go.dev/github.com/biogo/ncbi

Creates an http.Request for NCBI utility programs. Subject to rate limiting by 'l', though circumvention may lead to IP blocking.

```go
func (ut Util) NewRequest(method, db string, v url.Values, tool, email string, l *Limiter) (*http.Request, error)
```

--------------------------------

### DoInfo Function

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Queries Entrez for database information using EInfo. Can query a specific database or all databases if db is an empty string. Returns an Info struct.

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

--------------------------------

### Define DbInfo Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/info

Defines the structure for database information, including metadata and field/link lists.

```go
type DbInfo struct {
	DbName      string   `xml:"DbName"`
	MenuName    string   `xml:"MenuName"`
	Description string   `xml:"Description"`
	Count       int      `xml:"Count"`
	LastUpdate  string   `xml:"LastUpdate"`
	FieldList   []Field  `xml:"FieldList>Field"`
	LinkList    []DbLink `xml:"LinkList>Link"`
}
```

--------------------------------

### New type Type method

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/spell

Returns the type of the New string.

```go
func (r New) Type() string
```

--------------------------------

### DoInfo

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Provides information about a specified Entrez database, including indexing fields and available link names. Requires a database name, tool name, and email address.

```APIDOC
## DoInfo

### Description
Provides information about a specified Entrez database, including indexing fields and available link names.

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

### Parameters
- **db** (string) - Required - The Entrez database to get information about.
- **tool** (string) - Required - Name of the application making the E-utility call.
- **email** (string) - Required - E-mail address of the E-utility user.

### Returns
- *Info - An Info object containing database details.
- error - An error if the request fails.
```

--------------------------------

### Get an io.ReadCloser for BLAST job output

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Returns an io.ReadCloser for the BLAST job's output stream. The caller is responsible for closing the stream.

```go
func (r *Rid) GetReadCloser(p *GetParameters, tool, email string) (io.ReadCloser, error)
```

--------------------------------

### Set HTTP Client Timeout

Source: https://pkg.go.dev/github.com/biogo/ncbi

Configures the HTTP client's timeout duration. The default is 10 seconds.

```go
func SetTimeout(d time.Duration)

```

--------------------------------

### Define DbLink Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/info

Defines the structure for database links, including name, description, and target database.

```go
type DbLink struct {
	Name        string `xml:"Name"`
	FullName    string `xml:"FullName"`
	Description string `xml:"Description"`
	DbTo        string `xml:"DbTo"`
}
```

--------------------------------

### DoGlobal Function

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Executes an EGQuery and returns a Global struct populated with the deserialized results. Requires a query string, tool name, and email address.

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

--------------------------------

### Post Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Holds deserialized results from an EPost request, including a list of invalid IDs, history information, and any errors.

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

--------------------------------

### Info Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Holds deserialized results from an EInfo request, including a list of databases, database-specific information, and any errors encountered.

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

--------------------------------

### Provider Struct Definition

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/link

Defines the Provider struct, containing information about the source of data, including name, abbreviation, ID, and URL.

```go
type Provider struct {
	Name     string `xml:"Name"`
	NameAbbr string `xml:"NameAbbr"`
	Id       Id     `xml:"Id"`
	Url      Url    `xml:"Url"`
	IconUrl  *Url   `xml:"IconUrl"`
}
```

--------------------------------

### Fetch

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Returns formatted data records for a list of input UIDs or a set of UIDs stored on the Entrez History server. Requires a database name, parameters, tool name, email, and optionally history and UIDs.

```APIDOC
## Fetch

### Description
Returns formatted data records for a list of input UIDs or a set of UIDs stored on the Entrez History server.

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

### Parameters
- **db** (string) - Required - The Entrez database to query.
- **p** (*Parameters) - Optional - Additional parameters for the request.
- **tool** (string) - Required - Name of the application making the E-utility call.
- **email** (string) - Required - E-mail address of the E-utility user.
- **h** (*History) - Optional - History object for retrieving UIDs from the History server.
- **id** (...int) - Optional - A list of UIDs to fetch.

### Returns
- io.ReadCloser - A reader for the fetched data.
- error - An error if the request fails.
```

--------------------------------

### DoSummary

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Returns document summaries (DocSums) for a list of input UIDs or a set of UIDs stored on the Entrez History server. Requires database name, parameters, tool name, email, and optionally history and UIDs.

```APIDOC
## DoSummary

### Description
Returns document summaries (DocSums) for a list of input UIDs or a set of UIDs stored on the Entrez History server.

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

### Parameters
- **db** (string) - Required - The Entrez database.
- **p** (*Parameters) - Optional - Additional parameters for the request.
- **tool** (string) - Required - Name of the application making the E-utility call.
- **email** (string) - Required - E-mail address of the E-utility user.
- **h** (*History) - Optional - History object for retrieving UIDs from the History server.
- **id** (...int) - Optional - A list of UIDs for which to retrieve summaries.

### Returns
- *Summary - A Summary object containing document summaries.
- error - An error if the request fails.
```

--------------------------------

### DoLink Function

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Performs an ELink action on a specified list of IDs. Can utilize history if provided. Returns a Link struct. An error is returned if history is nil and no IDs are provided.

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

--------------------------------

### Old type String method

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/spell

Returns the string representation of the Old type.

```go
func (o Old) String() string
```

--------------------------------

### LinkInfo Struct Definition

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/link

Defines the LinkInfo struct, providing details about a link, including database, name, URL, and priority.

```go
type LinkInfo struct {
	DbTo     string  `xml:"DbTo"`
	LinkName string  `xml:"LinkName"`
	MenuTag  *string `xml:"MenuTag"`
	HtmlTag  *string `xml:"HtmlTag"`
	Url      *Url    `xml:"Url"`
	Priority int     `xml:"Priority"`
}
```

--------------------------------

### Link Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Holds deserialized results from an ELink request, containing a list of link sets and any errors.

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

--------------------------------

### Parameters Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

A struct for passing optional parameters to E-utility programs, covering various settings like retrieval mode, type, start/max results, and date ranges.

```go
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"`
	Field      string `param:"field"`
	APIKey     string `param:"api_key"`
	Sort       string `param:"sort"`
}
```

--------------------------------

### Define Replacement interface

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/spell

Defines an interface for text fragments indicating a change specified by ESpell. Implementations must provide String and Type methods.

```go
type Replacement interface {
	String() string
	Type() string
}
```

--------------------------------

### Rid.String

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Returns the string representation of the Rid.

```APIDOC
## Rid.String

### Description
Returns the string representation of the Rid.

### Method
```go
func (r *Rid) String() string
```

### Returns
* `string` - The string representation of the Rid.
```

--------------------------------

### DoPost

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Uploads a list of UIDs to the Entrez History server or appends them to an existing set. Requires a database name, tool name, email, and optionally a history object and UIDs.

```APIDOC
## DoPost

### Description
Uploads a list of UIDs to the Entrez History server or appends them to an existing set.

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

### Parameters
- **db** (string) - Required - The Entrez database.
- **tool** (string) - Required - Name of the application making the E-utility call.
- **email** (string) - Required - E-mail address of the E-utility user.
- **h** (*History) - Optional - History object to which UIDs will be posted.
- **id** (...int) - Optional - A list of UIDs to post.

### Returns
- *Post - A Post object containing information about the posted UIDs.
- error - An error if the request fails.
```

--------------------------------

### Util.NewRequest

Source: https://pkg.go.dev/github.com/biogo/ncbi

Constructs an http.Request object for the specified method and parameters.

```APIDOC
## Util.NewRequest

### Description
Returns an http.Request for the utility, ut using the given method. Parameters to be sent to the utility program should be places in db, v, tool and email. NewRequest is subject to a limit that prevents requests being sent more frequently than allowed by l. The limit is easy to circumvent, though circumvention may result in IP blocking by the NCBI servers, so please do not do this.

### Method
Specified by the `method` parameter (e.g., GET, POST).

### Parameters
- **method** (string) - The HTTP method for the request.
- **db** (string) - The database to query.
- **v** (url.Values) - URL parameters.
- **tool** (string) - The tool name for the request.
- **email** (string) - The email address of the user.
- **l** (*Limiter) - A limiter to control request frequency.

### Returns
- **http.Request** - The constructed HTTP request.
- **error** - An error if the request creation fails.
```

--------------------------------

### CitQuery Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Represents a single citation query element, used for specifying criteria like journal title, year, volume, page, and author name.

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

--------------------------------

### Global Struct

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Holds deserialized results from an EGQuery request, including the original query and a list of result items.

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

--------------------------------

### Define New type

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/spell

Defines a string type for a segment of replaced text in a query.

```go
type New string
```

--------------------------------

### Perform BLAST Search

Source: https://pkg.go.dev/github.com/biogo/ncbi

Submits a query to the BLAST server, monitors its status, and retrieves results. It includes retry logic for data retrieval errors and handles various search statuses.

```go
// tool is required by the BLAST server.
const tool  = "blast.example"

// BLAST submits a query to the BLAST server, waits for the server's estimated time of
// execution and retrieves the search status. If the search is ready the results are then
// retrieved and returned. If errors are returned during data retrieval from the server,
// retrieval is retried with up to retry attempts; all server requests honour the request
// frequency policy specified in the BLAST usage guidelines.
func BLAST(query string, retry int, pp *blast.PutParameters, gp *blast.GetParameters, email string) (*blast.Output, error) {
	// Put the query request to the BLAST server.
	r, err := blast.Put(query, pp, tool, email)
	if err != nil {
		return nil, err
	}

	var o *blast.Output
	for k := 0; k < retry; k++ {
		// Wait for RTOE to elapse and get search status.
		var s *blast.SearchInfo
		s, err = r.SearchInfo(tool, email)
		if err != nil {
			return nil, err
		}

		// Output search status.
		fmt.Println(s)

		switch s.Status {
		case "WAITING":
			continue
		case "FAILED":
			return nil, fmt.Errorf("search: %s failed", r)
		case "UNKNOWN":
			return nil, fmt.Errorf("search: %s expired", r)
		case "READY":
			if !s.HaveHits {
				return nil, fmt.Errorf("search: %s no hits", r)
			}
		default:
			return nil, errors.New("unknown error")
		}

		// We have hits, so get the BLAST output.
		o, err = r.GetOutput(gp, tool, email)
		if err == nil {
			return o, err
		}
	}

	return nil, fmt.Errorf("%s exceeded retries", r)
}

```

--------------------------------

### DoLink

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Returns UIDs linked to an input set of UIDs in either the same or a different Entrez database. Supports various linking and querying options. Requires source and target databases, command, query, tool name, email, and optionally parameters, history, and more.

```APIDOC
## DoLink

### Description
Returns UIDs linked to an input set of UIDs in either the same or a different Entrez database. Supports various linking and querying options.

### Function Signature
func DoLink(fromDb, toDb, cmd, query string, p *Parameters, tool, email string, h *History, ...) (*Link, error)

### Parameters
- **fromDb** (string) - Required - The source Entrez database.
- **toDb** (string) - Required - The target Entrez database.
- **cmd** (string) - Required - The command to perform (e.g., 'neighbor', 'llink').
- **query** (string) - Required - The query to use for linking.
- **p** (*Parameters) - Optional - Additional parameters for the request.
- **tool** (string) - Required - Name of the application making the E-utility call.
- **email** (string) - Required - E-mail address of the E-utility user.
- **h** (*History) - Optional - History object for retrieving UIDs from the History server.
- **...** - Optional - Additional arguments depending on the command.

### Returns
- *Link - A Link object containing information about linked UIDs.
- error - An error if the request fails.
```

--------------------------------

### Retrieve BLAST job output

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Fetches the output data for a BLAST job using GetParameters. Returns an Output object containing the results.

```go
func (r *Rid) GetOutput(p *GetParameters, tool, email string) (*Output, error)
```

--------------------------------

### NewRid

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Returns a Rid with the given request ID string.

```APIDOC
## NewRid

### Description
Returns a Rid with the given request ID string. The returned Rid has a zero RTOE but is subject to the usage policy poll limiter. It is intended to be used to retrieve results from queries submitted without a call to Put.

### Method
```go
func NewRid(rid string) *Rid
```

### Parameters
* `rid` (string) - The request ID string.

### Returns
* `*Rid` - A new Rid object.
```

--------------------------------

### DoSearch

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Returns a list of UIDs matching a text query in a specified database. Supports optional parameters and history. Requires database name, query string, tool name, and email address.

```APIDOC
## DoSearch

### Description
Returns a list of UIDs matching a text query in a specified database. Supports optional parameters and history.

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

### Parameters
- **db** (string) - Required - The Entrez database to search.
- **query** (string) - Required - The text query.
- **p** (*Parameters) - Optional - Additional parameters for the search.
- **h** (*History) - Optional - History object to store search results.
- **tool** (string) - Required - Name of the application making the E-utility call.
- **email** (string) - Required - E-mail address of the E-utility user.

### Returns
- *Search - A Search object containing the list of UIDs and other search information.
- error - An error if the request fails.
```

--------------------------------

### DoInfo

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Retrieves information about Entrez databases. Can query a specific database or all databases.

```APIDOC
## func DoInfo

### Description
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.

### Signature
```go
func DoInfo(db, tool, email string) (*Info, error)
```

### Parameters
#### Query Parameters
- **db** (string) - Optional - The name of the database to get information about. If empty, information for all databases is returned.
- **tool** (string) - Required - The name of the tool making the request.
- **email** (string) - Optional - An email address to send the results to.

### Returns
- **(*Info)** - A pointer to an Info struct containing database information.
- **error** - An error if the request fails.
```

--------------------------------

### DoPost

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Performs an EPost request to create a new history of search results. Can use an existing history or create a new one.

```APIDOC
## func DoPost

### Description
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.

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

### Parameters
#### Query Parameters
- **db** (string) - Required - The Entrez database to post to.
- **tool** (string) - Required - The name of the tool making the request.
- **email** (string) - Optional - An email address to send the results to.
- **h** (*History) - Optional - A History struct containing WebEnv and QueryKey. If h is nil, a new history will be created.
- **id** (...int) - Optional - A list of integer IDs to post.

### Returns
- **(*Post)** - A pointer to a Post struct containing information about the posted IDs and history.
- **error** - An error if the request fails.
```

--------------------------------

### Replacement Interface

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/spell

Defines an interface for text fragments that indicate changes specified by ESpell. Implementations must provide String() and Type() methods.

```APIDOC
## Interface: Replacement

```
interface Replacement {
	String() string
	Type() string
}
```

A Replacement is text fragment that indicates a change specified by ESpell.
```

--------------------------------

### Fetch

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Fetches data from an Entrez database based on provided IDs or history. Returns an io.ReadCloser for the data stream.

```APIDOC
## func Fetch

### Description
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.

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

### Parameters
#### Query Parameters
- **db** (string) - Required - The Entrez database to fetch from.
- **p** (*Parameters) - Optional - A Parameters struct for additional fetch options.
- **tool** (string) - Required - The name of the tool making the request.
- **email** (string) - Optional - An email address to send the results to.
- **h** (*History) - Optional - A History struct containing WebEnv and QueryKey for previous queries.
- **id** (...int) - Optional - A list of integer IDs to fetch.

### Returns
- **io.ReadCloser** - A reader for the fetched data. Must be closed by the caller.
- **error** - An error if the request fails or returns a non-200 status code.
```

--------------------------------

### Create a new Rid object

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast

Constructs a new Rid object with the provided request ID string. Useful for retrieving results from queries submitted without an explicit Put call.

```go
func NewRid(rid string) *Rid
```

--------------------------------

### Old type Type method

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/spell

Returns the type of the Old string.

```go
func (o Old) Type() string
```

--------------------------------

### NewSummary Function

Source: https://pkg.go.dev/github.com/biogo/ncbi/blast/graphic

Creates a new Summary object from a given blast.Output. By default, all graphical elements (legend, alignments, depths) are enabled.

```APIDOC
## Function: NewSummary

```go
func NewSummary(o blast.Output) Summary
```

NewSummary returns a Summary of the provided blast output.
```

--------------------------------

### NotFound Struct Definition

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/search

Represents fields or phrases not found during an Entrez search.

```go
type NotFound struct {
	Phrase []string `xml:"PhraseNotFound"`
	Field  []string `xml:"FieldNotFound"`
}
```

--------------------------------

### IdUrlSet Type

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez/link

Contains an ID and a list of ObjUrl, along with optional informational text.

```APIDOC
## Type IdUrlSet

```
type IdUrlSet struct {
	Id     Id       `xml:"Id"`
	ObjUrl []ObjUrl `xml:"ObjUrl"`
	Info   *string  `xml:"Info"`
}
```
```

--------------------------------

### DoCitMatch Function

Source: https://pkg.go.dev/github.com/biogo/ncbi/entrez

Performs a citation match query against the Entrez server. Returns a map of query keys to citation counts and an error if any. Optionally sends results to a specified email.

```go
func DoCitMatch(query map[string]CitQuery, tool, email string) (map[string]int, error)
```
Tokens:
Raw