From 27df9ed4d6172b1c9e1e1213b1da9c7d7c00051f Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 14:56:32 -0400 Subject: [PATCH 01/24] docs(deployment): add console output examples MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add dry-run and run console output screenshots plus explanatory text for issue 147. ⚡ Generated using AI ⚡ --- CHANGELOG.md | 1 + docs/assets/images/aspen_dryrun_console.jpeg | Bin 0 -> 89531 bytes docs/assets/images/aspen_run_console.jpeg | Bin 0 -> 140195 bytes docs/deployment.md | 30 +++++++++++++++++++ 4 files changed, 31 insertions(+) create mode 100644 docs/assets/images/aspen_dryrun_console.jpeg create mode 100644 docs/assets/images/aspen_run_console.jpeg diff --git a/CHANGELOG.md b/CHANGELOG.md index afc95d5..401b6f4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,6 @@ ## ASPEN development version +- Document successful `dryrun` and `run` console output in `docs/deployment.md`, including example screenshots, an explanation of `STEP`/`OK`/`INFO`/`NEXT`, and explicit links between wrapper messages and `WORKDIR` status files. (#147, @kopardev) - Add attempt-aware resource scaling for the main Snakemake rules, document how baseline `cluster.json` resources interact with retry-based `resources.gres` scaling, and fix dry-run failure handling so failed dry-runs now exit non-zero instead of reporting success. (#152, @kopardev) - Detect SLURM-killed Snakemake child jobs in classic cluster mode by adding a `--cluster-status` hook and `scancel` integration, so timed out, OOM-killed, cancelled, or otherwise failed child jobs now retry/fail cleanly instead of leaving the master workflow hanging indefinitely. (#148, @kopardev) - Clarify motif enrichment outputs and interpretation in the documentation: fix the reported location of HOMER/AME result folders, explain how ASPEN reuses HOMER-generated `target.fa`/`background.fa` in AME, document the AME parallelization strategy, and add simpler guidance for interpreting `knownResults.txt` and `ame_results.txt`. (#146, @kopardev) diff --git a/docs/assets/images/aspen_dryrun_console.jpeg b/docs/assets/images/aspen_dryrun_console.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..b06792f05d5a0891848182bde82f1e9a33f5555f GIT binary patch literal 89531 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

