H&hx,ddlZddlZddlZddlZddlmZddlmZdZ dZ dZ dZ dZ d Zd Zd Zd Zd ZdZdZdZdZdZdZdZdZdZdZdZdZdZifdZ dZ!dZ"dZ#dZ$dNd Z%d!Z&d"Z'd#Z(d$Z)d%Z*d&Z+d'Z,d(Z-d)Z.d*Z/d+Z0d,Z1d-Z2d.Z3d/Z4d0Z5d1Z6d2Z7d3Z8d4Z9d5Z:d6Z;d7Zd:Z?d;Z@d<ZAd=d>iZBd?d@iZCdAZDdBZEdCZFdPdDZGdPdEZHdPdFZIdGZJdHZKdIZLdJZMdKZNdLZOePdMk(rddlQZQeQjyy)QN)etree)Refactorz8http://www.itis.gov/ITISWebService/services/ITISService/c ttdzidjd i|}ddi}|jd|}|Dcgc]}|jc}d}|Scc}w) z^ Ping the ITIS API Usage:: import pytaxize pytaxize.itis_ping() getDescriptiongetpayloadrequestax26z%http://itis_service.itis.usgs.gov/xsdz//ax26:description namespacesrr itis_basexmlxpathtext)kwargsttnsnodesxrs \/mounts/lovelace/software/anaconda3/envs/py312/lib/python3.12/site-packages/pytaxize/itis.py itis_pingr sk O)..E J N N XQW XB 8 9B HH)bH 9E! "qAFF "1 %D K #sAc ttdzd|idjd i|}|j}|djdj ddk(r"|djdj }|S|djdj}t |}|jd|djdj |d <|S) a5 Get accepted names from tsn :param tsn: taxonomic serial number (TSN) (character or numeric) Usage:: # TSN accepted - good name pytaxize.getacceptednamesfromtsn('208527') # TSN not accepted - input TSN is old name pytaxize.getacceptednamesfromtsn('504239') getAcceptedNamesFromTSNtsnrrrtrueauthor submittedTsnr)rrr getchildrenvaluesr _parse_nodespop)rrouttempdatrs rgetacceptednamesfromtsnr)s c(9885#,X] ^ b b lek lC ?? D AwQ&&(+v51g!!#A&++ J Q##%a(4465! "1g113A6;;N Jc ttdzd|idjdi|}t|j dj S)a Get any match count. :param x: text or taxonomic serial number (TSN) (character or numeric) :param **kwargs: Curl options passed on to `requests.get` Usage:: pytaxize.getanymatchcount(x=202385) pytaxize.getanymatchcount(x="dolphin") getAnyMatchCountsrchKeyrrrr)rrrintr"r)rrr&s rgetanymatchcountr/1sL ^(911Iq>SX Y ] ] g`f gC s #(( ))r*c ttdzd|idjd i|}ddi}gd}gd}t||||S) z Get comment detail from TSN :param tsn: TSN for a taxonomic group (numeric) :param **kwargs: Curl options passed on to `requests.get` Usage:: pytaxize.getcommentdetailfromtsn(tsn=180543) getCommentDetailFromTSNrrrax21*http://data.itis_service.itis.usgs.gov/xsd) commentDetail commentIdcommentTimeStamp commentator updateDate)commentcommidcommtimer7 updatedater)rrr _itisdict)rrr&rmatchescolnamess rgetcommentdetailfromtsnr@@sU c(9885#,X] ^ b b lek lC = >B\GIH S"gx 00r*c ttdzd|idjd i|}ddi}gd}gd}t||||}|d d =tDcgc]}t t ||c}Scc}w) z Get common names from tsn :param tsn: TSN for a taxonomic group (numeric) :param **kwargs: Curl options passed on to `requests.get` Usage:: pytaxize.getcommonnamesfromtsn(tsn=183833) getCommonNamesFromTSNrrrr2r3 commonNamelanguager)comnamelangrr)rrr _itisextractrdictzip)rrr&rr>r?reszs rgetcommonnamesfromtsnrOQs a(966 V[ \ ` ` jci jC = >B/G'H sB 2C Ar -. 0T#h" # 00 0sA/c zttdzd|idjdi|}ddi}gd}t|||S) z Get core metadata from tsn Usage:: # coverage and currrency data pytaxize.getcoremetadatafromtsn(tsn=28727) # no coverage or currrency data pytaxize.getcoremetadatafromtsn(tsn=183671) getCoreMetadataFromTSNrrrr2r3) credRatingrankId taxonCoverage taxonCurrencytaxonUsageRatingrrrrr _itis_parserrr&rtogets rgetcoremetadatafromtsnr[fsN b(977%W\ ] a a kdj kC = >B \E uc2 &&r*c ttdzd|idjdi|}gd}t|t|t |}|S)z Get coverge from tsn Usage:: # coverage data pytaxize.getcoveragefromtsn(tsn=28727) # no coverage data pytaxize.getcoveragefromtsn(526852) getCoverageFromTSNrrr)rSrTrrrrrr=ns21_tolowerrrr&r>dfs rgetcoveragefromtsnrcvsN ^(933eS\SX Y ] ] g`f gC0G 3gx'8 9B Ir*c ttdzd|idjdi|}ddg}t|t|t |}|S)z Get credibility rating from tsn Usage:: pytaxize.getcredibilityratingfromtsn(526852) pytaxize.getcredibilityratingfromtsn(28727) getCredibilityRatingFromTSNrrrrRrr^ras rgetcredibilityratingfromtsnrfsS g(9<B 2r B Ir*c tttdzd|idjdi|}t|t}|S)z Get full hierarchy from ts :param tsn: TSN for a taxonomic group (numeric) Usage:: pytaxize.getfullhierarchyfromtsn(tsn = 37906) pytaxize.getfullhierarchyfromtsn(tsn = 100800) getFullHierarchyFromTSNrrrr)rrr _parse_hierr_)rrrrbs rgetfullhierarchyfromtsnrs@ b)77%W\ ] a a kdj kB R B Ir*c tt|z|djdi|gd}fd}|Dcgc] }|| c}Scc}w)Nrr)acceptedNameList commentListcommonNameListcompletenessRating coreMetadatacredibilityRatingcurrencyRatingdateData expertListgeographicDivisionList hierarchyUpjurisdictionalOriginListkingdomotherSourceList parentTSNpublicationListscientificName synonymListtaxRank taxonAuthorunacceptReasonusagecpjd|ztdj}t|S)N//ax21:r r)rr_r" _get_text)rchr&s rparsedatz_fullrecord..parsedats1 YYy{tY 4Q 7 C C E}r*r)rrr)verbargsrrZrrr&s @r _fullrecordrsM E(9t#T5 A E E O OC OE "' 'AHQK '' 'sAc tdd|ifi|S)a6 Returns the full ITIS record for the TSN in the LSID, found by comparing the TSN in the search key to the TSN field. Returns an empty result set if there is no match or the TSN is invalid. :param lsid: lsid for a taxonomic group (character) :param **kwargs: Curl options passed on to `requests.get` Usage:: pytaxize.getfullrecordfromlsid("urn:lsid:itis.gov:itis_tsn:180543") pytaxize.getfullrecordfromlsid("urn:lsid:itis.gov:itis_tsn:37906") pytaxize.getfullrecordfromlsid("urn:lsid:itis.gov:itis_tsn:100800") getFullRecordFromLSIDlsidr)rrs rgetfullrecordfromlsidrs . I& IIr*c tdd|ifi|S)aC Returns the full ITIS record for a TSN :param tsn: tsn for a taxonomic group (character) :param **kwargs: Curl options passed on to `requests.get` Usage:: pytaxize.getfullrecordfromtsn("504239") pytaxize.getfullrecordfromtsn("202385") pytaxize.getfullrecordfromtsn("183833") getFullRecordFromTSNrr)rrs rgetfullrecordfromtsnrs -s| Fv FFr*c zttdzd|idjdi|}ddg}t||tS)zp Get geographic divisions from tsn Usage:: pytaxize.getgeographicdivisionsfromtsn(180543) getGeographicDivisionsFromTSNrrrgeographicValuer8rryrzs rgetgeographicdivisionsfromtsnrsI i(9>>PS ^c d h h rkq rC | ,E uc4 ((r*c ttdzidjdi|}ddi}|jd|}|Dcgc]}|jc}Scc}w) z Get all possible geographic values :param **kwargs: Curl options passed on to `requests.get` Usage:: pytaxize.getgeographicvalues() getGeographicValuesrrr2.http://metadata.itis_service.itis.usgs.gov/xsdz//ax21:geographicValuesr rr)rr&rrrs rgetgeographicvaluesr#s` U(944b% P T T ^W] ^C A BB II/BI ?E! "qAFF "" "rkc zttdzd|idjdi|}gd}t||tS)z} Get global species completeness from tsn Usage:: pytaxize.getglobalspeciescompletenessfromtsn(180541) #getGlobalSpeciesCompletenessFromTSNrrr) completenessrSrrryrzs r#getglobalspeciescompletenessfromtsnr2sD o(9DDuVYldi j n n xqw xC +E uc4 ((r*c tttdzd|idjdi|}ddi}t||}|S)z Get hierarchy down from tsn :param tsn: TSN for a taxonomic group (numeric) Usage:: pytaxize.gethierarchydownfromtsn(tsn = 161030) getHierarchyDownFromTSNrrrr2r3r)rrrrrs rgethierarchydownfromtsnr?sK b)77%W\ ] a a kdj kB = >B R B Ir*c tttdzd|idjdi|}ddi}t||}|S)z Get hierarchy up from tsn :param tsn: TSN for a taxonomic group (numeric) Usage:: pytaxize.gethierarchyupfromtsn(tsn = 36485) pytaxize.gethierarchyupfromtsn(tsn = 37906) getHierarchyUpFromTSNrrrr2r3rr~rs rgethierarchyupfromtsnrNsK `)55s|UZ [ _ _ ibh iB = >B 2r B Ir*c tt|z|djdi|}|jdt}|Dcgc]}|j }}|Dcgc]}|Dcgc] }t |c}}}}g} |D]/}|Dcgc]}t|jd } }t| D cgc]} | j| dkDs| c} } t| dkDr| D]} dj|Dcgc]>}t|jd| k(s#t|jd@c}}| |i}|D cgc]#} t| jd| vs"| %}} |j|| j| j|2tj | D cgc]/}|D cic]}|j#D]\}} ||  c} }}1c} }}}}||dDcgc]}t|jd c}Scc}wcc}wcc}}wcc}wcc} wcc}wcc} wcc} }}wcc} }}}wcc}w) zI Get itis term Usage:: pytaxize._itisterms("buya") rrz//ax21:itisTermsr rr,r)rrrrr_r"_get_text_singlelistkeyssetcountlenjoinr#appendpd DataFrameitems)endptrrr&rrnodes2yallnodesoutputkyzvnotuniqrNmrtoadduuRdkrbs r _itistermsr^s G(9u$dE B F F P PC II(TI :E', -!ammo -F -:@AQa0!!$0AHA F  *+,QtAFFH~a ,,#:Q1)9q:; w \U[ \\r*ct|}g}|dk(r8tt|D]}|jt ||!|S|dk(r8tt|D]}|jt ||!|Stt|D]}|jt ||!|S)a Get hierarchies from TSN values, full, upstream only, or immediate downstream only. Uses the ITIS database. :param tsn: One or more TSN's (taxonomic serial number) :param what: One of full (full hierarchy), up (immediate upstream), or down (immediate downstream) Details Note that `pytaxize.itis_downstream` gets taxa downstream to a particular rank, whilc this function only gets immediate names downstream. Usage:: # Get full hierarchy pytaxize.itis_hierarchy(tsn=180543) # Get hierarchy upstream pytaxize.itis_hierarchy(tsn=180543, "up") # Get hierarchy downstream pytaxize.itis_hierarchy(tsn=180543, "down") # Many tsn's pytaxize.itis_hierarchy(tsn=[180543,41074,36616]) fullup) convertsinglerangerrrrr)rwhattsn2r'is ritis_hierarchyrs4  D D v~s4y! :A KK/Q8 9 : K s4y! 8A KK-d1g6 7 8 Ks4y! :A KK/Q8 9 : Kr*c zttdzd|idjdi|}ddi}gd}t|||S) zr Get jurisdictional origin from tsn Usage:: pytaxize.getjurisdictionaloriginfromtsn(180543) getJurisdictionalOriginFromTSNrrrr2r3)jurisdictionValueoriginr8rrWrYs rgetjurisdictionaloriginfromtsnrsO i)>>PS ^c d h h rkq rC = >B 7E uc2 &&r*c zttdzidjdi|}ddi}ddg}t||||dS) ze Get jurisdiction origin values Usage:: pytaxize.getjurisdictionoriginvalues() getJurisdictionalOriginValuesrrax23r jurisdictionrr)rrr_itisdfrr&rr>s rgetjurisdictionoriginvaluesrsS ^)==rSX Y ] ] g`f gC A BBh'G 3GWf 55r*c ttdzidjdi|}|jdjDcgc]}|j}}t j |dgScc}w)za Get possible jurisdiction values Usage:: pytaxize.getjurisdictionvalues() getJurisdictionValuesrrrjurisdictionValuescolumnsr)rrrr"rrr)rr&rrs rgetjurisdictionvaluesrsq V)55r5 Q U U _X^ _C __.q1==? AQVV AD A <<)=(> ?? Bs A6c tdd|ifi|}ttdzd|idjdi|}ddi}gd}t |||S) za Get kingdom names from tsn Usage:: pytaxize.getkingdomnamefromtsn(202385) getKingdomNameFromTSNrrrr2r3 kingdomId kingdomNamerr)_itisGETrrrrXrYs rgetkingdomnamefromtsnrsc *UCL CF CC ^)55c{TY Z ^ ^ hag hC = >B -E uc2 &&r*c ttdzidjdi|}ddi}gd}t|||t |dS)zY Get all possible kingdom names Usage:: pytaxize.getkingdomnames() getKingdomNamesrrrrr r)rrrrr`rs rgetkingdomnamesrsR P)//U K O O YRX YC A BB/G 3GXg%6 ??r*c ttdzidjd i|}ddi}|jd|}|dj}t j |jdd }|S) zr Provides the date the ITIS database was last updated. Usage:: pytaxize.getlastchangedate() getLastChangeDaterrrrz//ax23:updateDater rz%Y-%m-%dr)rrrrrtimestrptimer)rr&rrbbdts rgetlastchangedater st R)112u M Q Q [TZ [C A BB II)bI 9E qB rxxz!}j 1B Ir*c tdd|ifi|}ttdzd|idjdi|}|j dj }|d}|S |S)z Gets the unique LSID for the TSN, or an empty result if there is no match. Usage:: # valid TSN pytaxize.getlsidfromtsn(155166) # invalid TSN, returns nothing pytaxize.getlsidfromtsn(0) getLSIDFromTSNrrrrno matchr)rrrrr"r)rrr&rs rgetlsidfromtsnrsu #eS\ s r getranknamesr>TsE M)n,b% H L L Vv VC1G 3gx'8& AAr*c zttdzd|idjdi|}gd}t||tS)a$ Gets the partial ITIS record for the TSN in the LSID, found by comparing the TSN in the search key to the TSN field. Returns an empty result set if there is no match or the TSN is invalid. Usage:: pytaxize.getrecordfromlsid("urn:lsid:itis.gov:itis_tsn:180543") getRecordFromLSIDrrr) authorship genusPartinfragenericEpithetinfraspecificEpithetr nameCompletenomenclaturalCoderank rankStringspecificEpithet uninomialrrry)rrr&rZs rgetrecordfromlsidrKasH ^)11FD>SX Y ] ] g`f gC EE uc4 ((r*c zttdzd|idjdi|}gd}t||tS)zj Returns the review year for the TSN. Usage:: pytaxize.getreviewyearfromtsn(180541) getReviewYearFromTSNrrr)rS reviewYearrrryrzs rgetreviewyearfromtsnrOqsC _)44uclTY Z ^ ^ hag hC )E uc4 ((r*c zttdzd|idjdi|}gd}t||tS)z Returns the scientific name for the TSN. Also returns the component parts (names and indicators) of the scientific name. Usage:: pytaxize.getscientificnamefromtsn(531894) getScientificNameFromTSNrrr) combinedNameunitInd1unitInd3 unitName1 unitName2 unitName3rrryrzs rgetscientificnamefromtsnrX}sE c)885#,X] ^ b b lek lC E uc4 ((r*c zttdzd|idjdi|}gd}t||tS)zv Returns the author information for the TSN. Usage:: pytaxize.gettaxonauthorshipfromtsn(183671) getTaxonAuthorshipFromTSNrrr)rAr8rrryrzs rgettaxonauthorshipfromtsnr[sC d)99E3s rgettsnbyvernacularlanguagerbsL o)::ZQYDZdi j n n xqw xC-G 3gx'8 99r*c ttdzd|idjdi|}|jdj}|d}|S |S)z Gets the TSN corresponding to the LSID, or an empty result if there is no match. Usage:: pytaxize.gettsnfromlsid(lsid="urn:lsid:itis.gov:itis_tsn:28726") pytaxize.gettsnfromlsid("urn:lsid:itis.gov:itis_tsn:0") getTSNFromLSIDrrrrrr)rrrr"r)rrr&rs rgettsnfromlsidresa [)..PU V Z Z d]c dC  1  " "B z  I Ir*c zttdzd|idjdi|}ddg}t||tS)z Returns the unacceptability reason, if any, for the TSN. Usage:: pytaxize.getunacceptabilityreasonfromtsn(183671) getUnacceptabilityReasonFromTSNrrrrrryrzs rgetunacceptabilityreasonfromtsnrhsJ j)??%QT_d e i i slr sC # $E uc4 ((r*c ttdzidjdi|}dg}t|t|t |dS)z Provides a list of the unique languages used in the vernacular table. Usage:: pytaxize.getvernacularlanguages() getVernacularLanguagesrr languageNamesrrr<r=s rgetvernacularlanguagesrlsJ W)66E R V V `Y_ `CG 3gx'8& AAr*c ttdzd|idjd i|}gd}|jdt}t |dt|t |S) z Search for tsn by common name Usage:: pytaxize.searchbycommonname(x="american bullfrog") pytaxize.searchbycommonname("ferret-badger") pytaxize.searchbycommonname("polar bear") searchByCommonNamer-rrrC//ax21:commonNamesr rrrrrrr_rr`rrr&r>tmps rsearchbycommonnamerssa ^)22YqMSX Y ] ] g`f gC-G ))(T) :C 3q64(7*; <s rsearchbyscientificnamer'sO b)661 W\ ] a a kdj kCe$G 3gx'8 99r*c ttdzd|idjdi|}|jdj}g}|D]}|j}|D]q}|j t t |jDcgc] }t|c}|jDcgc]}|jc}s|Scc}wcc}w)z Search for any match Usage:: pytaxize.searchforanymatch(x=202385) pytaxize.searchforanymatch(x="dolphin") searchForAnyMatchr-rrrr rrrr"rrKrLitergettagr)rrr&rrrrwes rsearchforanymatchr4s ])11Ia=RW X \ \ f_e fC // A  * * ,C F `mmo `A MM$sqvvx#@!F1I#@STSYSYS[B\a166B\]^ _ `` M$AB\s C2Cc ||||d}ttdz|djdi|}|jdj}g}|D]} | j}|D]q} |j t t | jD cgc] } t| c} | jD cgc]} | jc} s|Scc} wcc} w)z Search for any matched page for descending (logical) Usage:: pytaxize.searchforanymatchpaged(x=202385, pagesize=100, pagenum=1, ascend=False) pytaxize.searchforanymatchpaged("Zy", pagesize=100, pagenum=1, ascend=False) )r-pageSizepageNumascendsearchForAnyMatchPagedrrrrr) rpagesizepagenumrrrr&rrrrrrs rsearchforanymatchpagedrGsH& QD X)66e T X X b[a bC // A  * * ,C F `mmo `A MM$sqvvx#@!F1I#@STSYSYS[B\a166B\]^ _ `` M$AB\s C7C$c>|jjdk(r|gS|S)Nr.) __class____name__)rs rrr[s {{u$s r*r2r3rrc|jd|}|Dcgc]}|j}}|Dcgc] }|jjdd"}}t t ||g}|Scc}wcc}w)Nz//ax21:*r rr)rrrrrKrL)objrrrrrrbs rrresp IIjRI 0E! "qAFF "D "). /AAEEKK Q  /D / s4  B I # /s A0%A5c|Dcgc]}|j}}|Dcgc] }|jjdd"}}tt ||Scc}wcc}wrr)rrrrs rr$r$lsW qAFF D ), -AAEEKK Q  -D - D$   ! - A%Ac |jd|}g}tt|D]C}|jt t gd||Dcgc]}|j c}E|Scc}w)Nz//ax21:hierarchyListr )rr parentNamer(r; taxonName)rrrrrKrLr)rrrrrrs rrrqss II,I }|j||} |j| Dcgc]}|jc}@t dk(rt j dt|dt|dk(s |ddd|d<t jtt|||ddd} | Scc}wcc}w)N//%s:r r Please enter a valid search namerIrr) rrrrsysexitrrrrL) abr>r?pastensprefixrrrrrbs rrrxs w F!()Avax)G) F /a( u-!qvv-./ 5zQ 34 q sF2J0 0BZ^r d3<(( d|z}|Dcgc]}||z }}g}|D]>}|j||} |j| Dcgc]}|jc}@t dk(rt j dt t||Scc}wcc}w)Nrr rr)rrrrrrrKrL rrr>r?rrrrrrs rr=r=s w F!()Avax)G) F /a( u-!qvv-./ 5zQ 34 Hf% &&*.s BB cd|z}|Dcgc]}||z }}g}|D]>}|j||} |j| Dcgc]}|jc}@|Scc}wcc}w)Nrr )rrrrs rrJrJsu w F!()Avax)G) F /a( u-!qvv-./ M *.s AA$ ct|Dcgc]}t|dk(c}r*tjt t ||}|Stjt t ||g}|Scc}w)NrH)allrrrrKrL)rr?rrbs r _array2dfrsg s #!CFAI #$ \\$s8S12 3 I\\4Hc 234 5 I $sA;c|d}|Dcgc] }||||}}ttt||Scc}w)Ncl|jd|z|}|Dcgc]}|jc}Scc}wNrr rrrrnsprrs r xpathfuncz_itis_parse..xpathfunc0ggikcg2 #$1$$$1)rKrLr`rrrrrrs rrXrXs@%)* *1IaA  *D * HQK& '' +s9cjd}|Dcgc] }||||}}tt||Scc}w)Ncl|jd|z|}|Dcgc]}|jc}Scc}wrrrs rrz$_itis_parse_2dict..xpathfuncrr)rKrLrs rr$r$s;%)* *1IaA  *D * At  +s0c|Dcgc]}|j}}|Dcgc] }|jjdd"}}tt ||Scc}wcc}wrr)rrrrs rrrsW qAFF D )* +AAEEKK Q  +D + D$    +rcH|Dcgc]}|jc}Scc}w)N)lower)rrs rr`r`s !!AGGI !! !sc>|jjddSr)rr)rs rrrs 55;;s A r*__main__)Nr)r{)r2)Srrrequestspandasrlxmlrpytaxize.refactorrrrr)r/r@rOr[rcrfrjrnrrr{rrrrrrrrrrrrrrrrrrrrrrrr%r)r8r>rKrOrXr[r^rbrerhrlrsrvryr}rrrrr_rirr$rrr=rJrrXr$rr`rrdoctesttestmodrr*rrs & F  0 *1"1*'   #   )   (J" G ) # )  <>! Y K ]%N ' 6 @ ' @ ( / ) ) B) ) )J ) ) :" ) B = = = 7 :&( ;<?@!  '(! " zGOOr*