From d5f3cd5f213da1667eb352a22691d10ab8e5fb73 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Tue, 19 Feb 2019 10:42:21 -0500
Subject: [PATCH 01/13] sankey: grouping with animations

---
 src/snapshot/helpers.js                |   1 +
 src/traces/sankey/attributes.js        |  10 ++
 src/traces/sankey/calc.js              |  92 +++++++++++-----
 src/traces/sankey/constants.js         |   4 +-
 src/traces/sankey/defaults.js          |   1 +
 src/traces/sankey/render.js            |  75 +++++++++----
 test/image/baselines/sankey_groups.png | Bin 0 -> 45947 bytes
 test/image/mocks/sankey_groups.json    | 144 +++++++++++++++++++++++++
 test/jasmine/tests/sankey_test.js      |  39 ++++++-
 9 files changed, 318 insertions(+), 48 deletions(-)
 create mode 100644 test/image/baselines/sankey_groups.png
 create mode 100644 test/image/mocks/sankey_groups.json

diff --git a/src/snapshot/helpers.js b/src/snapshot/helpers.js
index b6f6ae21423..93af480d623 100644
--- a/src/snapshot/helpers.js
+++ b/src/snapshot/helpers.js
@@ -15,6 +15,7 @@ exports.getDelay = function(fullLayout) {
     return (
         fullLayout._has('gl3d') ||
         fullLayout._has('gl2d') ||
+        fullLayout._has('sankey') ||
         fullLayout._has('mapbox')
     ) ? 500 : 0;
 };