6w;$M;4>g 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 z zkdBCF#{Y89HZ_i1sFT%Q#N%f+x-`cIsA7?G{#FFd^ngJkBF;cmNW(ZtMjc#K;W=7k z;rRlD?LO*Hg@)0u#=t^Ok}&||iL`nwXZ<#qvY`)c8-54WaX5OXuRAc*BZF=J)W@}? zJwR;h(yoSE+nnzg@?Av09@&C?JX7BzSjYY&`)8j~1EVP{dh7U= zrmsXpL`2!`+d8lh7%Yz3R9qz+x!}>^JR%)-&`Yd|I*ZA&Ax>TYfegn7I~_tlmYKa4 zepc0u5lIv1M#Za<39vVMJ-ga`1prg65p_`OI<=7;41 z?%Ws(ap`jb(>>p-9BjX(E3)wY42R?EVd+@zkFG zY+CzwsRC>;7b{tXeS?u8jR_f8ECI6naT zgbrdot{!mj=jybo9({Q8scoEpY0u zP2YM_xjCu-f3z6;PaG=>FaC|SgQXPk+2;YvcbVxlU-?xD9`la93pln$cS6IE3;0eh%>4`|dSFTKe=n*izDdw^n*JX58iw$_N-y zGMwexbaE=l^I=zHQ*H4|yu+3dV-0H9NK1z|m5m+iB`a%)rV41J_QgOtJy_axhAc6K znY5bUfo0Gq%Z^aBXiW;U4v$}rNH}8t7r?O%JH=zB>sc&f*eG8fx2CZABUFYQZ!t-1 z*;#jhc~Kp`udHiX@Bc2E5|^R;=E(!cG$UNWmQ_9ijc<9nLezdK=5d|bt{ll#8p|7b zuZEy20x$YXw>iD*9!RyRHkW-cqMg9POqTIAVjHZnpXrrIdIA+~L-k+W65Hd}>INjx zu})5(1X{X?5Ft$LIE!3o{`I|EAkMx$#)a>~DCulKQ4s7)UG!v6cZRic6C&t_!y!te zpPub|I+86B{kU@CpO%Pd-r%c!vbP)i^9R$GQwq#fR7Di_Q$hH z3cpR8KB-+9Z_~h#)Ili9@)9E6@3}szkt1&nh#d{KwKMQS^VIf*bVAxKghnioaGNCcE{0MC+QQY;6&38Y(5k_=6L-a(^-VSnn-) zwBOXN1|amKeZ$zubnznc^XSBMDc1*tzl}$iS?iC`FYLXF(rW+4qF zju~5Ny#;P3Hd3?hvWfvvwUhgw*jLO>M;!kkxa%7i81Z7#{DN22-Sk#PoWE=Bi1)i{ z*t;p|6UwUW(7^UfzBhjmbRqsAc&7|~U(*mQ`MOr2Z=c32^CpGwvTbQ$B3IKSH$fv| z22uZPQD*X_w^uzQ=aCU;(+&pDQ!mU=84>NWkhGy#31*L6W@B1z1u-o}ziQtVRk0|S z)NuP5tmKk#yzfG7DEdkWroELEDTZ=L?UXC0-bnlgVbRo`yH%ewh$y>V`*u!HYPE5G zJI3?NV`^ow09g~H@kg$v#9h|{WMUdjQekrm`r}2tGknEU?){pqV&Ll()JfVO1QJDd zhx6(ty$f%JC#dk@&P#X=5EF}1cGDBZUbK>eQ!HVbIKcZY1NpqRqD~)sVObDpvtZU* z+5L`nimtUPes^D%5+@*YP&-rxnuB~4ij z?$RPPY{RdL-AE~-;YHrnv20Q?Qk26O_{u`&x|QcM6wa*z1uq?)pzO*oaZX-S>rs@Y zb6rl)*7iq^YTi&uTipg5&3leC5dv! ztdOoS&1FWZ?WSwb6+0e(BhMNa^EiO46yh9x70Ed2kiETl2n0bmzGiEXdYmO8tXi~L zuU;yC>$FSJCv9HOlCJneVUJIY03K)&Y94UqkYE;>+vHd#m^c#y!>dv;pET?$yKRG_8v^fJR@K`QrF$9^g+fUpM1Cw6 z$?Ns+k{E2r5|*vj>N{!}e%qT(tlNVLf0=W96a!6B?ZZhi=4Y2Dev&THV&orf7Q+ZO zOoP{lI_D2*)?8*N7`_ z{Yxy5rOhHsSd?E=ByNU2N22r}3o&?R2gEnk?8R3K*3OaMJahfY)uhwBFW**mZ>KoR#c|Up( z<$F!<;?@8q>=TF2b!t&p*#;Z*y9tI^B@<|_NW=pYzo#mya;-**Xsm1C=n%rGJO;gS z>2f|nDSd!0^LrYqnkUlZxxTm2bcj=A8S%}$#aSAeHFWEH&Z{g^8vSm}>S`kat8#@@ z$668*@V{4orWY*u7S&&s)@rrM`+J*O;RBL_Nnno8^w1*RA_ER_ zo&cvFiHWaA_Nd^xBB@GgsE7+3{jNv zSAH{)7^v9H?%dTm=b36&1gGY9tc+y?v#q5s-h*U@wwSG7j~i5vS@0=q3b(%>>5P2~ zxak8`+~24osa26)err?vL#9r}WRWU6fr)nkSz0c)&SmVZh4M8i2iXM!YAf2}vw>mi1Hb*_~Q-ru{Y)MNafb9UMLsL+?Y% z;7#4dU+mI0iW}P7da-xe`yMaDE;_SMQ^s%C{+KxHJ&sAU{ybUTdyOxGHP?0*cJ^KO z@d->uBVk}-yMp5O0N!!kY3sz&3V8W`7m45ecdMgN=|gDPMY5bgnbP*IQl4$fB-CH$ zha&tg9V=t+e&05vA_Rf#FS)|# zL!)aY&^3g1=d+_>kQG*3Z=%g?xxp!Kp^vWUqr2$n%CK4gDvM3(YNESv=3 zeQFJSoi2ixA2!E^?14Z5Qj`JrrQf-pc$c^0oLr5i8&B$lmNd9FT#s7)|3rrqf1rA3 ztg>5y1y|I&<%@G=76p5Y4NKQij)}GI2tf(ERK38AX&z%+w-ggMHI5}fA6u0X6(r8& zP|If{DKp7T1d>(Yp@|H?%8*#>MY^hl+77KWTT#NyP}r_>Lee(QosHF$j&BAjky~09 zdpEbmShOmcIL-f+vkQkeM_AIygLk^z`esEF*Bagia3h)0wh4pver*!Vpv9*=^97Ry5tdf$<<#ip|20p}TWI}JKs6s?9 zRpEXQnw2SK6W&Ob{YEz_V!-Ysazfk{nd?J_S#4H0B-z|tb_RyX=1C{ahkImruD~T* z@A9PgVJ*Ke5C+>H5Ll7E|16Pw#Ue(0v3O1YP~UaJugo{SvPu{8b60$DzBuA-S6hJB z9J~MPgkjhRuZiTctjvbVvNHerQleHM9<92VL3J2PE~~Al*Q4Y@a-qF3^kexC0;X-H z!-$cF&H55!V`b;EvZAKF!2lV|XW+0;{7m>Af6FqEU zHSVb_bVR*>qcWRmO-PiLc_T)B$ZEzsta73Gi^^gGNpCgzIZz1+L)=U~qJ27tv5$xH zj%iXe59Hcl@$_9<8h-4yR#z{gmJf}}R>lmeB`{Cu`5H8T0w0L(y3)Sc<&_(!ZHDKf zfu5~~{l;cO-xIY%2|S5r2?+f+owy20qVwR8N5vmH5BeEDn)eXlXOf*Pb^NX~x}(V# z%+M02QvS2sBMh7C)Q>Z}*%=E2p$#3~PgUOtMq3ZlLUGzj1&IuG`)#IK3XDS@oIOOzdVxGN?XGEi6)DeWGQ?)9);l#j)`JU}f>U%q z;N^3k+9Gd^ncoK#jV;w6Or)Qx&^ohw(oHyGdgA2DTPn@eW%ilVC$VRd z=y(a^PPWu{c&Cb_a1(LL+S<{H5NCu_8m7}Z66e&`PtC;cE432I<40Ufi;9<>>HvMa zH~_zC9>)pdgSfZCnfaUX$T)(3L{e(cn2*osjRlU@GXj-8YBd)wB)b%u%5iLgfSI=| zOfe6#u7BpcY>R0~PW_ebVQQ_> z7CYiZAUZ9t4X3N#HD46d?){+ci^7^@#L(77a>c$4vMS)ofVy|&%fN;<>3Px!a;so{ z4MpZ2znid~BVEC`X#{fAXkT*LRbjZnzvk|eb8Jl3X`+a%|DcGrpwqWYNLsTFh!^Si zv1_Z?DT@Qntw`B-lPa9y4!z^box3*uwX&i#RhZM6hbKY^SmlRQli?-Y$ zuOp)Gs~5?9x%i)nzWo|p`IWnI2y$oD2&SOi$)R4yA;k&m%EyoK)zO{*h(G<;=VW^N zA`XHKFBIpSK0Ns6Ar1XSn$6;OL)Jmg-}#q@b)Na>U)w*uajI{y{|herKmR~dHLgv< zVJoW6XiMjB^PZgL4+7BtfSmouIhV^zI8d8<9F%gJ5hb<|aZ*szCk9J&K&vzVXzJm( zDqH>6$noEe7ylD8#@}2OyzOd$GvUYhmRQK?Z--s-`kJq$U;g9TRT#XHNE1a>sKV@9E1;dHduW&Y(J5w)#UdcZU1Ac7w8e z_U{}ux3bH)#w^P}@z#+T5#x;0m|7@DL80L50B%ZjS~8w3D&R2>sF7M0AS&`V(q(;| z>WTpvglN{AwfJtS;5d+8mPU^qKX=7G?F8~0%*}UX?bMbY4`Dp-s`~jRddFmL$&I{euiI#|-h~Qryp}pf z8!I&9FKM5u3W=B6qY)lhg{h9}KF+LP{gpcvw!mht_NQbyQfbV5RKh>dm**<^k>dDfFs357qVT>?-ykB=KVj( zjzz7E4r75Nw!=^$&_4Xcvq_C!9jG(BCU)OXp_lDG-8!vRR%p=1xP)r%E~vh<9O@cZ z>WoP<8qn_acNFCRbYV*TY;xW>Fa~S7b9z}ME-`fSdGOmSMD;A$!+6Z-*s^Lc;9TphllmEF7#|hd?`?xROcqA{G~ScZ&-Fd)09j;CFvy(OlW-htI^E*~28%j6 z6(fpb4@3$FeYYnGaNAw3r^Et#>d)zwTX&6Bf!5RSToUKCG=044U*4I1$~2{&hq;XS z;BaQN+)yTvuiaVb9gg zg_T8i_3Dh&n!tqIFD9YBci5%4Pms|El@f3AU5_>|Eh2K8_4U-OijgIY$-O^! zxZm_#BQ7QkM?NN0mUZUB7Ky7gWA38|fC9zUqa$Mz3fP}?o8$zshR$7T(%GU z+-pEnt0MhM0^_lDryJ>0H-U>*Uq@BeHUAIl-YcxBw_n$dQX&di0fB%hAPNKl=}nLh z0@5LLLrn-R^rnKM(g_Gi2@-k>0!ipilq!T?0-^URT|sc?|IKf$x#r$$?`vP{Y@Ttz z!MO5{ykq43J;>j?FCrAqao~2kifebYdcH7!2e#HMZ?9^d8=|#=;%GJkv6kwsI4PEEndt% zIDVc&L;x~}4PLz`Ld?%u9C%Sp#*;^5PZ4=#v1~vzlaWqBnSZiK#F}bLdWmM%*0XMXw%SXAfI8Mnf{QCN1rQkX4<7gFJTh{kF?PnPU(gwUh zkQrIu>arkRKf}%1IsIE+Yb7Roy~Mh(5Q7@Xe;{^h3r#yRaGN*KXqAEoLg!I2sw~gf z6EWTr#DlW!a!ts#BqU8LC*tPK+Y{P3&@3MG2S#qHPt;4~30}C&*Ma=Q^R8lXbXsMr zL+vDwU~zr{9MS<$`zZwgiO;o;0}GdvAk?a&t3e#aC0z@qWPZdjYU*UY>hs)HJ;dMMN}ikWS#=X}}?}V3fvq@e9`&#v9+LUU6gTSdWvkua`|apDGmf zA5f0tOR|euG^`%0xPs?qh2xQ9OL4FTHWDf`cRqZSt;q+duT~5CaW}|77vF%Aq8^oCDM$)cbI)qh z+Ll;Va&TLp=O=6m`^VleaYM>9T!o z@MmopE!8i?L4*=u@!Hk9Z#jO;Q9RYX1ycyWbvCUdLxX4ZhTnJ`Pwk;zR1xwo%N~NS z-COMvPbN}KIwZ|Hw((Oa|LLu2I&LVMXPPY3>gK2XfpvQAhaU|Faii6JB4RX~T&;|( zawAl-v8A|+57YU&VtAKUR6L!DZB4MUavqwX}Tfl&)1=+8@gH7B(Q-dv|n)IrSP=gsn?&b`bysj;M7tq zsh>cMjX@qtNQ&!3vQjf*CBCk44s>>2c%R~zkYXPj{Nd|Alqtb23rBr(iA-3PSr4Xq zdggZCyu;MRm2K(V!@C8*u`r;VgBxl3?DLTWGJkNG#6J_@Eh0Q>WE3Hz-}u9!&rZl! zczae9(BT#F8pi;189EgigoH(CRhwF|vlrZuV`f-Aj$H*@Cr)Dy2dxb*PD@zi{OKf5 zTI52DEQm>JH_W8>SJjPsi+C^JdvTyI~Hl@%r%mw-#a^N@ zQtzx&Xf}3c5XU|AZd7tJ&yWRO)?ww%jqY33 z+I&Z1IND$Eu6kss<95!TRj|>QSaF&mFRAo1)27dMIh%zSoQ|?8&!m-<^4qgMN6JK4 zKXewb?x_7nPz2`F$?ciFY)FDgl4v^@hfY#-$6fKnTFdQTPmv~(+i|y7GSD^;vYx|8 zvEL3ddF@RE(6zB(9bt-a1WKj+ev$muOS7{hmu~yAYNVM^sG--Fh{mH5TH1hZ`9Z3L zb=fNDxF(QZKat}=lw2XjiYM#5%KHl z9M7QOV6P|M8o-UE4eFrb%%JgDRFyFycCCE2dQ?74O|&TC%Qi~U_ezIg_(^hWb?QQj zORi8H-lcR{(4$&sDs4kvBU5%A{i%q``^+b1eH-bCVQLz!(tr}unA5ej-t;xHK1aLe zQr*w$BJwroxX^p&>T41i; za41WMFkF}xjSol;Q^&|SHSDoUchoyh3RS@c98OkG4^5tciD07z3VUczAJse zj$6RDe8kh(jVFC>&MAD9vxt#u_iW&tYuuJ?hD3Sev8aWj)vfB{IanUb5OgRS?cs6t zxkiUbEZlw1zgEwU^gZ)S=kj;cZv~%na!6(xz|+=(O%sVzRVLaoacZMog47HT(ynnk z_*qaKX?{LTIcMB0sSG!4_26(AIqA}M)2O|Z46+AkAgjMfUke>!+0X$y;?_411$r~{ z4F<-d@+XDW8Zp}mz2E~)Rshvlqh>w$JVs_=KQeCWYc_-Uxjv~`HtLTZ^<*&RHmNk0 zh~1#vCL>+96QYalU3qikIVj9duJb%fTFxPbfsO`@gxgVyFd3{&mSA#QlowSxidId7 zE8ZjUp-uM{$CDhhjmXQBG>!OMuAl9%ej2&{MSNZpqz0M|l=9}-V8_=MiA8(|vvD@f z(fEFbr`p@QO$+0sniam#Dzj(YkYQA3ekXe`U2qJX2X z-DUxt`Z_d5d%tKQf!waTZmyFc*b$Fh9Gd6xnZ>B0k5 z8)a5{PLZZcbkO|549TFk?CO^GPCWQ#i?EUP&uPi|kigWeTR$5*c-(IzL5!EUYr+c1 z^iRUU@22q2a^3|uB``3mfkrbTuJ?>I^A)}tetl&_)`2O-XsRr^yJK{4@R=P#IhDw}|+wrEf)GR?wi6gKhZj5 ziX19wK*I#eMoCiQG!ai>_am4^HB$|- zl3a8x46mU?_pU^J3E&tN+xrX9cyQiw64W=aRgQ{8^J`7w9EPKv=fvYuUor!A`WZ#m zRpHKci7-=!3sn}wZgJ`s+oqA@lYEXMl~T6vZ&1Agb4kSqO7a1DY#l|=$N4__g9jE{ z5Eyz0^wFcuMs0lDF6q-d4}cUiI>32jI_Z5L^J#TZ2uBHQtXtMW@K#d7PszKlUq`#y zMrT~;v`2-G;I_^?U^tgX8ZefusSY;2NtT`cP%0YVsUgILR7hA3ad@Eopw7vV;U|B2xrnJ1j(b>AiMlKK!ZO1nf@P9Rj2qQ-knRiNaLCvUEWGW!z6-0GtyM85T{k=sLl894Ui z)M5)JbU3kt3SQ)*;%im-P6Z7lX|tM>5I8Jc0AD%K8Tt#zsz2T@xfG`FaPSsorCAJ4 z_P41y>6*MA`nYB=gb&(G#kXllzzx^kbQ~)@XylBjw(1ph-ST15f#&wS@|Dc!U;$kV zd`+a{_>M$940ne}5a9)tuowZBi^Ra_C$DJP*`t(65ZUlFy_|mLvv5T1;2I)!wVvHA z%`x^bpb+aSszV};(c0w%UtF#SxYND@D%dCGR!iSoJ+n~GeI$FK9#%q&##9>*Yu?PD zMm)+-jJxFy1p)8J(*bO+ZO+=i?Yo4z_u#+dvGf1oxiINKH?|Q*$Bo4gi9%q35d`&5 zkg4lo0XNZabtoqvELM65!gt5lRhsmDL2bEk;Y%F>m+6PU9y#;8yxu$8 z{-++`MA5(i%-!eo%wM9PkSW~l*C7nDIJ;tx?$h5te@`BGJ)UG2N!?l?Zq)=lG1OKq z5~l%c`#FV)+=}UxLRu@aa{jDh2RDf7Se1C6nSeURbWE@4m1-zA&BUt@YrQLDt2=h8 z86BG}@fY`r70Uc`Up5$J8NeJboj4HSTt3FnzSb}}oVu;1-t9>5(vy|BP^Tunxc3#l zw15?U-!vroE7AQb_>EBnI_RH-rAX&7ysj{pLVP&PV<5*@Si{*WGOw2w9)TH zhndHQYU9|Ed@WzukS`T6&M}BaZAN>1m3`sq?SSRp;ocPQgWHz zd>{SJY_k6XhK)iyS>(&!8E?oQmBzkJ3v0$#e!wE6W;-}%eYZoE)k3ucS1@BAlf3DD zPtuQ3ne@!5_9aD_(x9aX=9K1(eu=BG!EavAn2N8BH&L`T1RWgv+rDI&l8qAgzqK{2 zUjNe8D9mHP3^=elM&-ws(f4clzJHSTzG$*%M!VY{NOg!r&pLg!o{SjvDf6!(K2c#Zd z86QJei?{t9eaizv<3pT|Y3^#4rfq|^j@F91MABkLw>iB0-Ka*Nz7=QM zTPWNSXR+v2cPTF<&uiC=y1U`Tyqp1E&Y-a7JiN|^mZ?mY-V`q;bBi2c%Lwl%>h%CW zan|6pC`(&&7Ky?W2yc2a`-Z46Gwl>s?c?aU(S|F~QJIduR6enjx90!E$;G(QXs&>ElZiMJsn(m&2Gcqc>M<&;WzA6OQxu- ztYKglp8Qs8y9fgg!K=0?$%JW0AjR5zTyiN*;(9*TB;?aZdQ4v$%w*~zs1y3>Z7dQR z`K%sT^GR3%lU#)W|IX12hwA!EbTyr$@4bPTimXj8^^W|O+&5JK8PrY zR%X-5pEGu;9h?I1{e(ZXckS=`2lA5<9(GCY%#QYKiCJ@!? z$gNT1@!bevP61^V<*E9h)2k;5?>OI&jktfnON{d{>3{(WYSG9;S~=;3jVq~#$zMtu zw%Do+2fAN;!pERvzJE@gWCaPSb90H;Zuc2=6uywXJO0)rqo_Q>N;xoDXLT+B35B-6 zJ3E1Xo;7_6hP6&tGMJLy#Ql-jx^k-ca(s=3K4y_R=~B_P)-?PAn_PM*g@Q3GpXmfC{RLbz>y22=RMNp01IHlnhuMTC z_2C{t)lwIFq#~nStmf?weIh36;B0-N0NZc5IiitJ@IV&I7#;#_T_ZFFn~tc}J>i zeQbvZO_q;%ZXBU+Dm=gNd3$^NfU4I2kYRnUu$+m-;`={e1n_?~_Rv*z7yRa6`JLN* zKKLs6r7`@Ff^D8`|GiF_fC_tY&*FKP(A`!dj5BA2{KFgH6%k0E4# zKiG|K{PxVAi*di^PqYs=Rocp1^dMW)X|4cI(a;#(!#fWc5L5 zDyIHP^*(GT1~=v{^~MW|glUtGuO|#(9w(CH8_>^EXiX5X)91?2tt4dk z=)tm6%=jJ0mj(mkzN6xy#h*iHx))iM?@Pr~Hr2F0K`MbNK~-^H!=-+Kr%a@@73ZQ5 zu#aqY&d1bFsn*4SYf4<4DTz(HslW zP%LsN?R$XoxfK5D81UR$+#;WJIMQPH&T10yw%7lfVLSO)Y>~wtw7SW`x5N+G8_fSF=7Ld?QHgp5kzL&Mn_mJopa*uak~e=8LCeydblSlHB4TDku`t@2 zNrA06sF0DkQJjB|h5pSPAcm`*Yn16>a+e zaP53fC(PwzB{M&+TEtYQ!Lr?Rp!Z{$S!yISpa(x?Upqc&D0PvMDZ8^cQGCCt6C-e)jvI zcHOI@*x+7rg zlzYqwQUS=I{)XBR-4y;rUl*}5+35%95M1d(G!^k(X9{Amy8VCRlS3$a7y2i4YG zsF!j+QP{}){AO|gZjWH!?uFx~+)r$j#wMKkH`d`$64fqseujnM6Wry6(62?kJ^LnMh}~{l9>y z==M!9q|k4n4oeUgX~7sjnij530`sx_*7!Nr{udAcea(8jpm1o%{3#btRfeyo zaw?0Bj7i@o3aUv6yVD-}ih8NvMdhEx(;b|*JxYty>aVOeXhO2yS#tQ>L-_xrprepYQfd~zdk8HxM*hky7Y!^_>Tp7bw!T~Ha@F$4i+)u7t`C&bXqg( zmR~cmZ~oEMg@t1XG=U^WOr5DIY&|mEF_xh-U7nk3{+Xq)MZ`r#XWyXOxGL@Os|zy* ze*wj%XQ#|@ri7RPeNTjKW2$A#a;4PT{2We}^*~#LFXf(>x*Vs2>$EmrbQA$uFf=&( zz5E%i$?-}u!y!8Hbx)Cz-J?^v;m2EHSkffIi7|h9&D?<7GcIgRvL^jZm@Qy`QB8&d z7_bUv3eqenc)b<0y2>4C3zTT6-Dy4FNDCcVY}iV-AZ?q%9l#S2w~O;)AMzB$?5Xwd z0jOhNPIu{BIT)+@SdJJcYRW(BdxSCvS+3L^@}TpSWL9O^N@fz7i>gUQi^XLufH`_7 zrB3N1+Xq+;;L5 zhEm|~no$`xU&}AOl_AkRe%l(t&OSb`xXpO`3FKf+mZrUJky!kel%{14zr*{?Q)_T6 z;)O)mG8)SJ=FCifoo9fOiIb6ddtd@PisZX7M?LU?t%EbKc3GZ+wb|Cj4*Ps0&3I(j zSm&Zq&A-37MF>jS(n}8XsAHrhsifsKyW91;CU-ju{sPX_&#hJ8O;Tl?6~escHMa&C zLqB^k19hjj*}V4uN49eNU)joiZ9Tq=SNX305ReS|Xf?lP>{-*(URo62Bbc6D-zTpN zpoA-_8y5?F!=h|PpAXAN`-HH6qVqG=7z4V+ZSQ1lmyqI25vZ=0h4>yr&rh2PKO!~C z66CAIICbr=?^7es8ipV0$>Bz>6LkdU(2~GPjVZ`-4U+o$4<_FJts$$yfu9V0Y+(Sn zL)xdeTU65k;;5HF2UbV3q(~ww2S!NXNoYbl7epI<2dO>a3Ee;|13J3+7?&kY>$|zt zZFosBIzCJUY$bZR^O;b=TOxaJOhqz?u_?lH{jMr0$H3~)nApd1GB#?weW`6~w3>lB z9^ee1Pwe+AtL!0IxjW$`$l88aBP3{5e$UyXRDd3ypud1dv<6Ss18vt)MEq(H!bDb; z?=qdAuG*<>YwMvsQy<)M_+-ZbmhJ;)IA1*>!JOQ`jZsd@H=(?(*&PWxyzqxyjYiDt zlTlMWAsjk}B+=#8n`p(u44Nei+W1k^Ee`Q#B(LU*uIK$-dbHA#ucYsQ3pj$3jG9XY zj~~i?I(Q56UGErG_Y?|dc-^iRccLdcWzPsbd|MQtFlaP@!1T}{a`l9O`q2M*k{q5uhq@Q0lH>U7l{V$+{ zVdH=@@A>@>ywcsX8|Qw;#Iob4&*0F9t=yF#%txI3F7SDV+J61%N_Es1THxah=oNB_ zkIsszWls69cqSGr^@btwP3O-RO)7eTkLQ`QaN&DQe!9ezm6dz!2#%eG;bcl!Dolc4 zGJCzTF6720r`goWSd%#7G=;!yny4SJ<`;$@&Jf8%w5R!k(UiFDlgBREGzRSwAW++ezj3cc$`&06+&BK#LZjGx471>92?wk zL}0nC;`JoRzxnos`f-KQ2c*iT{K_TyuNWtpN|#L8CC(3`Ebc5`t6s=14WmhqG2GF4 z_hcKV;)SX%9rj#jjtOw*I;-CeYllx{d7%E(=W1&q#zw*}uMx`f+k62|bFHS6 zQ8_knpQ@a9Vu1zE6e+(JI9%_?iH3LzebB0`g(!15K<6g%P9hg8M{7&;ENJ0~Nk{JVHi<(}Sew@< z!APak?5p)knirL_x+uk8a%&J$d7KN+qtGL_a|)9cZgxVgK~v#jV;5y&Yr21sD4lh| zLrJzM!~||{icege7Z?9R^HQtt6=AxacF}-CZT9mP3D1}Lqr=swOLdqDw`zjsV{_II zgK}SRfHB)wlGRnwUJ%+LAt%Vz(;ahY7_7orDmF9zOXD6snx3YNitp~Hjz+WLdd-oO zt9A1)P zaXbm#*IYa3DRogY1Qf|If?)Yu~%he<|i4b$=g8F{re%-d;=0n-;+K=#+OJT26Jl5vl=fTtfRb%K(09lMa>>S7E0dOdFHVd|*rBU%YJ zJXXlL4RT?5KH$yGM@j94&1SwI5Dv-v9@$a772VLV>>qZ1%=)N)j{tyl?2@0AD(8sr zBg*bO?=(k~%4`xLNz?1T7rx$lBks8nRq-1Nu%KamBgu!7=_VL=T>FnqH=V~nneI$t zx%lc}Amz4rAaIw0oe&gHU1(p0ek^a{@(R)beOMc7#+ac>Po?`wfkY+Wv6EZ{t<-x( z4ur(SpGP}@SQ`PG#Ct2U>(2vu zW2#im1th|8{4kk!wR>a3b(l)WSHeG1I?t5>haH0Uud1&;*E>_dD7nCGHE``V{r*^KZB(?T!BUAkpk5g!?w@i zMzJ^}0_oG+?#9Dwy5kuy1V5fm2(<&;j_9^q^`qUry~KBGe*|eDEr-G`ttuHj_MN~^ zx@>X=5OZot^z@J27H&^>*c>#OhCX-aG}W1^cS#PmPS8g8^^^5A>TdH zM@aEM7^!Qg#76TH^-a?{hJ-8cy?{z8wTEg`$TB6%;U?2tC)U-vgC;*WM=Cv?3g(1& z>IYW-2cA&SHmPxuSeQeAe{dbi%MUxID?r|f8RAwF>V`L4nFH-eQ<)0E%| z#(b@)GztIIPp(rXc1~6bz-XQ5iBhB0QUW)_4w6nEjsJmY%}AUX&l60$9&{q-u1@ou z9;*l{G{LU+KUtd2IOEkh9WBdohtz?saF;(hJKnT#PJQTt9$IanPm%Kj)nst~WW!y) zT)TC6Fp?BEH$2oifeF1p4$|P7-IHrsNAbq-JKe+s=sIr+zusP6%HA9`X~pS?2)+@I zsU2du;Q^Sh=Jh|+&83`A7i74PgkY;Y)c;pr@q1A0Q+}t(quA!LE#FFbNO2`rHqq8c zcJ4!;%RPy9C6C2RU}>VFl3cQTcYgfj7UV`uAEVg8{#T71vMbeJfGVaMk+wyM=$F`& zXWsS=r=tH}(|+as#(7HjPWK32?MpK(75sB%qu1V>Ua(;LLyRD`7%2Ib)t<$V70kWo zd$0ZixFpO^L}u#pt)nClo;95Z&&+(q$SW1^Kq6*f6hXpKq=ls=n}kPd-%a6xXxzmB zkw)auhRyT!jYS!)kjG5ETd@Jum4+UvewhtpPCp?7PweP%Z@O~*)y#koUla^uo3v}fLN0<{p(4 z@HQLhxu45jt?RCXr_dejgt2IVR1hxi z6n^MX&q!EKj0FY#Terj!nq9i}(eoRZYsNo5cT3vafb|vRMlT}S3bzrZgU9JxrOQ2Y zTy!gXi;@rDd*5|_^xQrDB`0*kBw~mu)+uAo-b<^+uiD?!O*X3};1_2@P)b!dGts6@ zkWJ6frA{U)hI?&_2O;LD{y12?mp6y6w&mnKpzw;m4K@w6#@qhe0_*^7r$<5Kw*ibg zAR-sQkn_i;tbShqfhm~5KVO10c}jfHP!{7FM8V>e9?BkS9M% z_i%%sH#Vaw|d8px-kX1Lo3b1twv=dN*j$N0wXGBf08)I zsG{k`E|I1c=@X-8KlXO625UxWFU z1!$OyRMKA8&E1$~Dct#&GRy^vu$Bj%i@En-uH*m5rT*u?2sC0si7gA7Eq(q$9exT8 z-X;nE&r4*~*Kx9NU@w=m`ZH(3Pk`{JKgG#$6HD+#PqFyR$K z37H_LdRs4f+*W9K8#YjdyOGI?&mZ`%|yeORdK&Q_CEZz zGkjs!=SM^cCt12cT)+#A|MIBMES$oFD%}1jUd3)>wTW?>^2&zEm0`i^N8iYS8<07n> zwFQZuwsZtoa2->cDX8knX2)m`^2kUW5g*FiQxH>J^J)&$|AF%MuV*&bYRMmvmd|b^pl6MbemxVYrG0BdK$so z*!Mbyo7G<`sM)Mz7+4l?B>$@oe`avLw*JHGNyl+jrp~ipaq~C$qRvfgWBgdIFTeam z83MN8C4aBGA9+%2#1XtsjHXr6WKY(^qAPCAOQkQ<)X(`IY`K3uu7$^>i`Jj|BZHKu z7Ak$#+Y0hSt6$s`8Ur-VMrtm{-oCxYo6s5!Rnz_;1-J_NWiJ27(;>?cB7{`4ryvj6 zQbZapZ~vSJt}6+vSM-V(Ja}k>)3M?pH09NQMP>O35*xxSfdK&eV|0lgDfA6)E%1sD zQ4c2d$aj714!bs$W;Bi}Y`G>Z;3VSKcU*6#623SMp_hZFq0Swu1gbvtoonSwkI?3L zXN#+@uSFga1|+wbAl*S{*WYL-(*N)X_If?$({=>9o{-RMu11J-s5jfv|1CPNMb+^40=f?! zA~I1F2K_yc?U1R;^3`6`&*FsKKQ}|)RQC@U({bmPz|DAhE-HC4Fv8!vKc7dwCKf+m z5i>mM#DNLnu4x6jGY{6>jBsLcB9{x(xyX;AD}Hfbn2hC+cW{;HA$(}q{5n^<)Sp}! z+-0!(A`i~`!774wC%zwa^_IO9Csf`b3VCsy5P+y6AI3DjGZ;-{SIO6vS7)l&ej&+x zqDxI*BZlNySDjqK4hW$K>M%X9e0(}y#7E`U7K5!PoO4I5pGo&Id6+PnK<5&BS5LM6 z(JxM)sXkLqQ4^1~_gT_j&6^Gb4oh@QxF5?} zq9jcFN3@@BGe)s?hs0EWHq+!a+eQtTSX?3Qy4|o4cT~V;MPL|ZmRjz0XxbgIZ zL=0AJv~;Ln-E~lmz}{f2vi-n2UrLWK{nQRh7Xl{;og&PjVuYgz)jpAoF^i3 zvu_$S^i0gV1}(bTX86bv#rHibAfFaHT+U!b%DDBuq-81>3*zt*sG>bqDdniUSDo#He)X++0%BA7XEQ5~9=-wXq}Kw<@i+59^agM4t``Dr&}z z)Hy zbbAVX;9FKS)gRL+kF` zNlp0un{{n97@Jk3@Z#R639DFBL5;anW@48*AANU=q8}GB{IIOqPKJLBi`PNa9h@X9 zG2AR>bD3t_nmv;I#I@HJIYTJGS;@POO7>V;6E{Z=JsaBB*P^82c*6&ud{0csvhn&B z!1EW7a;!HHcebgye=STXW`LCCbXeET!J>^p5DAUjxsgk<<~&u>pXauF9V@T(NP zDip>}ipYAW4L==0$0zFO2@8k+z{fcUStO2KXmM($Q#Mf@un==3_O*94afq)hFqi~c zWN*n%5~qG!Cwtb%Rb9#am+(oGU1&JXtpiaUIhWH+=e|$;3s8^MApQDgk;6?bi}nh5 zyk#(&g@Z_>YkJ|W3EpQ9&BpzQM|KTvzn1Rko~z=q59H&DKKP1@wNmABHPq6FW#$+{ zcA#PjqM8ox{Bhl83KTL;0Ut+8(M=NsmCjnGo&^*;fhfWm4b^e|z8e#l@M6O=A zsN~UVAJdp)!_SK~@Vm;4ap8zQCfrd9;Ed6rN(!LqAkcjx+bUOGNtAsA<1(gh541J#vK?v zKRE8^Rnxx!2lu~#U*0o63;x%JloIydC*MQ|oYAJX%DRPWQ(CfTq*it76*I@sIe5k% z@NqNUa!7gLko^Ste4{S%l$*wy?rtLqYQ@C zUhTqbh4+VjjRNpBI+cvRNzHrM|;6D`d45@sVgip5>mB!x#$|CRUBpPmxs9N zFyNg|i-TDiJLP8#b_otDNLjQOd7#xqC1n#lmZwz~23Qv_KVQZ_G;$Vr76i;21*6LQ z26dsxXW?&SAAh3oiC*~~n&N#24$wJ+)$HCfHzJ7EkiHIM4Q}2yayRJcDRq^g{J?`9 zi(d41k74vP<{)Eq2GLyKOc^2#kk#Is4|)aaQtIt206WnpPB^CdW)@^u&)`2QQx(J3 zKf9LZbS~9_7#Xi(W_DzgFYLKK(lW~|a6g$eF%%_`VT|@h*bBWuq?Q$jg2Y%*OTVtD zZcya&;UjSF)(O#~!==718<$VVdmk8452gZjD&R|Db(atj%&uGhBVhv*9X-~7o+z`u zfy9j#E0GEvyS&4Qk|cc>egT?!6i|~sDZM6{JE9g#h6hAfvjR6e6#T|+NO0uB=Yp9YxEQHC{15C+wT)!tN? zyc73Qg+X<1n5mjTu}$0ig~OV^0B;cZmop;G`B}XMjL&-eSs&tnvTk>HTMM{OrB~($Sd&twSo_$Zzs-qiH3!=k#syH5AghSTC7ji>9>I?} zztYsU--%^Fg?zo#)D$UdDEr2tA>}HoIG5j$G0_FD+`?dcuOO@5+1TArUq}9w^5>>F zdy6eCey6E@TeeN11@UdQy?m}zim-4rW@Ak44znOHxwu z%yY2uKD3Nb@5^S`96WN4-W}weItpy8pL~^qlmZ?KCVjIEPEh&CrOA7%?ac}j{1=e7 z9sSa0F+^LsZZl+w5sR_k9t3!IAHy{VNx~OM1 zYvK&pYb!ri*{IT50^%VnKq&fHB--0723S?-qYySs=`BVl?LqFL)D*|V-=rt7>`O0Y z*lE>yjcz5nh8rlC7O$C```TmDrY9tOGG0uz0}V9Uzu5zT;wyV@1exQ?Ehm^ghQ(Ay z%kC~K{iAR{shxI%H{w-RSCC^VNBtHZm(%2AipzR?xSYzT7s4ZsPhasMj>xIwLZ`aE zi8vU4Wa?~~CO`joSwEE+?tb??BI|NUaMC;czCPuB%c3+;=+p3lak;m#pYY4*88U0v zoiTr6-W2=mShKj`WXei{|8%>b71K}EU#T=1GqTu}Ihm0saU8L+n)Tg3^}2Mod>U{) zd^O{NpV8Vza!QjC#9i0}&c)4jZMo)p{BpwZ_2d0ca~(fZdD`JaCI=8UG9SHfC}<#A zVmUFTbjR7C<74zS;xBGrdmYyiqrHk9s!z^ywK=?RNGv)o7KXf)>!hIXEykAvTv%%x+5Idn=czs{LVzT~9Ufx4 ze8+(i#mu7$Y5r5%7#i|q2NY)d#WhH8*cq;t)4V?564{soavmQAX3n#LEJZyAL%%l2 zRK4iK3?8z*(}MBKE4vpk27hIKwTy4n*0!9Tr_}_-0$-{&+K82{nEsY^CNaoslGYcJ zA5QfNaJNzMx=4FcmArctSeq@lw;ApPL6ty8hE&D7-WX24$zJM%gCy0YS)^*HqF(`c zPRbZxsPb<1Ja^U#;!sVoHp|j)FM6!*^|rZPWpFfR5Te|sZ+B^90(KJsmvZjWDjfnvnjuMC2j&P$Wr74*MU0(1e6W5@{W^~8ofwMhHFcQi zrB3Ci6TGd(Za475Q(JlC-GiwgvG2_V^s<8<4@GS?^~(o4FSu zk16ZN3xCzDWMF{p(yNa`06A(y=bEF zHUM~WhzRBg8p&0CP))9%T-~xTY0{s3Xq%fG_qvvzo*s&%wx4BG=1Dv%D{w!OHO|pl zeTeW~*OG=6qSt1qb?lNNo+^1#eL9GHyz!7y+8&Zgbv6r)Jp0^QFok=+2^{=`zhF232UvMlcOSDDM$$ z49vYOutcKKo{6@>D#_o;=NB9T@l)UBOVj|wE3Q+F?g`Ii#U}7He*y56Qyq_>&1A@j zwuuI%Bng9d;e;PftbD^m8{H(qlYOV^Gb_$?-*CJ#tR$;a$+FXI;!1`eWRvzHc_G$r zg0=hkioJnv_Qa>$NjWwJlxd_)ZR#%v&z^Lui2bI@eopzNro-k9dBe}%_c3g`@^nfb zxp}Uxr6mcaqG7XiWZvAyRxFUW4XrLz^i+=2^Z~!7^B7aI6<6$i94V=1aNpm9k^b%U zdw{K@df;gitnO+z_A-#(*k~iU*RoYxjkAe`o0}>hmCTW4d#?gOyrzx+%;e zN(H6n5Qcq4_ygVrtqUlM+m!;tHltpz&9Cz|abMvL7F+U|D=>5wI_cRsFNN56#p8X~3b6!@PzmWoYBfdyUyTo^G2e!nNrNOyiQq3{2ZPzyW> zR`IJ&UEbXvkvZ}S%nvd>YcLG~zYIH5b*oibnG*20H=U%R(I=|G2Y_x~b}FwY9l1MH zl6w5Z)Fb3#)&0%~4Wy6J=s%2+EGZW2bZ$S%Jmv6`?C9^HeDovLf%|B1d*iIY9J<*xJ?1>N?@5YqZXk980$^?FYS*PTR_Wqs%0F8yP^QUen@kyNN=F;BTBmfk%*w3L*}K$oAzt`yIl}r`LA}t)tbU63ad|lHQ}+KI7Y@L zvzb?}^oH6Blzm*DQRD|yiglHRFo(~CTML1U8XE^Jxi*J7TB1BU-Z6~E%%~@lf7qhU z`KYekFhzZQh$X<&6t~*+Y2+-X%a;2d??MRQaSGYtaEZ||NXbJe;l~=xA^G0uW1j-5 zpzN-e+kHwzUAW3%T{q zH|ObTr!7+3M(()?s^)sM`-Pqjx2uiRZP`NCEdS&jl2y6e=5Nt*%nb!TrgqyED+6l1 zRE=>uF?q5(SlFfoD;Z5JM-y5tCitD+w{ib^Mu~NW{o{WHDikMCJVBayaBni@yOvz3 zFL&_gKF4v`Amc83+v4MF4h39=AR>JCZq>^}?qem}KUuD08WLp%CHD!V9hx69JAxVM zTMH6_LAP5w&)}*Ju%40S4n);diT~(^2RZNEoA#gWBEtZ^N9Fd9qtO>oKhVmJ!1i&$F(sV5o*4peRAQy>wV+PU~7s<3%)G~Dc35u|1taC`}dzS{$zLkp_zEq)mkk_VLj&Qe*T^@ z45>UUEJS$wrA-g%xJI{W^xb4_vtzj3qsW)YJ|@r1pg*8sU{ZW~SfXa-df+2I9GBuZq!`;7KsKPX zXqo9Vn(8(L0E`l*XRzSpIC2{iVtLtzrF*NE2He|8acrqG%R6qP_*wGM0B_ zG@RLaS{VCi!vSWz~657y3Y%j$`}c-fD1#nZ;L0j*6htm2;3r z)G(9$ECU^S(?Z5yc-Ieh#%4os>F6Q2k~WL_DqZx$hfnohkDNF? za9&@vn^jW(P)fl-<>_o^{U!0vmidzpu0TS?ivLKccqG~0G36p*;b5*yc-I_JF-nXz z^LE4P8Z-4abaA+5ONf$_Cfxl*rXPeE?{UF@Z$v?1Zin;(bld`3kqoC?l(Tj!pq@v( z3A>7E(`T7$LcqGs-WWeI6i0i!6V?S8A`$VcdqvJRS|>|}kO{8Zzu8m{_5%$>?^a%n=m zeT7=}{lbc0Roy5;SNMlmi4pwt& zhX&c>p%Hlm?$p?%mu>Gu>C<=e`+HU3LGOxsOFnmrsdwTjgEY!K>rb{`D1~2`mrfYc36Ds5g9`l^T+)oA^(v~#9r~PP}3CLQp0LtwMn-N z!-3-hzq>ISn6?W=TlyKPz&>;#E~=2%j@-R>R!A*Zdr_gPYs8~20I2_09{+N8o=?h+ zj3XmS5=_;@h2DnprVJ!C4pjKUw(;@1*bb=bieXi4V`jV>x!VR3FUW%{Tqu|Ut*Y;u z1v4YH^a=n|CjP9Yq9AmR4kt60{b@wl>|lVqNSc9X#Tdq-X#-O@mSjQk+Mp4o-=|2f zDJyEmq1 zvD#LAga((meruf;Y`RwsfQ^8yEGVulNyi<zP3i8p_{lguwzZV0RF4ExCT){~c@VA(_*HuAQ zzg8z0f}8EHXue87pH3%J?ebA#p~^^&LqFZ6 z+d6SfUfTlL^ooE=+_KN=XvFowxLaiWxL;+;KBH~% z;$3%OgbaKk?5z@gAscq2O>ixjpvc618}zK(We(G+TxM2IzX-o_tE;%t##E>I$~!f~ z!W%D49C6IVX|0aTq_5&k(279lA0vTZB%hg)BT-;U);z&y?S8r%$UY?VZi0VhC4ccabzMyFCem8Nj>oczsSVfjh0T%R(EIEi#= zTns^hvcjQy`bkT9S&X9yV33c{)l{ zN#N|cnN1Sv(k*umI?+fWttX7rPr$%G!qGLccS-V^oc5d$5KN-Jj!~$hgp%*1XQZ%T z__6&gGcKA}6z~poY5lfSJGgxYq+}!Sx8JYaGEF+9oDj;CNP`-R`Jh?lzTPDC=+8)r zPjyq>Y&~08Xy~FyfCC#6ZUxo5gl-4vCvuZm)pL+$D(NlLb&8b9xWR@aE&H9%GqyE( z{&B@%!i&4;C=n5_Z|Po;KL2;t9JM=Gm5o5#4)^fk6VBw1jF**knqS{K2Q@cZbp+Im z5Ch>w`FSG~21)Bh6mYaU=}qk)o$%KuJjYBb;>sNhE2~7TG6cLO3L-mR;6kxYmv;q+ z`WU2E)AU`Yk9xB-;ev=y3b>}s4ss(w=S@>CXOgY=*VlSIG%W8hMGln;_!!YMUCZQA zYE!2z!bW7TCO1*>lD%T{(yjj6XVH@;;IoLvbLu9;RrW`Dl!ZjUsu${R)+RvRQt(S( zf-kvE)B-@HzH+dgBtnLfB63HonsxBJ+IMJ}bpI%9DI|ivi_ms-6lIC`R#H5op*t(I ztdmxGT{KoxGyR!3YXW+-0*)h__78FMoM%B5Z;iIvG`g+AcUs0PcD6*MuULcs|F0vV2x#QWeI{qPWPJG8rfL+s~ zA9qvpP~D?G-r5T0z%3ZzA|q&20&nmtx3CY-my~%<;Pj_TF}?b|UZ;4jg{t(Doh_3K zMr{XQ-T&BQ4|$mE-hG*wpOUaOP2fE8W>wU6YkiwPYpDZO=6_ROlKA!mXJ8#5O%JZ{ z%yP->h5s(Ts)3;xK+t!vDinlDsVrTEVF66cQ?Ee=fO}21=4f7Euw#760*=84GQC78 z^}BvV*%21J^SX?1FB`}0P$h>N4chOrjTYN{;Up; z-}LK{%g?FwXMg=DhCVpXPLb`A`SqE#mVuy`*~>}lJ=~;cD=j58z{UgA#JhgRdBYyn zQkj{bu~+xL?*>S^{h}J_Sq$FUYGQ?w^f@98ZrP*a+I3Y6L> z=B4{qjW0UyyABzFGf$crXZ2`Vxy1&eKQv3n{m3BD@(lf4@2)n!HL_*B#lQgXo}h~V zwS4ukkR;CwqHY(}GoWD|Z~n~Pyz|t1%m>&i{9gz;mj0tt&NAY3TH$7 zg?5VGO4*)NMRAJn7xtkH_{#%_j3f#hBfgEbkI*vPuUPB?im*Xj6y(M9i_s7w;0Ku*4Sl%akCfu@tFx!R_!poJ!@*{eBqSM2PC2_g~~)tonVB&Al8 z0*=f#Z^g8ER3hfBwVvUFXUGQcqr073#S^mTwmPM=;UdjkKH zo*Mqra=zO&9}W+?)(buCLp{W?r1qkmi3H;vsMQ3x!a=Y#{MfdzD7F^M<`6br>Dg-Rj?*~@3EKFy^j7a7w*mIo))jN|70-atQ zOFj8dRS9`%_sX)hM?t*ox}9X0th5*PX3)z+V(;Hlk4vm+TBx^^#LT2FkI5wMlvg9X z+Kj$5^>?t*Ms}b5rBoG^#{O9PT6C@lUgjKRjl%a-eJSsKN6-oz-HqgxE{vLHyo60) zN3KCGknWqc-Og0nr@L=+19`-1sXsk7zu?#7A&Q8KR_Z1B7CPm$j(fV95hyS} zBy#%oASC2k)Y0XN78mB=^2j|Xp3lw8(|M}XPD&H2BJ%0#O4re#PF1i{MNPs6-{D82 z=?3W)nw}qp%qItyfD^}Jf7QMC$EIl#iN|46^8j{&zG}@l-o&L=s$QASy2C8lJNz(dn6$@ zjR0)nY4AzAK3OCUa=}B&O;E`uh6Bg--I&KtD^yR}vV-Ewl+D?k@M(gj_?ArbVbo>IEe*h&emCBy-@t^5CU-wx zd){K`)@Rl4v0c1F%c4k`lQPtBpQ??4%@mZEDDGJJ=4CGe$6w@hE%sGj;&NV+iW-P_ z#sPFv8?2!@{WN-%cE@qS+07_b&!W&iWmx%!w{;rwMzb_IHL$4i-spdjtR-;Jb8lZx zz0fOYB`DfETU(v$NP1VFn-YIC%UY_7^QWS4hV!OfmNO2UZB~`9nvy%LYx!z0#O#)? zsM|Qbnu*A#*|plTVLblVmMK%^zNzORBZKM1QF{9Ew_()|(!aSH7EdTc!s}5@VA@f;-v?Yt3jz4Ze3qo3quHKC{CvJwlg1^3CAO z9P%Q07_ucTNM2qJVB0*fmN8#`%YZy04UFvbLu^mBmnBIyix2K{(uBp=3Vb^mciPpr|E^ut2*rX}EeKDKo~hH~QpPiyXC$Ik4ct-V<4Ojq zEUv-#gc9gq$P2E>EJS>%2}u!e3Xw?d`5Ildt#hv6E$&`StSdT{@6Dph+)d^t2>Yky zzVU}eXp?!tOh=5)rwPw0x`8{TC5yt-E0N)TFEw89px?04bX~duSl<4lY~g?J-@mx| z|7qd>!_EIsWB>oc&HrCT!T$5>=@{VpX#twa-Cyk?7DRg5FR7pZ zk4h>2%AEKg(FDo#0o;s$zacdKJp2=(A^ul{Mj+~W>SI)U1md|FwEmyK9R8!s<>$r! z?ZHZB_UFKnC+gkm36Rxoig!#I^u)nRlk|?rMbAOD0-^_k!k^cw&@dcqHpnx!a<;fM zp!C^t+H#K+o8FuU(Kr;t<}Smsc_!JF|MKa^gX>Eqm9OOaa;*j8{c(ZIy;0Vr191vU znVyQ*T^$#fY}1Br82*gZe>+nDa=Hh(B1J8#Q$|zjGI%mo>Rz#pdr6TTB{VD8FZfzg ztjy;jc$pAul$?%Gl?kde!t-;G?kZWEToI3pKos(z*iCQp@T_%;@;c1M6^cE1PwBKH zE$<@mdi`Zi#qS;WW$mYEJ!&!!N=(NsD6PfsuJAwz9%XZNpU#4v$Syf_m}bOZ74{hH zdrqO%TC8?^F^SLA59s|tMr^Vl@_)p{o2+Mn%cEYRXf34}+#XmxtNKp#C$c=h?&22O zN8*4O^nLyr>EUiDR@WZvM#?q{9?I5u|Gx8*axP}0tSXfX*ev8z9p7{AZfYkVz4!}eBIU0V>4nHTypOeAQSL6Smxv&D+;Af~g zIdzxx1fR-Xr?Dv^qv~E)n0jXe5@j-H>-KNyrEMoed~lI>CWx*sec16gu6=s literal 0 HcmV?d00001 diff --git a/docs/assets/images/aspen_run_console.jpeg b/docs/assets/images/aspen_run_console.jpeg new file mode 100644 index 0000000000000000000000000000000000000000..d33242aa9f0ecb25979ce7da56c1c97031df5d89 GIT binary patch literal 140195 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

