blast

package
v1.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jan 23, 2019 License: BSD-3-Clause Imports: 11 Imported by: 0

Documentation

Overview

Package blast provides support for interaction with the NCBI BLAST service.

Please see http://blast.ncbi.nlm.nih.gov/Blast.cgi?CMD=Web&PAGE_TYPE=BlastDocs&DOC_TYPE=DeveloperInfo for the BLAST service usage policy.

Required parameters are specified by name in the function call. Optional parameters are passed via parameter struct values. See the 'QBlast URL API User's Guide' at http://www.ncbi.nlm.nih.gov/BLAST/Doc/urlapi.html for explanation of the use of these programs.

The following two parameters should be included in all BLAST requests.

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

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

Index

Constants

View Source
const RidPollLimit = 60 * time.Second

Blast server usage policy requires that users not poll for any single RID more often than once a minute. The blast package Get requests honour this policy.

Variables

View Source
var (
	ErrNoRidProvided = errors.New("blast: no RID provided")
	ErrMissingRid    = errors.New("blast: missing RID/RTOE field")
	ErrMissingStatus = errors.New("blast: missing Status field")
)

Limit is a package level limit on requests that can be sent to the BLAST server. This limit is mandated by the BLAST service usage policy. Limit is exported to allow reuse of http.Requests provided by RequestWebReadCloser without overrunning the BLAST request limit. Changing the the value of Limit to allow more frequent requests may result in IP blocking by the BLAST servers.

View Source
var URL = ncbi.Util("http://www.ncbi.nlm.nih.gov/blast/Blast.cgi")

URL is the base URL for the NCBI BLAST URL API.

Functions

func RequestWebReadCloser

func RequestWebReadCloser(page string, p *WebParameters, tool, email string) (io.ReadCloser, error)

RequestWebReadCloser returns an io.ReadCloser that reads from the stream returned by a Web request of the the given page. It is the responsibility of the caller to close the returned stream.

Types

type ErrBadRequest

type ErrBadRequest string

func (ErrBadRequest) Error

func (e ErrBadRequest) Error() string

type GetParameters

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"`
}

GetParameters is used to pass optional parameters to the Get command. The relevant documentation for each of these parameters is at http://www.ncbi.nlm.nih.gov/BLAST/Doc/node9.html.

type Hit

type Hit struct {
	N         int    `xml:"Hit_num"`       // Hit_num
	Id        string `xml:"Hit_id"`        // Hit_id
	Def       string `xml:"Hit_def"`       // Hit_def
	Accession string `xml:"Hit_accession"` // Hit_accession
	Len       int    `xml:"Hit_len"`       // Hit_len
	Hsps      []Hsp  `xml:"Hit_hsps>Hsp"`  // Hit_hsps?
}

A Hit holds the details of an individual Blast hit.

type Hsp

type Hsp struct {
	N              int     `xml:"Hsp_num"`          // Hsp_num
	BitScore       float64 `xml:"Hsp_bit-score"`    // Hsp_bit-score
	Score          float64 `xml:"Hsp_score"`        // Hsp_score
	EValue         float64 `xml:"Hsp_evalue"`       // Hsp_evalue
	QueryFrom      int     `xml:"Hsp_query-from"`   // Hsp_query-from
	QueryTo        int     `xml:"Hsp_query-to"`     // Hsp_query-to
	HitFrom        int     `xml:"Hsp_hit-from"`     // Hsp_hit-from
	HitTo          int     `xml:"Hsp_hit-to"`       // Hsp_hit-to
	PhiPatternFrom *int    `xml:"Hsp_pattern-from"` // Hsp_pattern-from?
	PhiPatternTo   *int    `xml:"Hsp_pattern-to"`   // Hsp_pattern-to?
	QueryFrame     *int    `xml:"Hsp_query-frame"`  // Hsp_query-frame?
	HitFrame       *int    `xml:"Hsp_hit-frame"`    // Hsp_hit-frame?
	HspIdentity    *int    `xml:"Hsp_identity"`     // Hsp_identity?
	HspPositive    *int    `xml:"Hsp_positive"`     // Hsp_positive?
	HspGaps        *int    `xml:"Hsp_gaps"`         // Hsp_gaps?
	AlignLen       *int    `xml:"Hsp_align-len"`    // Hsp_align-len?
	Density        *int    `xml:"Hsp_density"`      // Hsp_density?
	QuerySeq       []byte  `xml:"Hsp_qseq"`         // Hsp_qseq
	SubjectSeq     []byte  `xml:"Hsp_hseq"`         // Hsp_hseq
	FormatMidline  []byte  `xml:"Hsp_midline"`      // Hsp_midline?
}

