"
]
},
{
"cell_type": "code",
"execution_count": 1,
"metadata": {},
"outputs": [
{
"data": {
"text/html": [
"\n",
"\n",
"\n",
""
],
"text/plain": [
""
]
},
"execution_count": 1,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"# code for loading the format for the notebook\n",
"import os\n",
"\n",
"# path : store the current path to convert back to it later\n",
"path = os.getcwd()\n",
"os.chdir(os.path.join('..', 'notebook_format'))\n",
"\n",
"from formats import load_style\n",
"load_style(css_style='custom2.css', plot_style=False)"
]
},
{
"cell_type": "code",
"execution_count": 2,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Ethen 2020-02-20 15:09:58 \n",
"\n",
"CPython 3.6.4\n",
"IPython 7.9.0\n",
"\n",
"numpy 1.16.5\n",
"pandas 0.25.0\n",
"sklearn 0.21.2\n",
"matplotlib 3.1.1\n",
"xgboost 0.81\n",
"lightgbm 2.2.4\n"
]
}
],
"source": [
"os.chdir(path)\n",
"\n",
"# 1. magic for inline plot\n",
"# 2. magic to print version\n",
"# 3. magic so that the notebook will reload external python modules\n",
"# 4. magic to enable retina (high resolution) plots\n",
"# https://gist.github.com/minrk/3301035\n",
"%matplotlib inline\n",
"%load_ext watermark\n",
"%load_ext autoreload\n",
"%autoreload 2\n",
"%config InlineBackend.figure_format='retina'\n",
"\n",
"import os\n",
"import time\n",
"import numpy as np\n",
"import pandas as pd\n",
"import xgboost as xgb\n",
"import lightgbm as lgb\n",
"import matplotlib.pyplot as plt\n",
"import sklearn.metrics as metrics\n",
"from copy import deepcopy\n",
"from sklearn.model_selection import train_test_split\n",
"from sklearn.datasets.california_housing import fetch_california_housing\n",
"\n",
"# prevent scientific notations\n",
"pd.set_option('display.float_format', lambda x: '%.3f' % x)\n",
"\n",
"%watermark -a 'Ethen' -d -t -v -p numpy,pandas,sklearn,matplotlib,xgboost,lightgbm"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Monotonic Constraint with Boosted Tree"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Real world machine learning is often times more than just fitting a model with high accuracy, often times we also want one that makes intuitive sense, or interpretable. Today's topic will be around monotonic.\n",
"\n",
"The idea around monotonic can be best illustrated by a few example:\n",
"\n",
"- If we applied for a credit card but got declined, one possible reason could be our previous credit card balance is too high. In this case, our mental model tells us that the underlying model should be monotonic with credit card balance. i.e. someone with a credit card balance higher than us but otherwise identical credit profile should also get rejected.\n",
"- A hotel chain might want to estimate the likelihood of a room being booked at a given price and day of the week. Our intuition tells us, with all else being equal, a cheaper price is most likely preferred by the user. i.e. price should have a monotonic relationship with booking probability.\n",
"\n",
"What may happen after building a model, especially when using popular non-linear models such as random forest, boosted tree or neural networks is that we end up with counter-intuitive scenarios (e.g. the higher the price the higher the booking probability, when all else being equal). This kind of situation often happens in the areas where data are sparse, or have a lot of noise.\n",
"\n",
"If our domain knowledge tells us that this feature has a monotonic relationship with the outcome, then we should try enforcing a monotonic constraint and check our model's overall performance. We might find out that by constraining the model, not only will it not lead to a significant degradation of the model's performance on the training set, but also can result in a better performance on the test data.\n",
"\n",
"Popular open-sourced boosted tree libraries such as XGBoost and LightGBM both have the capabilities of introducing monotonic constraint to the features that we specify. In this notebook, we will explore how this can be achieved."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## Data Preparation"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We'll be using the california housing data to illustrate the concept. In particular, we'll see how to enforce monotonic constraint on the feature `MedInc`, medium income on the target, medium house value."
]
},
{
"cell_type": "code",
"execution_count": 3,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"feature names: ['MedInc', 'HouseAge', 'AveRooms', 'AveBedrms', 'Population', 'AveOccup', 'Latitude', 'Longitude']\n",
"data shape: (20640, 8)\n",
"description:\n",
".. _california_housing_dataset:\n",
"\n",
"California Housing dataset\n",
"--------------------------\n",
"\n",
"**Data Set Characteristics:**\n",
"\n",
" :Number of Instances: 20640\n",
"\n",
" :Number of Attributes: 8 numeric, predictive attributes and the target\n",
"\n",
" :Attribute Information:\n",
" - MedInc median income in block\n",
" - HouseAge median house age in block\n",
" - AveRooms average number of rooms\n",
" - AveBedrms average number of bedrooms\n",
" - Population block population\n",
" - AveOccup average house occupancy\n",
" - Latitude house block latitude\n",
" - Longitude house block longitude\n",
"\n",
" :Missing Attribute Values: None\n",
"\n",
"This dataset was obtained from the StatLib repository.\n",
"http://lib.stat.cmu.edu/datasets/\n",
"\n",
"The target variable is the median house value for California districts.\n",
"\n",
"This dataset was derived from the 1990 U.S. census, using one row per census\n",
"block group. A block group is the smallest geographical unit for which the U.S.\n",
"Census Bureau publishes sample data (a block group typically has a population\n",
"of 600 to 3,000 people).\n",
"\n",
"It can be downloaded/loaded using the\n",
":func:`sklearn.datasets.fetch_california_housing` function.\n",
"\n",
".. topic:: References\n",
"\n",
" - Pace, R. Kelley and Ronald Barry, Sparse Spatial Autoregressions,\n",
" Statistics and Probability Letters, 33 (1997) 291-297\n",
"\n"
]
}
],
"source": [
"cal_housing = fetch_california_housing()\n",
"print('feature names:', cal_housing.feature_names)\n",
"print('data shape: ', cal_housing.data.shape)\n",
"\n",
"print('description:')\n",
"print(cal_housing.DESCR)"
]
},
{
"cell_type": "code",
"execution_count": 4,
"metadata": {},
"outputs": [],
"source": [
"test_size = 0.2\n",
"random_state = 123\n",
"\n",
"X_train, X_test, y_train, y_test = train_test_split(\n",
" cal_housing.data,\n",
" cal_housing.target,\n",
" test_size=test_size,\n",
" random_state=random_state)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## XGBoost"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"We'll follow the standard process of fitting the boosted tree model and evaluate of regression model metrics."
]
},
{
"cell_type": "code",
"execution_count": 5,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 5,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"dtrain = xgb.DMatrix(X_train, y_train, feature_names=cal_housing.feature_names)\n",
"dtest = xgb.DMatrix(X_test, y_test, feature_names=cal_housing.feature_names)\n",
"dtrain"
]
},
{
"cell_type": "code",
"execution_count": 6,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[0]\ttrain-rmse:1.78053\teval-rmse:1.77867\n",
"Multiple eval metrics have been passed: 'eval-rmse' will be used for early stopping.\n",
"\n",
"Will train until eval-rmse hasn't improved in 10 rounds.\n",
"[50]\ttrain-rmse:0.469279\teval-rmse:0.503594\n",
"[100]\ttrain-rmse:0.419359\teval-rmse:0.477911\n",
"[150]\ttrain-rmse:0.388882\teval-rmse:0.467229\n",
"[200]\ttrain-rmse:0.366135\teval-rmse:0.4603\n",
"[250]\ttrain-rmse:0.348431\teval-rmse:0.457543\n",
"[300]\ttrain-rmse:0.332337\teval-rmse:0.453901\n",
"Stopping. Best iteration:\n",
"[325]\ttrain-rmse:0.325168\teval-rmse:0.45305\n",
"\n"
]
}
],
"source": [
"evals = [(dtrain, 'train'), (dtest, 'eval')]\n",
"\n",
"params_no_constraint = {\n",
" 'nthread': 6,\n",
" 'seed': 0,\n",
" 'eval_metric': 'rmse',\n",
" 'eta': 0.1,\n",
" 'max_depth': 5\n",
"}\n",
"evals_result = {}\n",
"model_no_constraint = xgb.train(\n",
" params_no_constraint, dtrain,\n",
" evals=evals,\n",
" evals_result=evals_result,\n",
" num_boost_round=1000,\n",
" early_stopping_rounds=10,\n",
" verbose_eval=50)"
]
},
{
"cell_type": "code",
"execution_count": 7,
"metadata": {},
"outputs": [],
"source": [
"def mape_score(y_true, y_score):\n",
" \"\"\"Mean Absolute Percentage Error (MAPE).\"\"\"\n",
" mask = y_true != 0\n",
" y_true = y_true[mask]\n",
" y_score = y_score[mask]\n",
" mape = np.abs(y_true - y_score) / y_true\n",
" return np.mean(mape)\n",
"\n",
"\n",
"def compute_score(model, dmatrix, verbose=True):\n",
" \"\"\"\n",
" Computes the model evaluation score (r2, rmse, mape) for the\n",
" input model and dmatrix.\n",
" \"\"\"\n",
" y_true = dmatrix.get_label()\n",
" y_score = model.predict(dmatrix)\n",
"\n",
" r2 = round(metrics.r2_score(y_true, y_score), 3)\n",
" rmse = round(np.sqrt(metrics.mean_squared_error(y_true, y_score)), 3)\n",
" mape = round(mape_score(y_true, y_score), 3)\n",
" if verbose:\n",
" print('r2: ', r2)\n",
" print('rmse: ', rmse)\n",
" print('mape: ', mape)\n",
"\n",
" return r2, rmse, mape"
]
},
{
"cell_type": "code",
"execution_count": 8,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"r2: 0.845\n",
"rmse: 0.453\n",
"mape: 0.169\n"
]
}
],
"source": [
"r2, rmse, mape = compute_score(model_no_constraint, dtest)"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To explore the relationship between the medium income feature and our target, medium house value. We will take one record from our data, impute different values for its medium income feature, and check what's the predicted medium house value."
]
},
{
"cell_type": "code",
"execution_count": 9,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "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\n",
"text/plain": [
""
]
},
"metadata": {
"image/png": {
"height": 359,
"width": 498
},
"needs_background": "light"
},
"output_type": "display_data"
}
],
"source": [
"# change default style figure and font size\n",
"plt.rcParams['figure.figsize'] = 8, 6\n",
"plt.rcParams['font.size'] = 12\n",
"\n",
"# we plot the histogram of the medium income feature\n",
"# to see what's a reasonable range for the data\n",
"plt.hist(X_train[:, 0], bins=40)\n",
"plt.show()"
]
},
{
"cell_type": "code",
"execution_count": 10,
"metadata": {},
"outputs": [],
"source": [
"impute_values = np.arange(1, 11)\n",
"\n",
"# https://stackoverflow.com/questions/1550130/cloning-row-or-column-vectors\n",
"row = X_train[0]\n",
"rows = np.repeat(row[np.newaxis, :], impute_values.shape[0], axis=0)\n",
"rows[:, 0] = impute_values"
]
},
{
"cell_type": "code",
"execution_count": 11,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"array([1.0887971, 1.3267556, 1.4421465, 1.7214452, 1.9341432, 2.3026903,\n",
" 3.1227002, 3.1882827, 2.9910197, 2.8958788], dtype=float32)"
]
},
"execution_count": 11,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"drows = xgb.DMatrix(rows, feature_names=cal_housing.feature_names)\n",
"predictions = model_no_constraint.predict(drows)\n",
"predictions"
]
},
{
"cell_type": "code",
"execution_count": 12,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "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\n",
"text/plain": [
""
]
},
"metadata": {
"image/png": {
"height": 392,
"width": 503
},
"needs_background": "light"
},
"output_type": "display_data"
}
],
"source": [
"plt.scatter(impute_values, predictions)\n",
"plt.title('Medium Income v.s. Medium House Value')\n",
"plt.xlabel('Medium Income')\n",
"plt.ylabel('Medium House Value')\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"From the scatter plot above, we can see that the relationship between median income and median house value is not strictly monotonic. If we find that it is hard to justify that neighborhoods with a low medium income will have a higher median house value, we can enforce the monotonicity on the median income feature. "
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## XGBoost Monotonic Constraint"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"The way to enforce [monotonicity constraint in XGBoost](https://xgboost.readthedocs.io/en/latest/tutorials/monotonic.html) is by passing the `monotone_constraints` parameter."
]
},
{
"cell_type": "code",
"execution_count": 13,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"'(1,0,0,0,0,0,0,0)'"
]
},
"execution_count": 13,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"monotone_constraints = ['1' if col == 'MedInc' else '0' for col in cal_housing.feature_names]\n",
"monotone_constraints = '(' + ','.join(monotone_constraints) + ')'\n",
"monotone_constraints"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"It will be a tuple-like string where 1 indicates an increasing constraint, 0 indicates no constraint and -1 indicates a decreasing constraint. The ordering of the number matches the ordering of our feature in the dataset. In our case, medium income is the first feature in our dataset, hence we indicate we want it to have an increasing constraint (higher the medium income, the higher the medium house value) by passing a 1 in the first number.\n",
"\n",
"> LightGBM has the exact same parameter, except we should pass the constraint as a list of values instead of a tuple-like string"
]
},
{
"cell_type": "code",
"execution_count": 14,
"metadata": {},
"outputs": [],
"source": [
"params_constraint = deepcopy(params_no_constraint)\n",
"params_constraint['monotone_constraints'] = monotone_constraints"
]
},
{
"cell_type": "code",
"execution_count": 15,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"[0]\ttrain-rmse:1.78659\teval-rmse:1.7838\n",
"Multiple eval metrics have been passed: 'eval-rmse' will be used for early stopping.\n",
"\n",
"Will train until eval-rmse hasn't improved in 10 rounds.\n",
"[50]\ttrain-rmse:0.479643\teval-rmse:0.500736\n",
"[100]\ttrain-rmse:0.437175\teval-rmse:0.480962\n",
"[150]\ttrain-rmse:0.413551\teval-rmse:0.474574\n",
"[200]\ttrain-rmse:0.391998\teval-rmse:0.46953\n",
"Stopping. Best iteration:\n",
"[229]\ttrain-rmse:0.381613\teval-rmse:0.466634\n",
"\n"
]
}
],
"source": [
"evals_result = {}\n",
"model_constraint = xgb.train(\n",
" params_constraint, dtrain,\n",
" evals=evals,\n",
" evals_result=evals_result,\n",
" num_boost_round=1000,\n",
" early_stopping_rounds=10,\n",
" verbose_eval=50)"
]
},
{
"cell_type": "code",
"execution_count": 16,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"r2: 0.836\n",
"rmse: 0.467\n",
"mape: 0.177\n"
]
}
],
"source": [
"# we also double-check the model performance\n",
"r2, rmse, mape = compute_score(model_constraint, dtest)"
]
},
{
"cell_type": "code",
"execution_count": 17,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"array([1.041534 , 1.0967472, 1.3294389, 1.6993836, 2.0748453, 2.6741812,\n",
" 3.5940247, 3.7912014, 4.1798806, 4.1798806], dtype=float32)"
]
},
"execution_count": 17,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"drows = xgb.DMatrix(rows, feature_names=cal_housing.feature_names)\n",
"predictions = model_constraint.predict(drows)\n",
"predictions"
]
},
{
"cell_type": "code",
"execution_count": 18,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "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\n",
"text/plain": [
""
]
},
"metadata": {
"image/png": {
"height": 392,
"width": 503
},
"needs_background": "light"
},
"output_type": "display_data"
}
],
"source": [
"plt.scatter(impute_values, predictions)\n",
"plt.title('Medium Income v.s. Medium House Value')\n",
"plt.xlabel('Medium Income')\n",
"plt.ylabel('Medium House Value')\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"After applying the monotonic constraint parameter, the response is now monotonically increasing with the predictor.\n",
"\n",
"So was it a good idea to enforce monotonicity constraints on features? it depends. For the example here:\n",
"\n",
"- Performance-wise: We didn't see a significant performance decrease on the test set after applying the constraint.\n",
"- Interpretation-wise: It is up to our domain knowledge and see whether enforcing monotonic relationship makes intuitive sense.\n",
"\n",
"One can view monotonic constraint a type of regularization and it is upon us, the end user, to fit a model that is as simple as possible, but no simpler."
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## XGBoost Monotonic Constraint Implementation Details"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"When growing a tree within the boosted tree, the algorithm will abandon a candidate split if it causes non-monotonic relationship. Imagine we specify a positive monotonic constraint on a particular feature $f$. Then when $f$ gets picked and a split at value $v$ will result in the best gain. We will check whether the weight assigned to the right child is greater than the left child. If this is the case, then it will proceed with performing the split at value $v$, if not it will give up splitting on value $v$ and trying to find the next best split, until the weight of the right child is higher than that of the left child.\n",
"\n",
"If we look at the [XGBoost code snippet](https://github.com/dmlc/xgboost/blob/97abcc7ee2a67194916fb1be17e55a29ca11ea57/src/tree/constraints.cuh), we can see that if the positive monotonic condition is specified `if constraint > 0`, then we check the weight of the right child versus left `wleft <= wright`, if the constraint is met, then the gain is retained `? gain`, else the gain is replaced by negative infinity `? negative_infinity`.\n",
"\n",
"\n",
"\n",
"Now this sounds good when the feature is picked once, however, what if on a split further down the tree that feature gets picked again? Let's imagine if the tree goes on and do the same thing to the left child (L) which happens to pick the same feature again, we will get a higher weight assigned to the right child of the left child (LR) because of the positive monotonic constraint we enforced. That weight, however, may be even higher than that of the right child (R) we previously obtained. In other words, we need to have make sure the constraint is enforced at the tree level. Not only should the weight assigned to the right child (R) be higher than the left child (L), but it should also be higher than its descendant that decides to use the same feature (LL, LR, LLL, LLR, LRL, LRR, etc.)\n",
"\n",
"To achieve this, when splitting on a node, the weight of the children node is bounded by the mean of their parent and uncle nodes weight (uncle refers to the same level as the node's direct parent).\n",
"\n",
"Using a similar example stated above: the weight of the left child's right child (LR) is now bounded by the left child(L) and right child(R)'s mean weight. And because the weight of the left child(L) is lower than the right child(R), the weight of the left child's right child (LR) can never exceed the weight of the right child(R).\n",
"\n",
"\n",
"\n",
"\n",
"Or if preferred the psuedocode below:\n",
"\n",
"```python\n",
"min_value = node.min_value\n",
"max_value = node.max_value\n",
"\n",
"check(min_value <= split.left_output) \n",
"check(min_value <= split.right_output)\n",
"check(max_value >= split.left_otput)\n",
"check(max_value >= split.right_output)\n",
"mid = (split.left_output + split.right_output) / 2;\n",
"\n",
"if (split.feature is monotonic increasing) {\n",
" check(split.left_output <= split.right_output)\n",
" node.left_child.set_max_value(mid)\n",
" node.right_child.set_min_value(mid)\n",
"}\n",
"if (split.feature is monotonic decreasing ) {\n",
" check(split.left_output >= split.right_output)\n",
" node.left_child.set_min_value(mid)\n",
" node.right_child.set_max_value(mid)\n",
"}\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## LightGBM Monotonic Constraint"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Specifying monotonic constraint is also available in lightgbm, expect the parameters are a little different from xgboost."
]
},
{
"cell_type": "code",
"execution_count": 19,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
""
]
},
"execution_count": 19,
"metadata": {},
"output_type": "execute_result"
}
],
"source": [
"dtrain = lgb.Dataset(X_train, y_train,\n",
" feature_name=cal_housing.feature_names,\n",
" free_raw_data=False)\n",
"dtest = lgb.Dataset(X_test, y_test,\n",
" feature_name=cal_housing.feature_names,\n",
" free_raw_data=False)\n",
"dtrain"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"To specify the monotonic constraint, we use a list of integers instead of a tuple like string."
]
},
{
"cell_type": "code",
"execution_count": 20,
"metadata": {},
"outputs": [
{
"name": "stdout",
"output_type": "stream",
"text": [
"Training until validation scores don't improve for 10 rounds.\n",
"[50]\ttraining's rmse: 0.488685\tvalid_1's rmse: 0.503612\n",
"[100]\ttraining's rmse: 0.444494\tvalid_1's rmse: 0.48004\n",
"[150]\ttraining's rmse: 0.422314\tvalid_1's rmse: 0.473423\n",
"[200]\ttraining's rmse: 0.405314\tvalid_1's rmse: 0.470076\n",
"Early stopping, best iteration is:\n",
"[216]\ttraining's rmse: 0.40057\tvalid_1's rmse: 0.469415\n"
]
}
],
"source": [
"monotone_constraints = [1 if col == 'MedInc' else 0 for col in cal_housing.feature_names]\n",
"\n",
"params_constraint = {\n",
" 'nthread': 6,\n",
" 'seed': 0,\n",
" 'metric': 'rmse',\n",
" 'eta': 0.1,\n",
" 'max_depth': 5,\n",
" 'monotone_constraints': monotone_constraints\n",
"}\n",
" \n",
"evals_result = {}\n",
"model_constraint = lgb.train(\n",
" params_constraint, dtrain,\n",
" valid_sets=[dtrain, dtest],\n",
" evals_result=evals_result,\n",
" num_boost_round=1000,\n",
" early_stopping_rounds=10,\n",
" verbose_eval=50)"
]
},
{
"cell_type": "code",
"execution_count": 21,
"metadata": {},
"outputs": [],
"source": [
"impute_values = np.arange(1, 11)\n",
"\n",
"# https://stackoverflow.com/questions/1550130/cloning-row-or-column-vectors\n",
"row = X_train[0]\n",
"rows = np.repeat(row[np.newaxis, :], impute_values.shape[0], axis=0)\n",
"rows[:, 0] = impute_values"
]
},
{
"cell_type": "code",
"execution_count": 22,
"metadata": {},
"outputs": [
{
"data": {
"image/png": "iVBORw0KGgoAAAANSUhEUgAAA+4AAAMRCAYAAAByIOxyAAAABHNCSVQICAgIfAhkiAAAAAlwSFlzAAAWJQAAFiUBSVIk8AAAADh0RVh0U29mdHdhcmUAbWF0cGxvdGxpYiB2ZXJzaW9uMy4xLjEsIGh0dHA6Ly9tYXRwbG90bGliLm9yZy8QZhcZAAAgAElEQVR4nOzdebxdVXnw8d8TIySQIMQgg4pEA6IoVaZY4hwH6gAWFadio/hWqxVqnUDfVotVcKgVUV86UIIoVapU64RD1LZGCZNaEQWioCgYDAgkQICQ5/1j7eM93JzpnrvvvTsnv+/nsz/77LPXXmudad/77LX2WpGZSJIkSZKkZpo10xWQJEmSJEndGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLaryIWB4RWS1Pnuh+SZoOEbFf27nohInul7Z1EXFz9fv43EzXRWoaA3dpxETE3m3/GLaWZQMeu3z8sVNdX01eRHy77TPbe6brIw0qIn4z7pzz9gGP26/Dee5xU11fTU5EnNL2eb14wGNe48WO+kTEOybzfkbEv7Qd/6KpqKOkzgzcpW3D8gHTvWIqKyFJffzpgOk8V0nDWQG0LsoP+nsDICJ2AI6uNm8CbBWXppGBuzTa7qjWR0XE/F4JI+KhwBPGHbdVyMwVmRnV8u2Zro+kCWudc/aJiKW9EkbEfYA/GXfcViEzf9p2rjplpuujbU9m/gL4ZrW53wR7qjwfaP0vcU5m3llr5ST1ZOAujbYvA3cD7VfJu/lTIIC1wHenuF6S1O5K4PLq8fI+aZ8B7Fk9/o+pqpA0wv617fHyCRzX3tPlzHqqImlQBu7SaFsHfLF6vLxboogI4OXV5ieBTVNbLUnawlnV+uiImNsj3fJq/V3gqimtkTSa/gO4pXr8ooiY0++AiHgI8ORq84eZeekU1U1SFwbu0uhrXRV/fEQ8rEuapwB7j0s/kIg4LCL+OSKuiIhbI+KOiLg6Ij456AjvEfHIiPjXiPhFRGyMiOsj4ssR8bwBj+836vw7Bx28rS3dig772gf+e2f13GER8amIuLaq+88i4mMR8aBxx+4XEadHxFXVe3RDRJwbEY8a5DVORqf3JyKOjIivVIOD3RkR11Sf40MHzHNeRBwfEV+NiOuqPG6vvgefjIgXR8T2PY5/fEScFRE/r45bHxE/rd67/fuUvaJ98MSI2CEiToiISyPiloj4XUSsGj/4VUTMjohXRsT/RMRvq3J/GBF/FRGzB3zdk/6+d8n3hW2f0Z8NkP5hbelPH7LMh0bEB6r37eaIuDsi1lWv7SsR8cZBvw81ORu4B9gJOKpLnXcBjqw2J3quWhQR76te743Vd/b6iPhiRPxJlC74/fJYWOXxk+r7sy4ivhsRrxvkOxT9R50/PAYcvC0iLqjS/bTL/tbAf+dX2w+NiI9ExJrqe/vriDgvIg4ad9yuUc6ZP6p+lzdHxMqI+KN+r2+mVb+LD0XEZdW54I4of1f+LSKe0efY9oHzdu+Rbk6/315EbBdlUL2vV9+xuyJiQ5Tz7OqI+PuIeHqf+uwUEW+OiG9Vn+Vd1fftOxHx1ojYabB3ZUuZeQfwb9XmzsAgf2tbvfKgy28vIh4XEe+OMmDq9dVv7LYo5/lzIuJpw9a5yn/ntvf+Q33Sfqgt7c590j4lIs6M8vd5ffXb/lmUv1EOeqnmyEwXF5cRWigBeFbL6cBs4DfV9ru6HPPxav/F1fb5rTx6lDMX+ERbWd2Ws4Dte+SzHLirx/H/WKVpbT+5Sx699r+zbf/efd6/VroVfd7bdwJ/RQk0OtX7OmDf6rijgdu7pLsdeMIkP/Nv93p9496fp1K6SXZ7v28GDu1T3h8Bvx3gs39eh2NnA//S57hNwN/0KH9FW9oHApf1yOsD1TE7A9/oke7zwKyp/r73yH974HdVHt8ZIP3ftpV52BDlvRDYOMDr+chkvpsD1KN1bvpBtf2lavvrXdK/ttp/GyXAf2dbXR/Xo5y30fs8k8D3gN175HEopRdTt+O/AxzStn1Chzz267P/8Lb9L+7z3l1Qpftpn/f2fMrtBbd0qfedwLOrYx4LXNvjNf7FJD/vUwZ9fW3HvKbXe9aW7rgBPuNzgTkD1K3X92BOW7rTO+zfg97npNayoUcZh/f5riVwfa/v/ADva/t39fw+aQP4Wdv35f4d0iwf4DUn5QLdfXuUdXOV7nMd9u3cls+H+tT5Q21pd+6SZj6l90Hf8yAwezLffReXOhZb3KURl5mbKN3fAV4eEdG+PyLmMda6tWKQPKuWqS8CL6ueWgm8ktJyf3D1/H+1yqRcQOiUzzMoQeR9Kf9wfZASWB5C+SfgR8CfAX8+SL2m2eHAB4DvA8dQXvfTGGvF2AP4p4g4lPL+/5ryD+gSyiCAH67SzQXOioj7TlO9T6Lcp/gl4AXAQZR/6s+p9t8P+GS31sOIOILy2S8ENgOfolyYOITy2l5Cudiyrkv5pwPHVo9/Rfln+3HA4ynB1c3AfYC/7dQi2cFngIcBf0/57hxM+c78ptr/xigt4WdRvp//QvnsDgJeylhX6yMo3+FOr7mW73svWQZ5OrfaXDpAS3drcLY1mTmhMSki4oFUFxiADZTf3bMZ+wz/GHg38MOJ5FuTFdX6qRHx4A77l1fr/8jMWwfJMCJOobye+1Luoz+Ose/AkYxdkHkc8OXo0G24qstXgftXT50LPKfK4yjgK8BSyj/4TbMXpb7rgb+kvM7DgPdQLpJtRzkH7U05L+wI/DXlPHUo8FbKhRKAv4/uPbdmTES8CjiV8hnfRvm8n0Sp/6sZ+52/kLFz9FQ5HWj1Gvoy5bf6BOBAyt+I4ygXCjsO7BYRz6Gcb+5POY+eRGkRPxhYRrnAsAHYHTg/IvYdppKZeRHlAgPA06vzQjdPBFrnpC9k5o0d0symnL/PBv4P5f0/kPJbewMl8IfyfvzdMHWuU5QeYd9grLfBlyjnlycx9j/I6mrf64D3T28NpQ5m+sqBi4tLvQvjWtyr5x7V9tyycelfWT2/EVhQPdezxR04sdp/F3Bkj7p8sK3cx4/bNxu4pi2fp3Q4fntKkNR+5fvJHdIt77P/nW379+7z/rXSrejz3ibwn3RoOQA+25bmBuBCYH6f96fr+zjAZ/7tXq+PLVtC3tkln/aW+CM67F/IWKvd7cAzetRpLrBw3HPL2vL/MZ1bbR7GWEvh3cDiDmlWtOVzJx16LACPYaw3xA3V+kUd0u1JCWgS+P5Ufd8H/BwP6/cZVeke35aua8+EHse/tu34Z/ZJu8VnVOfCli3u2wM3Vs+9fVzaR7bVe1n13Dvbntui9ZFyMef37yldelUAL25L96YO+z/Ta3+V5gPjfmdNaXFP4Apg1w5p3tKW5oZq6fSbO7ot3cmT+LzbW7XfRPnb1G85qc97tislWE/K+ekPOqTZse396vjeUkOLO6UFd1O1798m+tuiBOs3Vcd/Gdixy7GPbPudfHESn8df9Xpv29Kd2ZbuWV3SPBDYoUces4HzGPt/4wFd0k1LizvwXsb+li3rkscs4Iwq3Wbg0cO+1y4udSy2uEvbgMy8DLik2lw+bndrlNgvZOZN/fKKMo/rG6vNUzPz8z2Sn0DpzgflCny75wAPqR5/LDO/1aHed1b1u7tfvWbARuDYzOxUt4+2Pd4VeGVmru+Qrr117kl1Vq6H71O6WXfS3qLQqT6vp3RPBnhbZn6tWyGZeUdmjm91P77t8SuzQ6tNZv6Mse/XbOAvupVROS0z/6dDPj8AVlWbuwKfycxPd0h3HWMjk//B+PtGa/y+95Wl5XxNtXlMj6StfUm5zWWiWvfvJuWiT686dWpZmzLVb77VIvqn43a3zlW/ZGw6q37+b7X+n8x8Z2Zu7lLupygtbjDus4syXkWrVe6CzPxAl7JOZOzza5rXZeZvOzx/OmODke4KnJiZnV7Dv1NmHIH6zlXvp/Sq6rf8dZ98/g9l5hQoF7K26CmSmbdResO0Pv+/nGzlu9iV0mMIYIu/aePq1Om39TpgF+BW4GVVvTsdezlwcrX57IjYs1O6AZzN2N/X5Z0SVL3yXlhtXkfpedKpTr/OzNu7FZSl91/rfd+e0stnRkTEAsp7DfDuzFzZKV11vjiOckEogFdNTw2lzgzcpW3Himr9+zndqy6Pjx+3v58nMtZd9JxeCTPzLsamlhs/N/Mz2x7/S488fgl8fcC6Taevd/lHGOAHbY9/VF042UJm/pzS2guwqM7K9fDJzMwu9fkJpQsmjHWLbHdEtb6V0h1+YFV386dWmz/MzNU9kp9LaXWC0o2/l17fwfbPoVf32Fa6YMvPoa7v+6DOrtYPjYjHj99Zde9sTe34P5l5zRBl/KqVHWO3LTTJimr9+znd495zt3+823e4XfXP+ZOrzUG6R3+7Wu8bEbu2Pb+MsWDsjG4HVxfxhrmQMtVuyMxvdNqR5XaDq6vNexi7XWN8ugT+t9qcrnPVoFrniLvoMWBhZl5J6cEFcGhE3G8K6rKWsQshL43esyN00rpt7fzM/F2ftN9ue3zYBMsBoPob1pp55uER8Ycdkr2A0mMBym/vnkHyjoi5EbFXlMFnHxVlINadKBe9oYynMFOewdhr6ndevw24uNoc9rwu1cLAXdp2nEPpVtw+p/vyan09pXv8IA5te3xp26itHRfg+VXaPcblc0C13kDpNt1LryBvpnQcybly84Dp2tMOPULwBPWrT+ufxfEtz7MZ+8xWZxmVeCIeytg/St/rlbAKgC6qNvfrc/9/HZ9De7rxn0Nd3/dBnU1pCYexKRrbHUHpLgrDB4mfZexz/mhEXBQRb4+IJ1atazMqMy9m7N7b5dX6cMZ6CqwYMKuDGRsF+2MDfHbtPU7aRxU/oO1xv3NRE89VV/TZ3/r+X9elZ9D4dHWdq16SmdFvof8YJ4+u1pdn/3EPWhfWou242lRBXusi0ZOAX0SZKeP5EbFXr2OrsRVadTp6gO/rRW2HD3u+gXtf7FjeYX/7c10vjMDvZ114d0S0LgL/gvL3vb0HRWsMiYVD1rcO7ef1nw/wXi+r0k7mfZYmzcBd2kZU3eC/UG0uj4hZjAUGnxj0KjrwgCGrsMO47VYr5m8HaD1b22f/TOjVJXDzIOkqrbR9p6KqSceul2261ef+jP3NuG6Icu/f9vg3XVNtmSaABd0S9eqaydhrgd6fQ3u68a+7ru/7QDLzaqDV9f+FHQZKa3WTv4PSfXmYMm6kzAzQGizqYMpgUf8F3BxlmrG/Gn/bwDRbUa1bc7ovr7b/p7qdYhDDfnZw78+v/bvb71y0VZ2rKq3vf9POVX1Vf8d2qTYncl6Be3+udXot0LotZ1fKhYfPUIL4X0TERyOi00WDhQz/f/lQ55vKVxh7X+41p3s1SOYTq81VVa+FjiJiCeUi0dsoYzn0ey0T7Y1Qp2k9r0t1GWjeWkkjYwWl29vjKfcF7tX2/KDazxvPYOyeXmkUzcT3/eOUf5Z3Bp5LFaBX3bcPr9J8boDWxa4yc3VE7EcZa+I5lHPCwylB2ZJqeWtEPD8zvzNsOZPwCcpgYTtR7itt3aaxYgJ5tH92b2bwXkUwdlFDmpDM3AC8OCL+jtK77cmUUcrnUP7mvhb484h4b2ae2HZo+/f1XOBdEyh2kIsW3eq7KSI+Thmo8H6UWSXax5noOXc7QETsSOnJs4Bygeefqu2fUkbGv7N1gT4ibqUM4hedc5sW7e/1HzJ2i1g/gzZwSFPCwF3atpxPCTz2oIy4CnBhNdDNoNrv67652/3bA2gNzLNrRESfVvfdhiyjpf2PbddWgOqfD3V2I+UfslmUkdiHOb5l966ptkyTjN3vPhPq+r5PxL8Dp1FapF7OWMv6iynTXUEN91JXg0V9rlqIiIWULqHLKRcIHgB8LiIeOpmLBEPWbW1EfIVy4eJ9lCnLbqPLPdhdtH92d9ZwroJyLrqhR9ppOVdVtvnzVWZujojfUQLGiZxX4N6fKwz+3g/0vlfft8sAImI7SvfsP6ZMVzkPOCEiLsvM1nSt7YN5zp6mc03LmZTAHcrv/98iIhjrlXcbY70IOnk2ZVR5KAMcvq9Touq2p8ncjlPX76P93HBjZl7VNaXUIHaVl7YhVXf4T1Sbre5wKyaYzSVtj5/YNVV/rYGO5jE25203SyZRDowNAAdj3So7ecQkyxlZVZDXGq15yRCDLv2csVaNx/VKWN1Pf0i1+ZMuI/dPl7q+7wOrguTW6PWHtw2U1von+nqmYMDGzFyXmZ/OzD+iTA0IpTvx0+sua0ArqnXrXPXZqjVzUJe2Pa7jXAX9z0XTcq6qAqDGzac+Q1qfzyNbA6/20BrEbTPlfut2U/Z3IjPvyszvZOYbgWe17XpxW5oNjI1HcFg1IOO0yMyfMjb2yNOqOd2fQpkCFcqsHL1+e+1d/z/VI92BTK6lvTXtH/T+jKD35zTt53WpDgbu0rbnTMqorndSRgcfZLTldiur4wBeV02XNYz2KWW6TrFSDegz2cDh522PD+maamzUanXWCiZ3orQaDay6aNSawusxEdHrc3ghY/e1d51ybprU9X2fqLOq9WzK6NT7Ue5FBzhnAmNSDKv997lr11RT6wuU8RTurJaeA2ONl5nXMxaMHBkR+wxZj5WMtfR1HYW/CqY7DSg4EYOeq57PzN4j3CStc8R2dJnSDCAiFjM2s8WFmXnLuCTT8neimr6yNbjn+N/WedV6d3pPCTkVWhfrWuPfLO+wr5v2Hry9zpGvnXi1xlTjx1xTbXb9jKoZczqNkN/yFcZGtz++zwCoUmMYuEvbmMz8SWbOzcw5mXm/zLy5/1H3On490JrHeBGlS13ProMR8fTWtE5tvkgZcRbgtRHxlA7HbUf5Z32yf1S/y9hcta/vMOAXEfF0xuZ1VWcfYWxk6ZOr96yjaiqg8aMGn9r2+F8jYosWk4hYBHyw2twEfHQS9Z20Gr/vE/V1xu6nfzn3DgjP2jL5vco/vG1E5C3u646IQeZ9PrztcXtAQ0TMact/I1MkM+/OzAdW56o5mfntIbJ5R7W+L6Xb/0N6JY6I/SPiBePq8Suq2wmAx0XEm7ocfjKweIg6tpd1A/CTavMF1e9hfB3bfyMq04m2Bt08Kcq0Y/dSXXD7OGMD631ofBrKoJCtAfiOr/7+jM/n2ZTxYTqKiH0jouc89xHxRMYuuvx83O4PUuYMBzit09/FcXk9ICImFQy3+TRjAxS+irGp6X7G2ICZ3bQPWre8U4KI+FMmf2ELxqbBe3hEHDF+Z3V+PoseMU5mrgU+Vm0+GlgRZarNjqJ4TkQcNHStpRoYuEsaxnsYa5E7ArgiIv4mIp4WEY+JiD+MiKMj4v0RsYbSInKvbmtV1+s/o3R7uy9wfkR8ICKeHBEHRcTLKdPdPBW4cDKVzcx1jPUseCTw7Yg4KiIeGxHPiIiPAl+imVM5NUY1GvmfUv65nUv5zM6JiBdExMERcUhEvLB6P39JGfCs/fhvMjYP9qOAH0TEX0TEkog4LCJOoMyX27oP9a8zc810vLY+Jv19n6iqRb01v/CBjE2J9YPMHN/Fd6KOoYxw/fWIeFNEPDMiDqxex4sj4j+BV1RpL2esp8RWJzO/ThkxH8pv/7KI+HBEPLc6zxxaPf6biFhNuSf58A5ZvYGxi1bvj4hPRcSzqvfteRHxJeCNTPJcVTmtWu8I/FdEHFuV84SI+GvG5pQeH/Rtk6q5yP+y2twZ+F5EnFS9X4dExKuA7zPWAvu5zNzifu2qh8Znqs3HAN+MiCOrvxPPjIjTKRdwek1n+VDK35crqvPB0RHxuOrzOzwi3svY7C6bGQseW3VYR+k+v4lyG9k3IuLfI+Kl1XnywOrC4Bsi4ovAr4C/msj71U11kbL1+tun7zxzgJlfPsfYBYe3RMRZbb+PIyPiU5SL8D+g/8wm/XyMsQss50TE26r35tCI+HPKZ30o/X+LbwNWVY9fCvwkIk6MiKdW5/XDIuIlEfEhSiv/FygXb6WZk5kuLi4jtFDuSctqOX3IPM5v5dEjzXaU1tB72srrtmwGju6SzyuAu3oc+/8oV/Bb20/ukEfP/VWa+1P+Ke9WzsWUbout7RV93tt39nkPu+YzLt01VbpvT+Iz/3ZbeXsP8/5MpD6UgYhuHOBzf16HY2dTgvdex90D/E2P8lf0+35W6d7Z632Z4Penlu/7BD/XAzrk/YYBjju8Lf35HfZ/aoDXkJSg/aEdjp/TlmbjJF/jb6p8fjDk8e2f8eN6pHsdpTVxkNf9913yWEIZQKzbcf9DuZ2htX1Chzz267W/SjOL0mW6WznXAQcBF1TbP+3z3m7xHRiXrmc+Hb43Q3/mlJkCWq/jxQMe85p+71mV7jh6/y1JykCPc3rksRvlPvNux19AGZyztX36uOMP71N+a7kDeEWPejwRuHbAvC6ZzG9wXLlPGpf3PcCDBjz2SEr3817nk4dQLoAl5QJKp3x67q/SnNDnvX0ppVdF67mdu+SzA21/T/os9wCH1/Veu7gMs9jiLmkoWQbbeR1lYLkPUALfGyl/3G6jdK/7AqUVanFmdhwNOjPPBB5L6dr2K8o/Xmsp96D9cWb+eafjhqjvjZQWl5Mo/0DcQRmM6JKqjodlablRH5n5JUqLzFsoc3//ltJCdDvln96zKffgfqnDsZsy81jgCVW6qyn/7N1G6W55OvAHmXnS1L+SwdX1fZ9gmf9LaaFq2cRYK/xkvA54GfDPlF4mv6D8Hu4Efk353I6lfA4j0aqbmR+lBA1vB75FOcfcTfnu/YpyH/u7gEOyDCDWKY/VlJ4UH6B8VzdSZjy4AHg9ZTCviQye162umynjPLya0rq7nvL5XEEZYf8xmXlJ9xy2TZn5YUqvilMp5/j1lO/0LyndwJ+ZmS/MzK63d2TpQn0o8G7KLQsbKWNcXERp1X8CvWe5+AZl+rd3U253uYISiG4Cfkf5vb0HeHj1t69bPf6bctvFsZTW7F9SvgN3U863F1B6ZjybyQ+I2O6/ufdUiF/PcqtIX5n5ecqFq09QziN3U86RqynTMR6cmb/onsPgMvMUykWSr1A+j7so79EKym94oPNkZt6emcuBP6B8b75f5XcP5bd8FeX9P55y8XciU0pKtYvMnOk6SJIkSZKkLmxxlyRJkiSpwQzcJUmSJElqMAN3SZIkSZIazMBdkiRJkqQGM3CXJEmSJKnBDNwlSZIkSWowA3dJkiRJkhrMwF2SJEmSpAYzcJckSZIkqcEM3CVJkiRJarDZM10BFRFxNbATcM0MV0WSJEmSVL+9gVszc9FEDzRwb46d5s6du+ARj3jEgpmuiCRJkiSpXj/5yU+44447hjrWwL05rnnEIx6x4JJLLpnpekiSJEmSanbQQQdx6aWXXjPMsd7jLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNdjsma7AVImIecBPgAdVT70iM1cMmdfuwInAc4AHArcAFwIfysyVk6+tJEmSJGkYV65dz6o169iwcRPz5sxm6eKF7Lvb/JmuVq1GNnAH/o6xoH1oEXEA8E3g/tVTtwILKUH8syPibZl5ymTLkSRJkiQNbtWadZy68iouvPqmLfYdumgBxy/bh6WLF85Azeo3kl3lI+JA4C+A1ZPMZy7wn5Sg/fvAozLzfsAuwN8DAbwnIp4xuRpLkiRJkgb16Yt+yTFnrO4YtANcePVNHHPGas696NpprtnUGLnAPSJmAf9Ybf75JLN7NfAQYAPw3Mz8MUBm3pqZbwI+RwneT55kOZIkSZKkAaxas44Tz/sRm7N3us0JJ5z3v6xas256KjaFRi5wB14PHAz8v8z8/iTzelm1Piczf91h//ur9YER8fBJliVJkiRJ6uPUlVf1DdpbNid8eOVVU1uhaTBSgXtEPBB4F7AW+L+TzGs+cFC1+dUuyS6gDFQHsGwy5UmSJEmSerty7fqu3eO7WX31TVy5dv0U1Wh6jFTgDpwGzAfelJm39EvcxyMo3eABftwpQWZuBq6oNh85yfIkSZIkST0M2+19a+8uPzKjykfEc4E/Br6dmZ+oIcs92h5f1yNda98ePdL8XkRc0mXXfoMcL0mSJEnbqg0bN03rcU0xEi3uEbEj8BHgbuB1NWW7Y9vjO3qku71az6upXEmSJElSB/PmDNf2POxxTbF1137MScBewPsy8/KZrkwvmXlQp+erlvgDp7k6kiRJkrTVGHZe9q19PvetvsU9Ih4DHA9cSwng63Jb2+O5PdLtUK031Fi2JEmSJGmcfXebz6GLFkzomCWLFrDvbvOnqEbTY6sP3IFTgfsAbwciIua1L23ptq+e26FzNltov699zx7pWvuuH7zKkiRJkqRhHL9sH2ZF/3QAswKOW7bP1FZoGoxC4P6Qav1xYH2HpeX0anvQrvQ/BVqzA+7fKUFEzAJa87c3uou+JEmSJI2CpYsXcvJRj+4bvM8KOOWoA7b6bvIwGoH7lMjM9cDF1ebTuyRbAtyverxyyislSZIkSeJFh+zF2ccuYUmXbvNLFi3g7GOXcPQhD57mmk2NrX5wuszcu9f+iGi1mr8iM1dMMPtzgEOAl0XESZk5vjv8m6r1JZl5BZIkSZKkabF08UKWLl7IlWvXs2rNOjZs3MS8ObNZunjhVn9P+3hbfeA+GRGxN3B1tdkpsP9H4C8p3fG/GBHHZOblETEf+GvgqCrd26a+tpIkSZK2FttCMNkU++42f+Tf2206cO8nM++IiCMp3eAPBH4cEbdS5myfRbkH/m2Z+bUZrKYkSZKkhli1Zh2nrp6h+44AACAASURBVLyKC6++aYt9hy5awPHL9hmJe641vbzHvY/M/CHwKODDwM+B7YEbgS8BT8/MU2awepIkSZIa4tMX/ZJjzljdMWgHuPDqmzjmjNWce9G101wzbe1GvsU9M7uONZiZ1wB9JxLIzN9Q5oo/vr6aSZIkSRoVq9as48TzfsTm7J1uc8IJ5/0vD9xlri3vGpgt7pIkSZI0SaeuvKpv0N6yOeHDK6+a2gpppBi4S5IkSdIkXLl2fdfu8d2svvomrly7fopqpFFj4C5JkiRJk7BqzbppPU7bHgN3SZIkSZqEDRs3Tetx2vYYuEuSJEnSJMybM9yY38Mep22PgbskSZIkTcKwo8M7qrwGZeAuSZIkSZOw727zOXTRggkds2TRAvbdbf4U1UijxsBdkiRJkibp+GX7MCsGSzsr4Lhl+0xthTRSDNwlSZIkaZKWLl7IyUc9um/wPivglKMOsJu8JsTRECRJkiSpBi86ZC8etMsOfHjlVazuMK/7kkULOG7ZPgbtmjADd0mSJEmqydLFC1m6eCFXrl3PqjXr2LBxE/PmzGbp4oXe066hGbhLkiRJUs323W2+gbpq4z3ukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNNhKBe0QcHBHviojzI2JNRNwSEXdGxK8j4vMR8bwh810eEdln2VD365EkSZIkqWX2TFegJq8CXt22vQHYDOwJHAEcERGfBV6SmXcPkf/dwE1d9t02RH6SJEmSJA1kJFrcge8BbwAOAuZn5vzMnAvsBby/SvN84IQh8/9uZu7eZXnY5KsvSZIkSVJnI9HinplndXn+WuAtEbEH8CfAcuBd01g1SZIkSZImZVRa3Pu5qFrvOaO1kCRJkiRpgraVwP2wan31jNZCkiRJkqQJGtnAPSLmRcQBEfFR4EXV0x8ZMrv9I+LHEXFHRKyPiMsi4h8iYlFN1ZUkSZIkqaORuMe9JSIeBFzbYddG4N2Z+bEhs14I3B/4HbATsH+1vDoiXpWZ5wyZryRJkiRJPY1U4A7cA6ytHu8CbAdsAk4GPjpEftcB7wA+C1yVmXdFxPbAMspo9Y8EzoqIX2Xmfw+SYURc0mXXfkPUT5IkSZI04kaqq3xmXt+apg2YCzwc+Djwt8APImL/Ceb3tcw8KTN/nJl3Vc/dmZlfptw3v4Zy8eOUWl+IJEmSJEmVUWtx/73M3AxcCRwbETcDfwWcHREHV/smm/8tEfEe4F+Bx0XEwsxcN8BxB3V6vmqJP3Cy9ZIkSZIkjZaRanHv4bRq/dhqqcvqah2AA9VJkiRJkmq3rQTuv257/LAZq4UkSZIkSRO0rQTu7a3hG2rMd0nb42tqzFeSJEmSJGAEAveIuE9ERJ9kb67Wm4DvDZhvzzwjYifghGrzwsz87SD5SpIkSZI0EVt94A48GLg4Il5ZzeMOQETMiojHRMQngVdVT5+Wmb9rS7N3RGS1LB+X70Mi4oKIODYi9mo7ZruIOBxYBewLbAZOnKLXJkmSJNXqyrXrOXPV1Zy28irOXHU1V65dP9NVktTHqIwqfyBwBkBEbKR0h58PbN+WZgXwlgnmu6RaWvneBuwE3Lfafzvwmsz85rAVlyRJkqbDqjXrOHXlVVx49U1b7Dt00QKOX7YPSxcvnIGaSepnFFrcrwNeBPwT8APgFmBn4G7gckpA//jMfEVmbppAvmuB44BzgSsoQfr9qvXFwHuBR2bm2TW9DkmSJGlKfPqiX3LMGas7Bu0AF159E8ecsZpzL7p2mmsmaRBbfYt7Zt5FCa7PHeLYayhTuXXadwdlGrnTOu2XJEmStgar1qzjxPN+xObsnW5zwgnn/S8P3GWuLe9Sw4xCi7skSZKkLk5deVXfoL1lc8KHV141tRWSNGEG7pIkSdKIunLt+q7d47tZffVNDlgnNYyBuyRJkjSiVq1ZN63HSZoaBu6SJEnSiNqwcSJjM0/+OElTw8BdkiRJGlHz5gw3FvWwx0maGgbukiRJ0ogadnR4R5WXmsXAXZIkSRpR++42n0MXLZjQMUsWLWDf3eZPUY0kDcPAXZIkSRphxy/bh1kxWNpZAcct22dqKyRpwgzcJUmSpBG2dPFCTj7q0X2D91kBpxx1gN3kpQZy1AlJkiRpxL3okL140C478OGVV7G6w7zuSxYt4Lhl+xi0Sw1l4C5JkiRtA5YuXsjSxQu5cu16Vq1Zx4aNm5g3ZzZLFy/0nnap4QzcJUmSpG3IvrvNN1CXtjLe4y5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNZuAuSZIkSVKDGbhLkiRJktRgBu6SJEmSJDWYgbskSZIkSQ1m4C5JkiRJUoMZuEuSJEmS1GAG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYLNnugKSJEkSwJVr17NqzTo2bNzEvDmzWbp4IfvuNn+mqyVJM87AXZIkSTNq1Zp1nLryKi68+qYt9h26aAHHL9uHpYsXzkDNJKkZ7CovSZKkGfPpi37JMWes7hi0A1x49U0cc8Zqzr3o2mmumSQ1h4G7JEmSZsSqNes48bwfsTl7p9uccMJ5/8uqNeump2KS1DAG7pIkSZoRp668qm/Q3rI54cMrr5raCklSQxm4S5IkadpduXZ91+7x3ay++iauXLt+imokSc1l4C5JkqRpN2y3d7vLS9oWGbhLkiRp2m3YuGlaj5OkrZmBuyRJkqbdvDnDzUo87HGStDUzcJckSdK0G3Zedudzl7QtmpJLlhFxAPB04MHA3Mx8ddu++wK7ApmZ109F+ZIkSWq2fXebz6GLFkxogLolixaw727zp7BWktRMtba4R8T9I+ILwPeB9wHHAa8al2w2cAlwbRXgS5IkaRt0/LJ9mBWDpZ0VcNyyfaa2QpLUULUF7hExF/gG8CzgBuBs4Lbx6TLzDuD0quyj6ypfkiRJW5elixdy8lGP7hu8zwo45agD7CYvaZtVZ4v7XwB/AFwK7J+Zy4ENXdJ+tlo/scbyJUmStJV50SF7cfaxS1iyaEHH/UsWLeDsY5dw9CEPnuaaSVJz1HmP+9FAAq/PzH43K10ObAL2q7F8SZIkbYWWLl7I0sULuXLtelatWceGjZuYN2c2Sxcv9J52SaLewH1f4G7gwn4JM3NzRNwC7Fxj+ZIkSdqK7bvbfAN1Seqgzq7ys4G7M3Nzv4QREcA8OtwDL0mSJEmSxtQZuP8K2CEi9hgg7eOA7YGf1Vi+JEmSJEkjp87A/evV+s96JYqI+wDvodwP/5Uay5ckSZIkaeTUGbh/ALgLODEilndKEBGPBb4KPAlYD3y4xvIlSZIkSRo5tQXumXkN8PIqzzMi4gZgF4CIuDAirgcuBp5KCfBfmpm/rat8SZIkSZJGUZ0t7mTmv1PmZr8QWAhsBwRwMLBb9fhi4EmZ+eW6yo2IgyPiXRFxfkSsiYhbIuLOiPh1RHw+Ip43yfx3j4hTI+JnEbExItZGxBciYlldr0GSJEmSpE7qnA4OgMy8APjDiNgXOAzYg3KBYC3wvcz8cd1lAq8CXt22vQHYDOwJHAEcERGfBV6SmXdPJOOIOAD4JnD/6qlbKRclngM8OyLelpmnTLL+kiRJkiR1VHvg3pKZVwJXTlX+43wP+Cnw38CVmbkBICIeDLweeDPwfOAE4F2DZhoRc4H/pATt3weOycwfR8ROwN8AbwTeExGXZubXanw9kiRJkiQBNXeVnymZeVZmfigzL20F7dXz12bmW4BPVE8tn2DWrwYeQmnBf26rt0Bm3pqZbwI+R+n+f/JkX4MkSZIkSZ2MROA+gIuq9Z4TPO5l1fqczPx1h/3vr9YHRsTDh6qZJEmSJEk91NZVPiLuGuKwzMzt66pDD4dV66sHPSAi5gMHVZtf7ZLsAuAW4H7AMuCKYSsoSZIkSVIndd7jPmX3yw8jIuYBD6V0d39R9fRHJpDFIyjd4AE6DqiXmZsj4grgUOCRQ1ZVkiRJkqSu6gy29+mz/37AIcDxwAOAY4HLaiyfiHgQcG2HXRuBd2fmxyaQ3R5tj6/rka61b48eaX4vIi7psmu/QY6XJEmSJG1bagvcM/NnAyS7NCJWAOcD/8RYV/S63EOZdg5gF8o88psog8d9dIJ57dj2+I4e6W6v1vMmmL8kSZIkSX1N++B0mXknZYq2XYF31Jz39Zm5e2buDswFHg58HPhb4AcRsX+d5Q0jMw/qtFCms5MkSZIk6V5mZFT5zLwMWA8cPoVlbM7MKzPzWOCDwF7A2REx6Gu+re3x3B7pdqjWG3qkkSRJkiRpKDMSuEfEdpRgeOE0FXlatX5stQyi/b72XtPItfZdP9FKSZIkSZLUz0zN4/5iyv310xXsts/B/rABj/kpkNXjjl3sq9b71vztlw9XNUmSJEmSuqtzHvderdIAc4AHAUcCr6EExZ+pq/w+FrU9HqhLe2auj4iLKSPhPx04r0OyJZTR8gFWTqqGkiRJkiR1UOd0cJ2mYesmgIuBkyZbaETcB9icmdkj2Zur9SbgexPI/hxK4P6yiDgpM8f3EHhTtb4kM6+YQL6SJEmSJA2kzq7y0WcBuBVYBRwHLM3MOgZ0ezBwcUS8sprHvVQmYlZEPCYiPgm8qnr6tMz8XVuavSMiq2V5h7z/EfgFMB/4YkQ8sjpufkS8DziqSve2Gl6HJEmSJElbqLPF/b69dmbmPTWWNd6BwBkAEbGR0h1+PrB9W5oVwFsmkmlm3hERR1K6wR8I/DgibqXM2T6L0t3/bZn5tcm+AEmSJEmSOqktcJ/iwLyX64AXAcuAQ4E9gPsDG4GfUbrGn5mZq4bJPDN/GBGPAk4EngM8ELgRuBD4h8z03nZJkiRJ0pSps8V9RmTmXcC51TLRY69hrBt/r3S/AY6vFkmSJEmSps1MTQcnSZIkSZIGMFSLe0TUdU93ZuYza8pLkiRJkqSRM2xX+afVVH6vKdwkSZIkSdrmDRu4/59aayFJkiRJkjoaKnDPzDPqrogkSZIkSdqSg9NJkiRJktRgBu6SJEmSJDXYlM3jHhELgT2BHekxV3pmfneq6iBJkiRJ0tau1sA9IgI4DngtsHiAQ7LuOkiSJEmSNEpqC5qroP084AhKC/t6YD6wGbgBWABsVyW/HfhdXWVLkiRJkjSq6rzHfTlwJCVIfwqwc/X8DZm5JzCPMv/79yiB/QmZ+eAay5ckSZIkaeTUGbgfQ+n6/ubM/K/MzPadmbkpM78JPBH4DvCvEXFojeVLkiRJkjRy6gzcD6jWnx33/H3aNzLzHuANwH2BN9VYviRJkiRJI6fOwH0ecHNm3tH23J2U+9zvJTMvB24FHl9j+ZIkSZIkjZw6A/cbKK3o7X4LbB8Re7Y/GRGzgLmUAeskSZIkSVIXdQbuvwB2jIgHtD13abU+clzaZ1GC/BtqLF+SJEmSpJFTZ+D+3Wr9xLbnzqGMIP/eiHhDRDwlIo4DzqIMZPeFGsuXJEmSJGnk1Bm4f5py3/pRrScy81xKcD4P+ADwDeAfgF2Aq4F31Fi+JEmSJEkjZ3ZdGWXmpZSAfLznA38OvAB4EHAL8HXgvZl5U13lS5IkSZI0imoL3LvJzE3AadUiSZIkSZImYOiu8hHxjIiIOisjSZIkSZLubTL3uJ8P/DIiTo6IR9RVIUmSJEmSNGayg9M9EHgLcFlEXBgRr40I52aXJEmSJKkmkwncHwW8H7iOMuXbwZT72K+LiM9ExJERMeX30EuSJEmSNMqGDtwz8/LMfCuwF/AM4JPA7cB2wB8D51GC+A9FxIF1VFaSJEmSpG3NpOdxz+IbmXkMsDuwHPgWkMBC4PXARRHxo4h4Y0TsPtkyJUmSJEnaVkw6cG+Xmbdl5scz82nA3sDbgZ9SutLvD7wPuDYivhwRR0fE9nWWL0mSJEnSqKk1cG+Xmb/KzJMzc3/gUOCjwI3AfYBnAv8GXD9V5UuSJEmSNAqmLHBvl5kXZ+brgT2B91C60Qdwv+koX5IkSZKkrdW0jPoeEQ8C/gQ4Btivbdfd01G+JEmSJElbqykL3CNiR+AFwMuBJ1Fa2KPa/X3gLOCcqSpfkiRJkqRRUGvgHhEBPJ0SrD8PmMtYsP4bypRxZ2XmZXWWK0mSJEnSqKolcI+IR1OC9ZdSpoSDErDfCXye0rr+1czcXEd5kiRJkiRtK4YO3CNiN+BllPvWD2g9Xa0voATrn8rMWyZVQ0mSJEmStmGTaXG/ljK1W7Rtn03pCn/VZCsmSZIkSZImF7jPBm4DzqO0rn8rM7OWWkmSJEmSJGBygfsrgM9k5m11VUaSJEmSJN3b0IF7Zp5VZ0UkSZIkSdKWZs10BSRJkiRJUncG7pIkSZIkNZiBuyRJkiRJDWbgLkmSJElSgxm4S5IkSZLUYAbukiRJkiQ1mIG7JEmSJEkNNvQ87r1ExGzgIODBwA6Z+fGpKEeSJEmSpFFXe4t7RLwV+A3wXeDTwJnj9u8cEZdHxJqI2LPu8iVJkiRJGiW1Bu4R8UngPcAuwNXApvFpMvNm4L+ARcCL6yxfkiRJkqRRU1vgHhEvBl5CaW0/LDMXAzd1Sf5JIICn1VW+JEmSJEmjqM4W92OBBP4yM1f3SXsxsBl4VI3lS5IkSZI0cuoM3B9LCdz/s1/CzNwI3ALsWmP5kiRJkiSNnDoD93nA+sy8c8D02wH31Fi+JEmSJEkjp87A/bfAThExv1/CiNgH2BH4VY3lS5IkSZI0cuoM3FdV6xcOkPbNlG7136qxfEmSJEmSRk6dgftplJHi/y4iOg46FxHbR8S7gVdRAveP1Fi+JEmSJEkjZ3ZdGWXmqoh4P6U1fXVEfAOYDxARHwT2Ap5MmeMd4G8y88d1lS9JkiRJ0iiqLXAHyMy3RsR1wLuA57btOp7SGg9wG3BiZtraLkmSJElSH7UG7gCZeWpErACeDxwG7EHpkr8W+B7w75l5U93lSpIkSZI0imoP3AEy8xbgX6tFkiRJkiQNqc7B6SRJkiRJUs1qbXGPiO2AzZm5adzzAbwGeBKwPXA+8M+ZubnO8iVJkiRJGjW1tbhHxJ8BdwArOuz+AmXqtxcCRwIfAz5XV9mSJEmSJI2qOrvK/1G1/nj7kxHxXOBZ1eangTOBu4FnR8RLayxfkiRJkqSRU2fgvn+1vnDc88cACZycmS/NzGOB11Omh3t5jeVLkiRJkjRy6gzcHwDclpk3j3v+qdX6n9ue+wQlmH9sjeVLkiRJkjRy6gzc51Ja0X8vIh4OLAB+npm/aD2fmXcANwM711i+JEmSJEkjp87A/QZgh4h4YNtzrfvev9Mh/RzglhrLlyRJkiRp5NQZuK+u1u+IYiHwF5Qu8V9rTxgRe1Fa6K+rsXxJkiRJkkZOnYH7aZSu8sdSWtKvBR4K/Bo4b1zaZ1TrS2ssX5IkSZKkkVNb4J6Z/wW8BrgNmAdsD1wF/HFm3jku+Sur9TfqKl+SJEmSpFE0u87MMvOfIuJs4FHArcBVmbm5PU1E3Bd4b7W5ss7yJUmSJEkaNbUG7vD7EeMv6rH/buDzdZcrSZIkSdIoqvMed0mSJEmSVLPaWtwj4onDHJeZ/11XHSRJkiRJGjV1dpX/NmXqt4nIOupQTS93FLAM+ANgN+Au4OfAV4BTM/P6IfJdDpzZJ9ltmTlvonlLkiRJkjSIOgP3X9I7cL8fsHP1+DZgXR2FRsSDgWsoU9G13ArsCBxQLX8WEc/PzG8NWczdwE1d9t02ZJ6SJEmSJPVVW+CemXv3SxMRDwNOBF4GvCMzP15D0fep1l8CVgArM/N3EbEdpQX+o8Ai4HMR8fDM/M0QZXw3M59cQ10lSZIkSZqQ2keV7yUzfwa8KiJuB/4lIn6Wmasmme3vgMdm5g/HlXUX8JWIeBbwfWAn4NXA306yPEmSJEmSps1MjSr/LkpL+YmTzSgzbxkftI/b/1PggmrzoMmWJ0mSJEnSdJqRwD0zfwvcAjxumoq8sVrfp2cqSZIkSZIaZkYC94hoDVQ3dxrKmg0srTYvGzKb/SPixxFxR0Ssj4jLIuIfImJRTdWUJEmSJKmjmeoq37rP/IppKOt1wO7AZuCsIfNYCDwCuB2YA+wP/CXw44h4aR2VlCRJkiSpk9oGp4uIl/dJMgd4EHAE8GjK1HH/WFf5Xep0AHBytfmRzLx8gllcB7wD+CxwVWbeFRHbU0arfz/wSOCsiPhVZv73gHW6pMuu/SZYN0mSNE2uXLueVWvWsWHjJubNmc3SxQvZd7f5M10tSdI2os5R5VfQex73lqjSfSgzpyxwj4g9gM9RuuNfArx1onlk5teAr4177k7gyxGxCrgYWAycAhw22TpLkv5/e/ce59dZ1wn8801bSC/pJQTCtTS7SaBcys227AZdIFqRi0pRENhqWRW8tugqtqILcrHgZbHFXRQsC4ggFwvaFUQNl7oR0i4oILcka0orl0AIhYQ2lDbP/nHO0CGZmczlNzMnM+/36/V7nfn9zvOc852ZX5v5/M5zngeGZevOPbl8y45cu2vvYfvOWbc6F2/ekE3r1yxCZQAsJ6MM7tdk6uB+W5Kbknw8ydtncfV72qpqdbrAvS7JjiRPaK0dGOU5Wmtfq6rfTvLaJI+sqjWttT3T6DfhzPb9lfiHj7JGAGD23nLdDbn0qo/n4CR/3Vy7a28uuHJbXnb+WXnq2fdZ2OIAWFZGFtxba48e1bHmop/47j1JHpTkhiTf21rbPU+n2zZ22nQfEhwxuAMAw7d1554pQ/uYgy255KqP5V6nHe/KOwDzZrEmp5sXVXVikncl+a4kX0wX2m9Y3KoAgKPN5Vt2HDG0jznYkiu27JjfggBY1pZMcK+q45Ncne5e86+kC+3z/a/oueO+vn6ezwUALIDtu/dNeE/7VLbt2pvtu/fNU0UALHejvMf926rq0Umemu6e7bv2L385yUeSvLW19v4Rn+9OSa5K8ph099Gf11r7xByPWa21ST9rr6qTk1zSP722tfbluZwPABiGrTtnd+fb1p17zDQPwLwY6RX3qlpTVe9JsiXJc5Kck+7e73X9189JsqWq/qaqRnIjWFUdk+RNSR6XZF+SH2itfWSafc+oqtY/Ljxk932r6kNV9ZNVdfq4Pneqqscl2ZpkY7r14S8dxfcCACy+/QduW9B+AHAko1zH/U5J/i7JWekma/tgkvcm+be+yb2TPDbJf0jyfUn+tqoe2Vq7dY6n3pTkKf3XxyV5Z1VN1vbG1trZMzj2uf0jVXUgyTeSnNyfJ0luTvIzrbX3zrRoAGCYTlo5uz+PZtsPAI5klP/C/EKShyTZm+TprbW/m6DNb1bVeUne3Lf9+SSvmON5x48aWNk/JjOTJeF2J7koyaPS1XrXJKekC+870o0qeFVr7bMzqhYAGLTZzg5vVnkA5ssog/vT0q3j/uxJQnuSpLX2t1X17CRvS/JjmWNw7++Xn/QS+xH6Xj9Z39baLUle2T8AgGVi49pVOWfd6hlNUHfuutXubwdg3ozyHvf7pbui/Y5ptH1H3/b+Izw/AMBIXLx5Q1ZM87LAikou2rxhfgsCYFkbZXA/Lsm3ppqJfUxr7WCSb2WeZrUHAJiLTevX5LLzH3zE8L6ikpedf5Zh8gDMq1EG9xuSrKqqhx+pYVU9Ismqvg8AwOA87ezT86c/eW7OXbd6wv3nrludP/3Jc/PUs++zwJUBsNyM8or3u9INl7+yqs6bbF3zqlqb5Mp098P/9QjPDwAwUpvWr8mm9Wuyffe+bN25J/sP3JaTVh6bTevXuKcdgAUzyuD+8iQ/kW45uE9X1WuSvD/J59LN9H56ksckuTDJCelmn/+dEZ4fAGBebFy7SlAHYNGMLLi31r5UVY9P8s4kd0/yq/3jUJXkC0l+uLX2pVGdHwAAAJaiUd7jntbatUkekOQFST6ebjh89Y/Wv/bfkjywtXbdKM8NAAAAS9HIZ3VvlG2C+gAAIABJREFUrd2U5MVJXlxVxyUZm9Flb2vtW6M+HwAAACxl87ocWx/Ud8/nOQAAAGApG+lQeQAAAGC0Zn3FvapOH0UBrTVruQMAAMAk5jJUftcIzt/mWAMAAAAsaXMJzTWyKgAAAIAJzSW4P2aS1yvJXyQ5Nclj53B8AAAAWPZmHdxbax+YbF9V3XqkNgAAAMCRmVUeAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAGb9XJwVXX6FLuP6dvcJ9267pNqrd0w2xoAAABgqZt1cE+yaxptrj/C/jbHGgAAAGBJm0tonvJKOgAAADB3cwnujxlZFQAAAMCEZh3cW2sfGGUhAAAAwOHMKg8AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgB076gNW1QOSnJ/kQUlOS3LcFM1ba23zqGsAAACApWJkwb2qViS5PMnPJqn+cSRtVOcHAACApWiUV9x/NcnP91+/N8mWJLuT3D7CcwAAAMCyMsrg/lPprqD/RmvtshEeFwAAAJatUU5Od+90V9dfMcJjAgAAwLI2yuD+xSQ3t9YOjPCYAAAAsKyNMrj/7ySrqupBIzwmAAAALGujDO4vTfL5JH9UVatGeFwAAABYtkY2OV1r7YtV9dgkf5pkV1W9Ksm/JPnCEfpdM6oaAAAAYKkZ5azySTer/OeSnJPk16fZftQ1AAAAwJIxstBcVfdPck2Su/QvfTPJnljHHQAAAGZtlFe7fzvJmiSfSfLTSba21toIjw8AAADLziiD+6PSDX3/kdbaJ0Z4XAAAAFi2Rjmr/J2T7BPaAQAAYHRGGdw/keT4qlo5wmMCAADAsjbK4P7KJMcl+akRHhMAAACWtVGu4/7mqnpIkt+rqlOTvKK19o1RHR8AAACWo1EuB/fe/stbkvxWkudX1fVJvjBFt9Za2zyqGgAAAGCpGeWs8o8+5Pmdk9yvf0zGcnEAAAAwhVEG92eN8FgAAABARnuP++tHdSwAAACgM8pZ5QEAAIARE9wBAABgwEY5q/yPz6Zfa+0No6oBAAAAlppRTk73usxulnjBHQAAACYxyuB+TaYO7qckOTPdMnE3JfnoCM8NAAAAS9IoZ5V/9JHaVNUJSX45yQuSbGmtvWRU5wcAAIClaJRX3I+otXZzkpdUVUvyoqr6aGvt6oWsAQAAAI4mizWr/CvTDav/5UU6PwAAABwVFiW4t9a+nuTrSR66GOcHAACAo8WiBPequmuSU7PAQ/UBAADgaLPgwb2q7pTkD/unH1vo8wMAAMDRZGRXvKvqvx2hycok905yXpK7prvH/RWjOj8AAAAsRaMcqv7CTL2Oe5JUv70lySWttbeP8PwAAACw5IwyuL8hUwf325LclOTjSa5urX11hOcGAACAJWlkwb21duGojgUAAAB0FmsddwAAAGAaBHcAAAAYsFkNla+q0/svv9Va+8Ihr81Ia+2G2fQDAACA5WC297jv6refTvLAQ16biTaHGr6t/9Dg/CSbkzwkydoktyb51yTvTnL52AcMszz+3ZNcmuSJSe6V5GtJrk3yB621LXOrHgAAACY329A8tqzbiglem81xZq2q7pPk+kOO9fUkJyY5q388u6qe0lp73yyOf1aS9ya5y7hjr0kX4p9QVb/eWnvZ7L8DAAAAmNys7nFvra3oH2dO8NqMHiP4Ho7pt3+d5EeTrG6tnZLkhCSPTzcS4LQk7+yvnE9bVR2f5K/ShfZ/SvKg/tinJfn9dB8W/HZVnTeC7wMAAAAOsxQmp/tqkoe11p7YWnv72PrwrbVbW2vvThfeDyQ5OclzZnjs5yS5b5L9SZ7UWvtEf+yvt9Z+Jck704X3y0bzrQAAAMB3OuqDe2vta621j06x/9NJPtQ/fcQMD//Mfvum1trnJtj/u/324VV1vxkeGwAAAI7oqA/u0/SVfnvMlK3GqapVuSPov2eSZh9KN1Fd0k2MBwAAACM12+XgXjui87fW2k+O6FgTqqpjk2zqn/7LDLqemTsmvPvERA1aawer6jNJzknygFkXCQAAAJOY7azyF6Zbym2iWeHbuK8P3X/ovpZkXoN7kp9PcvckB5O8fgb97jHu689P0W5s3z2maPNtVfXhSXbdfzr9AQAAWF5mG9x/a5LX75Tk55KckuSzSa5JMnZv+D2TfE+SM5LclOSPknxzluefln4pt7GJ4/6wtfbJGXQ/cdzXt0zR7uZ+e9JMagMAAIDpmFVwb60dFtyr6k5J3tcf84LW2p9N1Leqnp7k1Um+O/N4X3hV3SPdrO/HJ/lwkl+br3PNRGttwgny+ivxD1/gcgAAABi4UU5Od0mSRyb52clCe5K01t6c5GfT3Xf+vBGe/9uqanWSv02yLsmOJE9orR2Y4WG+Me7r46dod0K/3T/D4wMAAMARjTK4Pz3JrUnePI22f55umPwzRnj+JElVnZJuFvgHJbkhyfe21nbP4lDj72u/5xTtxvZ9YRbnAAAAgCmNMrjfN8mB1trtR2rYWrstyYG+z8hU1YlJ3pXku5J8MV1ov2GWh/t07phM74GTnG9FkrH122dy/zwAAABMyyiD+74kJ1fVg47UsKoenG4Cu32jOnlVHZ/k6iT/Md267d/bWtsx2+O11vYl+b/90++bpNm56b6PJNky23MBAADAZEYZ3N+bbom311bVaZM1qqpTk1yZ7mr2e0dx4n5ivKuSPCbdjPXntdYmXHt9ht7Ub5/ZT3Z3qF/ptx9urX1mBOcDAACA7zDK4P6CdEujPSLJZ6rqJVV1XlU9qH+cV1UvSfKZdEPZb+n7zElVHZMuYD8u3RX8H2itfWSafc+oqtY/LpygyR+nW9ZuVZL/XVUP6PutqqrfSXJ+3+7X5/htAAAAwIRmu477YVpr26vq8UneluSuSS7tH4eqJF9K8tS5DGUfZ1OSp/RfH5fknVU1WdsbW2tnT/fArbVbquqH0g2Df3iST1TV19Ot2b4i3aiBX2+t/e1siwcAAICpjCy4J0lr7Zqqul+SX0wXph+Y5Jh+9+1JPpEu2P+P1tpNIzrt+FEDK/vHZGa6JFxaax/t79u/NMkTk9wr3T301yZ5RWvNve0AAADMm5EG9yTpA/mLk7y4qo5Lsrrftbe19q15ON/7013Fn03f66fTt7X2xSQX9w8AAABYMCMP7uP1QX02a6gDAAAAmcfgXlVrk9wnyQmttWvm6zwAsJxt370vW3fuyf4Dt+Wklcdm0/o12bh21WKXBQCM0MiDe1U9Lcnz093fnnQTuB07bv+p6e5zryQ/2lr76qhrAIClbuvOPbl8y45cu2vvYfvOWbc6F2/ekE3r1yxCZQDAqI1yObhU1WXplmZ7UJJb04X277iHvL8Hfne6NdefNsrzA8By8JbrbsgFV26bMLQnybW79uaCK7flrdfduMCVAQDzYWTBvarOS/Jr6dZS/7F0S6Z9eZLmr08X6L9/VOcHgOVg6849ufSqj+dgm7rdwZZcctXHsnXnnoUpDACYN6O84v4L6a6w/1pr7a2ttdunaPvBvu1DRnh+AFjyLt+y44ihfczBllyxZcf8FgQAzLtRBvdz++0bj9SwtbY/ydeT3H2E5weAJW377n2TDo+fzLZde7N99755qggAWAijDO6nJvl6a+0b02w/q7XXAWC5mu2wd8PlAeDoNsrgvjfJyVV1/JEaVtW9kpyc5IsjPD8ALGn7D9y2oP0AgGEYZXC/tt/+wDTa/ny//YcRnh8AlrSTVs5uFdfZ9gMAhmGUwf1P0g1//+2quudkjarqp5M8L93kdH80wvMDwJI223XZrecOAEe3kQX31trV6dZw35jkw1V1eZITkqSqLqqq36uqf0kX1lckeVVr7YOjOj8ALHUb167KOetWz6jPuetWZ+PaVfNUEQCwEEZ5xT1JLkxyeZK7JfnFJGN/KbwiyS8leUD//PeTXDTicwPAknfx5g1ZMc3pXVdUctHmDfNbEAAw70Ya3Ftrt7XWfinJ/ZK8NMl7k3w6yfZ097O/PMmDWmu/2lo7OMpzA8BysGn9mlx2/oOPGN5XVPKy888yTB4AloB5ma2mtbYzyW/Ox7EBYLl72tmn596nnZArtuzItgnWdT933epctHmD0A4AS4RpZgHgKLRp/ZpsWr8m23fvy9ade7L/wG05aeWx2bR+jXvaAWCJEdwB4Ci2ce0qQR0AlrhZB/eq+vFRFNBae8MojgMAAABL0VyuuL8u3Vrsc9GSCO4AAAAwiVEMlf9qkltGcBwAAADgEKMI7scl+askb2itvX8ExwMAAAB6c1nH/clJ3pnkzkkuTLKlqnZV1UuqauMoigMAAIDlbtbBvbX2l621pyS5R5JfSHJdkvsm+fUkn6qqbVX1c1W1ejSlAgAAwPIzlyvuSZLW2ldba/+ztfbIJPdL8ttJbkhydpJXJvl8VV1VVedX1XFzPR8AAAAsJ3MO7uO11na01n6jtbYuyWOSvD7JN5P8cJK3JflCVf3nUZ4TAAAAlrKRBvfxWmsfaK39lyRrkzwvyW1JTkty1nydEwAAAJaaUcwqP6GqOj7JU5JckOSxSY7pd+2br3MCAADAUjPy4F5Vm9OF9fOTnJikknw5yZvTLRn3kVGfEwAAAJaqkQT3qjozyY8neWaSe6UL6weSvD3JG5L8TWvt9lGcCwAAAJaTWQf3qlqT5BnpAvvD0oX1JNmaLqy/tbX2tTlXCAAAAMvYXK64fz7dfeuV5P+lC+tvbK3tGkVhAAAAwNyC+7FJWpLPJrkuyZlJXlpVU3Y6RGutPXMONQAAAMCSNtd73CvJfZOcPu75TLR098UDAAAAE5hLcH/9yKoAAAAAJjTr4N5ae9YoCwEAAAAOt2KxCwAAAAAmJ7gDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADduxiFwDA0rR9975s3bkn+w/clpNWHptN69dk49pVi10WAMBRR3AHYKS27tyTy7fsyLW79h6275x1q3Px5g3ZtH7NIlQGAHB0MlQegJF5y3U35IIrt00Y2pPk2l17c8GV2/LW625c4MoAAI5egjsAI7F1555cetXHc7BN3e5gSy656mPZunPPwhQGAHCUE9wBGInLt+w4Ymgfc7AlV2zZMb8FAQAsEYI7AHO2ffe+SYfHT2bbrr3ZvnvfPFUEALB0CO4AzNlsh70bLg8AcGSCOwBztv/AbQvaDwBgORHcAZizk1bObnXR2fYDAFhOBHcA5my267Jbzx0A4MgEdwDmbOPaVTln3eoZ9Tl33epsXLtqnioCAFg6lkRwr6pVVfWDVfXiqnp3Ve2pqtY/7j+H4z563HGmerhkBCx7F2/ekBU1vbYrKrlo84b5LQgAYIlYKjcXbk7yjnk8/sEkXz7CfoBlbdP6Nbns/Afn0qs+PuV67isqedn5ZxkmDwAwTUsluCfJl5L83yTXJflckleP8Ng3ttbOGOHxAJakp519eu592gm5YsuObJtgXfdz163ORZs3CO0AADOwVIL71a21d449qaozFq8UgOVt0/o12bR+Tbbv3petO/dk/4HbctLKY7Np/Rr3tAMAzMKSCO6ttdsXuwYAvtPGtasEdQCAEVgSk9MBAADAUiW4T89dq+ojVfWN/rG9ql5dVQ9e7MIAAABY2pbEUPkFcEKShyX5apITk2zoH/+lqi5prf3edA9UVR+eZNesl60DAABg6XLFfWo3JfndJN+V5PjW2up0If4/JfnHJMck+d2qesbilQgAAMBS5or7FFpr/5zknw957fYk11TVY5K8N8mmJC+vqj9vrR1xPffW2iMmer2/Ev/wuVcNAADAUuKK+yy11m5N8pv903unG0oPAAAAIyW4z822cV//u0WrAgAAgCVLcAcAAIABE9zn5txxX+9atCoAAABYsgT3KVRVTbHvuCQv6p9+IclHFqQoAAAAlpUlE9yras3YI8lp43adOn5fVa04pF/rHy+c4LD/UlW/WFUbxkJ8VR1TVY9KsiXJo/p2l05nRnkAAACYqaW0HNyXJ3n9g4c8X5fk+mke8wFJrui//mZV7UtycpI79a/dluQ3Wmuvn0GdAAAAMG1LKbjPh+ekW6f9EUnulu5K/i1JPpPkA0le1Vr75OKVBwAAwFK3ZIJ7a23S+9Fn26+19uokr551UQAAADBHS+YedwAAAFiKBHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDAjl3sAgAW2vbd+7J1557sP3BbTlp5bDatX5ONa1ctdlkAADAhwR1YNrbu3JPLt+zItbv2HrbvnHWrc/HmDdm0fs0iVAYAAJMzVB5YFt5y3Q254MptE4b2JLl2195ccOW2vPW6Gxe4MgAAmJrgDix5W3fuyaVXfTwH29TtDrbkkqs+lq079yxMYQAAMA2CO7DkXb5lxxFD+5iDLbliy475LQgAAGZAcAeWtO279006PH4y23btzfbd++apIgAAmBnBHVjSZjvs3XB5AACGQnAHlrT9B25b0H4AADBqgjuwpJ20cnarXs62HwAAjJrgDixps12X3XruAAAMheAOLGkb167KOetWz6jPuetWZ+PaVfNUEQAAzIzgDix5F2/ekBU1vbYrKrlo84b5LQgAAGZAcAeWvE3r1+Sy8x98xPC+opKXnX+WYfIAAAyK2ZeAZeFpZ5+ee592Qq7YsiPbJljX/dx1q3PR5g1COwAAgyO4A8vGpvVrsmn9mmzfvS9bd+7J/gO35aSVx2bT+jXuaQcAYLAEd2DZ2bh2laAOAMBRwz3uAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGBLIrhX1aqq+sGqenFVvbuq9lRV6x/3H8HxT66ql1TVp6rq5qr6SlVtqaofGUX9AAAAMJljF7uAEdmc5B3zceCquneSa5Ks61/an+TkJI9N8tiqelVr7efm49wAAACwJK64976U5F1JfivJs0dxwKqqJG9PF9qvT7KptbYqyaokz0tyMMnPVtVPj+J8AAAAcKilcsX96tbaO8eeVNUZIzruDyU5N11Af3Jr7Z+TpLV2IMnvVtU9kzw3yYuq6vWttVtHdF4AAABIskSuuLfWbp+nQz+z3/79WGg/xO8laUnunm7oPAAAAIzUkgju8+gx/fY9E+1srX0uySf6p4I7AAAAIye4T6Kq7pbkLv3TT0zR9JP99gHzWxEAAADLkeA+uXuM+/rzU7Qb23ePKdoAAADArCyVyenmw4njvr5linY399uTpnPQqvrwJLvmvN48AAAAS48r7gAAADBgrrhP7hvjvj5+inYn9Nv90zloa+0RE73eX4l/+PRKAwAAYLlwxX1y4+9rv+cU7cb2fWEeawEAAGCZcsV9Eq21L1fVniRrkjwwkywJlztmk//kJPth2rbv3petO/dk/4HbctLKY7Np/ZpsXLtqscsCAAAWkeA+tfcl+dEk35fkvx+6s6rulS7UJ8mWBayLJWbrzj25fMuOXLtr72H7zlm3Ohdv3pBN69csQmUAAMBiM1R+am/qt+dV1UMm2P/LSSrdMPn3LVhVLClvue6GXHDltglDe5Jcu2tvLrhyW9563Y0LXBkAADAESya4V9WasUeS08btOnX8vqpacUi/1j9eOMFh/zLJtnQ/p3dU1SP7Pneuqv+a5Ll9uxe01m4d+TfFkrd1555cetXHc7BN3e5gSy656mPZunPPwhQGAAAMxlIaKv/lSV7/4CHP1yW5fjoHbK21qvqRJNf0/T5YVfuTrMwdP7s/aq29ZublQnL5lh1HDO1jDrbkii07DJkHAIBlZslccZ8vrbV/S/LQJL+d5NPpAvu+dEPjn9pa+9lFLI+j2Pbd+yYdHj+Zbbv2ZvvuffNUEQAAMERL5op7a63mq19r7etJnt8/YCRmO+x96849ZpoHAIBlxBV3WCT7D9y2oP0AAICjk+AOi+SklbMb8DLbfgAAwNFJcIdFMttJ5kxOBwAAy4vgDotk49pVOWfd6hn1OXfdave3AwDAMiO4wyK6ePOGrJjmtIorKrlo84b5LQgAABgcwR0W0ab1a3LZ+Q8+YnhfUcnLzj/LMHkAAFiGzHIFi+xpZ5+ee592Qq7YsiPbJljX/dx1q3PR5g1COwAALFOCOwzApvVrsmn9mmzfvS9bd+7J/gO35aSVx2bT+jXuaQcAgGVOcIcB2bh2laAOAAB8B8GdaXElGAAAYHEI7kxp6849uXzLjlw7wb3X56xbnYvdew0AADCvzCrPpN5y3Q254MptE4b2JLl2195ccOW2vPW6Gxe4MgAAgOVDcGdCW3fuyaVXfTwH29TtDrbkkqs+lq079yxMYQAAAMuM4M6ELt+y44ihfczBllyxZcf8FgQAALBMCe4cZvvufZMOj5/Mtl17s333vnmqCAAAYPkS3DnMbIe9Gy4PAAAweoI7h9l/4LYF7QcAAMDkBHcOc9LK2a0SONt+AAAATE5w5zCzXZfdeu4AAACjJ7hzmI1rV+Wcdatn1Ofcdauzce2qeaoIAABg+RLcmdDFmzdkRU2v7YpKLtq8YX4LAgAAWKYEdya0af2aXHb+g48Y3ldU8rLzzzJMHgAAYJ6YTYxJPe3s03Pv007IFVt2ZNsE67qfu251Ltq8QWgHAACYR4I7U9q0fk02rV+T7bv3ZevOPdl/4LactPLYbFq/xj3tAAAAC0BwZ1o2rl0lqAMAACwC97gDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGCCOwAAAAyY4A4AAAADJrgDAADAgAnuAAAAMGDVWlvsGkhSVV85/vjjV5955pmLXQoAAAAj9qlPfSq33HLL3tbaXWbaV3AfiKraleTkJNcvciksvvv3208vahUwGt7PLCXezywl3s8sNUfDe/qMJF9vra2baUfBHQamqj6cJK21Ryx2LTBX3s8sJd7PLCXezyw1S/097R53AAAAGDDBHQAAAAZMcAcAAIABE9wBAABgwAR3AAAAGDCzygMAAMCAueIOAAAAAya4AwAAwIAJ7gAAADBggjsAAAAMmOAOAAAAAya4AwAAwIAJ7gAAADBggjsssqo6vaqeW1VXV9UNVfXNqtpXVR+tqpdV1T0Wu0aYi6o6qapurKrWPy5c7JpgpqrqflX1yqr6TFV9o6q+VlWfqqrXVtV/Wuz6YDqqakVVPauq/r6qvlxV36qqm6pqW1U9v6pWLXaNMKaqVlXVD1bVi6vq3VW1Z9zfEvefRv8VVfXsqvpg/z7fV1X/VFW/WlV3WojvYZSqtbbYNcCyVVX3SfLZJDXu5a8nOTHJMf3zryZ5SmvtfQtcHoxEVf1BkovHvfSs1trrFqkcmLGquijJ7yYZ+0Nvf5Jjk6zsn1/ZWvupxagNpquqTkhydZLHjnv5a0lOzh1/h3w2yWNba/+6wOXBYarqh5O8Y5LdZ7bWPj1F3+OSvDPJ4/uXbk1ye5Lj++fXpXuv7x9RufPOFXdYXGPh/K+T/GiS1a21U5KckO5/NLuSnJbknVV198UpEWavqh6e5BeSbFvsWmA2quo5SS5PF9RfnuS+rbVVrbXjk9wjyY8n+cdFLBGm6zfThfaW5NIkp7bWTk33AdTTk9yU5L5J/mTRKoTDfSnJu5L8VpJnz6DfS9L9LX0gyYXp/rY+McmTkuxNcnaSPx5lofPNFXdYRFV1SpIzWmsfnWT//ZP8U7p/VF/YWvuthawP5qKqVqQL7A9L9w/kR/pdrrhzVKiqM5J8It0ffM9urb1mUQuCOaiqzyY5PclrW2s/OcH+C5P8r/7p6tbaVxewPDhMVR3TWrt93PMz0l3USqa44t5f7Lo+yZ2TXNxau+KQ/T+U7mp8S/LQ1trHRl78PHDFHRZRa+1rk4X2fv+nk3yof/qIhakKRuYXk3xXkle11v5psYuBWbg4XWjfJrSzBKztt5P9//jD474+YZ5rgSMaH9pn6CnpQvvXkrx6guP+ZZLt6W4RecasC1xggjsM31f67TFTtoIBqap7JXlxkt1JfmORy4HZGvuD7s2LWgWMxvX99mGT7B+7QLC7tfa5+S8H5s1j+u01rbUDk7T523772En2D47gDgNWVccm2dQ//ZfFrAVm6JVJViX5ldba1xa7GJipqvr3Se7WP/2nqnpkv/rHV6rqlqr6dFX9blXdbaoLQeCPAAAPTUlEQVTjwICMjRp5VlVd0t+ul6q6U1U9Lckr0g0d/pXFKhBG5AH99hNTtPlkvz2zqmqKdoMhuMOw/XySuyc5mOT1i1wLTEtVPSnJk5O8v7X2xsWuB2Zpw7ivH53k/yR5YpLj0oWb+6ULOP9cVQ9c8Opg5v4gyf9INzz4siQ3VdVNSW5J8udJPp3kB/1/myVgbCnlz0/RZmzfSf1j8AR3GKiqOivdP6xJ8oettU9O1R6GoKpOTPKHSb6V7oMnOFqdOu7rF6S7H/KRrbWT0/2R9/h0sx3fI8lf9COkYLD6+4Wfm+S/Jrmtf/mU3JEHViW56yKUBqN2Yr+9ZYo2N4/7WnAHZqeq7pFutsvj000W82uLWxFM24vSzVr8Ch82cZQb/zdSS/Lk1tq2JGmtHWytvTvJf+n33y/J+QtcH8xIP9P21iS/n+TPkjwkXWDZkG55uH+X5LVVddmkBwEWjeAOA1NVq9NNmLEuyY4kT5hiYg0YjKp6aLpZuG9MF+DhaLZ/3Nd/01r7zKENWmt/ne5KfJJsXpCqYPbekOScJFe21i5srX2stfaN1trO1trLkjynb/c8t39wlPtGvz1+ijbjV07YP2mrARHcYUD6iWLek+RBSW5I8r2ttd2LWxVM2+XpVj94fpKqqpPGP8a1u3P/muWGGLLx90YeFton2HefeawF5qSqHpDk+/qnr5ioTWvtT9OtZLMiyZMWqDSYD2P//77nFG3G9u1vre2b53pGQnCHgejvDX5XunWvv5gutN+wuFXBjNy3374hyb4JHmP+qH9uKD1D9sl0E4NOV5uvQmAEzhz39a4p2v1rvz1j/kqBeTf298VUI0fGZp7/1DzXMjKCOwxAVR2f5Ook/zHdp93f21rbsbhVASxfrbWbk3ywf3q/KZqO7bt+XguCuRn/IdTpU7Qb+wD2qLgCCZN4X7/97qpaOUmbsREoWxagnpEQ3GGRVdWdklyV5DFJbkpyXmttqnUnYZBaa2e01mqyx7imz+pfO2OxaoVpekO/fVxVHRbeq+oJSTb2T9+1YFXBzH103Nc/PVGDfinPu/VPt817RTB/rkryzXSrg/zUoTv79/r90o2UevPCljZ7gjssoqo6Jsmbkjwu3afbP9Ba+8jiVgVA77Xphlwek+SqqjonSapqRVU9LsmVfbsPRXBnwFpr/5pu4tskeW5VXVZVd0uSfs6RC5O8rt9/fZK/WugaYSJVtWbskeS0cbtOHb+vqr6da1trX0w3706S/E5VXdD/zZ2qenyS/9Xve3Nr7WML8X2MQrXmlixYLFX1PUk+0D89kORrUzS/sbV29vxXBfOjqsb+wXlWa+11i1kLTFdV/bsk788dk8/tSxfkxyZX/GS6kVKfW/jqYPr6pWa35Dvvd9+Xbv32MbvTXUT4p4WsDSYz7m+HI1nXWrt+XL/j0i2t/Pj+pW8muT13/L/7uiSbj5aJ6RJX3GGxjf9vcGWStVM87rrg1QEsc/2VygcneWm6kH5suuGVH0m39vU5QjtHg9baF5I8Islzk1yTZG+6EPP1dO/nFyd5sNDOUtBa+1a61RF+Jt2oqG+m+3/3Pyf5tSSPOppCe+KKOwAAAAyaK+4AAAAwYII7AAAADJjgDgAAAAMmuAMAAMCACe4AAAAwYII7AAAADJjgDgAAAAMmuAMAAMCACe4AAAAwYII7AAAADJjgDgAAAAMmuAMAAMCACe4AcJSpqhdWVauq102wr/WPMxa8MABgXgjuACx7VfW6cYH3W1V1tyO0/6Fx7VtVXbhApS47VfVoH0YAsNwJ7gDwnY5N8owjtPmJhShklj7TP7612IUAAKMhuAPAHW7otz8+WYOqWp3kCUn2J9m7EEXNRGvt/v3jc4tdCwAwGoI7ANzhg0n+X5KHVdUDJ2nzY0nulOQvktyyUIUBAMuX4A4A3+lP++1kV93HXn/DdA5WVU+qqr+sqi9W1a1V9aWqurqqvv8I/e5XVW/u299SVZ+uqhdU1Z2P0G/C+8HH3cf/win6vn+ie/ar6sL+9ff3z59eVf9YVV+vqi9X1Tuq6sxx7e9RVa+squur6kBV7ayqS6rqmKlqn6kJ6npSVb2vqm6qqv1V9aGqevoRjlFV9bSq+uv+d/TNqvpcVV1TVb9UVXeZoM+KqvrJqvpAVe3tv8ddVfXqqlo/yXnG7tW/vn/+/VX1933/m6rq76rqP4xrf0pVvbSqtve//xur6uVVdfwRvp9HVdWfV9W/9d/LV/rzPL2q6sg/VQCGSHAHgO80FtyfWVXf8e9kVW1Mcm6SG5O8f6qDVNVxVfXGJH+V5AeTrE13hf6uSZ6Y5G+q6uWT9P2eJB9Jd3X/rkluTbIuyQuTvC/dFf9F0df8piRn9y+tSfLDSf6hqjZW1YYk1yb5hSSr080Z8O+TXJbkinms6zfT/ay/p3/pxHS/qzdV1XMn6XNKkr9N8udJHp/kbkm+0df93Un+e5InHdLnhCTvTvIn/blOSnIgyRlJfjrJx6vqh45Q68/1x3hMkmOSnJLke5O8t6o2VdVdk/yfJL+e5J7p/l67d5LnJXnbFMd9eZJ/SPK0JPfq6zotyeZ0v7M3HfqeBuDo4H/eADBOa+1fk2xNF3w2H7J77Gr7n7XWDh7hUL+T5JlJdiZ5apKTWmunJDk5yc8l2ZfkeYdeEa6q09KFsxPShfeH9v1OSjcp3kP6/ovhoUl+Kclzk5zSWjs5yVnpJsO7S5KXJXljug82HtrvPznJb/T9f7aqHjRPdb0gyW8muUtr7dQkd0/y9n7/Zf3cBIf6s3SB+ZYkFydZ3Vpbne5n/4AkL0ry1UP6/Pck5yX5ZpKfSbKqP9/90n2YszJdQN44Sa13TfKKdB9k3KX/3a5Ld5vGyn7fHyU5Lt2HB6v6x08luS3JE6rq8YcetKouThfsdyd5dpJT+2OfmO4DoC/221+bpC4ABkxwB4DDjQ2Dv2DshX6Y8X8+ZP+E+qvOFyf5cpLHttbe1lr7RpK01va11l6VLlwlyfMP6f4L6a78fiXJ97fWPtr3+1Zr7Q1JnpPuCu1iOCXJS1trl7fWbu7r+ni6K81J8uQkG5I8flzdN7fWXprkvUkqyfnzVNcLWmsvaa3d1J93d7oPWr6cLhA/cXyHPvw+IUlLcn5r7YpxfVtr7VOttRe01v5yXJ8zxn2vF7fW/ri19s2+z/b+eP8vXfD/jUzshCRvaq09f9z5rk8Xqlu6kQxPSvLE1tr/6Wu5tbV2Ze543/3IId/LqUleku4K+/e31l7TWvtaf+xbWmtvSfdzb0l+taoWbcQGALMjuAPA4d6aLgSdX1Un9q/9pyT3TfJ/W2ufOkL/H08XUt/SWrtxkjZvT3fV9oFVdY9xr4+Fste01vZM0O/Pknx2Gt/DfLg13RXnQ21N9/NKkleNBdJDbOm383HF/UCSPzj0xdbaLUneM8l5x0ZPvKe19jfTPM+T0/3t9MV0Q+UPPd/N6UZaJN17Z7J7+i+boO8NSXb0T9/WWts5Qb/JfoZPSTci4+/HPjCZ4PgfTLIr3dD5R0xSFwADJbgDwCH64Hl1umHGT+lfnsmkdP+x3/5EP+HZYY8k/5ZuOHSS3CdJ+iuhY7PZf2CS2lqSa2b0DY3O9a21fYe+2N82MPYhw79M0nd3vz1tHur65NiIhgmMLYt36Hkf2W/fNYPzPLzf/kNr7fZJ2ry3356Ybvj8oQ7kjoB+qC/125n+DMfeb4+d7P3Wv+fu07e7TwA4qhy72AUAwEC9IcmPJrmgqt6W7kr4t5K8eRp9x66gj92ffCQn9NvV6SYrS5LPT9F+sdZo/8IU+24/Qpux/cdNsn8uDvswYZyxkQCHnndtv71hBue5a7+d6uf/bxO0H293/+HLRGb7Mxx7v52QO95LU5lOGwAGRHAHgIn9Tfp71NPdd74qyV9NMnz9UGMj2n6ptXbYEG6OeisXu4BDjL3fLm+tTTiDPgBHN0PlAWACrbXb0l1dX5Hkpf3Lfzp5j+8wNqT59Bmedm/uuKp6zynaTbVvMrf126lC52JNercYxn5H951Bny/326l+r/eeoP18m+37DYCjhOAOAJMbu5/9uHTLgl09zX4f7LePm8nJWmu3JvlE//R7JmrTz24/4b4jGJsw7t4T7ewn4TtzFsc9Wn2o3x62tNoUPtJvz+3Xc5/IY/vtN9Itk7cQxt5vj66q4xfonAAsIMEdACbRWvtwkhcm+f0kzx1b+msa3pBu6a0zq+o5UzXs120f72399qcnWXv8x5KcMc06xvt4vz2vqia66v5LSe48i+MercY+lDmvqqb7ActVSQ6mW7P+2Yfu7MP8r461nWICu1F7W7oPCk5L8t+majjB+w2Ao4DgDgBTaK39VmvtV/o11Kfb55NJXtE//Z9VdVlVfftKd1WtqqrzquqNuSOoj/kf6WYXX5PkPVV1Vt/nuKr6z0lek+Rrs/hWrk5yS7oJ095QVXfrj3tKVT0/3QcUsznu0erd/aOS/EVV/WK/Hnqq84Cq+v2q+uGxDq21zyZ5df/0ZVX17Kq6c99nY5K/TrI+yc3p1lVfEK21ryS5tH96SVW9pq8nfW3HV9V3V9WrkvzjQtUFwOgI7gAwP56X5FXp/q29JMmNVfW1qropXUB+T5Jn5o5Z5JMkrbWvJnlqupD9XUk+2vfZl+4e+4/1x52R1trevo6kmy1/d1V9Nd199S9J8qIk/zzT4x6t+pndn5Fu2b0TklyR5CtV9ZV0wfsTSX45yamHdP2vSf4u3eiEP06yr/85fibJo5N8M8kzWmvbF+Db+LbW2iuT/Ga6kR4/leQzVbW/qvYm2Z9uCcGfyfAm1gNgGgR3AJgHrbXbW2s/l+RRSd6Y5LPpwt7KdEuQ/VW62ep/ZIK+H0jysCRvSTfB2Z2TXJ/uqvhj04XD2dR0RZKnpbu/++Z0fwdsTfLk1tqLZnPMo1lr7aZ0P8+fSPL36T7EWJXkK+kC/XPT/Z7G97k5yQ+kC8f/kO7neEK63++fJHlwa+0vF+hb+A6ttZckeUi6UQE70v1+T0y3vNx70n2Y9N2LURsAc1OTLyUKAAAALDZX3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYMMEdAAAABkxwBwAAgAET3AEAAGDABHcAAAAYsP8Ps5bPXW9yjA8AAAAASUVORK5CYII=\n",
"text/plain": [
""
]
},
"metadata": {
"image/png": {
"height": 392,
"width": 503
},
"needs_background": "light"
},
"output_type": "display_data"
}
],
"source": [
"predictions = model_constraint.predict(rows)\n",
"\n",
"plt.scatter(impute_values, predictions)\n",
"plt.title('Medium Income v.s. Medium House Value')\n",
"plt.xlabel('Medium Income')\n",
"plt.ylabel('Medium House Value')\n",
"plt.show()"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"# Reference"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"- [Blog: Monotonicity constraints in machine learning](https://blog.datadive.net/monotonicity-constraints-in-machine-learning/)\n",
"- [Blog: A Tutorial of Model Monotonicity Constraint Using Xgboost](https://xiaoxiaowang87.github.io/monotonicity_constraint/)\n",
"- [Blog: How does the popular XGBoost and LightGBM algorithm enforce monotonic constraint](https://towardsdatascience.com/how-does-the-popular-xgboost-and-lightgbm-algorithms-enforce-monotonic-constraint-cf8fce797acb)\n",
"- [Stackoverflow: how does xgboost enforce monotonicity constraints](https://stackoverflow.com/questions/44236078/how-does-xgboost-enforce-monotonicity-constraints)"
]
}
],
"metadata": {
"kernelspec": {
"display_name": "Python 3",
"language": "python",
"name": "python3"
},
"language_info": {
"codemirror_mode": {
"name": "ipython",
"version": 3
},
"file_extension": ".py",
"mimetype": "text/x-python",
"name": "python",
"nbconvert_exporter": "python",
"pygments_lexer": "ipython3",
"version": "3.6.4"
},
"toc": {
"nav_menu": {},
"number_sections": true,
"sideBar": true,
"skip_h1_title": false,
"title_cell": "Table of Contents",
"title_sidebar": "Contents",
"toc_cell": true,
"toc_position": {
"height": "calc(100% - 180px)",
"left": "10px",
"top": "150px",
"width": "256px"
},
"toc_section_display": true,
"toc_window_display": true
},
"varInspector": {
"cols": {
"lenName": 16,
"lenType": 16,
"lenVar": 40
},
"kernels_config": {
"python": {
"delete_cmd_postfix": "",
"delete_cmd_prefix": "del ",
"library": "var_list.py",
"varRefreshCmd": "print(var_dic_list())"
},
"r": {
"delete_cmd_postfix": ") ",
"delete_cmd_prefix": "rm(",
"library": "var_list.r",
"varRefreshCmd": "cat(var_dic_list()) "
}
},
"types_to_exclude": [
"module",
"function",
"builtin_function_or_method",
"instance",
"_Feature"
],
"window_display": false
}
},
"nbformat": 4,
"nbformat_minor": 2
}
![](\"img/monotonic_node.png\")
\n",
"\n",
"Now this sounds good when the feature is picked once, however, what if on a split further down the tree that feature gets picked again? Let's imagine if the tree goes on and do the same thing to the left child (L) which happens to pick the same feature again, we will get a higher weight assigned to the right child of the left child (LR) because of the positive monotonic constraint we enforced. That weight, however, may be even higher than that of the right child (R) we previously obtained. In other words, we need to have make sure the constraint is enforced at the tree level. Not only should the weight assigned to the right child (R) be higher than the left child (L), but it should also be higher than its descendant that decides to use the same feature (LL, LR, LLL, LLR, LRL, LRR, etc.)\n",
"\n",
"To achieve this, when splitting on a node, the weight of the children node is bounded by the mean of their parent and uncle nodes weight (uncle refers to the same level as the node's direct parent).\n",
"\n",
"Using a similar example stated above: the weight of the left child's right child (LR) is now bounded by the left child(L) and right child(R)'s mean weight. And because the weight of the left child(L) is lower than the right child(R), the weight of the left child's right child (LR) can never exceed the weight of the right child(R).\n",
"\n",
"\n",
"![](\"img/monotonic_tree.png\")
\n",
"\n",
"Or if preferred the psuedocode below:\n",
"\n",
"```python\n",
"min_value = node.min_value\n",
"max_value = node.max_value\n",
"\n",
"check(min_value <= split.left_output) \n",
"check(min_value <= split.right_output)\n",
"check(max_value >= split.left_otput)\n",
"check(max_value >= split.right_output)\n",
"mid = (split.left_output + split.right_output) / 2;\n",
"\n",
"if (split.feature is monotonic increasing) {\n",
" check(split.left_output <= split.right_output)\n",
" node.left_child.set_max_value(mid)\n",
" node.right_child.set_min_value(mid)\n",
"}\n",
"if (split.feature is monotonic decreasing ) {\n",
" check(split.left_output >= split.right_output)\n",
" node.left_child.set_min_value(mid)\n",
" node.right_child.set_max_value(mid)\n",
"}\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## LightGBM Monotonic Constraint"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"Specifying monotonic constraint is also available in lightgbm, expect the parameters are a little different from xgboost."
]
},
{
"cell_type": "code",
"execution_count": 19,
"metadata": {},
"outputs": [
{
"data": {
"text/plain": [
"