Elink modules¶

Elinker¶

class entrezpy.elink.elinker.Elinker(tool, email, apikey=None, apikey_var=None, threads=None, qid=None)¶

Bases: entrezpy.base.query.EutilsQuery

Elinker implements elink queries to E-Utilities [0]. Elinker implements the inquire() method to link data sets on NCBI Entrez servers. All parameters described in [0] are acccepted. Elink queries consist of one request linking UIDs or an earlier requests on the history server within the same or different Entrez database. [0]: https://www.ncbi.nlm.nih.gov/books/NBK25499/#chapter4.ELink

Parameters:

tool (str) – tool name

email (str) – user email

apikey (str) – NCBI apikey

apikey_var (str) – enviroment variable storing NCBI apikey

threads (int) – set threads for multithreading

qid (str) – unique query id

inquire(parameter, analyzer=<entrezpy.elink.elink_analyzer.ElinkAnalyzer object>)¶

Implements virtual function inquire()

Prepares parameter instance entrezpy.elink.elink_parameter.ElinkerParameter

Starts threading monitor monitor_start()

Adds ElinkRequests to queue add_request()

Runs and analyzes all requests

Checks for errors check_requests()

Parameters:

parameter (dict) – ELink parameter

analyzer (analyzer) – analyzer for Elink Results, default is entrezpy.elink.elink_analyzer.ElinkAnalyzer

Returns:
analyzer or None if request errors have been encountered

Return type:
entrezpy.base.analyzer.EntrezpyAnalyzer instance or None

ElinkParameter¶

class entrezpy.elink.elink_parameter.ElinkParameter(parameter)¶

Bases: entrezpy.base.parameter.EutilsParameter

ElinkParameter checks query specific parameters and configures a entrezpy.elink.elink_query.ElinkQuery instance. A link gets its size from entrezpy.elink.elink_parameter.ElinkParameter.uids (from the id Eutils parameter) or earlier result stored on the Entrez history server. entrezpy.elink.elink_parameter.ElinkParameter.retmode is JSON where possible and entrezpy.elink.elink_parameter.ElinkParameter.cmd is neighbor. ELink has no set maximum for UIDs which can be linked in one query, fixing entrezpy.elink.elink_parameter.ElinkParameter.query_size, entrezpy.elink.elink_parameter.ElinkParameter.request_size, and entrezpy.elink.elink_parameter.ElinkParameter.expected_requests to 1.

Parameters: parameter (dict) – Eutils Elink parameter

nodb_cmds = {'acheck', 'lcheck', 'llinks', 'llinkslib', 'ncheck', 'prlinks'}¶

Elink commands not requiring the db parameter

retmodes = {'llinkslib': 'xml'}¶

The llinkslib elink command is the only command only returning XML

def_retmode = 'json'¶

Use JSON whenever possible

check()¶

Implements entrezpy.base.parameter.check() and aborts if required parameters are missing.

haveDb()¶

Check for required db parameter

Return type: bool

haveExpectedRequets()¶

Check fo expected requests. Hints an error if no requests are expected.

Return type: bool

haveQuerykey()¶

Check for required QueryKey parameter

Return type: bool

haveWebenv()¶

Check for required WebEnv parameter

Return type: bool

useHistory()¶

Check if history server should be used.

Return type: bool

set_retmode(retmode)¶

Checks for valid and supported Elink retmodes

Parameters: retmode (str) – requested retmode

Returns: default or cmd adjusted cretmode

Return type: str

dump()¶

Returns: Instance attributes

Return type: dict

ElinkAnalyzer¶

class entrezpy.elink.elink_analyzer.ElinkAnalyzer¶

Bases: entrezpy.base.analyzer.EutilsAnalyzer

ElinkAnalyzer implements parsing and superficial analysis of responses from ELink queries. ElinkAnalyzer implements the virtual methods analyze_result() and analyze_error(). The variety in possible Elink response formats results in several specialized parser. Default is to obtain results in JSON.

ElinkAnalyzer instances create linked.Linkset or relaxed.Linkset instances, depending on the request Elink result. entrezpy.elink.linkset.bare.Linkset.new_unit() is called to set the type of LinkSet unit based ont he used Elink command.

Warning

Expect for ‘llinkslib’, all responses are expected in JSON. ElinkAnalyzer will abort if a response from another command is not in JSON.

Variables: result – entrezpy.elink.elink_result.ElinkResult

init_result(response, request)¶

Inits entrezpy.elink.elink_result.ElinkResult

analyze_error(response, request)¶

Implements virtual function entrezpy.base.analyzer.analyze_error().

get_linkset_unit(elink_cmd)¶

analyze_result(response, request)¶

Implements virtual method entrezpy.base.analyzer.analyze_result() and checks used elink command to run according result parser.

analyze_linklist(linksets, lset_unit)¶

Parses ELink responses listing link information for UIDs.

Parameters:

linksets (dict) – ‘linkset’ part in an ELink JSON response from NCBI.

lset_unit – Elink LinkSet unit instance

analyze_links(linksets, lset_unit)¶

Parses ELink responses with links as UIDs or History server references.

Parameters:

linksets (dict) – ‘linkset’ part in an ELink JSON response from NCBI.

lset_unit – Elink LinkSet unit instance

parse_llinkslib(response, lset_unit, lset=None)¶

Exclusive XML parser for ‘llinkslib’ responses. Its approach is ugly but parses the XML. The cmd parametes is always ‘llinkslib’ but retains the calling signature.

Parameters:

response (io.StringIO) – XML response from Entrez

lset_unit – Elink LinkSet unit instance

check_error_json(response)¶

Checks for errors in JSON responses. Not unified among Eutil functions.

Parameters: response (dict) – reponse

Returns: status if JSON response has error message

