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 fromentrezpy.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 andentrezpy.elink.elink_parameter.ElinkParameter.cmd
is neighbor. ELink has no set maximum for UIDs which can be linked in one query, fixingentrezpy.elink.elink_parameter.ElinkParameter.query_size
,entrezpy.elink.elink_parameter.ElinkParameter.request_size
, andentrezpy.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()
andanalyze_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
orrelaxed.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)¶
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 responseReturns: 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
) – responseentrezpy.requester.requester.Requester
- request (
entrezpy.base.request.EutilsRequest
) – query requestReturns: 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 fromconvert_response()
- request (
entrezpy.base.request.EutilsRequest
) – query requestReturns: 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 fromentrezpy.requester.requester.Requester
- request (
entrezpy.base.request.EutilsRequest
) – query requestRaises: 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 isentrezpy.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