An Hsp holds the details of an individual Blast high scoring pair.

type Info

type Info string

func RequestInfo

func RequestInfo(target string, tool, email string) (*Info, error)

RequestInfo returns an Info with up-to-date information about NCBI BLAST services.

type Iteration

type Iteration struct {
	N          int         `xml:"Iteration_iter-num"`        // Iteration_iter-num
	QueryId    *string     `xml:"Iteration_query-ID"`        // Iteration_query-ID?
	QueryDef   *string     `xml:"Iteration_query-def"`       // Iteration_query-def?
	QueryLen   *int        `xml:"Iteration_query-len"`       // Iteration_query-len?
	Hits       []Hit       `xml:"Iteration_hits>Hit"`        // Iteration_hits?
	Statistics *Statistics `xml:"Iteration_stat>Statistics"` // Iteration_stat?
	Message    *string     `xml:"Iteration_message"`         // Iteration_message?
}

An Iteration holds the iteration data for a Blast result.

type Output

type Output struct {
	Program        string      `xml:"BlastOutput_program"`              // BlastOutput_program
	Version        string      `xml:"BlastOutput_version"`              // BlastOutput_version
	Reference      string      `xml:"BlastOutput_reference"`            // BlastOutput_reference
	Database       string      `xml:"BlastOutput_db"`                   // BlastOutput_db
	QueryId        string      `xml:"BlastOutput_query-ID"`             // BlastOutput_query-ID
	QueryDef       string      `xml:"BlastOutput_query-def"`            // BlastOutput_query-def
	QueryLen       int         `xml:"BlastOutput_query-len"`            // BlastOutput_query-len
	QuerSeq        *string     `xml:"BlastOutput_query-seq"`            // BlastOutput_query-seq?
	Parameters     Parameters  `xml:"BlastOutput_param>Parameters"`     // BlastOutput_param
	Iterations     []Iteration `xml:"BlastOutput_iterations>Iteration"` // BlastOutput_iterations
	MegaStatistics *Statistics `xml:"BlastOutput_mbstat>Statistics"`    // BlastOutput_mbstat?
}

An Output holds the deserialised results of an Blast Get request.

type Parameters

type Parameters struct {
	MatrixName  *string  `xml:"Parameters_matrix"`       // Parameters_matrix?
	Expect      float64  `xml:"Parameters_expect"`       // Parameters_expect
	Include     *float64 `xml:"Parameters_include"`      // Parameters_include?
	Match       *int     `xml:"Parameters_sc-match"`     // Parameters_sc-match?
	Mismatch    *int     `xml:"Parameters_sc-mismatch"`  // Parameters_sc-mismatch?
	GapOpen     int      `xml:"Parameters_gap-open"`     // Parameters_gap-open
	GapExtend   int      `xml:"Parameters_gap-extend"`   // Parameters_gap-extend
	Filter      *string  `xml:"Parameters_filter"`       // Parameters_filter?
	PhiPattern  *string  `xml:"Parameters_pattern"`      // Parameters_pattern?
	EntrezQuery *string  `xml:"Parameters_entrez-query"` // Parameters_entrez-query?
}

A Parameters holds the parameter information for a Blast result.

type PutParameters