Return type: bool

check_error_xml(response)¶

Checks for errors in XML responses

Parameters: response (io.stringIO) – XML response

Returns: if XML response has error message

Return type: bool

convert_response(raw_response_decoded, request)¶

Converts raw_response into the expected format, deduced from request and set via the retmode parameter.

Parameters:

raw_response (urllib.request.Request) – response entrezpy.requester.requester.Requester

request (entrezpy.base.request.EutilsRequest) – query request

Returns:
response in parseable format

Return type:
dict or io.stringIO

..note::

Using threads without locks randomly ‘looses’ the response, i.e. the raw response is emptied between requests. With locks, it works, but threading is not much faster than non-threading. It seems JSON is more prone to this than XML.

follow_up()¶

Return follow-up parameters if available

Returns: Follow-up parameters

Return type: dict

get_result()¶

Return result

Returns: result instance

Return type: entrezpy.base.result.EutilsResult

isEmpty()¶

Test for empty result

Return type: bool

isErrorResponse(response, request)¶

Checking for error messages in response from Entrez Servers and set flag hasErrorResponse.

Parameters:

response (dict or io.stringIO) – parseable response from convert_response()

request (entrezpy.base.request.EutilsRequest) – query request

Returns:
error status

Return type:
bool

isSuccess()¶

Test if response has errors

Return type: bool

known_fmts = {'json', 'text', 'xml'}¶

parse(raw_response, request)¶

Check for errors and calls parser for the raw response.

Parameters:

raw_response (urllib.request.Request) – response from entrezpy.requester.requester.Requester

request (entrezpy.base.request.EutilsRequest) – query request

Raises:
NotImplementedError – if request format is not in EutilsAnalyzer.known_fmts

ElinkRequest¶

class entrezpy.elink.elink_request.ElinkRequest(eutil, parameter)¶

Bases: entrezpy.base.request.EutilsRequest

The ElinkRequest class implements a single request as part of a Elinker query. It stores and prepares the parameters for a single request. See entrezpy.elink.elink_parameter.ElinkParameter for parameter description.

Parameters:

parameter – request parameter

type – entrezpy.elink.elink_parameter.ElinkParameter

linkname_cmds = {'neighbor', 'neighbor_history', 'neighbor_score'}¶

get_post_parameter()¶

Implements entrezpy.base.request.EutilsRequest.get_post_parameter().

If WebEnv and query_key are given the history server will be used.

If UIDs are given create an id parameter for each UID, i.e. id=123&id=456 (see entrezpy.elink.elink.elink_parameter.ElinkParameter.doseq)

Setting entrezpy.elink.elink.elink_parameter.ElinkParameter.doseq to False concatenats UIDs with commas, i.e. id=123,456

linkname: For neighbor or neighbor commands without a given linkname

one generated. See documentation for more details.

set_linkname(qry)¶

dump()¶

Dumps instance attributes

Returns: instance attributes

Return type: dict

calc_duration()¶

Calculates request duration

dump_internals(extend=None)¶

Dumps internal attributes for request.

Parameters: extend (dict) – extend dump with additional information

get_request_id()¶

Returns: full request id

Return type: str

prepare_base_qry(extend=None)¶

Returns instance attributes required for every POST request.

Parameters: extend (dict) – parameters extending basic parameters

Returns: base parameters for POST request

Return type: dict

report_status(processed_requests=None, expected_requests=None)¶

Reports request status when triggered

set_request_error(error)¶

Sets request error and HTTP/URL error message

Parameters: error (str) – HTTP/URL error

set_status_fail()¶

Set status if request failed

set_status_success()¶

Set status if request succeeded

start_stopwatch()¶

Starts time to measure request duration.

ElinkResult¶

class entrezpy.elink.elink_result.ElinkResult(qid, cmd)¶

Bases: entrezpy.base.result.EutilsResult

The ElinkResult class implements the uniform handling of different Elink LinkSets instances. It creates follow-up parameters if possible. ElinkResult instances store all results from one Elinker query as an aggregation of entrezpy.elink.linkset.bare.LinkSet instances. The size unit for ElinkResult is entrezpy.elink.linkset.bare.LinkSet.

Parameters:

qid (str) – query id

cmd (str) – used Elink command

Variables:

linksets (list) – list to store analyzed linskets

cmd (str) – invoked ELink command

size()¶

Implements entrezpy.base.result.EutilsResult.size(). :rtype: int

isEmpty()¶

Test for empty result

Returns: True if empty, False otherwise

Return type: bool

add_linkset(linkset)¶

Store linkset in self.linkset

Parameters: linkset (LinkSet instance) – populated LinkSet

dump()¶

Returns: all ELinkResult instance attributes

Return type: dict

get_link_parameter(reqnum=0)¶

Assemble follow-up parameters depending if the History server has been used.

Returns: parameters for follow-up query

Rype: dict

collapse_history_linksets()¶

Assemble follow-up WebEnv and query_key parameters in linksets. Skip those who cannot and test for unexpected result

Returns: parameters for follow-up query using History server

Rype: dict

collapse_uid_linksets()¶

Assemble follow-up UID and database parameters in linksets. Skip those who cannot and test for unexpected result

Returns: parameters for follow-up query using UIDs

Rype: dict

check_unexpected_dbnum(dbs)¶

Deal with more databases than expected when linking. Expecting one database per request for linking. Abort if more are present since this is unexpected. It shouldn’t happen, but make sure to catch such a case, report it and abort.

Parameters: dbs (dbs) – unique database names encountered in all LinkSets

canLink(lset)¶

Test if linkset can be use to generate automated follow-up queries

Parameters: lset (LinkSet instance) – LinkSet

Returns: True if empty, False otherwise

Return type: bool