From 39b47a32bfab2413f18d834331b5bc77fc6013f6 Mon Sep 17 00:00:00 2001 From: Eric Coissac Date: Fri, 27 Jan 2023 10:49:28 +0100 Subject: [PATCH] Complement on the doc --- doc/_book/annexes.html | 2 +- doc/_book/commands.html | 122 +++++++++++++++-- .../figure-html/unnamed-chunk-1-1.png | Bin 0 -> 62529 bytes doc/_book/index.html | 29 +++- doc/_book/intro.html | 4 +- doc/_book/library.html | 76 ++++++++++- doc/_book/references.html | 13 +- doc/book.bib | 70 ++++++++++ doc/commands.qmd | 127 +++++++++++++++++- doc/index.qmd | 4 + doc/library.qmd | 65 ++++++++- pkg/obialign/dnamatrix.go | 2 +- 12 files changed, 485 insertions(+), 29 deletions(-) create mode 100644 doc/_book/commands_files/figure-html/unnamed-chunk-1-1.png diff --git a/doc/_book/annexes.html b/doc/_book/annexes.html index 426c191..8d6e915 100644 --- a/doc/_book/annexes.html +++ b/doc/_book/annexes.html @@ -105,7 +105,7 @@ ul.task-list li input[type="checkbox"] {
  • - 2  The OBITools commands + 2  The OBITools V4 commands
  • diff --git a/doc/_book/commands.html b/doc/_book/commands.html index 7bb097d..7bd123a 100644 --- a/doc/_book/commands.html +++ b/doc/_book/commands.html @@ -7,7 +7,7 @@ -OBITools V4 - 2  The OBITools commands +OBITools V4 - 2  The OBITools V4 commands @@ -61,6 +80,7 @@ ul.task-list li input[type="checkbox"] { } } + @@ -70,7 +90,7 @@ ul.task-list li input[type="checkbox"] {
  • - 2  The OBITools commands + 2  The OBITools V4 commands
  • @@ -164,7 +184,7 @@ ul.task-list li input[type="checkbox"] {
    -

    2  The OBITools commands

    +

    2  The OBITools V4 commands

    @@ -296,20 +316,93 @@ ul.task-list li input[type="checkbox"] {

    Replace the illuminapairedends original OBITools

    -
    -

    2.7.1.1 obimultiplex

    +
    +

    2.7.1.1 Alignment procedure

    +

    obipairing is introducing a new alignment algorithm compared to the illuminapairedend command of the OBITools V2. Nethertheless this new algorithm has been design to produce the same results than the previous, except in very few cases.

    +

    The new algorithm is a two-step procedure. First, a FASTN-type algorithm (Lipman and Pearson 1985) identifies the best offset between the two matched readings. This identifies the region of overlap.

    +

    In the second step, the matching regions of the two reads are extracted along with a flanking sequence of \(\Delta\) base pairs. The two subsequences are then aligned using a “one side free end-gap” dynamic programming algorithm. This latter step is only called if at least one mismatch is detected by the FASTP step.

    +

    Unless the similarity between the two reads at their overlap region is very low, the addition of the flanking regions in the second step of the alignment ensures the same alignment as if the dynamic programming alignment was performed on the full reads.

    +
    +
    +

    2.7.1.2 The scoring system

    +

    In the dynamic programming step, the match and mismatch scores take into account the quality scores of the two aligned nucleotides. By taking these into account, the probability of a true match can be calculated for each aligned base pair.

    +

    If we consider a nucleotide read with a quality score \(Q\), the probability of misreading this base (\(P_E\)) is : \[ +P_E = 10^{-\frac{Q}{10}} +\]

    +

    Thus, when a given nucleotide \(X\) is observed with the quality score \(Q\). The probability that \(X\) is really an \(X\) is :

    +

    \[ +P(X=X) = 1 - P_E +\]

    +

    Otherwise, \(X\) is actually one of the three other possible nucleotides (\(X_{E1}\), \(X_{E2}\) or \(X_{E3}\)). If we suppose that the three reading error have the same probability :

    +

    \[ +P(X=X_{E1}) = P(X=X_{E3}) = P(X=X_{E3}) = \frac{P_E}{3} +\]

    +

    At each position in an alignment where the two nucleotides \(X_1\) and \(X_2\) face each other (not a gapped position), the probability of a true match varies depending on whether \(X_1=X_2\), an observed match, or \(X_1 \neq X_2\), an observed mismatch.

    +

    Probability of a true match when \(X_1=X_2\)

    +

    That probability can be divided in two parts. First \(X_1\) and \(X_2\) have been correctly read. The corresponding probability is :

    +

    \[ +\begin{aligned} +P_{TM} &= (1- PE_1)(1-PE_2)\\ + &=(1 - 10^{-\frac{Q_1}{10} } )(1 - 10^{-\frac{Q_2}{10}} ) +\end{aligned} +\]

    +

    Secondly, a match can occure if the true nucleotides read as \(X_1\) and \(X_2\) are not \(X_1\) and \(X_2\) but identical.

    +

    \[ +\begin{aligned} +P(X_1==X_{E1}) \cap P(X_2==X_{E1}) &= \frac{P_{E1} P_{E2}}{9} \\ +P(X_1==X_{Ex}) \cap P(X_2==X_{Ex}) & = \frac{P_{E1} P_{E2}}{3} +\end{aligned} +\]

    +

    The probability of a true match between \(X_1\) and \(X_2\) when \(X_1 = X_2\) an observed match :

    +

    \[ +\begin{aligned} +P(MATCH | X_1 = X_2) = (1- PE_1)(1-PE_2) + \frac{P_{E1} P_{E2}}{3} +\end{aligned} +\]

    +

    Probability of a true match when \(X_1 \neq X_2\)

    +

    That probability can be divided in three parts.

    +
      +
    1. \(X_1\) has been correctly read and \(X_2\) is a sequencing error and is actually equal to \(X_1\). \[ +P_a = (1-P_{E1})\frac{P_{E2}}{3} +\]
      2. +
    2. \(X_2\) has been correctly read and \(X_1\) is a sequencing error and is actually equal to \(X_2\). \[ +P_b = (1-P_{E2})\frac{P_{E1}}{3} +\]
      3. +
    3. \(X_1\) and \(X_2\) corresponds to sequencing error but are actually the same base \(X_{Ex}\) \[ +P_c = 2\frac{P_{E1} P_{E2}}{9} +\]
      4. +
    +

    Consequently : \[ +\begin{aligned} +P(MATCH | X_1 \neq X_2) = (1-P_{E1})\frac{P_{E2}}{3} + (1-P_{E2})\frac{P_{E1}}{3} + 2\frac{P_{E1} P_{E2}}{9} +\end{aligned} +\]

    +

    Probability of a match under the random model

    +
    +
    +
    +
    +

    +

    Evolution of the match and mismatch scores when the quality of base is 20 while the second range from 10 to 40.

    +
    +
    +
    +
    +
    +
    +

    2.7.1.3 obimultiplex

    Replace the ngsfilter original OBITools

    -
    -

    2.7.1.2 obicomplement

    +
    +

    2.7.1.4 obicomplement

    -
    -

    2.7.1.3 obiclean

    +
    +

    2.7.1.5 obiclean

    -
    -

    2.7.1.4 obiuniq

    +
    +

    2.7.1.6 obiuniq

    @@ -333,6 +426,11 @@ ul.task-list li input[type="checkbox"] { +
    diff --git a/doc/_book/commands_files/figure-html/unnamed-chunk-1-1.png b/doc/_book/commands_files/figure-html/unnamed-chunk-1-1.png new file mode 100644 index 0000000000000000000000000000000000000000..872555ee7b7a417ffa6f8892ee1eba7fcf69c564 GIT binary patch literal 62529 zcmeFaXINBQvo+eZpeQ1s1OW+(ie!-_xfKy53z7vCBqzz4hK(5k70J+`B*~IUUs@8s^sw_u-is2Lt1|z?J z?~WP_MuLFBj#ZN$2Ul>Wo&7Kv@fiyl8C5G8IT<@^I|ub=PmE3EOl(aYER5CUZo^1Cu`IYX}!F;0H38d$=z z){pdV7Hu7xEo7<65xpLM(U)tP^K{6u`93 zqbOE#F_9l`yf&2OzLxgxpmy-}i5a#{UE&jtD}zB2LSHjEE;Y&i6i$y)X6vl*-$fS6 z4qMd@`l|%zUH7IQJyyIK&gl>~{)#eAug?&ygJH5lM;)Qt86g+vho)Wr>E zjWs;WFU&fnrirvybER}eno*AWyE)fLG}bTQ*(=~Tj5+1(qZV^|nt~ZNHo?jB&0~v= z`J0jj=j*0GEpuV?+UxD&X+UmC=mc51lpytjdO(Ta^Eo%kq9N5=5(3ZG`d>g@)kRsnk=rD35HGI(OBL1{3g zktnVzj$ukQge7F@kyI^BMBqsw|*(CGN+udV} zqu)7p4q!zOEe{$NX4|jdPCjH?X-oT#HP>J(Kkeggp6=Xs()1Zy7yo^}`yc(cFI)=w zb)EiV0_#WipXyKFJ#810KO=+=yX5$Ey`;U%orp~>P9&f_VAl0k{ejujh_QT3oqU`K zWgn&wW7QbiYil6pZL1Yfc2_g5tjBTA>9QGvC680XKv%2-=J31WOz$_t84=yn2Pb@v zAr}TUi-Z;gn>9~)m)hyo%B@Q(Kb1=2(Xf7!m+(bLND~idX@Yr|xRsHb9oO6Ywe?f_ zqt(x?k1SV_lOw;R##?v*@=6*#7BJNcaLzBK)%7dB-c&zClmU3?TI2eSR@9apU-NQ}G;y#%GGrN2M( zrymWde6YCM1^4B_T)1K;pS7Y zZ=N@9ez&`SuunJWo@C+}cl_oayZDxFp(w>z#<8|t^Cn?mv&jl9EJG^UZBxySz1C6IKkJXFrrr$FkBg*4A-xhJY%?dHZu8mXL+0XZZaAETs3M;9%XgYj>G7dcX}u%|+_uGIa5uhx z3~ESf2b>y?V^%!q7HU$yACA9XtN=WgW8N%v7vv(}iM znDG3a&E}Yw(_uXQq?D`(UlZ*xtQyp|Kr|& z{~}y9j?iV|;~Bm%r|L7AWNiOh|9?C^0yZx|;IePEFAb&dnZD1?PY69TDZ=|Wp&LK{ z4GwQ363^#-_vh|HpF#8$L+CR6m}b0vwSkT-ul43)zr|EzD9xOWd|+Up#rNkYb&zy? z1~Jnu(OQv}3+4sHSCwNTCIku}*ZgDY{K$@r?Yc!rVn%jTIG>8+OlziMm2e6l{U zNo;Q-fKM}h(nF8lZ*>x#a#7~x(|zyFelxC4JEqLA>e=>$&Xw^W>U+yZY^u+z`*Mu) zFxvT&z*6#!>fT;bR=*eRe}Y1JwJabI=I1~bL8QC9+AjX@7V{tb=5dh~wnT!GIZ5Ee zt`+&h@`ol9TnTL=?luB8Kqm3(?Eg59f7yzvEfJA<30e+IXqRVSfK}<-&RijIaPdRn z1RR2cN2my_+C~Oes==7(Cj#dOc83(vBq`+~ zM`%?(;5QZ3j@JlT<`gZZZo2Bf42Prn&eLR;R*!wTcs+MZ=1v}y$-)V|@B zxtOn{)MAmDq_CSn)~a&?&h_d{OO`{XNz?q8rM?l8l$%AEJM%)c@lGe;j-K ztKZk>Td$1e_nbu<^!#|Xg%%PfXZjeHRpi64xh%6giEF*@i(mrou<-c3{v{%~D7+~w z`Qp}4?8^}kM+V$?GSN^P3TnSXs;&2a4iB;toZu~oiytuBb1zM+oxY|{$xmjaN<*EDSc^)({MJ-4GHA=CXIr5o?3~>t zXdhcxR>ABGpF{^^vMlS~(pZd?yB}LQrLRU$T>p+f#M$^@Z^vXdNa{4gFUJ_2Twkws zATRB@JVfO7f;aUvoK5bX;*TDNFoS0)iu5my5t~nNv+Wj{{8khVR*nydNk7Q|hYqrD zBZCvar8T!z_CFMpB(EsBvb~3X=VE4MYkrTbXejN<_KxKtZY*RJ3H`mr0Jdc<@Fq^}8K;s(841J z8=curFk6pu_RpkF`B@xljnVvpo7W$cT!#JT6@K`$=l5nuby3)zS6zK;6-zxsYo=4v zdgW_g7>?*7p0%hyu=?vU@cc}ta}_RwMRYZ>wq9cg*0NhQ7|Gt{8_{~EZoH#U(D~(4 zJ1C`vjKQpC#(%dYM7$3O5E}wLS)Zz_soZv^1aZNxi5H8CBt{*_|8eQ<7Ib*3TRFJQ zgV`RE6bfb-Ca}T*w1UWVRs_O?gkiebB67*yk--5woch^h(`?XY>iHXsovsR9Q}5+Z zYEARY!hhU>F9Nuh_Zd>kYZcXF$mRxGVFrnPzSPe$c3Re@{al!>A)}^G3}Rs}Ul)1) z*f&*I5Ee@r9q1I}8Q?8B|LhLCCQ((D@RIvX&$-0fGE3ad>^mU0=tp^`B>xNnonkR3#@t4jIMl2cz8h!`c~exo-O&a315Z$phyrtM; zT%XUe`tgr*U~MY_q`;BR(~&rejz`{N{JY?_6qFI%`(hhzpf}mXGau~eOsqPCSO#BI z*YQ6egdIGH82xNzW%J9hNH>exhOVKZu3japV8qq7>t9WlXMSyTObm~F(zGscmiMn+ zl4AJNiZQ^7B}E+X1XQn_Q@&gJg|{yo8eWAcAZ^#9HW+uDY5yU|Hu>zv`d`cW^>FzL3oI=834eEBk?RxX8% zwd^G2*XO=*CZXrA#$HCmGs1mP&d2W4z=`GgRJ-F$n!nWb_N%L3y~l}J z?1Evro4s!C)B8x*guxjWL333GNe?GYbk|xp4hW@IOvnTJI{Zq>_9evw!6STfKT~x*VhLYD`PeNC#NxShC^@iAN9hi zmTMCONyuos{^KXMSH?5X`A=X?R=4uftoixx!E{60J1`y~BidY_MOV>gJ}SwL^K9Sm z6cH9KJRaX}SJmb`s@#G)Sd<(`3BpDH=T3V?7S<9@r5&|ZH9LQa0J zOv)soMSqhP|WV16!xdpiTJZu-0RW|XKt3z}qCZwA|$nv3Xp|wsawsN<_BwRnNay8H{k;!$4KZT@@P^y9p z_thKIVmoY;p-6JXNQ#g%i3xgdq#G*rK5|qlT`pbdK<=TDiFE;VDd$uq_$9Z79Mdgs zQT++c(4Oyeu)_2M4}y_zd$yWY6Hk$1f?TjNUjM;9+wfHF441HU6JAY2&xT}zN~xe_CgbY3 zry*IF&xsZK1uLDUZemNMLH(|_f5K*Ddgv}loBc*W3SCC&wKEl-_pzHK-njnV&-t!- zm!7T+oxBdT)MifW+g$Iey(zv<{6hAqiF+j31Rvty?89lQG@sFz6fCHTrn~X?{I?HW6b9|lDymB2?GIM zyP9W3ABJvj>6;MV$|`)2aMwguA&h%2?d?86J4*1SkJldyz94#oO9vProse4Ez5-_6 z^j3Y90h41hzkVTAQ5D~#;%`lBxiqzzCkym8!}$zHEL97A=2bRGCLC$W-eoQy*326w zam}ju4M-aa2?-?)NPBFUA!9rrpUNoc(d~b+gYNJXtu!f4D^~yFl5QS)psaIT+cM!FXOiz>(TK3V*i8Ht=#Qh9gV`-h4~wPX^&p{oIO7av;f|_ZhPCS zIzRVz*2}(r$elsneZs@NlwmY<)#3X|b|=kGOVN^^E>`0Dnw$@A?bW5w`rf@sgFzHf zUAxWd^EqIp(=3Bj-{vKP2c}=*kc5d0zVigWI%8_>6Gn6Q(H1$HZ@2)~HIuO{edYyG zt-k%L=sG>uyW(ZWAdD6dEKshw4jZM>{{>rsp43Rf;P1yXlMKN}>%R8F+q(BJ8j{JO z0~vc|xm*ZoHEnUw{o~j{>qThoDXe|ED|#s@+(4eMeC76Az3(ZCksUdGo`l>(o)z>) z7*SqTLB$jfIW#Tq!~jQS(Molm3=~N&wz)CiWqZ;v=_3=t(@h6$D?)p67wqq7dW^rI zEA$*uk|0n^bOC;ynM@)}@b^-DW#4NiRBerTreqcla4G@cREienS<1sm_5X;l zD;|G|+grz^NN)DAEtO#_|Ig6klQF%yWQP=w1-&D4B2_y|rN2HZV+c)9 z(ln`{uy8U@Vc(bN0u6#)8K(hyaQ?V9dyLQ;FF>J#>`6Dl&I=RJBN6t58s|sowr>Lk z>cuxpg1sI$z@kmpPvQSes3CAeTm)uvTU&@=cL_aM)Z{#gHvxSS5l;!g_hJSE!G4z0 zV9^`z{*fXCpQ^8cAV#SfNT7Das(KtON`Lnj3n93_b_XbMr0IWFqkeDWHGi<^>4bO+ zLdHdX33Q%3*GM4ry-&BmqAwq`ogm~1r>H=Q{d?L2Lf>lyUc&SD82=vQUvE5uD}TN5 zFR1cGL`6smO+eBdZ5X&eUJM>y41c z#>SSrd6~w;xfR)JhFWGtPk(-N>Ng2bVmVlOH5aC5tCKYU?a7ahS5mmoPV=cL$>hR) zk3-k`>~ZaKDFM8t*8&-YIC-?c#dnIioSo(K1A{l2Rm#id96b7^f^`&U8UM&xReAjU zR>b$&f+aqlk;Jv(R(?>-Oi%!2FxGRqWUkLRSU<@Y2pKvFWOTfbAT@5EQ0vWBH9CQMQn-kmXvDF7$24G}@*E=oEALKhB6J1_}>c8$2wk z+UM~;+#OYc^j1hM6+76T%+s3;28!ivMIrfkQjo4vrAe9#_^)k~vu;_u5Xwg>jW$}RZz@tVZXq5x7;c`iZaK{q$~R`F zQ~80R;v6`}FQMD$x$U&Zo=tvxjXB56ILGPc`&33frdBBT=}1VCu-+p5CnDl(Q8~6~ z)MxHBTTp}P+q*BR@+4isS?BLeNB2gp$0AZm($-ggstL?r_~Xz*u!?KmU$l3Ioi|Y6xaW{(J_-@b4 z&8wBdBW{!3$E(t<)ODPJJkd?hC3!@G!0C>eN$={UNqUSGPX;MKUZokGQ{CRJWf*I) z3p#5deMS%6#R)m6-u(mDs$G2>tuicCBFbgJqTgmaFfhGdLwe_@N(V$$2$r%m8J*3%{uDuT2+ zrMt^zdHsngC=W|bcH5tJWp&ow2|;3WzbW+Hrkv9bKr z%(e5h@@ZC;oQ?PI0J{DMp`wMXvSgm3p&R0I#5s`0{TBP=*{JuHN#27&RPTZx+ZcWP zF*9!clYg2EtJYX*3d%C`T#+ALh4*G&T+3~AgeboH7)4^VU8U&$HdWH+8W6Sf++rPNzU~NJVB9PrS7@!JBj0rXq(I48pq)Ybbo$ zO24WvZcp(c`x$(Ew#r78Tu0o^ga_AWqz~Pr#9eL0Cf^C%WlM#6Nplez`1W8Q!9kWM zPn%C=+E6{LU%zb}VD|oQ+@Ng;yGkpq86?oVFz!}tjST8~fug|EY~#XNe)NUTQfY%) zo6WcbTuPqa4p3J6mSdJUJp@>Zhv3qzFWY60$X#nB6NT#lJVeuPKKcIqI~{DmYrUnD zTx94ykCam_m7G(5O(BL_AM_+zRYcG;d^W?0n)>*R9b;**McQSytxfD>kw}lx-I4H# zO?=^C;{A}^B1ph>S@Z-K3+r@9@c?pDYWz720k}!5aparj|IVantpTcFmd|(zrI6PT@i8kh|~Be*pi@!`U5f z+RcH21$He%dT*SflecW~V<^S8x)u@PScTQrcZ3q$6bc((bO1{%uG(? z?ov^T8){ZreCg9f&rU+Hl$bsMkW`zofgEz|iI+g1e*7*W{fMOLq`<0qJKF}i(`0DL zSGFOEVqqu>>@`(&nTZEML51UcgLcJ!li`8GTiMqW<)A0E$<{77GKya&FP#U~PCssu zab|Q=bBFYqvF7Yg_P7|5RDcl&oJxv7#oiyMK;C=Bm06(M6bFK%^{vF4TV1K@ zodOt%PTlFcYS5B-rkvmTh&t}aOER(=ne!Ha4crSpuZx~n&A43zkq3Jjv0w8_c}xT97h587@LN@flHN1o zqxVlRIjJsuxkr`EjNDu0(DcL>*NIMs?YPmJH*fECrAUPq4p^r5SmucBF^+E6=X>p} z^>`cn_sq(l<#p{$1aW);iT}Y2@_;@1P07Hq1D*2%yhwl+CfG~G8N*?frN$Vk-9_AD z9>!GTU|sr9U>M;4oPr@<%>&~(5|Rum5(B}c>{fa)X3m4j(Y8^U49IQ`tt9O$Qm6%; zLEfspwSgv$N(vS!iKVK;gSo1Mg{oZouT%%N6&pP|6%j-XMGb?;lc56+N>9J^XX@p| zNr`FQ8#^H#5n6ZY&gkB>h_<+D0e0SPOxMVq9lCZp357}V{0Wn^+~-0pj`~juye0||I!ZCmwEvy zw#2~DN%6r;dlCS;bOR0mL>5+V8a)R6o+obDlN2}5Pp6dW@aubMz0GS*L-n%Ic<+- z3NK(RYBltjOR@kSi0yHA0sE0*K>T_2G)CL&Yhm5e!c45If!O@lgaMv39H7WOX-~v*s^P>r_%wcjty8t7Bs+~J9>5J`7zxcKVn=%jSJtu>Xy-NO`>I8;UUKD#aYa8^z_ zsv=M)2i_LdT)jKewsz5+*)3cnmMaRB;u<{*Wh1kab8`6WC|>l@{^t~O^7330?Cfjl zcas9Nhw|po>@WnSrjvXst8{#fewT>r0~y1G1~>UuWn<)`H@GN^nCtnna=KC3npF&0 z<=6b$6Xa4NmT0QV`beoSUUymSTNI$R!9)tM7gX$*yk6fhiRN#*?&F%e<^lpwBH$Cl z!}wt?ALd#CNeH~M9e&!E?a0#Uf8vqPe>VQTXAQ)1PBH~6%(k_;d4sK%VZQkT+WfoR zG-RB0r?6CN_1oyhj>4kk!yOE=_505O>?=@sQe?Erf1tVbh8=Ye6j*<@x-RCRlkJeZ zgPBO-`c~bl3FjEkwO>E`BkBaCt%}ys*yCCT?j~t33Lf+de5Y7x5RFfX^YPF{?r(@o^1{(7UK8hZDq6o|lqv8tt>){%A?58+eV10=4R#n4Iq_9$ z{p(!-Uq~Oa;oe0iw=dh4EroTzc@Z|y+8dxTGfDp$ssk39cQo-;#V{TARvifGRdZ-M zNgwX5=VcE_pEe~g*qhlMJ@gT75`=e}ug|5#wQ42?uLykK(!PIy@?56!>8UnecQ zb${FfTbdzyhW}48N`IY6;FweOX_HjG+S6@n6d2#x7(ic)&MP3POnt+AUUQD#5d6DcEVdwi#95gwl7HaCJQ%g3j43xfK))zRwO7;Cr-eu zRdLldvzSI2K2V;Sn#xg@e3N(CG;keasP3;gSXkkK$9{=D`g0%)RMYr~Cummz4v6e} zOfru41%!!73tqk0b@h^y0UOee`)&TP%bo>Cs0%L zD+Qj})1q2NXrOunG~;Jh@w*c0)|kILra_J{4$XQ&M%P20MRtTC1Evy>BsoQnm}!m- zQI=S(&4((lpba7g)bEozmBo3=CP1N-TPapdNZ-DWhC_2A_Xyd7OesE_ ztYfR_Z#0h*u`@{V_SsuScV-riM0r3sh#shXr&z2q0qUCW*N;I`g11nKLQd?GahrS?G>}f zwOEh&RGq3b5-Zh$pdrEu@Z2P~VHeK@z0s)9I-8Z8y3=h{2OHTo>26AY#xjT-_!*qU zxx+j_3Y3zh5N?_$#RtMq{`gBqm;M@%G_&dhKbaHCc309ZaWE+z`-iMF1C+l1WX{kP zNt)Sp7|!nma|50-5Ah1LTMWj1RgY%EgH&g_M~hH3mk2&gGusIhG_{x7Tlvvn;yPfF zvb=eb=~*?A&TyoFnal2Z8bY%Mtnb;|Qix{9YWzFDK1j%QtOVQTK4Z%RELwTf13*LO zZut@71MNP-js!0V3v9Kn+TYZPgDALjnceDzw!T7OueK}+V1W70*Z{7q5#uFbP}IwF z^Z~R<83|J5_0~Av@|EvSO9j2A8y*gWUba6tp-=d8YgD)3-psyG!wiR}tKqlDw+7s2 zVmo(c;^ItOq6$voKo8M}WTogZDS)14CV()Rd4RjBke3uc0$|XceM^Rux9|)`F%Nay zi;TD#dq9vD6&0nMei~HrA@xEjN{|C;C~AonFDkGGO*wNlCs-6A<65ZnaOd~jT%-<= z(=f5JwpKiMRk5M8%x!f-&~BtW%}HOH>*{s;iCXHooNY8U6fGt&34LM*kq>K2@^z|y zzqx|SX8pi!!;661$6eFHj1T8(h~taI=D5+bh)n9zf6x7XjP8 zHX-;TpWf<;SrE85`otk9zpA%A3FqoB}<>ExW!7 ziM8G$U@@SjP7%US`^kD|7v|lgCIzmnq>%w&9O$OuepGzDC4!%g95|R#%uRk-)q%FQ zHVx~(nF92a^)k6@Qhfy-`I*>Y(Q9+Ef*Lo?^1L%Fn)p(Yc=N;0r$slo;g`spSkX7jDRH57^ z-gIlI_uPtquQvwCZG|tR?4x(1K?agvN2{0ETe0j6xd+GbIS?f7A@QAYYCPOf&f0lG zYQ^u&@Ol`5`@oVgFf!&{m|tt+Q~99pTu^6xA-fVkpY^ua{19ravQuqd5i@p{G}?qY4Gu|&Y7 zzSYA+t}4kxM3g^4;OcZ;0)zNqR_T0NK7dMY%-fhIO>aM`Dv|?`m@7dq_hGavw}*s* zVUuloCn(>1OX&oFm!o4tfwv?P|0Rn6+&MqXN-c(AFw=DZf*Bp~t!v;)31GR~cET z{}j6+XuCvg`PuY&SgZ{nco9b_(EIYxqRJ?Vl044-N;2MJ*37(CF)07R{L`U5>j_AQ z(n5BX4<4j{s20}1w>igK3kPkZc`I-oi^YI1v3nwWbj(b!R);&d6zN!__LW$d0S>4O zvOlo~(x4%=ZAq}}UHm$*7t^;onGoIYd?3dZS~%jdkl$|_Z4!*iC|KC#f_rkPJMZ@^ z?r?90x~K>ZAF(Oo$}YdbqgTkyWM4~V<67jo4`e#g=xq_7y=^Bb{{W4?0xcjBiY{

    %|HYo)4o&J-4xj7X>{)g^HPZIlj0PruC9UesyYQF2UT2+ev2W!t(+2?EM zHNB?SIWqHXDS~Eox{JxB;B65k1N^YS!O>TR&$EAPvS?u!Yth?iZS2)TETBho-+r92 z%3MoT@#geiG-gpa+#fxR<*nSF;D#|tdASuHw2U4eY;nVeje{j~w+j5fP*6G4PmEDD z)Nl2TY-G8b)Xaml=fL{&>N(|`7d?F}mWpT5T9s>|xDt$aRw0-7YJg$0sc$QQS6NEW zYN8YQVcoj{QWYdpnqH$0O*{gfdUh2BgM}Y_(GWv(Cd>zM598Bkd|OeH;`;|%RVn}i zkPITWk5XFdpI7mD&nf7b_Y3c3XatSjC>#J8<8B$A8H0Vd1R|LwxwMtDG3`8{+Ho(^ zz&jz*ms%^ci$*+_zGM361=LcMW1~XLn#7FF_f_IrVS$l3Pzx9W&-DK_hxT zDkG0>_0fxg2{|V9t=9R$qc56j6M?tr*+oZ{lJ4TCPg}J$t{B-32kAAl`M;$P&zWrl z@h`&phN*G=Bol@7-U_cc6K3w6YVHy(hCEQOjm2a3^P=$fH9Y|6gPi)6K|q@v1n#Yw zdhQ&#ahQdfo({mz9nJ$FK3^wimMCU& zI(=IWj-9p@(#gtw7OS`nEK9WY~B0H%(X z==PG{pNvH1P^xhshfuJfCtH#s*BNbTzzvwE9+gy@HOMm4Q%fu#Xl<|w2DVtPEVbZq zwA0m9{v$Reh?{}WUYuG4&=Xbr3nk7Esloz&Q%hZtR!|2LO zk*5^F&byv+^w^`UCfXHP!@HgdsgY={f}2ToO7|MH`7d= zk_N8lOzV39j;j^kKX5RxrLHV`Wf&-6{duw^@j{^}Bp){{Fe{^CbAaP`T49~w_&^@1 z<*pZj$@mpZvf9iAc9fe@>Fk$)-=tHiqsdcZ5>U`w+Y#XDIt~4sk#W$B#qT1>+7*Sc z{IZzwAFs@?;#sW+kr=P5WFo-vhNz3C?DATKGtp4w)Y+ydNtUhd8>vH@b6Td1QOgBXW1T7SDW0AlBFWjb?kG(m>n%Bk<$6N~BQ$bOqS z!<|O0jz}|9B$Qg?mR+mF>k^m~_NKxOTWLwN^=l#Fwqg%b2)lQ_(^bB&Kz2rtd;-2) z3}sW+$7k~`I&(?t5@K&^HD7=@f1a?F&CZCU-*L=)P33rcdNfRb*JI{px8o22$U%eIobfT@8?-xJ>3qhfKT?l``SSNQw%CrOzQA+v)1{;1m%e97Z)Zb>H_kRpRYM0H!@4%=h&4MSLyXY8tlw> z8>7JU`vr-}RkQA)5=Vt$t=ROeYEUN6ZAJg{UKlP*TKoJTZN$aGVrLBWA}mOoEOr*~ zam|6o4p3#NmN(loe!v2_4T z=kEOo)U`LwT)OO{L%V|lHX#L>TBjdqWLkquo_r*Duj4?dkctWdt@l0896^ymg}<1o z=w3~*=yZfNCl)F{NNv|pBrj*Y@6KT&00yMxQE)0ByWF2w`>ip{FXP&)NF|M@wt%#F zEjV-x6f7vl%^u^%duE7cfdGiww^CAM3Zlt3qDhbVKIjrKLsy$eRk>AxO=7eyz8HM~ zl7p>eh(Ov1WgkTzfQW5eP%>o)q>Kz1knB1QxQ==|iqm1VUY{thcj;6TnfgDgE+`~r zQ6Ac5d;FEzXxVyPs(OlPcd|;{NbLOlQ7!?l#OuMm8GMBW1)pMY?*z7feXfJlSusX3 zHp1^LZPS8&zCKSPh=DK_e(z8IBEU7ruyXGGf3oxRjki)sR*q=AJ zkplEPPt94V;Nb*n$SKLm$@%N8;#;#NpO+YLFOT8`xDrbW7Ayq}Gznrv{iz0Ct93Xa zS4;ioz|h-N(lZO?qistq7yu<2fZ_o(c?N0n6^B1nd_IB%MttszKEXUxTL3!41V-rm z@O6AXA9?`l_83&`tu@U-18~3jUq_OH-d5El6ZRg3#0p{nprziH`>mr%1$g>O%4^n* zCK6;&kqm=c-2w4bj7-X`B`OrEHyVYRdqGMkG;QK-&opo}$p%-dIpHrz;_Z{63fam# zJ_6YRki-mZ{BGO&Vai@>6aOTvUwk3KbHie#kv^a&C^~n>%cW-yD0<0A5Cc_!fj=qi zdmzDrgU}Dk1jW*ASqN%x9z1OeFei{U&OJY;d=J#EmF;}iqdRG|9_7fVfS!U%kj{uF zfivWj1levX5V0jeQakrif%oU8;j`#jJzPT7lk3~gscXPs^Kh; z&w{3k4hA0x2chiq9#kbLlY#(Rr;lD7OeTGVM(dnFI*|ft(E8pR-5l`tJ}}4@oCJxn z+54{uTBP^IZ}mj8kc3ouxQ{jScKg9N@_xDM@ZfhIvXtAzo4NnCE(p>m7rkX zK7i(V`gx`;^V+{8p;O;OZZ03IY)u16+?FX;GAdukrX%r1t}OjOzS{3Ee!b~O+j#a9 zoc7Lpo=Nn`Bn63XHPP3Gtgo#9T#84Sbu1>fjChV7il$T)Sw!dSxJqpKv^KGCjhMx( zO7(Vlc^-$8viidQ?XT-5ejFzdObJ5g&YeSZdp&-PklG$Q=Ex%{sSorN>1l8LQ$4-t z5?WeX;bqB32pADDC4s-La$TQ-eI04nPg%Wd;{yP?V|dtRc?U2tTLU!yvxqz%*lEj^ ziV%sDgcqQU;DGL9YZQr8fA#U>NB)Ie(-wxA9Xqc{#@4N}%67K<;^N{ha~T;K`h4s3 z|Jx$D)t`>VpSbYMmm|NpSR3T6RZ9>3Mn(*D3M@lK>CT?L#2)kPyK=7_vKUOH#s+1Yt|0E9%|$;@+jkpJIh zcK=1?XlQMnv1pODrzjNRMQD>K5!J}wi{5Ghtro5KG&D8eGE=3wKJT4jLGIZ*N(l(4 zLjVyg`0CZGme=ioTd4wGBr#K zj)B2)GcPZ%@`%^E(tQO5M^vXB?loqrDIDvxd_sEL?-7Uz;<1y*{>>KtYc@Q-&vsVTm>RJ#&(0TqO**7)g46dH>guA=g$`p zR>Tmn5U`_S@HiiQD%8lJ*28~nL#%vNZZkOKAw3yPZf{fcqhBv9YoIHT$U_0%u{diX>ZucGC0}>$^`;Qw9VLC;1X3HT7kW^<|LC-iO*B z?DN`c%6kow-a`u>hS8OkQVLj;&YqsDu0!^(o^ zztlPXsi|q>_ZMVWxVWrRJaMnU^k?M$Gbd)3GJRp&A#+sc77J)^6JH8d*U-2Eh5ySE z5|1juP_x3_yY;p^qRL%eT@f(5`}f~mzIs*OzyL)}O}!}Ckylu#+1S|F%vQPxRHcY5 zGFtBIOD?~X45Oo?rvQ+LEHB%38t7M!oHH*^)OYd$=zDk>pc2qxvhOJ>HoFy-ElCim z7Clg>Bw)n8>?BUA>UIs8DK(>@^{q@Jsh~gusJ?6-32aQ&j9hc9@dn58b8|b0MVYoT zv~zAV1Jz=<=Xf{cOKA{}zsSXlb$|??Gbbl!?O+!hO@Sl3vH~|ka zA8qXj9bGk*A1twj*8P`2EeMsmJG+kGFLz(RlWmbE!qowF_I?1Nvbnr>!3FZ|=?WlJ zaB?=5AA&OgJ-}CTU6ypu#S5`_2m7B9YxtEUa(h%LG%TzUMB-faHtiE1!G!Jc5};?g zRt#sxo%AgYjs8vmT(DGq1HF91mR%^3q{Wr%Cm;9;XkC{4u6AOtC)>~t?(7k@I}7Bw z{h!3wk=s95f}|>Xw?Lm(@T|-U#_aMn`E%u6(Z`@fOXSv1h_8r~9Cv;x_S)mu2f3*D zNzl*4<`LMz9_OWoBW;0{PEf+LoOcIGue^gp?jGnY{RFyi>`Wc)nI5*ZwhC`_EV$20 zx;m|Bp0KR~?=Oh(Cr6XdZ!k!&| z!ywYPcgc);f+pywz>k{Q20Sd@xDT_1vr0*z0BM49+-r00*eC~0ZYKt zcYY4*Va&>O-3#2()ki1xW0X}SH$I)bJ-;RP+HJXHM&8yoOUKcv*I91kb<^|b!~z2X z931zhFM$$8W#mLw%7+CDoJU$YTbo-A2_0yYxp2wDDfx^o3h2qxk)ZeyHI_2ce*hXx z(;e~U%u8whDIS-t)YU^y)bRQsZ1N>sRv1 z^v;3)lIy)py*Mj*`L}z(9bAH9fLf!V^j;%4znkr`Bt6Vo>87{Sf_pGQL<}dLg?&}_ zcs?=P)z-!e(V3P{xb5xj_V7)-0hTvA#DK-gsiQ_g^6bNGau1MIzpH#YvhX1;Xe>qQ zvz+OCdx+Q^#}fG0L5AGxd9V}>4b8O1VcX8U{?f*5dv!Hp#(n>8aJdAiZ?u$zg@wgt z1#a95KHI(UVSdI32&aoq0j;~Bl=2?DIWjVSS(&c;6%+{R_naPevgtT?B*;rfo+p~W z@7;L!D9@0%_DoeV|9Po->CVGwni2&{yR@BmTQMW&8*+Y>jbzAWTcw78XezS014)M? z36m&kfb=cbFmZdo*iG{jm}OJteCK_Wc)g;FF&NT#avAH`kY6C}LN5lb~4l3Mx9BxztD<5SpRX(>5!ckVP4Rc>V7*HR4j z>AF=3(q}EHgKcBS*||v%B}K_tpN#eorIctfR05gPVs4hm{Q;plr58>PLzBf>a@r%v z!+q00Ri^C==g&WTbc0PUmSuCTo(fQwJ{94>jduwsk0N)KtI5@#YH_(#1S0YfZ+tJh z>;4IZb4S_N1#(Xu@AQWcAEt+%`phCmL6yryn85?2oKrw`zERUvUw_vfG>%MxinQ=T z&~jADNVj*d;D^WKv!1w@cRY;QffLoJ==WfJHU$K(K;|Tupe#7oo**_iJkB2N66+(~ zKcnw1O{A(d|51bxV)ve$brz?I*6_)uAD=c!JP(F@TOSG%~mME{J1o=k!M5vNY2vdqE$;bER=5j){t zxoo2O2>B{2Rj2XqFQyHc?sV65>34#B#LgwHYCbL9rQ%mNfOQY&EmcuM@n4HH#=f53 zl&1wSuAYqkR99|_lP4pc9(c^SNPdJ!F2E(!FbcVlS=3wtiW)9OR-KZcd%3&Iek|lK zd{vaxT?f5^p$7*(j^4QX`*_hnm7uK-@qpPyVM-gDR`R6Z4^_Y^1?4pX68 zjaR}S8M*i#g2voSIyyQIKm^3NvEdlL1U*hN+ivdQtvbIzbteR<%?4rII+r};wp65c?o7;JOVD7`Dp5iypmF=ageBKV~JSLnF`Q2l=$si z+XXQJ$qu#P?~lOSKrUaoq9l4KDY*^gwWts2>6)1zLH|I_1&@cbKucz~tK3QM>g|n= zp8^#)BbQXy#pX(n4a;+%x``fF=ybj$XS~eA(?a~LH`|a8bZGj4cfHiV3+kR)kN|H> z;q^$XFz%W|%}*)yT3h;QVU}gEN({_j6=Y=mZ@ToYAyz|p)sQtIAt5b}6%`f6Stt1C z6y0Hd{KRT%YIl%mF>!HpaU%zDGGF}RkF1c9;cuy_7I^xP$Kb}Kvq;h2)Pe%%cj+;= zALHS8y410;#~~k#yXtX{S56SS(7p}|61Hlb8`Zx@T6`OkU3Q+C**3T5Rz&*(b?KM# z$Yyn{M<&uWM~%TsUyiHG5UG;!-YG)q1a*2^+MQleX=%d?3pS;t2c>o!Sy(Zb1i8=i z4^Zdsd-z}7-+EJ9TRUvq+c_fwDB(c-;EkTFjWWq!FW3Q|zlgmZN`SHuXRyc1Y0c}8 zZj3J{9?J@vTMpsSQ?X&;n`2EwU9#J#Wr)|r-kK*E%V6-yQWqd*HS=A=LNM z^M!r2+sanZ-HH{RTWh{}Lf*W(FdI{kGSE?bc&U4TpO+(8kLb{qrD zk{a#K45%0tsd$feNV6)OQg|xk8XVWu=0ym@?9Q^n=9Ma*&Ouyl0o@;SFi2@a_<~aj8k6aSFe9 zT2zR?MyVkF{E^R%c#U}UXy}gZBr~y>d^Hvx58AA=_SWMLKY^lo!|PK$CLpbO@`~vy zmak)#hC5R7r(|H>qN$JX?@acV2{nJku4BR4gAomp+0q=pcT5wSKGnk_bvTV04UTzhrNI?)46lT1_5v1{)z?vI}j~H zZ;j>hb>)*36r-tp20l9`?qhx@noGWZy+(ij{Cl93A=f~b&*#Jd1YDH2%M&{$qd2!-P)0@w?6r;e=qc<3)_D~-hX}Nrdn;+1M>!KUU5Z0 zTwD+3G0y?9_vTg5fGdCZ?n|$OotZW85}u_l8W0>pfMTV3`}XZ$K->)lGPwGP&#p}g zpqfz930~g?2_WKvqW#3;O&}F@W+L6+o(yi;1@B73ZoZq0ITLjzbr^GBoGd0Z z>QYf^d;G1zluBezH;+QV+wM=>ezA7H&Jmz8FgP#uN`MdoA~OQ;{OoKyMR}%bYdbrU z-V0@)Z3gmx65rXtZR2pbVN@rZTtY%Zi=&2yhV|?G==Tk8POg4DPyJL_ZeCM;tO<{w zTKs<2{W71NgR72}^EqC>?-C%DCTKJ|IA9~ZYOl`PmYR`~E6)rgyk#?7 z+FdRN|6(kek?ri_BJb?HQB2ep7Dk&lJ*$mba2y3K5m)&6?aP}CTn+fx#_rwXEKc>W z_LN7bE>r~sesJuyeSf#$qMH8*y^mw6L=N`0s35P4O0Yu`M*(93oVF88jNVVSf4~E~jS(H{P;%+1lEMab*?X z9vB$7qY~0vb5G8}`el9!a>{9sAZ=Pr321#j@bEHFBS_ugW z0cr5=7mr5{%=g}Z;Qr#nGd}OkyZ2uCS)aAnWCK})=F)1+(SA%sXxfTKE|<&g#z{0U zYLsf9Ll5nGuia?x?Gfvu*22Ewp+bFTU?0o18#aO^E`>nlw=Tadny~bA+Kq~|w5A7E zm6~-&Sqec$3wFHO_#Qh)Kt==y>6{8vQr@9mX|8+M&c=7-UyzqEB=7(Y!Js1_SN)x> zT=1X(fx4cRX^WW5su;YhZ=a->ltA@v)a_N0h0oa6QP>{4NZ4V}ZUshx)8j_9BNnII z!YzHg=%jr+JEa}G`$Hr;rj<*+Die`AiTtz=6D(1iLnXbM&2%CUNMQmkE7Bgg0TbE7 zOfr|RP*eH&ZDa39qNu%IBV9Gr+q^%X)(14r4S$VPE$%yuLG3V_xYUIoq}u|p4SMqDFN!z1nFm>>55mby;hdm5dOP#Glx;h!!hf*smRoYkH`NDT{Pb2w| zvF`}>Q$&Mb=9@x+3Tf4vSA>Z-0fc;O8|ndY1gS#Mz8nA#sxsXk4!!FI%@7}()_>fh zA@k~NZztiUV0+2#5HfS1?9RvsmHl=G^9P6}S`VgoeI`_W~3 zg>Rr$O6Hm4YOM_>_Arl%o2p__yuKE-y7#yAN=+d#inovh5| zHjE@BXy02&WSna;M(V|F@YkL(u6ZtXfNoK3V2nC!6-5ur=8bF9c_jq^wX|~<LOBKf{(lQ0x#Ln>-*y{@l~d}EQ!_g-=sZwD?u+s%gbxF zHa6iPI}wBMQCU!_@d9N02*B_Bn2);nHfd-9(!QC<3mLz0q_v9(Iu+}5^0Y7w4N&yGt* z#`^j5=Tu)eDyk_g1W3s@$okxu-bw9k+vm{=JG8xdR-(QrCyciyh1zfpRREtX@0{=M z?yi|}dJL9Nmt>vS&DYXDC~)iW51wH@=$aE&QDvx9&l&&nY)DZ4A+m}}u^UJqJbAxd zx{QH#0j;IrQ;eg=V#UYIYAkkcp7!S@SPK;8a)=ALcS4ZuAR!2Mtx~$yD|1Ic`Q*Mr z^?@E)(59Vkpk6x9-NoXba15z&cVx+cLjww`(srEc7h3c#wKVu@OKUhK0q(%UMxh;l zR<`8g`SbKK_?5`wyPY`jr0>#$7Zq*~#A}6Oc{QmA`X45=9fuG188zZ&f{|+NHAO#^ z`G=hG+X4vo+fuD<2YNDCmpEOlNl8PU2BdowrIra-T_Q5Yku8&)07Ui5K3GZla39IH z`EA`{--?wsEQZ#e>g5ljd1sZ|mS{f^MIzFE;1WTUACDBa%IPx$pR|-((a!sX;AL7q za;-T?%~$am?U}ch&k#oTn|)U)Q3T}SUH$w-Wuj5I}8^9w^RRP;a9 zN0&q%jaz^t^}5W$jGM_LS#54m;U&oU?$ZmRolN@w=+`Man(DO{XeOF(WW z#5eC`n<0j5b@)VJbq|e0bb z`qfKjmhcd1U+&NT%;^mI;t!MG)xB_jCO-AP_T>0<$ez*-WQSpnj^XDqnAEFJS$u<2 zC9$(RVlx;w%yX%yIKC*e>1SzO6M9An9kM5Rp<>hAM2ej%VG9;^m^yk@C##e-zNzNpLz>7=*(OHZ;ybG?W zL>sknw06ymPl){{w69`ZdQh7$z6bQ>3bIwM0-)i?czuRx8k!9ghR1Havv$fQDUYH8 z2{yGj8kdVW{0iTnBZP!B2(Czm3qPBmuhrYkhxU!s}P$BdJ*^fR3KU!C; znjN}?UZ3vz#E@T9GxX6TxqGi3NjMe~WA0g+M=fDzp&{F#N=#f77ZPrC_qfJ`rw&lI z&3`W?(@MXI#__>}n1hUr&e7bv-pHgc^9CHn`MHD890|;lifUcXr|=ua^?RTtsj{8D zjd}L*-knJc$^s;w{6G(Y5lOzN7WLAQI*a%wda<&7Xnn99NnE8!=1PD|NA+(C`$y5V zG{I9Y`$4hY$#5;W-OozHjcJ~ zq`NX6xm??o{T|6txh`Tgfq@BMk@^E8Fd8>`aDmxsksg8FYu1XxgiHLkuJ(0**IN7Y zyBU@aJ@VX0AP6`LA_n*Z0oBl%X;oNOPR`o)?3}cgUuRifcBN+I)ktYm!z9J>un&LM z_U~WyY(NHvJfpYdwWspl++3eI(0hhG!b4bQW(1EUjA(&Emanakkm<+@WS9-?@0Lb4 z)`#G&+xR4=2L?pPR^s5a@5af_BrTH>T4N3%aX<&EU}Jr^1Pc-a;2K)l`D`r_2Wt)+ zYLid(*_aulG-G2KLa-~5fvXS2!IKRAjD3!*%8)HNodVfgK-+V>4wVoIJr-}cDeY4)!GK68=RgZ-@qOt=Czm4e;h&m&2V8a=_2 z9*Txa_}CaH^f`aI-HPb|^3Wt7r;*$A30knTaUPGVwZt1U{gb1*Wugcc9n!Z)1ZGl! zeHOVj!}m8cGD|=Nxh;Q%WURrfJ8y{5_k8)aQ>7j+Zr*l#9j~fJU4HJ|pbc(0lG2rz z64;%~u1xZdNsYWf*j@u+OM_J&8s^j%8Ae_uY@bUs*jD#P3YvTXhbh2@LxdY0-AH9+ zzLT}#M90t9BGkjjN88R51%Xlc?S3`L)KZTgEY!5jY78nCv!+byWcM=)yPL6{k#euf$SJ3Ga&VqaYj{ESo++FjG-KbUZJSesmHHc0J}Np2>H51c)GgkCj5krmeFMd2 zkF`}-2;MILj3n?rEJ@GSdhX%jou6?F3Bcn3x^$JcwN4(uj$!%#SUVjv?`Zl*Kgwj31Zhd*mmD?%331>LQldfrHKcV_t)VT3QDdSU!hYzj%U`R%%_w(F|p zY!=&V#s5QsTtS>zU4vi0nSTmznF5%TTm8>}!br(r=F+mAT7>Nf$ zfRaNDp&E8&=4gx*Q&n}^Wn^rW!JLRt_O{_9n$r{y5?|H;`7%x4J{<~NK2DxHiSeR} zUmjJwLN6e@7M}5#uB0Mw^n#8Q{#k)X#6VJ8nmF^sPZw?L)yrV>jSUl5>8FfE`UU77 z_a5XNq!o;_&Z=UZJrpA_d^%ZUfpPI!BO5H{UP?(dr6!?dKpe9-jcZkEnfTFge{Fk$ z7ZUY6fTF0MTf(f{sEB|mBlo-Vfubz*BV}g5XJ-JPt*rX>TtOPVWhPDPrum_@yBN)aKr+L6cY+5yJ-Mt2q5aM z#_mpZOb(+z|7PCbHBP=CDlDm>e9O!-2hKX0*zBm=JqD z&_rALnb+9Ig^wP}d}mK`N&#|${h2IiV=TcW)^@62U%)pWAwqqSE#$^zP2KiLoz#nN*6K~g??Qm8Pm9cC4SaK3qfh4>U#JK zKN9rRN3hP=eKv>0KA?FJf-Ow=}J}n0&W2U@C?_$p9YSp8*Ljn zuhwO`iJg_?Uojxjt$L6r^b>hT@KA9C!Tmbv8#>}?MCFraYmMctc#AwoPdTIMN+(|w@zGr%Gkp(h7U}GjGrTTGEqcGxQqbV=X z{PNd*a}y%kDq1YF-roPC+NlWrVt{}t^%NaU>aPzisvBQryp)1-l$RTm<5jh&4V_&) zWpHwk(9Adhk2|?%Ckb~)0X1P4hvgyFYN z20m`Zz==@btt#Q59<$gSU0&Y+4qC#POW>?3`eguB)T!Rj7J_jx1mlw0WHwQdF@;*`}g-x*Fl3%j`8ccU{Lc8;)rY<|Lrbc@)F~MCV z@{$illvcubyzv~~z=J#KdCkq+s!CPj=?-&pZWk)4e({vre5-^+E&ffQp8M&d`|t?L z7j{LnRxD@KPfpz9k+LEocC;40aq+BcjSd1{ZejjA3rvJM=AX_;_pkQew z1lUxSKGCUZ)-3lkTQkKBbl*FJ!SVu(?aGdaSG-UpuVyNUxgRKhnq-%K{yZZ)Yv?vz zDC=2u;&6ieTvup3?wU5@QEJ-Ervo7wWx>Cf`fu^keg&zQuYiDeMdz)vuj?fNOsf4R zO#!@d7Pj%e$;3sh5OT_`i;#+5F@A;6o!m5)b!&{?9%qPQ3>E|Cjc+;gbUX!7*QaHi% zKQ#E?6o}FY4-xE#QYv_`9fqI4?URxsSE$Ml@=@{QU^vC_q4h{05r94Vn+9V>F~=QTqn&y9qdhz zB(B@(?vp2eK_cjX?EirZCCx20fTx9dQ@@wr-(PmsR@R|n=jGYYxbW(1?$ix!P`+pe z%~Ti+^PSjwI;adt%9UA8KHYP-9w2nj&+K9tl}$SnJT!Vj_?`Wv5*Hc^D^TSd+h6Be z7@vLbay@7m@u4((R>7ct1>Y~nOhsWl~ej)3Kg>MhbXW<7e@9N8b3dYseMKn z$L%p2Oyx9j7oEv*8d+>v6KmgwX+i@e&iFcnicY7SJO!j5Oi~gG=GWax%pa}1l@fB* z)|{SU`4et!zTC$6isVsC0BI!^zwPA`MMJwH{Y<(NPgx!c4nrC*8&0z zaRl2)@-9yhl2vO`gZdL9hA^6loIVeG-NZmEy0u!$_UUG6D5raAl}qLeYSA-s$C?w^ zSf3;G}(g3R?-~mC2T-1<4vvZoaXO#BE@78H(vVSccr%Y&S>T;?TI~zLCGlNG< z?vH^anGK)MT;uszXabd3h3)NwtOEUITtjM{bC1}V!(N^_mBvaSuzRjQdj&vP=HPhW zUnp8olNxqTe*A^!z6l7f!gDl{C>Dn{*wrwCX&*FPhpNVVH$ScivQtn4uqiWNfE%_+ z%6(-Mlu4qZcb9IY7^N&vz3(a2^J9xF)5o@}FW#Y&4#i8u;4T0X)7v1F-I~k>RN| z0LC9558%R}ocbFknvej6WxzMP93_ z9$ZD!nTmk%l-HXV6My0lS=9>KBR)E6Je*-5!J3`kx^%td#X)ZB-4S*2ujU| zyd!NM4i3tcloX$Fw_D_>%upcgz|MW^R?FI2aiI0h?_Yj2bkH#{#9i?4^vozIu>Eq` zi2)XdD=i~~2UU6F$2<~g7AKuoCRAt|Y%LrkU28`;7KQ*~em~{oU{~A52UD1(r6v99 zyLV!iRwLg*MH*r9EeiJi`}fT8f&!NI&ryabytf2E5x66|=k~zhV0DV*^ED~N{Jh1- zwDrwZHd?T9Tp}X#dSiiAKuf=_V!aQ@EuYBu+=zhTcv$J@GH2jfNmDL?g36B9LnBO}q zrCzbTc8zq&wd+iB*RIu)>IMb zcz96O&nY4C($4@2PfXX{%6X7LG5=6M*$X645X-Pq35nTH{>SDl{<>1l-$gg_f{92z z9mcU^o>rZDfW!1hc}7)G`86uQzFQF=gzZ*2n%I=_+iQy27mYAowl5f85E1#ec=20p z{Z=9ANvKb!1Fi`b;ZRQ1>%HMPqx%fAt44E>y9Eb;Kk0XnB>jz*5SF6h+e?gw8|`F!dhYAObBOW z55!=b{x26`)36ceQmJRJmrESv2OITG;QiPrvR$^iW$_GfVpvwoDq1<>Xm|g1L)d0Nh{hd9mT!R8qPeIE;F))mr^}5f)K0nlzkOnY?n5c zWw3Pqyq+P|-7_f-;!o`5SA->*`vcy6S3YEDOP|th#-t6@rMfa*abCAr0lz)t5;qgO ze)m)Mou_BvpGHA+|JqWWeke>|y9DTkf(Ks$9y)mq4$yVyG=BB8CA+UVK%&tMAi+64 ztpX|!GpiC(0umb3QMd5zAVMYV(;9vN5ukmyMGK@*5Hc8~*9hqLvR77ltr166RqA_p zHeF??!9dl&muR?dN&4i&QnG02rFXJjBpH-1o-KVfUc}-+_c?#F6};Yo1QhTWcE!_J z6S4*;btclaT8%47AG*7=3?wTJsz{|<1v@ndFCvZ8X z;CMl1^$D#qCA-$HU{HlKZxZNN_|CjUJR@1IF#m%qY2r^9K)vwB_B0nw!ZI*7YRPym}@qNBB%C+pVo~Yenj>keLo*3JcNe*yQ6cs!pO3 zpCZIe)dA_OtF+I)4#Ut=no=Sd>z8sjOcE;Mk@Jv17ui?GRm*xUP}6afm!%&~Tu~*C z`EjvAHo9jF)2XOhOU93JO=FRD5md_~@mesk!H*3>DhI4-Rhf;>bx5= z+z40APbBs|np4>=u4^J2NWOSldc1UiOe?yvzXC3g8G{!6Lc5}QR;%p(O#8tahwAJ^ z2%ffq3R@9RrB(`NKi+9?QUp?+#d3X#zd?igBwDCCrL(C|p%luB|D( zx25mKSRI$ekd*&k?5>s9T?2R6lkQj}UxWA>|zhDG+9d1CUL z*8WH3<(;dxD5ov1kr0TCr&}G!AwwyS*zCb|ub|Z2dhwE@oTO~Db7if;+G73vhzi|l z;Sqw0wj17X9N?G`GMIm%qqpJ%LXPsAn{)g%d%L~^y0h;J%EQ_M<4!Md4O~=`eALrk z21LqBfl>|t)quvyFARuP73Pb?Gu7)%NQqU&;9}<+lMo4|F%^aYg&n|iCCbbY&|UM8 z&0}F_j6zPWnu75B!>Vmd;JtSO8X;;`bqD{KopXniWC@NFpcDX5x-)6qnj32KYWvX& zd>?v!S!^#s{*Q9cE@KzRxY{f(M9|%)QyCbtUvO1+KfN)TP>NgaF9g+rA3kgR_~6aD zOoQt=(N1&#c7tc+--Cjra2V0#Ee5N4ad4)Gi5?Z1uZ2$J{wo<^3BD`YLWge;Pp>d2ExwbHn8Ob>F zf#$Rk(SjUX`Tpw>=sS(EXfIr7?*n0)g>!gS;dVenN{LQlZUM!HkHTp~IF$!})4SZ< zk_hZ;9XuUiT%X5C`Kd&@EWb<3|I*`cu1L6UQ|-`$Rc@BxWx<0EpcD`p#%P{FFUV?O zV-rbWN`O?2*P!OC`iZ8p%aDLKnw7Q^IQ7nc1sn{wQNY3Y!ntsb*fIXg89+Y?ssn|M z--SRh#P~5q(q1!7?2#H=Evp-Z=kcjma!9TXADVTYIS(4>Mbl|4A-tXg4}pK>%Pdr- z&B^?*q&7Ij4%PJ@*sn^Ge?xtME8)zpZ|_E(HwJ$kBC@65=uk_T+$iX=s)`o#C z6OiGsgTCBLhLY!oG!&V3$;m{nEid^mZXGJx20Oc3K8~+QQSzDWp{=8#sqeQL@&DH` z9haV`q`<2jW|vwrLE9Gz2e%C#3DM{evgq81>QZnj#K~PPSfL0O%&q)4%6Z`6kk7(* zx^>iV2+ER13RCVwi}HkOPP6gajO$OZ0*(X(Ro9!E5(wt6kw-?j;H-CosBrH&)2Fef z!tV;Cr`aD5%Nr|L{pzZpt6hS&tuX;AD8`3hvky`Pq^#}%-Zs%uK{&`={GHL&fU=ea0K-Z(xf>kL9yuH_Ju>$G~{gVzydGGAK z#tK?AE*z0Lk|V%4G!w542-1=2myLyUpFB3O(SX&)xb_PG1VM%*T1nIU8BOi$>w`Yn zvkVI$)ZtNdOfRYTsj6~(5ucseENY<2!1_o6Nn|kvp&jI_Fed02w4^8v&_&p#M7ns~q3 zc37jRCvYgC9PV`E7Q zy1F{Eru0gk5fg`fffR6wz;ltgz`z(6aYd!2fJOPpGu!=E7VOYUXeKFibj=WdVK(!d z9GCD>tv2Hol56ue-_5wmj`p5g@yp1+Hq6Ovb<18@KNClcQ32H?YYT^9w4D%$oTA4m zC_kY=La!gjuM6_wgaUgt5?bMWp1V5vJaW}_Rxi|YaKg{NjS4WF%r31Y(2|T193Z~F z-YT=+CbH}J6Sy;g-R67*4Tn%4^?2o+}~$BhzUs1@=v}|FZ!+<=mzp{J;R79RaKpNyQ76^lF;+!CjY4ji^CH2 zj-Nv8%L~T>mdR91NiA;I-WocztxqZ2zp|!`5Io{4OUcsoQ8r-A%AceKQ5=i4$CA_rp4`SjL@$L0#$l0*&C5>X8rF~jjn_)2^n-3w}(cx|^l7x5%}i*VKc zCo-B*>TP=~o6sUGV0(z_$oNUw{q~JU3V|9c>enNMV_UA`q4o)np{a?JfBxO zTxt{-a$kjasi5|y85`63xrplzQkc91PyI3VJE1^_4HxB)t=EoU;}KI!&g+81!*y|q zu-e{!>N=}iAlA#7$`+Xmc+wKX*y?C?zcwIGIsJ@aeZV)uIsmNrW0Sm=-T19Xsfx+C zBL9$D~U3)eQzYN}eZsDVpg7V(vL7X$-DhEi)d)}!1GJ{jxu#Z*&UweVM z`;dwb@sC-aVz>>0IeS-sI_p1*FY`&$(=?#FZN=bz2L4V%kA{irJlZ~9tpPJ``ryGq zX6$<5Yem7D4uO=_O1J2}OP_8V*jsWpr+id)%+z7nYyp<;jY9U&76Spu3Qo9|F*=|& z`n}=Dc^-!`EHIlgON42EZ)SIoo?yo&q#lm|U46lrfOJ4gK`UFEVUw1C0|&?GebdX& zVR$DuoYLqfst-+>R-m#z^z{fbnD)JU5UtkT`lEOipLZnf`Q;tAx^-abGOS+2zqLyf zI<|EA_|+0YZYNF-Sfrm2P?S`knE^ib>&E&Er1ra(IZU|KaJ!DS;ITChb6wrQC$rB+ zJP0txX+eov*3v#{gZMOi%*)WIS?T(uJu~Yu<7Mpu!iam|P*(E_?c60n`_ige9zElDm%s{Qzbyq%eS}pmOw6MgfS1XQ0p@A0+ z81^4$UybN60BSnwDn!Sa;$kR#S}m z`M@ePJ~Eo}v(;6`Q#_Ey4VWBa+lxZ!-0?PamL+55P+YnNb&zx| z67PPfezo2hNo=XK^yD;1Cj|1O{?eoHV_eio8DYWw-l;YJs=N0`SotHbOqQ1zZWZa) z4kr02GiQ^>#a*~ z@?0Y`*9!kdk@^ z*|}L>u;H3gWhO0y+m?lM0!f>B(%jF%)(%XWD9) z)_c6~6D+|5giH{9$(|j=!0Fwg=~HAsC$s>yq*B8+1b;vv<@Hd%OgrULfQOTz3h&AH zDy|1^YH6E__4rlSR1m|-l>F?h>Jwvb2#D9@{`p>4Yz5%zfH!Cjy4y&j6f`V;Oze@#GyIug&v0>A1}91z_=D-tv`aD(>C zJkDNI1&gN}R)`#_ zxw#Z@R8X#eN6mWkdyq%bWim=(Rrv(bI|YoyEdnW#->jKlos8%DAliqwgyS!bZZwAN z=Td%605M$R-cj6>JMI}dx2p#%loINd-hE_mW1eXM{UU)@XbIHH3C7RWKwNi;KDU80fzd9vIjf*3B@Ipbz-%C7ghq_kj z2Hy0)HupFa2LBvUgFQF&h;==NQFb1~!-+q;130m^Vig967phyzf~|ropbIiT*FHQ9 zSc0KQ&Aay$U!M-8L6pORK4D%H`Q-TfcS_;GIvY-)dy`*eX;EbKb zd38rR9!NWgD()=@pp2>KcnnQAEI50^nDA z^690=&%H)I6$Cl9V&QO;&?m%SW50(ghx>`XS@EQOT0=+mY5M-yARXtIW0iwbaTbEbv$*E9b}Dd>L(-s(ss z^~tY~JF=m!&G@KDCVTLdeOp)XE--cnqfeg90&>G~V5gxbD`Q`DCa`11`gU#a-rpmt z=Ks7ZXhtZGUG%ZK@6Ru?I3NBM>@!8KX2SVp*WJ=srlQwP{d>s(h>9CxB>M2*CMn>? z0bvRw@%}I4vPO?6f&$<+kNp{UV3kNZ3pkVglLZcS(Qp5_$<88Y8y(KVK>L>r2C(I- z+sZ^I_iFeNit5z1U(-LB>VdpbA)sw}YdopV7{shok`H@*8O!-f_|}hBoQQ#Sd2V3? z#V~t7c06tIrV0SSQde%C4G=hJ@5rx8E0NIZgLdIwM9)(H2N`~=b97Qx8VJQYTvQ z`=?T0s-ZT{M{55e=}RrSg<+MDcG)y>UN@go#=Q&NN6^#$=J9UaTm2xZ}m9 z&iI_#D;K`R{8ks8Xp_KHT^Y4qHRUe)r>iEIf+qJcsc5NI4_6-4tYcn@hac->VGI%v9Ta`%XF2>x%}%$#ICeFe-@%_ z>uCD!`uI$JEl(&B(Ng_-;<{r@t#{U@ZuuSh8T+VZQ_~gi{Qny1cL0MUma{GVb#V(E z|Ee^{bbvuz0%NJd61Ad>4ZArVUA48g$G7O(dh?`C3tZ+)!S3Ws8Nob?))rx!u#e)pqT5oep}qCi z;sfR@KgILvC%OPA%V1?FI0d4bzm6qY1}omqKYm)UEbNn6yb_KpeXK@mVOcMl)X$}T z)(Z9cm%^U24s_E2)iw`L)+-Q=*aw?MA&p<Y5thTdDAzLjKR6Lf~;h;_7p!HK?pXSCZ4u>CMx0+X4nMtjZhl1!H4pOv7f%USdtJiNa&ijMOdlQksZa zqBoebWeP@GZbgI3T0TyL*=Nk|;C4cjgPrfa;5s7d-F&5g9F9LVuJMP1ezw(W7C{Fk z18%Wy-&jp~g1KhdWu~Hbch)cyE!RjrqYs#;(&~CN>I&=waM7O0NSS55-nT9FJdIW` zFp-vrXRrb{f!98fMXMOT@^<x;!$=d-<2kru2g!qIX%wu=p*O;5H@vUA2#o%dQc%KS z49(5$P0Q;hKHGMj@14UGxqO@S7xrmP*RxnhO&W8{*S~e?tEee|9y!&DN{M$JB|*R? z*Jh+l=FTf(I#!*swY{5sUOUC$it>(?C2;BBD`UM;FcF4^;6Nhp$z_sXDUpLX<+xn% ztzNnCvPQY+O{JQ!bP2Ecea^>otKTPGzeS<~5p1rQY0sn)eMzw>;`blJ^Hdt~6x)x@ zuwKtuuY03g)bKnG@yteMk$%l!#ZgCldl-vXLhOB4iCRt1+H;B7<{OzpTq_x?o~raw{@bwd)RjPX`+Bm5z(uM^ADrOw?1~-eXE`N?BvU z?u%1xzmL<_5iUli5Lr&&vpW`9u)fkYu43n(94j*J+sH;H_xknbaJ0_cwYN>FsTI-& z;W9Qr%To#njOd#tn%ZG$z*v%#xDM?;n6oq%n|vi)^NL((D0R6} z{ULN7Z$xY5>g-Er#8WIkg?K(?EG#S=+*`uJcnf!lE3VaxpP&(-~0SAvB5I*5O2 zmI|31ZPgdM=N*hYKVs+cHRtxWe^Rk~}7x(QuvG8R$*AvUK=F87h z7zs3OpTmUOW54L*6bXF4j$O3>QB5{&!|qmQf3$!3tJa7TYFrD%(*>BQ+lroc?ZY=0 zuW>XgSU6Kllburwb9LH|2o3d_x62Y!_>EZv1j3oQ?)9G2SBNNLtC9SWG$AiQ>p`(9 zIGk~q`>@`t)>7;$6#7ipjZ@P^qF1MgoOO`1^5%$>3zDf`?M_{0$p%M9Q zq+FI>F_DFzpP$oX(}G=UU@Sa3+Je_=qCT{XzKD@+B@6RfF2!h}zThqxIFM)W+Awrb z?)8e!QuCu+-++>;rDYD;x$-yR364B$sE59qqQ-%jZn_#yS3AARD%;}~3v<;SskAqo zX5^zQ2!sFJ(OQ`Np~i2tvhhYB;d=BV-DnCG^VJDso%Ff(Ac_W68)jkZ%SGA@iiP_c zJ_!+2L#F03c6v5OY|?Ca49WVT`UM%peQs?}Ym{Hrz8_hW2&5mWakHl>!u?qDEoe;N~PCHsWH~Bk1u^4(H` zE#g%eP!C^z=g-5}P7~t$WE}sOkp^Ywf%INYg}bA=N~)KQj^B~@w!v=ZOrQZh-P~$J zeUe=y=+rQ^$YbFbmea{Q-}lrSUBS;>dy1vCwFV{W<|>;FPCndt-|oXtB1GL!(7dP$ zlLwd3iQO?Q;NZ2NV9C=gs(9ooy4fSaP5R=+i{%P1@@&L-(`Bj=v7!-FNNN5Gzw^AN zL%*S4->AFIZ_nRy1^8=rUNHszdJ(nz=aOE?!PR_W1-IJwZv$`Lj&?UN25zw$9@+cy zfjG^Qgt+Y=oQ4$N;tFaHxv)nIxURmAy1=kuLRk5AgHfh6HBCaew5qFXg?DFnH_`aq zqK*k~?9cg^>yIBl=CK&bQDqo1`$IHpfSJcqeog8u8NZmp<=rh3Q(mNW*Y_Jv$$K;@ zmsT$QFZLYz(-%xLW&L+kqW+WI{~!WypyWHSI#yK*u8?f`N(C+|%&=hYf$n--Utb?< zF1H)ksdiqVhHhB|*WZeRnJ41gBKlwyjAD98iAuH05aF=A8L|jGNUQ@;qmofXVXyRA=*NLOmLbOG(ts#-$e%|B!fW@Uf6#t&OCO$0Qq#1L0fKxm58biMzz3!i*$6bT20zfEx zbB}af+Xwd_-UgFuEO)_e)h2tJ3tPD3A`jP$uHU>LKz6Qd&%O5F+?kkqjSGLK-?Tl1 zW_@JEo3kcasZ9=7t&bC*bYOO7hfmPypmFooGvoN4Ck{?*|E?5{PxLgGGw0dRP0E41 z?CjuIB)rcZ7qn8IJ$r`Qs#(*wq?P)Lj@y1hucV~J=7FrN?D9^|tBh~qr4KOYB~A9O zZ;<+=J{a)peNqDlcgnM-DmYi#Pu4rIv&~wkL+t2^8E^qPPOjLSU2;w*dql0}2TWFu zr9{R~=aiwF;x00;KUdl+#z|{+cXT)_4ubiqUDDZ{E*BASa2r1@E$!2z(Z>OP_%JYC zXp1Y;eRaHM2*n|-5(S0*iHxL}+E%Ue7XgKt9GrB$up5FQqVCjwa3i#xNIh98oP&jc zyZ;u%D2HJ=bDk}%RRuGd8rqxX)@jPG3 zMhC6TtZ0x;SwGrs7fki%JVf<3GBU=Z)5M0;l?Wa!ouIxLp~rsyjp<-e_B=#axH-N4 z$})*zqsFa#d`7i1Iypr_pn8{@>(Sxb50cp@<&$kN{P=;GZzr?v0C7LUzUR^uJ{)R z%4%x$5_!aWECpTTC@re>?CGto$cUDHc=4QAGOjdgb>ju7ga6+ghxT3BT0hEH&n&l) zXJjL-G0#}Xm;zsug)Mk)wMIOruJ6@e7K1JyQF6L;CKz zEH1eoqZ1HvvcM*~7RS9l1*Z3{ ztlird(fG5sxY>Cq`cq3xAHM(DCsce3yAPOT!HH&3?3c+yhvcT5z8{@aF)dWOcf?gx zJj^C4s}O$A?0&`z6`i}`{DCKh-xh#;gBs7L|NH_e0iPhhjPoat^o}6>Jp-{6QvS>o zr4U~-mN&9BZ~3lU(aY_DFz+wkG_J5T-hhtZ_7Xu)-B|g7-jU`{19OiW+Q^6I)Izw5`nA_sN%}abxJ(*E^{SPi+ z5e&b(F}J=yroq|$5`Qmi%iYmRyjHN`%k#VLc3@dA_zk=~emfeyv^IS@`PQ zU66l*Nrg)fyP27{pZwCf#>;0a8Q=#w?gMHD>U68Ih3nPvlbqTw z(e5BmTEtu|v+SkOCfOjeFip4Bi0ftxagj_-I;O1)&seSE2%7(m1%jY!zFtP2Xw37c z!`+_dO9{oxXMWP`!U@JVd_Y5RFOOAm(LUbWQ+kHu<)cz-7!-3wEq3-C{>#Bx7A}$O z^WvUaW#MKo@rgtCn{NLjSnvRp8%eN#R{(8MrJsU-diz!hCl}k&uRuy3Xf(5&gIZMW zTdk^hFYyI#&~(bF{Oy4LORHD!H-ZC{2Z4br&BH3>YyH6_ z!J0ms7>aOgL#7IUylcDb{$Pmw`c5aYyG5Udw(r~i6A)Y@Be0%=bh7n-v>8LP81BS1 z_mv>Cy@u_lz{8dx{A!b*sLU$LbevhmEo@(D8CsQq!FtRZM)w?qt2_7-1HZP)K>=`% zoGNDiLt(iyWlrCc(;i79HB&ymZ{jMJ60RO|BU`2&+O4qZX_M^h49>}z(TnLCe_XT@ z%&QawTyF8l?txOZA;R_h_jRM1FcZXehE3p%Xw!BTmv8crF@{N10%gt{Z0RSfNiU9n zAbxni1mbc*9>EIKB+CZXNPh!F#|uT^N^>K+bscqEy}(MMUELk;0$m77}`w03=%2fH#{lNc0W=7UdIg_O@EHX!aX?EeAgpQv2{k1DjhP(>aPYU7@uU>&)xrKW z!2s#Oq{pb1%Jp{=E4=ammXo<(Gj*){A+5D3yhRAz`;uRVBh#1 z6P}b@@Yz{^@^7>PDQ_^SDdFt0CZn8C!xP^y6%NYlSthOj0rUUaAn^0z;99*~GnIa@ z6Oa6f0-;w&gC~U2{lgvk^W3k$Fsgt&22aAUPCRmQ6$+4T{r?L;d0x=j|Nj#|DI_Q4 z_Wz6eu|+uj&;MJ;;c5{w3Z@G6@`^@ak|Za{?RDRvo;%<2*E9S$1G*eQQ@rJlde}Eq z=jo=~9YiMB21f6V&Me8HEndl?PsYQZ-@ZBI^wJgQ)y^FiXEbWP#tm&(FvuQbD0vUq)c}wbBq-7Sr|AAiV=%CR zv%2?y z+nk3!nK_0HK350`25z*;Q$a335dmi3wSiOkmWj>w7OqoavrrWWnqA?^@4(xT$Vs0+ zvAz@Ujavx($mJnHiK^3f_}6y*zaK|~H~r{RV*3@{ocuz8o|XWp}9Ihz8q-$dV%Odh?)MjdYQ}8U~5MV7nqvI8VcausQ5P1C-z9W8qB>lUFgkl9Mm?4N@leh zRnVYZFqC*$)W8D{UDi)XIARP9=5hzqVxWrJQk4xPZ1K1~@ONOQJX=Oa#+KCoDep?- zp={rFSxQAE;Ylg=B#&$n)ibt{Hqjt0!WfdQ6S6O3N&i$rgvh=o%P7lOhM`h+W3o() zHH5K~C8GDdds3eF|MC6!_NiZ*+kM}2UFUh6$9bIB5%K5|C(Ya3)HDU?rYgiETfLh? z2qMc;bNWsoI!a?9Ep6@n$N~M(5aTDwR##Ww9%|fAn=ls@6_o)xdl;HV0U^ww4`7i^ zVmt{6=^vscInf5Y7pD4B%&4()4aSH&?RE{H<6SPQv96zYxmWKxdh?v2pz_P1+YW4Vw_}xJ!vjA*ZA$d>Xqds(=S7`xk^E54pA?^#&iC|zPS9$Enorq!wC&6 z1wRhP&5gF@TRj~V{ZZJe@P2%0>^n45kNb4(v!)+`Lr4n;dww>|Dsj-_xD(fox)}MZ z&*WylPwD2~3_#j?q%=3^XIWdZnOZcZ1}Mxn>yQRozI~k;=y~mX;gY}Qes2I~b+L+! zl|R3Om-Z7_uj&Q{(GrQ2F0fv|T`l~y3aIx}LH5G2rjnb0=N2+x%WFwpNy}98s-qdo z)khsKP<815FKSYLs8X##mMV6@6Fl6kx6l$){o3sTK!SDanR}eO4nRlGp=Q#BU6x~-Vj%aD~E=<1NHb5kg=SZ;TogVCT z?jGYmLyoj$c9IJ!Dk~X|bgw+IZ{R;~LN>72{$rw_P1We#L*6+Veyl?>YF!V{8` z?V4M6&~W5(izUppB`ObH(k#|&f-v1lb{KV9HrCTA^IYy=V8w{|c9XMYI#NIS7;Vvr zL0vwEZ$FrHCLn}QLeHgCfhvgecnF1dymi2_UJbA-Eb zlgbMC;MOFoJ+W4Q!F+dn`M!O-#d8>xJ94RVW6P^AUzQAJn^V;JX?Cabp_`edpE2KXUCyr&sqFQ4Q zQPFn>?TBM7mF+VM_mH?M^q8f+rIVrjZC0TDQ+3OM&ZFk#x#EwVy@B{ES6d&m$kDq{Q2{vQ$)1c>=S*GwZ-wGzzlFNL2|?qc878T*WRHM@1S4h zfNP(91k3%9F*|G~4Ws47S(%$a)N?i^I!<(TVirCx5>ptMFXBxm29@N%7CchlmRqbJ z!|H-Jly5xh(zCLDH>IzOhN*+o;xi&uN-(M;jOKU2$ym>e*^YjcmJhzaH@WjgNeVC` zJ)!W#~9d-+6L*@<%)+o|HtZ2Z#14AF)tQzv1i|knD;{OIv?AG zbsZ{neda-sY9bIPZlZj4AeAV`J#P$=>@szI*AXLcLB_%gcUAHY zwMppY$&+_3PxAIS;OCFO#oax6kpQ2(Q=Usz5~C{2JmT_XM!1y7&yo}#3sX~YrEX-dclIdUuiNrWPe=KJ`{#7`qu zp>1oMwA+^xNaU6KuJZSgBlMx90i)At z@G`8)$fg`#RIP&x4NTWcW!wE7Ybtl{BSb>uL)&?I2PA1Pp2u2}gU_5jTl+lD^Dyy2 zhXFMQzP-YrEXo__T;>6!Z}Ob&u$b7GvlQNrsNC8-*L_!^HoExFe$b~pT3=%p-^H?6 zskV{kOo$}L29Io6cyRMcw&&gnBvRblJY=s{W}U73>P;X|ibRS-or28+v&iGTaIOgY z#FjiOdIRSA7l;tm1>K%vs8>;9<~<|sk*$6cH+wy#W_B5g6By?o@f1zcy@Ddp+BXgMn|pn$0o|YcUjG18Dyt1rlT^X z#C7XM*uLyrfN+rWn)(ETQcK0eFpn<0pbuXAT!9q=Xl8!jo5XCsm4tG7mAw;8+nnWW zR#e?L&~r7sqFebUTb?w$G0@dDXXQe~7?h|VE54jPFQu4dMBjHaU5e;GoP4&JI@#D+X}>>AlA3(uY2U7yGPVy>08FV%gPDIBD{ zQdnO}*dc~I00$cp9JXn8XtTPA{Vnbz@HnrzdP6u)c>@6DD6F2%x{hawe^!8zNyMc( zgHnkSO5!YqR&6rCpmF>UIU#0qrhWnDR?$GX9ySp)0n@O7_c@FIMq4kzLdz9Avv1Tt zlNcO5kc{Z|MiCAN$4X=&$3 zw>l3)&jygd;)R5sujwGHz4`+D zn5)}ewR-gf2tDz;ev0=&k{d_W@W1Zq*WGPLT0?K=yR>Bf^{HQ<2Q&&51^=lx$EUDl@O>+ct*>ywis)0SiEkA3LxFDxac3Cb2J z$oX7+hoz+W>k;d6Fmw}$juZ3kBsLp1xun&m#TKO6h6(xo(b_f>LNv-l>-N?ktLLf&fBn13)xw^(H{H8nXZuewUz=}Z^8%F&y3k9XfHd`)RVGt;z_49Egs z7T@o-sdA)a&3y9_K_tB-I=wGK+T=z@q1{Do?cUkq;wg{`?#v>S+#Cp- z0JdaB@(XR5Ag}{-OcCTNrUNx$ByusuQcRi4)&e9)*?3Xir&po{l1qkDqgb|<*mNru z^##gXH;#d&{N%GT9mnSIV6VldIP1yW3sJ|A;8F{q+7v`8GNASXbZ&3$n#Vf?X{t0l zD`7XQ_C3T^ZM^6C)_q6J8unCEsRdbArHcA@=%4cXM}ad-$4Lor#2hg`shUyo_4gxi zEbuk*#s6ww#7nXqI`Ulc-01c9Uo-VURo2~fL5y~o=U{$iRJiA5oafh+?!F7&IW>8U z4!F0D5=|`46R!E47RAks62EQx#%FelFwO6zUxuP`uKm!$wadD?x_yhOEf!(B&Xi-F zo8FbYm*#5QeqUw}XfqFk$S$15>8O=5q1Xf!Q97~k(`ItF!^FIvrlKcc(#td&?XsPn z-DO6B&3xS*1WT`OZk9vnEn3~LjOTtX4{!eUJfnFgZcItRr#h9kB@3VYOZR+jN+pjM zt3z#ajjTc@bOZXl4b@@X)=6D=kied*d>5@mDDF(>5oMRLP``wCd@&3TtNGb2-}^2J zDuY36TbWl`X|$7%rn-8DrvWVd;uEhzD0t$$ewAr z88WP!@^rD`gW8l3%$|W~+=hNTIBsk{wM%KChgClrl19VxaptX9J}RlHe$qeX${9FET#39 z3jsFkX&iTvzh#Ym@0S(34FR*Od1F$z+#!l`tIxM%*wn~YbYTlCl^8BV zasoB#IMs>JI{ty!4BEsh+LPTKmHd z8jj)iF=Gb$CYDy`s6y?LX0f8hC&H9g7EGcXH8dW%Y~WMO9&`{?%pSlmm%~wYS+a5| zsi}MUIa|Fy*?7+Ewt4=w(`j+|`BEp2@VrcBCogZ&Ho6h9EE(I6Rr8aZ43jJ#IY<^{OmTnnisOWpWg*D!>CT;IV zGD|#4DJ8o#BOx;h!#SIQTRxu`mXcciL_{6j+B@W0&5RGu&u-y~wc!1Lx=%3{Xg z3gA*ExpQJ>dV16iC|nP?PZ^`~b!+;T@U5Dsp*t6|#B}sO)2iaNopE}h)uQdk_XmU+4=}(a>H2Qq3PC&=^|=KZSE6M0 zD7Z8dmche*zPNyw+RJ5N^2|-1h-Z+->xu6DUFDnC-~}#_#k8Z*n12*%LLqF>kMC@m zwH6)j()AAmriL7pZX_sHCJ*5RSRaHY4`*U(B@JIID7<%JSx9lj{u;(n)T# zJp>#>#szaeMdH}9Fm*XLOC=+&Z`b2F`en*m2^?&^V~BPpU`OR@Y~!7@o-HzdyI~mO zV2mkL6=qbL-3d*_*=AH6uA9fN~g)jS9>t>o4lg9k7|TSD5e{B&2)p zS-Z2+f&eWorrG_JKye@L`FkpO1A63Ho`3#G2_^>hV1tTpm;(9Mh{hMn#UmqyH|qt8 zK0Oq>0sEbFqJ3cb>tNjc@H9eA%6Kf;;!e*O5$YnOm0$@;r~=QqgaYm7xTB32)HCDt zkUz#}nPLK$TKE#%FBs}4t{rmbNCuXX^@ZBcxhh#ZpA2I0`De$!_s%!D&U{ugH8qW~ z{06_zKSSREYj!BR=|3fVqGMvly3#v)2`NS`cC^IPA2O~=IZw_6d3{SNnXVC2@{Oa^ zFdmQ1iu!Kd*TZa}IF4K?dph4Su}hce8G_ti@xi{;J^dzI=xBktYqQdwF?HrH22eY0t{A zB?Y2r!3_>XO#9}!fv33ev-=2nZrYY5Wxe-yCue46Hu!J2n(=%wJmFgI&D+3TwT*)9 zx3(gquZui4@{%Q1b;};-$F6;@%1{aYB(GKxFV_xO!9q%yf2J>mrrE~JzI)PyB2oe7 zoGJ-uTNo!#w6{JYEPe@w0Hp~un?#V}Tm+$I#$i;G>ofb&;eJKpI3srbaT`@Ym6v4o>oPBr%`zzZFu@z0oDqN)=G*7vWv{XD};loi1 zVA{?RX<|U^{9DH$gQd0eRq+Wd8h4ttR2qIp0~Yo?@*D!pkb0Z20OdMw`8HPjmamsEKXazfIljj1?d|M_ zWD(<0u`08`CA&^5s2XxtYFyw9AlcXPHDYaHv1C0u){}oK2mX)T;06 zo1oz%t_pK1b#cl#hmvL(V0n?2_R^$;dGLY&ry%H&Aw2fqeXWUC$uz031j|INzg!EC z{mKVu9$rBFJf*KLZTW#XfXfbj`c&Q1lY$HY%}sRMkZ%=O(J?u>xt*t9WM+oKx2)&j zQ3ZXcNFb)TLW{O>ym@H&9kyI}UY@MHkEVx*M^<*bE>m}8Gy4!4FG_|!=?E zrgTca8g#07Vp0tK)EgD@jaZ| zw&&Y)cQqI)6BZqcRu)HCLuaPi?&btmK0WBsZP9Z{zu)uw^1O`2hl9Hm-5eJ9!q?CM zvU-sG1Lj(_ZGXbT%UB%^@2V>t*$}i-3qaK8(N}Igj{>?gZJ_33t zKg;u8u+os-GtOeVx=^99arc5$$>g2V&(QDDe|~M$SFiDq$18}4)v$2}K)xOZMZ~e* zXBXvu6$(CDTN>Gwnw`Bze!?1b727RfiR8JP01)h_8@l7GYPc=Hf?*qG!SwDs)#1K}hdq}_GuXE+fp>D!_ zOrCYy#dhc$-WXAXGdx$Z=^Is`aa=k!p8uuPTvP7CQ*Y%svLTH%?Z&^R+kO{ny@-}c zVVpJP*9CuH8u{Bs7^6mcpa0*-ul&5g_Pq#I(x;@g`PZvih0H&$2WJJY`~UjOd%myl XrZ-y(-q6fi2Y=K~V@?rI8r}IHW~>r} literal 0 HcmV?d00001 diff --git a/doc/_book/index.html b/doc/_book/index.html index 57db65f..4b4538d 100644 --- a/doc/_book/index.html +++ b/doc/_book/index.html @@ -22,6 +22,25 @@ ul.task-list li input[type="checkbox"] { margin: 0 0.8em 0.2em -1.6em; vertical-align: middle; } +div.csl-bib-body { } +div.csl-entry { + clear: both; +} +.hanging div.csl-entry { + margin-left:2em; + text-indent:-2em; +} +div.csl-left-margin { + min-width:2em; + float:left; +} +div.csl-right-inline { + margin-left:2em; + padding-left:1em; +} +div.csl-indent { + margin-left: 2em; +} @@ -106,7 +125,7 @@ ul.task-list li input[type="checkbox"] {

  • - 2  The OBITools commands + 2  The OBITools V4 commands
  • @@ -172,8 +191,16 @@ ul.task-list li input[type="checkbox"] {

    Preface

    The first version of OBITools started to be developed in 2005. This was at the beginning of the DNA metabarcoding story at the Laboratoire d’Ecologie Alpine (LECA) in Grenoble. At that time, with Pierre Taberlet and François Pompanon, we were thinking about the potential of this new methodology under development. PIerre and François developed more the laboratory methods, while I was thinking more about the tools for analysing the sequences produced. Two ideas were behind this development. I wanted something modular, and something easy to extend. To achieve the first goal, I decided to implement obitools as a suite of unix commands mimicking the classic unix commands but dedicated to sequence files. The basic unix commands are very useful for automatically manipulating, parsing and editing text files. They work in flow, line by line on the input text. The result is a new text file that can be used as input for the next command. Such a design makes it possible to quickly develop a text processing pipeline by chaining simple elementary operations. The OBITools are the exact counterpart of these basic Unix commands, but the basic information they process is a sequence (potentially spanning several lines of text), not a single line of text. Most OBITools consume sequence files and produce sequence files. Thus, the principles of chaining and modularity are respected. In order to be able to easily extend the OBITools to keep up with our evolving ideas about processing DNA metabarcoding data, it was decided to develop them using an interpreted language: Python. Python 2, the version available at the time, allowed us to develop the OBITools efficiently. When parts of the algorithms were computationally demanding, they were implemented in C and linked to the Python code. Even though Python is not the most efficient language available, even though computers were not as powerful as they are today, the size of the data we could produce using 454 sequencers or early solexa machines was small enough to be processed in a reasonable time.

    +

    The first public version of obitools was OBITools2 (Boyer et al. 2016), this was actually a cleaned up and documented version of OBITools that had been running at LECA for years and was not really distributed except to a few collaborators. This is where OBITools started its public life from then on. The DNA metabarcoding spring schools provided and still provide user training every year. But OBITools2 soon suffered from two limitations: it was developed in Python2, which was increasingly abandoned in favour of Python3, and the data size kept increasing with the new illumina machines. Python’s intrinsic slowness coupled with the increasing size of the datasets made OBITools computation times increasingly long. The abandonment of all maintenance of Python2 by its developers also imposed the need for a new version of OBITools.

    +

    OBITools3 was the first response to this crisis. Developed and maintained by Céline Mercier, OBITools3 attempted to address several limitations of OBITools2. It is a complete new code, mainly developed in Python3, with most of the lower layer code written in C for efficiency. OBITools3 has also abandoned text files for binary files for the same reason of efficiency. They have been replaced by a database structure that keeps track of every operation performed on the data.

    +

    Here we present OBITools4 which can be seen as a return to the origins of OBITools. While OBITools3 offered traceability of analyses, which is in line with the concept of open science, and faster execution, OBITools2 was more versatile and not only usable for the analysis of DNA metabarcoding data. OBITools4 is the third full implementation of OBITools. The idea behind this new version is to go back to the original design of OBITools which ran on text files containing sequences, like the classic Unix commands, but running at least as fast as OBITools3 and taking advantage of the multicore architecture of all modern laptops. For this, the idea of relying on an interpreted language was abandoned. The OBITools4 are now fully implemented in the GO language with the exception of a few small pieces of specific code already implemented very efficiently in C. OBITools4 also implement a new format for the annotations inserted in the header of every sequences. Rather tha relying on a format specific to OBITools, by default OBITools4 use the JSON format. This simplifies the writing of parsers in any languages, and thus allows obitools to easiestly interact with other software.

    +
    diff --git a/doc/_book/intro.html b/doc/_book/intro.html index 5f78c1e..43e98ea 100644 --- a/doc/_book/intro.html +++ b/doc/_book/intro.html @@ -125,7 +125,7 @@ div.csl-indent {
  • - 2  The OBITools commands + 2  The OBITools V4 commands
  • @@ -525,7 +525,7 @@ window.document.addEventListener("DOMContentLoaded", function (event) {
    - 2  The OBITools commands + 2  The OBITools V4 commands
    diff --git a/doc/_book/library.html b/doc/_book/library.html index 8b2c379..005de52 100644 --- a/doc/_book/library.html +++ b/doc/_book/library.html @@ -168,7 +168,7 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
  • - 2  The OBITools commands + 2  The OBITools V4 commands
  • @@ -200,6 +200,13 @@ code span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warni
  • 3.1.1 Creating new instances
  • 3.1.2 End of life of a BioSequence instance
  • 3.1.3 Accessing to the elements of a sequence
    • +
  • 3.1.4 The annotations of a sequence
    • + +
  • 3.2 The sequence iterator +
    • @@ -261,7 +268,7 @@ sequence

    3.1.2 End of life of a BioSequence instance

    -

    When a BioSequence instance is no more used, it is normally taken in charge by the GO garbage collector. You can if you want call the Recycle method on the instance to store the allocated memory element in a pool to limit allocation effort when many sequences are manipulated.

    +

    When an instance of BioSequence is no longer in use, it is normally taken over by the GO garbage collector. If you know that an instance will never be used again, you can, if you wish, call the Recycle method on it to store the allocated memory elements in a pool to limit the allocation effort when many sequences are being handled. Once the recycle method has been called on an instance, you must ensure that no other method is called on it.

    3.1.3 Accessing to the elements of a sequence

    @@ -330,9 +337,68 @@ sequence
  • WriteByteQualities(data byte) error

    • In a way analogous to the Clear method, ClearQualities() empties the sequence of quality scores.

    - -
    + +
    +

    3.1.4 The annotations of a sequence

    +

    A sequence can be annotated with attributes. Each attribute is associated with a value. An attribute is identified by its name. The name of an attribute consists of a character string containing no spaces or blank characters. Values can be of several types.

    +
      +
    • Scalar types: +
        +
      • integer
        • +
      • numeric
        • +
      • character
        • +
      • boolean
        • +
      • +
    • Container types: +
        +
      • vector
        • +
      • map
        • +
      • +
    +

    Vectors can contain any type of scalar. Maps are compulsorily indexed by strings and can contain any scalar type. It is not possible to have nested container type.

    +

    Annotations are stored in an object of type bioseq.Annotation which is an alias of map[string]interface{}. This map can be retrieved using the Annotations() Annotation method. If no annotation has been defined for this sequence, the method returns an empty map. It is possible to test an instance of BioSequence using its HasAnnotation() bool method to see if it has any annotations associated with it.

    +
      +
    • GetAttribute(key string) (interface{}, bool)
      • +
    +
    + +
    +

    3.2 The sequence iterator

    +

    The pakage obiter provides an iterator mecanism for manipulating sequences. The main class provided by this package is obiiter.IBioSequence. An IBioSequence iterator provides batch of sequences.

    +
    +

    3.2.1 Basic usage of a sequence iterator

    +

    Many functions, among them functions reading sequences from a text file, return a IBioSequence iterator. The iterator class provides two main methods:

    +
      +
    • Next() bool
      • +
    • Get() obiiter.BioSequenceBatch
      • +
    +

    The Next method moves the iterator to the next value, while the Get method returns the currently pointed value. Using them, it is possible to loop over the data as in the following code chunk.

    +
    import (
+    "git.metabarcoding.org/lecasofts/go/obitools/pkg/obiformats"
+)
+
+func main() {
+    mydata := obiformats.ReadFastSeqFromFile("myfile.fasta")
+       
+    for mydata.Next() {
+        data := mydata.Get()
+        //
+        // Whatever you want to do with the data chunk
+        //
+    }
+}
    +

    An obiseq.BioSequenceBatch instance is a set of sequences stored in an obiseq.BioSequenceSlice and a sequence number. The number of sequences in a batch is not defined. A batch can even contain zero sequences, if for example all sequences initially included in the batch have been filtered out at some stage of their processing.

    +
    +
    +

    3.2.2 The Pipable functions

    +

    A function consuming a obiiter.IBioSequence and returning a obiiter.IBioSequence is of class obiiter.Pipable.

    +
    +
    +

    3.2.3 The Teeable functions

    +

    A function consuming a obiiter.IBioSequence and returning two obiiter.IBioSequence instance is of class obiiter.Teeable.

    + +
    @@ -473,7 +539,7 @@ window.document.addEventListener("DOMContentLoaded", function (event) {