&|fx6t zw((#&4}1Tu$9y4tuN&^ea=ejNa+#_-F9Di4mt8Z7HUX8|i$dbq-U}jR=lM(16qc%ymqkSjJvr%li0%!> z2X=^VKStoCk%;XiKCHK3rv%;~Zs&ygvGQO)Oe%ce(YdZJH|jmaa}CLx-QdUV|Q0=OgN1mrF(LZac_4_-bE7_y<_AQd$d%aus{3sBQBkW9lhN1RfS ze<7RUv?A*1w<7E5-H1AtPvm*M{I+cDXj09gK@us`mo)iua#T?{@2wQ@Mmr)jwuNE! zerM|9Y5QzbhJk|Nw$l@+A>9R+ND4tJ)L0AQ#;h|jSjKzIM;&)+6+82Jm)#SZfJcJS zb^P18L2@F`U-9QK&aOwLg-P*@gnaYQ`2;RD9KFDvo$48ArFY$9W@b@)iG5GJr+W$i zT3w(^Hn13)J`f@_AH$Gp2@y1Kji9{kz=T*G6aA>ka+U zSNlfS*oD}xO^00@*S2m~hZH6zcfVsY!6C9}%R;XMnngPEfgl!_oJb{d81T7e-S2++ z+nX{UD?01{8+Y#+)MWVoYerEJsTO*bsx;|62qIlNp`&0x2oNCjE=56FXwotCPJ%!} zFVX^tw9tF+y(0*2e*bgMi!-ykGiP?si{01BOy1f?YW#=&D>R==sg#w z_pyrbpBNOQQ(={^8g!{9Bd-d_jCq15;UE8m*{#+2n!hXI&|s<{K5a^0`TEpA4A7F| zQ;PKJ7hRi^cH)podA%mKL{>&vFfoF|wTjQEin|Sz4ZvE^_w81&G`gKX1T;}V& z3JT{;5-sHi*nr5t!~UAfq$%4ZgvBE->$+rP!kosx9R8-)A{pdQ1+1=RTY4}VWtFFx z&M=K5*6fQt#Go>@O1$!%MYNl)6l}g_v_~87=;gY9JarjC ztCEc9eX64%ChGB6f$~ng>hhvI!D0x&^VRgJz)pK$AFSC3QijQmENp<=E7AstYJIz_ z>gI-K&Y5kNa0RSV8fU((0znoCk^Im)!EPfaH;x1e534wBu8|#v!@w`~Y9ElJ%nzxr z{LCL4fI2vm$ijqDR2e{Ai$p$c+)S5i{d%=GJ|!MxX~|{%!T4B3TfY65nH-sC zX}^#YUe|H00VHeTv83Nx;hU$cKVW6Hr6m~GB6?ka^Wrv&e(=xut34b_!~~{dXunNC z**L56H37Hn&F%>GVIrygeX*FGAYMmnA5U z9XD093;4`um2ON9W4FSuNp%oUD_fji=qr&haa3e~L4uVvBK&>=ypqgkF)`Xk3lKzvO*^8>s0`$SPui$V^( zr9q<-Dpt6npi%zCqXm`Pr$HH8^X2zE?B%og!D0i>fZR3bh$^F*oflx(G?Og3CHD|9 zlabqXEex+<_y=gy$19_B(rdq_7a5u5=8Q^cGZsYZ%Frzzse}i~OMw+OSI)Al{xZK< ztG8q3Gj$s>f62Y>mj2bC6;JL6Wb3Vk;{{qZdWV>lg>+6h35+ z)iwsEAV<(i&EL~&w8nh{d&B*j=KZ3)D1zocyDQwQwd1GZjdn^{a4s(eYfVT$Fh8Wo zj-yW4K24!KQ;y3{j?$Ww)k-#bJ7^o##q~~}u5VgfIkrT}4DnbzBgrG`Ef@LvkF0q;@R_qdz<;8@7^t^#lj7Bq$be zEJoGdqBV{xjXBZe8k!q)|IM)oAQG9y9A}ZMs2v{Y>K=K{IR?~J*idyP^y+@kiQu1)>?1u+*&U5an@YH2T@y@y9y{6#AXfSmp7z3SN~%S3>^}mrY}1P$%F7eJst;* zj3r!JTKWCau3O4WJ29si?$?=MunDN#wfPlR8h=3NV2@vSb&SOc7rMjiN7EImCA8*j z^5EbG)pKFxCtK5p@^Vc!fns6k)*ZSR)}tP`l2?}Noqn_{(@fES38PP$bUZVum!K~x zH&KaWvm3dhu0k=6uyChY;@)1ohr-;1uJFubeDEp0nJqQ<#M;d><<9);865qIp53PX zhmn+*Pv8ap?s-4pnw{1ZVI%OO+|NyOyf2MR%aR71=4%Sp)vTu(>bqM30AMiH)ZzFN z3O&cEd7`2R8gz1R{-O#epO>i5mZ7j)7i5&(w}2t+_kUP$E++?#YE4W#AwoN|-InS+ z1)>Qso%I>VrY7ho;goKneev0%Mvpwiql*&KJKjw~I1(}bk6(9V27l763rpP@f=787 z9f6JP8;G9^7*TgCa{p0%k?RQkRMP3w>0A97?Qu(-RqhvlVvsf8o|Dlr_gWIm-|`l@ z+cknYLi|1t2!}Lc7DgC+&UX4LI6EQy`aU>`7rduuwh?2!kAiWYZxi`A9^*|ghOs3c zr?b$BZ|8$gplcOB?^O3{GZfe{&3xTBjnhWnkLmQB_IUXji@;1IYiMYb8k~`OwYi6) zlgg!56=r{`RFJ%UDi;2D%lnI1l)Bz1Zm1gkf{Rk3yKCvr3cmel zdXZZes&3bV(vOVX?3mIO1Q2sP!ZPjx0KL7NPqjnL%cY}qaQk;5cBbpGsuXRvLm;{Q zajzQ<=i1@-PA|)gvYn<~E+-j>gQV&J8;p1QJCj(fn$6vB26$uAQKssXEu@tQ|EvG_ zGi4L5U!?C8RwO6?+9^ORsWECzU-WC8V~Qj%-+)USCGVOPOIje^llUrYwq&f+sikJT zh&pL0h8TZR&96=qvuZ4 zzV*dBY*N;hGDMqlaei&9enaXbc2Ip?uVZUNl6d6859}u65IHPirH8^q@~n)a&0eCT zi>ElB!P@3tzso7*<#8_83aTkNyz6fX0n5<9FXPVe-Jj=xI;2pkv-GX2nP{u;%KGo}3cQrE*-Dm`-la$o)kxB{V(-Z(u8U31WSuty`&1%) zIj@9U;Nk`irRjyj>+0){GQlSq(TE`QwL#XM*1^kvfJFR{FSlB1HRm3?X^NhD5e=$b%H14-^A^|)7v8=gk&mh)Jj`Gubb0WUea@#d&f5W$Dkyi}; zUH0@#;fqE^=G$m?+Md&jH!zQzx648eUyExIK7N78O-0i68R>@8MW02_HG%J4ZI(^G zYd(rowgkv9P0iM~Fdpug84KGNjYi72YwccJWXxV1b0X=O?l2DKdu&9ILEG!yTM&rt zooXJlC#fT}LDe#uL>Aq+#%qlQ>%~`4^|x;HG(F5CAx!MCvRBFnm9B6(I%t-x><6~( z{kf`DTX^x|;IEJN+a-P5C{j82jF<(!>Riv}w4%uiaQnG~>1Z8`wJ%CqSzIy^*?Q^j z>?8OF?^^OpH)m!#+jAZ*wXo9qrD@_@6cHS+WF|s8JR~Z+7@#rOJMnp^+q16h(pR!k zT>1CuZbrqo*K9AJ%(AhOE0DU&{`U&y2J!^^>AR4OL`7R}pFy?VC9T{fOtGXV_OE2%aF4hr$D~$Fg zDTh*8oStVTs+kqkOM9W;G1b=GOOa#=Mkw}QTHM|A#-Gu>vYGJmgL(#4&++8&Q6Mv` z{Xb)I#J{bN?~yn6Dh@nofHTgy-(=|0_k-*M#v|hDRNf9f5I&wZCnjL>-Kcntx)JlM z*)~IRR&BJ^=uDR}OreI`0X zezFl}3zV*R-Y)ZK49k39TolkC(~pW+R@MW>nelQ&u}a3Nq+3j|G#h=9Ls!2F7BdZQ zkei-y;2|K(gzlRAeXNC@2xZ0{gpP8^AL|Kpe@(9%D}65yr8iwD>XP)1(}Vs!->aJo zlPDyYKI2)<#!-R>VD3Ylh4Yt4x$v1jW@cFECMO0XQ(t|&1c1^ z3KQ1I8j@dh*hWLHolFYqWg~(4$62NzJhyR|SDUCTT~|F`ajUh#k_Uz^Q|JNY0YZ zcOeB6)avoo>W5A;G37qFwt7S@@<5pnpJcDh*NB$x1vj7}9VE*&ZAmQl0xA z)u$LVbv+WYs3Nbzk@GgU`7fjBSh&vCp5>gPl7=XrG(+_mi@WknR;&LFBZANlsAT)n ztX$|Vt%AsFs>4OKt0aUXzgMP*OVE-}n|+_J=JGrKCN=-ij#mqlJ9<2~S_Ve`P~iZ6 z4$e*?CZ3CPJ0zMe9s6|2TRB*>lPpv)=po7~N}2$Z;0)=`+hu%->(GT!CosfpBfp@< zO#m)LEGS*}H-bD;%b8 zj-L*lu}4MK7J(zU*fXWlWCzF}49ZH9d;h9B)l5;sxzG=ncz_V;ZWF%5Q9Q_{E(lA>XytI8EwiZNOX(^Q4y4z}YZiDYRD^k+}u>)x%Od_kOwP>=vyT zGn^Kh##V{>ryHEO?b1%E zbKxT(6Dsh6)^sq3BR{Qx3zp(YJ#&e<5^Zc#R5R&-Rb={nGcD`zz-z(M+j}H; zCWdbfeI$BY__^_&TE0ilYtaX5h&qLLY?YUnqK6Zje-n;v6Pxs8|A_wRnzos`WUP+n zSyFmLu?CXY4lj0fHf3!5 z=+|2sY?YXe-x1VcCj>(XG_-_=5#|jjigpU68PTre8Q4g_wP#ePK>G9aT}-SKNzE0# z;-vh3@1`JCK8*h10;FMk$AdbrT-2}xu>_QluiRx&V|EKBNF~TB2=wT`UpiGLU|OVWSWnkG*lxUC9r24z%K;i+6h5o=c9tOBnK;dj?%(5-1w=e8}?$Vx92% zE&m?ZC&zW6FO$7a8p`C#M2gWbvEO6Wj#4z|H=m=M3A0*~E2lL(taB6x%B8}D|qFXMs*#tieO1}t% z_gS>{+VNrZXz9#WmwVagdVn)v2AL|wzw`Byc+yql`$!+H#9tN_Up;>x!TT7lfgPT+ z7b}uRne+_d(%}mB4(rJhsPQpP-tOogdWjn0_2X`#UPDPs$ni@I_=zsSNU zb}5b`9}XQ16fPflc$;4r{}=IopE2$^NGx{~n!*oq%xeYFYnYD^8fY=oRknQZq?Aj@ z0d=wrtG65qqcG+?_V$e3=A{ITew7*o_s)cCrZ|C2#S0a=OKIT7~Qd}Xvt$vx8 zOAhAw;22!wO$UIhjDLIa4X>c${|`=U4E^76TGsy^r^WG=AmqUS@zsQ_)tLFKkBzZP zZMpn79qHmBk{Crgjw+3Wp=A=0kXyxp)d%<#W_YHqiB~_rg4N2Ncvjdm{&I^FK$vcQ z;R_3f8paJ)qP>k#a{K;e=!K%oilO&+@vxfN9Uidt$$_;aoN&d#jKNd#u4jS|d0yHe zCxu7}la!{4Nio!YLhbLn1u+BN(cg>=Q=RV!z9;rrK6VA=EIldQ_1r?QUB4YsQB(3O zaBu$ncCrmE)Yg`l=sHCxzqY>7RD4Ue?Lfr|YSp$l4X8Q-V%HcyG!#MHHRCE%0Y6p= z5~JZQql~SO_Y8RjkR`devGpYfFs;ce$0=7l4ogB5;9|sA{^R0=0;gd`3}p26FPO~ zPfA+>L}q!C7&RaK$$0$u43oJ5))Z2b-hLjv;^JnEBQZCI{g#ov@kqJj4irF-Yr}UZ zq^A^UqP1xy_sHcPh_~-ZagX9;a9`}BhLiar9djUL$?41~5S2d1FAqA5U6F3k9WOU5Gex%<*`{R2;RM7T$nFtr~mO?8>}aFYkNeV{FuqB~B{-j(28TWn0T7MQ%0% za6=-|Wr;^|0S;B8zTs*Rk}->_a1GtrRY#P^o9f*=DA)kj2A`ylCcOi{EqOGST%>DE z@7o8R@K^p`vu&$mQu8o^)rsD8Xgpl3u7}R&Dz*|od*ZcV8lBm?bmkaOU6`WJd-E1f zkbIQ<*zYLC`YJ()Up0465?PRqyNa(I3V-;pxN`{8nK0nZ*Sik8plt9K1LbP>Z_P7y zo4r|(Kqmk$>UcjwHs(L%bw;_(Y3%rH#Kf8GqGoC2+xrICcKnGxmz|TkfQ3lT&q55TfDKqR#;cszf z0LH{_qFk2mv-CK2kMVw90$FZiqi*bzH z7@=X}uh_QdOOm#SkLX-RZLJrOk+03g4gdD&7IX<{iX|@}s*R*H75JfG&|^~^X1r?W z$G9%ElC$&M#+1KKCouIBCSf|I0tfMo*>_zC4h82ye zJw|nS2>$qr+CG`MFI{9Zgi%oXcy{4qfZDQYlagKFTbG?1XbFB$fv-d8Ho)6*OZYJQ zQ)i549=m`pl8oLB_E*hJQ+iP@&yjN!wl$`8F!3TpAJcLDpbMqyTz^c?wJ)U#AI+2K z8-nz8i~y?YJ)izawZ`xa$}IguaRC`Y@mwQ-IgM$1*olcMszbwu%rka;WL&pRc68Kl zDM7X4J42(CmZ`R4oLm7@`$KvSczu3RMPX#&_u-zmu0N#m!x&w8bnOOMrb;k`6}2wB^a)b4QT|1}5BuNibKA^kEWN+gx$EI~==%IL#* zLT4@jAEn-*EIUpLNjREuoLad@-bXheJTk$)t(QC{8Eju^>LgkTDGNpw`9C|B{WT@t z$^qslV65zQ-R@aQLWN8e^B>JT-`Zji5ZDl=CcNv_h#{II=#?GlJUtt}Qw&8v zk*(rMPhIj0Zo4x8See+=i&D;Qz%Oa~bNAcFsKc`n@zGAx5tAa~%080l#LzwtgcYa( z)v(~&+;3!?bM#P+9`^z(*bQZEwebCgnlozjslh~gqK0#Pr-q>S$Kg=8 zHKo*2pa+njjOw-~eOSldjy=&)IEBcWb|((NTfYRI?gtq;j+|Y63@L@YJKUa9G(S1a z6ejU&@G!4^1hLE=pYXMpG$DP|AEv_KG9FDX&uhUV0HZ3)M|uJ!I{pEEHQwCw;z=(d zbw}eCt4jcuA;O+@iJ?8N2Lm@P2t4f<=nf@INFVmiwS_z?A|ne_z`77BuoJN-E8LgW z(6>X96PfJQ`cy*!P2hLV71{y6E7%Q-3L#JsSCkIiugl47_< z2em%9#9evWjtHV1)lQ6Hq=w$impq+WP>6)a^;OaO)loL7B+C|jJ+3( zDVSU6(!1)@HK`aCEnKh+8L?m(w1b?70aMq8$bHWIjLh0@RGdB5`)%ocBQSMwKB{2M zYIox+BB1PiGu789E?+~hKDRxZ^cnwH$Jm0jVH&ihWN0*!%3&wQ#xCr{ueMcn#-_wE zq1}G2*2hbzb=kdT z_SlfU*=Nt06bd>8B^?qo5S5g(ZBKj(p#+QSGZ20I0H1XFiX*shrRZCj)SQNDpW99w zomwQD&Sr(gFhql!e3xbhgFxhZ{_Kyh45E)PpZ&AZB$es+q?dA)LzMm)y=oZqMzcJrMyW&R}lQ$mb|+dRsCi9 zb^1y%3f_t-gbxrSgk2a9RRRA1RpND7*#bq%_DGRWW20yxNTiu#44&xv_8C6r6C&?9 z9&Js~$DQ@k^vx5V?sujycBN~U9CPvH;NX5zVM>es7}*|zrsDgPFu$`XpIg~abCs}d zZA>g);*rZ%eW_qsYiRb;tMuxQdwOtIYA*Y;4Tx9U0XKkLr8R!FTq(bw_daKlf6|(r zf9r~zR!5^YHTLh~3fP}FEvLpMLN3Y@cwD)v-%T-pOOdXJX=5# zZevJ*6k%||sHykF9wPhAu-?%SO=uiZK}(VuuinmW?6~t9>h>690ohCg-cCLJO%bV{ zn!a9VElCrkV5n-xwqG~soLA$ZqCZn&RS?>>;$=%hV3wGfdB3$&26Uf>;xqun$s{W# zMu{2GU;wy(#*U;g-`eZiPf?Y%`EeE=*^P#rXcDY|Y3~hM3VbQ3=u2Og9qE%gd)YhT zE0sXcW!GS9Mrh34LD~skvaH3|5@O{rb{ONx#p+)050~6Qf8-CHSqF|1fB9e7kd+p# z{LoCXBDynQ8eR8rjj1z_!YSsA+P<~&1~nE2)vsW(Y1{)kc7)K@I^xCZNy7`I12l55 zOaT3K#gTGgi6M|zTO1x3B(GD(Pm(uexWhkixhckJm6y9~zQh`*vJoOEtiU8(-{tOt z-LV?2rA0p3;x%vzOYtiup+7#J%j2NF*Z_jQ)~o4b$|I$Fr?mDCYg7m&GuP@@0}H-D z=h>}|d^cC@9Oz`G$KgRljQ1gC#g3*d3T72Xeg-rS$U%qYNJnb1d?(r-R=}+FVrHiM z=GUsR$9t!qN!d-Cb1EKX0gCp}qm*`b7cvgP#({f`CnSXxxj%Mdh+Uhep*p4lH9t4{ zp3;)K$r67W*ZX)pDF8UYyQG8GvWrF0=aVEo~>p#N^~0I%+b9@j~oR?9tJ6l6ljXE}q? zzC=LS*dnur&aX8G{sEZ8v&%)@$-z+tkHu157{kmT=o;CTEH)S_Dm_b1mO}Jcb1?lT ze^$hfQl=_sZ%l%pnJ9h0kAOGSdl=svA5PS-#Dwr+t?MPbqb8lGW<;*xn~Y5%oE zV3xmQ56=Iij9O5En37--Jq#C@qB1BbIDyx*h%Tr6_$(YH^|(k&szDgFW2kA7IS5 zi_74lz=rzdsfS1Ui-U$Rd!7rawnMR|^gC3;w-`%kO?09VuyXif)$ zsoL1I)Pcp-<5`$fr=Vi1oSoFb(v~@Bd=7}((RVI$n%Y_udNmy98>_obwUyhX+?9Lg z*kE5j_U*Jee@N^6%sUvhE+|da3v-PmX(r1uo}v2_xh~EVB()buZgO_)rhTMRU=Q13 z^K)xb9WEcneA5xejD5(Jc*Vt^;R4&@^$Kf}`}-pgS&FDUjZc zYC>U&247SwU)X24$*w7Nn9K2o6y(MBmzI~oYd*r2cJHaGjKKQ~c=+lI)ckAJ?3%`B z)};bO2fjAa&V>dAGzXOBEm>juOTo4Cn~Nm{6_6rGoEu#6P!-sjB{BVUkZCWbaLmO# zXX8GWu+?Sr-K^-!EmQb(S%Y-M3!cT2&&$T|rf381F~-(w>$NPgm+n?U_7p7~Qd8)C z1SeP)1WzF6Ay3sYvd>i*?#ghl zWI?A-Oy;BLQlTbJEOh`j8mnM*-a3-P+f81=FG^XXzS+r;`ffZ{tWLJK{p37j^dd&| zD%^xu)?_3sg2K9c9}7DS?$#^%t#EA$WWCH$PGHMUW?*$r;wb}+JW?Cv~MCEWg@ z@@!A4oy5W-B~rU~7W@dLpv~$>5L%gxhJ#aH)0o*c)x^eJg^cKjYPwlFPVa{)cj81& zV^${ON+vx#_L-FU&!y*TP0TPS=WnHG2^RNehRD~-i~{RH3tzT<6LwPL6Cyh3W!G0A zKWW#3XH#7(C!)bIXZQrMqU{r4y_U&@_r%#hfJRpPi<}1Eq4DFp`N97HZ1XFeZ%;EN zYI`+gfAoC(>=d(B#FSBQ&10s!eZ8Mw6h<=U72Wluwz4_eu?;J-j(%C&Y!ldG#$G$e zd+jSZJ0Xsb3ofE5r7+p2+|ACmBBVvuo!Uol^bsx8-q^ad*rl{IB?I%a(howTm_ z>n0p1m#YY)^I+03f5wC{(ikefFjEPq&570IC);h#(@nbt?)y0nTfd4%P0Cm_*|8Ig zL}DG|xCgw0*aiCPw86U665o1rpPA3fOm8*YFBbQckT~i_4CqogU9C^eDjr1&7hI`} zQ{AY$Q4eVyuh|HwH>xZ^mX;*AQ0Oo&e>&6mje5TgR8Zd5`10u{esYdf7ZW^r8YdhW zz2sVYEMb)_xii6}GKUb4J{;t4{3u(r%f@yL3}Iv46__S4fi(0ih@~%g2eB|Iu`}`d zoIcy_AsUMVjgcIH+e&Y}gY2(AEWeO-XP&He4@lnqv#=%-ebQa_u%a5)Xg<9)1!zzK zJz>D)781$^|Fyg$hcl8X$L!~iTV#0LA5j0w=DE4(V8#fQ`;G)W`F$cK`>S|n@%Pcl zk@njbBPgWYL1f3%R1Qa@+dU@~kP+!s`pXa4?yGjq-7RZy;Kz9HEfF~Z<5%{{QoH%f ze8>3u-+roY<|82wHWds>8SR$u2?|r&(3;zz8HXh%*;tGDw#b6!s!1(9VCO1Rn_OHcwB@Y*tGq0{s>skK*WUmVh z#=;He9jSLPWQEmTTTVaDsiJpNZ^u$yu;#?h+>NPi>v8;k;aAViUS-B!R0(8#J>TZ7 zDO$RJe*}_?psrGG%)_#EP#nP-_6!))QDA2JLZ?oNPG3BQ5o&f0+bFLf2CFICF@KUe5p61c%-dSBS^ zlizzhPYrv6j#H}dd^GnbB8j$$&$Q~y3S$ASNnfDJZBVu(4*8$#V+DR))4WpbDd z=y`__#3K#K8K$FxcQ><(;s}P~xOhKl&y`&6%= z8UH}NL~v2K>Gtb_4;AnZi{)sPrH%Y9IPg4XlG#m5?g<{bi*IHLP?KPQ1A}^3rrT}} zQl@v<*@@zNSVI(u;x*LG14&03wPA8w;Km<%8JT@$#4We3queJr%{lRpa*InDf5Nz!=@N0*~&l`7^0%b>5I znvBCL3>gf)bo`dIy;iIH{z;*JZW)VdMICB)#`cNEWqby2gAM5O^eoOmgTH95CdNU# zkHYbXFZ9H$fFS@KclLov(O7Lm47X;X4RX%9D6Wr6!nzI9HQ?z5o%Ly+)AoJ9@kUq4 z&-?${M9ldXqN(YL^ZGbjE(R|sBjXbQNCJz>%tzu>o=r3njPl-{J+#9al?FajgH_aw z>*9v>dnV*^X_QIf9g2i1A|cvkEU*6_4&FQ$$QqzwX#w@lN{*p+cymf=;7GEP#qj3SZapER_(zMEo-{` zn%4UZ991#`_;%&_Rh;?!V_)@?SC7nGYiG)MAx@NU*aKv>;)u{tzEuiYK!DGc!37h) z+mz&^JSZj<3KBh3;dT37vCAIeR_C(CzhhAkAg@@#F15!9-eDxMRM65&BI ztmF##jYdETMhV5>akY6ht!lG3+1*9^?2=t3R56yD`OOmFyA+Kt8;Xao)HOS{0UW5X z7iFc(L2u82N8yhZh@@crz4ris(-#3RLFEFnPsY8-+(g%X_Rik%K0OqssSzS*S{_F; zTO(TV!zwM9{{wcbGGhk`dOJi>#e4 zE8SvpwhlnblE>#Ps}Vz385t=9N<%I7%A%&XCltu2n6tm>w+~^7EhF^+n-aj!Sx5!o z;)rWlUzdU=4EQ<89XBkhDjqMeUMISd!}%GEb7^4uR3=$#Id(x$?;90b+^^WrkW;I| z{{9h1wZmsyZYN>s(9BZth9!`NdvU$N?+wF2ky4JNY|%8vy{-;g0{r2Nm1*4)3VHe= z<5&Ec7?KpcZ3&(qdNuu1K(5xhAiDNO5&3M)RJt{Syx3Y4qdPuQxIeuzn2E7mRpt9kBRjJ$k&hr*H@t-}rpYQ7m8!C-8-0qu4q2Lud z6D?KVGnJn!%SoNwg2sdHZk{gC;72)V@hJrl^8A?ZnQY!Byg5uWYIJKu1aU;HlqTjM zsz)bfnNGh{)fXh`j4Mw6$V`?R)>>Y$@&rcaF2Q308^*}0g)!(i?SG=N0wWBtK04+s z_3jdn^P8 zyHhOb#H?1?Kb*RsFoN1p-7RZ8?O`kLEs+z~5YrOBuoFDL&h zX4_FBc_J6aa96grMLh6<<*DeJb@KH1a0>9IG20~;^5s&dGMe#A6x`4uuP&{GmjQ|t z4JiKP#Oh^>7OKa;#xG+_D>ha&qo$zfzgzO+gEeLMa-56@>?Ny??TpUMhAO4Aw*PAI-OqlEUXd#`Ie(JS)IvJXM0XO3?y z{ghr2S}b!b`N ztLro_Zcm>Ic}YbX87Ywr*PcF4u?!KMpdFAp+sx*gV6+Wez4n{)Ji^LAB5I0fwPme8 z$brYDc#-kH3&)c5WYm)esa%*tdSG0+=h4EuND<k;ZG@ zu_h&@XK(t)2mLB^lzZlxC#Q{Z5@?@LXO)d<0e|6WR!@lf3}b zo)v3abTVm|Z7vmz8ogpH3ey@F_ioZ%nq>b^fk{0P1N&q?jYQX6k!;wgX*{tCd-XJU z#&|dgf5TU0hBRQe{cb6dzL8bDP>0QK>)W{>lHF+e-`^*(gcPF<4$fDc7N3%9{{e&^ zFFDCtO?dGJfXJX1=z@}npnRigE|?EYy*rVH@K@8eDUa?&rxgZ1hx@dV9MJ>L`|c6#*&D@!VXGSVKY1D3kfO z`=MB0jr`=T?;c{&Fz1hb=FW4WWBJO8;pMKpAs_I#o>^mydA|wT$X0Ki(@0|OJfzrD8Zg} zH_!7}o@jtyfH7$Eb&x`U3m#q_cnBFg@3YoI)ES*4zl6HYGEBaTW9)qf|9SB2tv4?u zqo4tG?NP5Yij%)I(WY^xvx-}-?<5!`AjqoNGJr>nPs~x7h$&|wcV%1{M71paUGI$W z16R25t973f-t6KPxu*2x?ePUtZ9XAPbYT?ORF#7;Ieu0O5r{^+&l9))S1YA;zP-+Z zWiaaeEk0#G^8a>4jElK&wFT$+mFa(;@U8m;X*Z3Qu#dwcu3lhT z+E;pCTkRXiuJ8>`i!%QY@Ch2Q3JYE?@OFB9g&%;I3+Va2n4zFLD+n3ZbVSelzYF_b zP>HX9wAyhXP*&V&Ky~u6cIkfi(&aDhg~>B!ViHyq8{psp+vixHV7R(b_`+rvvNgH! zT68BSCB|PqSps`~YrJTx5;1Z@gr^bI`voGKXV6`qh&<%(?pehi&x>m=ru`0OFY0}k zJIxO^llczrwT_E*|0&cy$T34aypZqeouKO+A*FdZj0?Xan z`g~&X^2~2cwd8fSC0pK=4uvSpSlj)Y`lKhI2JQzMA6#7ceQ0HBf`qots6yM#&T8?C zMmM4hE3+DgSJW(@^8Z$kKK%iirZdym7j^pby&5dj;W{1;<;;`$A-*BCY4=WKVar3} zafK0sf0#Pkc?ZdL=D1M#Ebt9Fe*49tWd0jnLtDT;Y0+4csBj(O_=pse=wc8u7yHMn z^!7x76SZfeAnvCQ$$Et6Fe@9aPgnq}Rx~Y?Z<3xK6VnD*UR-_KpnN$hoqQ$WE}DQ- zp)yWkby4NDVY7$9*cgV&Lwk>hJ091A7b*=%aTCO?`z2iEHX6^~ty9z} z=Ppd^w<;@iV;?k`AIsw3)WBK-_z3x}}YsQEYE|$`b_o%Brtzm~m z0nTLp%3oNlA9v54d!lzmLZnVe(97bvW9Q9UGg=vi$;tCrA#{6se8ryYaHdTWtrRWo zW-0I5_KJVS(F{_5n@3Smv4;TgSRR0HR{?>%1>up>RrFjVHLK)9fTY99!JlXGgIlsV zjv_a#r;$oW28k06U#63hwVGsHm}&${d7KJxtIeN-fI5kC9Z2R29M~HT(^$c^;?$x-L02wBA`@wYAQo`5 zxg)5(Y6Qe7CeNUe5yA+($Na|kt5IK7gV*fSk%>o0FseAexTq)>{`#Vi&QgG%pKN1c z4~>wWj@$cPodN^(hvNxzc5hs58!X)gQb}PFMA*_ zdJ2-KpQp_Tvxh%wFbAg|bo-Xtm)Y~6geSDQwo7b8ny=;idV3`q8<5S4f%W$Eo=j^*xv0^douWk7n@6R6BffcVVkKlw`{9sP>rKozN2QJffebp)CllC>CV${yO%;FJLq*xZCj|mzVf*8>qCVjP2-o4MP8_wKv6Ln9|u4&-8Y1S zP1@u1{?OQw2xxSy+@R#81_z+drjd-9Nd^G|d5us`K4>0k&b%3gMDhUGP z)tH;>q+i$986B9OdJ_kX=B$_{RQ4rh3`L}#3TVNvUGrKQ#>BMx(&CTPYDE7G4y>S~ z-Ddq7CzLcgZ%niq%V~tT?KEoDNEl7kdb?j%XYUikK%5#a6SywIx}~#XRTkjWN;;uU zw-vkFHZx!6vx{PUWQ?NWzG};fO8`Dsz>~$0H?N^ackx==VyGwpDr zx&3gjRyxenwSN-pCDFfzuC=@5-;_x@mbD0ry3yMH2e^p2PAyA!2(U5usBW(wkxDM1 z@+4Davxme!^2Rl{dfc?c-ctvZ*-wrAzLDZX$3*nHc9(ua2Xgg9#jeh~S;!}@x-#Y# z_LExx0&M%Z44OMS4yh{BnR&0FrYoYvMGO~SB)@Q7rMaK~>Ujz825LkIM4xWB?1Tlb ziXz~)veEF={Xy4nH=`c0huyc-ER#Cp79gLhS$hX0CX7C^$SL(4>Jqn#u#EQL&aD>m zjDMmL^?I8ZUQ=9x-fn(%4~_hqC>7jKCL2b+`=?v>hXU<+p z-=2)Sl3{THvcbQy8ekFzvk(?dPCu)dz3JO_@yY=f>^3mfJn6oTQcDeegVb9PWu2S^ z9Le6y<@nW1oXo2{w{B$G+0bbAUhJdhM7{ci_>qdX^Z303^96dS__cENE)pjEV7Fn01_@rjBa#9K_Sb6k%!PKL9KU;T{R>oqk$a=4CT55x~ zy-Tq(z(`R^TTR1bcWW`GQhAW(>z;!$pw~(J**ty-!2mKEHqZmj`KkM?xa)~@EiLGeH&`M`l0w z+F@y?X03E?Ux`qHM70kwBff~E!nOEw--(|bmyWDb@GDaVy0bI0hD7siGNrc=6sQxI zKpe(JD4O+7Dht9h>!*I{Df<8q6)1g`fF~sRu6w__!d8Ex*WO2D@0x~fSy8Bj|ErsrwPMt}bJ-|DUP z3k+%*e@F4`gDy1on5cB(QGP{akZ+ArtakxenPwiZ3%a&VQV9?|t#SVPr5?ewk~oxmL2)n)CC;7e6_+=0AE)SVS7erFYCS)CH$z z7-u-$RAobgt;D5UQHmE5gNpQ2+8^&%PHAPH)(fF)zC|aKn9cn{QQJTcH>c~}ShXjP z(f7(Z;R%P|s?}L|quziXwlnnv1sTX42m8*Ml$M~jAONDYWRGn`XKDY)XNw2VGK`SOm8_vBj68PBk*m zO>9bRv^i&{?6c&9L6*o5$E>nN-Xu3ii$?q&`|5srdn`~SH$Z^e9=#x&P)p(_WvbaeYa*SeKexSYZtPcB>Jh89oCmDmB;FQs8nK0YeTQ(HXsex>yAOwm*d=s~ zKGt+*R5;!&eQCrN@e@*Q8at?}UA~D!z9XXc_!!yu8Wn>qFRt%wK1O}o>C1vZ{VchJ zeKmXqxSbe*FZ?!Tdj&UPOQ+3e-7UWX><{*5KNR^etYnSWHqK?TR>IY{or3Q^c zsyQ(VwbL^TriyxipYjUxA+RO~WMYv-;p z+^uBwAy%#-0+9ok*Mu^N5^rtX8u3BYnTprW81hPK%aT=}1d(s4mzBqDG)7h}qt$50p=lCnt>knKiwrumF`78OTzy!os`N;-&eg3nEji@?$-JNGG#qFvhV z?+m<^7r7_S8qc6gL7ddc+WNt?|Ni*57sXgd@b&BEz3+uR{j%P6K;%2;2eF)I6CxCn zLo+Q83#BBbM8%`_L%t?Q<$rJnIDX<|Q_77aWJ>en(+*5Ym)?34SZ)-=J$q6ZuQtF#}Gu^Y*s~@O6 z9_ZQZ9c?rjKPd4H{i-9bW-Cr$z z3pIHgN32V&tzD~<6`w+_$c=f3sCx>b&|h>~)HJtZ(mHt4OKJD2b5vtPy#i>JSttG2 zU@kGS;HcdKD3q*J5~S5Ar%}L?bE&`iadQm+;1NP-bi`>w8f#U)Q7o7%tNp^xZkAnk z>BQ@S!NoRSFA#%xH&d}zaw|kS94ocZiXd^sM#Vi{L|DYur}@X`F_qarzx$~UEIO)5 zOa<_TXr|n;JLu{6f=#{C(^NIoXH%7D>{Y!PAbhpGF+EHLZ)x?s0E)}^NuYapB`BcF z0N_RZ+KmivmB4Z9$e4|gBr(_0BPo>>^2B?V%uizz-~Y4`t`pEYW-x9Iwl=&f@{{ve zh8rqwMQRo3%Tpo2R;=B;tjzrgJWfqs@L*mG)_vc3fX-!F$qocv_5Mp8O zX8b#iwN(t8k;Ru0tvZiSWjgY|2omLOzT>+bQ-09|)-}U%Y#HAttI}#ibBFSISHfKf ztvs_dYJantC8^WjaG?P#<*?JRsRAj7FPc9hc3#{2APw-6C5psfwdE;#L-!kCW?FRu zzw9)KPg6&oP9S4Ir^Sfvg3!N@HBQx**E*ndT#N)pr@hP;+OnQ zP$_p9-e%d(Fei$oe=<(-7L<|ar%e~4sBn7L>t@h-TijDdPKGGY*?7NX zN@hrFioi$kc_)U;qF`oh4<%ge9%WZbE9wW<7#LwJ1oE`0l)t=+cjj4TqUPqFe$;qP zw=)v$w>1>1r?0Q7uSZAz?hE0kDgY{*-*WzaKR4Wz8&UBbwae0NET6e$U;eUJrZAJ5 zh(m+PAYGVeCo7?8!h5cv>loU%wE|*2*y5qKA(W>+c#PR$F|4@zX%sidD|Rfg3TY>M zKpyn6Tk(i&!^%QH5WKPhk+Kgdf%HXit1MFcPO>{cxNZ(}5CaWnI0l)1o&;>c=x+j*yTfPRi6B);BeLA~o7^ zHaZ0HUOnxA2EzbU!xxt6R8&v9AN}T*p#LbHs$F9nJ}AGjhk7R?gI?W}kK~+8s@`n^ z8|;>em{c{L!R?&*jeeM3!V`Xb_wf+4rr79z18C~6Qh#Vw+B8?^H5%*Mz(^qgQkzh{ zI__Dcj3$dx_1@+<{-gIs$-tZHPo@_XX&}N6>|Ed`-8~J#38AWPmM0TN8rwYnMX4$E z6B$k1`Gn%A|4l9U|Bfbm`2VF;(ys)sKNQZ(#c-?fhQE!YhKxo1D!i#!q}u*Nk7=1x#+O}#vM=CRP1pI>T)+(hg%wV@bhNv3`NTvg)ok-k?ig7&t zIq$s0$F{5tP(V61!6`ONy7rZr1GSl-t3MoS-8U4?&3(GRYVMp@Ab+7vQX=lp9_Z-b za7yKL%%CD+y%LlQVx6pbt8J)(mQYnKIqG_!KFwjSqW*M4tH(F3P+m_To4nJ!!=|Hb zDX0?{4N;oj1USULSH!&(?F!&y|K#%J(QK}@aNfA#0&;!jE8P=)b$4g)LQkGgRKn{= z_h0gw-9x@?EIt5|OwfS&yCqA7dcL!<>*;TtoUk7~-@@y;RgGCBqVse{$1vkHJr-ui zdu2bab+(Kh`tW!88>BvP%uDtSYBsX;cz**k>I|cJ5}zKJna7eXs)mV9wED4UO+zDj zl$)+?>N2l)t-R{nJe@RBFM!D zxF+=O=M32clKcE{NQt|Tu}@m2Tx>#B%nDPvihs|qz*c5V{87g-olv{Ra^@mz1qN}D zUy7*(`ciQ{)tjhPca|8>SM}M#O{GjSym9{8FDGZ={NaFP+BprU7MSf$=EQfWE8hRe znD_WKff{ffuyUZS&qLG&B9wLH)o4b=I1yk(TxkCLcsY*8<^qKnqmzu?0@u1pBT2;? z6jHw2xm~_mEGcp%bIG^lW8LD%g3#LTs|7Ie1JOwL-pGVjz$UhNwq8v0w!1Oi`*UN! zQi%Ueb-mS%3XgbKwi5YAV$BHAHqY2eWv_adM(h}7qV2i~noo;RfF+drVML`bR7>A! zpV`@hN{0@QC7X~OYv)O-A!L=!6Ru{jEKjyB{baeD{=7$kqiyS5+Wc%tk}+ZleAA#uUcz^NHHb zG&_ZEujo59iTX}l+UV@Yc%z$aaFt*BN06XFOHU7ySQMn`zDbmt`^`%!jr-PwTnff# z!Z>}FIk<8oH(FEW#e1L(C{$J5Q*6>f7RtC5=Y@5_w3R3~E{h zDiudY%fu<9N$=9V%=}oHS>S~+7p4g3OXtF1wzcpcrFSZv@Dt3jwa`HW7x)46ZHWlY z{6<7zIMIfNtz=G$j(XXBp{Gy!?91k3*sl?TwVOZ17MnJ1kkrPkV_4HUWYJs?V z_!l=m;%#0(1&#^76C2klNNHJ?WenN-XnC6_!FAufF+;m!T=E5H|99jNJVzP+_#Q0F z6LV$G{R*1fbWZyrPUt7rLN}BfQd(4A9-EJObeB4zi0Dha_Zfq9)uo_I zoLk}#^{X$l@|!hzfx!-CI4IRHi<(8C*GRn){m#vb`br<9!%vA4FLl+n=Nb0=}88WUh0U@Be!|zOMWV{0hj@o0E+wex5 zqTqWYf1;TCJa*2}k7Ph(rD4L6tWC7p+NKnZrQ^t3o`_QYrX%(TtSh3U%QLINmKdfj zy`bIwgK40fef{{PS-A*9Y=d7a`lD1wOSGr9E~zen7?rxaIC*<^7szXDZeK*}Q!idi z5GuL1IEw_*n5Zww2{0Cy6+Jd{A|Tey%RU}t_Hl|(-s+q3P-IDsuP8O2mSSl%3mvV{4z%~-e>906ZmBs#@$%FZR( zMkv(}?#javKfI%1LtqDl1hJ(cWzPb}yH-t9EMj39Q;@c_xyvhb)i`sugQZL&%94$@==e{{a#mDgpkO7nvE`<^tq_N0+*KH-)!G z-t;0X+j&_pPEw>CMNp*i(0MjQeWlD4{l+${CK0(9@v^?l5@eqqYql`D zH80O>5p)yfr6p7ndy4(BO-1Jwt6zF=*Ii010g1EdD|p5?(lbuPr*JUhp}#m}hL8(0 zIUv(*$kM|+MaJNa^=c5YkGLVu?EqGgLi=&W>NjY`&7kX(>}f4iE?@%xAevFIHr+3| znykNmSa<`#>5wB4&+20Ztx3d`0Uh+p+>V2^t&QkH<8Zp|L>^+1;S%SVFJ7D5dbcJG zxCD{HrTREQ+Dw~4Q;;2 zmdvwH;XEDEZDDD7Xp@b`!6p5+1;T*G9W0i8bwD1Xw6eq$V*}yNsGt{AhA>MV%jT|+ z@gouz8X|yjmfXD*#c)JVmdV!6&|{p)T26~4Z&r7P*_5cl8lL7<7La=})BC_6nPdP~ zixF=)P}UanOblF&=`JOsCXjb6@>bk)3o&vzQ|I0#K3C{9GqPFtvNt~vj}}RhX1_>Z ziMmQ93n}(Bx~+^_i0ZpxN# z-Zeqvg_OB!QH9TuS#*U)+gmK!>bB9^#DSzO$mDR@E7B-duRivAi*hmT+t0bu$FUaL ziWA1BvrA}|>c;L(P8q&W9~70M=y(I`&76_eu(pV$?J9{+bdvKGR@{vKiXZL0sdj>~ zg7B9-m{}K~FQ^4qdFVF-+acX(ZzpH59pt1ur1-FGlNo8`QerT*Hm1x}mhthO4G};_ zaYmT^3;c<{=50(??Rag&4`oe)LxSF}K%6@|vx$1AN>8&&%MORjeB0)>a{y5(FHFhg z`D8Z$*6Ve~+XB(>Qlx6hy^qCGLW!AZ`uZw7aZ9h46Hu7=)Ar%L{d?oM3SbQ-1FTUW zx2U@?LLHWd&HP>!alTo!PBGE!~d5m%wGPDh4#mEgE`BE zhoX^5KM7g%a&5e@veW@;-$gF-)s}_M^l}>(A$k-xnPU8uX0Kn3qZ1NF=YR$pFL^Mh!UA zbmK~wdvacsP8vlxoUMF*N?P4*iO9s2lf)%iyZq1< zzYmexE*qH9eOhBG*KY(`U%TejCPh!>;~Q{l0bAFgpj}OUOHfJkJl|{4>+$s6x2-gQ zoIiMnx8%{^O}OWaTaIH#R@k6pkg;RDb!i#yQGYgfS;;dZxGXm(wFPIb(uC~cLuqpC*6whruYH!y)@oxWW3)C-lOOrHpQ!V4d6W8 zNBXlS{-S*5!&4zP&w$BZo=-{FcbO#+aEsj(K0jK$9qymm3-snZiDD?*DrneYDJD#~ z=uDWInT?mW#dp%sfa{yfZH1V#B*U6_+q0HBpEDAnnOdQR!JZZy%~T!=@`@KUPrR3L zezmhlmu2pS^?_=M1+{*G9~ruWO<5a(n};{j#%=#d8F`P}z}> zj>GMT%ZpmeM@sKooHHzNt#=Y-Qn=F))S!bc?tLKtlP5xG1cy2PtU}AC@=}1p<30W$ zQ!8BbBq>&}5Xf$volEoAgHi8`>cMEm4kZLn6iQvpGkUb%qTfU1s}vZu9s}HjP8N zFz|(}SBvLP3Pzd29ucqH6oq&CVHx=)TjYUrt6l&`ugo{4t~&?l^zQh{%RNU9a#mkL z{;A=VZ70X6S(sh$={XXN1+M!mT_}a|sa-U43*Hsru)$<=)=$m^6rG3mh|w9*ekZF2 z$}@pAHe`M7_%_51I-M?-2}uDZvC?Woh%I|p9qtDj3yOi)bKaQREKe9Lg5Wscv}W4} z_MOS$O4ReMfPIU4|J^j}Q=8Iq;ied-d)Z=z!|u}AM2Ti>{ci-=0(yXp=C+5@5DDD- z^&J0%Fx$hXUtF0irEn?_PJRuJ??U_HMkAV?!6EPK1}USR)V3BZAT!O-N5%E*Rc$+3 z0nb`Z1HS0X2eVA~d|?GCfgha*Pnqtn*UE>Ee`+jD81e=Y6bmVoiL)$d9tBSwdy5YE zJ$d{aK&vXdyX+Vbj`?uOl=0qJbpTz$&8Fk_WGvSqMQf9$EG^9G#*k@8ztGdZF@rvb zLcjflmzs7;mGl=C!vm(eJ1mH7Sg2}d&EdF$+e?7Am7*JGM9VL?g9_Q~^O)H5inQJw z)MLAet~rsH)Y}&GcfifYwvqRXvXM|G=B2(>YWWzF#NecfGJy-QyFV^1nAu_$mca)& zA{r*(tc_*L>MsdQJoh4$>2JUcTf%5Jiy2#zCNbaEFav)Tw;vNIu@y2AI{%4>*jvl~mJg+x;&}K)+ zVW#n^)mm8upL-%{eN7K$dv=saVMHSJ3oN0Ha)j*x?cw0M-xLA)t<>mHh`-~@8j4|< zL6rtome$Sj73I~2cz5fb)U-ct_goU|i%^U$N%$J8*3XjNi+m$B1msM7P4}#$Cy`Ty z_|A*`K#(PpVZ8n1<}SpJ=d52Dd&+Nl&!ztA_hreO6INx;A9jF?iK^YWY>CnDP9uJ+ z+lC=Zli9|TtjfhD2wxpK1pg~uSNF!+dn*a0!b#p4&3r8C;`@R7yiaGrPpu_~rsUHS zYqhj`u8bZN_=1xNvOArnT=Efk;a^~^>D|v*>nuVhP`{WSF-y~srzg)+>KDqyH~A#I z302oTrsfId&>Zvie#|zBB|n#HeDjf*K~r-&cS=!Y)8=ipAK|ijlIsR?P(sbv1UAs! ze;|(;kqieH69iMExwMn9Pl()dlM-7QNwnYWpR>W{ZvO=Y^ZPTYMJ z;$4$dcc{tSg9jn+*`jRVE9+RD`MZ@VORk@DhG0+&^5=Fjo#1fDvk~s|1(!nW{fd=^ z>WSl@Tf#DT#Utz*G&rN;so5hS&FqzkYqX}OM85&1A*PqkzX9JS_>FbUe04TD+?xqr zSFnNZ(%6{|_b1`a-%vWVL%#<%#j`tK!J@(nqUwJ3{RRYcZJ#E&7c{%Pyz$gpI`jTA zmyq`~%eZaHnC*#Z4`jUWAZQCKmU7cOp zZpj=Te%Bza_M8<>577LfE|JxoHmWNVM<)u;JO8A-`%STJp0}n zfLrQ@->{nM0U333GXgBe0uPD4AM*t=0ziJj5pd9IVoT!OtlE5`usfj4 zSJFM5Jwl`7jG(!@UeDe*VUaSa?%rm#R#{Z!w`IxWI!7&*@=XS~+L8h_7+q2pT6Uz> z)+DjaR%ToLkf9&z)mRaE+iJ`C8%ZIO=pFs5u_0eW8l5 z$ci7aPqa5sb&bJieEjZBp7en`Z;^mCz0eQ%v}hUFM5t?KX`~ZV>$8Ray8W|y0hF%P z^5&!P)SJZ2eP~j(4A6y~2o805!GNSOBYvRSuYIFM54Ec`u~gQ2mfBi5FXN zyW*p2p%Kyq-k{PI+H~e~HwQK$I)w!9ojX3y`t~G6?Y)6KXElc+Bb2`Z;}P4xmLccs zRymys7W=hm=KMg~jayG3oqCMVcu_nNm}WvbSN!+SDc?fjWla!t3YwtP2&?ER%{W)_ zR~&0WEqO8V96q*N@u#V$Z81lW>s#{gTpg~Tr2Qey$2jQVx0enANTMS2o(Pa7p6m$t z(;ZSuJZT?%l5Awu62E7c_9m~&)&Bg^nv^M{Z}A)B9kB7$u@Wdtnvo~dNBhL60>>rE z&56furQWsci;Hdze&Jy*KTtB26&WT9a`oqs**UMYZM4Y*ET?xNgl~y zy0!tqYU9HXf3%Zf^NRH#<5x&##D_(5N*}LiZ9UHzKP}yi%h_d?y%mLw;BYth}MQyEURR{CX_ga5Cu8{Mxx{unsv-?X?xxg!o+hMulFb zfMJQ$MDThToo{i7KXB)(M~Xl^yO1GMgb*T$n#Dr;XG`wBTgL|c{rcgrgYiXt{cW}y zRm0m0p#X(jh{fw{vVkZtnjaSmLnD%>j@4%|?c2=kJnx_>L>(Puvt?2Xv#3@C+~>xa z{?0X31tH33Q1W6<>PYWt&9jNy3sf@qTw9E2vA3r+O?8BBKaO<1wGWQe4Z3BfrpQN; zk3Fl4^P{qbGAU<92pRx2*;$*`~M54i$O z3u4XW;W;a@aM|qdCUg~v%sY!}_gl)@3@t``luAey@x&LES5|lZw9E#>CgjH1j0-DH z-|a-JXdAP+$vc)N@->KYQ}lzGS(N~5%emU6-?A_aLGvD}z73MT4Z@dGju zUuA|yo?57v^08enJ94jV-PzgNIid>Qbo<0m2?zC6c^HL}(uZy#0$rQ5oM>NqFjLeXsviLyi5W~YTD8vfpM%xp=D z?UYNz;j)zK&Y|kQA3)_S#@~%g^L&-lsru<#2dVo!pE^3Luv|Pk|>PLl@Kh~D1@mvHv+=Glyd>BE)J^JjB zAN1L~wqf>AIuD=0Yuy$zkC2PTCnU%o-e$Qh{<)$~@B8ut_AC(#M%8s?DBZCi6<49Q zxHhXXVmP`MlqM3=JST$H+?NR|ciDCH+Z?>J5&F;v;7`=&&n3uyWd;E`P|-Efbc4Gw zc`xG7WaP&mY$KZ)JNnE}>o3sqF_|ef4YL^a**C{4WPZUaEUC?mpD_)PNNY9s1HZ7;|4g>tNiC--Q3W<F-#sE2_55>!>{! zDNFb=N3`&rXcsAgx1_VDnBh|-iKp_HBFH)8{cphFw%yj26+&%# z=(+HGKbcMvop=rP9!~o+NVX$u6Te^;DMfY~Js$KTzdSnSK%cy;qX7sXRRPs}so9uikXD zet#BYsC)WK=@p6^j9h|eZUK`^DySNe`lsz-9@Fx5xX2Mdu_TMvlXJ=h@?IjdwW{~Q zK!80SM9}hOXN!=4O0vH$mp5fN8iL`pJwCSi8NIKOW&|B*u+=9p67#;!RcR$@7H)uvihjG;tyCz>87mF#5<;Uepr-S^>SFtf&Av|)oT zU)Pd<1HS5AWr<_ahq;Lv)#k1f%94=?A+jv_hk9a>5y#n~O7%~-b?idN)vCA8zS2s$ z-W>Y*VQpb7n?|veO;7cvI|9}))oJcg2F-*qxF`Dupsbp>iyr9KiOvQPrnN;ZC;fgzl*M z%~r_Uijyd6p>ICe;!-l?hfvR+GTsL+Qw%uW?5b+qZnJ=K;N1f10T~Y-K*-AYav$~U zdn624YWSqgSJE6?*M`U2yHQ~-(`GV?9j%c+iN2&T?oofI?Tu*2KwHATHd>}p>G04* zy+80ffHF~QXFpW-yfwVm9E^AXOCc(Ak--Gh=gCTU}=<>#P?QCZ&C`ClEFE>-3ZT$hSR? zpV4JGyaZ)ewRPT?xs?Y5T|`ki-ToAZ*AZ&$b0fV+#JDy_BCH- z6Z;c7S9>~$@I zi;rGg>p9{p$f-WCwJ;N+of_2H?A~&owWPHXpg4}u+}XGlm^$%sr-i!`tA)5{#qaD^ zUuWod(h=gm{EcNaG3NR3H|-0MRamC|7F5@@v-Y-qTmG&l^cL&ihGFW*ZojMN z83r=JJU*}Nh;XACc5MA-)U^K$G~27d+W6rVxW287^W2RN%1w`>N4xA=Tivh(XXr~= z7I?mH;3K<&O^$4KB4*FiH&fvKWa-awA{ypL*KAjJV0Ut+H>jwrO`4ORRxc%?wq=f! zmS~X?a`GFukZ2}$_s)%uT2;JEH-zvXK^pt)3q)K+KQ#@3n1?ziv^Cia@`z&}tJ1yj zq+S{bH8)fd2zPUn$Q%s|InJ5>4M-2F`YL(LVt?}eZAWBD#sTXIp2y*(n=b|@EIB#h zF{7`?nfzvoCahc+a^*s$+@oMqMN^0;rEBbIFY3l-qB-NyvtYWm)OFqt+bOBW)4DLf zbz*qG+&Ce|^3Fqk0~TbRXWS?M4!me0053WyU-mRJk+AEM`0#?U#yZxP`ld#NAqiv? zOloJzUQO|orFLu*feF+nvl}J2&llY4Ha~x}>t7C0Q_zjhZ+(7O;(Pmw47a?2l1RlAK zc6N5#1F<~0U(S4q6=LeKfJ7$0N{lUNvq8uV5IE%MNu`1!NlArpQ6e4!JB2b8GmbV3 zD6F_s;3n_>5D&O!OTqe!#+>ysb%;yLU%}DACq%Zo0ng{`dAqKM?bXmlRvjkY_R)$@ z&Q~*Mu#vF|+PN5M#Gsh}jmeJZ*0`4}a*f@b>2rAVPTbH6?&{UyrX$JfPe_nW&!)eU z!}Q$Cn>%{O+@%4p$|`Ba#w>T4Rv?@9;*YVUYbk+$V{T~g4{Sf%X{U!PL z9o&x%2+$7FjrjN9JF!}^K|%M{L_%tyS60SH7eX%~O5HzHjJs`n8747JRnac6#-5Esf;wZzar`}& zk()<~vr&h>GF0z0=4;78V2a+#SGfd8KH>gj_wN`UR|1A7PM&8LOP~q#wGsdI3vE#1vses?HFqnB$*JQ4LRgA>WD|e+!%AQc1+Y~ipYQH4sG05Xq`&|q{TF24`f{qavFgfjXjo@bUqhJq%z z_cB~$&wpBJEB6h1{g}^P@8E(OHjc|A*p>*n!jXo0yd}lmr#^Shtd{&z2eb49eVKY+ zGI+mC%WRHnWSP7ip+m1f36lWYIj3Gl35_Tgp&Ch&^K7+Nb;0v0rDYlF?v+l3cD&X7 zx2;HZb*TvmoTErXu>5{eOpP^IdwUlDnE)*ZDyWT(OsX=_M) z$62xa%lojMe3VYfe&xzl?j0wWXNj*{f1ou6RYJxA{X3f6Gbv3h^u^87&bxPzCTOT! zL-bG$oM-8VsK%gPc3{NyEcnU`SY;zR#WHsaNZ)$U)uY({8-OGed2wsCpm=I~16NPO ziZC=H--wnW07M@OB_Bj1Icy(&ePO!OsDE%}9qw5F)bCI~Hj>3+)`zDJfWTguJ) zBb$AH-C)$j2)D~sQIPS?s0;rk`OVd0-*oD`JFp!-gMJ7lXx8jR^)}-s@h)+C-L*Bt zf^TmKmtaDl`g)J&YCUuLumofpx+`gbSR`%ixRJxaHp{Kdh1XYoRlQvTTP2bX5K%(pVDD z=Oo^>;eF_R9gBJQz|d0*fpP0fzkWY1o`7m*IZ3Ky0F7Hl*}AYfyqqwCj4yzHy&zw^ zRZrlKcUG%;O%Y`7|BWV8fWVmY3Z8Zdbr4SZXtJuQ2_zl?DZ@5%j+H;7RL9?d-7v2s8U*2j-ty%8 z&)yXbB87s&jy`oT*^ki*W#mFAt zU*+xe>xW78Bo~yFgi_W$rI&0U$n;li))TA8_m-CEDqgpYoA61qP#O$_PT?FDN}l%H z0i?Q%5q$o4QlX7iV$D~*riS@kvO;-$#<1!<`qg3)W@g$C8Ceff@dM!#7O}f!I~j^A zHAghh?u3U=RkNd<+S$l3Q64ZYJP7Ap((HLF;2w9#4~+4xtyPwsfrqPoK{bsXFzt5ps4YK6y&i*aV(b!q&wWiOPXEVe_<128o2XZf3f>m4b4NX10%Ph|N= zQJ)OEtPP)@rEB^^=x!eCIXbYOgH@Et zx27SoqOX)IbZxmM(FGj0%3U#vU+%yuWlycif$fLu-a%pd^T?C{r3KlkF|)PWVX-XvfJW!E8c_{3v2QilDcQ4$n26%%W&&LB)%6VxR&37zh+4e| z1OmUQX-|5-iL~80w+()|$-mznikfyOMNb+$g9!s-N)4W%>{YK z+bK`jB8=&oEd?j#;qS+pp1%R9VcEKJru$EIcY-G-KfOi67FDjYv0>^;UPS!t$$dw9z~FgSdq#Y@pKYSZc<9U-F~iN z8@s^0gPxV$c0n|6ZzhasEHb=x2S@*nbi>u8;gE8z5PFS+wFV`dWY?LgE~?CS-O4&` zQtpy_8u4ydU}Cs&@&m`ypIHLWA$E4M!+W57E0^7(6}3ue!eQ-v_Nh%LOXSD5DdVDn z_z~S-2vyCh2nI4XxG$CkUeXqk5(HBpcg5d{Zy`qI25i4uPSRQhf=mV<+`t=H5%OcW zm&2UIs+$s@4F`F9n!yQD9EP(_g+=+z8Uq16Q(_0TI)$h!8!2Sv4+$Cq!p1+Qrut_m zhQI&hK*~TAPg&D4_WP2en!2?2n`>QM%F1B;Em_=+hH`Qyip?6Qva^AagJgMAC^*P> ziq3D~4ov4^5mbeTDwkBvY9s!3IMLSSrMke8^NLA%gF$VkK$05;OMOHD?vB%?7?aYt zk#rH^d__}GuVqTEuy*9dJREGE?Fb;+;xKqJ`&jTL&=TfBU2E&+IcTh^DEeaSgLNaH zw`T8?H=%LQmt9~;Pf`tmf)FX1J@TW*P^5*Cr$ZInUT|;@>QRg$?A+j5=J`R)?>n? zN9&HS_VG0ef70*6kUc{M<*^i}9W>A$?qC})HbU(hEWNbKrZu~C@bQf$W^!KOemQ4x z%=h}qTT%($HAu?b-vD`~?#S4n^zZ4$BZ4&ZDmp)7LwvlI36P`yGqEj0m~A@e+c^FU zOee4EACi2*Nd0)eSxSqN?NOu`lf~o?Y&l>?extI}4M>9fI%l zSVvK{W^?Sl)E^_?nL-HgMpsY27wG$Jb0>y%o@dcY-DR1YuhZFt=+Av;XY`fz*m#aS zn|^dK0wg0u_o&TfxznvbX@xKI9AFM^efgQqjNzWXrnsLlL_DiOk=tSou9Es%i8kst zG`Lj#dKd)QA}bS;Rvc@s0>#;2-Yt15A4Z8Z3&8xcwJ|4VQVBcxQ)i6^ZH~HpuEJt_ zN`C%CiPo3#!s%}&zFVCt!`u$t#3zq?ly3*35-K@~w&ls$)B21cG)5Da4j*&(emXnE zjJ8%qi(7pbRrZ^or?FaB-G*!WVvIe?>LwZ4IH{70^M?Z1#A!r4Y#c1(v@*@JiE2zS zHV6iOnEA(2+KrqN6Z)@^V9lPORmTTK{4j!&WiJ7Z_P*|1*~c3qV%%@T-#yyP2`U6z zQU)`RD=RrWbF{LKJg``Mo^hbtU+BjJikyXvMrId%2@!nM_br@fH$Y-umHokH(3^ix zC&OSB%S0O4l&xk5Th-%@>LWxi5*+`HqWryj29X8@zn40mX=X-w*Xra?_i=tFTy7Sh zIQVJ@tN#XMv+Df@{7k|Rbs^)HjCC38@!6{C_&;JV_gQw z)#F`dXH}TT4jqSqyYWE=Tm=T9H31Jyx=AZ5iqnR`FlUV^sMICf$Mp*MY>A&^=a5?hf^X08MCRO%3b-KSq9KffGtA73~_5G$l}aJ zbF(Bfr^Y=Y>fDAk1e2Kkwzo7d-?(OKLcF!Uz!43vz4p3FKHG-cpY=%g5Ydno%iO>m z!z&|pKcK_)U7g3BzHmTqT~&~k9Y_=DBTG)4N2oA8aMKLAZN%oHtRd)Q+XaT2)~G?fG5i z>-|8P;-y4rKBo4WH4BJ$=!gA|*gGVOO6DzCZh*Px!`-stJMqcI2;r-U9-4DmrEcQ$ zvR#hlq+fy$s+(rd@xyJ$?nhD{GF%(Yjn8hP=);Lv9umJ}qeC@oo%*0{)fenm=%^@> zhRAUfaZLxoJFnvXv?I~aUJYX2m7W&!B7_AWo&S>1aizuMGp=ub;WsbEV;S8YJsfxtyoJLob?JEvn@yf?i{XM59<sOYgSUu)RW(U0y-?ZCTQB_$7)D+26}r!sr->kI8Kkr8tHd=M5s(vMT&!5HAj+V6;p|= z@|MPy-1%kR8!&%I;m>Afn_e&XKXmjf4yF>IXlW^*Pt*liS+Uhi$i&y|D}*n@(h75} zI}CSk$zHQ2aX3ALL>?x;kBKd}$b0>jeU~fC)Uuq*+v?21@A$*c_~z}%J;1rq8;(lj zNd~a*Fd>eXL<5?er5Rj3A>6?2oWZ)px{X85^>>=38{AEM%!^*_~9qZ{pGO5WDDxTF+&Q%iC(-FLUO? zM?Plrmt-!Q8#AS3rWCv&P8jRjq&yS9GB-gW;FZB}h5;3!kK|&<%Iwt9BKUo z^UK#`v%>5mPi*W3_dsFUo&@z(Jx_xdywC6dp8$&s3~IYo)Kb>5*qgFY2V~ zCDUlX>34lQ(PnyKqej?(|LQ-!*R%chNVsiM2-c+RR#aS>YyKjg^;KGD%d4Zba$^F` zQeRS>BG3N$28n0&6;Cw{?mU|}>0w@LU|0zPURD7MbJkZ#gsLx55zr?<);AJ!#k~c^ zj&iG=^LHU`1?l=$OoVNSwdx(Nl&JjTyAbA7y77$cHy{EjdDAV+Iw1R@ zlS}jS`4y#ZTwExy$Fnw&e)|`T5lX0*`~=yLvCWSAvhe2h0g70|0IwPkz`D2&d<*h?fG+BM5bW;?_>Iv3u zmZ-@J=BlE@NT+@S9uhLAw3x{o=D}6=Ut$iWbf8b5qMw&GK?qXW%0D;StjA({?91|D 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 ``` +#### What successful dry-run output looks like + +![Example ASPEN dry-run console output](assets/images/aspen_dryrun_console.jpeg) + +The dry-run summary confirms that ASPEN finished the preflight checks successfully, points you to `dryrun.log` for the full transcript, and ends with the exact `run` command to use next. + +In practice, the wrapper prefixes mean: + +- `STEP` starts a major wrapper phase. +- `OK` confirms that phase completed successfully. +- `INFO` reports status details such as where output was written. +- `NEXT` gives the follow-up command or monitoring action ASPEN expects you to take. + +For `dryrun`, the short terminal summary is only the high-level result. The full dry-run transcript is written to `dryrun.log`; see the [outputs page](outputs.md) for the complete workdir artifact reference. + This step outlines the sequence of tasks (Directed Acyclic Graph - DAG) without actual execution, allowing you to verify the planned operations. ### 🚀 Execute the Pipeline @@ -260,6 +275,21 @@ If the dry run output is satisfactory, proceed to execute the pipeline: aspen -m=run -w= ``` +#### What successful run submission output looks like + +![Example ASPEN run submission console output](assets/images/aspen_run_console.jpeg) + +The run summary shows that ASPEN created the submission script, wrote the `pipeline.running` marker updates during submission, and printed the `NEXT` monitoring hints for `squeue`, `snakemake.log`, and `pipeline.status.json`. + +Those lines map directly to files in `WORKDIR`: + +- `submit_script.sbatch` is created before the master Slurm job is submitted. +- `pipeline.running` is the human-readable status marker updated during execution. +- `pipeline.status.json` is the machine-readable sidecar for scripting and automation. +- `snakemake.log` is the detailed workflow execution log once the run starts. + +Treat the `NEXT` lines as the wrapper's built-in "what should I do now?" guidance. They point you to the same files and commands documented below and in the [outputs page](outputs.md), without requiring you to remember the monitoring commands yourself. + This command submits a master job to the Slurm workload manager, which orchestrates the entire analysis workflow, managing job submissions and monitoring progress. ASPEN submits the generated Snakemake job with rule-level resources exposed to Slurm. The heavy rules that may need extra scratch space now define an attempt-aware `resources.gres` value, so the first submission uses the baseline `cluster.json` request and later retries can scale the requested `lscratch` allocation automatically if a rule is retried by Snakemake. This keeps the default configuration in `cluster.json` while still allowing individual rules to become more conservative on repeated failures. From 06ae3a11f1bf6e81924c3e8a2b3a9b50d1067348 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 15:12:30 -0400 Subject: [PATCH 02/24] docs(deployment): clarify status and replicate guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update the monitoring section to prefer the sidecar and pipeline.* files, and fix admonition formatting in the replicate guidance block. ⚡ Generated using AI ⚡ --- docs/deployment.md | 74 ++++++++++++++++++++++++---------------------- 1 file changed, 38 insertions(+), 36 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index b72835b..b3bd591 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,29 +31,30 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y - `path_to_R2_fastq`: Absolute path to the Read 2 FASTQ file (required for paired-end data). !!! note -Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. + Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. !!! note -The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. + The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. !!! warning "Biological vs. technical replicates" -ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. + ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. - | Replicate type | Definition | What to do | - |---|---|---| - | **Biological** | Independent biological samples (separate cultures, animals, patients, etc.) | One row per sample in `samples.tsv` | - | **Technical** | Same sample re-sequenced across multiple lanes or runs | `cat` the FASTQs together first, then one row | + Biological replicates are independent samples: - Example of concatenating technical replicates before running ASPEN: - ```bash - cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz - cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz - ``` + - **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. + - **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. + + Example of concatenating technical replicates before running ASPEN: - DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. + ```bash + cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz + cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz + ``` + + DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. !!! note -For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. + For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. ## 🏃 Running the ASPEN Pipeline @@ -296,7 +297,7 @@ ASPEN submits the generated Snakemake job with rule-level resources exposed to S - 🛠️ **Optional Argument**: -`--singcache` or `-c`: Specify a Singularity cache directory. The default is `/data/${USER}/.singularity` if available; otherwise, it defaults to `${WORKDIR}/snakemake/.singularity`. +`--singcache` or `-c`: Override the Singularity cache directory. On Biowulf, when you load the `ccbrpipeliner` module, ASPEN already uses `SIFCACHE=/data/CCBR_Pipeliner/SIFS` for you, so you usually do not need `-c`. Use `-c` only on another HPC system if you want to point ASPEN at your own cache directory or pull containers yourself. **💡 Example Command**: @@ -304,13 +305,32 @@ ASPEN submits the generated Snakemake job with rule-level resources exposed to S aspen -m=run -w= -c /data/${USER}/.singularity ``` -This command runs the pipeline with the specified working directory and Singularity cache directory. +This example is for a non-Biowulf HPC system where you want to manage your own Singularity cache location. + +grep "done$" /snakemake.log +### 📝 Pipeline State Markers: the primary status check + +ASPEN writes a set of state-tracking files directly into `WORKDIR` while a `run` is executing, so you can check status from the sidecar and `pipeline.*` files first, even without Slurm access (for example, from a laptop over `ssh`): -> **Note**: If deploying on Biowulf, try setting the `--singcache` to `/data/CCBR_Pipeliner/SIFS` to reuse the pre-pulled containers and save time. +- `pipeline.running`, `pipeline.completed`, `pipeline.failed`, `pipeline.canceled` — exactly one of these marker files exists at a time, reflecting the current state. While the pipeline is running, `pipeline.running` is periodically refreshed by a background progress monitor with a human-readable summary, including the percentage of Snakemake steps completed so far: + + ```bash + cat /pipeline.running + ``` + +- `pipeline.status.json` — a machine-readable sidecar with the same information (`state`, `reason`, `slurm_job_id`, start/end timestamps, `duration_seconds`, `tasks_done`/`tasks_total`, `exit_code`), useful for scripting/automation: + + ```bash + cat /pipeline.status.json + ``` + +- `snakemake.log.jobby` / `snakemake.log.jobby.short` — a `jobby` TSV summary of per-rule/job resource usage, generated as a best-effort step after the run finishes (even if the Slurm submission itself failed before Snakemake started). ## 📊 Monitor ASPEN Runs -To monitor the status of your ASPEN pipeline and its associated jobs on a Slurm-managed system, you can utilize the squeue and scontrol commands. The squeue command provides information about jobs in the scheduling queue, while scontrol offers detailed insights into specific jobs. +For day-to-day status checks, use the sidecar and `pipeline.*` files above first. They are the fastest and most reliable way to see whether ASPEN is running, completed, or failed. Reach for `squeue` and `scontrol` only when you want an advanced scheduler-level view or need to inspect an individual SLURM job. + +If you do need to inspect the cluster directly, `squeue` shows the queue state and `scontrol` exposes detailed job metadata. To view all your active and pending jobs, execute: @@ -333,21 +353,3 @@ To quickly gauge the process of the entire pipeline run: ```bash grep "done$" /snakemake.log ``` - -### 📝 Lightweight Status Checks via Pipeline State Markers - -In addition to `squeue`/`scontrol`, ASPEN writes a set of state-tracking files directly into `WORKDIR` while a `run` is executing, so you don't need Slurm access (e.g. from a laptop over `ssh`) to check on a run: - -- `pipeline.running`, `pipeline.completed`, `pipeline.failed`, `pipeline.canceled` — exactly one of these marker files exists at a time, reflecting the current state. While the pipeline is running, `pipeline.running` is periodically refreshed by a background progress monitor with a human-readable summary, including the percentage of Snakemake steps completed so far: - - ```bash - cat /pipeline.running - ``` - -- `pipeline.status.json` — a machine-readable sidecar with the same information (`state`, `reason`, `slurm_job_id`, start/end timestamps, `duration_seconds`, `tasks_done`/`tasks_total`, `exit_code`), useful for scripting/automation: - - ```bash - cat /pipeline.status.json - ``` - -- `snakemake.log.jobby` / `snakemake.log.jobby.short` — a `jobby` TSV summary of per-rule/job resource usage, generated as a best-effort step after the run finishes (even if the Slurm submission itself failed before Snakemake started). From 331bd44230abe04c5d8298be0689180781037f86 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 15:14:27 -0400 Subject: [PATCH 03/24] docs(deployment): refine monitoring and replicate guidance MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Tighten the ASPEN deployment guide so the monitoring section points users to the sidecar and pipeline.* files first, while keeping the Slurm commands as an advanced fallback. Include the generated console-output source assets alongside the docs update. ⚡ Generated using AI ⚡ --- .../images/aspen_console_output_examples.html | 210 ++++++++++++++++++ docs/assets/images/aspen_dryrun_console.svg | 55 +++++ docs/assets/images/aspen_run_console.svg | 62 ++++++ docs/deployment.md | 25 +-- 4 files changed, 339 insertions(+), 13 deletions(-) create mode 100644 docs/assets/images/aspen_console_output_examples.html create mode 100644 docs/assets/images/aspen_dryrun_console.svg create mode 100644 docs/assets/images/aspen_run_console.svg diff --git a/docs/assets/images/aspen_console_output_examples.html b/docs/assets/images/aspen_console_output_examples.html new file mode 100644 index 0000000..0966854 --- /dev/null +++ b/docs/assets/images/aspen_console_output_examples.html @@ -0,0 +1,210 @@ + + + + + + ASPEN Console Output Examples + + + +

+
+
ASPEN Docs Assets
+

ASPEN console output examples

+

Terminal-style screenshots for the deployment docs, showing what successful dryrun and run wrapper output look like in practice.

+
+ +
+
+

Successful dry-run summary

+

Use in deployment docs near the aspen -m=dryrun example.

+
+
+
+
+
bash • ASPEN dryrun example
+
+ 
$ aspen --workdir=<WORKDIR> --runmode=dryrun
+STEP  [dryrun] Running preflight checks
+INFO  Validating config, samples, and runtime dependencies
+INFO  Rendering the planned Snakemake DAG without execution
+OK    Dry-run completed.
+INFO  Full dry-run output captured in <WORKDIR>/dryrun.log
+NEXT  Submit run with: aspen --workdir=<WORKDIR> --runmode=run
+
+
+ +
+
+

Successful run submission summary

+

Use in deployment docs near the aspen -m=run and monitoring guidance.

+
+
+
+
+
bash • ASPEN run example
+
+ 
$ aspen --workdir=<WORKDIR> --runmode=run
+OK    Dry-run was successful.
+STEP  [run] Preparing workdir for new execution
+OK    Created <WORKDIR>/submit_script.sbatch
+INFO  State marker updated: pipeline.running (reason=submission_started, slurm_job_id=NA)
+INFO  State marker updated: pipeline.running (reason=sbatch_submitted, slurm_job_id=<jobid>)
+---------------------------------------------------------------------
+OK    Job submitted successfully (SLURM job ID: <jobid>)
+NEXT  Monitor:  squeue -u $USER
+NEXT  Progress: tail -f <WORKDIR>/snakemake.log
+NEXT  Status:   ls -1 <WORKDIR>/pipeline.*
+NEXT  Sidecar:  <WORKDIR>/pipeline.status.json
+
+
+
+ + diff --git a/docs/assets/images/aspen_dryrun_console.svg b/docs/assets/images/aspen_dryrun_console.svg new file mode 100644 index 0000000..cb3542d --- /dev/null +++ b/docs/assets/images/aspen_dryrun_console.svg @@ -0,0 +1,55 @@ + + ASPEN successful dry-run console output + Terminal-style screenshot showing successful ASPEN dry-run output and next-step guidance. + + + + + + + + + + + + + + ASPEN Docs Asset + Successful dry-run summary + Example image for deployment docs near the aspen dryrun command. + + + + + + + + + + + bash • ASPEN dryrun example + + + $ aspen --workdir=<WORKDIR> --runmode=dryrun + STEP [dryrun] Running preflight checks + INFO Validating config, samples, and runtime dependencies + INFO Rendering the planned Snakemake DAG without execution + OK Dry-run completed. + INFO Full dry-run output captured in <WORKDIR>/dryrun.log + NEXT Submit run with: aspen --workdir=<WORKDIR> --runmode=run + + diff --git a/docs/assets/images/aspen_run_console.svg b/docs/assets/images/aspen_run_console.svg new file mode 100644 index 0000000..f91a717 --- /dev/null +++ b/docs/assets/images/aspen_run_console.svg @@ -0,0 +1,62 @@ + + ASPEN successful run submission console output + Terminal-style screenshot showing successful ASPEN run submission output, state marker updates, and monitoring hints. + + + + + + + + + + + + + + ASPEN Docs Asset + Successful run submission summary + Example image for deployment docs near the run command and monitoring guidance. + + + + + + + + + + + bash • ASPEN run example + + + $ aspen --workdir=<WORKDIR> --runmode=run + OK Dry-run was successful. + STEP [run] Preparing workdir for new execution + OK Created <WORKDIR>/submit_script.sbatch + INFO State marker updated: pipeline.running (reason=submission_started, slurm_job_id=NA) + INFO State marker updated: pipeline.running (reason=sbatch_submitted, slurm_job_id=<jobid>) + --------------------------------------------------------------------- + OK Job submitted successfully (SLURM job ID: <jobid>) + NEXT Monitor: squeue -u $USER + NEXT Progress: tail -f <WORKDIR>/snakemake.log + NEXT Status: ls -1 <WORKDIR>/pipeline.* + NEXT Sidecar: <WORKDIR>/pipeline.status.json + + diff --git a/docs/deployment.md b/docs/deployment.md index b3bd591..022a550 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -307,31 +307,30 @@ aspen -m=run -w= -c /data/${USER}/.singularity This example is for a non-Biowulf HPC system where you want to manage your own Singularity cache location. -grep "done$" /snakemake.log +## 📊 Monitor ASPEN Runs + +For day-to-day status checks, use the sidecar and `pipeline.*` files below first. They are the fastest and most reliable way to see whether ASPEN is running, completed, or failed. Reach for `squeue` and `scontrol` only when you want an advanced scheduler-level view or need to inspect an individual SLURM job. + +If you do need to inspect the cluster directly, `squeue` shows the queue state and `scontrol` exposes detailed job metadata. + ### 📝 Pipeline State Markers: the primary status check ASPEN writes a set of state-tracking files directly into `WORKDIR` while a `run` is executing, so you can check status from the sidecar and `pipeline.*` files first, even without Slurm access (for example, from a laptop over `ssh`): - `pipeline.running`, `pipeline.completed`, `pipeline.failed`, `pipeline.canceled` — exactly one of these marker files exists at a time, reflecting the current state. While the pipeline is running, `pipeline.running` is periodically refreshed by a background progress monitor with a human-readable summary, including the percentage of Snakemake steps completed so far: - ```bash - cat /pipeline.running - ``` + ```bash + cat /pipeline.running + ``` - `pipeline.status.json` — a machine-readable sidecar with the same information (`state`, `reason`, `slurm_job_id`, start/end timestamps, `duration_seconds`, `tasks_done`/`tasks_total`, `exit_code`), useful for scripting/automation: - ```bash - cat /pipeline.status.json - ``` + ```bash + cat /pipeline.status.json + ``` - `snakemake.log.jobby` / `snakemake.log.jobby.short` — a `jobby` TSV summary of per-rule/job resource usage, generated as a best-effort step after the run finishes (even if the Slurm submission itself failed before Snakemake started). -## 📊 Monitor ASPEN Runs - -For day-to-day status checks, use the sidecar and `pipeline.*` files above first. They are the fastest and most reliable way to see whether ASPEN is running, completed, or failed. Reach for `squeue` and `scontrol` only when you want an advanced scheduler-level view or need to inspect an individual SLURM job. - -If you do need to inspect the cluster directly, `squeue` shows the queue state and `scontrol` exposes detailed job metadata. - To view all your active and pending jobs, execute: ```bash From bb4eb03a777e9e6fed6cd9d0d4e1bb4d1a1dd299 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 19:15:27 +0000 Subject: [PATCH 04/24] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/deployment.md | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 022a550..fe54d0f 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,30 +31,30 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y - `path_to_R2_fastq`: Absolute path to the Read 2 FASTQ file (required for paired-end data). !!! note - Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. +Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. !!! note - The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. +The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. !!! warning "Biological vs. technical replicates" - ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. +ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. - Biological replicates are independent samples: +Biological replicates are independent samples: - - **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. - - **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. +- **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. +- **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. - Example of concatenating technical replicates before running ASPEN: +Example of concatenating technical replicates before running ASPEN: - ```bash - cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz - cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz - ``` +```bash +cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz +cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz +``` - DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. +DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. !!! note - For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. +For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. ## 🏃 Running the ASPEN Pipeline @@ -319,15 +319,15 @@ ASPEN writes a set of state-tracking files directly into `WORKDIR` while a `run` - `pipeline.running`, `pipeline.completed`, `pipeline.failed`, `pipeline.canceled` — exactly one of these marker files exists at a time, reflecting the current state. While the pipeline is running, `pipeline.running` is periodically refreshed by a background progress monitor with a human-readable summary, including the percentage of Snakemake steps completed so far: - ```bash - cat /pipeline.running - ``` + ```bash + cat /pipeline.running + ``` - `pipeline.status.json` — a machine-readable sidecar with the same information (`state`, `reason`, `slurm_job_id`, start/end timestamps, `duration_seconds`, `tasks_done`/`tasks_total`, `exit_code`), useful for scripting/automation: - ```bash - cat /pipeline.status.json - ``` + ```bash + cat /pipeline.status.json + ``` - `snakemake.log.jobby` / `snakemake.log.jobby.short` — a `jobby` TSV summary of per-rule/job resource usage, generated as a best-effort step after the run finishes (even if the Slurm submission itself failed before Snakemake started). From e2a8c541aa3bb7a22c989b66ab41af1faf4368ba Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 15:16:49 -0400 Subject: [PATCH 05/24] docs(overview): fix admonition formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Indent the tip callout bodies so MkDocs renders them as proper admonitions on ghpages. ⚡ Generated using AI ⚡ --- docs/overview.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index 3678a5a..a6e8f74 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -116,21 +116,21 @@ ASPEN employs custom scripts to analyze the distribution of fragment lengths wit To evaluate the sufficiency of sequencing depth and detect potential biases introduced during PCR amplification, ASPEN utilizes Preseq to estimate library complexity, reporting the Non-Redundant Fraction (`NRF`) and PCR Bottlenecking Coefficients (`PBC1`, `PBC2`). This metric helps determine whether the sequencing effort is adequate to capture the diversity of the library, ensuring that the data is representative of the underlying chromatin landscape. By identifying potential saturation or over-representation of certain fragments, researchers can assess the reliability of their sequencing results. !!! tip "Rule of thumb" -Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. + Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. ### 🧬 **Transcription Start Site (TSS) Enrichment** ASPEN calculates TSS enrichment scores, a widely recognized quality metric for ATAC-seq data. These scores measure the accumulation of sequencing reads around transcription start sites (TSS), which are hallmark regions of open chromatin. High TSS enrichment scores indicate well-prepared libraries with minimal technical artifacts, as they reflect the accessibility of promoter regions and the integrity of the chromatin preparation process. !!! tip "Rule of thumb" -[ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. + [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. ### 📊 **Fraction of Reads in Peaks (FRiP)** The Fraction of Reads in Peaks (FRiP) score quantifies the proportion of sequencing reads that fall within identified peaks, serving as a measure of the signal-to-noise ratio in the dataset. Higher FRiP scores indicate datasets with strong, biologically meaningful signals and minimal background noise. Additionally, ASPEN computes the fraction of reads localized to specific genomic features, such as promoters, enhancers, and DNase hypersensitive sites (DHS). These feature-specific FRiP scores provide further insights into the quality and biological relevance of the data. !!! tip "Rule of thumb" -Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. + Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. --- @@ -151,11 +151,11 @@ If a project later needs de novo motif discovery, that can be added as a separate workflow enhancement rather than mixed into the default run. !!! tip "Rule of thumb" -Start by looking for motif families that are strong in **both** HOMER and -AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values -and a clear increase in `% of Target Sequences with Motif` relative to -background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` -is clearly higher than `%FP`. + Start by looking for motif families that are strong in **both** HOMER and + AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values + and a clear increase in `% of Target Sequences with Motif` relative to + background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` + is clearly higher than `%FP`. Detailed file locations and interpretation notes for `knownResults.txt`, `ame_results.txt`, `target.fa`, and `background.fa` are documented in From 1f7065bc9dafc686e77b7db699e5d1cec59b99d2 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 19:18:06 +0000 Subject: [PATCH 06/24] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/overview.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index a6e8f74..3678a5a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -116,21 +116,21 @@ ASPEN employs custom scripts to analyze the distribution of fragment lengths wit To evaluate the sufficiency of sequencing depth and detect potential biases introduced during PCR amplification, ASPEN utilizes Preseq to estimate library complexity, reporting the Non-Redundant Fraction (`NRF`) and PCR Bottlenecking Coefficients (`PBC1`, `PBC2`). This metric helps determine whether the sequencing effort is adequate to capture the diversity of the library, ensuring that the data is representative of the underlying chromatin landscape. By identifying potential saturation or over-representation of certain fragments, researchers can assess the reliability of their sequencing results. !!! tip "Rule of thumb" - Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. +Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. ### 🧬 **Transcription Start Site (TSS) Enrichment** ASPEN calculates TSS enrichment scores, a widely recognized quality metric for ATAC-seq data. These scores measure the accumulation of sequencing reads around transcription start sites (TSS), which are hallmark regions of open chromatin. High TSS enrichment scores indicate well-prepared libraries with minimal technical artifacts, as they reflect the accessibility of promoter regions and the integrity of the chromatin preparation process. !!! tip "Rule of thumb" - [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. +[ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. ### 📊 **Fraction of Reads in Peaks (FRiP)** The Fraction of Reads in Peaks (FRiP) score quantifies the proportion of sequencing reads that fall within identified peaks, serving as a measure of the signal-to-noise ratio in the dataset. Higher FRiP scores indicate datasets with strong, biologically meaningful signals and minimal background noise. Additionally, ASPEN computes the fraction of reads localized to specific genomic features, such as promoters, enhancers, and DNase hypersensitive sites (DHS). These feature-specific FRiP scores provide further insights into the quality and biological relevance of the data. !!! tip "Rule of thumb" - Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. +Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. --- @@ -151,11 +151,11 @@ If a project later needs de novo motif discovery, that can be added as a separate workflow enhancement rather than mixed into the default run. !!! tip "Rule of thumb" - Start by looking for motif families that are strong in **both** HOMER and - AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values - and a clear increase in `% of Target Sequences with Motif` relative to - background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` - is clearly higher than `%FP`. +Start by looking for motif families that are strong in **both** HOMER and +AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values +and a clear increase in `% of Target Sequences with Motif` relative to +background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` +is clearly higher than `%FP`. Detailed file locations and interpretation notes for `knownResults.txt`, `ame_results.txt`, `target.fa`, and `background.fa` are documented in From 3b1ed81e1e250254200249979f996359b9e0d4b0 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 15:19:25 -0400 Subject: [PATCH 07/24] docs(overview): fix spike-in callout formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rewrite the spike-in normalization tip so the yes/no guidance renders as regular admonition text instead of a code-like block on ghpages. ⚡ Generated using AI ⚡ --- docs/overview.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index 3678a5a..6a4b6a3 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -212,10 +212,11 @@ In ASPEN, if spike-in data is present: This spike-in-derived scaling factor allows the comparison of chromatin accessibility across conditions even when global chromatin accessibility levels differ (e.g., treatment-induced repression or global decondensation). !!! tip "Should I turn on spike-in normalization?" -Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? + Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? - - **Yes** (e.g. a chromatin remodeler inhibitor, a broad transcription factor knockdown/knockout, drug-induced chromatin modulation) → turn on spike-in normalization. Standard depth-based normalization (DESeq2 size factors) assumes *most* regions are unchanged between conditions — that assumption breaks down under a genome-wide shift, and spike-in gives you an external, biology-independent scale instead. - - **No** (you expect differences to be confined to specific loci/pathways, with most of the genome unchanged) → spike-in is probably unnecessary. It adds experimental complexity (extra reagents, a second alignment step, and a "0 spike-in reads" failure mode to manage — see the warning below) for a scenario DESeq2's built-in normalization already handles well. + **Yes** (for example, a chromatin remodeler inhibitor, a broad transcription factor knockdown/knockout, or drug-induced chromatin modulation) → turn on spike-in normalization. Standard depth-based normalization (DESeq2 size factors) assumes *most* regions are unchanged between conditions, and that assumption breaks down under a genome-wide shift. Spike-in gives you an external, biology-independent scale instead. + + **No** (you expect differences to be confined to specific loci/pathways, with most of the genome unchanged) → spike-in is probably unnecessary. It adds experimental complexity (extra reagents, a second alignment step, and a "0 spike-in reads" failure mode to manage — see the warning below) for a scenario DESeq2's built-in normalization already handles well. See [Enabling Spike-In Normalization](deployment.md#enabling-spike-in-normalization-optional) for the config steps once you've decided to use it. From 8add0f7f0fb5513b8eaf1f20552eba7bad1f77fc Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 19:20:30 +0000 Subject: [PATCH 08/24] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview.md b/docs/overview.md index 6a4b6a3..e4e227a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -212,7 +212,7 @@ In ASPEN, if spike-in data is present: This spike-in-derived scaling factor allows the comparison of chromatin accessibility across conditions even when global chromatin accessibility levels differ (e.g., treatment-induced repression or global decondensation). !!! tip "Should I turn on spike-in normalization?" - Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? +Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? **Yes** (for example, a chromatin remodeler inhibitor, a broad transcription factor knockdown/knockout, or drug-induced chromatin modulation) → turn on spike-in normalization. Standard depth-based normalization (DESeq2 size factors) assumes *most* regions are unchanged between conditions, and that assumption breaks down under a genome-wide shift. Spike-in gives you an external, biology-independent scale instead. From b71d738edc3149ddf135a9002f085df5a90f5336 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 15:28:59 -0400 Subject: [PATCH 09/24] docs(overview): fix spike-in warning formatting MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Indent the zero-spike-in warning body so it renders as a proper MkDocs admonition alongside the spike-in normalization tip. ⚡ Generated using AI ⚡ --- docs/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview.md b/docs/overview.md index e4e227a..5b207e8 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -223,7 +223,7 @@ Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibi ASPEN performs spike-in-aware normalization transparently, and reports both raw and normalized counts in the final output matrix for differential analysis. This ensures flexibility in downstream interpretation while preserving the ability to adjust for systemic experimental artifacts. !!! warning "What if a replicate has 0 spike-in reads?" -If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. + If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. ### 📊 **Reporting** From 280ddac99a7073896c51066c53300e38b9302bcf Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 19:30:08 +0000 Subject: [PATCH 10/24] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview.md b/docs/overview.md index 5b207e8..e4e227a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -223,7 +223,7 @@ Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibi ASPEN performs spike-in-aware normalization transparently, and reports both raw and normalized counts in the final output matrix for differential analysis. This ensures flexibility in downstream interpretation while preserving the ability to adjust for systemic experimental artifacts. !!! warning "What if a replicate has 0 spike-in reads?" - If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. +If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. ### 📊 **Reporting** From 8a93c6d6fb42d4ee5d8ec86bd3492e82cf8871f0 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 15:32:38 -0400 Subject: [PATCH 11/24] docs: fix admonition indentation in markdown docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Indent MkDocs admonition bodies across the ASPEN docs so notes, tips, and warnings render consistently on ghpages. ⚡ Generated using AI ⚡ --- docs/deployment.md | 28 ++++++++++++------------- docs/index.md | 6 +++--- docs/outputs.md | 28 ++++++++++++------------- docs/overview.md | 52 +++++++++++++++++++++++----------------------- 4 files changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index fe54d0f..c91dc4b 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,30 +31,30 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y - `path_to_R2_fastq`: Absolute path to the Read 2 FASTQ file (required for paired-end data). !!! note -Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. + Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. !!! note -The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. + The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. !!! warning "Biological vs. technical replicates" -ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. + ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. -Biological replicates are independent samples: + Biological replicates are independent samples: -- **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. -- **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. + - **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. + - **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. -Example of concatenating technical replicates before running ASPEN: + Example of concatenating technical replicates before running ASPEN: -```bash -cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz -cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz -``` + ```bash + cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz + cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz + ``` -DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. + DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. !!! note -For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. + For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. ## 🏃 Running the ASPEN Pipeline @@ -71,7 +71,7 @@ aspen -m=init -w= This command generates a config.yaml and a placeholder `samples.tsv` in the specified directory. Edit these files to reflect your experimental setup, replacing the placeholder `samples.tsv` with your prepared manifest. If performing differential analysis, include the `contrasts.tsv` file at this stage. !!! note -To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` + To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` Here is what help looks like: diff --git a/docs/index.md b/docs/index.md index 67714c2..acab70f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,8 @@ ## Background !!! tip "New here?" -If you just want to **run the pipeline**, skip ahead to -[Running ASPEN](deployment.md). Come back here later for the -scientific background on ATAC-seq and why ASPEN is built the way it is. + If you just want to **run the pipeline**, skip ahead to + [Running ASPEN](deployment.md). Come back here later for the + scientific background on ATAC-seq and why ASPEN is built the way it is. The Assay for Transposase-Accessible Chromatin using sequencing (ATAC-seq) has revolutionized genomics by providing a rapid and sensitive method to assess chromatin accessibility across the genome. This technique offers profound insights into gene regulation, epigenetic modifications, and the dynamic landscape of the chromatin environment. To facilitate the comprehensive analysis of ATAC-seq data, the Center for Cancer Research (CCR) Collaborative Bioinformatics Resource (CCBR) has developed ASPEN (**A**tac **S**eq **P**ip**E**li**N**e), an automated, robust, reproducible pipeline designed using the Snakemake pipelining framework to streamline the complexities inherent in ATAC-seq data processing. diff --git a/docs/outputs.md b/docs/outputs.md index 579b884..bb261c2 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -144,13 +144,13 @@ Content details: | tmp | various | - Can be deleted.
- Blacklist index.
- Intermediate FASTQs.
- Genrich output reads. | !!! note -BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline + BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline !!! note -[bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. + [bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. !!! note -BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. + BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. #### How consensus peaks are generated @@ -212,13 +212,13 @@ sample3.consensus.bed ─► fixed-width peaks ─┘ !!! tip "Config knobs that control consensus" -| Parameter | Default | Round | Effect | -| -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | -| `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | -| `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | -| `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | -| `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | -| `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | + | Parameter | Default | Round | Effect | + | -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | + | `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | + | `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | + | `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | + | `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | + | `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | #### Counts matrices: reads vs Tn5 nicking sites, and `dedup` vs `nondedup` @@ -448,10 +448,10 @@ while sample-level `*.consensus.bed` inputs use all consensus peaks. If your replicate and consensus motif results differ, this is one reason why. !!! tip -If you need to confirm the exact HOMER settings used in a finished run, -start with `motifFindingParameters.txt`. If you want to reproduce the AME -input precisely, reuse the `target.fa` and `background.fa` files in the -same output folder. + If you need to confirm the exact HOMER settings used in a finished run, + start with `motifFindingParameters.txt`. If you want to reproduce the AME + input precisely, reuse the `target.fa` and `background.fa` files in the + same output folder. #### Interpreting motif enrichment results diff --git a/docs/overview.md b/docs/overview.md index e4e227a..9dba026 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -59,23 +59,23 @@ Genrich is integrated into the pipeline to complement MACS2. This tool is partic By combining the strengths of MACS2 and Genrich, ASPEN delivers a comprehensive and reliable peak detection framework, facilitating downstream analyses and enabling researchers to uncover critical insights into chromatin accessibility and gene regulation. !!! tip "Which peak caller should I use?" -Both MACS2 and Genrich run automatically for every sample — you -don't have to choose upfront. **Genrich is generally -recommended for ATAC-seq** because it was purpose-built for -assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut -sites directly (`-j` ATAC-seq mode) rather than adapting a -ChIP-seq fragment-shift model, and it combines biological -replicates natively via Fisher's method instead of requiring a -separate consensus step. **MACS2** was originally designed for -ChIP-seq and requires ATAC-specific parameter workarounds to -approximate cut-site signal, but remains the field standard — -it's included because many reviewers and downstream tools -expect to see MACS2 peaks, and comparing both gives an extra -sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq -data has generally found Genrich peaks to be higher quality. If -your MACS2 and Genrich DiffATAC results disagree substantially -for a given region, treat that region as lower-confidence -rather than assuming one caller is unconditionally "right". + Both MACS2 and Genrich run automatically for every sample — you + don't have to choose upfront. **Genrich is generally + recommended for ATAC-seq** because it was purpose-built for + assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut + sites directly (`-j` ATAC-seq mode) rather than adapting a + ChIP-seq fragment-shift model, and it combines biological + replicates natively via Fisher's method instead of requiring a + separate consensus step. **MACS2** was originally designed for + ChIP-seq and requires ATAC-specific parameter workarounds to + approximate cut-site signal, but remains the field standard — + it's included because many reviewers and downstream tools + expect to see MACS2 peaks, and comparing both gives an extra + sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq + data has generally found Genrich peaks to be higher quality. If + your MACS2 and Genrich DiffATAC results disagree substantially + for a given region, treat that region as lower-confidence + rather than assuming one caller is unconditionally "right". ### 🤝 **Consensus Peaks** @@ -116,21 +116,21 @@ ASPEN employs custom scripts to analyze the distribution of fragment lengths wit To evaluate the sufficiency of sequencing depth and detect potential biases introduced during PCR amplification, ASPEN utilizes Preseq to estimate library complexity, reporting the Non-Redundant Fraction (`NRF`) and PCR Bottlenecking Coefficients (`PBC1`, `PBC2`). This metric helps determine whether the sequencing effort is adequate to capture the diversity of the library, ensuring that the data is representative of the underlying chromatin landscape. By identifying potential saturation or over-representation of certain fragments, researchers can assess the reliability of their sequencing results. !!! tip "Rule of thumb" -Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. + Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. ### 🧬 **Transcription Start Site (TSS) Enrichment** ASPEN calculates TSS enrichment scores, a widely recognized quality metric for ATAC-seq data. These scores measure the accumulation of sequencing reads around transcription start sites (TSS), which are hallmark regions of open chromatin. High TSS enrichment scores indicate well-prepared libraries with minimal technical artifacts, as they reflect the accessibility of promoter regions and the integrity of the chromatin preparation process. !!! tip "Rule of thumb" -[ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. + [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. ### 📊 **Fraction of Reads in Peaks (FRiP)** The Fraction of Reads in Peaks (FRiP) score quantifies the proportion of sequencing reads that fall within identified peaks, serving as a measure of the signal-to-noise ratio in the dataset. Higher FRiP scores indicate datasets with strong, biologically meaningful signals and minimal background noise. Additionally, ASPEN computes the fraction of reads localized to specific genomic features, such as promoters, enhancers, and DNase hypersensitive sites (DHS). These feature-specific FRiP scores provide further insights into the quality and biological relevance of the data. !!! tip "Rule of thumb" -Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. + Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. --- @@ -151,11 +151,11 @@ If a project later needs de novo motif discovery, that can be added as a separate workflow enhancement rather than mixed into the default run. !!! tip "Rule of thumb" -Start by looking for motif families that are strong in **both** HOMER and -AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values -and a clear increase in `% of Target Sequences with Motif` relative to -background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` -is clearly higher than `%FP`. + Start by looking for motif families that are strong in **both** HOMER and + AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values + and a clear increase in `% of Target Sequences with Motif` relative to + background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` + is clearly higher than `%FP`. Detailed file locations and interpretation notes for `knownResults.txt`, `ame_results.txt`, `target.fa`, and `background.fa` are documented in @@ -212,7 +212,7 @@ In ASPEN, if spike-in data is present: This spike-in-derived scaling factor allows the comparison of chromatin accessibility across conditions even when global chromatin accessibility levels differ (e.g., treatment-induced repression or global decondensation). !!! tip "Should I turn on spike-in normalization?" -Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? + Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? **Yes** (for example, a chromatin remodeler inhibitor, a broad transcription factor knockdown/knockout, or drug-induced chromatin modulation) → turn on spike-in normalization. Standard depth-based normalization (DESeq2 size factors) assumes *most* regions are unchanged between conditions, and that assumption breaks down under a genome-wide shift. Spike-in gives you an external, biology-independent scale instead. From 0a13d3b74f8dc0eac95e9ffb6f8c3b9403b8813e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 19:34:08 +0000 Subject: [PATCH 12/24] =?UTF-8?q?ci:=20=F0=9F=A4=96=20format=20everything?= =?UTF-8?q?=20with=20pre-commit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/deployment.md | 28 ++++++++++++------------- docs/index.md | 6 +++--- docs/outputs.md | 28 ++++++++++++------------- docs/overview.md | 52 +++++++++++++++++++++++----------------------- 4 files changed, 57 insertions(+), 57 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index c91dc4b..fe54d0f 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,30 +31,30 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y - `path_to_R2_fastq`: Absolute path to the Read 2 FASTQ file (required for paired-end data). !!! note - Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. +Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. !!! note - The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. +The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. !!! warning "Biological vs. technical replicates" - ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. +ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. - Biological replicates are independent samples: +Biological replicates are independent samples: - - **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. - - **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. +- **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. +- **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. - Example of concatenating technical replicates before running ASPEN: +Example of concatenating technical replicates before running ASPEN: - ```bash - cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz - cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz - ``` +```bash +cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz +cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz +``` - DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. +DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. !!! note - For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. +For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. ## 🏃 Running the ASPEN Pipeline @@ -71,7 +71,7 @@ aspen -m=init -w= This command generates a config.yaml and a placeholder `samples.tsv` in the specified directory. Edit these files to reflect your experimental setup, replacing the placeholder `samples.tsv` with your prepared manifest. If performing differential analysis, include the `contrasts.tsv` file at this stage. !!! note - To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` +To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` Here is what help looks like: diff --git a/docs/index.md b/docs/index.md index acab70f..67714c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,8 @@ ## Background !!! tip "New here?" - If you just want to **run the pipeline**, skip ahead to - [Running ASPEN](deployment.md). Come back here later for the - scientific background on ATAC-seq and why ASPEN is built the way it is. +If you just want to **run the pipeline**, skip ahead to +[Running ASPEN](deployment.md). Come back here later for the +scientific background on ATAC-seq and why ASPEN is built the way it is. The Assay for Transposase-Accessible Chromatin using sequencing (ATAC-seq) has revolutionized genomics by providing a rapid and sensitive method to assess chromatin accessibility across the genome. This technique offers profound insights into gene regulation, epigenetic modifications, and the dynamic landscape of the chromatin environment. To facilitate the comprehensive analysis of ATAC-seq data, the Center for Cancer Research (CCR) Collaborative Bioinformatics Resource (CCBR) has developed ASPEN (**A**tac **S**eq **P**ip**E**li**N**e), an automated, robust, reproducible pipeline designed using the Snakemake pipelining framework to streamline the complexities inherent in ATAC-seq data processing. diff --git a/docs/outputs.md b/docs/outputs.md index bb261c2..579b884 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -144,13 +144,13 @@ Content details: | tmp | various | - Can be deleted.
- Blacklist index.
- Intermediate FASTQs.
- Genrich output reads. | !!! note - BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline +BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline !!! note - [bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. +[bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. !!! note - BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. +BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. #### How consensus peaks are generated @@ -212,13 +212,13 @@ sample3.consensus.bed ─► fixed-width peaks ─┘ !!! tip "Config knobs that control consensus" - | Parameter | Default | Round | Effect | - | -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | - | `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | - | `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | - | `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | - | `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | - | `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | +| Parameter | Default | Round | Effect | +| -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | +| `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | +| `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | +| `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | +| `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | +| `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | #### Counts matrices: reads vs Tn5 nicking sites, and `dedup` vs `nondedup` @@ -448,10 +448,10 @@ while sample-level `*.consensus.bed` inputs use all consensus peaks. If your replicate and consensus motif results differ, this is one reason why. !!! tip - If you need to confirm the exact HOMER settings used in a finished run, - start with `motifFindingParameters.txt`. If you want to reproduce the AME - input precisely, reuse the `target.fa` and `background.fa` files in the - same output folder. +If you need to confirm the exact HOMER settings used in a finished run, +start with `motifFindingParameters.txt`. If you want to reproduce the AME +input precisely, reuse the `target.fa` and `background.fa` files in the +same output folder. #### Interpreting motif enrichment results diff --git a/docs/overview.md b/docs/overview.md index 9dba026..e4e227a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -59,23 +59,23 @@ Genrich is integrated into the pipeline to complement MACS2. This tool is partic By combining the strengths of MACS2 and Genrich, ASPEN delivers a comprehensive and reliable peak detection framework, facilitating downstream analyses and enabling researchers to uncover critical insights into chromatin accessibility and gene regulation. !!! tip "Which peak caller should I use?" - Both MACS2 and Genrich run automatically for every sample — you - don't have to choose upfront. **Genrich is generally - recommended for ATAC-seq** because it was purpose-built for - assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut - sites directly (`-j` ATAC-seq mode) rather than adapting a - ChIP-seq fragment-shift model, and it combines biological - replicates natively via Fisher's method instead of requiring a - separate consensus step. **MACS2** was originally designed for - ChIP-seq and requires ATAC-specific parameter workarounds to - approximate cut-site signal, but remains the field standard — - it's included because many reviewers and downstream tools - expect to see MACS2 peaks, and comparing both gives an extra - sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq - data has generally found Genrich peaks to be higher quality. If - your MACS2 and Genrich DiffATAC results disagree substantially - for a given region, treat that region as lower-confidence - rather than assuming one caller is unconditionally "right". +Both MACS2 and Genrich run automatically for every sample — you +don't have to choose upfront. **Genrich is generally +recommended for ATAC-seq** because it was purpose-built for +assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut +sites directly (`-j` ATAC-seq mode) rather than adapting a +ChIP-seq fragment-shift model, and it combines biological +replicates natively via Fisher's method instead of requiring a +separate consensus step. **MACS2** was originally designed for +ChIP-seq and requires ATAC-specific parameter workarounds to +approximate cut-site signal, but remains the field standard — +it's included because many reviewers and downstream tools +expect to see MACS2 peaks, and comparing both gives an extra +sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq +data has generally found Genrich peaks to be higher quality. If +your MACS2 and Genrich DiffATAC results disagree substantially +for a given region, treat that region as lower-confidence +rather than assuming one caller is unconditionally "right". ### 🤝 **Consensus Peaks** @@ -116,21 +116,21 @@ ASPEN employs custom scripts to analyze the distribution of fragment lengths wit To evaluate the sufficiency of sequencing depth and detect potential biases introduced during PCR amplification, ASPEN utilizes Preseq to estimate library complexity, reporting the Non-Redundant Fraction (`NRF`) and PCR Bottlenecking Coefficients (`PBC1`, `PBC2`). This metric helps determine whether the sequencing effort is adequate to capture the diversity of the library, ensuring that the data is representative of the underlying chromatin landscape. By identifying potential saturation or over-representation of certain fragments, researchers can assess the reliability of their sequencing results. !!! tip "Rule of thumb" - Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. +Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. ### 🧬 **Transcription Start Site (TSS) Enrichment** ASPEN calculates TSS enrichment scores, a widely recognized quality metric for ATAC-seq data. These scores measure the accumulation of sequencing reads around transcription start sites (TSS), which are hallmark regions of open chromatin. High TSS enrichment scores indicate well-prepared libraries with minimal technical artifacts, as they reflect the accessibility of promoter regions and the integrity of the chromatin preparation process. !!! tip "Rule of thumb" - [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. +[ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. ### 📊 **Fraction of Reads in Peaks (FRiP)** The Fraction of Reads in Peaks (FRiP) score quantifies the proportion of sequencing reads that fall within identified peaks, serving as a measure of the signal-to-noise ratio in the dataset. Higher FRiP scores indicate datasets with strong, biologically meaningful signals and minimal background noise. Additionally, ASPEN computes the fraction of reads localized to specific genomic features, such as promoters, enhancers, and DNase hypersensitive sites (DHS). These feature-specific FRiP scores provide further insights into the quality and biological relevance of the data. !!! tip "Rule of thumb" - Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. +Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. --- @@ -151,11 +151,11 @@ If a project later needs de novo motif discovery, that can be added as a separate workflow enhancement rather than mixed into the default run. !!! tip "Rule of thumb" - Start by looking for motif families that are strong in **both** HOMER and - AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values - and a clear increase in `% of Target Sequences with Motif` relative to - background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` - is clearly higher than `%FP`. +Start by looking for motif families that are strong in **both** HOMER and +AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values +and a clear increase in `% of Target Sequences with Motif` relative to +background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` +is clearly higher than `%FP`. Detailed file locations and interpretation notes for `knownResults.txt`, `ame_results.txt`, `target.fa`, and `background.fa` are documented in @@ -212,7 +212,7 @@ In ASPEN, if spike-in data is present: This spike-in-derived scaling factor allows the comparison of chromatin accessibility across conditions even when global chromatin accessibility levels differ (e.g., treatment-induced repression or global decondensation). !!! tip "Should I turn on spike-in normalization?" - Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? +Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? **Yes** (for example, a chromatin remodeler inhibitor, a broad transcription factor knockdown/knockout, or drug-induced chromatin modulation) → turn on spike-in normalization. Standard depth-based normalization (DESeq2 size factors) assumes *most* regions are unchanged between conditions, and that assumption breaks down under a genome-wide shift. Spike-in gives you an external, biology-independent scale instead. From 7aa301d55f0ed603ab6d90e93d591c48de128e0c Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 15:39:49 -0400 Subject: [PATCH 13/24] docs(overview): indent spike-in warning body MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make the orange spike-in warning render as a proper admonition by indenting its body in the overview docs. ⚡ Generated using AI ⚡ --- docs/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview.md b/docs/overview.md index e4e227a..5b207e8 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -223,7 +223,7 @@ Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibi ASPEN performs spike-in-aware normalization transparently, and reports both raw and normalized counts in the final output matrix for differential analysis. This ensures flexibility in downstream interpretation while preserving the ability to adjust for systemic experimental artifacts. !!! warning "What if a replicate has 0 spike-in reads?" -If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. + If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. ### 📊 **Reporting** From 5942e96fa316766b15c0727890f821dc3ece793e Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 19:41:05 +0000 Subject: [PATCH 14/24] =?UTF-8?q?ci:=20=F0=9F=A4=96=20format=20everything?= =?UTF-8?q?=20with=20pre-commit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview.md b/docs/overview.md index 5b207e8..e4e227a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -223,7 +223,7 @@ Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibi ASPEN performs spike-in-aware normalization transparently, and reports both raw and normalized counts in the final output matrix for differential analysis. This ensures flexibility in downstream interpretation while preserving the ability to adjust for systemic experimental artifacts. !!! warning "What if a replicate has 0 spike-in reads?" - If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. +If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. ### 📊 **Reporting** From eed7f4104ab6bb49a35762b2d783a963f0c9965d Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 15:41:48 -0400 Subject: [PATCH 15/24] docs(outputs): indent remaining admonitions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Make the remaining note and tip callouts in outputs.md render as proper MkDocs admonitions, including the consensus table and motif guidance. ⚡ Generated using AI ⚡ --- docs/outputs.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/outputs.md b/docs/outputs.md index 579b884..bb261c2 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -144,13 +144,13 @@ Content details: | tmp | various | - Can be deleted.
- Blacklist index.
- Intermediate FASTQs.
- Genrich output reads. | !!! note -BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline + BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline !!! note -[bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. + [bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. !!! note -BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. + BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. #### How consensus peaks are generated @@ -212,13 +212,13 @@ sample3.consensus.bed ─► fixed-width peaks ─┘ !!! tip "Config knobs that control consensus" -| Parameter | Default | Round | Effect | -| -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | -| `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | -| `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | -| `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | -| `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | -| `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | + | Parameter | Default | Round | Effect | + | -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | + | `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | + | `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | + | `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | + | `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | + | `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | #### Counts matrices: reads vs Tn5 nicking sites, and `dedup` vs `nondedup` @@ -448,10 +448,10 @@ while sample-level `*.consensus.bed` inputs use all consensus peaks. If your replicate and consensus motif results differ, this is one reason why. !!! tip -If you need to confirm the exact HOMER settings used in a finished run, -start with `motifFindingParameters.txt`. If you want to reproduce the AME -input precisely, reuse the `target.fa` and `background.fa` files in the -same output folder. + If you need to confirm the exact HOMER settings used in a finished run, + start with `motifFindingParameters.txt`. If you want to reproduce the AME + input precisely, reuse the `target.fa` and `background.fa` files in the + same output folder. #### Interpreting motif enrichment results From 2af0268bedca3e3323754a05bd7f55a26b5395c5 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 19:42:49 +0000 Subject: [PATCH 16/24] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/outputs.md | 28 ++++++++++++++-------------- 1 file changed, 14 insertions(+), 14 deletions(-) diff --git a/docs/outputs.md b/docs/outputs.md index bb261c2..579b884 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -144,13 +144,13 @@ Content details: | tmp | various | - Can be deleted.
- Blacklist index.
- Intermediate FASTQs.
- Genrich output reads. | !!! note - BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline +BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline !!! note - [bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. +[bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. !!! note - BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. +BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. #### How consensus peaks are generated @@ -212,13 +212,13 @@ sample3.consensus.bed ─► fixed-width peaks ─┘ !!! tip "Config knobs that control consensus" - | Parameter | Default | Round | Effect | - | -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | - | `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | - | `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | - | `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | - | `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | - | `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | +| Parameter | Default | Round | Effect | +| -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | +| `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | +| `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | +| `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | +| `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | +| `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | #### Counts matrices: reads vs Tn5 nicking sites, and `dedup` vs `nondedup` @@ -448,10 +448,10 @@ while sample-level `*.consensus.bed` inputs use all consensus peaks. If your replicate and consensus motif results differ, this is one reason why. !!! tip - If you need to confirm the exact HOMER settings used in a finished run, - start with `motifFindingParameters.txt`. If you want to reproduce the AME - input precisely, reuse the `target.fa` and `background.fa` files in the - same output folder. +If you need to confirm the exact HOMER settings used in a finished run, +start with `motifFindingParameters.txt`. If you want to reproduce the AME +input precisely, reuse the `target.fa` and `background.fa` files in the +same output folder. #### Interpreting motif enrichment results From dfc810f5a014bbb3ceb6a10c630e5611314c2077 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 15:43:22 -0400 Subject: [PATCH 17/24] docs(deployment): indent note callouts MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Indent the deployment note and warning bodies so the callouts render consistently on ghpages. ⚡ Generated using AI ⚡ --- docs/deployment.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index fe54d0f..3827e6e 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,30 +31,30 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y - `path_to_R2_fastq`: Absolute path to the Read 2 FASTQ file (required for paired-end data). !!! note -Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. + Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. !!! note -The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. + The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. !!! warning "Biological vs. technical replicates" -ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. + ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. -Biological replicates are independent samples: + Biological replicates are independent samples: -- **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. -- **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. + - **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. + - **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. -Example of concatenating technical replicates before running ASPEN: + Example of concatenating technical replicates before running ASPEN: -```bash -cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz -cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz -``` + ```bash + cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz + cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz + ``` -DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. + DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. !!! note -For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. + For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. ## 🏃 Running the ASPEN Pipeline From fbe8e220fdce4716b6d907c4cccee33a7de326c6 Mon Sep 17 00:00:00 2001 From: "github-actions[bot]" <41898282+github-actions[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 19:44:49 +0000 Subject: [PATCH 18/24] =?UTF-8?q?ci:=20=F0=9F=A4=96=20format=20everything?= =?UTF-8?q?=20with=20pre-commit?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- docs/deployment.md | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 3827e6e..fe54d0f 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,30 +31,30 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y - `path_to_R2_fastq`: Absolute path to the Read 2 FASTQ file (required for paired-end data). !!! note - Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. +Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. !!! note - The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. +The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. !!! warning "Biological vs. technical replicates" - ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. +ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. - Biological replicates are independent samples: +Biological replicates are independent samples: - - **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. - - **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. +- **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. +- **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. - Example of concatenating technical replicates before running ASPEN: +Example of concatenating technical replicates before running ASPEN: - ```bash - cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz - cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz - ``` +```bash +cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz +cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz +``` - DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. +DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. !!! note - For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. +For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. ## 🏃 Running the ASPEN Pipeline From 66da8791f37f9b006935a9144e24ce7bd15ec6e6 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 16:00:13 -0400 Subject: [PATCH 19/24] docs: fix markdown admonition rendering MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Indent MkDocs admonition bodies across the documentation so notes, tips, and warnings render consistently on ghpages. ⚡ Generated using AI ⚡ --- docs/deployment.md | 31 +++++++++++++------------- docs/index.md | 6 ++--- docs/limitations.md | 52 +++++++++++++++++++++---------------------- docs/outputs.md | 28 +++++++++++------------ docs/overview.md | 54 ++++++++++++++++++++++----------------------- 5 files changed, 86 insertions(+), 85 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index fe54d0f..6756db5 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,30 +31,30 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y - `path_to_R2_fastq`: Absolute path to the Read 2 FASTQ file (required for paired-end data). !!! note -Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. + Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. !!! note -The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. + The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. !!! warning "Biological vs. technical replicates" -ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. + ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. -Biological replicates are independent samples: + Biological replicates are independent samples: -- **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. -- **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. + - **Biological**: independent biological samples (separate cultures, animals, patients, etc.). Use one row per sample in `samples.tsv`. + - **Technical**: the same sample re-sequenced across multiple lanes or runs. `cat` the FASTQs together first, then use one row. -Example of concatenating technical replicates before running ASPEN: + Example of concatenating technical replicates before running ASPEN: -```bash -cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz -cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz -``` + ```bash + cat sample1_L001_R1.fastq.gz sample1_L002_R1.fastq.gz > sample1_R1.fastq.gz + cat sample1_L001_R2.fastq.gz sample1_L002_R2.fastq.gz > sample1_R2.fastq.gz + ``` -DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. + DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. !!! note -For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. + For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. ## 🏃 Running the ASPEN Pipeline @@ -71,11 +71,12 @@ aspen -m=init -w= This command generates a config.yaml and a placeholder `samples.tsv` in the specified directory. Edit these files to reflect your experimental setup, replacing the placeholder `samples.tsv` with your prepared manifest. If performing differential analysis, include the `contrasts.tsv` file at this stage. !!! note -To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` + To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` Here is what help looks like: -> **Note**: This is illustrative example output captured at doc-writing time — exact values (e.g. `pipeline_home`, `git commit/tag`, `aspen_version`) will differ depending on which ASPEN version/branch is installed at your site. Run `aspen --help` yourself to see the current values for your installation. +!!! note + This is illustrative example output captured at doc-writing time — exact values (e.g. `pipeline_home`, `git commit/tag`, `aspen_version`) will differ depending on which ASPEN version/branch is installed at your site. Run `aspen --help` yourself to see the current values for your installation. ```bash diff --git a/docs/index.md b/docs/index.md index 67714c2..978d5e0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,8 @@ ## Background !!! tip "New here?" -If you just want to **run the pipeline**, skip ahead to -[Running ASPEN](deployment.md). Come back here later for the -scientific background on ATAC-seq and why ASPEN is built the way it is. + If you just want to **run the pipeline**, skip ahead to + [Running ASPEN](deployment.md). Come back here later for the + scientific background on ATAC-seq and why ASPEN is built the way it is. The Assay for Transposase-Accessible Chromatin using sequencing (ATAC-seq) has revolutionized genomics by providing a rapid and sensitive method to assess chromatin accessibility across the genome. This technique offers profound insights into gene regulation, epigenetic modifications, and the dynamic landscape of the chromatin environment. To facilitate the comprehensive analysis of ATAC-seq data, the Center for Cancer Research (CCR) Collaborative Bioinformatics Resource (CCBR) has developed ASPEN (**A**tac **S**eq **P**ip**E**li**N**e), an automated, robust, reproducible pipeline designed using the Snakemake pipelining framework to streamline the complexities inherent in ATAC-seq data processing. diff --git a/docs/limitations.md b/docs/limitations.md index 7eed620..59c86d3 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -18,32 +18,32 @@ | hs1 | Human | _Homo sapiens_ (T2T-CHM13) | | hs1_chrR | Human | _Homo sapiens_ (T2T-CHM13 + chrR rDNA unit; see note below) | - !!! tip "Use `hs1_chrR` for ribosomal DNA chromatin accessibility studies" - Standard genome assemblies mask or collapse ribosomal DNA (rDNA) repeat - loci, making it impossible to call ATAC-seq peaks in these regions. - `hs1_chrR` is a customized version of the T2T-CHM13 (`hs1`) assembly - where endogenous rDNA-like sequences are masked throughout the canonical - chromosomes, and a single consensus rDNA unit (NCBI KY962518.1, modified) - is inserted as an additional chromosome **chrR**. This design ensures that - rDNA-mapping reads are captured unambiguously on chrR rather than being - lost to multi-mapping or suppressed by masking. - - **When to choose `hs1_chrR` over `hs1`:** - - - Your experiment involves a perturbation that may affect nucleolar - chromatin or ribosomal gene accessibility (e.g., RNA Pol I inhibition, - nucleolar stress, epigenetic reprogramming). - - You want to quantify ATAC-seq peaks at rDNA promoters, the transcribed - region, or the intergenic spacer (IGS) of the ribosomal repeat unit. - - You need FRiP scores, TSS enrichment, or differential accessibility - analysis specifically for rDNA loci alongside the rest of the genome. - - **Reference:** - George SS, Pimkin M, Paralkar VR. - *"Construction and validation of customized genomes for human and mouse ribosomal DNA mapping."* - J Biol Chem (2023). - - Genome files: +!!! tip "Use `hs1_chrR` for ribosomal DNA chromatin accessibility studies" + Standard genome assemblies mask or collapse ribosomal DNA (rDNA) repeat + loci, making it impossible to call ATAC-seq peaks in these regions. + `hs1_chrR` is a customized version of the T2T-CHM13 (`hs1`) assembly + where endogenous rDNA-like sequences are masked throughout the canonical + chromosomes, and a single consensus rDNA unit (NCBI KY962518.1, modified) + is inserted as an additional chromosome **chrR**. This design ensures that + rDNA-mapping reads are captured unambiguously on chrR rather than being + lost to multi-mapping or suppressed by masking. + + **When to choose `hs1_chrR` over `hs1`:** + + - Your experiment involves a perturbation that may affect nucleolar + chromatin or ribosomal gene accessibility (e.g., RNA Pol I inhibition, + nucleolar stress, epigenetic reprogramming). + - You want to quantify ATAC-seq peaks at rDNA promoters, the transcribed + region, or the intergenic spacer (IGS) of the ribosomal repeat unit. + - You need FRiP scores, TSS enrichment, or differential accessibility + analysis specifically for rDNA loci alongside the rest of the genome. + + **Reference:** + George SS, Pimkin M, Paralkar VR. + *"Construction and validation of customized genomes for human and mouse ribosomal DNA mapping."* + J Biol Chem (2023). + + Genome files: - **Spike-in genomes supported**: Spike-in genomes supported is limited to: diff --git a/docs/outputs.md b/docs/outputs.md index 579b884..82af38c 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -144,13 +144,13 @@ Content details: | tmp | various | - Can be deleted.
- Blacklist index.
- Intermediate FASTQs.
- Genrich output reads. | !!! note -BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline + BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline !!! note -[bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. + [bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. !!! note -BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. + BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. #### How consensus peaks are generated @@ -212,13 +212,13 @@ sample3.consensus.bed ─► fixed-width peaks ─┘ !!! tip "Config knobs that control consensus" -| Parameter | Default | Round | Effect | -| -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | -| `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | -| `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | -| `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | -| `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | -| `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | + | Parameter | Default | Round | Effect | + | -------------------------- | ------- | ----- | ---------------------------------------------------------------------------------------- | + | `consensus_min_replicates` | `2` | 1 | Min. replicates a peak must appear in to be retained in per-sample consensus | + | `consensus_min_spm` | `5` | 1 | Min. signal-per-million reads threshold for a peak to be included | + | `roi_min_replicates` | `1` | 2 | Min. samples/replicates a fixed-width peak must appear in to be kept in the ROI set | + | `roi_min_spm` | `2` | 2 | Min. signal-per-million reads threshold for a fixed-width peak to be kept in the ROI set | + | `fixed_width` | `500` | 1 | Width (bp) of fixed-width peaks used to build the ROI set | #### Counts matrices: reads vs Tn5 nicking sites, and `dedup` vs `nondedup` @@ -448,10 +448,10 @@ while sample-level `*.consensus.bed` inputs use all consensus peaks. If your replicate and consensus motif results differ, this is one reason why. !!! tip -If you need to confirm the exact HOMER settings used in a finished run, -start with `motifFindingParameters.txt`. If you want to reproduce the AME -input precisely, reuse the `target.fa` and `background.fa` files in the -same output folder. + If you need to confirm the exact HOMER settings used in a finished run, + start with `motifFindingParameters.txt`. If you want to reproduce the AME + input precisely, reuse the `target.fa` and `background.fa` files in the + same output folder. #### Interpreting motif enrichment results diff --git a/docs/overview.md b/docs/overview.md index e4e227a..5c0a20b 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -59,23 +59,23 @@ Genrich is integrated into the pipeline to complement MACS2. This tool is partic By combining the strengths of MACS2 and Genrich, ASPEN delivers a comprehensive and reliable peak detection framework, facilitating downstream analyses and enabling researchers to uncover critical insights into chromatin accessibility and gene regulation. !!! tip "Which peak caller should I use?" -Both MACS2 and Genrich run automatically for every sample — you -don't have to choose upfront. **Genrich is generally -recommended for ATAC-seq** because it was purpose-built for -assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut -sites directly (`-j` ATAC-seq mode) rather than adapting a -ChIP-seq fragment-shift model, and it combines biological -replicates natively via Fisher's method instead of requiring a -separate consensus step. **MACS2** was originally designed for -ChIP-seq and requires ATAC-specific parameter workarounds to -approximate cut-site signal, but remains the field standard — -it's included because many reviewers and downstream tools -expect to see MACS2 peaks, and comparing both gives an extra -sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq -data has generally found Genrich peaks to be higher quality. If -your MACS2 and Genrich DiffATAC results disagree substantially -for a given region, treat that region as lower-confidence -rather than assuming one caller is unconditionally "right". + Both MACS2 and Genrich run automatically for every sample — you + don't have to choose upfront. **Genrich is generally + recommended for ATAC-seq** because it was purpose-built for + assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut + sites directly (`-j` ATAC-seq mode) rather than adapting a + ChIP-seq fragment-shift model, and it combines biological + replicates natively via Fisher's method instead of requiring a + separate consensus step. **MACS2** was originally designed for + ChIP-seq and requires ATAC-specific parameter workarounds to + approximate cut-site signal, but remains the field standard — + it's included because many reviewers and downstream tools + expect to see MACS2 peaks, and comparing both gives an extra + sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq + data has generally found Genrich peaks to be higher quality. If + your MACS2 and Genrich DiffATAC results disagree substantially + for a given region, treat that region as lower-confidence + rather than assuming one caller is unconditionally "right". ### 🤝 **Consensus Peaks** @@ -116,21 +116,21 @@ ASPEN employs custom scripts to analyze the distribution of fragment lengths wit To evaluate the sufficiency of sequencing depth and detect potential biases introduced during PCR amplification, ASPEN utilizes Preseq to estimate library complexity, reporting the Non-Redundant Fraction (`NRF`) and PCR Bottlenecking Coefficients (`PBC1`, `PBC2`). This metric helps determine whether the sequencing effort is adequate to capture the diversity of the library, ensuring that the data is representative of the underlying chromatin landscape. By identifying potential saturation or over-representation of certain fragments, researchers can assess the reliability of their sequencing results. !!! tip "Rule of thumb" -Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. + Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. ### 🧬 **Transcription Start Site (TSS) Enrichment** ASPEN calculates TSS enrichment scores, a widely recognized quality metric for ATAC-seq data. These scores measure the accumulation of sequencing reads around transcription start sites (TSS), which are hallmark regions of open chromatin. High TSS enrichment scores indicate well-prepared libraries with minimal technical artifacts, as they reflect the accessibility of promoter regions and the integrity of the chromatin preparation process. !!! tip "Rule of thumb" -[ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. + [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. ### 📊 **Fraction of Reads in Peaks (FRiP)** The Fraction of Reads in Peaks (FRiP) score quantifies the proportion of sequencing reads that fall within identified peaks, serving as a measure of the signal-to-noise ratio in the dataset. Higher FRiP scores indicate datasets with strong, biologically meaningful signals and minimal background noise. Additionally, ASPEN computes the fraction of reads localized to specific genomic features, such as promoters, enhancers, and DNase hypersensitive sites (DHS). These feature-specific FRiP scores provide further insights into the quality and biological relevance of the data. !!! tip "Rule of thumb" -Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. + Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. --- @@ -151,11 +151,11 @@ If a project later needs de novo motif discovery, that can be added as a separate workflow enhancement rather than mixed into the default run. !!! tip "Rule of thumb" -Start by looking for motif families that are strong in **both** HOMER and -AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values -and a clear increase in `% of Target Sequences with Motif` relative to -background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` -is clearly higher than `%FP`. + Start by looking for motif families that are strong in **both** HOMER and + AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values + and a clear increase in `% of Target Sequences with Motif` relative to + background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` + is clearly higher than `%FP`. Detailed file locations and interpretation notes for `knownResults.txt`, `ame_results.txt`, `target.fa`, and `background.fa` are documented in @@ -212,7 +212,7 @@ In ASPEN, if spike-in data is present: This spike-in-derived scaling factor allows the comparison of chromatin accessibility across conditions even when global chromatin accessibility levels differ (e.g., treatment-induced repression or global decondensation). !!! tip "Should I turn on spike-in normalization?" -Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? + Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? **Yes** (for example, a chromatin remodeler inhibitor, a broad transcription factor knockdown/knockout, or drug-induced chromatin modulation) → turn on spike-in normalization. Standard depth-based normalization (DESeq2 size factors) assumes *most* regions are unchanged between conditions, and that assumption breaks down under a genome-wide shift. Spike-in gives you an external, biology-independent scale instead. @@ -223,7 +223,7 @@ Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibi ASPEN performs spike-in-aware normalization transparently, and reports both raw and normalized counts in the final output matrix for differential analysis. This ensures flexibility in downstream interpretation while preserving the ability to adjust for systemic experimental artifacts. !!! warning "What if a replicate has 0 spike-in reads?" -If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. + If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. ### 📊 **Reporting** From 04868195c8b6906393bde9ea35d0ab6219d5e01f Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Fri, 25 Sep 2026 20:01:25 +0000 Subject: [PATCH 20/24] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- docs/deployment.md | 12 +++++----- docs/index.md | 6 ++--- docs/limitations.md | 16 +++++++------- docs/outputs.md | 14 ++++++------ docs/overview.md | 54 ++++++++++++++++++++++----------------------- 5 files changed, 51 insertions(+), 51 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 6756db5..991ca10 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,13 +31,13 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y - `path_to_R2_fastq`: Absolute path to the Read 2 FASTQ file (required for paired-end data). !!! note - Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. +Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. !!! note - The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. +The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. !!! warning "Biological vs. technical replicates" - ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. +ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. Biological replicates are independent samples: @@ -54,7 +54,7 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. !!! note - For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. +For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. ## 🏃 Running the ASPEN Pipeline @@ -71,12 +71,12 @@ aspen -m=init -w= This command generates a config.yaml and a placeholder `samples.tsv` in the specified directory. Edit these files to reflect your experimental setup, replacing the placeholder `samples.tsv` with your prepared manifest. If performing differential analysis, include the `contrasts.tsv` file at this stage. !!! note - To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` +To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` Here is what help looks like: !!! note - This is illustrative example output captured at doc-writing time — exact values (e.g. `pipeline_home`, `git commit/tag`, `aspen_version`) will differ depending on which ASPEN version/branch is installed at your site. Run `aspen --help` yourself to see the current values for your installation. +This is illustrative example output captured at doc-writing time — exact values (e.g. `pipeline_home`, `git commit/tag`, `aspen_version`) will differ depending on which ASPEN version/branch is installed at your site. Run `aspen --help` yourself to see the current values for your installation. ```bash diff --git a/docs/index.md b/docs/index.md index 978d5e0..67714c2 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,8 @@ ## Background !!! tip "New here?" - If you just want to **run the pipeline**, skip ahead to - [Running ASPEN](deployment.md). Come back here later for the - scientific background on ATAC-seq and why ASPEN is built the way it is. +If you just want to **run the pipeline**, skip ahead to +[Running ASPEN](deployment.md). Come back here later for the +scientific background on ATAC-seq and why ASPEN is built the way it is. The Assay for Transposase-Accessible Chromatin using sequencing (ATAC-seq) has revolutionized genomics by providing a rapid and sensitive method to assess chromatin accessibility across the genome. This technique offers profound insights into gene regulation, epigenetic modifications, and the dynamic landscape of the chromatin environment. To facilitate the comprehensive analysis of ATAC-seq data, the Center for Cancer Research (CCR) Collaborative Bioinformatics Resource (CCBR) has developed ASPEN (**A**tac **S**eq **P**ip**E**li**N**e), an automated, robust, reproducible pipeline designed using the Snakemake pipelining framework to streamline the complexities inherent in ATAC-seq data processing. diff --git a/docs/limitations.md b/docs/limitations.md index 59c86d3..e20d7bf 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -19,14 +19,14 @@ | hs1_chrR | Human | _Homo sapiens_ (T2T-CHM13 + chrR rDNA unit; see note below) | !!! tip "Use `hs1_chrR` for ribosomal DNA chromatin accessibility studies" - Standard genome assemblies mask or collapse ribosomal DNA (rDNA) repeat - loci, making it impossible to call ATAC-seq peaks in these regions. - `hs1_chrR` is a customized version of the T2T-CHM13 (`hs1`) assembly - where endogenous rDNA-like sequences are masked throughout the canonical - chromosomes, and a single consensus rDNA unit (NCBI KY962518.1, modified) - is inserted as an additional chromosome **chrR**. This design ensures that - rDNA-mapping reads are captured unambiguously on chrR rather than being - lost to multi-mapping or suppressed by masking. +Standard genome assemblies mask or collapse ribosomal DNA (rDNA) repeat +loci, making it impossible to call ATAC-seq peaks in these regions. +`hs1_chrR` is a customized version of the T2T-CHM13 (`hs1`) assembly +where endogenous rDNA-like sequences are masked throughout the canonical +chromosomes, and a single consensus rDNA unit (NCBI KY962518.1, modified) +is inserted as an additional chromosome **chrR**. This design ensures that +rDNA-mapping reads are captured unambiguously on chrR rather than being +lost to multi-mapping or suppressed by masking. **When to choose `hs1_chrR` over `hs1`:** diff --git a/docs/outputs.md b/docs/outputs.md index 82af38c..155bbbc 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -144,13 +144,13 @@ Content details: | tmp | various | - Can be deleted.
- Blacklist index.
- Intermediate FASTQs.
- Genrich output reads. | !!! note - BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline +BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline !!! note - [bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. +[bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. !!! note - BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. +BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. #### How consensus peaks are generated @@ -448,10 +448,10 @@ while sample-level `*.consensus.bed` inputs use all consensus peaks. If your replicate and consensus motif results differ, this is one reason why. !!! tip - If you need to confirm the exact HOMER settings used in a finished run, - start with `motifFindingParameters.txt`. If you want to reproduce the AME - input precisely, reuse the `target.fa` and `background.fa` files in the - same output folder. +If you need to confirm the exact HOMER settings used in a finished run, +start with `motifFindingParameters.txt`. If you want to reproduce the AME +input precisely, reuse the `target.fa` and `background.fa` files in the +same output folder. #### Interpreting motif enrichment results diff --git a/docs/overview.md b/docs/overview.md index 5c0a20b..e4e227a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -59,23 +59,23 @@ Genrich is integrated into the pipeline to complement MACS2. This tool is partic By combining the strengths of MACS2 and Genrich, ASPEN delivers a comprehensive and reliable peak detection framework, facilitating downstream analyses and enabling researchers to uncover critical insights into chromatin accessibility and gene regulation. !!! tip "Which peak caller should I use?" - Both MACS2 and Genrich run automatically for every sample — you - don't have to choose upfront. **Genrich is generally - recommended for ATAC-seq** because it was purpose-built for - assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut - sites directly (`-j` ATAC-seq mode) rather than adapting a - ChIP-seq fragment-shift model, and it combines biological - replicates natively via Fisher's method instead of requiring a - separate consensus step. **MACS2** was originally designed for - ChIP-seq and requires ATAC-specific parameter workarounds to - approximate cut-site signal, but remains the field standard — - it's included because many reviewers and downstream tools - expect to see MACS2 peaks, and comparing both gives an extra - sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq - data has generally found Genrich peaks to be higher quality. If - your MACS2 and Genrich DiffATAC results disagree substantially - for a given region, treat that region as lower-confidence - rather than assuming one caller is unconditionally "right". +Both MACS2 and Genrich run automatically for every sample — you +don't have to choose upfront. **Genrich is generally +recommended for ATAC-seq** because it was purpose-built for +assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut +sites directly (`-j` ATAC-seq mode) rather than adapting a +ChIP-seq fragment-shift model, and it combines biological +replicates natively via Fisher's method instead of requiring a +separate consensus step. **MACS2** was originally designed for +ChIP-seq and requires ATAC-specific parameter workarounds to +approximate cut-site signal, but remains the field standard — +it's included because many reviewers and downstream tools +expect to see MACS2 peaks, and comparing both gives an extra +sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq +data has generally found Genrich peaks to be higher quality. If +your MACS2 and Genrich DiffATAC results disagree substantially +for a given region, treat that region as lower-confidence +rather than assuming one caller is unconditionally "right". ### 🤝 **Consensus Peaks** @@ -116,21 +116,21 @@ ASPEN employs custom scripts to analyze the distribution of fragment lengths wit To evaluate the sufficiency of sequencing depth and detect potential biases introduced during PCR amplification, ASPEN utilizes Preseq to estimate library complexity, reporting the Non-Redundant Fraction (`NRF`) and PCR Bottlenecking Coefficients (`PBC1`, `PBC2`). This metric helps determine whether the sequencing effort is adequate to capture the diversity of the library, ensuring that the data is representative of the underlying chromatin landscape. By identifying potential saturation or over-representation of certain fragments, researchers can assess the reliability of their sequencing results. !!! tip "Rule of thumb" - Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. +Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. ### 🧬 **Transcription Start Site (TSS) Enrichment** ASPEN calculates TSS enrichment scores, a widely recognized quality metric for ATAC-seq data. These scores measure the accumulation of sequencing reads around transcription start sites (TSS), which are hallmark regions of open chromatin. High TSS enrichment scores indicate well-prepared libraries with minimal technical artifacts, as they reflect the accessibility of promoter regions and the integrity of the chromatin preparation process. !!! tip "Rule of thumb" - [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. +[ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. ### 📊 **Fraction of Reads in Peaks (FRiP)** The Fraction of Reads in Peaks (FRiP) score quantifies the proportion of sequencing reads that fall within identified peaks, serving as a measure of the signal-to-noise ratio in the dataset. Higher FRiP scores indicate datasets with strong, biologically meaningful signals and minimal background noise. Additionally, ASPEN computes the fraction of reads localized to specific genomic features, such as promoters, enhancers, and DNase hypersensitive sites (DHS). These feature-specific FRiP scores provide further insights into the quality and biological relevance of the data. !!! tip "Rule of thumb" - Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. +Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. --- @@ -151,11 +151,11 @@ If a project later needs de novo motif discovery, that can be added as a separate workflow enhancement rather than mixed into the default run. !!! tip "Rule of thumb" - Start by looking for motif families that are strong in **both** HOMER and - AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values - and a clear increase in `% of Target Sequences with Motif` relative to - background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` - is clearly higher than `%FP`. +Start by looking for motif families that are strong in **both** HOMER and +AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values +and a clear increase in `% of Target Sequences with Motif` relative to +background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` +is clearly higher than `%FP`. Detailed file locations and interpretation notes for `knownResults.txt`, `ame_results.txt`, `target.fa`, and `background.fa` are documented in @@ -212,7 +212,7 @@ In ASPEN, if spike-in data is present: This spike-in-derived scaling factor allows the comparison of chromatin accessibility across conditions even when global chromatin accessibility levels differ (e.g., treatment-induced repression or global decondensation). !!! tip "Should I turn on spike-in normalization?" - Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? +Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? **Yes** (for example, a chromatin remodeler inhibitor, a broad transcription factor knockdown/knockout, or drug-induced chromatin modulation) → turn on spike-in normalization. Standard depth-based normalization (DESeq2 size factors) assumes *most* regions are unchanged between conditions, and that assumption breaks down under a genome-wide shift. Spike-in gives you an external, biology-independent scale instead. @@ -223,7 +223,7 @@ This spike-in-derived scaling factor allows the comparison of chromatin accessib ASPEN performs spike-in-aware normalization transparently, and reports both raw and normalized counts in the final output matrix for differential analysis. This ensures flexibility in downstream interpretation while preserving the ability to adjust for systemic experimental artifacts. !!! warning "What if a replicate has 0 spike-in reads?" - If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. +If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. ### 📊 **Reporting** From ea6bb02ee018617423f547a9df5a4250b2063fd4 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 16:07:02 -0400 Subject: [PATCH 21/24] docs(overview): update rendered callout markup MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Capture the remaining overview markdown change before syncing with the latest remote branch tip. ⚡ Generated using AI ⚡ --- docs/overview.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/overview.md b/docs/overview.md index e4e227a..0fa63e2 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -227,4 +227,4 @@ If `spikein: true` is set but a replicate has **zero reads** aligned to the spik ### 📊 **Reporting** -ASPEN enhances differential chromatin accessibility analysis by providing an interactive HTML report generated from DESeq2 results, featuring various visualizations. Additionally, it offers a TSV (tabl-delimited) file with integrated gene annotations, compatible with Microsoft Excel, enabling efficient data manipulation and facilitating the identification of genes near regions with altered accessibility. The Excel file is aggregated across all different contrasts queried in the project. +ASPEN enhances differential chromatin accessibility analysis by providing an interactive HTML report generated from DESeq2 results, featuring various visualizations. Additionally, it offers a TSV (tab-delimited) file with integrated gene annotations, compatible with Microsoft Excel, enabling efficient data manipulation and facilitating the identification of genes near regions with altered accessibility. The Excel file is aggregated across all different contrasts queried in the project. From f175f5e2d32536cc82143976bda10f4bf0e12784 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 16:10:20 -0400 Subject: [PATCH 22/24] ci(prettier): ignore MkDocs markdown pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Stop prettier from reformatting docs/*.md pages that use MkDocs admonition syntax requiring preserved indentation. ⚡ Generated using AI ⚡ --- .prettierignore | 1 + 1 file changed, 1 insertion(+) diff --git a/.prettierignore b/.prettierignore index f0a6037..c908443 100644 --- a/.prettierignore +++ b/.prettierignore @@ -6,3 +6,4 @@ results/ .DS_Store *.code-workspace assets/*.html +docs/*.md From 1448e236bef1e5060cf1f02832e79ea05d60922f Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 16:12:22 -0400 Subject: [PATCH 23/24] docs(overview): preserve MkDocs admonition indentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Keep the overview markdown admonitions indented so they render correctly on ghpages and are not flattened into plain paragraphs. ⚡ Generated using AI ⚡ --- docs/overview.md | 54 ++++++++++++++++++++++++------------------------ 1 file changed, 27 insertions(+), 27 deletions(-) diff --git a/docs/overview.md b/docs/overview.md index 0fa63e2..0a4267a 100644 --- a/docs/overview.md +++ b/docs/overview.md @@ -59,23 +59,23 @@ Genrich is integrated into the pipeline to complement MACS2. This tool is partic By combining the strengths of MACS2 and Genrich, ASPEN delivers a comprehensive and reliable peak detection framework, facilitating downstream analyses and enabling researchers to uncover critical insights into chromatin accessibility and gene regulation. !!! tip "Which peak caller should I use?" -Both MACS2 and Genrich run automatically for every sample — you -don't have to choose upfront. **Genrich is generally -recommended for ATAC-seq** because it was purpose-built for -assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut -sites directly (`-j` ATAC-seq mode) rather than adapting a -ChIP-seq fragment-shift model, and it combines biological -replicates natively via Fisher's method instead of requiring a -separate consensus step. **MACS2** was originally designed for -ChIP-seq and requires ATAC-specific parameter workarounds to -approximate cut-site signal, but remains the field standard — -it's included because many reviewers and downstream tools -expect to see MACS2 peaks, and comparing both gives an extra -sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq -data has generally found Genrich peaks to be higher quality. If -your MACS2 and Genrich DiffATAC results disagree substantially -for a given region, treat that region as lower-confidence -rather than assuming one caller is unconditionally "right". + Both MACS2 and Genrich run automatically for every sample — you + don't have to choose upfront. **Genrich is generally + recommended for ATAC-seq** because it was purpose-built for + assays like ATAC-seq/DNase-seq: it models Tn5 transposase cut + sites directly (`-j` ATAC-seq mode) rather than adapting a + ChIP-seq fragment-shift model, and it combines biological + replicates natively via Fisher's method instead of requiring a + separate consensus step. **MACS2** was originally designed for + ChIP-seq and requires ATAC-specific parameter workarounds to + approximate cut-site signal, but remains the field standard — + it's included because many reviewers and downstream tools + expect to see MACS2 peaks, and comparing both gives an extra + sanity check. CCBR's internal benchmarking on ASPEN's ATAC-seq + data has generally found Genrich peaks to be higher quality. If + your MACS2 and Genrich DiffATAC results disagree substantially + for a given region, treat that region as lower-confidence + rather than assuming one caller is unconditionally "right". ### 🤝 **Consensus Peaks** @@ -116,21 +116,21 @@ ASPEN employs custom scripts to analyze the distribution of fragment lengths wit To evaluate the sufficiency of sequencing depth and detect potential biases introduced during PCR amplification, ASPEN utilizes Preseq to estimate library complexity, reporting the Non-Redundant Fraction (`NRF`) and PCR Bottlenecking Coefficients (`PBC1`, `PBC2`). This metric helps determine whether the sequencing effort is adequate to capture the diversity of the library, ensuring that the data is representative of the underlying chromatin landscape. By identifying potential saturation or over-representation of certain fragments, researchers can assess the reliability of their sequencing results. !!! tip "Rule of thumb" -Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. + Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), the preferred values are **`NRF` > 0.9, `PBC1` > 0.9, and `PBC2` > 3**. Lower values indicate a less complex library (e.g. over-amplified by PCR), which can inflate apparent signal at a subset of loci rather than reflecting true biological accessibility. ### 🧬 **Transcription Start Site (TSS) Enrichment** ASPEN calculates TSS enrichment scores, a widely recognized quality metric for ATAC-seq data. These scores measure the accumulation of sequencing reads around transcription start sites (TSS), which are hallmark regions of open chromatin. High TSS enrichment scores indicate well-prepared libraries with minimal technical artifacts, as they reflect the accessibility of promoter regions and the integrity of the chromatin preparation process. !!! tip "Rule of thumb" -[ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. + [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards) define annotation-dependent TSS enrichment cutoffs — for example, using a GRCh38 RefSeq TSS annotation: **< 5 is concerning, 5-7 is acceptable, and > 7 is ideal**. **Caveat:** ASPEN builds its TSS bins from GENCODE (not RefSeq) gene annotations (see `resources/tssBed/`), so ENCODE's exact per-annotation cutoffs may not transfer precisely to ASPEN's TSS enrichment values — treat these numbers as directional guidance (aim for high single digits or higher) rather than an exact pass/fail threshold. ### 📊 **Fraction of Reads in Peaks (FRiP)** The Fraction of Reads in Peaks (FRiP) score quantifies the proportion of sequencing reads that fall within identified peaks, serving as a measure of the signal-to-noise ratio in the dataset. Higher FRiP scores indicate datasets with strong, biologically meaningful signals and minimal background noise. Additionally, ASPEN computes the fraction of reads localized to specific genomic features, such as promoters, enhancers, and DNase hypersensitive sites (DHS). These feature-specific FRiP scores provide further insights into the quality and biological relevance of the data. !!! tip "Rule of thumb" -Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. + Per [ENCODE's ATAC-seq data standards](https://www.encodeproject.org/atac-seq/#standards), a FRiP score **> 0.3** indicates high-quality data, though values **> 0.2** may still be acceptable. Consistently lower scores suggest poor signal-to-noise and warrant a closer look at library prep or peak-calling parameters. --- @@ -151,11 +151,11 @@ If a project later needs de novo motif discovery, that can be added as a separate workflow enhancement rather than mixed into the default run. !!! tip "Rule of thumb" -Start by looking for motif families that are strong in **both** HOMER and -AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values -and a clear increase in `% of Target Sequences with Motif` relative to -background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` -is clearly higher than `%FP`. + Start by looking for motif families that are strong in **both** HOMER and + AME. In HOMER, focus on motifs with very small `p-value`/`q-value` values + and a clear increase in `% of Target Sequences with Motif` relative to + background. In AME, focus on low `adj_p-value`/`E-value` hits where `%TP` + is clearly higher than `%FP`. Detailed file locations and interpretation notes for `knownResults.txt`, `ame_results.txt`, `target.fa`, and `background.fa` are documented in @@ -212,7 +212,7 @@ In ASPEN, if spike-in data is present: This spike-in-derived scaling factor allows the comparison of chromatin accessibility across conditions even when global chromatin accessibility levels differ (e.g., treatment-induced repression or global decondensation). !!! tip "Should I turn on spike-in normalization?" -Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? + Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibility between my conditions — rather than just **localized** changes at a handful of specific regulatory elements? **Yes** (for example, a chromatin remodeler inhibitor, a broad transcription factor knockdown/knockout, or drug-induced chromatin modulation) → turn on spike-in normalization. Standard depth-based normalization (DESeq2 size factors) assumes *most* regions are unchanged between conditions, and that assumption breaks down under a genome-wide shift. Spike-in gives you an external, biology-independent scale instead. @@ -223,7 +223,7 @@ Ask yourself: do I expect a **global, genome-wide shift** in chromatin accessibi ASPEN performs spike-in-aware normalization transparently, and reports both raw and normalized counts in the final output matrix for differential analysis. This ensures flexibility in downstream interpretation while preserving the ability to adjust for systemic experimental artifacts. !!! warning "What if a replicate has 0 spike-in reads?" -If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. + If `spikein: true` is set but a replicate has **zero reads** aligned to the spike-in genome (e.g. the spike-in material wasn't actually added to that library, the spike-in genome/index is misconfigured, or a genuinely contamination-free host-only library), ASPEN cannot compute a scaling factor for it and the run will **fail with a clear error message** naming the affected replicate(s) rather than silently producing `Inf`/`NaN` normalized counts. To resolve this: verify the spike-in genome/index path in `config.yaml`, confirm spike-in material was actually included during library prep for that replicate, or set `spikein: false` if none of your samples have spike-in material. ### 📊 **Reporting** From 1c2957f823c08f2e912ae2a17985238f5c114aa3 Mon Sep 17 00:00:00 2001 From: kopardev Date: Fri, 25 Sep 2026 16:16:36 -0400 Subject: [PATCH 24/24] docs: preserve admonition indentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Keep MkDocs admonition bodies indented across the remaining documentation pages so ghpages renders the callouts correctly. ⚡ Generated using AI ⚡ --- docs/deployment.md | 12 ++++++------ docs/index.md | 6 +++--- docs/limitations.md | 16 ++++++++-------- docs/outputs.md | 14 +++++++------- 4 files changed, 24 insertions(+), 24 deletions(-) diff --git a/docs/deployment.md b/docs/deployment.md index 991ca10..6756db5 100644 --- a/docs/deployment.md +++ b/docs/deployment.md @@ -31,13 +31,13 @@ ASPEN requires a sample manifest file (`samples.tsv`) to identify and organize y - `path_to_R2_fastq`: Absolute path to the Read 2 FASTQ file (required for paired-end data). !!! note -Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. + Symlinks for R1 and R2 files will be created in the results directory, named as `.R1.fastq.gz` and `.R2.fastq.gz`, respectively. Therefore, original filenames do not need to be altered. !!! note -The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. + The `replicateName` is used as a prefix for individual peak calls, while the `sampleName` serves as a prefix for consensus peak calls. !!! warning "Biological vs. technical replicates" -ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. + ASPEN expects **one row per biological replicate**. If you sequenced the same sample across multiple lanes or sequencing runs (technical replicates), you must **concatenate those FASTQ files into a single file** before creating your manifest — ASPEN does not merge lanes internally. Biological replicates are independent samples: @@ -54,7 +54,7 @@ ASPEN expects **one row per biological replicate**. If you sequenced the same sa DESeq2 (used in `diffatac`) requires **at least 2 biological replicates per group**. Technical replicates do not count as biological replicates and will not satisfy this requirement. !!! note -For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. + For differential ATAC analysis, create a `contrasts.tsv` file with two columns (Group1 and Group2 ... aka Sample1 and Sample2, without headers) and place it in the output directory after initialization. Ensure each group/sample in the contrast has at least two biological replicates, as DESeq2 requires this for accurate contrast calculations. ## 🏃 Running the ASPEN Pipeline @@ -71,12 +71,12 @@ aspen -m=init -w= This command generates a config.yaml and a placeholder `samples.tsv` in the specified directory. Edit these files to reflect your experimental setup, replacing the placeholder `samples.tsv` with your prepared manifest. If performing differential analysis, include the `contrasts.tsv` file at this stage. !!! note -To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` + To explore all possible options of the `aspen` command you can either run it without any arguments or run `aspen --help` Here is what help looks like: !!! note -This is illustrative example output captured at doc-writing time — exact values (e.g. `pipeline_home`, `git commit/tag`, `aspen_version`) will differ depending on which ASPEN version/branch is installed at your site. Run `aspen --help` yourself to see the current values for your installation. + This is illustrative example output captured at doc-writing time — exact values (e.g. `pipeline_home`, `git commit/tag`, `aspen_version`) will differ depending on which ASPEN version/branch is installed at your site. Run `aspen --help` yourself to see the current values for your installation. ```bash diff --git a/docs/index.md b/docs/index.md index 67714c2..978d5e0 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,8 +1,8 @@ ## Background !!! tip "New here?" -If you just want to **run the pipeline**, skip ahead to -[Running ASPEN](deployment.md). Come back here later for the -scientific background on ATAC-seq and why ASPEN is built the way it is. + If you just want to **run the pipeline**, skip ahead to + [Running ASPEN](deployment.md). Come back here later for the + scientific background on ATAC-seq and why ASPEN is built the way it is. The Assay for Transposase-Accessible Chromatin using sequencing (ATAC-seq) has revolutionized genomics by providing a rapid and sensitive method to assess chromatin accessibility across the genome. This technique offers profound insights into gene regulation, epigenetic modifications, and the dynamic landscape of the chromatin environment. To facilitate the comprehensive analysis of ATAC-seq data, the Center for Cancer Research (CCR) Collaborative Bioinformatics Resource (CCBR) has developed ASPEN (**A**tac **S**eq **P**ip**E**li**N**e), an automated, robust, reproducible pipeline designed using the Snakemake pipelining framework to streamline the complexities inherent in ATAC-seq data processing. diff --git a/docs/limitations.md b/docs/limitations.md index e20d7bf..59c86d3 100644 --- a/docs/limitations.md +++ b/docs/limitations.md @@ -19,14 +19,14 @@ | hs1_chrR | Human | _Homo sapiens_ (T2T-CHM13 + chrR rDNA unit; see note below) | !!! tip "Use `hs1_chrR` for ribosomal DNA chromatin accessibility studies" -Standard genome assemblies mask or collapse ribosomal DNA (rDNA) repeat -loci, making it impossible to call ATAC-seq peaks in these regions. -`hs1_chrR` is a customized version of the T2T-CHM13 (`hs1`) assembly -where endogenous rDNA-like sequences are masked throughout the canonical -chromosomes, and a single consensus rDNA unit (NCBI KY962518.1, modified) -is inserted as an additional chromosome **chrR**. This design ensures that -rDNA-mapping reads are captured unambiguously on chrR rather than being -lost to multi-mapping or suppressed by masking. + Standard genome assemblies mask or collapse ribosomal DNA (rDNA) repeat + loci, making it impossible to call ATAC-seq peaks in these regions. + `hs1_chrR` is a customized version of the T2T-CHM13 (`hs1`) assembly + where endogenous rDNA-like sequences are masked throughout the canonical + chromosomes, and a single consensus rDNA unit (NCBI KY962518.1, modified) + is inserted as an additional chromosome **chrR**. This design ensures that + rDNA-mapping reads are captured unambiguously on chrR rather than being + lost to multi-mapping or suppressed by masking. **When to choose `hs1_chrR` over `hs1`:** diff --git a/docs/outputs.md b/docs/outputs.md index 155bbbc..82af38c 100644 --- a/docs/outputs.md +++ b/docs/outputs.md @@ -144,13 +144,13 @@ Content details: | tmp | various | - Can be deleted.
- Blacklist index.
- Intermediate FASTQs.
- Genrich output reads. | !!! note -BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline + BAM files from `dedupBam` can be used for downstream footprinting analysis using [CCBR_TOBIAS](https://github.com/CCBR/CCBR_Tobias) pipeline !!! note -[bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. + [bamCompare](https://deeptools.readthedocs.io/en/develop/content/tools/bamCompare.html) from deeptools can be run to compare BAMs from `dedupBam` for comprehensive BAM comparisons. !!! note -BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. + BAM files from `dedupBam` can also be converted to BED format and processed with [chromVAR](https://github.com/GreenleafLab/chromVAR) to identify variability in motif accessibility across samples and assess differentially active transcription factors from the JASPAR database. #### How consensus peaks are generated @@ -448,10 +448,10 @@ while sample-level `*.consensus.bed` inputs use all consensus peaks. If your replicate and consensus motif results differ, this is one reason why. !!! tip -If you need to confirm the exact HOMER settings used in a finished run, -start with `motifFindingParameters.txt`. If you want to reproduce the AME -input precisely, reuse the `target.fa` and `background.fa` files in the -same output folder. + If you need to confirm the exact HOMER settings used in a finished run, + start with `motifFindingParameters.txt`. If you want to reproduce the AME + input precisely, reuse the `target.fa` and `background.fa` files in the + same output folder. #### Interpreting motif enrichment results