o Rŀgu@szdZddlmZddlmZddlmZddlmZddl m Z Gdd d eZ d d Z e d kr;dd lmZedSdS)z@Bio.SearchIO object to model search results from a single query.deepcopy)chain)optionalcascade)_BaseSearchObject)Hitc@s0eZdZdZdZdDddZddZed d Zed d Z ed dZ ddZ ddZ ddZ ddZddZddZddZddZdd Zd!d"Zd#d$Zed%d&d'Zed(d)d*Zed+d,Zed-d.Zd/d0Zd1d2ZdEd3d4ZdEd5d6ZdEd7d8ZdEd9d:Z e!Z"d;e"fdd?Z$dFdBdCZ%dS)G QueryResultaClass representing search results from a single query. QueryResult is the container object that stores all search hits from a single search query. It is the top-level object returned by SearchIO's two main functions, ``read`` and ``parse``. Depending on the search results and search output format, a QueryResult object will contain zero or more Hit objects (see Hit). You can take a quick look at a QueryResult's contents and attributes by invoking ``print`` on it:: >>> from Bio import SearchIO >>> qresult = next(SearchIO.parse('Blast/mirna.xml', 'blast-xml')) >>> print(qresult) Program: blastn (2.2.27+) Query: 33211 (61) mir_1 Target: refseq_rna Hits: ---- ----- ---------------------------------------------------------- # # HSP ID + description ---- ----- ---------------------------------------------------------- 0 1 gi|262205317|ref|NR_030195.1| Homo sapiens microRNA 52... 1 1 gi|301171311|ref|NR_035856.1| Pan troglodytes microRNA... 2 1 gi|270133242|ref|NR_032573.1| Macaca mulatta microRNA ... 3 2 gi|301171322|ref|NR_035857.1| Pan troglodytes microRNA... 4 1 gi|301171267|ref|NR_035851.1| Pan troglodytes microRNA... 5 2 gi|262205330|ref|NR_030198.1| Homo sapiens microRNA 52... 6 1 gi|262205302|ref|NR_030191.1| Homo sapiens microRNA 51... 7 1 gi|301171259|ref|NR_035850.1| Pan troglodytes microRNA... 8 1 gi|262205451|ref|NR_030222.1| Homo sapiens microRNA 51... 9 2 gi|301171447|ref|NR_035871.1| Pan troglodytes microRNA... 10 1 gi|301171276|ref|NR_035852.1| Pan troglodytes microRNA... 11 1 gi|262205290|ref|NR_030188.1| Homo sapiens microRNA 51... ... If you just want to know how many hits a QueryResult has, you can invoke ``len`` on it. Alternatively, you can simply type its name in the interpreter:: >>> len(qresult) 100 >>> qresult QueryResult(id='33211', 100 hits) QueryResult behaves like a hybrid of Python's built-in list and dictionary. You can retrieve its items (Hit objects) using the integer index of the item, just like regular Python lists:: >>> first_hit = qresult[0] >>> first_hit Hit(id='gi|262205317|ref|NR_030195.1|', query_id='33211', 1 hsps) You can slice QueryResult objects as well. Slicing will return a new QueryResult object containing only the sliced hits:: >>> sliced_qresult = qresult[:3] # slice the first three hits >>> len(qresult) 100 >>> len(sliced_qresult) 3 >>> print(sliced_qresult) Program: blastn (2.2.27+) Query: 33211 (61) mir_1 Target: refseq_rna Hits: ---- ----- ---------------------------------------------------------- # # HSP ID + description ---- ----- ---------------------------------------------------------- 0 1 gi|262205317|ref|NR_030195.1| Homo sapiens microRNA 52... 1 1 gi|301171311|ref|NR_035856.1| Pan troglodytes microRNA... 2 1 gi|270133242|ref|NR_032573.1| Macaca mulatta microRNA ... Like Python dictionaries, you can also retrieve hits using the hit's ID. This is useful for retrieving hits that you know should exist in a given search:: >>> hit = qresult['gi|262205317|ref|NR_030195.1|'] >>> hit Hit(id='gi|262205317|ref|NR_030195.1|', query_id='33211', 1 hsps) You can also replace a Hit in QueryResult with another Hit using either the integer index or hit key string. Note that the replacing object must be a Hit that has the same ``query_id`` property as the QueryResult object. If you're not sure whether a QueryResult contains a particular hit, you can use the hit ID to check for membership first:: >>> 'gi|262205317|ref|NR_030195.1|' in qresult True >>> 'gi|262380031|ref|NR_023426.1|' in qresult False Or, if you just want to know the rank / position of a given hit, you can use the hit ID as an argument for the ``index`` method. Note that the values returned will be zero-based. So zero (0) means the hit is the first in the QueryResult, three (3) means the hit is the fourth item, and so on. If the hit does not exist in the QueryResult, a ``ValueError`` will be raised. >>> qresult.index('gi|262205317|ref|NR_030195.1|') 0 >>> qresult.index('gi|262205330|ref|NR_030198.1|') 5 >>> qresult.index('gi|262380031|ref|NR_023426.1|') Traceback (most recent call last): ... ValueError: ... To ease working with a large number of hits, QueryResult has several ``filter`` and ``map`` methods, analogous to Python's built-in functions with the same names. There are ``filter`` and ``map`` methods available for operations over both Hit objects or HSP objects. As an example, here we are using the ``hit_map`` method to rename all hit IDs within a QueryResult:: >>> def renamer(hit): ... hit.id = hit.id.split('|')[3] ... return hit >>> mapped_qresult = qresult.hit_map(renamer) >>> print(mapped_qresult) Program: blastn (2.2.27+) Query: 33211 (61) mir_1 Target: refseq_rna Hits: ---- ----- ---------------------------------------------------------- # # HSP ID + description ---- ----- ---------------------------------------------------------- 0 1 NR_030195.1 Homo sapiens microRNA 520b (MIR520B), micr... 1 1 NR_035856.1 Pan troglodytes microRNA mir-520b (MIR520B... 2 1 NR_032573.1 Macaca mulatta microRNA mir-519a (MIR519A)... ... The principle for other ``map`` and ``filter`` methods are similar: they accept a function, applies it, and returns a new QueryResult object. There are also other methods useful for working with list-like objects: ``append``, ``pop``, and ``sort``. More details and examples are available in their respective documentations. Finally, just like Python lists and dictionaries, QueryResult objects are iterable. Iteration over QueryResults will yield Hit objects:: >>> for hit in qresult[:4]: # iterate over the first four items ... hit ... Hit(id='gi|262205317|ref|NR_030195.1|', query_id='33211', 1 hsps) Hit(id='gi|301171311|ref|NR_035856.1|', query_id='33211', 1 hsps) Hit(id='gi|270133242|ref|NR_032573.1|', query_id='33211', 1 hsps) Hit(id='gi|301171322|ref|NR_035857.1|', query_id='33211', 2 hsps) If you need access to all the hits in a QueryResult object, you can get them in a list using the ``hits`` property. Similarly, access to all hit IDs is available through the ``hit_keys`` property. >>> qresult.hits [Hit(id='gi|262205317|ref|NR_030195.1|', query_id='33211', 1 hsps), ...] >>> qresult.hit_keys ['gi|262205317|ref|NR_030195.1|', 'gi|301171311|ref|NR_035856.1|', ...] )_items __alt_hit_idsNcCsL||_|pt|_i|_d|_i|_d|_d|_d|_|D]}| |qdS)aDInitialize a QueryResult object. :param id: query sequence ID :type id: string :param hits: iterator yielding Hit objects :type hits: iterable :param hit_key_function: function to define hit keys :type hit_key_function: callable, accepts Hit objects, returns string Nzzz) _id _hit_key_func_hit_key_functionr _description_QueryResult__alt_hit_idsprogramtargetversionappend)selfhitsidhit_key_functionhitr r M/var/www/html/myenv/lib/python3.10/site-packages/Bio/SearchIO/_model/query.py__init__s  zQueryResult.__init__cC t|jS)zIterate over hits.)iterrrr r r__iter__ zQueryResult.__iter__cCt|jS)z)Hit objects contained in the QueryResult.)listr valuesrr r rrzQueryResult.hitscCr")z8Hit IDs of the Hit objects contained in the QueryResult.)r#r keysrr r rhit_keysr%zQueryResult.hit_keyscCr")z*List of tuples of Hit IDs and Hit objects.)r#r itemsrr r rr(r%zQueryResult.itemscc|jEdHdS)z(Return an iterator over the Hit objects.N)r r$rr r riterhitszQueryResult.iterhitsccs|jEdHdS)z2Return an iterator over the ID of the Hit objects.N)r rr r r iterhit_keysszQueryResult.iterhit_keysccr))z=Return an iterator yielding tuples of Hit ID and Hit objects.N)r r(rr r r iteritemsr+zQueryResult.iteritemscCs.t|tr |||jvS||jvp||jvS)z?Return True if hit key in items or alternative hit identifiers.) isinstancerrr rrhit_keyr r r __contains__s zQueryResult.__contains__cCr)zReturn the number of items.)lenr rr r r__len__r!zQueryResult.__len__cCr)zReturn True if there are items.)boolr rr r r__bool__r!zQueryResult.__bool__cCsd|jt|fS)z7Return string representation of the QueryResult object.zQueryResult(id=%r, %r hits))rr2rr r r__repr__szQueryResult.__repr__c Csg}|d|j|jfd|j}z|j}Wn ty Ynw|d|7}|||jrId|j}t|dkrB|dddn|}|||d |j|j sZ|d n|d d d }||d||d t |j D]b\}}|dkrd|j|jf}t|dkr|ddd}|||t||fqv|t|j dkrd|j|jf}t|dkr|ddd}|||t||fqv|dkr|ddqvd |S)z:Return a human readable summary of the QueryResult object.zProgram: %s (%s)z Query: %sz (%i)z %sPNMz...z Target: %sz Hits: 0z Hits: %s %s %s)z----z-----z:----------------------------------------------------------z %13s %5s %s)#z# HSPzID + descriptionz%s %s:7z%14sz~~~ ) rrrrseq_lenAttributeError descriptionr2rr enumeratejoin) rlinesqid_liner?linepatternidxrhid_liner r r__str__sH            zQueryResult.__str__cCst|trt|j|}|||j|j}|||St|trrt |}d|kr/|krHnnt | D] \}}||krC|Sq7t dd||krTdkrnnt dt | D]\}}|||krm|Sq_t dz|j |WSty|j |j|YSw)z5Return a QueryResult object that matches the hit_key.rzlist index out of range)r.slicer#r __class__rr_transfer_attrsintr2rBr* IndexErrorr KeyErrorr)rr0robjlengthrHitemr r r __getitem__/s2      zQueryResult.__getitem__c Cst|ts tdt|tstd|j}|j}|dur)||kr(td||fn||_|j}|j}|durC||krBtd||fn||_||j vr\|j |j ddD]}|j |=qU||j vre|j |=||j |<|j ddD]}||j |<qqdS)z)Add an item of key hit_key and value hit.z)QueryResult object keys must be a string.z1QueryResult objects can only contain Hit objects.Nz0Expected Hit with query ID %r, found %r instead.z9Expected Hit with query description %r, found %r instead.r) r.str TypeErrorrrquery_id ValueErrorrAquery_descriptionr id_allr) rr0rqidhqidqdeschqdescalt_keyalt_idr r r __setitem__NsB        zQueryResult.__setitem__cCst|trt|j|g}nt|trt|j|}n|g}|D])}d}||jvr/|j|=d}||jvrA|j|j|=|j|=d}|sItt|q dS)zDelete item of key hit_key.FTN) r.rOr#r'rLr rrQrepr)rr0r'keydeletedr r r __delitem__|s$     zQueryResult.__delitem__r rXzQueryResult ID stringrrZzQueryResult descriptioncCs tddt|jDdddS)z4Access the HSP objects contained in the QueryResult.css|]}|VqdSNr ).0hspr r r sz#QueryResult.hsps..cS|jSrg) output_index)rir r rsz"QueryResult.hsps..)rd)sortedrrrr r rhspsszQueryResult.hspscCstt|jS)z.rz?The ID or alternative IDs of Hit %r exists in this QueryResult.)rrallr[rY)rrr0r rrrs ( zQueryResult.appendcCs0tt||j}|||j|j}|||S)aCreate new QueryResult object whose Hit objects pass the filter function. :param func: filter function :type func: callable, accepts Hit, returns bool Here is an example of using ``hit_filter`` to select Hits whose description begins with the string 'Homo sapiens', case sensitive:: >>> from Bio import SearchIO >>> qresult = next(SearchIO.parse('Blast/mirna.xml', 'blast-xml')) >>> def desc_filter(hit): ... return hit.description.startswith('Homo sapiens') ... >>> len(qresult) 100 >>> filtered = qresult.hit_filter(desc_filter) >>> len(filtered) 39 >>> print(filtered[:4]) Program: blastn (2.2.27+) Query: 33211 (61) mir_1 Target: refseq_rna Hits: ---- ----- ---------------------------------------------------------- # # HSP ID + description ---- ----- ---------------------------------------------------------- 0 1 gi|262205317|ref|NR_030195.1| Homo sapiens microRNA 52... 1 2 gi|262205330|ref|NR_030198.1| Homo sapiens microRNA 52... 2 1 gi|262205302|ref|NR_030191.1| Homo sapiens microRNA 51... 3 1 gi|262205451|ref|NR_030222.1| Homo sapiens microRNA 51... Note that instance attributes (other than the hits) from the unfiltered QueryResult are retained in the filtered object. >>> qresult.program == filtered.program True >>> qresult.target == filtered.target True )r#filterrrMrrrNrfuncrrRr r r hit_filters) zQueryResult.hit_filtercsJdd|jD}durfdd|D}|||j|j}|||S)a Create new QueryResult object, mapping the given function to its Hits. :param func: map function :type func: callable, accepts Hit, returns Hit Here is an example of using ``hit_map`` with a function that discards all HSPs in a Hit except for the first one:: >>> from Bio import SearchIO >>> qresult = next(SearchIO.parse('Blast/mirna.xml', 'blast-xml')) >>> print(qresult[:8]) Program: blastn (2.2.27+) Query: 33211 (61) mir_1 Target: refseq_rna Hits: ---- ----- ---------------------------------------------------------- # # HSP ID + description ---- ----- ---------------------------------------------------------- 0 1 gi|262205317|ref|NR_030195.1| Homo sapiens microRNA 52... 1 1 gi|301171311|ref|NR_035856.1| Pan troglodytes microRNA... 2 1 gi|270133242|ref|NR_032573.1| Macaca mulatta microRNA ... 3 2 gi|301171322|ref|NR_035857.1| Pan troglodytes microRNA... 4 1 gi|301171267|ref|NR_035851.1| Pan troglodytes microRNA... 5 2 gi|262205330|ref|NR_030198.1| Homo sapiens microRNA 52... 6 1 gi|262205302|ref|NR_030191.1| Homo sapiens microRNA 51... 7 1 gi|301171259|ref|NR_035850.1| Pan troglodytes microRNA... >>> top_hsp = lambda hit: hit[:1] >>> mapped_qresult = qresult.hit_map(top_hsp) >>> print(mapped_qresult[:8]) Program: blastn (2.2.27+) Query: 33211 (61) mir_1 Target: refseq_rna Hits: ---- ----- ---------------------------------------------------------- # # HSP ID + description ---- ----- ---------------------------------------------------------- 0 1 gi|262205317|ref|NR_030195.1| Homo sapiens microRNA 52... 1 1 gi|301171311|ref|NR_035856.1| Pan troglodytes microRNA... 2 1 gi|270133242|ref|NR_032573.1| Macaca mulatta microRNA ... 3 1 gi|301171322|ref|NR_035857.1| Pan troglodytes microRNA... 4 1 gi|301171267|ref|NR_035851.1| Pan troglodytes microRNA... 5 1 gi|262205330|ref|NR_030198.1| Homo sapiens microRNA 52... 6 1 gi|262205302|ref|NR_030191.1| Homo sapiens microRNA 51... 7 1 gi|301171259|ref|NR_035850.1| Pan troglodytes microRNA... cSsg|]}t|qSr rrhrr r r 6z'QueryResult.hit_map..Ncsg|]}|qSr r rhxrvr rry8rzrrMrrrNrur r}rhit_maps 0 zQueryResult.hit_mapcs>ddfdd|jDD}|||j|j}|||S)aCreate new QueryResult object whose HSP objects pass the filter function. ``hsp_filter`` is the same as ``hit_filter``, except that it filters directly on each HSP object in every Hit. If the filtering removes all HSP objects in a given Hit, the entire Hit will be discarded. This will result in the QueryResult having less Hit after filtering. cSg|]}|r|qSr r r{r r rryErzz*QueryResult.hsp_filter..c3|]}|VqdSrg)rtrxr}r rrjEz)QueryResult.hsp_filter..r~rur r}r hsp_filter=s zQueryResult.hsp_filtercsJddfddt|jddDD}|||j|j}|||S)zCreate new QueryResult object, mapping the given function to its HSPs. ``hsp_map`` is the same as ``hit_map``, except that it applies the given function to all HSP objects in every Hit, instead of the Hit objects. cSrr r r{r r rryPrzz'QueryResult.hsp_map..c3rrg)maprxr}r rrjPrz&QueryResult.hsp_map..N)r#rrMrrrNrur r}rhsp_mapJs* zQueryResult.hsp_maprKc Cst|tr|s tdt|j|}z|j|}|jddD] }|j|dq W|St yXz ||j|}WY|St yW||j urN|}nt |dYY|Sww)aoRemove the specified hit key and return the Hit object. :param hit_key: key of the Hit object to return :type hit_key: int or string :param default: return value if no Hit exists with the given key :type default: object By default, ``pop`` will remove and return the last Hit object in the QueryResult object. To remove specific Hit objects, you can use its integer index or hit key. >>> from Bio import SearchIO >>> qresult = next(SearchIO.parse('Blast/mirna.xml', 'blast-xml')) >>> len(qresult) 100 >>> for hit in qresult[:5]: ... print(hit.id) ... gi|262205317|ref|NR_030195.1| gi|301171311|ref|NR_035856.1| gi|270133242|ref|NR_032573.1| gi|301171322|ref|NR_035857.1| gi|301171267|ref|NR_035851.1| # remove the last hit >>> qresult.pop() Hit(id='gi|397513516|ref|XM_003827011.1|', query_id='33211', 1 hsps) # remove the first hit >>> qresult.pop(0) Hit(id='gi|262205317|ref|NR_030195.1|', query_id='33211', 1 hsps) # remove hit with the given ID >>> qresult.pop('gi|301171322|ref|NR_035857.1|') Hit(id='gi|301171322|ref|NR_035857.1|', query_id='33211', 2 hsps) zpop from empty listrN) r.rOrPr#r'r popr[rrQ_QueryResult__marker)rr0defaultrrar r rrZs, (    zQueryResult.popcCs^t|trt|j|jSz t|j|WSty.||jvr-||j|YSw)aReturn the index of a given hit key, zero-based. :param hit_key: hit ID :type hit_key: string This method is useful for finding out the integer index (usually correlated with search rank) of a given hit key. >>> from Bio import SearchIO >>> qresult = next(SearchIO.parse('Blast/mirna.xml', 'blast-xml')) >>> qresult.index('gi|301171259|ref|NR_035850.1|') 7 )r.rr#r'indexrrYrr/r r rrs   zQueryResult.indexFTcs|dur|rtjddd}ntjdd}ntj||d}|r1fdd|D_dS|jj}||S)a7Sort the Hit objects. :param key: sorting function :type key: callable, accepts Hit, returns key for sorting :param reverse: whether to reverse sorting results or no :type reverse: bool :param in_place: whether to do in-place sorting or no :type in_place: bool ``sort`` defaults to sorting in-place, to mimic Python's ``list.sort`` method. If you set the ``in_place`` argument to False, it will treat return a new, sorted QueryResult object and keep the initial one unsorted. NrK)rdreversecsi|]}||qSr )rrxrr r sz$QueryResult.sort..)r#rrnr rMrrrN)rrdrin_place sorted_hitsrRr rrsorts zQueryResult.sort)r NNrg)NFT)&__name__ __module__ __qualname____doc___NON_STICKY_ATTRSrr propertyrr'r(r*r,r-r1r3r5r6rJrUrbrfrrrArorprqrrwrrrobjectrrrrr r r rr sR!    0.     . 7 ?r cCrk)zeMap hit to its identifier (PRIVATE). Default hit key function for QueryResult.__init__ use. )r)rr r rrsr__main__) run_doctestN)rcopyr itertoolsrBio.SearchIO._utilsr_baserrrr rr Bio._utilsrr r r rs"     I