type PutParameters struct {
	AutoFormat                 string   `param:"AUTO_FORMAT"`
	CompositionBasedStatistics bool     `param:"COMPOSITION_BASED_STATISTICS"`
	Database                   string   `param:"DATABASE"`
	DbGeneticCode              []int    `param:"DB_GENETIC_CODE"`
	EndPoints                  bool     `param:"ENDPOINTS"`
	EntrezQuery                string   `param:"ENTREZ_QUERY"`
	Expect                     *float64 `param:"EXPECT"`
	Filter                     string   `param:"FILTER"`
	GapCosts                   [2]int   `param:"GAPCOSTS"`
	GeneticCode                []int    `param:"GENETIC_CODE"`
	HitListSize                int      `param:"HITLIST_SIZE"`
	IThresh                    float64  `param:"I_THRESH"`
	Layout                     string   `param:"LAYOUT"`
	LCaseMask                  bool     `param:"LCASE_MASK"`
	Megablast                  bool     `param:"MEGABLAST"`
	MatrixName                 string   `param:"MATRIX_NAME"`
	NuclPenalty                int      `param:"NUCL_PENALTY"`
	NuclReward                 int      `param:"NUCL_REWARD"`
	OtherAdvanced              string   `param:"OTHER_ADVANCED"`
	PercIdent                  int      `param:"PERC_IDENT"`
	PhiPattern                 string   `param:"PHI_PATTERN"`
	Program                    string   `param:"PROGRAM"`
	Pssm                       string   `param:"PSSM"`
	QueryFile                  string   `param:"QUERY_FILE"`
	QueryBelieveDefline        bool     `param:"QUERY_BELIEVE_DEFLINE"`
	QueryFrom                  int      `param:"QUERY_FROM"`
	QueryTo                    int      `param:"QUERY_TO"`
	ResultsFile                bool     `param:"RESULTS_FILE"`
	SearchspEff                int      `param:"SEARCHSP_EFF"`
	Service                    string   `param:"SERVICE"`
	Threshold                  int      `param:"THRESHOLD"`
	UngappedAlignment          bool     `param:"UNGAPPED_ALIGNMENT"`
	WordSize                   int      `param:"WORD_SIZE"`
}

PutParameters is used to pass optional parameters to the Put command. The relevant documentation for each of these parameters is at http://www.ncbi.nlm.nih.gov/BLAST/Doc/node9.html.

type Rid

type Rid struct {
	// contains filtered or unexported fields
}

Rid implements RID recovery and waiting functions associated with Blast Put and Get requests.

func NewRid

func NewRid(rid string) *Rid

NewRid 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.

func Put

func Put(query string, p *PutParameters, tool, email string) (*Rid, error)

Put submits a request for a BLAST job to the NCBI BLAST server and returns the associated Rid containing the RID for the request.

func (*Rid) Delete

func (r *Rid) Delete(tool, email string) error

Delete deletes the the request and results corresponding to r from the NCBI BLAST server.

func (*Rid) GetOutput

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

GetOutput returns an Output filled with data obtained from an Get request for the request corresponding to r.

func (*Rid) GetReadCloser

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

GetReadCloser returns an io.ReadCloser that reads from the stream returned by a Get request corresponding to r. It is the responsibility of the caller to close the returned stream.

func (*Rid) Ready

func (r *Rid) Ready() <-chan time.Time

Ready returns a time.Time chan that will send when the estimated time for the Put request to be satisfied has elapsed. If the request has failed the channel is returned closed.

func (*Rid) SearchInfo

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

SearchInfo returns status information for the search request corresponding to r.

func (*Rid) String

func (r *Rid) String() string

String returns the string representation of the Rid.

func (*Rid) TimeOfExecution

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

TimeOfExecution returns the expected time until the request can be satisfied.

type SearchInfo

type SearchInfo struct {
	*Rid
	Status   string
	HaveHits bool
}

SearchInfo holds search status information.

func (*SearchInfo) String

func (s *SearchInfo) String() string

type Statistics

type Statistics struct {
	DbNum    int     `xml:"Statistics_db-num"`    // Statistics_db-num
	DbLen    int64   `xml:"Statistics_db-len"`    // Statistics_db-len
	HspLen   int     `xml:"Statistics_hsp-len"`   // Statistics_hsp-len
	EffSpace float64 `xml:"Statistics_eff-space"` // Statistics_eff-space
	Kappa    float64 `xml:"Statistics_kappa"`     // Statistics_kappa
	Lambda   float64 `xml:"Statistics_lambda"`    // Statistics_lambda
	Entropy  float64 `xml:"Statistics_entropy"`   // Statistics_entropy
}

