From 648046eb1c18d672334a8d8671623f561ed38c9a Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 20 Jun 2023 16:36:50 -0700 Subject: [PATCH 1/3] simplify docs generating process by using readthedocs, instead of github pages --- .readthedocs.yaml | 32 ++++++ docs/Makefile | 20 ++++ docs/README.md | 49 +++++++++ docs/_static/PMPLogo_500x421px_72dpi.png | Bin 0 -> 82025 bytes docs/conf.py | 93 ++++++++++++++++ docs/index.rst | 90 ++++++++++++++++ docs/install.rst | 61 +++++++++++ docs/make.bat | 35 +++++++ docs/metrics.rst | 21 ++++ docs/metrics_enso.rst | 39 +++++++ docs/metrics_mean-clim.rst | 78 ++++++++++++++ docs/metrics_mjo.rst | 58 ++++++++++ docs/metrics_monsoon.rst | 19 ++++ docs/metrics_mov.rst | 42 ++++++++ docs/overview.rst | 52 +++++++++ docs/pmp-using-cdp-guide.rst | 39 +++++++ docs/pmpparser.rst | 128 +++++++++++++++++++++++ docs/resources.rst | 12 +++ docs/start.rst | 10 ++ docs/subdaily-precipitation.rst | 24 +++++ docs/supporting-data.rst | 25 +++++ docs/team.rst | 18 ++++ 22 files changed, 945 insertions(+) create mode 100644 .readthedocs.yaml create mode 100644 docs/Makefile create mode 100755 docs/README.md create mode 100644 docs/_static/PMPLogo_500x421px_72dpi.png create mode 100644 docs/conf.py create mode 100644 docs/index.rst create mode 100644 docs/install.rst create mode 100644 docs/make.bat create mode 100644 docs/metrics.rst create mode 100644 docs/metrics_enso.rst create mode 100644 docs/metrics_mean-clim.rst create mode 100644 docs/metrics_mjo.rst create mode 100644 docs/metrics_monsoon.rst create mode 100644 docs/metrics_mov.rst create mode 100644 docs/overview.rst create mode 100644 docs/pmp-using-cdp-guide.rst create mode 100644 docs/pmpparser.rst create mode 100644 docs/resources.rst create mode 100644 docs/start.rst create mode 100644 docs/subdaily-precipitation.rst create mode 100644 docs/supporting-data.rst create mode 100644 docs/team.rst diff --git a/.readthedocs.yaml b/.readthedocs.yaml new file mode 100644 index 000000000..aa209bb21 --- /dev/null +++ b/.readthedocs.yaml @@ -0,0 +1,32 @@ +# .readthedocs.yaml +# Read the Docs configuration file +# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details + +# Required +version: 2 + +# Set the OS, Python version and other tools you might need +build: + os: ubuntu-22.04 + tools: + python: "3.11" + # You can also specify other tool versions: + # nodejs: "19" + # rust: "1.64" + # golang: "1.19" + +# Build documentation in the "docs/" directory with Sphinx +sphinx: + configuration: docs/conf.py + +# Optionally build your docs in additional formats such as PDF and ePub +# formats: +# - pdf +# - epub + +# Optional but recommended, declare the Python requirements required +# to build your documentation +# See https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html +# python: +# install: +# - requirements: docs/requirements.txt diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 000000000..84b8f84f4 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = python -msphinx +SPHINXPROJ = pcmdi_metrics +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md new file mode 100755 index 000000000..381f9b38c --- /dev/null +++ b/docs/README.md @@ -0,0 +1,49 @@ +gh-pages +-------- +This branch hosts the online documentation for the PCMDI Metrics packages. Provided here are instructions for updating the documentation. + +Checking out and making changes to the docs branch: +--------------------------------------------------- + +You must be in a conda environment with "sphinx" and "sphinx_rtd_theme" installed +``` +git pull origin main (optional, grab latest updates) +git checkout -b +cd docs +``` +The source files are found in pcmdi_metrics/docs/. There is an index.rst file that is the landing page. If you create a new page, make sure to list it under the toctree in index.rst. + +Building for local preview +-------------------------- +``` +cd pcmdi_metrics/docs +make clean +make html +``` +The `make clean` command is optional and deletes the existing docs/build folder, which is populated by `make html`. +To view your changes locally, open pcmdi_metrics/docs/build/html/index.html with a browser. If it does not build as expected, first try running `make clean` before building again. + +Build for readthedocs +--------------------- +After building, you then have to "git add" all the files you updated. + +For example: +``` +git add *rst _static/* +git commit -m "your message" +``` +Then you can push your changes. + +Pushing your changes to your fork to preview: +--------------------------------------------- +In pcmdi_metrics, set up your fork as a remote: +``` +git remote add +git remote -v +``` +Checkout and push your changes: +``` +git checkout +git push +``` +Then go to your forked repo on github.com and create a Pull Request to the `main` branch. Once merged, readthedocs webhook will automatically generate the web pages. diff --git a/docs/_static/PMPLogo_500x421px_72dpi.png b/docs/_static/PMPLogo_500x421px_72dpi.png new file mode 100644 index 0000000000000000000000000000000000000000..760396e36b2445eb453d03024765f985579f674b GIT binary patch literal 82025 zcmaI7WmH_twl<7wkl?Nf?lkTmf(Lik1{!GGo!}7M-GT>q3GNo$-QD#g`|NY?{qc>r z$LQ6yYE7$}PgTt|t2$IsUJ3T?R$;`sT%nD#+VdZ7v;bmbZ`}affuFb*3jQ5+k zo+<%q*74Ux<-)opm-g#MA#6(0ySh>Ww*tuC*CAhfR zc|;{yxy8jqMI-^75)%LAm9_;t8rmA0{#E*y*YbaPIsc!$ykZWfhK?Wy6%fe!zfh63 zwsrzLI{d9B6B8q2V`E|=qmeT-wzPEwfh}nN`tx6lO&u(qO-&>nKsIFmIE2^o|JdE|!iKWVRqOM^jfve&)aUw6=Vg z@K5PK!kGV$ihrvA51{```94bi7XN2>zTf=M05`RLAJq=;!Gjt zaR$6E;h&7Rjyxutvp>Mfw$qh)g9zxtyHqGz7>p?j{C6;^M2{>EnG&2>Efp>OupnC ztQ}NdO(d*ps_Tu2;CPp$SSxbke+m0n$mJMp1ESlz1V7t%ajjxqHr=c5va-|OrBkCW zQy)pDE3%|zbM^kC^3oQnkwyMH>Dg!s-ria?@)Xs!9Bc1iwXK+BOxx$Fc0^CS9|_zj zLdGNTr>N%teVEP!f!l|0Qr-R*7y*x8kBNEijd}iVJJbr6vb?shxxY*OT?WlWG<=Wy zne_I3JFD0#OzV3qgt>a-<6tj!Ael^jU738czEn~7HI~Dl^>DulGNG)(wEPc^ecl|K zUs`Hf9osCOCVgyX(${id4nCm#tPVOoH_q3r=wG`@nf)49)i~xh-|IvU?7vj6bZOB@ zo$$p5a8|r%Q^oA@A`T#)Q!W2%as=+?7HlJ#NTXj}Q<+?1CKpX+QdZCJ6Z7(nI{AZG zGN0r+fwDSj%m8Z^`Tb|Pri@{rdzMu2U8>!`UF9H3Ug6c2T*v;&b==s76A0EA=0lN} ziK!DSJBcG{sHvBjItTkX)!XFVks)8pHNJQFUr*xWjsy{rF#%WEHTlx&*bDmcx!q#- zsb!+7>J#cl%WRBo;DH}e(r?IYuNO6Z(M;|}(+vLAh)&AhQ}oLj5r|uJOOpS*a7Kk# zRqt0<_l+`AumbwT6)t-Z>V7M@1=0Dhe}%brRv_&eJ8#J3MJ#cDImg0W(C((l#R<;p zncJWMOEn3VI{9rOTu;{O#`|;sR|`QC)4(8_H#Tri2Hhpa9AF+QZRewBwSwdeth)<@ zTn0~WM%FrE9{=Osco)cl8j*Ae@ACXezSXgybs3L1+AuMNuLRb1zQCTm$??88n{&>NVQ>d^J;TU0u$JMcTD1mR{wZ2@&VcNJsagkfujyT@}>g1rcNx%fzPN za^9X?RoXjT-;sVs7Q^)gy#t?mf?8fNlih`BcQh@e@L-zNX;B5h7L$~e6n#(_(ZBT^ zYuhhQQPHf~`}EC#pe<(RI3c=e;QX9LOG~TD=S=W;r3K#O?zl_vc6skAqgYwY(oUiJ zRy`l;aB~a7lOMi(W#*q2LaoG4Pnp&sm?#1%5&}jjX#dE&eZFh!Gs`qy;!vI!o4rKq!(%$Z1u{w9Cl~wvd|0U94(Cr8hKxg`h_g+@p-p%DiS=J%s2ll? zQMrknXNi{8D-$Lsm8@5O1^s>*l}qE^7t5Itez)cIY~djT|6#2Y1HhRw*E3hiE<)N`<}%&v?!$UB+!HK zfH!02dg4rlDG;-;R{`6K==9G7I7AEQFx4m2uQhq$?ecqjuyHet-tJ&0$$0hI?dOv( zguEi5DI?Ygd*3W1t-H{L%FbF>KAjJz@qA>l1y-s)^aOOFKSK(^H?j68M099JDJBs<)WC+vw89@Kd1rp77Ji$2 zv!^X!9Mj8ND~pI1Qo5^L^*-RjoWJ6?ZPY2D@W3K}+YD!3-w1j2zp3mH?Cb2zzyD;D z0k!{3@cl?&j=dMCye7-uN=r2%$GT(V|G-nWGPwA|-ZGApo~h;7!SgvTtFt?(r1Q=K zfRr_kRyp3El|^HRc|JgTV)upCM2&FH&gR%<(zsBCjg?d&w!TA_A|PXGYrnB4(LEEm zzUtZs!AlYyvVOWj<*r$rJ(_jeK^pz~5__@RqTIRsCQ>GfI|zBa0JSe`v+~dC=m2F{ z0sCMw>y1<`ev}+ERJ?lMm1Z|wPP(PKuq{uD5aIA$S!-6jJIxj!it8bXSRNieb;WG2 zY2(rbQ^WY%E6+|&|2-!#Ovkawv<7`3m5&38)+@SrBYfPF!dQJfhu)90FuvI?P~cmb zZeYMFH@vrJDt|%G&fX5Vb9hU-le9B0n&1D)`^}@ap&{CQ&O_trBd{f#^S4y&DKM$d z(S}9$LsKQ3x&MF6WkW63v336LefieKJyfHnrnae^_3**A^`OtB!j%DM@3VqbYdd18 zi~M;$ja>s4qC7;=Q}8L}kU$ZQtH0SNy4^gf1>@6^bOU-n;Y1`t_|^=E@d6^pRNsL+ zURa1=niu)6y~DlYnZw*7d!c~a=jYb#9{-9ib_JoxwG}Y)?db~NZZ)#e`f??iT27oF z$?!xx%N%kx^sl+d|6&(EK+T&I*kNij>nifvh34}eIx(=5mw$7o@Mi0eaLMvd1UoLD zc)1~%BLkWNLp;=w#=f*Cm$o*yea~AH-0(-Z!>v6HWU+O zOLZn7kDwo0T4#gle(Ms0S?XWnxaafzI_39NafZy_9u$0n#o*DRoEnbEQ#V=w!qJws zE&`+;^^RQ1+W(pVB1Gu*2Nz$^y>^YKZf&2osm~9_p9%ThND#NlKcJ!*I|5uHzb*ZF z_)$QDwnhyZd5R2$zmqo&L(Y|)L2^DO;To12?^BUJW5P$;beyFF0UHE+{>6Zr{cS5+ zAXxwTcyIskkYIRY0>h!hg?Ze69IE)8VCUNR!Oe&>N5e<`c?g z^HF7gQv0Q;ifVY5?e-fn9?=kzL!PbNi$F9azYue@0+#DJ5p?3(+1|vEwWv_thCu8c z+etVT4@v5|>+-YK`6k~n(c}YxxfKDthoKUA7Rvx8J5u`7=!(mga5L+G)~xr4Ruty_q8>1ew5Hxx^dH!^E*UU!UB)WgUOZPHyA0x+uk*Qh;@0eqY%F0h${+c}MSJoq zI`R?^jF0aTG?8hzZns2>@n=I{gf>xA9CMKha7N^8qMPdGvfsaVTsXTm`6H{ zEL8Wx#u9{b=OVIxTeZz$a1{CAQ1j{DzS*XXhhYHBYBOgnrj!Y-`q@^tf>zW^!qB1Q zPiQ8(T_ZchbW>dT@OKHf=VfBn%(HCaw%qP+6Hh4Y!iS4@%=W)M%xf5t6{C-$X?Tdi z@5eGMHfQ<>EDhOG&HTmJPz&6y7UmN*865i#QJ0>MPQ=^m;@r7kn(g*dJ|Zew^to@t zhj0tiiM}gE4aH7KQ4t%xEIjU{%MenZH_#b=SCp6l_dKh=ae$$#m|7qVHG>-U<|GSH zL_=4iWDp+OWqvKZxDvj4l3YAM?2EY6!Z0h=Xd}_&q{#ger)br@f&F&%IL_}~reJ{% zBpe0W7QZ+b&dr>Ul2T|4$3o;J{=YFqs_Ffj9jMJ_aSbOUtm3hosAc1l!iN<<@fDoJ z;%A0k-!JrhDXrVP6v!`$>$8nJ><4)tF?v3wHAHhzWX|fp5d%evN6)puo}5+YKe^%m zhKGLx(BcH;b;5+pR(po?wvD#4-nrL3AH{E4-TIX0sHiBHDz()J5B{|1rDPqx&@|}h zSAhCzt2lSIq1$TXHzn)&rEtnNRv3&R-_anL6{%QXghOE=BR>)6Er|`fG&qj~6%APA z?p3BhI8;iuslknMt_+$?Cmsrz>pa4n@wib$DJ6m9&yiIgLowfjJ|6OYKeyw1N(=Yv zz?yA!m|w^e3uey0Ss)IV8oyWA~-KOBrd*7x+ec$M!wiwQX6)M+ahU zI%3pAtEzz#29%2zT_N0Dudnu2#1+N2BDImFd`*{!FlrO-R+|EWXemhXO{AhpxrR4oH%)&~ zi(~E-|6)O$BCN3z({v012Y_QR*jkc24M zfq=ic=3zi9i%w0a!6V#j<~DixCG>SS2vY%jn{WgzdVqhUtIG=i2Nd)p`@Nl?7fL}5 zl|Ea9tt=mIWWI_J;$KA3CZz*^?D0app1F`_i~|ZyEf+ zDZzJlb8|&Oy+8#?8@W6rtQQaSFmXPRj66Kh0yIST@tQ_0TWN$A5HqaMc_%>RzoH}gHz^>;74=1l%iJYU2&lF$Wu_`&JuRPoeucvx!RkJdh}F0!TdFu@YM z;G0FyGSH)~qR}a&@H(p_T+vW!+y?Dxd7`b+U`fr}^3sY{LJUgTtHrH#kfnQ!WPSliT)t;)unxLG{exq@Yp)9DZ-(xI2 z8d;6OEY)Q-+2^BbKBY}s8BP2abF;9+T{R!EJQgmly-kMyskg_tz}Ob`t*A!jClWj;WAfDP7v)PAU1(n4L2?dK*2O#U!pg)!Ep(h@x4;r$ChtG==%b(;Xck@1& zi4>MNWVyh_Oha34KPV?&jYk41w-)OT;qxJN2DmM0Qz@ZV=9+2eTD0#Z8*pcHvo~Z< z+3)JhqKS!mZwJ>_Q$lvVr*W|4Tvm9<}%3=OW2>?By~zR!Kw z=*J}YDSZmD=a)pniXTu-F4kS6Ckc-1Gnw{iGEiL}K73+86>rNpUOwJ7D7sTmN?M;% zHQ!{Ly}WWz2#pJW#M<7wvT2S|fhSYXA##P{ds&T*{pfi!tiNGu0!9z3_;mH;4m(pv z;6e4){7r`ICoJgk&p!*lB_i0tQ>ahNkm;%A@@MJ!Z_>BqB#qDIWtBc;dyb#z30uQu z!kV(uW$Ry{1B}Bm1zqz|qThgwv$l)mD+o}>4?8r)`a{q?n>mK}E%lTDM*yrwuS0=5 zS8~B`m#;tS92xtZPTP#&9H%bZq&V?c)0mP73wE$QRU1m= z*kk%3EbBs%%VllT;X+jQ+B+K3=42XhW^#%f@y5g<P(u_W&qQ{hQ zLUd&?|77R?amDc&r6ceL-pw#&?d{g(p7uzaXJ(-&{EcunQx!rW*K){_OTcEOnCjmJ z!$GV2x$QjyzSV&{W%k;kzrXJAl2nNkCAT#icZ$XQ8bD`Amizj3M{iIit<-w88ZBC| z4vz1RSRN`htQLJ>#Z>uYILycW#XjgR@dQLZ#hy)L1-g=1ui|e3pWOxUlDTdU*E%( zzBz%lW=qOu-bGfxe6&nuJ7nEW+>hB?af+OXNM)O0MTIYwq=HqrrCIlcPi|`5!{*&e zoR~Pb+5s<59|`#b7m&vdmT)*BHKKRI&9}VN%S>L1n2L@lD`}b4!?(;_E4|J9SMgNI z9(-^z$VTt1JKM4&l&h<|OcDfCQ&lb^SZ76ful|{2I4QJ}cZqfmUoGmX!2)&-*6LCALv*Qu5}8v$`cpQdUeIG!5Wm?JH?qvNurEcN~wL+F7yJgs1w z$6F^z)bktIXVGeC9oZl@^vx6maxQ9VSD757%(pusGjEITGS)W-ll|K2atg!GuQxbBrPi9@#-mgk&6qNfFQt#;Zl%Crj zC41Aima&<=FGm#R>1n$uoC-}N3sewn1EikUJcY4bMY+S8;9YexpCOO+b1X`3SFG2l z2K4BA)y0M(btd3GQn^lWU6C`%}f4j8_1ohB^tbY&0mKSFL5X14SxXSh6nbXi?)x2lJz*PZ$d}Cv!zfad~Km2m7 zCAEyJFr5MTRKu{|YO-DL*R}8s#5A1S!tFW1G-Qa-n6wHJ( zw@;`7R|l#WAU{QsPqZV-hroKDA*`_y-wmTfBHL36e9<=>cW45BC}}Q5 zmu-kuYJ5nCNu8sBEAjb|*!sxt5soEt2XvS%)oSu*PO7pJ8#6lyH^hcjE6J#r4CvIp za|)>=RA^8kF8Uy};E>?Pw-(>7M5~nO4`{y^TsgZ}A@8*t>=5EW3kQy@!V0419(;#~ zM=6C2I689MEl^t3>-W8 z&@U_V2l9KURx##G4R663^6aHL-o4oO2N^9`}YiTinGx4cfrdzl0=TxHD%s`%eF9f=vG{KB7uZ#&s1y+@4(siL&%k+F7LiaL~n!!@s-x*c{O! zjV1_1-EuHj0`i`(z=U5X1c<~n{V+{~n2!0UqD7;jUnujq7q?_YbXq41zTb*ttU8za zmX6s54jU?`Y}AN&se_rFNe^M~JinY3y!7w9T#bL~2{PV}=YD-ThOS1y0ce~*pfLn2 zS#roKC|e%Y8ibFI0i3e%gj0TVOVlAQPq`oYw4Mn*uScEjC)vttk4MLt6jdFQ(o(T1SC?|cxdtICB7<-B%ip&fjjCY8WZpnRId%Q$G2(s?~Fss_Sw^i&xN$dzlj~)Jnr+) zZpl>I7q6q+Hg3<_xHspOG<~RxUlQQ?_F*Mm)rx1#Bv*=@+fw?>hB_CcquGr8Bh2YJ zEIPro0*wuZv@Y+ENcACPwD;X9m`BI-N=$9l-M*q#56-b2@cFu9zV6o-}P* zeN(OFX$66xO3w?KCh>`mp~W}pb5v(#^czB#+)5#Tg8Y^4JiBllMky08Jzab zj$;fgZvbG&n5j_KTer{Vn$R83YkJ~TK9RjKeMvT3HRf^zU2j3!oQM4!=q>of1NAFe z!zVv$`$i?e4L^6-Avy{72hft_CnF`;bL>~!uI?^i4IfKMHDctndCt#5lFvKX{Blv1 z_t?=nI}_gb7!TH14P9&1grgqy)GP3wB0rv?wx^9)V1v#*+Gq^o{C88ljxp{h<3IJm2P^nWz?=ZnP6aLD%kC>TZ$ z`!q2FkP|W(gE(}2zI%D3=C_e62?eh;t)M8Zq`c=7+zc~?=hO-(r5@I3*3Xt@*22X+ z>W$nZ;jvu|_D@dx5DAp~2?nFmMASedomHVGChvR6i}#N}U1^h7 zFlRWOKlhz9Y*CW7rGSP@(@c-F0bi1m5-uQXF-LxzGvtKNMu?;6JPBsfI5gCuTR+ru&u0!mA=m%Mn|STgLg< zcIS{G;kD9UE)Dv|_9vOCiVqB1;inUZa}A7CLc<^P@ttqK)oe|u7$)9l0pVd2xz{Bk#P>3b~V(oQNAl}4i(IWvT| z5m3hRq>#F5iP^$4h{{_Kda94iE8>^{`!>b=zMA%$<%u;=AR2G)Um~yReAfCtoTc@v z>sfp40oB%Mf;^`d;Df5#QM{xGDvJ$#@kN#qW2{ z8IoC>sN7Hyc0F9qx_*X_g-|o2EpdXn=$Xqmd`inJ#W>QiVyJv33zCeqlreo)`l-}I z(1^Dy!za%Wv6qih61_)J&J@_2jznJ0b6zyADvRbhkiRa=YsO*PyXB%Qh-3)NU(&_u z`{2B_p6$Dnpnw|qs-B-qCy9oXK1J(nL}UT#ck$6E(g% zEUx0gb89xcxjlHi+l{>D6~t^};(Q;E1b!rLj@6SW67aIpn^ ztHLa(ij5Y~F7k4}(OUL+6Z&YVs4AKs_d|f$N(0s9hA1$2k=4P3@n~L&RYL}SboU`h zqPQfh8$vI<;x_L+Zi59UF&HnVv7_t`?Om?`E*BY$DjKsdJH!eSfQFgA5Kh@G6ghG& z);|qA#T1F4AVbGEGL{%YHeC?Y*9Uj#>v>2WEN$ketxeoV>Dc@<5r==y)>?3Dc1Je$ zj9!41MptPdy606yfLxZJOl30_<$!eV@v_jwL9xy= zRgo1V@bBp=C{Fm6U0rQgOa zSEwIXtYBdbk``QzWq>}MsKOO`x`Cdrb>f;U3yNQ4=uQ>M$v=SN4m-l9aqeELPDtxW zV9A={CN5>_$Q0=dIb3vCMb}0eDM4@{X&VD5SjCr)jvn~OeBAZF&X6QiPXw!r^4~NY ze7K$@OHE6w294|Kb$AZdmT0^jgMVUmrqr0*U-3P>BvooK?Izcdim&@zl1As$mSM#a z7H!_tRg%lvM&?)YcTodyb)9(%$I}atFJ~!3s!tPeS=j*bvZ^vxyFXIA79$pDD$C3; z3wc%4{#*<>R(4!7@Gfcf++C$R((^m1m^GkwwL_niF7;jQF*m*DEx)kN&p~Io1nTdJ zhNE%mH(}Wp37kCB1j(MMNW^@bK{&JwZ?zDV8b1EEzJr%74=;OQt(|>a5`r}j*4&l= z6>#DuubIwAn-dA>_DzKnN!|1fRMW_WUPR>;5lk>*Rw;<|tIz}8)DDzZ>uK~Ftm^B0 zrrY;aEY$+c9IX>sNupK3tF?P7XEza;)kMa`+g_?Nscve?Yp)rgtrxD90r+bj1NlW` zH#dBJn{e6V1%r04IY`gLj&|y99Yu>@7$c0RxL?h6A*GZUr-$aqC#pY}kPmm+eiG0< znePD7)6oGT^3w*D<6tgkNp8Y#22W5uoRh(r-l#0N@k%!(X9}lcd`8HdqrBZ@bxD@< z@VBJm+@f9fxDG;3QnoKNVKOogKZ-J2JxPe>#>XtprKq7~!*TP!_&`03l6EBE?zrs~ zB%vb)6>Q0w!cKsEb_#IaHt^Ny$I~1!e=u|)?%+AP* zSY7wzedirV0vB}X#I;k=a5zMAR(xv%xWIH3wzWZLctf__a{OLumE&dNYp^|cS_=t& z*vtKJi8aWmP`K~S#KhG1Wb4U{rngk(4NXua-!(g`Jux|%GV@be#QIy3;W%NDeD99B zewt@^t5DeN+g#k6Z0cO>7l}dY@cu8m9`1S?I^DYX0{y&y&eT))Ws16W+YmnLGq;ul zt2h1WS)F!0+qp+FZ3tuZHT;_g*&FeFzOEuL@zR6c3C98FjSt4YH@(&zXkV0z=mH&4 zN?xD(K}{UmUzZ?&Yo_JuQv(46H693kT@KB$XQQ}pn{v*E$k}wPW$)ga_F}jxD#H%- zoyqZ>(pc<&6w|k2Kyl*p)Rm%l7Fsq9jiPcOlB$VJ+VT>h9(_@nSnRiUm>c_wH?hSc z;h`09EM8Cc5onrGBk^70c0mf>IRPNlvNYYml}=gA-j+D<@w};1mr$uRy;^W!5&jqP zNxy9iivH`N&()q$b@Xv6&%5_3GBa0Anq&2R2vLI1<62Jpn^Cl5KUl=coqUT=Sy2xA zp_z2i<+I*t)guM}FfU1#(qaN@#;h|$o;l-hx;|v^CwY;!lO88LZ1Ru*?AdH7NW5#c zPd{?*&pPmDIKPOqxjAa1$)~(;y_4)KZhDA?0SqOKqcpqX2qRiMl)bVRDvGMvoZlaIrxP5H6od`7hoofCb1dz~K6@C8< zgh$&-q{sbg|Dg|9;IYg^3*`-irmKs%my!8oNT{BJTQZ1x zuG)zKX@(Zo8FQanJy(>XK1;+qJ`kdZ#L^(SaVSB}ro@BDc zkF}=<7#h5RJs;$GVUV0#j=dT#`9Z3wDQh9Ol<*HqQ*7DLZ7bY+-NP|i%&6OWd60#2 zi*6(hm*6e`re0zCama0=^va6giKE(aO9jYd5;H>Gfa{asz2hG;%suH%HOhI0+!24q zI|2jX(P$|qaxPQEauSaGycRUg4G(Ln;^Py;{2W`Bs$P1f;@q}NzB<@T@GMk|>dJy@ z-05P3EMYN}NXL?OLmvmH@3+GQn{9p%+j(5F8vEgq3r)B|WHnpqEjAx%L93GQ=0ap60&<~VGuL#(MoQ)sDzJpJRwFEw&+65a|5WF`@4G?~0lmvh zhU=)NOWASSk?BPeg34LSq;k*=ZVEmXs9jMUem?H-`LU--53+Ued){#I`MR5?KBtnm zr{QA7Rscvbhv1V4tmMA)BqI2g+P$utI_)J@r3p2K??WW4 zMLJLPSu`^Md=Igxje2g(SZOP)q{J$Cp2<6-ZmtK;_<8toCLqU7?W!d%Lx@g8>@qxS zEwsfaqb_)gvg}31*cr`ooy6ZAQSI{xPhcwZvnC--DFC|eOG8QTIujtLf<4)tv3kHA zIR7N7cXx|Bd@D3-$`Tc2ejH(5<(|o=IF7$BsWkCnpS6ZkZuth?D3;4QC#MKGy27iu z(MhgDBqW@$weY0%f@qydXvpkVQu>Hy@LH^BJlPNa^%9-=P~@{@iQR~J*Yls7w2M6b z)&AOH8Z=QEdKj_Y$<}Z2qwW6oWMLw(BL`;*b#W|SV;F!@-2n~K-dU7NgSD~I)@vI0 zFN@vuMr2C~T%Iw^>W6mCc&%SuVcEqxny6A&(0Ba}iW87iCA7EaxU5|<30GZ}`K7`< zsvNt%PHuZ!NTudw3~lS#KS&gpmrv4d?3?aA<-ou7-APeBqWNq?Yg}Cd=WEPCS}C)# z21(>6C0S@5gP$Uf-4HLTge;?q*gvYvLtSTA80X^VWGbpA)ii&_n^_BhX{kW@Y{(#Z zq*L3#nU~v4(lrS|@;1$^q%`e|T+s&GzTurNG#vE6eu%;t&Q?6AF8{)jR(M(nB{G$I zsQ=uJdp?7yVCK$ua*SJcqSmR6cuh7VVNu(3m^=95pH*Kqri@TBl!M?jeJ!YGxcG!q zNF$&&(R6VzB{uH7$6{ucQ0R(dN*5<_Z3Fpq0ihe?OTy7IhS&u7CkY0MPK(hP<2x)2^p=I1<1HXR5N=&@)>)2V>%Yw5C^= zuA#B2N2Z~p?Zuv38}L;h5|S!SH)X4%KWZz5T4(FzCmh(>%Ta{6TfTx9SDpB%Sa0{4 z;`QTws!QSTp@Ys*t~DCV#6^el_0l+Eo~f`Vu=&N2h)l(*%Nn%w_gxt0l6-n=RIIUf z^o<-;7_A1Xx=U_mOFq=%QXFgP?EG4&%x5T~BYg4IPn@BMsJY#f}%~*fL!|=o6Ie7S`alLFovkrvnG&NI`U#oNrYk9j}-}oR#+C9st&3=-4 zh&jCo=Pu&#^{x5WX-ip&RAaDrmjY_2Fz&b1Cd8Z2nBvbk?h6|yCdLN>l^PU&8o?KA znXvZ@0CzF==Rx1c&@bBTrbfF-w~eD-e=H8JL!x!g#;2mM)*N{O5i(KJbb-YaH(I$)O+{h9O zOFAuFDRLgMp`LfWj5{P>-3(kIv6wy*0RW>SGFO7v&Q1n*vypfN`=%^tv``^CSd96z z66ORCJf%##PIKkXgdt7t+3KBKm?PK~D_VU_w1Jy zMy_>^9n8xMbP23MwtOf(6H`yF#MQ%1-W+l`(t`_`TLt50{uf0U5-NpM34WYMzB&uM z_pL^|M9$7#CfQ5{H(0*#O&8kfMH7UQ#KJlnHk^E)kdQ}KuTzY4@F`tj^IG7FZrG{; z>#g;gFQ>B&SNkQ_Pinc|DKK+?yA3GY^o^55q61V6qtO0~eM?tjk*5hTz!=L|5IOZi zGnKLGao2X2TT#I@T`_p!od%#COB^e78P|$uLLEcrnS~hKIjQ~Kz$3d$Rp0o>O}eV_ zLV>Z=`+R6JVXc)zgTGGEUe`LcFv-k<1CKA^z;t(oM-1Sg-xV}Dcr`a zG5eJI#N6k`bXE}03FqT{23$Ze#x3V|rq83^tYGX(gXhaF$Y}EY5cCMvWM&BgZdXyn zd#pyH^{B!?^+V8g>Zs#+G{E(K(x-$bbt2KSAeWV$dAGz8`Y9`9<%h7>mMlOv4Yr66 zO)Bj!*X_*tzD=-q^QH&Lynin6u{y0ymI!}os?4F zblBa4rai^vx89RJ+PKDt=f|VUp1L_*rf${XlHOcCd^%=k2{EyZ%?4peMK5KcyE>Wk zF(l`px6&Yi3S1v;SI zoXjupuoL5r&t`81m>J9rvVx)cxD2x!;?6qgwSqb-S1W)ov4o~D-%UMiG)oO1pCN67 z=olG$E4{%DRvi4qhU}koa-bbUy2Sb2vVM7V_AwHdV1oc;TseZQ#wB&EKhz)EqS)WS zHcLGEZ`>Z4MR+m^n9SO61+;Pg`LJFDG741lPI9Mk!VO=j?y45#RP{N5^(@7c6{K-;;2Hv+iIxy20*{~}b@#EsOmdww` z@oIb7U#*icwaO9#;Us3&1q!KGe*ekY29212pP79d@E0WK8KF{p=7m`vx6RL2g~gcF^E?1A$41!$cC*Y3%v0M51*i?{^V)BEIs=D z*_Ui)KmICPJ@H($A4^sh(l_g9<3UGtfXVJuZHvzU`JbgN-4*g3 znYsXN3L_c>Ko``8=SJIU=Bzn{w4*8qG3GufOM~(?Nd{Hm zsx3DU*z!wQx2ZYKxqv#=QgC!JOm>X}^y<0%)|vG{hW8=ZwV+z|+Yp5Gt2NR98{LEm z%UjpDPYAC5O0l$*%v}a9M}=>Z73y>O(Z-QL%uLmv)a=hTlh~>s2_o0h)g&p`+$Bso zm^xl1+lP{IHZR-bl};qR!Q?g~xL(P~VVft-cIvaPa}je#&Ln+(xcZyp%*}S610G}r zA(hH1DIg~ij;)I0m{S~9^tGSh9-p3^p7*WZnx}B(kJ53+^n!|AAlfNGbW;=8IhiBM z3ZlB04Ep&dZEMNu zPbzv{It)Q7K^G|}588TlbZ+I3JUMq;TS|v%URGhsm5n{4nu#6;5Tn@A*t%V4e;yrg zpy`u7!TZU$kTwC?f^#mMnB5c#^W^Ha@4pbf>K(dp#k8Mx(_X|o_P7~|FY77UPVV;9 z@vAHSFz9XDT*x>eH6w}ePq)s|RDpz=&WBy-7wBe|q>Y;z{TD>$_Fv?30ke-|S9IoG z$~=UxQ7055vHs4Yw}YZ61_-HiQMA};4GUMedCkrk1cjU%tumFHz@(!TeN_YX5BGG+ zeDV71oXMrK=QtuSZW07+9A_4Iqq;AH#2oS^d)Q|XqlRDAV7z2}7h&EO7jIgJmi-^V zib{H!fDCH6i?8hbF_%HpPk1q6UW`>qGo6PFil!7aUWfkI-d#T)H@ACGCOF#Sc-r#I zFiaCT=4+e;P)}C+s95&8F;2zwPK@RSu(@Zw@z`+~`c2QCK8mDhDSh@>AVl*@*qRF;g4%TDqKe=`rIUP1i$IAh|8}|9Nvi1A!w&hi>tzYr8 zZJ}Ol8t^qQ{d*(VY&CCQ^dk}h2{O<@zj(558|Ys|ugGy?2D$gWo}%~^wblDM4h`%8 zDC=Kyc;_G7+>97qEN!ers4Y%?&fL()E4&%K;0e~6^0Ennl*h~nH0eDvv{l&=@I4WQ zchXcXj|K<*V$u;N*z$CVr6yS=67# zre%K9kyoT2JEA;%4DEfWR#jE|RGNwy_IP%QHtVm8b_ht*cUnavVQ8@1;MeK&rPZQj z7~Hp7IAf&oTp#jnvhyKaQut!<~tsxg;YiY_YlKJhy`V z^~5iS7I!3uH+LC-J)I$<9aAP9ys~$(S`F96(TzG@0DrfX8xuTDuVI&Mkyb{+eu}eBk&l@sY$Lpr$O7IVum{so=9HSE2}{t4MW38OS8LLzuod60UXM zD5j{hH(_`$r=%KZvemLx$RSb(B6@DZs$66Z!M*#l>vgX#{%E{|o_itNuNnUwGNTX8 zDx!DVE}mT4xZWN4<$N(=-Y#^tVECs~ECvkLkDJoP^pwj9EV#0aFFjg<>enM356my@ z6)BZ|%_Q?T6x)%tHxaSt)KG^DzOVIZ=(282Bq8Da8Y=p`8k zYCB4%3pc{`A2CSJMP--9R1Cvw)24o46!wZYI@^AVe*ga;iTid+Ek=dqt}|S~X5kgN z#t9z(HJg44z50pH_)JBFRnb|lZ*vp!IC>KHpHPdrD_T6uJ*!BqHJwV18fwFe#?l#J zNvSilS}ncZ)^pJGdDor3U!i53@*er<3Ax3r16MF_!jacT@7(#s@3-w{A@5FBl^5*~dOJ*(=v zKEy0xZjNT8TmV!PZ)}VIWydU&8_upd$OAN7nRyy3cOZY0k7c z=u1!s>SGCTNa`b;eSsQN6VTLV1<;nYTs>n{Ns#I=N!pCN>@EU#vJCg4dK01MGdwgN z8r;knlCk&8tcez+E``PLKzT#&lUc>xuG@6fHAfD&skrxp{+m*NZUL!KRy8Hd#LK#r z(B`lm#=!4bJINaUu5=RvyNPoz;2fy0^6W*1Do*{|5mS0C%$PqN>XnAwC)G>UoD6NO z1HH$^ro|a1v9jh0NL+n4f#_oS7gZEP)zv1W%NWI0p#+|CswNz$gQnfZsVagPpkQ%2 z=14KKdh`m?H0$=h<05?IO|8Q1;(8Tsf7DI)5hiY9uIj)(reJ;BLAeb-%jpl~@txS~ z(7?-v??;`OGg}ynf!jc+r5_YCl;nXS&B=*^hffE1`GZfR)IKdc6>B=6n0k?Q0_-0Ny{bZ9 zB7Y7{=5nAG!DsqYyy~_@@hG-eLWi6GIgnpv)67yKAbKK(ar$NJxuxB(_5NqXi9ZXL z*SDX`CariKm@?SDsIJyuVG5@kFhx77icvZ^$b8Rx_}{Jg)qh!-{3E)a|IU!Q~tM3;pW z_Iv`a#hIlBI~?^3jSaUrbhv$~!TP!T3l|5=4(tKa@A!$7?l6(Rc)a#7xq^W=^Zx;1 zK%T$J-Ae78#93I2yxN5bbnioGs7?KS3h*U#w7N`zaI&^Y5z%=C1;~mKy; zH~G>XCADxC*B~^|E*XU_Nf?V;0^f(gquYfPxCQ0!7Lt5N(zq;rhHdQIv5_Ay^)pu_ z3h&4WDl1AcG|&fsY>30VYSJ|JwK1lhdk_i+5RF9O_7uYIbm8T_0hAXHqM@e5P*c~s zMf8M%i3Be7l9a0S5()=qS+0G?EBw`ZOQwq7*>7S zYC@X9Y1v^8%@Z`3+WZxBzuCR$HcQpEKde@arE*g$OHmCQ;|kDg7te|tL7f!oiHdx; zWr4WaOHQMXI8uMk?bgWX*GmsRy-m8d)Zs2+?Tk#HoYvHY+dlP4o+r$s)D!6tmxWT( z@}wZRXf&b=$u6cHe)aY{xj8=F%&ykXt#%iRo6bWd&<}6ho9Qa9W@0fm?Oc2^GCYJ` zTi-%)Ss4#-l2hLtg=Osaiy$`Yl>*AtMPDH2rz^E^OUj2YPXH`}I+~ld9Zowxk4IYD zP+C%q3I-v);xlTKyP!YGP+DD;;E^=kzW!l6`{H`!=X-GG()sNB3i&m7>6J~`ykjry zR;!fimf)pL&sn|%1qFGiuByO_3WRQRO)lPi&YBvh%`82089w;o58*ElK4i43 zV%9E&m>vq9!CXjc=z^kN1Fu{pDf5C=njFa~iW2Ar!2s%}Or(b7t6KOq%iIqJD|SEp zI`nSNK+&F*vR8s4R=WN{2lx$t(!NXHlQySGxVI{DE5Bhx2o zp#Ro)zsoglGA$Yvgdw4V8?*u!rSp(4R!?YktFL|QP7Dr>WUb1@wf!k8*x2R3$o}Uk zgITfcsGhl9qYCGso!c3}FTd_aTXeww(uY#l#lYupU;G3{?7z_n()%S@?T&6GG2Lk4LXfY@9$xa z(lpu?CU>W-t?@ZCEk{d}5gr^TNd9ywpfeFyKwLTY3yKMk@)Vg``a~;8-n!-AaQM2u zP}KU$A*d_DDO<#Vk;>=s^oyr@oG_@5wU)ctV@`Fn3)X_(xi@|*>f%oB+aztlP(FO~ z&6quBwm4XYBN_KiOIOnShBE}g{rDHZNAuw}{obN6x4X-x!c*1=Z~JBjgyD4U+$b1M zWg^e4ov*y$GE~*n@w)ATf!#qbK+d8~(bL%3Rgv6Aw}+tizmsX(YO})SbYObZWCq|O zG`Do5LE9)$OB)S;ke%m4M>?@^-gNi_LH-@I7Wjg>P24(?NER%SBGef)UU+o_?*9G5 zxc85L$3LEY9*;e_8Y5mGFD1*Z56R*tDa(qSiUx(tgWw(>=wxJy!&yE#St3?-jgkS1 z&jinaX!1Sx{2o*L|K+F!r2c5rXV58!KG586a;6qdfFq8J&)Bdy{;bk4b1I=-OcmO zLnFr!=-#8-yRxOKsWtX=?R?IHC73aHe(pV25#64)>kKkv!*w&Hkm_A-hWAP0bgE~Oz%{`ytt$ovt~?HmB*!P*xNUV zzJVdUv0*FP+Pji7870)Ag1RDyoOEucSw;rC;4H1(mp?QU>ngGUOE$VbnLw1LnMgy@*m^XYxA|==56f>Zbh}tW~M? z>0vnW6L^(5x>wFwxe}LOnei5z&f09~ra>i~TtnyZR-~^f!Jg0-dCX-27gHuu;#NmR z_o9z~Q3G_N)V54(YUoA4kEITbsiD8?V6MnpE$H5IX1445#V>y)X=;y2gP5K+Xt&$= zTG1n3F9*M%^WTnL`|+!L9?EPtRu00Gmvi6eaLendv?q)< zJJgSo@)~&Zi}>O_ks50+&&5kq2{k$t1W+8+j01EaXj31yh*Y)6CJx91O={K6M5zy7C6yN?^PiolSt# zZh_NgfkS$9+39t*ZKc;3tgZCA02>3gjl-MWsW$!j(Sg1YS_Y%)0yC)38 z=NF=%!E=O7PQ2_jN|_t+2l(UguuqDPPt}zdr0Dic5$`Hru|{@pehrPY7O}~OlfT{W za3Qa-goB)awl5?mGf^NEt|Q`-M{~s0f+^i8C61OJ8qy}B(zW;k3T&d&;=9fr<-;TlpS~? z<0nZg|KeA^ESi*J@rS?!}t97&flT8e=uo^)vA<&Lan3-WYW$ffdK@1 z_GW~?GWR^a8>)lh3JdahP}tnLb8*hO=fT6^=y6z?hG~V{Vc`IGI|K%9i>PVl(y?>w z?G<@84s;kWJ8e3y&_?6&1X??~(Kxv}4dkI{9NoiyxY*^HHl>#5R@2`L^46LwTBJ-+`Fx7D2Put=M^UGsUgUA2slHPE!xO2e zZij<6?HYYz5ua-I`x^CKKt?u04Pd-m`w`1Ssxl0 z9N~pxO`dCC5p&wx%^x_5X0P4mvet54mJ7@OeCS#|*f zG!;q;V&>v=@!C^=z#qyT`1Fmd^an)-`fxa&gu0Q$7=WoJ{6}xS1&{snpJ;7qF?#Fy ztkDeHs~F@N(4*{9*wmJ%xMT&1OW}kTq@bO=7*gYc)Nv0vmL+XB~cYsRJMCxoj7HQ|SD>6hyPRpB z6=fx;C@o>zMO+hgI&2&)HeLyC0tT}&?4sChWg5MJXgpzHBRAI0*KXX2#q*ky+k;G- zC5@d-=l1+OOfFAf;g$gQ;_ExGW!GU9ut_t1=&?0STMvrh=Ae~VQL{)RhFG{npx5IT z1>k{&GwPFmWEIKNpK5+joG*7PYu(y+(LPHG@_CzFSDCRR$EYw4gMLrn5c&p(Iqdre z2GPs5BW$?ZeV_%yLqiCT`f+gAM$B2VQu6t;bJyRC!r~IV^7Nk>h+R1QlAG}6%a38_ z#?_dAQFzL1Nz(Tq|=srkw3x(;OUGF%9EB*az z|MUOwZ=d?K;k=l&b69&>p`}?wA9_^LHzbz`!Q3Kg;>nZ&Ic~+GFipvM2xe~jNin^9 zDwYg2Uc9jQ$P3#u%%JpETuVT;7Oo2n;7|8Q#7BJ0xKO(+fRW&#@ z0M)OO>HMA_eO2=1!XQ$8{4hV>VUIpv=CPvN7ghTQGJFrcW$(c@?gK9_%0pN800(h> zZ8`EhF0O?erK+`d^kVDo775r$7IPVmuLOIhTgX|V*% zVg__W^*onhB|YyVDjN=l?@-fk)Ru zL|F;+9af9g(DY9C2LYX2SgX!IAFr%gV{~w2c7GG85=l!Weq$T^)7SV z0(F3#v~5<9J83dBdDTtDEidgyA}$y}T(6*v(ekQ-0_>Ow4c%g1qIZ&Z{ub<`eHq_= z3xm0vY27ps@o05}P--f3NtzU2?T*yC@)-l< z%sTHUTw>0`Ndwa^qe5MoBHs0uvNlR(o6rEcT+`Of>E9`?ol`(f@sXD@ezLZ<7S~>X zeKLv{8CII2sCKIPZ8Vtu^U2lNzH6TbV8;G)M}8$-rIX?B*v1r-kbYG(MKKwr)Yn!T zb3$63OAy}PE?Smng)qjOXL@5jCNYhCa(yK?@j_>AV-Z9xaOZ(GJods{_|>0RW6Pda zu^O7(lyM3MVCT1b67cCzpTd4eNr8L(W{gDU)ypP=^VDZumN3G>QJ!y}vfx-5d>tq% zbi-9X6Be5|DWVAX&er`R)Gz%IsvBlt%i1SlcY1hf*m=t@!|tPgY}m5j@ID}@^W5{e zaelh|x2EaSarqS))7S_E1(5U6lQ54;Adl)tyT=VyWRoGD&?Vq z@LB8Joa|3SfiRwUX)B&zw+jbbd-(e3e2sK+SI8PSY3O_b6ssZFQ`$Oop}x4OF6UuD z$TZCqj#o?1{JA_fWEK>a>h|9w`?m5Nad+ixzCG&qqG9?14EA>7xrcv=x~X$9W#(cW z-o23*#G!pqbo{eh{qSonO>#OWRT`uT57oL?f?nHrS|HosXFmH`u_k~)H<7e-aga|$ z)f%~0TUTl7@+xeZv~-wS`bm(et7M9=X6ZDfuga!fH$5B7^&oyy^UzH>6}5AAqn8|c zA>${fG&bTgrafeXIr#&r3fAc8sJ>Rh1}}n{BbBB3yws~+Fegn`!-I$6ES>_ZLrh;A8SF*Vg5|sf?7FA#hr{VcU)K@- zTL*jEn6~eSyRaPh{$q=(u7Xk=O#7#d0s78N76`hp>gwxp{d?b==@1r6TDna?|6HeX zToUAZg=I`F{q2yE`g4}+fL!~i%uCmr+pSrkKCT<-v=54N__{`%BW;RWq(b@}RS*&e zR21j9R;P_jlL?#C&SQS<9!Jcc=ZxF)+zE^I)SUDvwDY{49dsTtzMXPqb<;eZyVF{EbzHK*wxW5!a9wr2^C1h$aU~RU%8#&t9e<)g;R*# zQed21H=o|=aX2w+azz%BC$hYf>W^ZyyFu}j<4n$}EH7pn_bwi>u9cFC8jP-c4nmabI(RRuL@h)d0#wxlJ3Nj zS}+tszAgKZ`N>ax3Qs)tSaKb89WDI~c7E20KJ=(!Vii+Ix+eqVB(pnTU`ML;kkG61 zZWQsJqm{|u<8uwS432jkmBvyl8%qWDXs5zOahu!0##3j^QQ%5gtX8~3Bv?FUQQYc$ z#u5u@OeCrRx45DubRLyajv1F&%{Aivvc{!_ge(tJOh7eZ{ToepPX=-}kHsT${ z|Ndyp2DOnYKoSm21r%JZ0=$<4uw%Z?;2HrmY}FSCi{8iqA>}Jw1^6O zq(U)*)uxGjKlMC91x^cGHUXh{`c=#I*B(`;KckXJ68tIb6ha=9(uaX`;Z zJ7tcCZfDecuIkLT&~TKsfNSW;Kx!6hxA>|SRrqR_O&%?sUVqZzuF%e%Bdv5JW_gbk^O^Ahk2>W_?L6>Co zwZ)>UEuLIJ1Y&Jff_cm$zE)l05&@;q@&w`3G@MlC+0f>V8Y)V1Nl_TQ-aQ;Z-=Ghp zktl4Xg=``eL&P6Uw`|K`PbeTRRbnG(Lw2pmaF3_9`D0v$dK~kss+6T$vJf`g_@cAk zt3f9o*Y24_{C#L`4WXiO6SZ`(`Ii z?Qu&gWzC}4R+`)s$_jFNaVy!Tj$?9%WKxK7ZE5?mhP_eNMqNYP3eYBk(JJ^W7gYFa z&uj>k&a7u+tNnC=j=y5wYzFlGIuMti%j>7x6x+)8DQ9B>CZNE~J1GxcZw49HKwa-| zMtOpU!;27$prG^3cGfzgu43olw9BV^YnIMpGfn%6J+yS~yy)oK%z&w^#Ko6hnv-@; zK1jb`e_7Ptz5zV_#6S4*s418WNjN9#v0GBBak)#Uz|DX@a`a6E2iqjAT(Mw_{5gw| z{Jh1Y)Y>g5E-HY-_EEkNNJ`;gf15z--9&nREAlL88_`UjbXL2Rwdzy}R1vVfM|;q` zzk|PCd)7<_q#*kDwHr^y5-DG5LiIcafh5S|5?tb99dbcRiJEuaT+yUEmVTJf@0s!> zFBvOg)PED>>GP6l-O`Ws+c%?N`GxG5B5->Ol7H(tyczz^{cxAfgp0M&{sTN1lQebe zZ)A3_uU^IL*!#P8AkbsMwE5@Yji-N$OFsNn912)58f5!)*>$yan(R`ez)?djogI61 zO*OmkF2Qrp{>$ini$z~~Tr{;4#5v3*GrQy}N#>_>_*yP*kovVOEgxV)Pzs!|KQG!|H$j0Ri7Iy4w$9 z>+8>=`@?(4B znLi>Lj^GcEZ!)}B$R$O-^h|-Ja%tgPKK8Lp=b_vk95sid+krz6~it2i-JZ}j%u_v&EAA2z1ht2NfX=?-BN0YzaKQh4o-rwcJ zYmeWJ>GPMP@6v@RFUe2q>y!aP!EOX~w~m%BPk?E`Bg#u(zT#}W@%nn*<0uNWTLR8f zDF9CLnRBgN<4@aFobp#KnC$R%4J*!rUGZE_S&J#m@5&ZKs#=^yGb0<9 z5B;5_p=-@Qu?#ay<%}|#VHO$6p{YJodg$q06?^}_S{h+b(4o@88c`Irt;_h%Yp%Nv zF1MQxFqtC4N$a2rWaK~Ble>TWV7f*kWCn6x)ojGV0gMi`WS(joRESGzW2B)A`Wn!w zDwUMJCI_r(HFJ%Yo=Bv$+P|;fhLJ#60=1%kxU6yOG*zmawi2A?J*vrpw0*{m+VLHv zkWo#?iA-OsDlbuW8(NTM*5Z{s0F%nY+Ib!K8`Jtct;7~$6M*HHeK;9|q3ml8mj{th z5IZ+Kj|ZOIsJnD(QcDj8RRGt%kH?F!^YD?6e$?s@Fu1$2C>r zG`@9}B`8~7`k2O3J@fH+tencRGM90bZx^?`yuWhC{m%-CSoD-NyXV(cBjqPoYT|m8 z;%pdO>ROt{o~_8tJ1Hnm*)S7l|TdHMU^_x&7x53}=nqal3%!lkS5=Gz~- z{kx?Mn;lfy5@ZH;K=sZ^mnB9CN*AdE+r~!(mjMB6stk1hg45Tq>TU?8*)F3cK3)6W z*~K;ZO!}NwcvX0#eor6U7GW$39UvAQkk5^ z^bx%I=G*Yw-+LM+1kG_UGsl3AnYzrEj-M;T0_Ufmej0Y}+zGdD-xgk{Vtp1?3ws=2 zy5mnLEZt-RjuNn=})#6= zY)IC+Vy!W&aGSwvKlvoLbn%m($?Xi7;|I7nb4>ZkFFpArDfLQ?i$^yC zCB@{FPB?z$*MD8QU8yn0_{yp8ykq~))_12qb`eVtRF7jPRjLl2kqDBAm9zGgXWc4W zT9epOm91@-rry0&m_2oDGXhU1H#8(*=zMXRuzKz~C%t!FU}h@-x+;*vPz=bnK;~(1 zKkEv>7p=a1jDPxPujrk|daqA7(W(-L9wxVoQlwb0ChQ#der~q{k|AC`J#!J>`{3gc z$mRC0Cm}y#8Pug4mR)K^;UTNAnMg50ryB34Nm&P<(qTxmp?rL zcjn6;h?5eoOucn_9dzAYX=OO~Z$?)4Qu#c4p!xFr!T0lt0~0;DcJh4myThn(_p{*v zk2w#IZHMi99`K_P5_`P*N<$U{Z^2V9{T7UpAZ7XSzW2d#m{}+bgG6!uJDx;{ipS8o zRMN@B_}(x5B9ZAuOUh_KwzcYXc|qU?$x)e|)^|7AQm}@iQ48(F222J-w1Mpuj^XX6 zNabYhXIo-Rd3zeR*12tc`xrg*pWd|W-pXbJA0wGBAU&Cepnp8U0C*DQ0dcwn$h(r= zw<<$7K<)Es37C2qsPi+&hTwM}xF?!xmA<)C@AeL2><1Y4JlBvs7;boE1fGBKMFQwa zr*Vl0u(83xg)n5j&j0Ms|2j6S!l`On!eTEA7lkrq0-{nX0 z?n$J>&O{F{k39QxkV^ZroN)6M9PAbZTib5t3jOfJ*MAKr_dN`moEQ9-$@W3kNrSs_ z{y6;Se-uw>X%QyusuDCSWRx)tN~M1I`b#fGWa*~ADT^-$9r+uy$lgO6nvt3i9^u|* z?5PaIn-Wqav!e~}ci-o9qqSbV^ZwhL?m@QzHwu~52195< z1LN-AGB)Imi$edfzu1noRLjex2f8Q#2K(9ZJ<0c#;K3)p4&VBn|DFIlUW&sL@XUAq z86;9^;?_BS@+?$q!V<2;e~xp~J01DtnzHm?RmkprttHUSHrGD2!_;->gXEkQP%wp! z@5I(!3Y#d3-2iz2aYJECd7D}bv7G zsO!F!09{lsS0od4AUvAAA($~n@v#TCPp!|dq-sl7dvc1F5lUBQA+t86-16tX^(|ts z5{lw035PxK#)vZc|MdU<4e_nVAm=0)F4Z>zwZ+Rlkzfb=i%v~0$UCIHD*~OU z4R!+!{F8RSBCZ7{c^}6EbdG^*yW@y< ztd?T%e&QRyX|eVJC@)M|6NC|X{ulohVeVJX9@jghto`<9utGVda8|ca!y_o6Ku$zjPFgdPhjE_Nj>x3Q;@5BHC5T?%2 zCbxU1SC~7c{Nw`{P6EyiA~RP!~01^x5jd``Z{58 z>LbGg%I`K@mSXQKp(n{XV`J@8CnR0q?)EZPNV$t`NyU!fPV(B7cWP&&-jx8LcB1KWaT}h1Sny%j2bOmQ{6EE<5 z;wlgqN$q@4oF;r|xkctj|H1=0(xegYs$9ud2qWhsGHVLis3!R7Thr@vH#R1>dxjBr zR#PqCcmU9Y8jWUbBcC1K3(b|O$iZ-7%cumn zv=IqdFu%ge2435EZFk6u|3*%2b*yfr6B?-;M~aq|tKvz87T!YE1#>RP9Dx>K>7ih1 zZF6|X5EQbXMagV**8<~)2feXz*<#V`tbS?sHuMjTyJG|)F|a2yS)ZT1I5-ZEeEItX z+=+2aBw@$F$00vB34i;#__@pHa%5tRpBLGrG3m5=`1x;tTY5hE_NrYZ%I8Dpz}=Mj z*aiM|-~-}NoRQ8Gqp&z6nX0Lh-9>g(WLJGMyv5LOY&HxslevrlxK*IezorR(YTe9^ zx3Ul2fM|YnHi$zO04D->{`Ym+z_l3q?Ow?3soJ8lO)3VquRDOARJ3`dj6u{m0>A!) zzj-ziW(O#SXE?8ZhPPkL~{osI+Aq{#^| zInc=8#*_lRE&U@H?@N+R5~4{*q!}w=8{@GI(N8t4og+`_b{(z+DgbA2<*q zyCZ?@PFKVgnh^lHD1{B75alnx&}BY!5vcRNbd|Cxvz@%nluiJ$;Y+=Umu?|?=xoU>jGaIF=%b`{BbC&p zHyxLz6a=5Qg9AnBmdNSr9RNK93RbVV>II$D z$Yfapy8=Uv5#DvJ2x)Cwq1u{czlPyJ0EvB*-M(q<)K-xI`=p@W=v-S*Gcxn4cwbv zpnBzVc5s}evzqUDRI&6zYe@jqrr)p`g`qynXs3?6*WkHhwVo;9%|9)_X2?*)zH|}blh&(A`~H7Jk-nC1m+f>^k?byGR?YLP zd!Pu8>zWve2$CojSY{_hKKHQP^=7KRRNjR6qk+6YjHZy)b?8B=nokYdVsbl#3_z9q z-r_*s0C5u+(WHovR%E4@q>(8Z(N9Grw_7`Eu0ghZQ~Bvp?i&F;nI$b!U%};GTg@7z)A_(D;=s9%*&+V)>$6o- z`#=|D4Pa2O)oM^I7Q}|uc_z0_PQt$Z`{CNvs{+~GfNZM_b=(?%_t_l#;?+fx)Gy|=lw3I1X;tleeHYs<=M(+4uav0R$=WtfRH+JqRyf^kBC z17U%1dI+dT?vcI~+oz%kGfYu~mbPGx(gLt4nUT8ezMUIRb$3Rd+@4>)sJy4xH#age zLbgezlG1=@TSgSK&zE0$6IxCrb{rF)8Q4imy|yYd;p{Vp!Yq^A5vMi;jt|8fG*q!b z0RZR?Lmeg2?q=Xbk%ToNhmm_D+U{kJ`b zcbv^|-R=ti?6Vcfcey^C0Rl;Se?Oi-L`AR_QLT`@wWBVLLR^AX7gt*N=1 z=D0L?Z>&EHyT*#Wec~c*b9W-$Cnm;8M0zTfCY9nw#&<$xbrIH<=A{1f09+%G79{eX z4c+daFgywG9KR&2yoig;;J;Nl=_$wU^85=gNVmzg*SP9$ywom`;C&@u*;F>vjqHvj zB*~0uM@7KS+e_8!$_YSYXn%3jA&*_KLyG{^aU$A77g6fkRt<_1wNjO>{ERZnKx~K1 zGJR{SxP52Wr{g@7VSxV3v(LIlBMNKeQ057TF%1Co0Lu%Skouygb7FjRWJ5APTdpT7&%wsCeR77SaYAdV)bK01UzYUH0x^M!3 zd~OmArdBj)cf^xF4C?h-UG7Iu*+SjJM~_0OB%Z8hj2a}&rUcZTdhfo!MN#g2u^Aaw z2Obs_!H&w9x(LWsKK2%b$1ere`ryIsn~$N_4FQO&WOWvMH3$!ii+(Iy49I1JF)R(k zkjyYUl0nK3)&MJK2Wuxgcpw(tLH=hey*>-c=9=`A0|Nt=aeF|TuEw$n8K7czZW{3= z=X7Zs`MI&^_TV>RKV?7TLk~FINU;@f@k+nO17^)>orz)%wdmX0>2W3;-7{kQy;-2A zvO5RD?qr3sD*U>^H0@wkma!ur`}ebR{PSr(T@Cf_;fr%`djjXyZR^V<$=-8)CD^w6 z5KQiV0ER7=j%%?O`-fp^_LlNE*jI2>xLRe|Ez=v=&a|&#rZ5a|ejpBx!_n?dMYKD~ zu1M%4UgBwI0xo3ft+Kcuy2+-m@r7mt4O_Ue;8RObBzvj~G7f8gB?ESujctd3JXza) zV+S`I_#~Q@W&~j7!5%6V2= zk=q}A{BgTFRw6-GQS^EkLw@-uZ$@I+ydlW+Z-Y*K70h-$p2-if^QB^6JSaikK?ljl zzl*irX_1+sLKYs_J_P%BjJW}A2vJt<4PE54$n;zQ$j{KZm1pQQrH^Ol!-WhS*w){J zNlLc_UF+#r;*V$3y8pg2{_@J|0<@Y9n4h{5m|!6805n8v{tJTW7=ghC^Z|JD*p!3h#x5qkAq2?)aR9Lq!H)8) z%+9)>?PU62+;o86sVNnb41zky5Ua%VLXtdG-D*7UXL) z>b&L~0ujD5a(Wut_^5pT@HSXltw4grCdtZoQcyR24BKVu?23@zr|tuDmbv5T_OTwF zPj?^Gdi*^&sy&-dxPyxgXv05o!5ADUH#)fw7N)Pe@eDz4hxcM1X7w}I!RWMu8){xD z;f3{#u$(X{GLufjdab4ebiBLA9)Ci*O}0~2fVr$voEbEINF=+5USAZ09I3jp$-v!= zU^hjisk3zGm&Q>d{qSZ3oK$_W4&sunaq`GD$t2*OmE2`NWl`^8s{!KT3TDJXN!I$% z!QbDg(af%@tFIk>s*1_@gM9o9{+)M@`N1AVFviw4soWruzFU>KXc6qH$pLq) z#bQ3}gHCZ7&G$JoL{SLrB?Qn>&xR(zvxg_4yjCUUV(Ilp9QgX=clQ_#IYXzPC%$zS z%>5DX&poiMw`YjrZrocRI?fMIr*wPIi3GG;4d0l`n9)HwigzsuUeBs(`n5cJe71|1Wuk2Ka=@<&aUlFRS9lQI{E116B95#E{@WM$-upv zZff^bl)DVvff;xp8I(~6CXx(1;Ur-C$^Y_@naurqJn5LdcL>k^AkkizezL!R0Cw!$ z>67z(BftS|T0}!scDM-1MlAaNZfBJm(P*nM7VOCYpn;iyB6`~UN|Z}kMdXv!d|_ioz7V{i@kBms82 zz{j%>Zu0<~iBLu?AUm(qoO8<9`ITpD$P@&~SwEjXI1akj3wEyF{!jnvbp;0W64C8z znQelJhAgbX~L zPLtygj^2vFO8;&G5SS8n++yuakYDe+f$qqne z@~Qvby1>~@C%4xYt6i|^yVkDoUI6qcv&|^hO$6#vnSb`NfBx@~rXSsalw&{GVSxU~ zBg8m}*f|fd!Ny)1oIigVmX}whkf8{M$c9dh&(M2qNj~Y@AZG z8r-d-4EF(jL$+JFT>rWMdwCX@dfo$sM``cW>?8%iYOwg$rG=F zV6eyMSjeT}Uwr?0*uP`k+Ajmh4q&t3Y};@?2i@DAzQzK%&yQ~XUdSZj@XjH@HP|>i zXJ2{m)MXMI5NQl-@G-=`Z4%6AG~wo@PoP#UyAwIK>?9f)kz>463|$v%u5jYS8DF}O3V7MS zQu$%>v%S6)dOA|yx@23-y9#`iJBoHYDSH#LbR-6U47NY}_`H%4l5{}bOB?N`c}vFv z1iU`DtslPp}d{ot4-@kg~*qcmT)^H+6Slb;axOXT5*w^1P6Nvxw3EV5ai_(`E*c{KB~<$yz?p{>xICCY%40k~=#SsH;z zuhMS6_$Lpw@?(E$S^cMaVX#OP`T87arrb#G*s;U)+0m3WQQkRD*%1Lce(%JIPkmo2 zN*C4y!z+~^w2W5EB1u&{g(rfNWIFrTMCZ$WaWIl9v=Rk@^o}IVT;akNHf!lhdXJKRC9%Gm= zuKyEh`d2nHup}ER)l_|{sd%W6LLPy;A)9PPK-WTmoF8PODn4wdA9{gJW>C7z?BoA( zq&D)gtKQVaaAF_&9Y-Cz7N$EJdr0j6ny z@`9<3&jP(v!a6^#3GaM--I)wo6QpzszWw48Fte}>hxhG(^?DP|H(D_3$m^nOir743 z9@wp=kV(PAdq#Svgi1dC?#WAzVi6v*&`XgQPh!J@;jkaQT3&);|0wXqWD3@MI2yg( zYC?0pOj@M+_QmZSKPO}x=T;c05@F(e{{-qM$AI21=tn@yz~c809+Ve8OJj!aGdq$r zHINjRL3&8{JuRv&RVkXH+T_6eZ3?zE1;as`Kl)GltK*OUS16JGuQB=E>_C%UxwZ)5 zsnR0AmIYUDn5}OWK-WS*UDbn@ue+-;Ku({gz^v-_3xD!(J3ss{EFk}F>m&IMTSycf z6Y1)#^3(hF+ZAP10dX`SOT^GW{`gb(`vQ$jMbEpN3#3_q-VcoxC%2c8uigE*n`#_G zpgZTh75083|nCGw|kcfor5pEnt+dMeF z+s=GoSw0SKY&R`NZ%;7O**?PLi433bhYzjE%=1qk7P9navmu?_(wLV6VSp}V=c+1l zG%}vyBFLG+_|n&CJ4X6@EQM3mMT`<51N<#Sfgwg33uIHz|C@uY{P-WBMDq8ow@P0W z(CM2$Jr}~p`Ig>MG6DqB*1gNnWiv>&Aiju=^8=BWiJ-FmncT|WpMT8A^uJ^#(%-Qj zh9h_F6dYrcT2}-5{sa3%3(DAlE`IOy>9bP6_JJ_hQ&~@CEu)<#C12U$jI>~Xb0OeM zm^__U5M!OqbV({~V8J=s6pU4%j^*@kfA2Tot+!q$KH$Z29VUj0!7p=)*7(_ZyaS_? z417+8ReK0yW0CUT$u(YxUg?tV!T)PeBY7Jof1Y|8B*PUGSCyyL}oW;67 z_~dfXU(HJG&fm`+-rhSfm+WS4aTPAym~mNRqt)(OU5RrA3`*^YEAc9NPYWHdGW)4VcuxlEJ{Gz@b~Lkm=$DRmGK1ehiPU$Ira$sU z0~)~Wbxy9u69m0kzEU4nh-Grnh?8S>$g=~`s1^M>l%;ZUK zb=IClx9eqzMlY7_Z5OKM&xv+}`u%?NY$o0P5O9or$81~YZo4DG{OQlX_;vE~tYw3@ zjo5Yy`-Dx_FYT~ru?sRB)J;0M!2`)+u}?p^9o{^Bg8(@`_0@6(h6YNoWc|c1Y#SMd zR%M+u{J_icGneJ;oSlGKYaxr}_OZJLs4hD{e!*quYV=3)41_KZ!uFAaFIA0Y=Wb^; zhY(VBuF(krH$Ht;-VvMbsS5){@oTpi#4H?7NUJ@Hi2oGpY1z#!nLbc zf}n46CHLHQN3zDxuE~IBS8+ugh`e}Y7rc4uI(fbwf!G4~vI9~Y6BK8NuPIy37a^a! z8uCz&i$yg#qKW5y76Y%l_COkd@XRnp_Vo2+`fHM2sPPI4@apKdoO!wvIAKKY-Fz2nujXU!&HM`^k#`Q)M`tn)W;H8NK_xSr(W^RC< z8zk*d#q1mdauyn^RRZW5awc%xPPIhRv!H@txMsZqiFC%9MA+E~2rE{Ze&HMzKa*Hi zZ?)Rei40bcplt#A4tejUBnEVp=K$Me*f?87j+fXOMz3iSqUS}wBT{T3t&2(e{l%TE zt=(SEmTy!A!!r!bMT{LFyx2~3SHS(-^LYcf7?F~V73HU?5eW021Aq|lFJ8Rjm(xXM zQ<0cuCQ^NNx*E?GRTbm-ymt0)(f4!}%%ugGtM7W?JaEf^8cq#&%qDT_&_Dd}Kf|jp z{~hsTl2pEnQ;e_NK2AGlnfWHRm(5l~LUnTxkw*3JG$09}%cPM=-89~Gcu+1=m%)MS)AMVVLkVxWNf=dbJD zo9cb{(lT)U)hi(H2O_IwZ$kW1;;{k#KA>+lYmc8nPfMJGgk^ zs-osP@&hyNQsv0G$xOik^k8r4@S%t7J`)m2n*PjZGd&h(SztE^uwyW%fHXII2i|=3 zABkbVG-apq=}sXT?CZq8V*`w%lkIA8&Wf*pARjCG(S7CU9}$lrW-H)24TfP#os_k;Wk~0Xz6k)9;OUS(b$&|toMEY5 z6zt{#x;1u4P##g+WDLENE4PDBc2BCjD53H#imvlAfl><#bMWTtFT+#Mei`Ogn=mn$bq&7GREhHr z-8Ph1#wU!v3+MX5og>!wRunhgy=em;Hqk}nKPFt)L_jdOkpQ!J4 z*F8YgTd?;7f9=4?Hn?qpIWFspw=E5g+mY!^FdQo)tjyhlwdGmJ^$kF}ZwQM0L%#9A z{@!lZp*TG0Be|(e-qp2k&WNMgGwBqpt*r?rBF;XX)V0a&+vN-$wSuf$6ur*+)A9Y# zIKbEVNO+C$srPoGwUw9QOMiQT8+RdqVtLxl=M5TEq6nliq?(q|s`;gMVIv5M+zw7WjY4)$rBk8f8ug0( zF%eO-cW%Sy!O!<4rt7fGetdlMA*qD8ULC$nH(71PG*ID7D(H9;~t2!?0j`$ zid^r}9fwE*mcqc09W==W!_lFUD-8O8o_E14RoVf-#w)H8hm|0Fe^?I1AcVKDeT7ao1oUzD03Pz{pP86z5 zBm`{S#0M|!c3XH}31=dR#}@{5p&dYNfpiWWu!EumEIS#{?(T$Z3om-7*&aRj7Z)Y6 zx=3C(6ztp(e4es>fEbbP_W^y=E`CRBvbCn%nx?GD0{roeUnaR@f8q4>j9*@4A8U~x z-7#LeQ!xtzy5AId^|Rx#Vvk{gGqKPV(cGbzuv_NG)j(faT_bH(F%#<$HfB1&Z90AD z^#EH`lXLmAxnpbq_Dl@=dY~h_tyWU_NS)PE8NXHr_y=53AZnwgprAT&VAD?W}b4#BL@1? z&^B0@x&)Qw8Ec(`nX9LuvNS`Y+}X(iX@KL5_BIkvKCz@u-fwrL�Z_ZcosK1{yi8 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 z%0D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 t0=O+EIt};(0%iyT0rCbAI7ezoFesj`_. + +The PMP expects model data to be `CF-compliant `_, otherwise, +to successfully use the package may require some input data conditioning. +It is also strongly suggested to work with observation datasets following the `CF-compliant `_, +such as datasets from the `obs4MIPs`_ project. + + +Getting Started +=============== +Installation requirements and instructions are available on the :ref:`install` page + +An overview of the summary statistics available via the package +are summarized with interactive Jupyter notebooks in the :ref:`metrics` page + +Some installation support for CMIP participating modeling groups is available: pcmdi-metrics@llnl.gov + + +Acknowledgement +=============== + +Huge thank you to all of the PMP `contributors`_! + +.. _contributors: https://github.com/PCMDI/pcmdi_metrics#contributors + +PMP is developed by scientists and developers from the Program for Climate Model Diagnosis and +Intercomparison (`PCMDI`_) at Lawrence Livermore National Laboratory (`LLNL`_). +This work is sponsored by the Regional and Global Model Analysis (`RGMA`_) program of +the Earth and Environmental Systems Sciences Division (`EESSD`_) in +the Office of Biological and Environmental Research (`BER`_) +within the `Department of Energy`_'s `Office of Science`_. +The work is performed under the auspices of the U.S. Department of Energy by +Lawrence Livermore National Laboratory under Contract DE-AC52-07NA27344. + +.. _LLNL: https://www.llnl.gov/ +.. _PCMDI: https://pcmdi.llnl.gov/ +.. _RGMA: https://climatemodeling.science.energy.gov/program/regional-global-model-analysis +.. _EESSD: https://science.osti.gov/ber/Research/eessd +.. _BER: https://science.osti.gov/ber +.. _Department of Energy: https://www.energy.gov/ +.. _Office of Science: https://science.osti.gov/ +.. _obs4MIPs: https://pcmdi.github.io/obs4MIPs/ + + +License +======= + +BSD 3-Clause License. See `LICENSE `_ for details + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: For users: + + overview + start + metrics + Results + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: For developers/contributors: + + resources + team + GitHub repository + +.. toctree:: + :maxdepth: 1 + :hidden: + :caption: Community + + GitHub discussions \ No newline at end of file diff --git a/docs/install.rst b/docs/install.rst new file mode 100644 index 000000000..fec2aa4cf --- /dev/null +++ b/docs/install.rst @@ -0,0 +1,61 @@ +.. _install: + +********************** +Installation +********************** + +We offer an installation for `Anaconda`_ users under linux-64 or osx-64. +Support for Windows is not available yet. + +https://anaconda.org/conda-forge/pcmdi_metrics + +All Platforms System Requirements +================================= + * Install the `Anaconda`_ package (we recommend installing this for each user) + * Alternatives include `Miniconda`_ or `Miniforge/Mambaforge`_ + * If using Anaconda or Miniconda, we recommend also installing `mamba`_ for better performance + + * Make sure anaconda is in your PATH (assuming anaconda is installed in ${HOME}/anaconda + * ``export PATH=${HOME}/anaconda/bin:${PATH}`` # for [ba]sh + * ``setenv PATH ${HOME}/anaconda/bin:${PATH}`` # for [t]csh + +Make sure you have no environment variables set from an old UV-CDAT installation in your PATH/PYTHONPATH,LD_LIBRARY_PATH etc + + +Install PMP using conda/mamba +========================================== +You can install the PCMDI Metrics package from the PCMDI conda-forge channel. +For the best performance, use `mamba`_. +For faster installation without mamba, specify versions of python and pcmdi_metrics. + +Create a new virtual environment and install PMP + * Using `mamba`_ + * ``mamba create -n [YOUR_CONDA_ENVIRONMENT] -c conda-forge pcmdi_metrics`` + + * Using `conda`_ + * ``conda create -n [YOUR_CONDA_ENVIRONMENT] -c conda-forge python=[VERSION] pcmdi_metrics=[VERSION]`` + * e.g. ``conda create -n pcmdi_metrics -c conda-forge python=3.10 pcmdi_metrics=3.0.1`` + + * Using `conda`_ (alternative) + * ``conda create -n [YOUR_CONDA_ENVIRONMENT]`` + * ``conda activate [YOUR_CONDA_ENVIRONMENT]`` + * ``conda install -c conda-forge python=[VERSION] pcmdi_metrics=[VERSION]`` + + * (Another alternative) Install PMP in the current (or existing) virtual environment + * Using `mamba`_: ``mamba install -c conda-forge pcmdi_metrics`` + * or using `conda`_: ``conda install -c conda-forge pcmdi_metrics`` + +To learn more about conda environments see: http://conda.pydata.org/docs/using/envs.html + +.. _mamba: https://mamba.readthedocs.io/en/latest/installation.html +.. _Miniforge/Mambaforge: https://github.com/conda-forge/miniforge +.. _Miniconda: https://conda.io/miniconda.html +.. _Anaconda: https://www.anaconda.com/products/individual#Downloads +.. _conda: https://docs.conda.io/en/latest/ + + +Bypassing firewalls (optional) +============================== +If your institution has tight ssl certificate/security issues try before installing PMP: + * ``conda config --set ssl_verify False`` + * ``binstar config --set ssl_verify False`` \ No newline at end of file diff --git a/docs/make.bat b/docs/make.bat new file mode 100644 index 000000000..6247f7e23 --- /dev/null +++ b/docs/make.bat @@ -0,0 +1,35 @@ +@ECHO OFF + +pushd %~dp0 + +REM Command file for Sphinx documentation + +if "%SPHINXBUILD%" == "" ( + set SPHINXBUILD=sphinx-build +) +set SOURCEDIR=source +set BUILDDIR=build + +if "%1" == "" goto help + +%SPHINXBUILD% >NUL 2>NUL +if errorlevel 9009 ( + echo. + echo.The 'sphinx-build' command was not found. Make sure you have Sphinx + echo.installed, then set the SPHINXBUILD environment variable to point + echo.to the full path of the 'sphinx-build' executable. Alternatively you + echo.may add the Sphinx directory to PATH. + echo. + echo.If you don't have Sphinx installed, grab it from + echo.http://sphinx-doc.org/ + exit /b 1 +) + +%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% +goto end + +:help +%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O% + +:end +popd diff --git a/docs/metrics.rst b/docs/metrics.rst new file mode 100644 index 000000000..a399be6f6 --- /dev/null +++ b/docs/metrics.rst @@ -0,0 +1,21 @@ +.. _metrics: + +***************** +PMP Metrics +***************** + +We provide documentation along with demos to assist users of the PMP. Most demos are simple examples on how to apply the PMP to one or several datasets. Example parameter files used for more complex appication of the PMP (e.g., applying the PMP across all CMIP models) via the sample setups used by PCMDI for semi-operational application to the CMIP database. + +A suite of demo scripts and interactive Jupyter notebooks are provided with `this documentation `_. + +.. toctree:: + :maxdepth: 1 + + metrics_mean-clim + subdaily-precipitation + metrics_mov + metrics_enso + metrics_mjo + metrics_monsoon + + diff --git a/docs/metrics_enso.rst b/docs/metrics_enso.rst new file mode 100644 index 000000000..24834d16f --- /dev/null +++ b/docs/metrics_enso.rst @@ -0,0 +1,39 @@ +.. _using-the-package: + +***************** +ENSO Metrics +***************** + +Overview +======== +The El Niño-Southern Oscillation (ENSO) is the dominant mode of +interannual variability in the tropical Pacific and has far-reaching +impacts on climate around the world. It is therefore key to ensure +the correct simulation of ENSO in state-of-the-art climate models. +A community-wide synthesis of metrics to evaluate the performance, +teleconnections and processes of ENSO in coupled GCMs have been implemented +to PMP as a result of the collaboration with the ENSO Metrics Working Group +of the `International CLIVAR Pacific Panel`_. + +Demo +==== +* `PMP demo Jupyter notebook`_ + +Results +========= +* `Interactive graphics for PMP-calculated ENSO Metrics`_ +* `Description for the results`_ + +Reference +========= +* Planton, Y., E. Guilyardi, A. T. Wittenberg, J. Lee, P. J. Gleckler, T. Bayr, S. McGregor, M. J. McPhaden, S. Power, R. Roehrig, J. Vialard, A Voldoire, 2021: Evaluating climate models with the CLIVAR 2020 ENSO metrics package, Bulletin of the American Meteorological Society, https://doi.org/10.1175/BAMS-D-19-0337.1. + +Additional Resources +==================== +* `CLIVAR ENSO Metrics GitHub repository`_ + +.. _International CLIVAR Pacific Panel: https://www.clivar.org/clivar-panels/pacific +.. _CLIVAR ENSO Metrics GitHub repository: https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/portrait_plot/enso_metric/enso_metrics_interactive_portrait_plots_v20210723.html +.. _Description for the results: https://github.com/CLIVAR-PRP/ENSO_metrics +.. _Interactive graphics for PMP-calculated ENSO Metrics: https://pcmdi.llnl.gov/metrics/enso/ +.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_6_ENSO.ipynb \ No newline at end of file diff --git a/docs/metrics_mean-clim.rst b/docs/metrics_mean-clim.rst new file mode 100644 index 000000000..1091740d2 --- /dev/null +++ b/docs/metrics_mean-clim.rst @@ -0,0 +1,78 @@ +***************** +Mean Climate +***************** + +Overview +======== + +The mean climate summary statistics are the most routine analysis available from the PMP. Because they are quasi-operationally applied to large numbers of simulations and under different conditions, the current mode of opertation is fairly general. Before it can be applied some prepration is needed including: + +* Setting-up observational climatologies + +* Construction of model climatologies + +* Construction of an input parameter file to run the desired operations + + +Each of these steps are included in the `mean climate notebook `_ along with a series of examples that demonstrate the options. These steps are also summarized below. + + +Observational climatologies +########################### + +A subset of the observational climatologies used for the PMP's mean climate metrics is available via a `jupyter notebook demo `_. Once you have run this demo or downloaded this demo data you can interactively run the mean climate and other demos. The complete database of `observational climatologies is available to users of the PMP. To obtain this, please contact the PMP user group (pcmdi-metrics@llnl.gov) and you will be promptly provided with the database. + +The PMP's mean climate summary statistics can be applied to many fields and in most cases there is more than one reference data set available. To accomodate this, the observational climatologies used by the PMP are managed via `a simple catalogue in the form of a JSON file `_. For many of the variables there are 'default' and 'alternate1' datasets and for some there is also an 'alternate2'. To simplify the use of the different options in the mean climate, the mean_climate_driver.py (see below) expects to be pointed to observational catalogue. Currently, if a user wants to add additional observational data this can be done by including it in the JSON cataloge. However, this most be done carefully to ensure the file retains JSON compliant structure. + +A recent observational climatology catalogue is included as part of the PMP as a default, so it does not need to be explicitly idenified when using the mean_climate_driver.py (unless the catalogue has been modified to include new observations). However, as described below, the user must provide the base path to the observational database. As indicated in the catalogue, the actual database does incorporate futher directory structure and defined filenames which should not be modified. If changes are made to the catalogue, this can be done with input parameter settings (below) using the "custom_observations" option. + + +Preparation of model climatologies +################################## + +Sample model climatologies are available as part of the PMP demo database noted above and are used for the mean climate notebook. However, if a user wants to create and use their own model climatologies with the PMP a simple example is provide in a stand alone `climatology notebook `_, via the `mean climate metrics notebook `_, or the `PMP github repository `_. + + +Construction of an input paramater file +####################################### + +The PMP mean climate metrics can be controlled via an input parameter file, the command line, or both. With the command line only it is executed via: :: + + + mean_climate_driver.py -p basic_param.py + +or as a combination of an input parameter file and the command line, e.g.: :: + + mean_climate_driver.py -p basic_param.py --vars rlut pr + +where the list of variables (vars) to run the analysis on includes 'rlut' (outgoing TOA longwave radiation) and 'pr' (precipitation). The following parameters are **required to be set by the user** either in a parameter file or on the command line: + +* **vars**: a python list of variables to apply the summary statistics, e.g., ['pr', 'rlut', 'tas'] +* **test_data_set**: a python list of runs or models, e.g., ['ACCESS-1-0', 'CESM1'] +* **filename_template**: template that is applicable for the runs in test_data_set, e.g., "CMIP5.historical.%(model_version).r1i1p1.mon.%(variable).198101-200512.AC.v20190225.nc" where "model_version" and "variable" will be analyzed for each of the entries in test_data_set and vars. +* **test_data_path**: the path/template where the test_data resides, e.g.: +* **reference_data_set**: a python list that specifies 'default', 'alternate1', 'alternate2' or 'all', e.g., ['default'] +* **reference_data_path**: the root path to the observational climatology database, e.g., '~/demo_data/PCMDIobs2_clims/' +* **target_grid**: '2.5x2.5' or an actual cdms2 grid object +* **regrid_tool**: options include 'esmf' and 'regrid2' +* **metric_output_path**: the full path to the metrics output in JSON files, e.g., '~/demo_data/PMP_metrics/' + +In addition to the above required input parameters, if the default cataolgue of observational climatologies is not being used its replacement needs to be specified, e.g.: :: + + custom_observations = './pcmdiobs2_clims_byVar_catalogue_v20200615.json' + + + +The output of the mean climate summary statistics are saved in a JSON file. `An example result `_ demonstrates that multiple statistics are computed for different conditions including regions and seasons. The resulting JSON files include the data, software and hardware information on how the summary statistics. + + +In addition to the minimum set of parameters noted above, the following **additional options can be controlled** for the mean climate: + +* **cmec** Flag to save summary statistics into a CMEC compliant JSON file or not. +* **region_specs** Define a different set of domains to compute the statistics (python dictionary). +* **regions** Specify which domains are applied to which variables (python dictionary). +* **sftlf_filename_template** Provided a land-sea mask to be used in defining regions. +* **generate_sftlf** Estimate a land-sea mask. +* **save_test_clims** Select to save (or not) interpolated climatologies including masking +* **case_id** Save JSON and netCDF files into a subdirectory so that results from multiple tests can be readily organized + diff --git a/docs/metrics_mjo.rst b/docs/metrics_mjo.rst new file mode 100644 index 000000000..b0fd0428b --- /dev/null +++ b/docs/metrics_mjo.rst @@ -0,0 +1,58 @@ +******************** +MJO baseline metrics +******************** + +Overview +======== +The MJO consists of large-scale regions of enhanced and suppressed convection, +and associated circulation anomalies in the tropics that propagate eastward, +mainly over the eastern hemisphere, with a time scale of ~30-60 days +(Madden and Julian `1971`_, `1972`_, `1994`_). Its large-scale nature and period are +easily seen via frequency-wavenumber decomposition of near-equatorial data +(10°S to 10°N), which partitions the raw anomalies into eastward and westward +propagating components and also as a function of frequency (cycles/day). +The frequency-wavenumber decomposition technique has been widely used to assess +if models properly represent this basic characteristic of the MJO +(e.g., `CLIVAR MJO Working Group 2009`_; `Kim et al. 2009`_; `Ahn et al. 2017`_). + +Here we apply the frequency-wavenumber decomposition method to precipitation +from observations (GPCP-based; 1997-2010) and the CMIP5 and CMIP6 Historical +simulations for 1985-2004. For disturbances with wavenumbers 1-3 and +frequencies corresponding to 30-60 days it is clear in observations that the +eastward propagating signal dominates over its westward propagating counterpart. +Thus, an important metric is the eastward/westward power ratio (EWR) for the +above-mentioned wavenumbers and frequencies, which is about 2.5 in observations. + +The EWR results are based on the work of Ahn et al. (`2017`_). +Implementation of these and other MJO analysis into the PMP is part of a +PCMDI collaboration with Prof. Daehyun Kim (University of Washington) and +the WGNE MJO Task Force. + +Demo +==== +* `PMP demo Jupyter notebook`_ + +Results +======= +* `Interactive graphics for PMP-calculated MJO Metrics`_ +* `Description for the results`_ + +References +========== +* Ahn, M.-S., D. Kim, K. R. Sperber, I.-S. Kang, E. Maloney, D. Waliser, H. Hendon, 2017: MJO simulation in CMIP5 climate models: MJO skill metrics and process-oriented diagnosis. Clim. Dynam., 49, 4023-4045. `doi: 10.1007/s00382-017-3558-4 `_. +* CLIVAR Madden-Julian Oscillation Working Group (Waliser, D., K. Sperber, H. Hendon, D. Kim, E. Maloney, M. Wheeler, K. Weickmann,, C. Zhang, L. Donner, J. Gottschalck, W. Higgins, I.-S. Kang, D. Legler, M. Moncrieff, S. Schubert, W. Stern, F. Vitart, B. Wang, W. Wang, and S. Woolnough), 2009: MJO simulation diagnostics. J. Clim., 22, 3006-3029. `doi: 10.1175/2008JCLI2731.1 `_. +* Kim, D., K. R. Sperber, W. S. Stern, D. Waliser, I.-S. Kang, E. Maloney, W. Wang, K. Weickmann, J. Benedict, M. Khairoutdinov, M.-I. Lee, R. Neale, M. Suarez, K. Thayer-Calder, and G. Zhang, 2009: Application of MJO simulation diagnostics to climate models. J. Clim., 22, 6413-6436. `doi: 10.1175/2009JCLI3063.1 `_. + +.. _Ahn et al. 2017: https://doi.org/10.1007/s00382-017-3558-4 +.. _2017: https://doi.org/10.1007/s00382-017-3558-4 + +.. _CLIVAR MJO Working Group 2009: https://doi.org/10.1175/2008JCLI2731.1 +.. _Kim et al. 2009: https://doi.org/10.1175/2009JCLI3063.1 + +.. _1971: https://doi.org/10.1175/1520-0469(1971)028%3C0702:DOADOI%3E2.0.CO;2 +.. _1972: https://doi.org/10.1175/1520-0469(1972)029%3C1109:DOGSCC%3E2.0.CO;2 +.. _1994: https://doi.org/10.1175/1520-0493(1994)122%3C0814:OOTDTO%3E2.0.CO;2 + +.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_5_mjo_metrics.ipynb +.. _Interactive graphics for PMP-calculated MJO Metrics: https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/mjo/bar_chart/mjo_ewr_cmip5and6_overlap_runs_average_v20200720.html +.. _Description for the results: https://pcmdi.llnl.gov/research/metrics/mjo/ \ No newline at end of file diff --git a/docs/metrics_monsoon.rst b/docs/metrics_monsoon.rst new file mode 100644 index 000000000..a4235c687 --- /dev/null +++ b/docs/metrics_monsoon.rst @@ -0,0 +1,19 @@ +.. _Monsoon-example: + +***************** +Monsoon +***************** + +Overview +======== + +The PMP currently can be used to produce baseline metrics on the overall evolution and pattern of regional monsoons. + +These evolution results are based on the work of Sperber and Annamalai (2014). Climatological pentads of precipitation in observations and CMIP5 for six monsoon-related domains (AIR: All-India Rainfall, AUS: Australian Monsoon, GoG: Gulf of Guinea, NAM: North American Monsoon, SAM: South American Monsoon, and Sahel). In the Northern Hemisphere the 73 climatological pentads run from January-December, while in the Southern Hemisphere the climatological pentads run from July-June. For each domain the precipitation is accumulated at each subsequent pentad and then divided by the total precipitation to give the fractional accumulation of precipitation as a function of pentad. Except for GoG, onset (decay) of monsoon occurs for a fractional accumulation of 0.2 (0.8). Between these fractional accumulations the accumulation of precipitation is nearly linear as the monsoon season progresses. + + + +References +========== + +Sperber, K.R. and Annamalai, H., 2014. The use of fractional accumulated precipitation for the evaluation of the annual cycle of monsoons. Climate Dynamics, 43, 3219-3244, doi:10.1007/s00382-014-2099-3 diff --git a/docs/metrics_mov.rst b/docs/metrics_mov.rst new file mode 100644 index 000000000..3a117d5f0 --- /dev/null +++ b/docs/metrics_mov.rst @@ -0,0 +1,42 @@ +*********************************** +Extra-tropical modes of variability +*********************************** + +Overview +======== + +PMP calculates skill metrics for extra-tropical modes of variability (EMoV), including +the Northern Annular Model (NAM), the North Atlantic Oscillation (NAO), +the Southern Annular Mode (SAM), the Pacific North American pattern (PNA), +the North Pacific Oscillation (NPO), the Pacific Decadal Oscillation (PDO), +and the North Pacific Gyre Oscillation (NPGO). + +For NAM, NAO, SAM, PNA, and NPO the results are based on sea-level pressure, +while the results for PDO and NPGO are based on sea surface temperature. +Our approach distinguishes itself from other studies that analyze modes of variability +in that we use the Common Basis Function approach (CBF), in which model anomalies +are projected onto the observed modes of variability, together with +the traditional EOF approach. + +Using the Historical simulations, the skill of the spatial patterns is given by +the Root-Mean-Squared-Error (RMSE), and the Amplitude gives the standard deviation +of the Principal Component time series. + +Demo +==== +* `PMP demo Jupyter notebook`_ + +Results +======= +* `Interactive graphics for PMP-calculated MoV Metrics`_ +* `Description for the results`_ + +References +========== +* Lee, J., K. Sperber, P. Gleckler, C. Bonfils, and K. Taylor, 2019: Quantifying the Agreement Between Observed and Simulated Extratropical Modes of Interannual Variability. Climate Dynamics, 52, 4057-4089, https://doi.org/10.1007/s00382-018-4355-4 +* Lee, J., K. Sperber, P. Gleckler, K. Taylor, and C. Bonfils, 2021: Benchmarking performance changes in the simulation of extratropical modes of variability across CMIP generations. Journal of Climate, 34, 6945–6969, https://doi.org/10.1175/JCLI-D-20-0832.1 + + +.. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_4_modes_of_variability.ipynb +.. _Interactive graphics for PMP-calculated MoV Metrics: https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/variability_modes/portrait_plot/pmp_mov_page_viewer.html +.. _Description for the results: https://pcmdi.llnl.gov/research/metrics/variability_modes/ \ No newline at end of file diff --git a/docs/overview.rst b/docs/overview.rst new file mode 100644 index 000000000..312742c56 --- /dev/null +++ b/docs/overview.rst @@ -0,0 +1,52 @@ +.. _overview: + +*********** +Overview +*********** + +The PMP provides a diverse suite of analysis utilities each of which produce summary statistics that gauge the consistency between climate model simulations and available observations. +The primary application of the PMP is to evaluate simulations from the `Coupled Model Intercomparison Project (CMIP) `_. +It can also be used to provide objective performance summaries during the model development process as well as selected research purposes. +The notes below provide a brief summary of some of the key aspects of the PMP design. + +Software framework and dependancies +----------------------------------- + +Most of the PMP is based on `Python 3 `_ and built upon the Climate Data Analysis Tools (`CDAT `_). +The key component of CDAT used by the PMP is the Community Data Management System (`CDMS `_) which provides access to a powerful collection of climate specific utilites, inclduing cdutil, genutil and cdtime. +To modernize, PMP is in transition to implement Xarray Climate Data Analysis Tools (`xCDAT`_) as its primary building block. + + +Input/Output format +------------------- + +The PMP is designed to most readily handle model output that adheres to the `Climate-Forecast (CF) data conventions `_. +More specifically, because the PMP is used to routinely analyze simulations contributed to CMIP it leverages `the data conventions developed in support of CMIP `_. +Many modeling groups have a workflow that conforms to CMIP or is very similiar to it, making it possible to adapt the PMP to assist in the model development process. + +The PMP statistics are output in `JSON format `_, and the underlying diagnostics from which they were derived are typically saved in `netCDF format `_. + + +Basic Operation +--------------- + +The summary statistics available with the PMP can be run independently or as a collective (the later to be available via the next PMP version). Here is a glimpse of how the mean climate statistics are executed from the unix command prompt: :: + + $ mean_climate_driver.py -p e3sm_parameterfile.py + +Because there are often multiple parameters to set before executing a PMP code, routine operation often involves setting these options in an "input parameter" python file such as the filename immediately following the "-p" flag above. The PMP input parameter files are similiar to a "namelist" text file used in other climate analysis packages but having the input parameters set in a python file enables us to leverage the power of python. For example, the contents of an input parameter file might look something like this: :: + + $ more input_parameters.py + $ test_data_set = ['ACCESS-1-0','CESM2'] + $ period = '1981-2005' + +which includes both a string variable (period) and a python list (test_data_set). Other python objects can be included in input parameter files, notably python dictionaries. Additional functionality is shown in another example command: :: + + $ mean_climate_driver.py -p e3sm_parameterfile.py --variable pr + +Here, the "---variable" option is used to specify "pr" (precipitation) with other options included in the file after the "-p" flag. + + +The python standard `argparse libary `_ is implicitly used in all cases, enabling the inclusion of user-friendly interface options. As in the above example, this allows users to set input parameters on the command line **or** in an input file. However, there are circumstances where users of the PMP may want to use a combination of both (an input parameter file and command line setting) for the same execution. This useful combination is possible with the standard argeparse library however with limited functionality. We make use of the Community Diagnostics Package (`CDP `_) to enable prioritization between the two input possibilities. The CDP enables us to use command line options in combination with input parameter files, with the command line inputs overrridding options set in the parameter files. This provides convenience in setting up and maintaining large jobs. Examples of the combined use of parameter files and command line inputs are included in the PMP demos. + +.. _xCDAT: https://xcdat.readthedocs.io/en/stable/ \ No newline at end of file diff --git a/docs/pmp-using-cdp-guide.rst b/docs/pmp-using-cdp-guide.rst new file mode 100644 index 000000000..ce0529d3a --- /dev/null +++ b/docs/pmp-using-cdp-guide.rst @@ -0,0 +1,39 @@ +PMP using CDP Guide +******************* + +Introduction +============ + +This guide is intended to bring developers (and maybe users) up to speed with the changes done when refactoring pmp to use cdp. If you don't know what cdp is, look `here `_. + +What changed +------------ +Vocabulary for the parameter has changed to account for the new paradigm of reference data set vs test data set, instead of just observation vs model. `See here `_ + +All other cdp related stuff is in the ``src/python/pcmdi/scripts/driver/`` folder. This include the ``pmp_parser``, which is no longer in ``src/python/pcmdi/``. + +The majority of the work was done to the ``pcmdi_metrics_driver.py``, which is now named ``pcmdi_metrics_driver_legacy.py``. The new driver is now named ``pcmdi_metrics_driver.py``. Both are executable via the command line. The next section details the changes done to the driver. + +Changes to the driver +--------------------- + +Though not a requirement of cdp, the driver is now programmed in an object-oriented fashion. There are many good reasons to this, which you can see by googling it. Below is an explanation of the classes, which are located in ``src/python/pcmdi/scripts/driver/``. + +* **PMPParameter**: Inherits from ``CDPParameter``. Contains the stuff that's usually in a Python parameter script. Eventually, we want to add error checking to the ``heck_values()`` function. + +* **PMPParser**: Inherits from ``CDPParser``, which it based on ``ArgumentParser``. You can add/remove/change the arguments in the ``load_default_args()`` function if needed. + +* **DataSet**: One of the largest forthcoming changes to pmp is that observations and models can be used interchangeably. To do so, both must be of the same class, which is ``DataSet``. ``DataSet`` is an abstract class that acts as an `interface `_, with some functionality through static methods. Each ``DataSet`` object also has an attribute of type ``pmp_io``. + +* **Model**: A concrete version of ``DataSet``. Looking at this from the legacy code, this is all of the stuff in the ``model_versions`` loop. It just does stuff related to ``_model_file``, which was called ``MODEL`` in the legacy version. + +* **Observation**: Another concrete version of ``DataSet``. Looking at this from the legacy code, this is all of the stuff in the ``refs`` loop. It just does stuff related to ``_obs_file``, which was called ``OBS`` in the legacy version. + +* **PMPDriver**: Inherits from ``CDPDriver``. Has a ``PMPParser`` to get command line arguments. Composed of three functions, ``check_parameter()``, ``run_diags()``, ``export()``. ``check_parameter()`` checks that the ``self.parameter`` has all of the stuff needed for this driver. ``run_diags()`` runs the diags. ``export()`` should export the results, but doesn't do that yet because that's already done in ``run_diags`` (but eventually will do it). + +* **RunDiags**: The actual work for ``PMPDriver.run_diags()`` is done by this class. **This is where the main functionality is**. This loops through all of the ``vars``, ``regions``, ``reference_data_set`` and ``test_data_set`` in that order. This also determines if the comparison is obs vs obs, obs vs model, or model vs model. + +* **OutputMetrics** When ``RunDiags`` gets the data from ``Model`` or ``Observation`` (via ``DataSet.get()``), these get sent to ``OutputMetrics`` which creates the ``metrics_dictionary``, computes the metrics needed, and outputs the results. Also has an ``out_file`` and ``clim_file``, which were respectively ``OUT`` and ``CLIM`` previously. + + + \ No newline at end of file diff --git a/docs/pmpparser.rst b/docs/pmpparser.rst new file mode 100644 index 000000000..6bcdf44e8 --- /dev/null +++ b/docs/pmpparser.rst @@ -0,0 +1,128 @@ +********* +PMPParser +********* + +PMPParser is basically a wrapper around ArgumentParser. It has the ability for users to use the default arguments which are listed below or define their own, which can overwrite the default arguments if needed. PMPParser also supports reading in a parameter file from the command line and then allowing for the user to modify select parameter values as needed. + +Default Arguments +^^^^^^^^^^^^^^^^^ + +============================== ===================================== +Value Argument +============================== ===================================== +parameter -p or --parameter +case_id --case_id +vars -v or --vars +regions --regions +regions_values --regions_values +reference_data_set -r or --reference_data_set +reference_data_path --reference_data_path +test_data_set -t or --test_data_set +test_data_path --test_data_path +target_grid --target_grid +regrid_tool --regrid_tool +regrid_method --regrid_method +regrid_tool_ocn -regrid_tool_ocn +regrid_method_ocn -regrid_method_ocn +period --period +realization --realization +simulation_description_mapping --simulation_description_mapping +model_tweaks --model_tweaks +ext --ext +dry_run --dry_run +filename_template --filename_template +sftlf_filename_template --sftlf_filename_template +custom_observations --custom_observations +metrics_output_path --metrics_output_path +filename_output_template --filename_output_template +save_test_clims --save_test_clims +test_clims_interpolated_output --test_clims_interpolated_output +compute_custom_metrics --compute_custom_metrics +============================== ===================================== + +Examples +^^^^^^^^ + +How to use PMPParser in your driver +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +.. code-block:: python + + #!/usr/bin/env python + from pcmdi_metrics.pcmdi.pmp_parser import * + # soon the import statement will be: + # from pcmdi_metrics.driver.pmp_parser import * + parser = PMPParser() # Includes all default options + + parser.add_argument( + '-n', '--newarg', + type=ast.literal_eval, #loading in a dictionary + dest='newarg', + help='description', + required=False) + + parameter = parser.get_parameter() + # All parameters can be referenced like so: + # parameter.vars + # parameter.regions + # ... + + +Reading in a list from the command line +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + driver -v var1 var2 var3 + +results in ``parameter.var`` being ``['var1', 'var2', 'var3']`` + +Reading in a dictionary from the command line +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ + +:: + + driver --regions '{"tas": [None, "terre", "ocean"], "tos": [None, ]}' + +results in ``parameter.regions`` being ``{'tos': [None], 'tas': [None, 'terre', 'ocean']}`` + + + +More PMPParser Info +^^^^^^^^^^^^^^^^^^^ + +This guide is intended to bring developers (and maybe users) up to speed with the changes done when refactoring pmp to use cdp. If you don't know what cdp is, look `here `_. + +What changed +------------ +Vocabulary for the parameter has changed to account for the new paradigm of reference data set vs test data set, instead of just observation vs model. `See here `_ + +All other cdp related stuff is in the ``src/python/pcmdi/scripts/driver/`` folder. This include the ``pmp_parser``, which is no longer in ``src/python/pcmdi/``. + +The majority of the work was done to the ``pcmdi_metrics_driver.py``, which is now named ``pcmdi_metrics_driver_legacy.py``. The new driver is now named ``pcmdi_metrics_driver.py``. Both are executable via the command line. The next section details the changes done to the driver. + +Changes to the driver +--------------------- + +Though not a requirement of cdp, the driver is now programmed in an object-oriented fashion. There are many good reasons to this, which you can see by googling it. Below is an explanation of the classes, which are located in ``src/python/pcmdi/scripts/driver/``. + +* **PMPParameter**: Inherits from ``CDPParameter``. Contains the stuff that's usually in a Python parameter script. Eventually, we want to add error checking to the ``heck_values()`` function. + +* **PMPParser**: Inherits from ``CDPParser``, which it based on ``ArgumentParser``. You can add/remove/change the arguments in the ``load_default_args()`` function if needed. + +* **DataSet**: One of the largest forthcoming changes to pmp is that observations and models can be used interchangeably. To do so, both must be of the same class, which is ``DataSet``. ``DataSet`` is an abstract class that acts as an `interface `_, with some functionality through static methods. Each ``DataSet`` object also has an attribute of type ``pmp_io``. + +* **Model**: A concrete version of ``DataSet``. Looking at this from the legacy code, this is all of the stuff in the ``model_versions`` loop. It just does stuff related to ``_model_file``, which was called ``MODEL`` in the legacy version. + +* **Observation**: Another concrete version of ``DataSet``. Looking at this from the legacy code, this is all of the stuff in the ``refs`` loop. It just does stuff related to ``_obs_file``, which was called ``OBS`` in the legacy version. + +* **PMPDriver**: Inherits from ``CDPDriver``. Has a ``PMPParser`` to get command line arguments. Composed of three functions, ``check_parameter()``, ``run_diags()``, ``export()``. ``check_parameter()`` checks that the ``self.parameter`` has all of the stuff needed for this driver. ``run_diags()`` runs the diags. ``export()`` should export the results, but doesn't do that yet because that's already done in ``run_diags`` (but eventually will do it). + +* **RunDiags**: The actual work for ``PMPDriver.run_diags()`` is done by this class. **This is where the main functionality is**. This loops through all of the ``vars``, ``regions``, ``reference_data_set`` and ``test_data_set`` in that order. This also determines if the comparison is obs vs obs, obs vs model, or model vs model. + +* **OutputMetrics** When ``RunDiags`` gets the data from ``Model`` or ``Observation`` (via ``DataSet.get()``), these get sent to ``OutputMetrics`` which creates the ``metrics_dictionary``, computes the metrics needed, and outputs the results. Also has an ``out_file`` and ``clim_file``, which were respectively ``OUT`` and ``CLIM`` previously. + + + + + diff --git a/docs/resources.rst b/docs/resources.rst new file mode 100644 index 000000000..e1f3ce25d --- /dev/null +++ b/docs/resources.rst @@ -0,0 +1,12 @@ +.. _metrics-overview: + +***************** +Resources +***************** + +.. toctree:: + :maxdepth: 1 + + pmpparser + + diff --git a/docs/start.rst b/docs/start.rst new file mode 100644 index 000000000..3c25824e9 --- /dev/null +++ b/docs/start.rst @@ -0,0 +1,10 @@ +***************** +Getting Started +***************** + +.. toctree:: + :maxdepth: 1 + + install + supporting-data + diff --git a/docs/subdaily-precipitation.rst b/docs/subdaily-precipitation.rst new file mode 100644 index 000000000..2a5ffc334 --- /dev/null +++ b/docs/subdaily-precipitation.rst @@ -0,0 +1,24 @@ +.. _subdaily-precipitation: + +***************** +Sub-daily precipitation +***************** + +Overview +======== + +The PMP can be used to compare observed and simulated sub-daily precipition, including forced (the diurnal and semi-diurnal cycle) and unforced variability (often referred to as "intermittency"). Well established Fourier analysis (e.g., Dai, 2006) with well-established large scale objective performance metrics (Covey et al., 2016) to estimate the phase and amplitude of the diurnal and semi-diurnal cycle of precipitation. The unforced sub-daily variability stems from methods developed by Trenberth et al. (2017) and Covey et al. (2017). Both analysis require data at a 3hr time resolution. + +Analysis of higher frequency data often includes multiple stages of processing. `The flow diagram of the PMP's sub-daily precipitation `_ shows that is the case here. Each of the steps highlighted in the flow diagram are included in `the diurnal cycle and intermittency Jupyter notebook demo `_. + + +References +========== + +Covey, C, PJ Gleckler, C Doutriaux, DN Williams, A Dai, J Fasullo, K Trenberth, and A Berg. 2016. ”Metrics for the diurnal cycle of precipitation: Toward routine benchmarks for climate models.” Journal of Climate 29(12): 4461–4471, https://doi.org/10.1175/JCLI-D-15-0664.1 + +Covey, C, C Doutriaux, PJ Gleckler, KE Taylor, KE Trenberth, and Y Zhang. 2018. “High-frequency intermittency in observed and model-simulated precipitation.” Geophysical Research Letters 45(22): 12514–12522, https://doi.org/10.1029/2018GL078926 + +Dai, A. 2006. “Precipitation characteristics coupled climate models.” Journal of Climate 19(18): 4605–4630, https://doi.org/10.1175/JCLI3884.1 + +Trenberth, KE, Y Zhang, and M Gehne. 2017. ”Intermittency in precipitation: Duration, frequency, intensity, and amounts using hourly data.” Journal of Hydrometeorology 18(5): 1393–1412, https://doi.org/10.1175/JHM-D-16-0263.1 diff --git a/docs/supporting-data.rst b/docs/supporting-data.rst new file mode 100644 index 000000000..fca3d6b5d --- /dev/null +++ b/docs/supporting-data.rst @@ -0,0 +1,25 @@ +***************** +Retrieving data for demos and use of the PMP +***************** + + +Sample model and observational data are provided via a `jupyter notebook demo `_. This is the first of multiple PMP demos. It enables a user to download all sample data before running the other demos that provide interactive examples of the different summary statistics provided by the PMP. More info is available for `preparing to run these notebooks `_. + +For users that are unfamiliar with Jupyter notebooks or just want to download the sample data without interactively running the demo, you can download the data by launching python from a PMP environment created from conda. You can then enter the following form the python command prompt :: + + import requests + r = requests.get("https://pcmdiweb.llnl.gov/pss/pmpdata/cmec_tutorial_files.txt") + with open("data_files.txt","wb") as f: + f.write(r.content) + +A location where you want to store the demo data locally can be set: :: + + demo_data_directory = 'MyDemoPath' + + +After you have set the location for the demo_output you can downloaded it by entering the following: :: + + import cdat_info + cdat_info.download_sample_data_files("data_files.txt", demo_data_directory) + +The PMP demo data is used for multiple demos. It is ~300MB. The best way to run these demos is via Jupyter notebooks. Running this initial demo for downloading sample data also on-the-fly creates demo parameter files with the user selection of the demo_data_directory. diff --git a/docs/team.rst b/docs/team.rst new file mode 100644 index 000000000..a9b2fb7f7 --- /dev/null +++ b/docs/team.rst @@ -0,0 +1,18 @@ +.. _team: + + +**** +Team +**** + +Core developers +=============== + +* Jiwoo Lee (LLNL) +* Ana Ordonez (LLNL) +* Paul Ullrich (LLNL) +* Bo Dong (LLNL) +* Peter Gleckler (LLNL) +* Min-Seop Ahn (NASA) + +pcmdi-metrics@llnl.gov \ No newline at end of file From d8719f8d42bbb39e11ce613e6ca36437851091f1 Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 20 Jun 2023 16:55:45 -0700 Subject: [PATCH 2/3] update and clean up --- docs/metrics_mean-clim.rst | 40 +++++++++++++++++++++++++++------ docs/pmp-using-cdp-guide.rst | 1 + docs/resources.rst | 5 +++-- docs/subdaily-precipitation.rst | 4 ++-- docs/supporting-data.rst | 4 ++-- 5 files changed, 41 insertions(+), 13 deletions(-) diff --git a/docs/metrics_mean-clim.rst b/docs/metrics_mean-clim.rst index 1091740d2..cae2a88f4 100644 --- a/docs/metrics_mean-clim.rst +++ b/docs/metrics_mean-clim.rst @@ -5,7 +5,10 @@ Mean Climate Overview ======== -The mean climate summary statistics are the most routine analysis available from the PMP. Because they are quasi-operationally applied to large numbers of simulations and under different conditions, the current mode of opertation is fairly general. Before it can be applied some prepration is needed including: +The mean climate summary statistics are the most routine analysis available from the PMP. +Because they are quasi-operationally applied to large numbers of simulations and under +different conditions, the current mode of opertation is fairly general. +Before it can be applied some prepration is needed including: * Setting-up observational climatologies @@ -14,15 +17,34 @@ The mean climate summary statistics are the most routine analysis available from * Construction of an input parameter file to run the desired operations -Each of these steps are included in the `mean climate notebook `_ along with a series of examples that demonstrate the options. These steps are also summarized below. +Each of these steps are included in the +`mean climate notebook `_ +along with a series of examples that demonstrate the options. +These steps are also summarized below. Observational climatologies ########################### -A subset of the observational climatologies used for the PMP's mean climate metrics is available via a `jupyter notebook demo `_. Once you have run this demo or downloaded this demo data you can interactively run the mean climate and other demos. The complete database of `observational climatologies is available to users of the PMP. To obtain this, please contact the PMP user group (pcmdi-metrics@llnl.gov) and you will be promptly provided with the database. - -The PMP's mean climate summary statistics can be applied to many fields and in most cases there is more than one reference data set available. To accomodate this, the observational climatologies used by the PMP are managed via `a simple catalogue in the form of a JSON file `_. For many of the variables there are 'default' and 'alternate1' datasets and for some there is also an 'alternate2'. To simplify the use of the different options in the mean climate, the mean_climate_driver.py (see below) expects to be pointed to observational catalogue. Currently, if a user wants to add additional observational data this can be done by including it in the JSON cataloge. However, this most be done carefully to ensure the file retains JSON compliant structure. +A subset of the observational climatologies used for the PMP's +mean climate metrics is available via a `jupyter notebook demo `_. +Once you have run this demo or downloaded this demo data you can interactively +run the mean climate and other demos. +The complete database of observational climatologies is available to users of the PMP. +To obtain this, please contact the PMP user group (pcmdi-metrics@llnl.gov) +and you will be promptly provided with the database. + +The PMP's mean climate summary statistics can be applied to many fields and +in most cases there is more than one reference data set available. +To accomodate this, the observational climatologies used by the PMP a +re managed via `a simple catalogue in the form of a JSON file `_. +For many of the variables there are 'default' and 'alternate1' +datasets and for some there is also an 'alternate2'. +To simplify the use of the different options in the mean climate, +the mean_climate_driver.py (see below) expects to be pointed to observational catalogue. +Currently, if a user wants to add additional observational data this can be done by +including it in the JSON cataloge. However, this most be done carefully to ensure +the file retains JSON compliant structure. A recent observational climatology catalogue is included as part of the PMP as a default, so it does not need to be explicitly idenified when using the mean_climate_driver.py (unless the catalogue has been modified to include new observations). However, as described below, the user must provide the base path to the observational database. As indicated in the catalogue, the actual database does incorporate futher directory structure and defined filenames which should not be modified. If changes are made to the catalogue, this can be done with input parameter settings (below) using the "custom_observations" option. @@ -30,7 +52,12 @@ A recent observational climatology catalogue is included as part of the PMP as a Preparation of model climatologies ################################## -Sample model climatologies are available as part of the PMP demo database noted above and are used for the mean climate notebook. However, if a user wants to create and use their own model climatologies with the PMP a simple example is provide in a stand alone `climatology notebook `_, via the `mean climate metrics notebook `_, or the `PMP github repository `_. +Sample model climatologies are available as part of the PMP demo database noted above +and are used for the mean climate notebook. However, if a user wants to create and use +their own model climatologies with the PMP a simple example is provide in a stand +alone `climatology notebook `_, +via the `mean climate metrics notebook `_, +or the `PMP github repository `_. Construction of an input paramater file @@ -62,7 +89,6 @@ In addition to the above required input parameters, if the default cataolgue of custom_observations = './pcmdiobs2_clims_byVar_catalogue_v20200615.json' - The output of the mean climate summary statistics are saved in a JSON file. `An example result `_ demonstrates that multiple statistics are computed for different conditions including regions and seasons. The resulting JSON files include the data, software and hardware information on how the summary statistics. diff --git a/docs/pmp-using-cdp-guide.rst b/docs/pmp-using-cdp-guide.rst index ce0529d3a..273c055fc 100644 --- a/docs/pmp-using-cdp-guide.rst +++ b/docs/pmp-using-cdp-guide.rst @@ -1,3 +1,4 @@ +******************* PMP using CDP Guide ******************* diff --git a/docs/resources.rst b/docs/resources.rst index e1f3ce25d..44b7c1f84 100644 --- a/docs/resources.rst +++ b/docs/resources.rst @@ -1,12 +1,13 @@ .. _metrics-overview: -***************** +********* Resources -***************** +********* .. toctree:: :maxdepth: 1 + pmp-using-cdp-guide pmpparser diff --git a/docs/subdaily-precipitation.rst b/docs/subdaily-precipitation.rst index 2a5ffc334..ba3eed3d4 100644 --- a/docs/subdaily-precipitation.rst +++ b/docs/subdaily-precipitation.rst @@ -1,8 +1,8 @@ .. _subdaily-precipitation: -***************** +*********************** Sub-daily precipitation -***************** +*********************** Overview ======== diff --git a/docs/supporting-data.rst b/docs/supporting-data.rst index fca3d6b5d..00379b216 100644 --- a/docs/supporting-data.rst +++ b/docs/supporting-data.rst @@ -1,6 +1,6 @@ -***************** +******************************************** Retrieving data for demos and use of the PMP -***************** +******************************************** Sample model and observational data are provided via a `jupyter notebook demo `_. This is the first of multiple PMP demos. It enables a user to download all sample data before running the other demos that provide interactive examples of the different summary statistics provided by the PMP. More info is available for `preparing to run these notebooks `_. From 742c1db08b8c116e7fd95b49ee2d201dec46c0ac Mon Sep 17 00:00:00 2001 From: Jiwoo Lee Date: Tue, 20 Jun 2023 17:01:13 -0700 Subject: [PATCH 3/3] typo fix --- docs/metrics_enso.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/metrics_enso.rst b/docs/metrics_enso.rst index 24834d16f..b69227e80 100644 --- a/docs/metrics_enso.rst +++ b/docs/metrics_enso.rst @@ -33,7 +33,7 @@ Additional Resources * `CLIVAR ENSO Metrics GitHub repository`_ .. _International CLIVAR Pacific Panel: https://www.clivar.org/clivar-panels/pacific -.. _CLIVAR ENSO Metrics GitHub repository: https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/portrait_plot/enso_metric/enso_metrics_interactive_portrait_plots_v20210723.html -.. _Description for the results: https://github.com/CLIVAR-PRP/ENSO_metrics -.. _Interactive graphics for PMP-calculated ENSO Metrics: https://pcmdi.llnl.gov/metrics/enso/ +.. _CLIVAR ENSO Metrics GitHub repository: https://github.com/CLIVAR-PRP/ENSO_metrics +.. _Description for the results: https://pcmdi.llnl.gov/metrics/enso/ +.. _Interactive graphics for PMP-calculated ENSO Metrics: https://pcmdi.llnl.gov/pmp-preliminary-results/interactive_plot/portrait_plot/enso_metric/enso_metrics_interactive_portrait_plots_v20210723.html .. _PMP demo Jupyter notebook: https://github.com/PCMDI/pcmdi_metrics/blob/main/doc/jupyter/Demo/Demo_6_ENSO.ipynb \ No newline at end of file