diff --git a/src/traces/sankey/attributes.js b/src/traces/sankey/attributes.js
index b9144ad0e4c..109934f28f0 100644
--- a/src/traces/sankey/attributes.js
+++ b/src/traces/sankey/attributes.js
@@ -89,6 +89,16 @@ var attrs = module.exports = overrideAll({
             role: 'info',
             description: 'The shown name of the node.'
         },
+        groups: {
+            valType: 'data_array',
+            dflt: [],
+            role: 'calc',
+            description: [
+                'Groups of nodes.',
+                'Each group is defined by an array with the indices of the nodes it contains.',
+                'Multiple groups can be specified.'
+            ].join(' ')
+        },
         color: {
             valType: 'color',
             role: 'style',
diff --git a/src/traces/sankey/calc.js b/src/traces/sankey/calc.js
index 861ce4f0397..485ac87de2d 100644
--- a/src/traces/sankey/calc.js
+++ b/src/traces/sankey/calc.js
@@ -17,8 +17,10 @@ var isIndex = Lib.isIndex;
 var Colorscale = require('../../components/colorscale');
 
 function convertToD3Sankey(trace) {
-    var nodeSpec = trace.node;
-    var linkSpec = trace.link;
+    // var nodeSpec = trace.node;
+    // var linkSpec = trace.link;
+    var nodeSpec = Lib.extendDeep({}, trace.node);
+    var linkSpec = Lib.extendDeep({}, trace.link);
 
     var links = [];
     var hasLinkColorArray = isArrayOrTypedArray(linkSpec.color);
@@ -34,7 +36,32 @@ function convertToD3Sankey(trace) {
         components[cscale.label] = scale;
     }
 
-    var nodeCount = nodeSpec.label.length;
+    var maxNodeId = 0;
+    for(i = 0; i < linkSpec.value.length; i++) {
+        if(linkSpec.source[i] > maxNodeId) maxNodeId = linkSpec.source[i];
+        if(linkSpec.target[i] > maxNodeId) maxNodeId = linkSpec.target[i];
+    }
+    var nodeCount = maxNodeId + 1;
+
+    // Group nodes
+    var j;
+    var groups = trace.node.groups;
+    var groupLookup = {};
+    for(i = 0; i < groups.length; i++) {
+        var group = groups[i];
+        // Build a lookup table to quickly find in which group a node is
+        if(Array.isArray(group)) {
+            for(j = 0; j < group.length; j++) {
+                var nodeIndex = group[j];
+                var groupIndex = nodeCount + i;
+                groupLookup[nodeIndex] = groupIndex;
+            }
+        } else {
+            Lib.warn('node.groups must be an array, default to empty array []');
+        }
+    }
+
+    // Process links
     for(i = 0; i < linkSpec.value.length; i++) {
         var val = linkSpec.value[i];
         // remove negative values, but keep zeros with special treatment
@@ -44,6 +71,22 @@ function convertToD3Sankey(trace) {
             continue;
         }
 
+        // Remove links that are within the same group
+        if(groupLookup.hasOwnProperty(source) && groupLookup.hasOwnProperty(target) && groupLookup[source] === groupLookup[target]) {
+            continue;
+        }
+
+        // if link targets a node in the group, relink target to that group
+        if(groupLookup.hasOwnProperty(target)) {
+            target = groupLookup[target];
+        }
+
+        // if link originates from a node in a group, relink source to that group
+        // if(group.indexOf(source) !== -1) {
+        if(groupLookup.hasOwnProperty(source)) {
+            source = groupLookup[source];
+        }
+
         source = +source;
         target = +target;
         linkedNodes[source] = linkedNodes[target] = true;
@@ -65,34 +108,29 @@ function convertToD3Sankey(trace) {
         });
     }
 
+    // Process nodes
+    var totalCount = nodeCount + groups.length;
     var hasNodeColorArray = isArrayOrTypedArray(nodeSpec.color);
     var nodes = [];
-    var removedNodes = false;
-    var nodeIndices = {};
-
-    for(i = 0; i < nodeCount; i++) {
-        if(linkedNodes[i]) {
-            var l = nodeSpec.label[i];
-            nodeIndices[i] = nodes.length;
-            nodes.push({
-                pointNumber: i,
-                label: l,
-                color: hasNodeColorArray ? nodeSpec.color[i] : nodeSpec.color
-            });
-        } else removedNodes = true;
-    }
+    for(i = 0; i < totalCount; i++) {
+        if(!linkedNodes[i]) continue;
+        var l = nodeSpec.label[i];
 
-    // need to re-index links now, since we didn't put all the nodes in
-    if(removedNodes) {
-        for(i = 0; i < links.length; i++) {
-            links[i].source = nodeIndices[links[i].source];
-            links[i].target = nodeIndices[links[i].target];
-        }
+        nodes.push({
+            group: (i > nodeCount - 1),
+            pointNumber: i,
+            label: l,
+            color: hasNodeColorArray ? nodeSpec.color[i] : nodeSpec.color
+        });
     }
 
     return {
         links: links,
-        nodes: nodes
+        nodes: nodes,
+
+        // Data structure for groups
+        groups: groups,
+        groupLookup: groupLookup
     };
 }
 
@@ -130,6 +168,10 @@ module.exports = function calc(gd, trace) {
     return wrap({
         circular: circular,
         _nodes: result.nodes,
-        _links: result.links
+        _links: result.links,
+
+        // Data structure for grouping
+        _groups: result.groups,
+        _groupLookup: result.groupLookup,
     });
 };
diff --git a/src/traces/sankey/constants.js b/src/traces/sankey/constants.js
index 2815475a341..bffd9294237 100644
--- a/src/traces/sankey/constants.js
+++ b/src/traces/sankey/constants.js
@@ -15,8 +15,8 @@ module.exports = {
     sankeyIterations: 50,
     forceIterations: 5,
     forceTicksPerFrame: 10,
-    duration: 500,
-    ease: 'cubic-in-out',
+    duration: 350,
+    ease: 'quart-in-out',
     cn: {
         sankey: 'sankey',
         sankeyLinks: 'sankey-links',
diff --git a/src/traces/sankey/defaults.js b/src/traces/sankey/defaults.js
index c5283910ade..531dfffcf50 100644
--- a/src/traces/sankey/defaults.js
+++ b/src/traces/sankey/defaults.js
@@ -32,6 +32,7 @@ module.exports = function supplyDefaults(traceIn, traceOut, defaultColor, layout
         return Lib.coerce(nodeIn, nodeOut, attributes.node, attr, dflt);
     }
     coerceNode('label');
+    coerceNode('groups');
     coerceNode('pad');
     coerceNode('thickness');
     coerceNode('line.color');
diff --git a/src/traces/sankey/render.js b/src/traces/sankey/render.js
index 88b27dbdafc..b9b41ef5be0 100644
--- a/src/traces/sankey/render.js
+++ b/src/traces/sankey/render.js
@@ -45,10 +45,7 @@ function sankeyModel(layout, d, traceIndex) {
     if(circular) {
         sankey = d3SankeyCircular
             .sankeyCircular()
-            .circularLinkGap(0)
-            .nodeId(function(d) {
-                return d.pointNumber;
-            });
+            .circularLinkGap(0);
     } else {
         sankey = d3Sankey.sankey();
     }
@@ -58,6 +55,9 @@ function sankeyModel(layout, d, traceIndex) {
       .size(horizontal ? [width, height] : [height, width])
       .nodeWidth(nodeThickness)
       .nodePadding(nodePad)
+      .nodeId(function(d) {
+          return d.pointNumber;
+      })
       .nodes(nodes)
       .links(links);
 
@@ -67,6 +67,30 @@ function sankeyModel(layout, d, traceIndex) {
         Lib.warn('node.pad was reduced to ', sankey.nodePadding(), ' to fit within the figure.');
     }
 
+    // Create transient nodes for animations
+    Object.keys(calcData._groupLookup).forEach(function(nodePointNumber) {
+        var groupIndex = parseInt(calcData._groupLookup[nodePointNumber]);
+
+        var groupingNode;
+        for(var i = 0; i < graph.nodes.length; i++) {
+            if(graph.nodes[i].pointNumber === groupIndex) {
+                groupingNode = graph.nodes[i];
+                break;
+            }
+        }
+
+        graph.nodes.push({
+            pointNumber: parseInt(nodePointNumber),
+            x0: groupingNode.x0,
+            x1: groupingNode.x1,
+            y0: groupingNode.y0,
+            y1: groupingNode.y1,
+            partOfGroup: true,
+            sourceLinks: [],
+            targetLinks: []
+        });
+    });
+
     function computeLinkConcentrations() {
         var i, j, k;
         for(i = 0; i < graph.nodes.length; i++) {
@@ -343,7 +367,7 @@ function linkPath() {
     return path;
 }
 
-function nodeModel(d, n, i) {
+function nodeModel(d, n) {
     var tc = tinycolor(n.color);
     var zoneThicknessPad = c.nodePadAcross;
     var zoneLengthPad = d.nodePad / 2;
@@ -352,8 +376,11 @@ function nodeModel(d, n, i) {
     var visibleThickness = n.dx;
     var visibleLength = Math.max(0.5, n.dy);
 
-    var basicKey = n.label;
-    var key = basicKey + '__' + i;
+    var key = 'node_' + n.pointNumber;
+    // If it's a group, it's mutable and should be unique
+    if(n.group) {
+        key = 'group_' + Math.floor(1e12 * (1 + Math.random()));
+    }
 
     // for event data
     n.trace = d.trace;
@@ -362,6 +389,8 @@ function nodeModel(d, n, i) {
     return {
         index: n.pointNumber,
         key: key,
+        partOfGroup: n.partOfGroup || false,
+        group: n.group,
         traceId: d.key,
         node: n,
         nodePad: d.nodePad,
@@ -540,7 +569,10 @@ function attachDragHandler(sankeyNode, sankeyLink, callbacks) {
 function attachForce(sankeyNode, forceKey, d) {
     // Attach force to nodes in the same column (same x coordinate)
     switchToForceFormat(d.graph.nodes);
-    var nodes = d.graph.nodes.filter(function(n) {return n.originalX === d.node.originalX;});
+    var nodes = d.graph.nodes
+        .filter(function(n) {return n.originalX === d.node.originalX;})
+        // Filter out children
+        .filter(function(n) {return !n.partOfGroup;});
     d.forceLayouts[forceKey] = d3Force.forceSimulation(nodes)
         .alphaDecay(0)
         .force('collide', d3Force.forceCollide()
@@ -683,7 +715,6 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
     sankeyLink
           .enter().append('path')
           .classed(c.cn.sankeyLink, true)
-          .attr('d', linkPath())
           .call(attachPointerEvents, sankey, callbacks.linkEvents);
 
     sankeyLink
@@ -701,13 +732,17 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
         })
         .style('stroke-width', function(d) {
             return salientEnough(d) ? d.linkLineWidth : 1;
-        });
+        })
+        .attr('d', linkPath());
 
-    sankeyLink.transition()
-       .ease(c.ease).duration(c.duration)
-       .attr('d', linkPath());
+    sankeyLink
+        .style('opacity', 0)
+        .transition()
+        .ease(c.ease).duration(c.duration)
+        .style('opacity', 1);
 
-    sankeyLink.exit().transition()
+    sankeyLink.exit()
+        .transition()
         .ease(c.ease).duration(c.duration)
         .style('opacity', 0)
         .remove();
@@ -733,24 +768,26 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
             var nodes = d.graph.nodes;
             persistOriginalPlace(nodes);
             return nodes
-                .filter(function(n) {return n.value;})
-                .map(nodeModel.bind(null, d));
+              .map(nodeModel.bind(null, d));
         }, keyFun);
 
     sankeyNode.enter()
         .append('g')
         .classed(c.cn.sankeyNode, true)
         .call(updateNodePositions)
-        .call(attachPointerEvents, sankey, callbacks.nodeEvents);
+        .style('opacity', 0);
 
     sankeyNode
+        .call(attachPointerEvents, sankey, callbacks.nodeEvents)
         .call(attachDragHandler, sankeyLink, callbacks); // has to be here as it binds sankeyLink
 
     sankeyNode.transition()
         .ease(c.ease).duration(c.duration)
-        .call(updateNodePositions);
+        .call(updateNodePositions)
+        .style('opacity', function(n) { return n.partOfGroup ? 0 : 1;});
 
-    sankeyNode.exit().transition()
+    sankeyNode.exit()
+        .transition()
         .ease(c.ease).duration(c.duration)
         .style('opacity', 0)
         .remove();
diff --git a/test/image/baselines/sankey_groups.png b/test/image/baselines/sankey_groups.png
new file mode 100644
index 0000000000000000000000000000000000000000..ee05b7d512e70d47d72de1b6f2dd83ee4e1556e8
GIT binary patch
literal 45947
zcmeFZ2T)X5*EUMGjWi%RNwmol1W|Hqa*~XKL<I$jN|G!&OHN7-4K!IYf`DW}iGpMi
z5Xq?I%-ucC%sal{_f_4xxBmKX-T$>pXX^Am`|Q2;3eQ^4Iwwq1U6BBf1`i7hi$GaP
zP8$pB0s`|Fei2-mdUEj*78U|aSx#El&15|tCyoC0M96HlU5`B;OK>0)@c~Sln3!W&
zo`f7<n>#kgc?GTwlOl#U1u+x`f0p|}#-Sp&<&79l-62H;?wAN3pPo61r1s2s?kA<c
z6tmpC*|PpvsPU#{zxa1g%l?~7X)jIa!JjTD1dhal68mDo5Ln=U5fEq-aSZHg75?v+
z5x%}L@V`f4Za|vBh+{f5tC)Wqhy`K9`D3EL=Je};BM@QP7K*>!j0Ke;{O4n_pkX9P
zB&lp))NeOKV1aaht?bu?q|Cm)EWs)C(tpkW$MWHD5zONMb&W*<3!;2UK+ONoZT<R%
znAq`OLolP2o?}7dE?Yl^{dO|~@%6Xc5HXh_Fc!X%b@;#J1a3wm-~DzQ62S+BE197u
zNPda(&qo2lUHEP9{}J5(9>K-=)4jN988!2C%5E>(=cGOV)=RU#zP{RF6|RX-hL7zU
zzc+hw3(yJKr=8B8pJp06^$AoYnA&AGZq%l3)Qp*=cY6;jvriNims#U5xZSIfw|Lg*
zNX_w0L;Po;vFAn&#m%1Cy&x)+SF@*^u7Xe3^=U<&AIUG~3G7cx(>)!(FK9h-Rct<#
znNze(SWj}J`lIbojyz=BOqFKMxTNg+o9(ELmh-cx6AzOoCT+^;*&B*_pRE=atap%U
zT<U)>8+@s-==l$Y&6BbLd{t5S0eL)n;OF+zKwakf$<ov1?2ySML;Jf`zTCzQBW2A;
z*2l-Q=k`?=eU-f4E2{Z|$b`(M6nZ)_9%U>DN7&WR6r!S{>p$9w>NF$|JDweV%$&3?
zF14t#9H<4;Nqs8T<DIh1^foI*8qoS3LLFyZ#wLEuwQm^C9^K)ltJHiX$!u(tAk^?S
zIQc5}*VFyky4mxy{io{{-IKnM3!H5)K26IaIq}S+@2JQ7(z$<)Wpg(K0u_tqu!aov
z<$<XM$B9($Lq($r=!6HK{Rp@s7mgl394vSt=N)BQ`5-La<<s5P$Yx%zIsDkIGSn*|
zazs6@LoY|ccrRDEZBep)8xtZ?bH~*fhU%*D+@EpXplUe?O8468sqGV-V!4xAEePGl
zX5m9nPYy9hi<>2zcofcfes8M4Rnm9@4y6)-uqmy%^F)?;L)8E#7nz=U@|FE*Cxu=I
zC&DUPv2?8<xWMDJD>#mK*r@TtSD(74<4?OCqP{D87tQSDMDSGB%|4srX+D@A|JpLy
zP+@!m{NVw$Yhy^X<k7oldsUg(T`fS_D2!cO{jr}OZ`4gmogZp^6g)lJt#TPN9wU@I
zxJS!pCif~m_|Y=#+2-q|$=qm3noD&<PaCSTBG&I1+Kt|Q_KaCmf^R9)r}-3|XDvSO
zn?cF_*8|vVMeGV|%_m#$KNV<PIqubKCS7+5qPTP2HCdDDF~MD2UMiy}epWA{HmAuA
zzV)SA>KVJ-ej;8}w~B7$Ta6l}zb>>>GWaU4<z$g}Z>;5P^fQpmJ;Pm^4PXVeLkhGm
zo2#RGrUaXVEkC<x^BL{u<YjG|Pd6UpbnmVdWKJ#*<*KpE&@Tuz|BSr1tS0it<;1+}
zIqoKlvHM~oq`2ApcruvQ{t;$+HL9@l!_0GBkGc-kilHBsG7;)+ICM{Z)4lg5-qVL{
z_BZcM+B_XIcD<{rs`{#Mb?@}MkJPf{m_s17RcN>O{)}aKf#Fl2fA{FAoQ#*tTh5NY
zbj(gp(sbyy-=CbE4F6{O?7Q+A{XE)9!>sIpgRLQ;@cwnvv#sQSuA0kK1|y-b55J{e
z*fcB4c**<hXT;vr?3tjxu}{nHC&P{G5C*)nGV@ul?LNDf(>?snHw}53{Y_^_Ymh1`
zQ!l=&OWT>}Z%&sLr7Fw4H*DS;3-3;7HSxBbIHq2|?_XL!AKrRib1PM_^ybCz><7{n
z`j+V~qVF}QcSL|G9|!F2icAA{qeigj7;;a5pMU)P?ECpeSJDsyT1u~sgbVf@>~*)J
z#Ww5PckYsLB^D06jB@{|CbYq=x<tKOU8s0V+;!TaJ8S<M9rLMLW;9TP&os2O0ZyGl
zEr)7i+aGSK61H+CH%f*qr8%j;J<3Zqsr=mJi6h(C;TkFM>FNvKUb0S`xwfEmA3Y-h
z?$O0M8il%P#|Vl2X{T1c*EjS`y?6WV5{MSMqlvbxS4Rq4f86!%cj0kRJzMJbHnFdt
zyXblHvpZm5fBLmkz)_>q<7av2dvz_?d_$J9OFrp0H6(UN`Wa(rx^kw6W^a!HiSk~y
zAd`GHy3kG}b;(gB6T7r{pocBhmNd<$Ei*tnlYO*Y_hd$-vT+<u*iG+h6!U#<v0v=_
zrC{c@H+P@MJFadvekbg20x;#0zSn-^EJ1&?fl4~jb_hy6Q&Qq`&e7L+jf=AWJBM0j
zoEg0w*Amm#+PdTOo!*EAKWUU*YTBrqm3${_Z0ce+a;WNFvKOH6fZR}}lhH>kooqyX
z$VJqvv|%a3b3IYdWM%k*_Ud%$jS&mYGW4}Cl%3j{rpCF63-&_-CKaQDf=QDAkyv+2
zj#o(vTbC5YmJrES{2bia*m&ASZ3!b_Fn;Tjqs#2`<4ddbf{2%yuIz0p2IB|L*~95i
z1Tt9gHq8=v5l5+wi1Nx_PHFeYO}lpnzvwWlNsvWQ@e;zM*?9%7Rx4$UAaIGU4bJY5
zn@4{^8JDz{GF&m{9|^tFu5he9(crr#GoJ2?_RG3>dbC!4MJbkN()#je=Z|XA%m!39
z=v#vAtn^dWO{|H})=bYURe4^s)W5Y6;~RVhCvcy-A42cH)u9s^<LK6?5dJCo>eZ*B
zgy|zSO~KB~`!q87_>(^8`#w{TpKYfu%3V);RyLG#v4XPV;AgZC9sha)b9ez|VxG}q
z`;{|dI@S8tlCFgL()hCG>Z>>-h@qcnhXX!@QCg95eWhCFa*^BucgW+-R9{0$<u_Mu
zW-olc7eL_uMrUC^fJhSFyf^JMkmDkLy7MvM^7p3w&wHllyQb0sa+zFX#3LtRmKpAB
z%MQ9FY#JGK@X9X6;_RHRs3b3l7PG#?v~5+NfAAZcA?tedT<L7%oL?`F0Gw4N{3Xw~
zdB$4n9o1<U?y_ulE!_+1RLaJeYS4a#=W9%ye7ZcdZVQoqq29a2rq@Jp<fxoSbuzCA
za3^wEzgh8b{HQL5eSDR@PJmyAPwHqnS1r=cTftdYI_|r@pi-I3X6)O?6`hoVR>P>Q
zB{d<@>BF}KK0`lOZgTL1$F8Ebm0g{XoO5LZY4#n<UO5h5C(E}C9)=c}CABQS$#RMr
ze`HKwK=aaI%)9n>K225Gt#r?k>pCyP^C)|wg|9fiV}#JsXO0)Dr*s$Oz3_c>(j>VQ
zp6n>^Wh^UXWV#scsOvIxs4r4%{?YvoLA%uHiUvd#H)p<l;e6rB`M7((Qya=-`6SDO
zQ$cip)hW*@zKlRr>UG}8QeoObhzMmwWWR>!<HF4&$I6m{T$`&@3oI+~X<X;dn`7rL
zpLK2tes){Pn%?XWxepmq<MUQXO-b<|$b6t6<U{VnCvkSLz}4LUZOO=>|7RymE)KPw
zRF>MXl1m%c;O8_bjdRVFjQPACV^rRY<z~49>HX~u)Y<ZUy!<B>X-;*$gMFl94BGAu
zNvkwjCk{?W<d!oDL$9xS#b+%C1xa-PWFAIfcZj_PMTyN?)2&36(%^~W*5eyh#EmFv
z1{lnazIA4&5XkpAT{Gpad&#3Kbuvd3fS=TeXi#3Zu3saZc3(=bGtvmA(P<D~fvxj|
zi{3@II<(=k!z2V7BJzV@G#h!lu&cY$IWu16_tRl_5kR~6eGHqqCi-j!mx~o~D6Xq$
zeBD`5zKKYbTBYBa>TXW<;zG0(;cDr{INI%^h>BJ34}9Iug8dB<29l3mb4G$zfO&Z=
z<%fsSz^os<{>*Wz#f~)o8lh%?=hVegY05?`SN3=$-Ldly0nIg1ftk6d@jctL9~zj^
z3O3n{`l2R1FM6FL%*q?AeL9mIv01{W<Aty43H&sOEOn%0ud+tIRxouFOLnq;R9G=j
zDexnas`tu<j;f?aPsXQsR0x$rLiO6sEQN&kIE(%^CH1=$WZqHE%x`Drk{&6;MwfNf
z(b7Dv!}Mc6WT~7LwF#(j?-nXAizY8`uWy+g>-B4-3G*$}bM71E*g3OnM^4JPN{+he
zr8~>Yk$$7}-W!Q85=BD_#I|~`ZHRff8q<x~45s_)_8Jp}|1jd)jZyI!d6FDMY48~Y
z$t;IFTF#(vzE=r(c&nQ{bVrq3cAriy?cZB7;<R$k95RF6aQylX!J8n}Nm=p9-Ee72
z#z`qb=%|rKrzq7h!StwQKFg_;(zTz=XJhJ`sOid^obLuI-Wk1-EyuSK$Wp(1fA?%9
zDE&c4?5f5U62H1(Z?a5NL`!1OAa*4fTkdtyc7Ai)*tOl^Vv^1N)I=l8ZS#~QCoew8
zP^6l-N&6B}x)V!v1H@oc`zm2jEd`Nrs!RV9)n?xW&&@mKkskaMkHemK=-T0W2fLUn
zZjhwEAK4u0t3@+h*Ww}jw59@*My)%`n|VA~(Gq+5PYN_6y=L6GYB7$>?-9D#fXdZX
zdnlbP{X=_%WMIS1;)v2l;+251P3v@hR%Be}kDQhj`vji(IeFJYXTFgT&#vdxt;WTs
zr>lB?{8n1+(pPrOB3T8TM_+uLIe4<5;A$}%RCMYxb|G#+mP%GY+-N~(u`!~M%d}m~
zS<l$jh~K%7Pm|gBL*tss)8qF`8|n!S=r#2mLuZIiu8Aw6Jt9#3*g@8RD_T~Tn;geQ
zb`8dvPl`QLI%Z7Yc{is}A;`nVx%;*%E0l@jJr$X&-{|+_{qLsNXL>1O(2g1eY(MWT
zXb@~^YfKJfD@fe$EtGMMajDRH9I`q2t=ph73%{%pKY2i>eR^d4lX2^hoNP&JFR?<G
zLxkTYqT*q}UbV2qcvZcq%@GyR(JYtkR+fSA$8NDKT<j{ip<mfr*i|FB7c(vs(D0-0
zd2KrxE-@`;M#=IG{s_9RH{-2$wn${B8J$A&tf;`lmRynGp_VN3n@39V4EKI%U*_SD
z!K*Wey3x|EOol4Rt<H|b6}dZ^%D933B6B8`i!bNVvt0JTK`k|yHFZQK$3p~$@r;Sc
zxfX4+-^3oQyiZ>+;ziR~&2^?<aPHUExK%iy^ZKW2W|*Vd$8_I>_8$7^2cLI;EW0k^
zg_apM1b<s9qWLKH{f*O;Dx?sc^L2mzE}iKuB>z{HrSKm)dww2L+mGLpi^m2&dwC^9
zW-XZ+v6#{560h`g$la)^n}#uqmRA&K<z~K9xxM7-&C=9#8fd?^A*cx09a2p<Zptjn
zqBb?XLq}LkE>>?2J}SxEbS&b_5;JW;e8X4DK4c*!o{@Hmyki{d+>M;cqG8AhF83gs
z&Z%@6z8xUs^P#DB=n2AA(Zp4Og-P_~a--zBH7uyRJA_Erb=KLh-$y0>lU9Iqj^-_-
z^SthYi3C=I6O$DQKA#gbXSR6lHaqjE{Ms@qHy+IsxM`nzdAZH-QHF}hn+ORGMQF}~
zlWf*>MI%`w4Q~*ofTqhd2$6DynWJdUTou_^XQt6~qtg<XY5fxw7;5lmLsv*g!8lnd
zP@}7k8n(_u$uWg<sNm+*f}A<~Aj+PQt=F3BR;Qb13`tm}wBJ@FaqK^9y3HO&Zfs_x
zp|YPh#3#=dbGUyRBpIFB#p1jo&@A;v$)Lub1ENJVrKLz;GhM5m;M_Vo`@YAHBI~od
z_a}yD2XkL;=Dvx4zPz1(U!g%dN5QpuaK(#>?_(cqRDNr@pQ6l+rU>n%%?AndZ;Z#T
z;MzkEX+z_DlKES1Ehc)rb&ewBr7_EKN{o2O2jLLd*LW!UX;sak-MsyHb@RJ=;Esqk
zeS`!q?>U|3>b9=^NrX2WUT3}-griGY_Hz3+Br%nS2W^wQc8yaHxkEkrWa7k#V(o`o
zolK-FRrJZ4?b&P2YfA@aQ0?WP3*aQLFPF8NsM8fu#HjSoG;pkzQG^Fga)hTlN^j7H
zl{_nV;U`bds|5+;<Q8v(tE-->tKR6N!5Jz66&7Ne#&WXK#;UuezK`6ZH;W2mv-v(W
zv}cPU?1$);jLDsE4469WX*l6lFMmZf=EboZzvHi#p;|PH4{}LXlhH)u$Q=)dWxw!6
zlaysM(iG(}&<Z@~my_SUMAR~rP9$*PA~X=$KGwr7-dZ)@sn5RT=%#oLVYbqxT&yUc
z^Q|G$MQfx}t4Y6Mjr;BsS0gTx7@6;o!XV#--liwbg<Qr|Qk}*GqRFmvE(womL}M~_
z?CBTlH+8928MTN)B{k+#0PJn?fF?$FdLWIW6<wh@2OQ=6<g7kg-y^n$C8$-Jj1QY)
zC)M4JRFM2*OyW_d$BsWojqMV()a^so&>qFH?CyHeXvxgY6I7RX{aCAAK?dc9Y7-HS
z)3qLa-W1O~Ck0mtgv4S-ps$i9|MacHyJ)K0Kc8%uw`DeM(o`HCX1~!}&~I1e&%Em6
z(B2ll>$~h#lA$qLZUo`jb>|d1bHEE-Qy%Ms%&a>KX^gxtAJE8y<|wvWqqQm+h<Ddl
zg70X+Sioss#YRmF>vACy(;8i(hF{AsAqke8hRX&D`|lq;Up6WWVG4X)pI=S=;?SBA
z!9h@wk(Jw3D~W8Ny=vo1wq}$#`b9gp#Q@^qgdEAu#!o}Zm?x(Tqg4&qA1JF7GODaP
z3~EvvKM=5OC)ni-9Gi(9RYnq6*P%mX2ue4<`JzL<ip?IX54O)yj=jLe4_z$_)^c?f
z2{(Q|Gc%$6W`UTv)3E*i$de&C&%Q(e-5Z0oAN4<HI}WCGK7{6U1#cQyr9PSNweunm
zzdIs<$aCavAuQv2d4;Sl<9*?Y2*c)gdpDi4nJ2qxR)nF=)3AN7j3c`6*D#3>I+5xU
ztSS=mb0UbKE=n8v9u(?^I2Dsu+7X>KcZ;L=$=MZwFT3P40!6^ldk8tJ!{4{?G^E@r
znoUlf3UWk><eAVBm^*J1vf$1%6)TApca=1Uc#i2(rMEPY#bh}0DkAw$)RyABR=Dcs
z*1HOpGT(0<?xJuy7K6SC1TMMNd!y^*UEOytyN<PQoaLXZj?WyNIu1bcBsCVhT8yHK
z$|ZdoVo~M}s;-gV-buTM1X69cGbs{t53j2udnK+EF_sQg2i_3Jk!#v$sIAXVlAws;
zPg}?(k8xbkEcMlO-27CdBT*&FUWhZ(^k|}w?6xOziDBj~*V6$0Jhir4ckm&F4*D*R
zACtSh8b9MimXFFC5)cZYowY~Psa$AR1M={r)YnDtug1QSpde-(d_rnmvU6E&CTJ{Y
z4!5BZrChm6Fcfra;q`4PfxvcfMt!9h%XyX?@U?8w&)Z8GE(xqw^X@J$v*ap-(`Yux
zYL(!~na_<zmi}CzX~_9GWIb(FpQ0{q53QuJZQ#m(&Dqdcn$6qrem%n(<w4$fIr+U9
zAtW|1EONDwfsP>cV-9{PPf5dd>&v&?%xs?pOw6Q@^n8+-yep$)zrd^v;Yjeb7G5nY
z{YH!)QzW>)YlN;SSFovYzZ9pgc5+)I`CC7lZZXI_Pa&Vdo%7`wv5*9x{LJyHbi7f0
zH{H_qNT;fM(UB4%e}a5YDgH~zo1|vfW_EqA7O((#Hb^YHYoW3!pk=`4Lbl*CeMG0!
zw)^^HjKZn9%jg9HpdZ0f90M-RgW@-KVMSv~nY04Ey?u5BGeb)XbgYC&UPajjj0Ebd
zqpzGaEJ$g8e*B>+U_x=BC&esFth<3aE9{I@RU)4VRLXu#Y^WnWdYkAV4g^*epB${}
z^UZXW+wZnNWOWl=s_)sPxmYy*8h2EJgm^Itb%#JN{X&Pq7*<a-gIm@>K=9k;{-)Ke
zIg8#4eJk3{T;FG8**QgU5{|?Z$<9@Tt$i9YtPaW~%{M*J*<L}x_pH#x9=kh2k)(sQ
zN4HjKP);pmF^&Tvz1ZFgiFM%LsDxZmp=JBmsfMFE5ao6eNfii(5aB3ZXf4<Nbm_vd
zrMeS!qR=X~Lxfq8lfNYXX7(ik`?Jy0O_CUz0$-ZLhF8mtU1detB}?y$g`}?_ELU!L
zPP|bs6BSuw$|XvsxhaYp!k(QhMmReY^c2poE8Dh^@g#3{Eviucx-~yKJ71xNO{R#1
zilHAxR7)d4N+h77a!vHkjGeZuI>9aDdKXs>?vcw^*$||xGhy1YI#l<SQ)og`+H)Ga
zNr{b>ba4a>+9Ni#ZRlOQYe5j0N@xcvH6-j4S)*sndS@=Ig+{NuD}4*W?H2UekkRk<
z1-UkKW4QI;o#BIb(WXWch#*G|jb`ogRGyJIHRD^(Lz>M?8k>Y;I#gE{i!$2sgJ0Fg
zUsb(R^T;HuVLOq^x&-Z4)|IyD8xrC|F<*GGo@VQa?vWG?Q-P6Vv;q$+;;1o79?Hrw
z7^qB;{n5edQSutDE<G!P6pKCpB^wFUh(W+u1zBCjKvwMJUpr)}3(cp6W2$GP7m68Z
z9fp^bBc*#vR%x1@&`!a7dH0dM#-#<ctgBisP4b&0Q$;PXTOU~Mi;9COC_H!SSEtA}
z7vZ6M*>eRnq($bp#raWXaluvnvSx@vZE8__<>xON6?^w|k-8eV^_$Zw1}^D?I*rcp
zZM*0dg(S)S@E~EE`lNoBIrh)D9SN`Qx@)JabheO2H8AE4G|`+kKyn#`=nX+q;vx$z
zwh8Sp*fwW*E&5pLZJWj=u6-|b+R&0wciup;{q%BvTA3ZscTZ4q7VcK$KqPiBo;PUs
zv+MxaV4$~gWzqO7fQVc#-7t}AZl5X9y7<Tb0pQbqR+JXU&7|KJaBh!GM=^rzt+B}(
zZgu&^n#$OWg}^NVI@T6QrZfG-mA|Pdv?YL|5{go7=B~VABlH)A5?I^j-}9)rdb?QG
z3|5`*>Ry>?y(ajwYCZiG)8BXbB1Zv8DH^KCZYUP$P&7VU6&?H9sy$F0othFXtAyk)
zP#}vKCCm9tP2lkH2OR;s*4VQHc~yt8ur0=aF>*<ulJ+jR2=`H1NrnoFfv5?t8Ly@)
zajkeY{r0QuZ#_zaJN@L53ohH%{B=kt)$k_Ua)0Ajoc~xwB3K1yYX$YcE&+y4Qv?D-
zIa=64exu=Z0l`s7N|*XOLzqa0L~>eoQU1=v{byRh<Niko|6dcrheOIsfAs?VLt+1q
z)8Q;d=vLkNu|{I!!<+E0aNGUS8tH!+yQU(nh?2MmC$d|#H{k_gqBtkfI^Y`2G^9?Q
z-ML(=KDC_f@=k#wu-&&?RqoqGyk(|RRVGcnv&|J12MwHxi;KM8M=w?)u>Yj>{cK6l
zD#%Ct7F@X2-uz#6R^TW#q{^6ZhQL-H%Juu=BCDwdCq<r{wOZj{rxJ*(%Z=ctRL(-<
z#^~gQF(LA(6Aff5hwC2OmwJIX_U^P<|M9KD%0scgJl7&{M7@@sDSW^usszX*Rc?lR
zM80~3Uh3>ot)~iRNJ1CtF#Iui<N|PS3^{3A=5k0C95{rd5B<p|@S&WP>b+_uqv?U2
zS0kb->sS6*{4f%fu4Ktq-w?u;R$yS}n_CW%CkzQEJxBJBUWf_8y1K9GSpLx=@s1sI
zB#;S!e-j8HQ0){giSnTt%~zWl$Zsz?cRTplH37xu@nG&QU`K6xNUNfv+B7sGY!%6W
zHAz%}b(_hmwl0!_r^L&ECz(a=kX)7&7pm}yxK{frjEsG+-XFt>+ch746EqK=n0}o|
zrKi-@w(Y5FrvGj0${o!^h6(5&%f`b5hKLj(5|t1@OZSBe3@ak+pu=P`_o*G6yryG>
z<?`4cOi)6J(TbSxr6BRJ`#D%Q9ITtf1{IA=f}!Xd)a6*%Xr6rwt_`}PqNy%Yask8x
z#2SbgC5qz#3$j3XxPQ)_^%;h0gbRzrK3BT6L(ivd+OG}TR}j?DFuZrFyiE^;X1%JK
zj#i6nAM}s{_8z@a(ao?I`Phs3W$v|C$qox$6BmfY@0}j+*E#izbe{pDoOl2HwbRn1
zz?hNw<CfD}0Re#tKw;T8ZZ_D|?Rp=r6l~<D+E*&av)wf}&-Gpso2>xkTUCkq`ttHC
z!1hi`o*xcOktouUj3|D{S4*WF!O$ayo9An#btZQg^W9ltC}(HlnBnL8%-&!}!+Z`m
zau~?iS&!)Pfs*)flPTRoW_YY}hyhA(<Lw2aYQTMeFfcG!$M7!WWq^AUFz1F)3qQGs
zpfuPzKgV#r3Q=@crYG}M7jT7l24y!&s`~L@+2dR9n4`y2Y|5xhZrXg}7F&PSz77W0
zlveeNvPN$MlCGLP)9c1~0j%R%H=WaS3{m_okoo+a6<_@xwi<EMYEd!X<_h5F1SOjC
z2mQe*5&n5fSWs=_TW#7*d>l*47NZ+srI;R{kzgbfG^g<h@XmGgUO!q}$!_6YtNZL>
zgJ4~iaNC=(v|AsqsNL%2N_}?zC4lIn1RI9Z-H4GTtoZiLB7X1$&{Wl!PK)%;Kj>Mm
z@;5h#@ixAL28E=iA8q)8-bc<;9&4p`<xP95m203D)Y4j5kU_IEZu@#M>7nBK&PR>9
z(%Q-1TENlU*Tu$Q_~<=Ac3r>sCDr$;!tr`lv|5I^`|E{-H^$CG^77I25RP;exRRAZ
zNvtGLMrS^)@1b&Xrg5bEj_;TEkjfaJ5XT%7>iY&zzfTY5LZ-k`>+HN^p*cDRdSqjI
z*sJHiI})G8sAQSupm055C7i45)!yD-mST2-@A{kV{#tP3)PBpkw_*L0Y<iawt*37x
zIOBjwuQ#ISBq0`f#VTlh%jQ78P=0>*yU+O)&+D&oUsTO>ZHF3GM`P}JgJ<r2xH;g)
zjt~_juza5!$!Fd*-bMQun2gE``?DzD9V~{_PoU?C^oqxBoG{~%Yp`8scS;;1mftci
z3lm~BNHaQ^HlylZtACb|Or*WQS5^oqabK12Tp*cf^cEnUBSG7WdU_K9rcY!jS8)oX
ztVzD;54E+mS>io?idVeJ`G2&7it`reR*+l{8@gVp{T|TLG&|Ef8&g8W`Sef6v!~QH
z>lX-9r9e-^x}{VVE*YB}7viu9k>?==3u1`To_G-Kn_$sFvx4dMq9Vgpa=IzO(nDgY
z0phd<9IO+NsY&#J8P7i?0HyXLRyv{SC$b2{YM~}kfFTS1s>op*RrBCsqw&*;&dr9k
zvU`tipAmB_N3tkN5UfHDKW3gi@Rn@6wzHfYeUZ0KbOjY(L`uA&>U2|GY@@pW#(PM)
z`N%XC0S=eogo%XQQo3tKy3g66->U;|gjtSBF=)cL{x+BKA+24tRvj7`<;%do*E_<)
zHpghFrdCso;~9*>sG%4&zpvwgm+(!a1oSSX@4lmok&mFnmcX))<yK;u_KJ8y6dEk3
zEXOad8sVYC!VVaE)dF87+i6XXQxhlYq7{giMi=1I={^VzX}(gS5_q@!l~-b>XfUV1
zNcpXYk04sF32v6(a|q~smsep#@q;rJuT6+6T$zUHZvywBzzCvJg~AcY8&<-U-OiLK
zk}G!T-~xVFup80{5(r7*@n++IJ!o^fCmhEXF9g~Y-t)H5i5q;{_5F$;`px%|x*v;d
z^xILon9c|)94BT;zz}9>Jp(Nn*bhNVh)>nc0r8v54;>^B9!6!ss(oo9H<y)Tv2;ao
z<Q7#Bcs<<(na^m%oAu)7+ao+I`FE6LvJ386ksj?$J-)KzPd>%=rs=x`LX?t^R?^F@
z=QB}hgl~dmGU8vWjtH|xc^Yr77{rn6CcXNjaW4*O2F(eG(|lAG5KN~`!!KnHf)AWU
zS^^6czwAcDo}8cV<3t`32#zD%E|p~@<vlz(_}Tg-uQdQ?3ayp9ZhC&Ccl|3UefKO$
z9rkGW2fqq_x?)T>DvqrxAru#C;!(3<8NsHj%E^Ca@n9kPyBB}iaU+|t4e9G(pTh13
zpm%{^B3tz#SiB9i(s^aLpCMfvH_|tOse>+NI8dKC5;$vqg*=;dVp6GjxoeCutRTiH
z#eLzYQ*C0;OHyIW4tYO}kGDVdxCNQk<~TfaRy5I-xb%^@MEk?`d6aJgn*!0_uI9*0
zTRpN(X8v1TLKXcQX8%`{krvo;PKqPPTGm6f??>B*%S~JE3BT~LYCFFIdWu?^M%uF#
zA!|d;i#(&Y3!eka*dKuOFoQhbgmM4e(ZpWg{?xjL0XS&!znyek^9x-=W}%S4x*9#z
zm<<qJuKP7m5f5kY{SkODpaK)>k;q}Hc(irGdF|6MTwcZJ;XI2-#4+p!7h;0Q_-Pa|
zgo9ochT>=bq;v&zO?vZ%RVk1X3q4TvpEpUmyd=p%3nl&$j|H8#oW60}2B@bn$=}g!
zrxQgf;Ml}W)0MaMdimV@cx!LZpu^u=25}86p;|5{YRwPC70G`t8C9yFu0HKL=9J^H
z)f`tXA8~|4h+^C`H%Flg_^;KIf4S@<vw8DK7S>h1A=0yn-TZp<9KFu&W$h&oR$t!{
zo3A>~(*Ql)`={b5OMF64XC$2LUcB^<fV#?uo|2&UwyO|rtqcD{Ej*YwKv8ZCZ@G1^
zfL+V~bJy7li)8v%c>@{iyFUaiGH+e=X*aWZcFG4sEs=9DGK1|rhYc^a1EDGs{RvJ0
zf-}8^);a{gZQZS4gK>gY>8d>6WyU}?h48;!42qX+1nmX3c37fM22CVI>m#c#&^%8x
zvpC&^$7tkjU-%y<)J*gh#w~QVEFtoffz=+bPWp04V?h|@y;yvG4=xL=t^*(O6$+bY
z)~xaE&|_5r9&8I2Tndba5ffj@RY)hnbkP0;cx~SD0|R2v9IPUmL>ox}?i29s=V4|>
z5-B~n$^nNOgDWi9Fmcc~>_*H|G#-QnmC-)9g$4O3;xQtzfjLga&?D)$ABc&E-vVqG
z8m*Pv9|Z>SAQ718>SfD84UGlL#w4pOjSH|QX<%O&6Oe>lR05Q75ajrb)QB$-2&^Lj
zq1DL)mKWCsDjcB$L%Ew)U>Hh5W`qcOsg(&w9Ej14M!1L`H0&zD;2nyf{~-Drt1RLM
zbjMdNIL@CGY@P+4YAmk~exc*QmdOI@DRTq)_5zp>M>;3`kG%v9fM;apD$aZa!<0P(
z(N|!X{pAVW0B8J@|B0^HuLkMRXiRW5R0&2tfGtD9F0o>>DuLm|f{o#6;1>~Xyg(#7
z=xTo8>x%>CBl4G{XvC}wFB6DaQZc%rARTlh@4>aC;MZXhbUzY+p;&!EKLzlfkpw}E
zu_(#fgiC(!;DZ-Psa5b)V!&{O?NbU+3Sn_Xk;DDep>TK)7K8}Mp8*!e`IHf$eR4@~
zVqQ@UE*fHB*ak_?Gva%2N|7%dKztwHYHj#}{WAR~_beQi8wunI2ryiFe4Wz~oXA%t
z4q|9JM$ix_16Z>-ob>j(3|JS37aPzXI*HYcr(oD5v)n1-Eit#_TOA<20>9iza7cl2
zzDO@{<_F{2H(*T6#4bedP7W<1sHn<559e7NiQ&UMfE-siq-)DrLDG}7GvWFP2;^?`
z_3mU`s208wsV2*fnQNUebkmG&PuyaiTzFil{?0KHnPaIE)&tZe&b%*U6$oG3hi@rV
zf`$0CFSpU7+DBUVNxhF#1cVAQv=u{MHcvA-;HpLw4qb~&Hw#HUy0BaC4-f5b&0WPP
z3WAs!Y*(S4oWKtam*YWvZ?Y78sG>W%W}q$`0O0%nVqGoeS!3;}o?DoHcp6&ip3&oo
zXHVl~qE-0|{e0!xW3{bieHmgVpIDaf0<$WN7IsR=Ap4<?jQcV(Z1$;Opi-i6Od)4J
z334Inl$*LYIR$T3UrB$Yc>Y<-J-?S8_w<v1=Ejix*V77}<ItycB~nVsWwVNX^Qh;1
zf<R(TI$G83k-nS0zMH*j)6Odd!s-m6S*H!etQ~kD1}g${=?+AJ&~q8$0b1*4TomW#
z9suV2blu}#I01Wc*5uqF*If2}P9|}2ZlkZ$uPN5EE*3NWX~@9RfNdZK|1jLYY{BvN
zrT0pF_gAEeR7F^}*q4_c$4lLBNxOkBkzO+LRA#6+d4kf=_C6WAI(LmnPm9#g4zgO%
ze2Ehs#<P?SExH+<z!R285suM#g5N9=4!p+4yPAcE+^bd`I}a-19wu>Eq&2>BT1#Ha
zTqA2=Gf-?39Exr^XsU;(5TNrJ`kL|U;M^;zbfT^XfIVNjD9|t4OO<lsy{IwHTfh^P
zp?=3&Oah*zSN_fu>0kGV(lho}y*g=~wuU*E%O&iyvN^~5_hZwRT|F*KpNZKPUCmI_
z2I{P=j6f@}0p)vni3=xD0BH0lCIj~Fs=44+@t0sGHVwg4$tFwU)RYe%`zCi3noD-p
zEc1D<&1JqHFJ3c_WnQt|MIqQ9`l?QF!j*cVGA=jdu^>IV!Xht9fE%l%nRtFhF9jQA
zu%m9&);6C}^sU)dr`AJ-Ur63GRJlf4$wCaqLfyZfCkfWDOYIspc@x-?B_y{&1bP=R
zSY~U%Z><iJ*CcwrJM?gMt8M9N;5M-?BBOlhVJy$O*0Y~s?xXdLnq~&~DYoVmy@!t!
z`;xzhjM*?z$G%X~Y*-P9O?Y%U*+b>q2gZsxV7x49X{V!P!0<A1`YJqBfkzW`-ZgfB
zq23%U;VYAH4E?x<8^+c&klG!%zxCx#3nf%rLaa6r$pNIpA#*|x<pACfg@Eg3V;sfe
zhiS?<(lOcjXZ>7#5@D*cwZw6&T2xb{kgyC6R++cp)ZSsk-GEE`iBQt5-~vY1Q1Ya`
zZbWRpnK*9wfbuFXB#eSLXbe-{?I-hX-wyy@P%#btkO2(+oB)5X<agiD{#}xX(hFH_
z_p8J)y)P@UVZFf5C#Z(+A~a>eA_(TH)>eTeMyrY~RM}ZdOR-JgF0<9x)PFiT99_?9
zu9Zfva($+=s|2d^z`aTct_x175RaC2GzB=3M);$5cj`k>Z)xY!V?Jc0r;hhmiUT+H
z{5LoD%S7TZ;X}Fc*jriY;w61H*3E0*vrCh>dnC5>Bv{~K)Ie8v^4KOoF7tplpHAx{
zSQPaoYY941Xx!(ks>n9kT95rr?J<ull|jBJA@9PM=fKCFo4+F&0ge+z=%3apD~CJ@
zD`MECWvIN3RBDT#T${7ofQL%0sH&ZUX%DDwS{sFceTZK2pd_S*{1ghGV;~Jv_G2^@
z72b_|w44;kVx#Tvdyv{ZB7O?S?R1CI$h-xP{H-cbk>vYa`c^`PGfi|A@1`beO4m4I
zUo5{LQ^aCMOemX1v0%y$JDq_v(pmUG0;nHx;4mJJ_m)+A%6cA@Zp_$n^JztgHS<px
z&we}+z6V3C-?}Fc*9D=z@G><m65$R`W9!3&ISkALM|j)`47LvHlso7B0snH68<*zn
z{MF-D^&{bAN{PtgI~reQkmBzpiq<GVXexf9HSs4jlaR89b!=lP=zA-NvDMlvCj~nx
ztFW-ke@h~ttb)m#8jN@{Svf?ou%4V>_0R(kTF}rUeg}jTLrVMugtvL=7_^xl2#t5O
z2qElD_Zc0WZl%>H=%{0_1wPChw@4>~db-h8X|U;Pdc@vtIeRhjs?^hjkQIrz0G53T
z7AyNs5-8s>U;kGUCg2)u`Up9>nGen4q&PnBR?2DJg|Xm;CqVobF|Y^rH|$X&f{T11
z^0UvFA9W|@Do>*o4E8-B)3aVB0NYE|)Ee>t);Hp`BO&?J11V0(aJ#N%OaZBM0p1}8
zum~=9rwjsvVH5Z{xc+>%Nb3?<&*dy_7MLSYlN<jC#UOw(a{V2OF^1TCL2eg;0GoFI
z0-|ci`&U{k17Lk9D9j8<rXx7XpOKgz>`F8#Apzl659?^EDT|XGieQ{J+-#fb%V_fA
z_*kH)&ADdr5_sIjWk*{9%yNaX))}CSz=!u{cZe1;6DRw!xMX>(rF-6&)4%s^V4&x@
z$yjOT-AaJbdMu1YigdwHZIX+e5Wh{J`wv2sVP>Q;OKeh>k2QQ6nOI6AOFw-Y|MW05
zwv;*fcqa4{2}R=6>q?k>TaKRN+LHS=al)!nz9kooMWP~$?Ip&Jcu;hjlwhvA&#md{
zbZ$X!%+28LwXySd5MGZ-3QnsI#O_j#cs4dUXwbm0DnFF`RZfBppDLv<<+g{|C-gO7
zR<$P+p7~&gmxR1H$rM0VcbM*4cF(=`O`t99l8mf1dmsL3Txh>3TO)wLj(YOYX~>a<
zm8Lh3w@?1%&2HPD^Nz0XJsdDNnC;e~3r5!$zBnzPft{X&Q3w!_pvfQ{6i&M@K&dec
zJtjAc&jWHAMx#}Zq3b+soyl#qv$G@^G~_q~=2(@)#`*$^y&WM}wYmY6jj@lHG0VAc
z1hU;1<mo>1!H@gWQ`cDU&wJjuBKRvf@PM_uP(LM{6ap6fm?XCu<16OnVxHIY;;OV}
zkOH$u1OI5zFQ>$rZ}jaVT<K+&J^}P^20;m+(Kunpr<bw8`QwGNkx)-0#gm+th_JoC
z23KZDYb5vg?PyQbX1r$shg<yvP68*}5k~<kuB@y<4_0;AYV~NbVJHJfTO7YQuyTOP
zAkZ3sJVqohj%48h!BPxz&Z1B;flDzTUiif%L|le&B$Ka6XPJTDI^T_BL3@A%;w<|a
zm_ZDY!>ZU~YLlrv${KB?%qp;5F=p}D;nkSnB)kkM6h9n?LLY({+6(KnCPx1S6n_zv
z@~^W~Wpln`XI2NrkatD;%DoIu!2Wl098UzhZYUX4B@=L!W76K?FoY}f*u#}px03N5
zVo*i8z9S1Y(D4Vt^>-!tVJy2trAkUWXR#hBvi`m(NuR>37GQNg=8Ao5p&(2sw)PKa
zGa)|9S8+2ICfC(4BR((kQtW}5<~2&tR`i&&6+V!>A_|>%+VO8tRq|Kf$duTso2sj6
zEU>e3Jod*vYXKFQpOQWzzB^!N!?d*47k@$cKTS5V$ocML8`q#ml3~r5pyHw`HIQ=K
znrh`h3>p_DtQm0&+;)Td4k4!v5Pyk$wR#i|q%a<7IH)?`99(;e;MwL@*WPu4-K2V<
z`Zdcw-dGf>a0vz}Og&jd#)E@m8Ay|m`Rg<g1Yi<=xois;5RX}yfoZbw4efsl{<O7<
z`b>H)f+|&6yINRlXu#n;9#q>TO&=e68|ZwIZx<V}5(u1e{0@6mxIm>ypWo${)1HUr
zRXn!O2s`$vlVG1|ebU4^=Q91He6#lB;47K;ukKqkdAyW(6FI?7=D`qLE@dHTyOxnG
zi%a|t3rulA`YUmz2Jj)zp5Js2ge$SNr*ue*P!BajMOLORuYU>)e^!PT%41JdKzhhT
z+c9c_R7l3`FQf{xHjJ~8_lLDP&OhZ+wz9EZtEKc{G|zsR2jRNQ3lQ;hL}L*<&_W6M
zRP)^=aAtPPtBvz;CGYOp?c7<P+*2pAl@-WO@i<+nU)7u-QE3E7F=SNSfNT4C!&X-m
z<dTeJzolgeL~J%Hiv>JedDy~~1ZV)$MHL5PH~>9LIKP3Oz>*&?z(XB=pgk}^rI3h(
zBG8u_Dnt3dY<4W!SMMMi;8__LqpTyqMi~CPoR0;_UU_nz3uB-iNDe|MBZwd?zq^1K
z3I?z<Ou*8R0K<0~bNqkHDD5y94@9y5l5770OR3)Sz-5MAzS=2`0D+E?{$H7V8L+R)
zHc(giBP}Zg3W}1H(<S~blfQ-uX;^;08X@u?z~vM`*7Z(PTNC4fSgfkbL%|+NF60Tr
z12N(5!r$Q-WB)RD+%Q!LVK-fgT`+tkBot4^mr?(#Zvl9+#s$S1fCCwcemm1YQ*8iz
z;#lnVDEPpR&9caG{D=V_a{fmm4=nK=UNm?%15R{NK?WFpM64zKTOwZz7W5SY3M{~l
zb|=L#5>tcR3{&Dz1~<o{`kI-5_mR7lFpnT+0^o)4-@wZpcy`Ca7p>h9Ab#yDOq_5?
z@V(dz8Q^Ad0=iL3upsf@AnLDj%vEJ@mT}b+dL3ZLp?=zQFd4Af;eQ7Y;^5hCbmB!B
z9$@&YtQ<DuZ+SdsK{&+!O@#wkgL0hUaX3(CQa;V_03`5@GNS)xi9y}qk<kH)qdLH*
zmAymJh~MfbhTzvNP+9_tGjFciLmc`XOXB~PDgED6cE1-e)U>Src=M~}qRjqN=hrQL
zM#3NS`!gpG8#%V~#}%ujI9>HhlBI!2E(Y{6<^_XeP0`dOfs+H>jG;FnMOXOBb=vj}
zvwr$K#6T`&GskUM{UA0dXz{RTK(U6aSD6Ipi+pPq=YI=bw!oWF6NZnQZj*iiY>>Wl
zdbVr`&wgD}66MEa!;6G;k9dR)(*NoO0B??Ry^j8YSJo}x#C7C8ysoUEp&}30sks4-
zD|({&@;Q*+4N6Ty_Ed1rwp{|-inq-nVd0PU6)qCckcTSk>o<_m>*4I?D5+R{$h?1L
z;BZ_r{k*V=ZzB?2q$I)zT)COAN-XgKponBR|9OB9<dD6%rKpau@Objm7F~^S)PvS}
z?A8;q-51x>is>eMN&<XY+Fv$}fZ`TPa-m<#6TIg0llz{okYZL845j;SR5iyW{_ONP
z^;kswE7zMQ57loxDYWpO<EqaE1t{|A7l57WfF+szJK*@_LZnnPm;4;v-Ladr?3pbu
z!J1;Y_33%tGHW5_)1WCv1O?RG1+I$(5Dbg5SSITZ*t$WiWs3w8(EZy7ZQAo5s$2MR
zG0R~_-}~GKOj5Su`b_v6i@Yne9DpC0fc(>s0H=g0*#U(P3#<*cF0_=>*o=!IUu7M7
zRl0(oKUJLBtU{#BGU85hU+yx;MJP5fc9x63`4>{dJ4$kCG2|Y2R3Nj9%3z4exQT+n
z$uYSI?ce6i1l4Y*iwS&wnJ?!NQO|UzligNY&)!k>*vk<Ui!|bx8`2dtup)qnbRm&y
zh!}pLLRRzZyrh_trGLe+%#PBRCq&BGjE1Cfu9k0X%GJF`B~wnd@*2?*yCg9U@S8Yy
zLHe&0`L@ast_!Lfg@Kf7`54s=*L*~%tgp0n<-D=lys*ziSj=smSEiEt0bGf5I9cTZ
zC^*Iqy>--|0M`D1E5pT!AN(M@5!gX6p&hO4hKsK((GmiKC_g;XE_@F3<p!w|A@dYQ
z-MWRU6hnO7NG5-f)sE=I@v?}*2_{nbd=!kEzzsi{ybDo(x!5%je6&q}_J0^+LYM^K
zIFD@!`aEtz^w>rb`R0}>=LSF!9q~x5z9Zm}MqE#tBs^dpQ-eWVo58j#ksF<#Wpj4Z
z6K<tT3B1tQ+S{pXdM3>TjSJgZL}+8);IX=gri8U&{7LJd`E9}QTwP6ZH)=4x)<|Tt
zbR!~(8!z}tpP~3bgdzmI$MFEVhRni{1}@X%c+fE5O-VcZ`g4E?<m87V9Mcl&h3ZsQ
z@cP&taB_P#Ba(S)u_LI))8w6OzqP&0{~TWp$AiwxPiiUu6<o)tfEhH;r@zdVN8TXo
zwI-5-GLe8P%KkG_T$OBh)}X!Y`^Fpe8?Bj=>Bm+}oU6(Xszz=8zPhw7wE;*guoA#B
zL;O<6LXD7=+}91?)K@N8KNd=rXsonL;^qVI8&}%ti-`fTuXo%CW_Do8`3{;Ah){B-
z>INQ_s$-4X=;wFwEnfx)BpTeYHtzA*U$xu&#Y5D1thD%?@>Sh8Og4!YKxpECNkri{
zLYAfc-eI#`QxX;Zki@fLKzphlM{a_LJNTU1B0@!oW!SOaMUM!E+LU3~g@lAS5YUTO
zSGf`FJF1em4cj%5#Gu<%+=;Kl0zowd2bMz_vv1LCsq;;(aQPkWG5;i9AD3>mn(S<F
zcwONmoI@^EBNhRJEmn)o>4!~{+uvUHz5JMKT;V_s7IOnpp+X01NCkOMK;q<g@F@hl
zCeM!-w8P1KLXZMrfHk^;07lA2T;qGP(Bw1DrDLLeaJ6BxtR{QZfYz|_BpW1crGu4k
z*2zf`rMWJi)q$S(`5%1PMF$22WhAW<Gb2VF%!_r255Swu>8WxWL`t0V(yW!3D%~A%
zk(B48?}~io=y`C%<m6SGJJ9=Gr=^PXIobE@wKT$$e*C!pt%-Xfz*jDPJ|X$f`gqYM
z2<t9Xj)dcwE)_2={QWj1ZGPKZs`~o;)HSQD+}!w7-yX<EJj;;sxm$5}{h>6nNS#)&
z1YjrB9$(hQ36NDi5UQoS8w}=I!TknuVCjc#65Mlh_hb7!Iryb#ck2Tk0z<-sd@_SG
zE`v-sOjV5&7>Dlj=L85%K`@Q2ZVBA)*Bi^t?4C)elJUxQD~Y*`gsi2!`x7V03<UUV
z%B<}Y{1P1O(~S$g)YspZfKNP_MO?F;?+BCNkQm<!W6yZiCp0^q;khZ|xmNn{yWg@y
zD>;@Q6oVC@zlCNf;2s|1;SE?iB=Yc+bBpV8dp(KW?T|xWf`nl)$+KW65;_sF5{wU`
z$4-^qO$JE!@%pgQwwVTFaen{Y;Z6Hvf{@3LyghcaaZof_wmME=XrC++`vyQ~Jx`v9
zRIdZ?Qc3pSLp07?aGL!Emn;!L>Jnnz;l2;pljxNHptB=z1^kgzz>O=<f!cjXH(JXQ
z1Iej=gKxheISjaJ+%^lnSPUdrRPiHT2AUdk>2Hs0_G_A(V49_6t^H~+Y?y&@6$f%t
z78GQzfV(9XB1Of(vtIuOJ^u_D|6zFm_WYgY`4f9$kdyzbiQ8X+>As8AM!-ZdLGvG=
z{C}VZe*@(gfZW4=llz~L-yh5hyI)oO4on)$oQH%v1MjVL@n4zNuc9R=V1X1I?KugC
zSw$1?2K)vOfe$1mh5V-Bzrg4JW2N~gDklU+&4M9S{~h!Hht>qB?f*x#=6@9aR~q^s
zh5tW<$N!JQ|3~5fr^Xee5%h-DFiWbai}i#q=F<_CV-Mxw!v6(7{T;{WNn_B2*-cF|
zNj%1rcc*jYBWypvaZf)#2VI(?J_=?zIhz_Hfc31%$v*>ij*|##fihVPzPu=LA%rf~
zm)pcPzuYl7pRMY1(|hB_uO1OnQ<(1-sY$IJm)xzg1>a(z*!_?&O~N$-l3Z<_lXdY0
z03M#>yl8)a5#-mj4kdNDp=y5;{7b@y21&fkrn+rD1EzJUO|H()<8iF2P(Hxtuw#p?
zxYx(=Kp@H~!pFt`UPEq}FQkgG&iPmn4Vp&mRoPk9je3`@Vq@yFO-RYSgF?J->#){_
z0g`}}NKYlm_g6*mUyV{oHf&Uyuoy{fmhk<Rv4LBr@|0m=9?GCO+#;S`!{Vx*NSe6`
z4kV2Fdgqt`K>lUz1Fgp(#sA5wJ#zC_mOVDAkv}FuNsfhMRe2?U>;d@rn4st0dRB6v
z@{b;$TH=_mFRQwbKwHp=Mu~{_uX1I1R555dq&|5Sqof(G6qYf`3SQ>!0UtwXA1uA`
z^G+iTRQsC9@0lt1HWCArQxot<D7;7Zpd+1>)cdtNdp486gz>f_=G%Ip@tQ_v_`-CM
zp!|Pd1P9QJWghk9#(eV<g$9vw^&66yNAB7*zjF6~6({A8as3d2Q9M=U&yDJ7F>m%i
zdwyUnWD>-1OXINrh7qa(tyhIfMu}62%Zv^hlV;kU?p`D@Tf!BTup+Q;UD-%GM9g*Y
z@cUoZc}Rf@v0N_Zm6I8sG;k&i%c#ujK700~6$kU_pVj^Np=%^D&o3smt6-Qiiu+ll
z#LJ+vD-(QxLHt@HJCdN&;l@2=t7{yB<$X6kxOS$U_yJRhqtYh48UZwnTS4HsJJ1&;
z+~v`G$L-x6zho9s#zWA4zUD}X3yqsU$+P|pvW+)Hj5wM^V7yVn@y@1spLc3$o@s=@
zj@2u|wO2u^l#_2dw{2VFuxqQ$tt3zZLfxUhZe&G9(Mq_CLv(TAC4`IL84E)&BoxCU
z@9kaCOE+))4*f&|;9=0IvTA1+X;-VgrXq;43MF`SnHb)^E?;H0dQ!MIv>t7{IsZD}
zmH8D4bXovbN%uBBJIkiBAvUPAIL>rD?PKjpNkAZOKP04;&f*3FyZb^P7h1y#sNbE9
znX!~(0mGKhr~coYN|LYLZRnt^;l*nnd8=10t2#@$Hq%&F!)r(MtU#f;_BL<eS<5Sl
zG5l=19kE?a{yn=(y-p7c>tuXvmeZ#!q>rJXcB-Xm@04j_vpPnOyc69upBE93dAz$~
z8R<>qbX-kHJIz0Ca9lI#UXWo)G=1v3YqM;L!{DBE`o&V}m2wsP#8;8{fYXXUcOs{a
z-^UmmSZ@-?1XwifoD9+?7OnQWosny&>r<d5f|74_4K%)V6g<)zYryR1k~PhPVnU<Q
zlp{gxCj2Ik-Br3_{>MGyh7HbEOS3E-N9pmzxC-abPQ^SKEx2FYccSdCfJ9#KXTZaa
z?6|*~^IFiS=LGqny7{YITy6%wa)g{hi>m~UfhlP=15sjjgR&9}*W_MV>i5dy?+vr|
zO>1{jZ@NZpylL-$`uX<KL}-oTc<RU5>Ir<yF}n=Z##@q@YI&CVqx!lUF}@WAm9!V!
z2Gv(%NR-2pz`H6p=T+qO=%A$Zsw)0S(4P>PhAF<xlM)kH8d!F^*oLS*eU-Vnt&@6i
zAeXw;Lq7FWOl<Nj<ojdq<DD9Z<mXj>b{Fj0a>>>MT%}&k&hC1yO_i6YyU)Me8|f%0
z(a4mnJzk!%%aq;64U}zS7>jE9wE1R5Jr#UJbE9U~<mn(E&V>JK{PhyD{z}UXkFJ!|
z)D09L`-Fv|y@e_jZ%ur(#6*V2JjX}Wm|ETBh<eL`bE=?wO8UWjvW;9KsY>i^s&T#+
zk*>X?pC*DH;IoHcc!{b@>t;nmr|aK$V@H!nY$Y&njB=DuCb;W}hd%PwCBZb+@wz6&
zkqUWnojBo=14{lO<|8|<1S<yhPwqcaM~^c5lf;OAFeMcE`)jO4?BHNaMBLO2UB?^t
z4k@G_7i79OY`6|SYi0TPef@x5Y`g8|26)k=v&-cAr?TdCYg*4;{VChVK7U4CMS72f
z((4bfkNd1zDqe4Yo6Kn3v{Gd7LD{t|>^<!+bsbk*u&?~-8eJ#Z=WTnmvr;=en7H1N
zt5Mw=aB<4YGR>mAX)ERQ!9eDCF4>iuZU*-c_DzR(j@z&Kz=Iu|_CDEQUUHdwq0=?K
znrS*iD7u446>-h)OB490;AJ0ZSNWOk=~SkDRc*Fi>yJ`)c5$mQ6Nl2sM!U48trado
zE6VRT(UKo?W<YmUQo&fB2(?2K3r+80F!<c#J$2n_!_PDMM@_+=LCG1t_)u->d-@bm
z3g8krVO^`lXl&5+@fDxzS!=WKdW4|a54h*<hF<A?r0n&Ug-Nb*0UIH)t!3to6Q_Z?
zWD~cZvii;Ndu}@C!DoWj2Uk76Ne$?mtD65`?0sca)Lj>^GYrx&fHcC;A_@vpQbV^W
zBA}E?w{({v-6@h1g3{e3NQi)dba!|6J)_U_yzhH+t$V-RyVm_QF!PUd_Stpz{_TD4
znXMHZT@7eEA2OY7tTdEOIE+mko_8ddH+Kub_Bek96}L8Wn{^SIj^<d_ns{Hw!*-Ud
zuUI=;-{*Q%At_HbvOFO@_AO4wEWxs_s_Xd!7IJsHv5<-p&;TS#>&*&!`FF}3^_nt`
ztNIJ`B<{f?zsr+wyZx;~;kwh|9Hj=6rSnbdnhUS7jRhs0@*~4~ogjEo&+njB+8yXC
z!ie`qR%y!bGNQ|rxT0E&-WwNXrno%VX&!s;#`$slbx^_4LE8`C1!s%rh{sz%{W|wt
z3!TD&T7lLDI(Y)NT2%M-eBACWpe0lp8QjZQ^{SyMtk8Drba!dB+!!zEDdXQ;942g|
zeN{r*U3_`-!n|%^sKg<w*7WI;BHrLt&)!wh*;eHgd*v~7%(~?6M(|#D;lPlN5IIq1
zz?><*dcW$~xCxI*-jgOh>x=$(S8v(a3qyD&+LIk;v1)eTvYGEnM{Q(qDHZ3Hk9;Ss
z;3%)LtQ*U(TYo_%{JK)>%?Wz>;uq6VU!C!vtyA2S*Tbl(_dU<|K6;FX%vqG0ZdDFy
zC+~6!Ay~f~!7`BdoR7LEPPPWvj--Xk%sV2-9bz}JeDoQ06tDvV*X&kU)nFh<KSJ{_
z_%@K7Yz)1NS8HS2P0br4aVceV&A!9R8YXec4xhPsdB$Ez-!xcCw#n~G5b41eK75%_
z_3{%Q?Y;3qimFFH(fS^wvcBIV+=Ps5xYUe<9bFcgH|!lA&g2q!cPyFWYBvvR8Y{ZY
zP4MP=TwNv+PjFXhD%JH#*ebsD*r_7hSW5S>@HlDH`9XQt5gN;!J>@#rbvVw|GlCwc
z`Lf2t!-1-9%4lpRK>!A|9+8Y2@rx2J)m0MUA%DxQ&u)Y4i|oUc(PsQ5V`0=TBr7K(
z|M0=ltIcsRYdx&!_YW*VA6e#Cz`Y2;amm2}W=+c{-g`d@nFuYOEIcsFY+@Vn!nkRa
z6~celG4_hL;^LE*`@}-|4l~sl`jXa5RPWu3u#u@xT?qy$RNMRl2g^^*zcsOqel|=t
z*<0)`5wf3X#uwRqGqyt|FnUbYHnuTmN#M-t%zap_^vU&gPJXG$J&cUZDyH|Q#ic`i
zFZl+iXS~gK{i4jb8=J~Uw+GB-YTq4pZ8R7=TrF6*tW8vy{mOpAlVRsycmB20esHV1
zc+Ij(_&rD3?!k>aU1}r7HA(9~<a<iFdDZ*1Qw|?0HOW0GZevH}^U{syq)NHD)Km{!
z<GCI@*xyJv%fDJX%0Ch%N|jv8Artd>`uv5+IWMn*v`2p&X+{0_zUtA|jj;oR<)ar<
z7uq7c+#`vZ^5**x4E46YO#7`6-Va@g#^rBb1=34DgF;OULOjE<;r;=@t0h(se20vN
z&E9|?c;?=JjVEx~GPf~mHFQ0!ecW`aZrzgsA9K+}(`tsKDaz<j*m`UFod?^4f|qWj
zM@9Epf{Ox(nP1q*muwvNPnb=KAL03`9jq?v$ECPbUF;l+T%X-dPq}Kxe|U;W5OJv2
zavXhkc;t6UBRFA@$C0aVsO1t{clgzmXR-2rd8ylH&~z21G<7-?=592XPiZ)$V_(P3
z!}CHzBO%GUo3*@`nF>8@Tj;3NW&>1R;w`4E+q4TGmUz1xL@g>{YfAyZZ`zOA<QS3~
z&urdTjh>0umX`_@DqkrQq2YadGN;qfPfz!gXGYs!GRV3P{z5G*#!d|QHVZ8h4RPT{
zS{K^TS>Myj85JT*7U5C9LA8^Ojl;_}+A)Wtkv5(wvy$nRM@N&cB_sPQ1~m07>4qaS
zO@n`m4(frDb`7CE$Y+CEVYid{x%W!t-|PF-ok&?*pbOGYO*H}!C^W@0Mg>N_16Dpn
z-FLg(pGNnl^v!heU#_D*O_*G{@7A>ck_s=gZ|Z@qiEJA{p(Ai&?_m1AUeTi6oS<_y
zt@70|Hr^bgj?Q#5o*HF$B#@a}eCZL1-6hiNBEHYr41hnWckX^57cswlaAwpkEh^+l
z?CdN|S%l;7%ZW#+m(DZ()4gb`o@WL$iKVHXXgJe4J9r|EPIPZ^HVDn@VhvQ3YHZc&
z5=_~Ip(<l%+Gs6_LF3Su`27%<E%Szl>xGF4??>K)UdmRylSVd+-DTn)J2(OhY7N-#
z!t-hk#Q{pf#&_@DwIAVM8XhVi?~5(17^9QEsqf)&zJvVbFzjqvW3jHDu;0N_ek6)9
zau&sm-XLPMRkz`zbJ=IWp=s39u;Y8z%(6nhHB^fkLFxM~k{t+o^{lA*zrnKo<&jc&
z6#7?XUp+=Bn+FSzMBGG-T0HKpc~4taMxtSPEjk)KvGkWf*5Nygrbc;BD=y1hTZ+YH
zJlHqKoJ`!D^r5NU(X?dQDx7w3E=v9WGYEYk;p6N<q<9yamF2S`2P{xUC!?v7KQD9E
zTN@TDT(vteH+z`ZU@8#15BJwXj*dbh#*~~b-TZ5J1kR_u%`a=64$E%Z7qYR}5A#ge
zKBcnRtg_!}<zpKC8w&usgxi6lV*&F9x1Ui(S9E^E({$qN>-|auEw8h*9LlB=-@M%@
zoeQ<!%c~gGSJN>k7`F+-GczuF&Sf~-NTOOO9xB*3dL6&?zG1R)LG9_6i<d_e8}TeD
zrG7Nd?H1G`lbe+r<(dR-0$ank8Kg(=v!s~i6x3H=?1qb*_0~G^EHo3C&xg}hO@?1y
zY=D)mC{ojWbu?)mr0pJ&fbsQzMCbC5(gBP-3#$Cuk3wfnC5MN>6;6RFs!`e3+klYa
zQtI(I7INcJ8%0ezwW%7J<Av_dc5+mF18sNLd!;d;yI*lQhL6_@dhilf$A(6I@k)-g
zJtnTZm0wPPPSID+ixdKT!CdP#Q&;sHT+XF#9&uXM&1ny!zvOjYC!n>kY}k?7CO5{L
z8C?LS*d;v=*}_A&HtTD&+`f^NH}j0m`@T3>1=RAWo3LI=vi~+*bolN`y0wiUz_q$r
znwR;pJSr_x(+=?bh2ZF%WP&R5+*b8LW&*cCE}%#lW`abpLn!(L8Oa}IPU7HsojP{6
zHN9ab#gq_5$U@?|?7kdanB}*2IZPUJ)bGk6Zs>Lk3oMhIY!N@ggy|hdG96a+cuX!T
zCYhAK6#dDt>(L{q%R6D^7gBfp8Z`NCFp1N0{Ahlf$+6(fOi5*KA?{s<f78UYpiGs8
zR7mRdNKM;V!@NBH0yM2I?e7s95<XvMsB!#3K4vjy?wuS;Wl=xUU9+#O;WRH(v!7dH
z_RAz^A>&gf6AMC3D@F?vQE5CGyx3ORah$fa*khC&TyIiTSzX1C{NnBMMzm5GQ|4}3
zv+$Y^2%oTcE#A9eMr{Ds`Z>rK=Y0i@mt%YdijW9ws4RB-T0!mW99&wO{YQy*lTL#L
zMZKXytJz2->5ml42GC(P)gdjtYGl-xpyFuKvH7~6Gbmy|d@iu&&`@HzRc(4NW!^<#
zD=`Y4J558wn<kuK(v8<K*mmh@$#{khw-FWP`ifynS)Kdo)3YODCG{NU;vBEBf|Lu;
zw|nDzPC<DVjZ=$RcjC0HdORtd_kKeaKkvsWAz0&%GDrCEmx^rCEs-ah4?JY-Y?Sz(
zx~UYraf657dV~f5+#sI>Cqe@SPCzFJ^4We_zVF3|J|FIlU%b~NJod?TH^98Ui^qNs
zw8K~9#+XmEc`G~JAhcNtI^D?!UCeGbn@^{T+E2c}&tuq~I8Gft7gmu}f1+5k=}Wa<
zEppzp*|5fLYHD1>`t;NA&zWX#eng0(Vv}Z+yW8oohGi`wW=|WfhuPh{yz;NxGfl3M
z1?Ck=ijLc&XVVu)=3U%_g{=^@^%HQ&K+0xGn9$Yn96!X^sL&5Ia<&2Gx7e{X%?X)V
zFJ<`{O%xUF=RnVSeV`-?E|x@^&hzXBUv#oR+<0*Iy?SjinSN3G`!Y>LuB(I4jZ=2f
z$6G$c-rEjG{<=r)dgfH@JqN`;6+;h+!o1KnE~RP9&<I4vCtX&U*3xIJKKK!D#)u*X
zh0h)z{5OeGMka(fSl1|}haLG8yzGv_`%PyXaW2@Z(taUT({B?!scjTC@g1H%-DbQk
z)Vtb?MVy;iHR8Tgk}_iDM@u7U@yb}*FX^E{@PzG{d6RAi!Pz&C_4%IUw|48G_kRkl
z^DXem)3sb(kLn#Mm&JEvW)10~#oy#(VPO%2?njq9VH>+S`Nbt1RgA|IjpaNw$AHm0
z6?vX(BlD|TH|tiIOGZjc_GsX;-t*~Y1CNB~aBH?aF5B2^mg&cA=R)$-r2T{r=A+6t
zfv=?=rerT(y05iolju_^&BC_A#G0Qa;Q^W&PObHJ5?vn}V|?D>L0wWFqghENRDB8*
zS4{|wdH*M+iaF5T!Txk~=!Zeq3t@av;FxuDb^X6WwzvtMO2G7fB1~xnhZl1Qw<vQ?
z^RH*QP<%A4{DL77qQU#1eS&|eI+EBttLDh0Ww8N+@yd-h-_>DgB5#YbZxj99%#o+j
zl?mKbYoi(Os&}hom)Z8FrA9&>P&MX-CyR&QOL|8AUp2>K`L2a5j}5hIIvX!BMCv%M
zFu9z2VVE6*voGG`aFnjKh7n{~oaI%N%Y!!lzV#OiGk)IM>1P9`jM^a~<-5*nBl1c@
z`e+yg<xke~h7PQLNK;1;!w>EmPraTRG<ZsOr!dc9w1d57o~UN`OV0YB)togn?I3X;
zfv8V*&aOaZSW(4}sA@zsVIpAi_Q@x`(DIDmk(hb8#HaZ7&J&Cg)^2P3oJi=L(CDgh
zA+BbV*RPBtlw%(c!k^fhc$2zKHGCkz8!WR{LnmtSJ{-s75>7|!y|H@7i%M`fzxu?$
zW&5Mwx`mK|`dg;U(*#FXo)(iICrcbI61(<e=nb?UYkBrvc)YMM(ZMs-(DQ);Go*Y_
zlGUj3VH^f6E{&G!)kejVME>UvRc#k@mxYt1yt2Hm52K^if}tnlpjpI5!|6bxrpyb*
z6i`FX1jLHVum|6{dr-^6E#bJLVFb|;;M-h9rb>?xHl(*xLRDlgK+>GyD43|=b_8-A
znikMv;^@9<Q~q*yUf-e6%_k=2p()?5=_dQplcljz<NozDn{F)M_d>@<4P(g|G)Aay
z^Rqi`V_0oB<G?h6I2LIl?#P0uu>FKC!I&lRb6lKpt)=}G6NJXfN35h>X5tOkIXq5+
zLh9BzYp%KlY@mJPW^7@U`USPeX=UZ*FZw+pS~P9vgJYIs-wc!EUDD#qd%ZEP;}t8`
zA9B~6bqkme45*eoeZ>Dw3YXRbBZMZ&g{^Ki4IR=Ur)o{j3NRBH_im|RK|z%=-1@6D
z6u5$vHPz{PG_Zr)l}BdBm~3ozgFiVB?rFN@30<}j+t(~s-eO-pFtRAO;vIiUtCVcU
zlHxeK8zysU=HA_^VIJcWFz-vXI6FFSX6msbf7k~YmLW{oM7J%p3v`!c1!ivkgXyR#
zM}ryKbzDps<CWEqBcW~23FnP6{-U2e-q%O=EbEPRCS7gTvS{K{ZE~A=M&F1hWM@Tx
z&XOR&eyl_ajf}~i=Tk-nY+pUjCPIxIfdhL@2FJ6q-m-p-R`Iijy7*dOmhR7cpMbU-
z;hikJ2|7niI-V?y&xH=8ZVmOcYI$66LMXTlMi?Ro)_#tg)vOo!Z8S`|SJA+^5_n8i
zw^d4pw4FOZquN(B(`iBLJx7yN`=Pe`E4p217^7LV9^<TtlQ7-bbxqe+imH##zQ>jG
z2&~RWZOH4KMsC#f2q)?B4m;}BY_w8s;DAaY4YlSnP;bl`R_**3lCnY=>nECWiq+9Y
zwk{cb3Zh?hX)^D@^S~m^?XV~;OQ9&JN1$g=$Fgo3OP5T`I-slH<@qCFrxAe{`~G^0
zmlh_)BI7nn+oVpiQdhC00;|V!c@72I_D%2aA07f9uUue5uR!RkmYbV*EYD&5l?bKK
zsDV;~0h%z?+n6i9MN@FN0566F0jrT&={KMfTCY<L2Ysl_cXmI#aaZWBIf%mXEY3&S
z)FFuIVT?f(-|uGvKOr&_`4|t=76r-?`BP+GhPj&iN*&m@_8*T#wgk_b%_~Ocm4u5v
zwMuE&#XNiKkiUL7v31=B`8G~sm9T^IQ|88p59`4|N9E)<OrGv<nvYqOJ=?yKt12{F
z;b3_-0gg>c0<K>Q70(Zz@t0_4Ys~~>BEbG%$E7wB_r+T~<uedMm$zp4Xk=9ALhJG)
zpBA{bH${Ybf5{2myf_<kiDDUx71%P{61=e8OhQl+`Fcu(<KBRHeFcodiE;%%lJBot
z=g<8aKi}~2im+TME^h|t&TKi0#ll4ESY|4+a8g`KizP&xH^vzvCw>Zm&K>-eRNgb{
zK-$(Pt2Zaf(oUBR2cD!wT)7O0HVpaL!7?5Zzi)o@77z)he+coS0UJJN%<wK#6kHSQ
z(02V-9fqWh*glE7LeZjkCC5=H>CvMbNB(-?j|*+0w5=J3oXTC{gzS8pxKDKA)xx18
zLYL|)r6FUFt{lQd*m>eGA+pl!PyU+<5n)t?NEqMH`K>u;YA&eq-cMz(b@1|HDvi)P
z;=q-~MK1}(M~8e)e>t@K_|G++*~MGIAW6YV^Aewf3S48>QZyL~g?z5?A6j<&b4|Ku
z@t8A!to{;@=9k(6K$}UwLUsZ$na)DPrBp%yRg7eiMb(?x(R~zyFaN1m0}2Jzcwihr
zZb3mmoC^HRQ+fl}YZ;`)dW$kL=D}x2k%7`b*yMJQT4{&<*Z3Y#dopWxob6f-Ub_-X
zQ09&N4K4Y*ufhMTkB5V_<_o=YJy|Qpy(NdMqm_QQ7TKgIfc*PivI~&q8KG~xKAxgV
zc6sd&H1~#KjQH6b8=Z0+%lD$@je571x-<^=a-UnRCvo<p6riq3_ERZ9Qwl6bzX)@%
z6)vAk7)TG2M@}Z~<hyZhMWqd^nmzBOJbOTTaRzXRLellNpW`JY-=<BHv)slZeg7H5
z_nQYO&$zljkEsmaD{F3)O%D6r;qf{xRtpn?crxiFhwHAG9>{b=l2$x8)H=NK6~^N!
z)i>H^xuDiA7{iu%#K;;%wp8DfZ0?&VL0Te#Eruj&`tfKLG+qE2ZYf&`V5J;M?|lJ)
zX-VW4tfBV7h$e$Sg@Oiocqwj{W}vRg{)uHkJt_MSysZyhEG)P0tN^@j1{=*U=BI!^
z72ZX8ciaZtloQc)Xr=!gDJRJekMiZA8sXtw=6}Kw=&ZDF)AS8*sc)S4AQr)t32(b{
z_)|b_0eHxc${BwgBzFCkdeiblkwQ2!MR(pb*D*3g-UyKG<!6l~Itb3rl2HB%JJu7?
z#FQzn9nsJNoVj{?oI1AvC=MM4wW$Ls<oB=!pB6VeHYN*Dh3nIX6-Q9{ft&CTg!MZZ
zZ}hu>7{ud0UE)iQR>8sySlMXE$~+iiJf7q!-X16NnZFtnh||sqWrJ`~V%*58^3;_M
zq#zgUYOLfk;-A1qNItn9f!lD6Tn|^l1xlljIZtqHPo^=OB?6a*ae|?7MJ9IiJ{enS
zSLe82)f=aY!G~>U)~=gXN9)qhHp;%#-=!=3TxT*+@jWc;%jf{!u9PJMVrQ7B$`SC!
z&eLnxXuz0gzDR_ka^;0KuWdV3nV3zTvwid|Lhov5?Jyv;uy%!Eg8;#Lj~_AZ3FI(U
zCZiHS&50b8mz{{TD0;aV*RTU7pQIf{zVXd)x(^Ru{NacO<pxyd7VX7_x&hU5nxQmh
z4!$t&D08t?k(r!0*&MyAG4Rp;Vt?ygkc|0JbFilZL(7(UDk|g6{ZQKniGpiC9NfPF
z@|;AW`Ux`C`toX0*F~6<=sx>Ms7c#)k~&1V(sDuj3`TeGVJ2X0OkSlC!cM_J_d8Q2
z$G{h(RzU}<cG+6`5}A5kNsP|AHIw4I%Y<TSlAsPkQF2xc35PR7VAQ|>P~Ql+F$6x%
zlmg{sY-<KvYGmZ5K*9EKa--f7O8Hc~GU{N1u|>-*aX*5!s0rody%_L145%ny`*^5q
z0g&ykiZ6@p0La+t8GGbiP>7^#vfvg*1=-PR=)J4qoiJ8mrXhgPV(L}8TD--C>A!`g
zaEPi<{nROL4JQXQdXGf|{-wz&ckfO=3O94qsF4duW_hkn6Buy0zB6bKV=Tb>VWa@&
zr4Zw-hqwnIk6(Xm1DW4ZFEij@`z~{!E6)1)>#9k>W%edZZ%V_(;38QiJlr74YY=V(
z)TQyYpil5+0L||sb2{AsR%k`6XRD@KnX^RS;Gn;OOT&<v)|!?!E&qdxMzxB9ipqXB
zkz2B$tcN8Qbk>0=vI<ms`=1a+AYj99zfo@kjlT1|LjAeg>ohiI4V|%v$2SUvi5nWr
zo)8U?7JLbr)JfY_78)oo*dbSBx(*58Ch^CC2sd|9gB&I_*V8eZh(8oqocF|vpn^de
zE71L&e1+Xg`Yz`V+%*b+wEUu9IHD${)a`7*rJ?%vZj_FFm^chm59vt~jvLqx-v#A4
z^Ez|X(*B<F>I0W;DtQ?y@yp)=)58J-EzT%CUdZD@`#gF(5CGCEW6z|I<Oeji&NaEz
z6+`Y8Sama;Pc)ocIBEz&BW>a-G?W1QCpY%rg?#{A@Zo1#9w-|2kC6+PrUJK9nbe|r
zIfE;l6OGWlw81jf&1UVzf-hpH9lKy4zbru^Ll63)$b5RIukHkvX!naDYq}^>?z3(3
zoCI<=mo2>*bPOqaf>G?*=nK>bvp+zR`?r0GumK$N3iQN5wLYNHpchA=j-n)&gE9fb
z$>^h~)&ySG6hQ=s=AiCE`wwP)e<K<Enw%rOiE5@Y$R^<qhg*ml5*?$AZZ6ex0`Tn*
z&=Cg(Ox2aw!-O$3V$0l%hRLA}1!hA2TR{G|3`_`^D!5SLIwl`5?tHh1So6Uy?jEZk
z_*GCXY&;Kq=BoLhBN|EXEPA4vzVv^MI0TB|D}VzFf;kJ8OZX!1fhC2B%clAOqWBc9
z+~xz*;8TW*y#$i*RnOBC0DS$u=_6(-0YE6~D++~ebI?BV5PUknYbSu3HND2?1ER}!
zm)aQB+D7635BvX9`+tu~5V4+uZaXTQLe)b?jGY{@3x~5C+*{+Wj!#Kb*m(ja=Qsg>
z>Hms<awrZ|pr1gUSSrfTB4nqeqJzsLU*m6`bS~|_Uig-Zb8#>}SJhM?jegxY;5kH~
zh!8GNhKM=`_n!<z6Y2vo>L|=c$7PN69Iv*Mrx9@<_n#(k-$ok&=Ocb_*xy>&Dsxj&
zxc%faqyEZBr0ZqZlDYV9G9eI!2(fS}l>WHW`90Md$mhIjFJ~*UJknykl1|5UNAiY$
zx>(xlVz5aT75RN4qMxu`=EA~vd8fnO_&awv+WVK37J{lc<|q4vPE2-kZdDOKxC2D)
zj#8TFO8|fS>iX{@M}wXrOTotaSt9d={&UMR{RidwvDxqMuyf#de{ywR>SxyK=YfE`
zA$rxfK%um<*$PD^$~nq1i7=H!I6&f6SL7Z~f@YgdJRDm5BSr@j71lz|r!q8x?w-*K
z-U-u3gyFF8l{9sr4T>@ir;`DNlD|miW45>2q(%}>Og@wC$k=10%zVLmV!bI}RrV%m
zLj&t-2Y7{FKjqAVtG~r0LR^5_a?GXVkE@6F*<R1~SvKjAQchcv`(mz<B6N&PXN+AX
z>H^Dv-1#7uN(WYq?%oISR08ly+FvUrpvz1Kn`i_8&DbEAPWLi4K<U3j>l(21vqemt
zKzA-)`w!juRVmOUM&g}>N3e$&IUQCTH3X|IQU*>Atjax>fBYPO&;5HCtC#^aCPQ3|
z9yLe27H*c08UDv(P(@Y~nO$B!pzGx@7joTwEL?L%k#d>zmJDJnd<C2$JD_OoWP9<U
zDAbm-kJ3;c_#&?t-NkAjH{jCwytlw?!o$|%jVwKIZc^}}L}rvkm{3zdAO-CIP|w2&
zH*V8`hO~#PAMJhgE-2{`hl?B(3xK0LvSNc7bpcgczjZkpVft^(u0jrX3e56Y7<D|(
z?5qrB;PA1%xOG>c)?J6f)^UKczoESR!#BY5__onay3h5+&%UDC&lH@<m)C<g*RM*J
zzXQX?zFWKZiUCoNqmC5-s`=aw9s2zDU!J9Bg)#E7iXvTmbc!n!fsNCmE%t8wZ65w|
zPC{(*Z8U16e#S%^a-`tlSN3r95X`rX(E)e7;iS_aRR^^G>#YK!kR1flI%Xn(w^d})
zWivQHsKxYz-|6CD2qTAyO6YVUkEJKMy+Wx$D<;ZC{%AhuTfqkhnjJhCBfX{=8K^pD
zb;rKei0ZQ;9@B0G8ek}ICT8np5Ji~?3_YM9_#RN+KS1oZf9<?)FSDt@Qn)sLol_E~
z_oD3B4YL%id#Pbt0$c`lu(a=oP$-x&@UIx71O2}T1j-()^`<1?+Nh}R*O@%if8d*6
zKCWFW#J!%e@d~qD#q5D6(iD)~)V3DW%N8bvBeVRY?MnJ(-En769L5+svk*=v&TiM7
z<>2|?)%Zoq&lMsLRMjxya&UF;UCmSRObI4QS`yNWwH+N6s>77SfbokA7l;3Fd%()3
z`s31hKnKwo?a=p?xTRAt<Ox)-lsznMIZoEc*Q@)Y9&YuWf_BI`j-xxO#mWa?JTB5{
zFP2?oRdU$+Imfogv7wxJv<(Datw8g%wmU+gD_B0H;h>$i3hJcUmuS6L+gICuB8ili
z>Go?Eli(2LxzAP!53=VMzIBpu9_d+ZuV$ADx?ieaUUp3-_+)H61cLR+*AUtO+JySC
zabWr{aYoiW0h*)tYd9%P3QL_VJbIw-itc@U{E2p4dL-xNS+(0-*^str%<S@Daqot%
z1MNgireU*qQEp*w7%9Y<d&98<6D*+&oeTr0?v#nu*MD3E9ICG>wze_)Dk_6#cKzB1
zV&!CP9M=o(vU7azCsV>`pdpEkR8@zEf8z2#j0HR!`$d!;b(eL{t+@_R*Wah~T>71)
zn${QZ!t{pCYDqJd7q-#qOV3*uGSjB@2hbrahLe4!<lueep%Pw=jKE3RgF;bt4)}qL
z^y!?Or)y7MeRk3Q)aBnsuoTuxt`!kas)5eZvR6=Z`HbhP-{9mMhdZ6eNvF<3zjKhC
zyF=@`?KNI$B@T`c4(i^)yyg`G9`=La-<>f};4m4p|IAJ_vYunRJ=aiRUY%&Vf(Ay5
zVRyO?!Y3<o;YW0ZDBRx&1cHjNV@Ps_&q|FoF$er`W_6fQRsH5R7s9L8|4A{|ll(nZ
z#!tZXeTfv7$W$Oo8SJd1qN%{mlnL8jspj^YI$z}V<_Ir>_EFMt90J?5LMW_dh-$!5
z--3G&16+sy?2aWari>GJk8um8%%cIlJA+`*gSW+m;qSrz;nfSrzcjQON}qy?CqUuf
z+Vw5?<LyVr$70|iV#Bs1U>HQytPr|FFo{>7(INyasAz<Y73hlOBRhkt)v9uyw*Z|G
zU)PDvV?YQ+k?*hn+5AX#gT_!kpaRbku&AS10It_d@W;zrSkb6Ph;SY)bReiOX*nb&
zs@d9mT=*L>FssLm%9=p+y;61rkrT&!nko%&m3jgEMAY-H`VUAJ7;e@(h7B+bA5diW
zZ;w`oVEINOv49fBde#5z4H*8L446+Nh%5MXT>FdU^xr^HDxCS9Az<sJ)rcB9@Ogk8
zLHm0b^ajk(>IGjPDv0<V6Yh^{h|w0?4#$)N+m!#KVNd1~sQiru_<wW?|CbLNIEuB7
zJ7U`PuKY2_{aH%-#>U34Yb@(eq+;XZ)I7F2qFAiY4mUpEH-3x{#3}IwSKmHh#{C~F
zgwPPcG9eK=Zz0ek7~{8}s;a8<CwoiY`BIXfh{$}HBuP#;&>$;uB6Ul^BzDx)2eT6c
z=3;(#$BeuPHs6{=WxY4k_4z@C`2;g+-(BvqcfhN^wwRaGP@%s^+S@R+=ybR~GF?_x
zRn^o3PH`TXUTV0y*fRgR6Z$`MABC$90?rRMb<)MC+dE@F)&>VEFtOXc%X}g0w7=Z@
zQeYTVkz>3qo*XR9_NI4a07GKXeBg`x=MNDuKljRhQ(kB?dPYaPgZUV@QN8J6O-jW^
z<iodVY%I5#tF5h%HnqA_A9y9F-i1b9<J7tVqJ*sF`?%vMp!L(T_A>g%fu3e6J0?t$
zYLE7ZEbA@@U*^PNf6u^RE!yiLfWFQm)r&-RI&JvCnT87pNkLlXNk@lRBda1J*5ZCb
zM}hf0)_hGaAU|?>@NRcZ#u)|%M7Hfi@^|1UN2}RLtpi;!TWFMV2UDg*Hq~$TnZzeq
z*)lonrS6;YNl6QWvRpsPG#C(NPkP~hFBBBk2mGBruB^6AFvU&W9CHmzOBap(+>Q(m
zyOp|IK|w)p!)=#@C?OE6&L|@|IV#>o`;Q;^JKkleobA7SJK!?+HRok^__7<5*~n@u
zEo7xNtb(o(m~)?#zqK^IB!F4+-&2&a?HsIgIhv=vI>yi$HThq9jz^a@0#i40gL5nN
z<t?p-NQiv&bn7u?YEIfT;MqXIeHIVkfiDC7*=GY;t_PYjgQPr_W2MP{BEQVAExD;@
zPG__)i0D9BLW}NXx07Q5bi)=sJEF#g>}U#ESAeSRB5k@|Z%=>VPojkZt>*HqUwp&+
zuEtan!-$NGTmv;Bq=?s};}$L84B;|8MhZYQPIik{adG52nZx$TRD}3O6uV4rx!FX6
zM?<y?@Fmao;&3m3E<PU&{ec4_o;Ot1gM9-%kJ%Qp!*d<@U$der7A}EvdIlWL<Ig1V
zq@VztwemRBFVvHdebV8xnnwBU`|-8}0X#QjBHz7xcSltY^hex_BOC^6Fr0@MFZw5j
z@Go!D1$dLaXq!DLB5_q!{D89~9Epkl=guTe43W^U{2a!$yl9nPyKfoQO?8pPBqZ`W
zGh)aOJ?N93NG&jBE#*>gB%n(;%}l@DABXOFZ8i~SiJieS85I@giE&}$!rQk_vlCSs
z25aPjn!xbTv2+^h!Dw@ZhrhQC&;kLCjD3p6V=Z70G@}C;+kgR82#|$+At4shNqd`?
z!|a_>VWDB8B&+o{CPQT-XCUTaUaDc4d*fuJ$DKKW*OK()cic<CRQTe^!|vHUOGDyh
zC@K6F@TirM5fo{^WAl`;d{9_M%NIY25_d{<S}n<u)6qe-hDpJ5yNQ@+#0UZ*dXESO
zO-I>jG?+8vn>pY1@$plv^RtGaW!gqMgb-;!z6My_7wL1~d||g=eb#<z{CtZ#aMEsf
zaLrP2V<zkB{OL%k@zZUR@E#GeDmRyl&7(~cu(369e&Fc|Xyd=O8&S&*jd`ruAbcZe
z)v(LP-u^hfqofc~Y)%F3^Pw=`_{*{XKzs~BZI7;#ab4Gj@Y^fQ6L=WK_FP^RjOL`S
z57Tj;a((R!X30APHhW(Ojq{Dn^y<Jz&Fsg^J?UwL)_j;UG9OyxfEtxmOuQ5$Dr7|1
zwPuPHyBs}MP*L9>+NuRW>`^2F)u&3x#@SX1sm7hJNg?NZIc`gm-uZ?woPFQ1!V;|R
z6iMn8JFFI~J)=mKjp;VysrQDKmH}+b7kD*38M3)|FtguiR`1I_<awA*=+cNOWA?Qr
z3`98tWaEa5umI8_iu@THV@!0R8{44*{pD{bG0hRWw^!gJ{w-Z;hMeO%RQY`077w@t
zTJ^J0J<pJ>I2r-%P2Tidb!x67kZ{m9DH8L+#4!DvwZX>^yHjW_@`_Ip2vs(5Z9Bjy
zcDH(4Z+j`j^r9OqMjl%09ivecJ>=SJ$ANUDhX$uzhiI)lo+)I%nJzAhG`SJWYyfnp
zfxP%@Zp`Rgh;;RRcujsFf`OYEN0AaNEhWPox+RQVhepmX-_g+p4!0y>m;$~z=3Wz*
zS0B2brc@{`EjE_U;I3fK#(b#f@MrXR7-OnN?w5hkXq`N4J|EFrFvbT@W-|eOGBOl(
zK7!Xp1*qoG)4G#?;M<Wyr8iVI6xynb>C@r{R@0Ac68YzB%5;^TKzfG7oUU06iOp*J
zsaXQa!=7u=+xLucBJEpTDd&YBVzv<Usd|Hz6x#R>r<sJHE{h=x1Jd#N!$Jr;gtcIi
zKLoS`R8thH)DFNLD_Omt9)k(}dgqNI^4r|6&!ur_pJ2ZKjOb$k5eE~HI(~C4yxuEj
z2Kug%m_x7-FTULjbFj^MwmJJG1`A>(_)1m_cyV69i<3E9rK8^%iP>d_D$8YZQ5dq$
zdU@(`zQUmew;jXY2)n{ETp)xIo47V1ATsk}<VS0!U+002UUGxcz$eCB&(e>r0;*uW
zRBwyYn1fIAY(;nJ3jHKLI!-PI&guj@O#+EsR90WL=<Du4&&uiyPnd(F&n*%t(Odfa
zr+{wzlF9DkKs>}AyOM|#<gBUPCZNTqiZc=hBo<zabsGfO-OC`kt6v$wJ!Y*sy=)8h
zJT7?E!2ld?6@a9l@fbVW2qI3&76z{uUR6<vb+)OpsQ8e;W-?5S5#)If<L~G#VR)qt
z(t$VI|BauFX18iO1K_r&kF^KfA8Q>v-nnI0GmsI<fIz?S4xf2U7>*nC;%7K$<Na;0
z6W6W+t>R0Yp?Mw#tmTCycGuGS$V`e);p)x>7SQsi1QN{6Qb<l#y^o;DeILo?bkmIf
z*IeHW-AM-}l&syV_0T%_>9I3!@9mUbOpo{|LzMMbu!idfkkuO<&Q|;3)pD3QbO(-3
zmhU_r3sUFK`Pc5(IbyckN|hD@ucAnUiZcONt@!R+QaBTVc{TL=QFVeRz}oEQ<&8wF
zT&bi8@{b>Nl-vi_mtyv>jRiOcg%@Mr%s&~!ZL99mI(4ZMX!J_g0AZ==){q&|y|p3H
zr=U7h*^kH^wTZ}8^{rh6Yq9z`a7^kdb$7U^(hXjRvVbDvLF)%!-_2ycrG8ML;|>~M
zvAq}tKFDwm7R3P2R=*5MN-~p)2d+F`%Bw1TU(sbiti+Rz%momeRhc|>gk|7yPZohZ
zOOZ0xt`RWb#^QIo1ze8s39?I=*zl)>)94Xyk2$iH>a7RzhB0M$-D@W}04M8Q?oWmQ
z8y}*xTyY|&YLs@-Dvmr|NU_^;o)nLJWN27IWALkq4)J7%NRSgylJn(PX<#ZPzKuQP
zTM~Pb&UHW!ef@>{GU~Ghx7x{YL&_eF7F(dFEmQm1-?=zc??f%ERu>%+1Dj3F+GB}O
zun!FAsjQ^gFMNO5>6Hcg$Y%(M)9-`*%u1M$kOP>ltsyxV)URK+FNBr~b!|4y{x0I8
zk3{LOZSxACX&-@uGai^JR`Y#>8$yZh3xVy28~0u4>~R4(algE46?C>ej=@fT16JhC
zoq%Xm54~i5AzwgLA6*JAA|j$Fi&{Vm!E#ASDdE{@@S^6JY-7OW#(e$q)Zii1`S;US
z$%<{6e0ug<Q>j>(p+tVBPo6}CIW9<{Hlx<A;3C)7eK@L7f0%i2y9{{m&TD#*^CTst
zIPupofHAV`q_qKpwJgZ*|6vVX32Cv{k3)!w!RyNWv)iT5IYE+?qF?;4^u{0R@PQLM
zz{6&A=@B#Wq=bYgGEc$7@C=;;z>NPj&bDQAtN>ANGX)Th?V(Sjqh0wP?3tmfs5AqJ
zJ`+!L9|e)PxkfIuF?rYe;$g~iNE43)xES^g`dWoIF@=xLdQky_#=|M`I|`Ei+s)(A
z<^+s%U)dkucspPcf1AD`&{N`i;!{TpJ|!K+-<A&-tQ9JTxdL9Z65qD`glT^DSwwt1
zd2hf72<rC5YQEZ95ve^pBI7YaYnDXf-tfBd;*Sd;i3S`6G)c_puMrINOWo+$QtuI9
zg%IR>_||i+kA)W(cWJV|_0l0g1GYzh#W1_+fw%wq+31prtV~&EtsCPcF350UiQb<h
z-`k^i4#zoJ&T2==&<Zy$m@uw%+CCuDil565?Vc1eepfyNf|h(B<Dccf{IuU{5IGNo
zDgC|u_z#Xc8m`l>qA#}8S=aU#0dm0^^4P0E=dRLj)x>2`*l(A?2ym})Pblvn7s8vI
zV)-WBDMrp#EiuEx`)fePS0iud-qfire)0y^B6YJp4J<*%P2R~rIXOS_=gV<L`C37Q
z@$dgkj^x)Pf}}N(M8OL{pVI;e#oyt<KmUvVz~zgkiQ3#BMrkU^vY+Bhw`ogCB=N@9
zUlPJgGU-5XH+VQ@xY27s_t)hQnuz8eJKu{AL8AkE#)T6xyUn?ubP@7#yVU7zPv}6(
z_phkO^dALwV7(+LBlPJ03p&L8?1v#8RRk{Yfd4(<6TAwBvs#jtDFocFx(_Yw{(Inx
zM_~b;3Wh2YK^hgl8U>YG&8k&|aE${*f&mzWL9LNF$oRg_p}AkeZznfD-|=1u?gHX7
zUlYmU)Aa-i#1Kf)bF$(ufO$T*1*q}>=HXc*Vq@FH2#~b5)&%EdTSnEn?ML{JiiG`n
zZTJ&6AYyK+rKRAWBDJXZ6o8S_bRbFb0V6m?Y~Z&U8_^2w6%kv(KTi`=JpclHz}Nd7
zB->jIv|bz7omaN6^xt<u@Ib#(lf(JmASL2%I+=lmG8=rCy9%O7t5#_-ieQ#q)h*qD
zdFn-21al=&aD;1zc6Tz#ld+|u|F91Jr1oIk_NK&KT=jt@QJXnHg-~`cI?v>&Ey{7;
zr-QXfC$(DxUFj45SM&*>|8vwQjt88mz^00|nMadvIXxR-cppYEfg!a6<q@f)m=J7a
zuR5RP@S#?8j2RG<xs=n`<={*E<wZO$^WH1aU7Cz<Z>9(u>Ey*lON08z!rht{jR+#^
zG=SUeW6CI0x4tgO^*0-BNuq82Ui|9e@07|KpO-omL{lHp2)UKgZ7+~@TD$BVw(!XJ
z#Ln+o3TM594}%TvSJ({Fxt1T5x;5q8eTPFY9r|7&B!d}Ps`sSHSS>{1<O<sPwb3A^
zp69Ert{tA$lY$TM@s<s-nM?BCI#YiVUac}-?^^-+Te17ZA5zPNVcY}(szJ^9larYw
zS{s{1WrmL^*HZzn2lg7PJ+Df`+F@nW*QnfVk{-2jZ{az0v8=x|U@1-iYJJsvA)3pv
zSWkX_zLKOQ@NH2aAjRNRcFO`mdrOk|w3`A!=cm%h-JF$bhS^pdk8e`Q^MT-C9YTL5
zM9TQ7#HI65f#?&<v1&zw^4e<Xb9DVRQw<C^T=zPs<F$&4I;|R=iR*{+Bg7|%D;3_)
zqR+y%N)B>(>Mp715f?*^V%NvRX|k|UHefNW`1DmiV;PYc3iT231ey%XVErnmuA;2+
z_zOwg!yL9A9bvMVsH!#_?`Op2cHEgMpM+5S<EMRm$MX0#9Z<v{g4<X9I*Jt(u_5t+
z{?~o6=I<c-3)S8#=Vh#qmdo#NnU58lPpCbUvlWQTk3HX*oZ>U(#Iv5Cl19>_+23$)
z!zZj0F<%^@|D3*V{wdINI9L8>uKERLAeZqy7$d92LmY)vJ;(^AJ`=-j7UxHqFGMLk
zq<i8~;qy&b7sG8yj_z1ka_ZBsbO>W7jjfPp;e{k($gjH(C_)AZqVzw<+<+?M5QhY#
z)EAkQn)GdoC!)`l<i0#3Dz_Lg94lu+sr2NnmD~Q>k1E|<lIP@wZo?S4cUmrrP9w-2
zr#Io@jYzCGkPPg@tB~`*1dyJ-xSD;zj%F5uh0ZFDg$9c&wF-QvGZ(Ok%q@HnRnf0q
zSTIIv`KSo>i+j&wM`h_yF_fRECU|B~_T@Ee4D9jhTQYN)qUzhZtHr*?=2@H*hFhFl
zyJ|G}+wB>IGRTWC16#D0A+$N(QAaE5g|UeX!NQGxBMZcH$7*fWU#=thrVI0=IcFuI
z`%L-y7VlLjizihq8pIegH+*p%hv?H!R1BUu{moicNAUwWY>2T>P%Daojd3`u#gxs*
zD0`-ROQgNUH-@$};|fR{<PuU#CgE^HboprZ9K<Um1L76mhu~tvp6$jPVLCvCOpQiV
zVM6=1?qvVQ4aMl46E~j5<b7NC)<jk=?6OTE#;M8<%a}SbtvX^;lQ`TcN&I**4gwq8
zCNVPuIrQK#NavV1T%eS2NxW75?5u)L-?|%{7V4Xhu{${|)p&OjOVj$ypB;lXiT%BH
z+uj(G?Ao?MK9f<>NM{bwL>T@}qAFX~M`mfCfT!~>U%)q5-R+gUnzV}CAaNu{80`%w
zUl;_7e{44>Q$S(TiKW3Rladhh^tAozzTaPST4zG@`|JqrJ5Df=pIcQTCc3F8i;Az*
zFIujeoiJMR&Z68%<|$zp)%jzqsLv59;y@pZzXXSm0Po>hXlqCCq$uYKZou_i3)2)A
zK^ABJ*}6=Zkwhj@B&AY(n)dWP=L%~E#KdvDYeMr9b7$XeRuE+R$NNAUtN4vdf75dv
zQyqxOj|Pe8TpH_!lkHD;gtc&^Wk1|Q>D^?P-n>m(_hl#8#RBlf+l1wMsD;DcmQ|!;
z%2+P1@S&Q2Uz3=lQ;{+#?{?j4Jv_*e@JoB0R#CAQ*m1sFyL>{Flf#VZztdre5W-Kd
z;DAE=l9M`k!)Qo)<*gle0ZL{5Nt?1XI4bP9lNKvQZlvqc%9Pw=9wK6<%&{tPtU)=5
z(Hz-os2ya~kAPDhZ7z9k9*idfS5$E-4XA+;>gmP3TI@j2`DZ<SQr@1?syiWV8UX?B
z_?3~7t6PduQ9JF`kpR0C_}wU>pyA?0Y%)iltkKGd@&?rmA$-yDCUiVl+pljFv?vj<
zV4kXWeJ&A)=Clg}T=P#miKM~VnCb_Ix`WS%Nh0$K@YEjf_x7NzrN33as5=xYb=^}s
zlh}0c+g*qla{nFRiPmkCxZL*Jobi9@eQm68bN~V|ZtI%YFl*p^9{UJLVbb=Fbq_E=
z$vEN0M+0AExob@%^=&I-DuWq}m^cCIh>LZ+aM*Vs5$J@(_z~V=cm47QdBozV@XlYp
z9pc>}NLUO|YFTj<<K;MY5CW8*LVeRATa^Av;tgmY1s%j0?DO|AQ}P9Xm+_F{4l@|a
zhd4@zarcjTDwaq7iTt{p+>xsw-?DNoOw9!qt<i=OE&u+%pixat6`R`DkB$LxbNadS
z!NrkezD`9nVU-V9EuU1GU{ogAEh1|Q4yFOW(HYQ`>C<Hr;`v}szxW_egTBTg0T{Q3
zK-WEl&L8}ZunGkihhD>Rxj43p=+DBTvh|yxM?K%^;469rgLJN*I1L@pEOf?1Y}~-6
z_SsSgbp{o0+rH{D^=@c5U)|ymzPQv8QFp#qS(T8b07N0)&QieS!h1S_cdTA((gpN<
z<`%J)k%+r=+y#<3uht(ar6-9LyVuZQ>w#bZ*;`4EJf(vp6-^Zb$6c^-2OM)FJwA!V
zX({Q3(8(4WWJgDQX0L|ghE)<BK!psJ`$Q~&0M+WVyiyf5wwToOsoARmrzD;~CU_Qc
zQ@Bl|K?dbMF>6d#(iJ-tbo`RJ{YN6i_N7uE0E1DQpPU`8B4WEn_PTHESMI?5-*!L>
zbJ_mbW(leMd+QoG!;^S*Pc!k_XF3D~L6ioLiD<XouYO@|xiX1Vu;7>^?M_lKjQxU+
z(jLMW%e0s}HL*R8uR~!VoW(1;o-QqE+Y!d11W1x>cUNBp1exW+<gwV8Hu&t_a6sm<
z@W;{8qC~kRht0a86j-N^`h^?GLiEnd0snqerQF(T`^y-;nZuWBq&iF3ZT59wa;~lX
zhmCHCgD-)ezvlFc2hMBTLvJ!aW%!H)>xo2Q^`jaC(b$9RKI>=qZIb-$T*B~e1$lqR
z)#&z)D5l`jF>;hyadtZc8<>kT7e%jb2Edc_Xw0rEV8AN1Q#iu68F^_Z_1-aFa|X(!
z1uDLL73X$t<%MR+r-wp@$ajgH%19_CumB4nQ(t!X73hEL@hl&|tVBP@4G$iExGv`&
zg@d*Bj25`P9eQl|sR?)Fe`dhLQ~9uBL7($T^5g3hc;zN{aVyNMvg@?9eq;a2Vy|KJ
zX7ymh^d2&l+{LGcS6P2Eb7mw3v00*P^mNXEh4y{jP1<hLS3k>nI4*qf4oZbUppy#y
z3_rN)I^4jyai{+trvKbmi_v*LC*=a5ls~@<kdgvCEQP}r8|(fgXY|Xv@Y=WDp2zPS
zNJ|85q~?e32gQ$cU_pwW21&)gL33u%w4h=@SjbDy(u4jsiPr&6D2_3<S|10TyytOO
z&+WHsP0Cr6fChbC!9!)xN>-Rin*VC_-_5|I4i!V0{WmVGN8t!W(kF#pjy<N_l?7?!
zCoayB+4bjy+-AwOU{Fp&yhmWyccSWeUVaGB2E}Ll9MH(E^AMrpIu}W>W10xsItF;a
z(;Y1BtaqmGd7yo8@-9VSDivZFoH^5#)7Y4Tl*lkDDqP&)@Pe3<h@<a;A%eLEUY_cC
zKcZ`Yo5c>}-3+Y+5RaiE!NUUz0GBk=FIq*6G?wf-XPR<a!(rj;w*ZFooO3l&X~#lS
z0oJmjw?tg~2xsV?`EL+V0+7r1xBWWw_RRu>Pf7BddZsSQ0t552_fLS%={uU@O_`NM
zp7+dRF$`BdmDu>ef{F%D9(1|cV#;iigo+4X(5sb&n4X;E=!AWji;-L|u%koltR>hG
zU}A!Ean2X<!(G2uyHvEhYy~WTEZbQUxfIvyB#oH5x;zrSe!ix2^}_vfFQqd{z(LR5
zz24@>yLadyefK<%kAOxndmvQm1UT)xpEHLdRM>7u?b4Ec*x?bmTItc>6EP<}(RlB1
z^<CqN86aH0dt7F<dt4nIx%7)Xu65UvXn4~Rh2ixyOX5-T58XTWrJ6`{$yJC!A6_D4
z==isp=4Os~MWV2FtpuEg(o)7SS`qE2A;u;OvUp}9J&Wmh79USN?U%k}iJpP}$y>h&
zx_)$DCs1lcVKhSkln0ANH#^^Af~Z%7duc}&`EG7j(u6$68E{k%*Xhsz*KH1e`CRPU
zz#z{SLj{5pqMu`>N{Q_bu2o^U5K&}t!knhqaz%!8sDGls67Q8J7i~;LuTB^?jz;?j
zHCkXdf_V}5<d8jt%W53_dn=aO)Pj8H%~Hu7Fm;F(9~T_%CrM0bA$9P)VkcKx?b+)2
z!>}h6ROryYP%29RVrx9vqn8f*+Cl}nOz6S(uizKp)`98WrnkYfUx!yYJ(ciSWDRPR
z8f$FrsbA(Nzi_D%#FSx=(W7=Fp5C3QXZu;}0fPbDm1%H;)k(2G`^L^OU8DA6k+S0G
zm5k<-wIr?QmO;an*D|STK^YT|+kyhJ;^oFjv+5lsZYh8aSK2F6%|DlwxvOA6x$>p0
z+0USlju2CU5iYJW={Sc6k|R;5GpcdL+=lYCcAGG0VF8kGOh<-PjJ|`H55qvL6B9bC
z`-!KW2q3RJkx%i{C~iSnk>GIGH;<58SWZ`NOWwC`xq&fuSX2WSPVS4xYrFOL1&JNt
zICOB-^g7`*{yi7&kz468$_oXZ*RBy?mz5AzA<;Sc^dq+5WoE|BYz`PByj|keK3Cw`
zA=7HG1p=JAjYMcbo$-BeurH#?AkQ0AG5u4VYCo_-XLA4;tiU<qF6!+092ihuy;q;M
zkAZmx5o80Ct~-R`A5w!Kh$Dk<ynTRr5FfDc$F~tspk+Q3JuQ|*y2cPgcAjw*zXQh}
zqf&CO%Q&O<P#Ah0E>cLx7j1CJ(t_SS)X@JZ!un@zfCPOev+8aEB=DS=_(U==3T-_c
zFh~@{qQyjC9b)`~0{<f~lR>Hw^mQsGo-)W=G^Vkl#)z2<_V_#8{OXWb=q*FRNs)KK
z-HHD`2RL}>EA$Lw)MMm+AYEWBNJ7dCPtOOQl20*Fgno(67{%X+jmd_HS6G<22S&Oe
zfpi@RGNS{JS7&O(_8<6O2<<E7%=LWm-yK3BG_r&GCAtquxWXrJ04@zqz;A@2ICyrU
zv?mE1wLA=91$Vf0v-CQ#{R^z=f8*s)MEDb1Hn7%4@quY8J>vNQNaTD;#Jvud7ikG(
zaPnuxDmjp(7mCz597TWA^IzjDGz@EB&mCBAHw6Kkx1M?jO6VvOWIYN<6kK65{Jjv@
zATBT-^Wr#S3Pt8ZUBC8bzn{;;uIV&c^YMb|N(wkWo}ZP};g9;g?3f_)1VrKT$fpg%
z>*7pO_;Oe}-%T&Tb6>PhHw9Bh+Eb`jn3tv4&4u7*Khy6;&=Z|reiE^_R6;IC2#T(F
z*twvy+q7txH(GRhLutwQ-9~jL^>D$8UV~l`SK7(z9c^CjA-qq)o)VUEX=c^8yZVeU
zX;`oxQ?r46chaTanpxxb+AOCueiWyVV?Rj2p!fw?4Md0xgQ8+F{iDP}GOHX4{M`wI
z^3;Xbqz6&NJVi8?uL);6Y!L%`Rrk>A62jrS=*HprM19vt6;aE1<IyxQToYeA=fWC)
zM=?)21)jAgLS!W$z7%mzbz187gkZ%)d%Ay6A|L`)oP8E6xWDBr5&n~l_BM@KjkR(i
zmhmo@yDIX$dlHXxNn`r5^Gj#RDGTH2bIEf3lL8h7FcQSin8pyQW|7o~HlIuxC%1s*
z0_I5wBYi*2Q=(~9<MG6YOg08V)SwZMnIRXC12*4GcX)fs%@^r91v9nY8h%USZSwZL
z%c1{|Zsuiw_TNGa7z*4#N%%9YdwpzZIVO#g0r9BQZMtzgNbb+Gz!U+E%YhqBHG~E!
z;?^-WY!1l=`*Zm3TTxG8WGXC<EERA7uIQ#5kHY({w*ml8k78ETV8TI$6fp7~mJ^V3
z<G8hh5)jn);KpIPMkb$r(<W>X&SchjL-DbrIQ+)%U%*B0fa~>1=^D!CiMqRwqkhVC
zhvxSR{<&EIR*9zPd>0<R68xilnjIDXy#M#l*i5N$vNXb)%hRU#Akc>O{WX{HH`Aiq
z^RVBO0b<YrJBDrTuQDL|DdNqoW_|o8OFPj1`Vou`?1yw3KWJn8akxO}kKcV9I9%8N
zxgwCh(4nBc%v2JuYTzYdxazQ3ZA)CC*)Oj<|B%&_i0`)$s4D>XOo2h~{D|M*q86Ef
z@%I?+!;Yb<b;=ANL>X^>aCt^QRFI$;*7DB-koRGHp4tV!z)4b%3^c6Z6K2LTe^>_`
zq5T!}&9yr1CPGje@}s=^jp%$kVaZAa`QOBY-+FtEH+6^ulwqdCbi|JPTNK}6MF0EE
zuVDL~8CgnXJj<~lAphcR$^IztvB7z*e=iJ5s^FEjvh&RZXDeeG1(^O7fr{-%za^53
z98>(S^#hkZ!V+}7RjljRKTn($;>mcOCS9Q0t0h%V;qSFTJPx}?1|OVLDFcXy9nKMF
zi${7(k3fjvpM{3ECto}AcmPf!><f+?863v|q3eH0ja-D~YZ3Q8gD3x~gZWW$y39aW
zX8CWd0FbZy<9^9k)1N^&{&UZFTlqRXEj3Zce+YRE)<^jBY`8l~en<yjhz`N8vQu+^
zn}0Gmu;cOH7rhbn?AhYsApWzFeUu32w`u*46)&c5Jj}5NdVJK1>x6WyP$BkR#@{!$
zM_(H&7$pHP(zdR34YOuW4N4;KKP-+!a6!!)Ow=Bu0{<nJMR=Y6zKX$^g%@Ak?h}H2
zfkJ%;&z&fJI@Z4l$H@R*c!(~E94+BGV~!*Ga2GE?^lzEMg0Rz?>Bzt`gak?~wJQ;6
zs@?y_zVPJ6%?Wy5OW!aJISCkJvs_PC!162Gi+GHGL=TC$1F1Wl9xf`pFCXaZsrO<7
zY|Xk;dTig|;{0<FI1Oe-oKVQ8yB}1;^@S#!RPY5`)Jrg8{>4b1;!tYgE$s)WoLvdw
zKl_q@iOD$O^tRJcBpqUc;zI~90RWR=(9iIXoFb+J8!s>DX+73&>qm9aBbYmh*jX*4
z2vCUlzgR3<5xF4F<dX#ocr&O(_AK{gwfC6lMgJxeHGI0iW+u=Fr16Y-`nr=`BZtha
z{*e+08Ek(o?Z1?E?eR>nf1K~x$;QuS-_fBM8#*<mRxVpnYnz2iZtGMO$!VuJa<8-F
zvLTnQB1FSdbdE7Z7dlF%Lm`*fOIOEhIJs0V*;Fd}J-gxe_iz91`~5th=XpNw&*$@e
zF5f2wbKAK)CPUss7PVvI@>!-^{u_J>Qau7q$b`z`lFHXZaQ4+lzknptXAJrWT;58I
zi+Z{J1sWpL{W@Tj*N5zua5lGQC(prj%{JklnO(cFFKQlz7M<~A(2Na4L8UQRk=5qj
z6qO7JZR8_VP$0PA&ljm>2^SV@rGGl09d-g-i`aMAjwDhPR;XDsG;gRk4bxWs_a@7V
zsD-|;P($!gP!AVh0cvL*ZX7fh@%~7iSfE|EEen+nPFNK=C=-BrXDJ)3ihQaT;^HYx
ziSzwecBr`#oMjq`K@QeAxFxIgM${AU(BYeGU`9?c;s=$<#_kyJdO_&;KI~rIKE7&p
zKqd`gN%igb90-C7t6tzK=^+adj6swp4*9M({9z*m=TuA&r=Zh(>jF1!hm+<Ac%X)}
zMM2Lf$M6P|M}bn)Kd<|dY;W(7F5V=an-Sj=C7_yzzuWca<sBPBlo_HC?No8n{G|CX
zYPfdS-WiDt$oaWEcoDq18^7g7K<+B+9CY-~Y4}tS@9+K52Bd&%AK{~Po_-mZvR7t4
zoQGZ!*8eTrrsnM;7AW1be`W6X@P7~u@fCqqeURqCN<zR54=ydQVvhK_|FQrYfNNih
zp+-Q99@2ShDD`fMPnFoO{kNo3x+-+>yHGJ-t5SQv+{;vCqid(}(>4`~Hb<3OF+qlo
zUH<MbjS3<NwG0|2NX@7_v&ibLanJw4W5xq-Zua@b@#%NF&kZ!SU3E!Niw;e=ShIed
z@hv^-%ZEK}hxFwi&_e}V?+3w5YW&8W&NXN?gj_9!DNm+)Qe2Tc?gDag(-+5M<Km9d
zPBKOYw>r%c45slIL(wH#@-oVU>pB@DT4*!EK^<m*dc<I7Ne>l7$9RF@;*Ee}_-|>4
zfnJtg7It1$OOEpjIF7M-EsItGpR~$bcc2!u+n5mM?G9+80M#4a7`zW~<b0;q6rRRA
zKT8~0@W5J4$Kbfpyx0F}Y17qQaq~m@mNQ8;tfrG{HZ05<hN5w_u?}#c)7+O<A(rRC
zY`)s8wjx+Q(fC{GGU`=s*O;!{Yubj^tnxFDFd`BLUFmc+iROtjn3*1N@ASO`;C>kp
z&9Gj3z_QUP*BOQsj{uM6-v>L=uzH)Wuf4beUSO_()t&4UwaO0*xowM4<as*~xShAo
zboTK{-X~FR?I|iQKx|>5@<tRdRfCt>>vG#ZcNO<NtGY%0Cpb;5#?rsnv^J9Yun>($
zMq3Yx?MqB4yrc`O^wc6Pz)?VPTdNT`)=^>+S0w#S#-HDnH3Kh~r1A&lKAf38KVk?#
zIk5@UddMkp#IGv7>0)1UAqhoS*%f~QuXi-;eGy1C61%6p23BPDDq1aAkx<jwlLE)3
z^-I^QZNHfp#C`7j(?%Ibl^uvALo?gP({KWvFprfPDsUSTLnnl(v+<1|Mw2s$S#ChW
z+&&$vMQJ)>iu{`UeVuWKYvczzz~cF>64@c_KQ8w&!7W!772G`2(*-&nsLuAO$$1^%
zf?&1(PFubSL{j2xqsYXW$lficRhBJIRdc(O&I_sSlHy4Ohu=V0XR=H*;=%S4OT6k!
zTA1O=J?39QcvIX80$bRg!;VqOJQ<=O#1Bh}I(%!%eYG8><sw*j!yo<_EiL>G={##2
zO{Sy&xV;?bqFSs3xPy(U@Amz+CgZBSLWFufn(VogA+Nrap9=uX`KaOJ3EZa#K8`)P
zgp`20@A}L9Ew6|;4B6J*J;HtT>qh3viL-ds_+oa<=rIuF=k12LBk2XY9)vjs+pvlM
zAjL_x^#X|?n40iwzX8gzUS<r`TObC9oMdoOHD@~T2rP+&lx8`VM!V@V65l>mNyPvZ
z4f1rLI_;t%hP7|#IcqidW@ZnhCL}!frWOW40wIHldj^`!Ms}^UG6(=X=>AJbxyDq_
z<r>NL1mMA=`ZIWV_h(XqvG>v48#9vSd&b{}GQ;OCwwnNDb@H5FHcvYhfADq;_1C*H
zwG+@_1%Y7-o8Aw&^BW@N;bK-zC{6e>ub8;je#mUUr%F%)X*5jE+nn;}hqE@5acJ-j
ze9$S}k8_{yFu*#NJsJ9aKw6@u&{@kf8&XWsKW*@)$@((uetwd8<1$OW9*$Ck^<KF1
zHuHJG&v(34P6`@1Y$rN=J@HkGiGFM731n(tfBGIns17b7-Y<1FEMO|E82=j5yUU|I
z`n)ZdwG@1-98M&W+u&PqGu@>~pPJU}G^M#0a-h10uH$1JrraQ~wsas~^e&5RE2ueD
z6n<`{Vl$b`c#+IS+di?uqGoDBYaJ@Z9G0y5j=*TYt3r%vD1^*7#Wf|QyuV};CWUZL
zAyf1Bq^A)el6f7yh#o#wda2R*d!?%B$lz%=-HB!Nb(k7k96@C~TdzoxSO6m4OcJ3s
zD(F*?O26{h5I1C?{v-3lSgfV7;C1Dm^2td$?Xiezj%Lz|nKwg5Ff&tM9RgtFs{INR
zBV5LJwTZN4#1B7CcGbG(fir94f?Sd;A>S=xnJ|a&M%!g7!ggoY`8S<x{X6%wq$~Y{
z<@l+?c9eT|dp$Znd;NryrQzpw7=!~@3WuGi1uDr`piBZ%!2LC$S9FzPsni>w%31F$
z+nl4eK5|CX4cO`vqZ~aA@_V-qbT=C**Fgy=HxL_k)7kP;31TH#WqG!3xI!RRBdNQ^
i?G!trQXc;&ixc0xBEw__@U>GK;OFAx#uU^26aEX&2r>Hr

literal 0
HcmV?d00001

diff --git a/test/image/mocks/sankey_groups.json b/test/image/mocks/sankey_groups.json
new file mode 100644
index 00000000000..a58b8857d3a
--- /dev/null
+++ b/test/image/mocks/sankey_groups.json
@@ -0,0 +1,144 @@
+{
+    "data": [
+        {
+            "type": "sankey",
+            "node": {
+                "pad": 25,
+                "line": {
+                  "color": "white",
+                  "width": 2
+                },
+                "color": ["black", "black", "black", "black", "black", "orange" ],
+                "label": ["process0", "process1", "process2", "process3", "process4", "Group A"],
+                "groups": [[2, 3, 4]]
+            },
+            "link": {
+                "source": [
+                    0, 0, 0, 0,
+                    1, 1, 1, 1,
+                    1, 1, 1, 1,
+                    1, 1,
+                    2
+                ],
+                "target": [
+                    1, 1, 1, 1,
+                    2, 2, 2, 2,
+                    3, 3, 3, 3,
+                    4, 4,
+                    0
+                ],
+                "value": [
+                    10, 20, 40, 30,
+                    10, 5, 10, 20,
+                    0, 10, 10, 10,
+                    15, 5,
+                    20
+
+                ],
+                "label": [
+                    "elementA", "elementB", "elementC", "elementD",
+                    "elementA", "elementB", "elementC", "elementD",
+                    "elementA", "elementB", "elementC", "elementD",
+                    "elementC", "elementC",
+                    "elementA"
+                ],
+                "line": {
+                    "color": "white",
+                    "width": 2
+                },
+                "colorscales": [
+                  {
+                    "label": "elementA",
+                    "colorscale": [[0, "white"], [1, "blue"]]
+                  },
+                  {
+                    "label": "elementB",
+                    "colorscale": [[0, "white"], [1, "red"]]
+                  },
+                  {
+                    "label": "elementC",
+                    "colorscale": [[0, "white"], [1, "green"]]
+                  },
+                  {
+                    "label": "elementD"
+                  }
+                ],
+
+                "hovertemplate": "%{label}<br><b>flow.labelConcentration</b>: %{flow.labelConcentration:%0.2f}<br><b>flow.concentration</b>: %{flow.concentration:%0.2f}<br><b>flow.value</b>: %{flow.value}"
+            }
+
+        }],
+    "layout": {
+        "title": "Sankey diagram with links colored based on their concentration within a flow",
+        "width": 800,
+        "height": 800,
+        "updatemenus": [{
+          "y": 1,
+          "x": 0,
+          "active": 1,
+          "buttons": [{
+              "label": "Ungroup [[]]",
+              "method": "restyle",
+              "args": ["node.groups", [
+                []
+              ]]
+            },
+            {
+              "label": "Group [[2, 3, 4]]",
+              "method": "restyle",
+              "args": ["node.groups", [
+                [
+                  [2, 3, 4]
+                ]
+              ]]
+            },
+            {
+              "label": "Group [[3, 4]]",
+              "method": "restyle",
+              "args": ["node.groups", [
+                [
+                  [3, 4]
+                ]
+              ]]
+            },
+            {
+              "label": "Group [[1, 2]]",
+              "method": "restyle",
+              "args": ["node.groups", [
+                [
+                  [1, 2]
+                ]
+              ]]
+            },
+            {
+              "label": "Group [[2, 4]]]",
+              "method": "restyle",
+              "args": ["node.groups", [
+                [
+                  [2, 4]
+                ]
+              ]]
+            },
+            {
+              "label": "Group [[0, 2]]]",
+              "method": "restyle",
+              "args": ["node.groups", [
+                [
+                  [0, 2]
+                ]
+              ]]
+            },
+            {
+              "label": "Group [[1, 2], [3, 4]]",
+              "method": "restyle",
+              "args": ["node.groups", [
+                [
+                  [1, 2],
+                  [3, 4]
+                ]
+              ]]
+            }
+          ]
+        }]
+    }
+}
diff --git a/test/jasmine/tests/sankey_test.js b/test/jasmine/tests/sankey_test.js
index 6471906d6e1..238344b3a38 100644
--- a/test/jasmine/tests/sankey_test.js
+++ b/test/jasmine/tests/sankey_test.js
@@ -263,7 +263,7 @@ describe('sankey tests', function() {
                     label: ['a', 'b', 'c', 'd', 'e']
                 },
                 link: {
-                    value: [1, 1, 1, 1, 1, 1, 1, 1],
+                    value: [1, 1, 1, 1],
                     source: [0, 1, 2, 3],
                     target: [1, 2, 0, 4]
                 }
@@ -277,13 +277,32 @@ describe('sankey tests', function() {
                     label: ['a', 'b', 'c', 'd', 'e']
                 },
                 link: {
-                    value: [1, 1, 1, 1, 1, 1, 1, 1],
+                    value: [1, 1, 1, 1],
                     source: [0, 1, 2, 3],
                     target: [1, 2, 4, 4]
                 }
             }));
             expect(calcData[0].circular).toBe(false);
         });
+
+        it('keep an index of groups', function() {
+            var calcData = _calc(Lib.extendDeep({}, base, {
+                node: {
+                    label: ['a', 'b', 'c', 'd', 'e'],
+                    groups: [[0, 1], [2, 3]]
+                },
+                link: {
+                    value: [1, 1, 1, 1],
+                    source: [0, 1, 2, 3],
+                    target: [1, 2, 4, 4]
+                }
+            }));
+            var groups = calcData[0]._nodes.filter(function(node) {
+                return node.group;
+            });
+            expect(groups.length).toBe(2);
+            expect(calcData[0].circular).toBe(false);
+        });
     });
 
     describe('lifecycle methods', function() {
@@ -404,6 +423,22 @@ describe('sankey tests', function() {
                   done();
               });
         });
+
+        it('can create groups', function(done) {
+            var gd = createGraphDiv();
+            var mockCircularCopy = Lib.extendDeep({}, mockCircular);
+            mockCircularCopy.data[0].node.groups = [[2, 3], [0, 1]];
+            Plotly.plot(gd, mockCircularCopy)
+              .then(function() {
+                  expect(gd._fullData[0].node.groups).toEqual([[2, 3], [0, 1]]);
+                  return Plotly.restyle(gd, {'node.groups': [[[3, 4]]]});
+              })
+              .then(function() {
+                  expect(gd._fullData[0].node.groups).toEqual([[3, 4]]);
+                  destroyGraphDiv();
+                  done();
+              });
+        });
     });
 
     describe('Test hover/click interactions:', function() {

From 85470a0d8bfb04ff168cd7ce2ce3b46ede7dc23f Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Tue, 19 Feb 2019 13:01:28 -0500
Subject: [PATCH 02/13] nodes that are part of a group should be in the back

---
 src/traces/sankey/calc.js   |  1 -
 src/traces/sankey/render.js | 10 +++++-----
 2 files changed, 5 insertions(+), 6 deletions(-)

diff --git a/src/traces/sankey/calc.js b/src/traces/sankey/calc.js
index 485ac87de2d..187185a567a 100644
--- a/src/traces/sankey/calc.js
+++ b/src/traces/sankey/calc.js
@@ -82,7 +82,6 @@ function convertToD3Sankey(trace) {
         }
 
         // if link originates from a node in a group, relink source to that group
-        // if(group.indexOf(source) !== -1) {
         if(groupLookup.hasOwnProperty(source)) {
             source = groupLookup[source];
         }
diff --git a/src/traces/sankey/render.js b/src/traces/sankey/render.js
index b9b41ef5be0..6d3c618b12b 100644
--- a/src/traces/sankey/render.js
+++ b/src/traces/sankey/render.js
@@ -79,7 +79,7 @@ function sankeyModel(layout, d, traceIndex) {
             }
         }
 
-        graph.nodes.push({
+        graph.nodes.unshift({
             pointNumber: parseInt(nodePointNumber),
             x0: groupingNode.x0,
             x1: groupingNode.x1,
@@ -474,19 +474,19 @@ function attachPointerEvents(selection, sankey, eventSet) {
     selection
         .on('.basic', null) // remove any preexisting handlers
         .on('mouseover.basic', function(d) {
-            if(!d.interactionState.dragInProgress) {
+            if(!d.interactionState.dragInProgress && !d.partOfGroup) {
                 eventSet.hover(this, d, sankey);
                 d.interactionState.hovered = [this, d];
             }
         })
         .on('mousemove.basic', function(d) {
-            if(!d.interactionState.dragInProgress) {
+            if(!d.interactionState.dragInProgress && !d.partOfGroup) {
                 eventSet.follow(this, d);
                 d.interactionState.hovered = [this, d];
             }
         })
         .on('mouseout.basic', function(d) {
-            if(!d.interactionState.dragInProgress) {
+            if(!d.interactionState.dragInProgress && !d.partOfGroup) {
                 eventSet.unhover(this, d, sankey);
                 d.interactionState.hovered = false;
             }
@@ -496,7 +496,7 @@ function attachPointerEvents(selection, sankey, eventSet) {
                 eventSet.unhover(this, d, sankey);
                 d.interactionState.hovered = false;
             }
-            if(!d.interactionState.dragInProgress) {
+            if(!d.interactionState.dragInProgress && !d.partOfGroup) {
                 eventSet.select(this, d, sankey);
             }
         });

From 1cd206f7fdba75b010650331fc1f7a726ec488df Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Tue, 19 Feb 2019 14:51:32 -0500
Subject: [PATCH 03/13] sankey: turn `node.groups` into a info_array, use for
 loops

---
 src/traces/sankey/attributes.js |  5 ++++-
 src/traces/sankey/calc.js       | 18 ++++++------------
 src/traces/sankey/render.js     |  8 ++++----
 3 files changed, 14 insertions(+), 17 deletions(-)

diff --git a/src/traces/sankey/attributes.js b/src/traces/sankey/attributes.js
index 109934f28f0..ccd14455e81 100644
--- a/src/traces/sankey/attributes.js
+++ b/src/traces/sankey/attributes.js
@@ -90,8 +90,11 @@ var attrs = module.exports = overrideAll({
             description: 'The shown name of the node.'
         },
         groups: {
-            valType: 'data_array',
+            valType: 'info_array',
+            dimensions: 2,
+            freeLength: true,
             dflt: [],
+            items: {valType: 'number', editType: 'calc'},
             role: 'calc',
             description: [
                 'Groups of nodes.',
diff --git a/src/traces/sankey/calc.js b/src/traces/sankey/calc.js
index 187185a567a..cebea266e37 100644
--- a/src/traces/sankey/calc.js
+++ b/src/traces/sankey/calc.js
@@ -17,10 +17,8 @@ var isIndex = Lib.isIndex;
 var Colorscale = require('../../components/colorscale');
 
 function convertToD3Sankey(trace) {
-    // var nodeSpec = trace.node;
-    // var linkSpec = trace.link;
-    var nodeSpec = Lib.extendDeep({}, trace.node);
-    var linkSpec = Lib.extendDeep({}, trace.link);
+    var nodeSpec = trace.node;
+    var linkSpec = trace.link;
 
     var links = [];
     var hasLinkColorArray = isArrayOrTypedArray(linkSpec.color);
@@ -50,14 +48,10 @@ function convertToD3Sankey(trace) {
     for(i = 0; i < groups.length; i++) {
         var group = groups[i];
         // Build a lookup table to quickly find in which group a node is
-        if(Array.isArray(group)) {
-            for(j = 0; j < group.length; j++) {
-                var nodeIndex = group[j];
-                var groupIndex = nodeCount + i;
-                groupLookup[nodeIndex] = groupIndex;
-            }
-        } else {
-            Lib.warn('node.groups must be an array, default to empty array []');
+        for(j = 0; j < group.length; j++) {
+            var nodeIndex = group[j];
+            var groupIndex = nodeCount + i;
+            groupLookup[nodeIndex] = groupIndex;
         }
     }
 
diff --git a/src/traces/sankey/render.js b/src/traces/sankey/render.js
index 6d3c618b12b..871fcd27956 100644
--- a/src/traces/sankey/render.js
+++ b/src/traces/sankey/render.js
@@ -68,7 +68,7 @@ function sankeyModel(layout, d, traceIndex) {
     }
 
     // Create transient nodes for animations
-    Object.keys(calcData._groupLookup).forEach(function(nodePointNumber) {
+    for(var nodePointNumber in calcData._groupLookup) {
         var groupIndex = parseInt(calcData._groupLookup[nodePointNumber]);
 
         var groupingNode;
@@ -89,7 +89,7 @@ function sankeyModel(layout, d, traceIndex) {
             sourceLinks: [],
             targetLinks: []
         });
-    });
+    }
 
     function computeLinkConcentrations() {
         var i, j, k;
@@ -161,7 +161,7 @@ function sankeyModel(layout, d, traceIndex) {
         circular: circular,
         key: traceIndex,
         trace: trace,
-        guid: Math.floor(1e12 * (1 + Math.random())),
+        guid: Lib.randstr(),
         horizontal: horizontal,
         width: width,
         height: height,
@@ -379,7 +379,7 @@ function nodeModel(d, n) {
     var key = 'node_' + n.pointNumber;
     // If it's a group, it's mutable and should be unique
     if(n.group) {
-        key = 'group_' + Math.floor(1e12 * (1 + Math.random()));
+        key = Lib.randstr();
     }
 
     // for event data

From b90fda19ab6b19bf7f1bb704c3e3e40b9f0730f5 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Tue, 19 Feb 2019 17:25:49 -0500
Subject: [PATCH 04/13] remove opacity transition if _context.staticPlot

---
 src/snapshot/helpers.js     | 1 -
 src/traces/sankey/render.js | 4 ++--
 2 files changed, 2 insertions(+), 3 deletions(-)

diff --git a/src/snapshot/helpers.js b/src/snapshot/helpers.js
index 93af480d623..b6f6ae21423 100644
--- a/src/snapshot/helpers.js
+++ b/src/snapshot/helpers.js
@@ -15,7 +15,6 @@ exports.getDelay = function(fullLayout) {
     return (
         fullLayout._has('gl3d') ||
         fullLayout._has('gl2d') ||
-        fullLayout._has('sankey') ||
         fullLayout._has('mapbox')
     ) ? 500 : 0;
 };
diff --git a/src/traces/sankey/render.js b/src/traces/sankey/render.js
index 871fcd27956..3cd3899dde9 100644
--- a/src/traces/sankey/render.js
+++ b/src/traces/sankey/render.js
@@ -736,7 +736,7 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
         .attr('d', linkPath());
 
     sankeyLink
-        .style('opacity', 0)
+        .style('opacity', function() { return gd._context.staticPlot ? 1 : 0;})
         .transition()
         .ease(c.ease).duration(c.duration)
         .style('opacity', 1);
@@ -775,7 +775,7 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
         .append('g')
         .classed(c.cn.sankeyNode, true)
         .call(updateNodePositions)
-        .style('opacity', 0);
+        .style('opacity', function(n) { return (!gd._context.staticPlot && n.partOfGroup) ? 0 : 1;});
 
     sankeyNode
         .call(attachPointerEvents, sankey, callbacks.nodeEvents)

From b4d7ff32790d07f0406ba36e86b0c383ece0e999 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Tue, 19 Feb 2019 17:37:47 -0500
Subject: [PATCH 05/13] fix opacity logic

---
 src/traces/sankey/render.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/traces/sankey/render.js b/src/traces/sankey/render.js
index 3cd3899dde9..ec1b0ffe173 100644
--- a/src/traces/sankey/render.js
+++ b/src/traces/sankey/render.js
@@ -775,7 +775,7 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
         .append('g')
         .classed(c.cn.sankeyNode, true)
         .call(updateNodePositions)
-        .style('opacity', function(n) { return (!gd._context.staticPlot && n.partOfGroup) ? 0 : 1;});
+        .style('opacity', function(n) { return (gd._context.staticPlot && !n.partOfGroup) ? 1 : 0;});
 
     sankeyNode
         .call(attachPointerEvents, sankey, callbacks.nodeEvents)

From ab1a0fb5e3f0578fe901278dd0dc52f70faa35cd Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Tue, 19 Feb 2019 17:52:51 -0500
Subject: [PATCH 06/13] update position of phantom children nodes when a group
 is dragged

---
 src/traces/sankey/calc.js   |  1 +
 src/traces/sankey/render.js | 11 +++++++++--
 2 files changed, 10 insertions(+), 2 deletions(-)

diff --git a/src/traces/sankey/calc.js b/src/traces/sankey/calc.js
index cebea266e37..7af7ec179d2 100644
--- a/src/traces/sankey/calc.js
+++ b/src/traces/sankey/calc.js
@@ -111,6 +111,7 @@ function convertToD3Sankey(trace) {
 
         nodes.push({
             group: (i > nodeCount - 1),
+            children: [],
             pointNumber: i,
             label: l,
             color: hasNodeColorArray ? nodeSpec.color[i] : nodeSpec.color
diff --git a/src/traces/sankey/render.js b/src/traces/sankey/render.js
index ec1b0ffe173..3258725fb80 100644
--- a/src/traces/sankey/render.js
+++ b/src/traces/sankey/render.js
@@ -79,7 +79,7 @@ function sankeyModel(layout, d, traceIndex) {
             }
         }
 
-        graph.nodes.unshift({
+        var child = {
             pointNumber: parseInt(nodePointNumber),
             x0: groupingNode.x0,
             x1: groupingNode.x1,
@@ -88,7 +88,10 @@ function sankeyModel(layout, d, traceIndex) {
             partOfGroup: true,
             sourceLinks: [],
             targetLinks: []
-        });
+        };
+
+        graph.nodes.unshift(child);
+        groupingNode.children.unshift(child);
     }
 
     function computeLinkConcentrations() {
@@ -559,6 +562,10 @@ function attachDragHandler(sankeyNode, sankeyLink, callbacks) {
 
         .on('dragend', function(d) {
             d.interactionState.dragInProgress = false;
+            for(var i = 0; i < d.node.children.length; i++) {
+                d.node.children[i].x = d.node.x;
+                d.node.children[i].y = d.node.y;
+            }
         });
 
     sankeyNode

From 63d819088679cad926ad8521ec5e141613a60fb1 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Tue, 19 Feb 2019 18:03:42 -0500
Subject: [PATCH 07/13] replace children by childrenNodes

---
 src/traces/sankey/calc.js   | 2 +-
 src/traces/sankey/render.js | 8 ++++----
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/src/traces/sankey/calc.js b/src/traces/sankey/calc.js
index 7af7ec179d2..87619f2549b 100644
--- a/src/traces/sankey/calc.js
+++ b/src/traces/sankey/calc.js
@@ -111,7 +111,7 @@ function convertToD3Sankey(trace) {
 
         nodes.push({
             group: (i > nodeCount - 1),
-            children: [],
+            childrenNodes: [],
             pointNumber: i,
             label: l,
             color: hasNodeColorArray ? nodeSpec.color[i] : nodeSpec.color
diff --git a/src/traces/sankey/render.js b/src/traces/sankey/render.js
index 3258725fb80..b8ec3f4ee5f 100644
--- a/src/traces/sankey/render.js
+++ b/src/traces/sankey/render.js
@@ -91,7 +91,7 @@ function sankeyModel(layout, d, traceIndex) {
         };
 
         graph.nodes.unshift(child);
-        groupingNode.children.unshift(child);
+        groupingNode.childrenNodes.unshift(child);
     }
 
     function computeLinkConcentrations() {
@@ -562,9 +562,9 @@ function attachDragHandler(sankeyNode, sankeyLink, callbacks) {
 
         .on('dragend', function(d) {
             d.interactionState.dragInProgress = false;
-            for(var i = 0; i < d.node.children.length; i++) {
-                d.node.children[i].x = d.node.x;
-                d.node.children[i].y = d.node.y;
+            for(var i = 0; i < d.node.childrenNodes.length; i++) {
+                d.node.childrenNodes[i].x = d.node.x;
+                d.node.childrenNodes[i].y = d.node.y;
             }
         });
 

From 6175fb59363ee1eb00e138a6f4353865dc1bef80 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Thu, 21 Feb 2019 17:51:36 -0500
Subject: [PATCH 08/13] sankey: add warning if node is in multiple groups,
 change transition settings

---
 src/traces/sankey/calc.js           |  6 +++++-
 src/traces/sankey/constants.js      |  4 ++--
 test/image/mocks/sankey_groups.json |  4 ++--
 test/jasmine/tests/sankey_test.js   | 24 ++++++++++++++++++++++++
 4 files changed, 33 insertions(+), 5 deletions(-)

diff --git a/src/traces/sankey/calc.js b/src/traces/sankey/calc.js
index 87619f2549b..c3bbe4ba246 100644
--- a/src/traces/sankey/calc.js
+++ b/src/traces/sankey/calc.js
@@ -51,7 +51,11 @@ function convertToD3Sankey(trace) {
         for(j = 0; j < group.length; j++) {
             var nodeIndex = group[j];
             var groupIndex = nodeCount + i;
-            groupLookup[nodeIndex] = groupIndex;
+            if(groupLookup.hasOwnProperty(nodeIndex)) {
+                Lib.warn('Node ' + nodeIndex + ' is already part of a group.');
+            } else {
+                groupLookup[nodeIndex] = groupIndex;
+            }
         }
     }
 
diff --git a/src/traces/sankey/constants.js b/src/traces/sankey/constants.js
index bffd9294237..534b05ad4e7 100644
--- a/src/traces/sankey/constants.js
+++ b/src/traces/sankey/constants.js
@@ -15,8 +15,8 @@ module.exports = {
     sankeyIterations: 50,
     forceIterations: 5,
     forceTicksPerFrame: 10,
-    duration: 350,
-    ease: 'quart-in-out',
+    duration: 500,
+    ease: 'linear',
     cn: {
         sankey: 'sankey',
         sankeyLinks: 'sankey-links',
diff --git a/test/image/mocks/sankey_groups.json b/test/image/mocks/sankey_groups.json
index a58b8857d3a..90afbde12bb 100644
--- a/test/image/mocks/sankey_groups.json
+++ b/test/image/mocks/sankey_groups.json
@@ -8,8 +8,8 @@
                   "color": "white",
                   "width": 2
                 },
-                "color": ["black", "black", "black", "black", "black", "orange" ],
-                "label": ["process0", "process1", "process2", "process3", "process4", "Group A"],
+                "color": ["black", "black", "black", "black", "black", "orange", "orange" ],
+                "label": ["process0", "process1", "process2", "process3", "process4", "Group A", "Group B"],
                 "groups": [[2, 3, 4]]
             },
             "link": {
diff --git a/test/jasmine/tests/sankey_test.js b/test/jasmine/tests/sankey_test.js
index 238344b3a38..58e818ddc2a 100644
--- a/test/jasmine/tests/sankey_test.js
+++ b/test/jasmine/tests/sankey_test.js
@@ -303,6 +303,30 @@ describe('sankey tests', function() {
             expect(groups.length).toBe(2);
             expect(calcData[0].circular).toBe(false);
         });
+
+        it('emits a warning if a node is part of more than one group', function() {
+            var warnings = [];
+            spyOn(Lib, 'warn').and.callFake(function(msg) {
+                warnings.push(msg);
+            });
+
+            var calcData = _calc(Lib.extendDeep({}, base, {
+                node: {
+                    label: ['a', 'b', 'c', 'd', 'e'],
+                    groups: [[0, 1], [1, 2, 3]]
+                },
+                link: {
+                    value: [1, 1, 1, 1],
+                    source: [0, 1, 2, 3],
+                    target: [1, 2, 4, 4]
+                }
+            }));
+
+            expect(warnings.length).toBe(1);
+
+            // Expect node '1' to be in the first group
+            expect(calcData[0]._groupLookup[1]).toBe(5);
+        });
     });
 
     describe('lifecycle methods', function() {

From 31990f074c5f63dea26b107114055e2f5417ef65 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Mon, 25 Feb 2019 15:46:02 -0500
Subject: [PATCH 09/13] sankey: do not animate on first render

---
 src/traces/sankey/render.js | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/traces/sankey/render.js b/src/traces/sankey/render.js
index b8ec3f4ee5f..6ea0049fc55 100644
--- a/src/traces/sankey/render.js
+++ b/src/traces/sankey/render.js
@@ -678,6 +678,11 @@ function switchToSankeyFormat(nodes) {
 
 // scene graph
 module.exports = function(gd, svg, calcData, layout, callbacks) {
+    // To prevent animation on first render
+    var firstRender = false;
+    Lib.ensureSingle(gd._fullLayout._infolayer, 'g', 'first-render', function() {
+        firstRender = true;
+    });
 
     var styledData = calcData
             .filter(function(d) {return unwrap(d).trace.visible;})
@@ -743,7 +748,7 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
         .attr('d', linkPath());
 
     sankeyLink
-        .style('opacity', function() { return gd._context.staticPlot ? 1 : 0;})
+        .style('opacity', function() { return (gd._context.staticPlot || firstRender) ? 1 : 0;})
         .transition()
         .ease(c.ease).duration(c.duration)
         .style('opacity', 1);
@@ -782,7 +787,7 @@ module.exports = function(gd, svg, calcData, layout, callbacks) {
         .append('g')
         .classed(c.cn.sankeyNode, true)
         .call(updateNodePositions)
-        .style('opacity', function(n) { return (gd._context.staticPlot && !n.partOfGroup) ? 1 : 0;});
+        .style('opacity', function(n) { return ((gd._context.staticPlot || firstRender) && !n.partOfGroup) ? 1 : 0;});
 
     sankeyNode
         .call(attachPointerEvents, sankey, callbacks.nodeEvents)

From fec37399e786b136d206088beb805dacb7d36567 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Mon, 25 Feb 2019 16:23:16 -0500
Subject: [PATCH 10/13] sankey: fix attribute's role for `node.groups`

---
 src/traces/sankey/attributes.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/traces/sankey/attributes.js b/src/traces/sankey/attributes.js
index ccd14455e81..9e0929100c7 100644
--- a/src/traces/sankey/attributes.js
+++ b/src/traces/sankey/attributes.js
@@ -95,7 +95,7 @@ var attrs = module.exports = overrideAll({
             freeLength: true,
             dflt: [],
             items: {valType: 'number', editType: 'calc'},
-            role: 'calc',
+            role: 'info',
             description: [
                 'Groups of nodes.',
                 'Each group is defined by an array with the indices of the nodes it contains.',

From ffbafa72b494d64d99b714a8c3b09fed12181b47 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Mon, 25 Feb 2019 20:29:28 -0500
Subject: [PATCH 11/13] sankey: test that groups have appropriate DOM elements

---
 src/traces/sankey/render.js       |  4 +++
 test/jasmine/tests/sankey_test.js | 50 ++++++++++++++++++++++---------
 2 files changed, 40 insertions(+), 14 deletions(-)

diff --git a/src/traces/sankey/render.js b/src/traces/sankey/render.js
index 6ea0049fc55..7c2ca3489ce 100644
--- a/src/traces/sankey/render.js
+++ b/src/traces/sankey/render.js
@@ -71,6 +71,7 @@ function sankeyModel(layout, d, traceIndex) {
     for(var nodePointNumber in calcData._groupLookup) {
         var groupIndex = parseInt(calcData._groupLookup[nodePointNumber]);
 
+        // Find node representing groupIndex
         var groupingNode;
         for(var i = 0; i < graph.nodes.length; i++) {
             if(graph.nodes[i].pointNumber === groupIndex) {
@@ -78,6 +79,8 @@ function sankeyModel(layout, d, traceIndex) {
                 break;
             }
         }
+        // If groupinNode is undefined, no links are targeting this group
+        if(!groupingNode) continue;
 
         var child = {
             pointNumber: parseInt(nodePointNumber),
@@ -211,6 +214,7 @@ function linkModel(d, l, i) {
         link: l,
         tinyColorHue: Color.tinyRGB(tc),
         tinyColorAlpha: tc.getAlpha(),
+        linkPath: linkPath,
         linkLineColor: d.linkLineColor,
         linkLineWidth: d.linkLineWidth,
         valueFormat: d.valueFormat,
diff --git a/test/jasmine/tests/sankey_test.js b/test/jasmine/tests/sankey_test.js
index 58e818ddc2a..53cfd4abecc 100644
--- a/test/jasmine/tests/sankey_test.js
+++ b/test/jasmine/tests/sankey_test.js
@@ -330,11 +330,14 @@ describe('sankey tests', function() {
     });
 
     describe('lifecycle methods', function() {
+        var gd;
+        beforeEach(function() {
+            gd = createGraphDiv();
+        });
         afterEach(destroyGraphDiv);
 
         it('Plotly.deleteTraces with two traces removes the deleted plot', function(done) {
 
-            var gd = createGraphDiv();
             var mockCopy = Lib.extendDeep({}, mock);
             var mockCopy2 = Lib.extendDeep({}, mockDark);
 
@@ -363,7 +366,6 @@ describe('sankey tests', function() {
 
         it('Plotly.plot does not show Sankey if \'visible\' is false', function(done) {
 
-            var gd = createGraphDiv();
             var mockCopy = Lib.extendDeep({}, mock);
 
             Plotly.plot(gd, mockCopy)
@@ -386,7 +388,6 @@ describe('sankey tests', function() {
 
         it('\'node\' remains visible even if \'value\' is very low', function(done) {
 
-            var gd = createGraphDiv();
             var minimock = [{
                 type: 'sankey',
                 node: {
@@ -408,7 +409,6 @@ describe('sankey tests', function() {
         });
 
         it('switch from normal to circular Sankey on react', function(done) {
-            var gd = createGraphDiv();
             var mockCopy = Lib.extendDeep({}, mock);
             var mockCircularCopy = Lib.extendDeep({}, mockCircular);
 
@@ -424,7 +424,6 @@ describe('sankey tests', function() {
         });
 
         it('switch from circular to normal Sankey on react', function(done) {
-            var gd = createGraphDiv();
             var mockCircularCopy = Lib.extendDeep({}, mockCircular);
 
             Plotly.plot(gd, mockCircularCopy)
@@ -448,20 +447,43 @@ describe('sankey tests', function() {
               });
         });
 
-        it('can create groups', function(done) {
-            var gd = createGraphDiv();
+        it('can create groups, restyle groups and properly update DOM', function(done) {
             var mockCircularCopy = Lib.extendDeep({}, mockCircular);
-            mockCircularCopy.data[0].node.groups = [[2, 3], [0, 1]];
+            var firstGroup = [[2, 3], [0, 1]];
+            var newGroup = [[2, 3]];
+            mockCircularCopy.data[0].node.groups = firstGroup;
+
             Plotly.plot(gd, mockCircularCopy)
               .then(function() {
-                  expect(gd._fullData[0].node.groups).toEqual([[2, 3], [0, 1]]);
-                  return Plotly.restyle(gd, {'node.groups': [[[3, 4]]]});
+                  expect(gd._fullData[0].node.groups).toEqual(firstGroup);
+                  return Plotly.restyle(gd, {'node.groups': [newGroup]});
               })
               .then(function() {
-                  expect(gd._fullData[0].node.groups).toEqual([[3, 4]]);
-                  destroyGraphDiv();
-                  done();
-              });
+                  expect(gd._fullData[0].node.groups).toEqual(newGroup);
+
+                  // Check that all links have updated their links
+                  d3.selectAll('.sankey .sankey-link').each(function(d, i) {
+                      var path = this.getAttribute('d');
+                      expect(path).toBe(d.linkPath()(d), 'link ' + i + ' has wrong `d` attribute');
+                  });
+
+                  // Check that ghost nodes used for animations:
+                  // 1) are drawn first so they apear behind
+                  var seeRealNode = false;
+                  var sankeyNodes = d3.selectAll('.sankey .sankey-node');
+                  sankeyNodes.each(function(d, i) {
+                      if(d.partOfGroup) {
+                          if(seeRealNode) fail('node ' + i + ' is a ghost node and should be behind');
+                      } else {
+                          seeRealNode = true;
+                      }
+                  });
+                  // 2) have an element for each grouped node
+                  var L = sankeyNodes.filter(function(d) { return d.partOfGroup;}).size();
+                  expect(L).toBe(newGroup.flat().length, 'does not have the right number of ghost nodes');
+              })
+              .catch(failTest)
+              .then(done);
         });
     });
 

From 7094887584b7bb9a3e2ca17fef03deba138858f6 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Tue, 26 Feb 2019 11:04:20 -0500
Subject: [PATCH 12/13] sankey: check for circularity after grouping

---
 src/traces/sankey/calc.js         | 25 ++++++++++++++++---------
 test/jasmine/tests/sankey_test.js | 22 ++++++++++++++++++++++
 2 files changed, 38 insertions(+), 9 deletions(-)

diff --git a/src/traces/sankey/calc.js b/src/traces/sankey/calc.js
index c3bbe4ba246..5b31199f1f9 100644
--- a/src/traces/sankey/calc.js
+++ b/src/traces/sankey/calc.js
@@ -60,6 +60,10 @@ function convertToD3Sankey(trace) {
     }
 
     // Process links
+    var groupedLinks = {
+        source: [],
+        target: []
+    };
     for(i = 0; i < linkSpec.value.length; i++) {
         var val = linkSpec.value[i];
         // remove negative values, but keep zeros with special treatment
@@ -103,6 +107,9 @@ function convertToD3Sankey(trace) {
             target: target,
             value: +val
         });
+
+        groupedLinks.source.push(source);
+        groupedLinks.target.push(target);
     }
 
     // Process nodes
@@ -122,7 +129,14 @@ function convertToD3Sankey(trace) {
         });
     }
 
+    // Check if we have circularity on the resulting graph
+    var circular = false;
+    if(circularityPresent(totalCount, groupedLinks.source, groupedLinks.target)) {
+        circular = true;
+    }
+
     return {
+        circular: circular,
         links: links,
         nodes: nodes,
 
@@ -132,9 +146,7 @@ function convertToD3Sankey(trace) {
     };
 }
 
-function circularityPresent(nodeList, sources, targets) {
-
-    var nodeLen = nodeList.length;
+function circularityPresent(nodeLen, sources, targets) {
     var nodes = Lib.init2dArray(nodeLen, 0);
 
     for(var i = 0; i < Math.min(sources.length, targets.length); i++) {
@@ -156,15 +168,10 @@ function circularityPresent(nodeList, sources, targets) {
 }
 
 module.exports = function calc(gd, trace) {
-    var circular = false;
-    if(circularityPresent(trace.node.label, trace.link.source, trace.link.target)) {
-        circular = true;
-    }
-
     var result = convertToD3Sankey(trace);
 
     return wrap({
-        circular: circular,
+        circular: result.circular,
         _nodes: result.nodes,
         _links: result.links,
 
diff --git a/test/jasmine/tests/sankey_test.js b/test/jasmine/tests/sankey_test.js
index 53cfd4abecc..c39017fb5f5 100644
--- a/test/jasmine/tests/sankey_test.js
+++ b/test/jasmine/tests/sankey_test.js
@@ -485,6 +485,28 @@ describe('sankey tests', function() {
               .catch(failTest)
               .then(done);
         });
+
+        it('switches from normal to circular Sankey on grouping', function(done) {
+            var mockCopy = Lib.extendDeep({}, mock);
+
+            Plotly.plot(gd, mockCopy)
+              .then(function() {
+                  expect(gd.calcdata[0][0].circular).toBe(false);
+
+                  // Group two nodes to create circularity
+                  return Plotly.restyle(gd, 'node.groups', [[[1, 3]]]);
+              })
+              .then(function() {
+                  expect(gd.calcdata[0][0].circular).toBe(true);
+                  // Group two nodes to that do not create circularity
+                  return Plotly.restyle(gd, 'node.groups', [[[1, 4]]]);
+              })
+              .then(function() {
+                  expect(gd.calcdata[0][0].circular).toBe(false);
+                  done();
+              });
+        });
+
     });
 
     describe('Test hover/click interactions:', function() {

From fb9479a5ca6b81ad83c930c600bf3be62b47c871 Mon Sep 17 00:00:00 2001
From: Antoine Roy-Gobeil <antoine@plot.ly>
Date: Tue, 26 Feb 2019 11:12:34 -0500
Subject: [PATCH 13/13] fix typo

---
 src/traces/sankey/calc.js         | 2 +-
 test/jasmine/tests/sankey_test.js | 4 ++--
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/traces/sankey/calc.js b/src/traces/sankey/calc.js
index 5b31199f1f9..b46715a155e 100644
--- a/src/traces/sankey/calc.js
+++ b/src/traces/sankey/calc.js
@@ -62,7 +62,7 @@ function convertToD3Sankey(trace) {
     // Process links
     var groupedLinks = {
         source: [],
-        target: []
+        target: []
     };
     for(i = 0; i < linkSpec.value.length; i++) {
         var val = linkSpec.value[i];
diff --git a/test/jasmine/tests/sankey_test.js b/test/jasmine/tests/sankey_test.js
index c39017fb5f5..69d985a5041 100644
--- a/test/jasmine/tests/sankey_test.js
+++ b/test/jasmine/tests/sankey_test.js
@@ -493,12 +493,12 @@ describe('sankey tests', function() {
               .then(function() {
                   expect(gd.calcdata[0][0].circular).toBe(false);
 
-                  // Group two nodes to create circularity
+                  // Group two nodes that creates a circularity
                   return Plotly.restyle(gd, 'node.groups', [[[1, 3]]]);
               })
               .then(function() {
                   expect(gd.calcdata[0][0].circular).toBe(true);
-                  // Group two nodes to that do not create circularity
+                  // Group two nodes that do not create a circularity
                   return Plotly.restyle(gd, 'node.groups', [[[1, 4]]]);
               })
               .then(function() {