A Statistics holds the search and database statistics for a Blast result.

type WebParameters

type WebParameters struct {
	Alignments                 int      `param:"ALIGNMENTS"`
	AlignmentView              string   `param:"ALIGNMENT_VIEW"`
	AutoFormat                 string   `param:"AUTO_FORMAT"`
	Cmd                        string   `param:"CMD"`
	CompositionBasedStatistics bool     `param:"COMPOSITION_BASED_STATISTICS"`
	Database                   string   `param:"DATABASE"`
	DbGeneticCode              []int    `param:"DB_GENETIC_CODE"`
	Descriptions               int      `param:"DESCRIPTIONS"`
	DocType                    string   `param:"DOC_TYPE"`
	EndPoints                  bool     `param:"ENDPOINTS"`
	EntrezLinksNewWindow       bool     `param:"ENTREZ_LINKS_NEW_WINDOW"`
	EntrezQuery                string   `param:"ENTREZ_QUERY"`
	Expect                     *float64 `param:"EXPECT"`
	ExpectLow                  float64  `param:"EXPECT_LOW"`
	ExpectHigh                 float64  `param:"EXPECT_HIGH"`
	Filter                     string   `param:"FILTER"`
	FormatEntrezQuery          string   `param:"FORMAT_ENTREZ_QUERY"`
	FormatObject               string   `param:"FORMAT_OBJECT"`
	FormatType                 string   `param:"FORMAT_TYPE"`
	GapCosts                   [2]int   `param:"GAPCOSTS"`
	GeneticCode                []int    `param:"GENETIC_CODE"`
	HitListSize                int      `param:"HITLIST_SIZE"`
	IThresh                    float64  `param:"I_THRESH"`
	Layout                     string   `param:"LAYOUT"`
	LCaseMask                  bool     `param:"LCASE_MASK"`
	Megablast                  bool     `param:"MEGABLAST"`
	MatrixName                 string   `param:"MATRIX_NAME"`
	NcbiGi                     bool     `param:"NCBI_GI"`
	NuclPenalty                int      `param:"NUCL_PENALTY"`
	NuclReward                 int      `param:"NUCL_REWARD"`
	OtherAdvanced              string   `param:"OTHER_ADVANCED"`
	PageType                   string   `param:"PAGE_TYPE"`
	PercIdent                  int      `param:"PERC_IDENT"`
	PhiPattern                 string   `param:"PHI_PATTERN"`
	Program                    string   `param:"PROGRAM"`
	Pssm                       string   `param:"PSSM"`
	Query                      string   `param:"QUERY"`
	QueryFile                  string   `param:"QUERY_FILE"`
	QueryBelieveDefline        bool     `param:"QUERY_BELIEVE_DEFLINE"`
	QueryFrom                  int      `param:"QUERY_FROM"`
	QueryTo                    int      `param:"QUERY_TO"`
	Rid                        string   `param:"RID"`
	ResultsFile                bool     `param:"RESULTS_FILE"`
	SearchspEff                int      `param:"SEARCHSP_EFF"`
	Service                    string   `param:"SERVICE"`
	ShowOverview               *bool    `param:"SHOW_OVERVIEW"`
	Threshold                  int      `param:"THRESHOLD"`
	UngappedAlignment          bool     `param:"UNGAPPED_ALIGNMENT"`
	WordSize                   int      `param:"WORD_SIZE"`
}

WebParameters is used to pass optional parameters to the Web command. The relevant documentation for each of these parameters is at http://www.ncbi.nlm.nih.gov/BLAST/Doc/node9.html. Note there is inadequate documentation for what parameters the Web command accepts, so all are included.

Directories

Path Synopsis
Package graphic provides simple BLAST report graphic rendering.
Package graphic provides simple BLAST report graphic rendering.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL