{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "cb3b5d69",
   "metadata": {},
   "source": [
    "# A tour of transmorph *merging* modules\n",
    "\n",
    "Merging algorithms are a special class of transformations which take as additional input similarity relationships between samples that were estimated via a matching. They return an integrated view of all datasets jointly embedded in a common feature space, so that matched items tend to be close from one another in the final representation. The embedding step is in general the last step in an integration model, and is chosen depending on the required output type. For instance, a joint embedding of datasets in an abstract space is suited for applications like visualization or clustering, while matrix factorization algorithms often require the embedding to be performed in an expressive feature space.\n",
    "\n",
    "In this tutorial we will present the current available merging modules, as well as the way to implement custom merging modules."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8d2168a9",
   "metadata": {},
   "source": [
    "## Toy dataset and plotting function\n",
    "\n",
    "Let us start by loading a small dataset to illustrate our mergings, and defining a custom plotting function for them."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "03a599c6",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "text/plain": [
       "{'src': AnnData object with n_obs × n_vars = 10 × 2\n",
       "     obs: 'class',\n",
       " 'ref': AnnData object with n_obs × n_vars = 9 × 2\n",
       "     obs: 'class'}"
      ]
     },
     "execution_count": 5,
     "metadata": {},
     "output_type": "execute_result"
    }
   ],
   "source": [
    "from transmorph.datasets import load_test_datasets_small\n",
    "\n",
    "datasets = load_test_datasets_small()\n",
    "datasets"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 61,
   "id": "8febfc1b",
   "metadata": {},
   "outputs": [],
   "source": [
    "import anndata as ad\n",
    "import matplotlib.pyplot as plt\n",
    "from typing import List, Optional\n",
    "\n",
    "from mpl_toolkits.axes_grid1 import make_axes_locatable\n",
    "\n",
    "SHAPES = ['s', 'o']\n",
    "COLORS = ['red', 'blue']\n",
    "\n",
    "def scatter_plot(datasets: List[ad.AnnData], use_rep: Optional[str] = None, plot_before: bool = False) -> None:\n",
    "    \"\"\"\n",
    "    Custom scatter_plot function that can also plot a matching between dots.\n",
    "    \"\"\"\n",
    "    fig = plt.figure(figsize=(5,5))\n",
    "    ax_scatter = fig.add_subplot(111)\n",
    "            \n",
    "    # \"Before\" position\n",
    "    if plot_before:\n",
    "        ax_scatter.scatter([], [], marker=\"h\", c=\"w\", ec=COLORS[0], linestyle=\"--\", label=\"Dataset src (before)\")\n",
    "        for dclass, shape in zip((0, 1), SHAPES):\n",
    "            ax_scatter.scatter(\n",
    "                *datasets['src'].X[datasets['src'].obs['class'] == dclass].T, \n",
    "                s=40,\n",
    "                c=\"w\",\n",
    "                marker=shape,\n",
    "                ec=COLORS[0],\n",
    "                linestyle='--'\n",
    "            )\n",
    "\n",
    "    # Scatter plot\n",
    "    for (adata_name, adata), color in zip(datasets.items(), COLORS):\n",
    "        if use_rep is None:\n",
    "            X = adata.X\n",
    "        else:\n",
    "            X = adata.obsm[use_rep]\n",
    "        for dclass, shape in zip((0, 1), SHAPES):\n",
    "            ax_scatter.scatter(\n",
    "                *X[adata.obs['class'] == dclass].T,\n",
    "                s=40,\n",
    "                c=color,\n",
    "                marker=shape\n",
    "            )\n",
    "\n",
    "    # Annotations\n",
    "    ax_scatter.set_xticks([])\n",
    "    ax_scatter.set_yticks([])\n",
    "    ax_scatter.set_xlabel(\"Feature 1\", fontsize=16)\n",
    "    ax_scatter.set_ylabel(\"Feature 2\", fontsize=16)\n",
    "\n",
    "    # Legend outside of plot\n",
    "    for (adata_name, adata), color in zip(datasets.items(), COLORS):\n",
    "        ax_scatter.scatter([], [], c=color, marker=\"h\", label=f\"Dataset {adata_name}\")\n",
    "    for dclass, shape in zip((0, 1), SHAPES):\n",
    "        ax_scatter.scatter([], [], c=\"k\", marker=shape, label=f\"Sample type {dclass}\")\n",
    "\n",
    "    divider = make_axes_locatable(ax_scatter)\n",
    "    ax_legend = divider.append_axes(\"right\", size=\"5%\", pad=0.1)\n",
    "    handles, labels = ax_scatter.get_legend_handles_labels()\n",
    "    for label in labels:\n",
    "        ax_legend.scatter([], [], label=label)\n",
    "    legend = ax_legend.legend(\n",
    "        handles,\n",
    "        labels,\n",
    "        fontsize=12,\n",
    "        loc=\"center left\",\n",
    "    )\n",
    "    ax_legend.axis(\"off\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 56,
   "id": "94c5dd8d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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/fqKj4933SggFV6GLBr4tKTwVNHak5KSlJqaqhdffFGff/65evTooYCAAGVmZmrx4sWaNWuWazsl6d+/vzp06KBhw4Zp3759qlOnjubMmaOCggJNnjy5zM9YYWXeI1mGJ554wvj5+RnLsoxlWW6/X/nez8/P000wDAUA+ChfHYZi//79FRqGYv/+/VWyvfKsWrXKDB8+3LRo0cLUrl3bBAYGmmbNmpmxY8ea48ePu7Vdvny5ad26tQkODjZxcXFm2rRp5s033zSSTFZWlqtd48aNTc+ePYttS5IZM2aM27SsrCwjybz00kuuaUOGDDGhoaHmwIEDpkePHuamm24yMTExJi0tzRQUFBRb55XDQBhjzPHjx82YMWNcQ07VrVvXdO3a1aSnp5e7P77++mtzzz33mJCQECOp2JAUFy9eND/5yU9MREREicfEtdRujDHp6ekmMTHRhISEmLCwMJOQkGDGjx9vjh49Wm6tp06dMiNGjDC33HKLuemmm0xSUpL59NNPy12uose0Zcy198xbvHixHnzwQTVs2FATJ07U0qVLtW7dOq1evVqZmZnKyMjQtm3b9NRTTyk5OVlJSUkehcOcnBxFRETI4XAoPDzco3UAAKpeVX0/X7hwQVlZWYqPj3fd4l9ZmZmZys3NLXV+WFiYLYOw+qqhQ4dqyZIlOnv2rLdLKSY/P1/169dXSkqK/vKXvxSb78u1F6noMe3RJcj09HT5+/vro48+0q233qqtW7dKKhzvpHv37ho9erQmTpyol156SQMGDPDsEwAA4IEbOVxVdx988IFOnjypwYMHe7uU686jTvi7d+9W+/btyzzIJ0+erHr16mnq1KkeFwcAAGq+HTt2aN68eXr88cd1++23e3zlrDrxKIDl5ua63SYbGBgoSW6nBP38/NS+fXtt2bKlkiUCAICabO7cufrd736n6Oho/fWvf/V2ObbwKIBFRUW53cJZdJvo1aPnnjt3Tjk5OR4XBwAAqtaCBQt8rg/VggULlJ+fr507d5b50HJfrN1THgWwuLg4HT582PX+9ttvlzFGixYtck374Ycf9MknnzBaPgAAwFU8CmBdu3bV119/7Trjdf/99+vmm2/WtGnT9Ktf/UpPPPGE2rdvr3Pnzqlfv35VWS8AAEC159FdkA899JCOHj2q7777TnFxcQoNDdX8+fP10EMPaenSpa52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\n",
      "text/plain": [
       "<Figure size 500x500 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "scatter_plot(datasets)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f03c1e0d",
   "metadata": {},
   "source": [
    "Let us also create a helper function which creates a minimal model using a given merging. Given we possess all class information about our toy dataset and it is quite small, we can use the \"Labels\" matching which connects together all samples with similar label across datasets."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "b684134d",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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\n",
      "text/plain": [
       "<Figure size 1000x140 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "from transmorph.engine import Model\n",
    "from transmorph.engine.layers import LayerInput, LayerMatching, LayerMerging, LayerOutput\n",
    "from transmorph.engine.matching import Labels\n",
    "from transmorph.utils.plotting import plot_model\n",
    "\n",
    "def create_model_merging(merging=None):\n",
    "    # Creates a minimalist model endowed with a set of transformations\n",
    "\n",
    "    # Initializes layers\n",
    "    layer_input = LayerInput()\n",
    "    layer_matching = LayerMatching(matching=Labels(label_obs=\"class\"))\n",
    "    layer_merging = LayerMerging(merging=merging)\n",
    "    layer_output = LayerOutput()\n",
    "\n",
    "    # Setup connections\n",
    "    layer_input.connect(layer_matching)\n",
    "    layer_matching.connect(layer_merging)\n",
    "    layer_merging.connect(layer_output)\n",
    "\n",
    "    # Build model\n",
    "    model = Model(input_layer=layer_input)\n",
    "    return model\n",
    "\n",
    "# Creating an empty model\n",
    "plot_model(create_model_merging())"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d1c651db",
   "metadata": {},
   "source": [
    "## Barycentric merging\n",
    "\n",
    "Barycentric merging simply projects every cell onto the everage of its matches, weighted by the matching value. In our case, Labels matching associates to each edge a weight of one, effectively making an unweighted average. Barycentric merging requires a reference dataset to be set, and every cell in non-reference datasets to be matched otherwise they will me mapped to zero. On the other hand, it can work when datasets are embedded in non-overlapping spaces.\n",
    "\n",
    "Her we set the blue dataset to be the reference, and we store the model result into AnnDatas .obsm field associated with key \"X_barycenter\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 43,
   "id": "8ed7c4c4",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CUSTOM_MODEL > Transmorph model is initializing.\n",
      "CUSTOM_MODEL > Ready to start the integration of 2 datasets, 19 total samples.\n",
      "CUSTOM_MODEL > Running layer LAYER_INPUT#47.\n",
      "CUSTOM_MODEL > Running layer LAYER_MATCHING#48.\n",
      "LAYER_MATCHING#48 > Calling matching MATCHING_LABELS.\n",
      "CUSTOM_MODEL > Running layer LAYER_MERGING#49.\n",
      "LAYER_MERGING#49 > Running merging MERGING_BARYCENTER...\n",
      "CUSTOM_MODEL > Running layer LAYER_OUTPUT#50.\n",
      "CUSTOM_MODEL > Terminated. Total embedding shape: (19, 2)\n",
      "CUSTOM_MODEL > Results have been written in AnnData.obsm['X_barycenter'].\n"
     ]
    }
   ],
   "source": [
    "from transmorph.engine.merging import Barycenter\n",
    "\n",
    "model_barycenter = create_model_merging(Barycenter())\n",
    "model_barycenter.fit(datasets, reference=datasets[\"ref\"], output_representation=\"X_barycenter\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 62,
   "id": "a883a1ee",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "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RESyMDgSERERkSwMjkREREQkC4MjEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLIwOBIRERGRLAyORERERCQLgyMRERERycLgSERERESyMDgSERERkSwMjkREREQkC4MjEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLIwOBIRERGRLAyORERERCQLgyMRERERycLgSERERESyMDgSERERkSwMjkREREQkC4MjEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLLYmLsAIiIiABBCoLCwEAUFBeYuhajasLGxgbW1NSRJkte/nOshIiIqlRACWVlZuHnzJgoLC81dDlG1Y21tDaVSCYVCUWaAZHAkIiKzun79OrKysuDq6gpXV1fY2NjIHv0gIuMJIVBQUIDs7Gxcu3YNubm5qFOnTqnvYXAkIiKzKSwshEqlgru7O2rXrm3ucoiqJRcXF9jb2yMjIwNKpRLW1tYl9uXFMUREZDYPHjyAEAJOTk7mLoWoWnNycoIQAg8ePCi1H0cczSElBcjJ0W3z8gLc3YHMTODSJcDFBXjySbOUB6By1EhEVQYPTROZl9zfQY44VrTr14ERI4DAQN3Hjz9qlm/ZonnduLEmvLFGIiIishAccaxonp7Apk3A33/rtnt5aZ5ffBH4/ntg6FD9Eb+KUhlqJCIiogrHEceKVlgI2NsDTz8NtG7978PdXbO8Zk2gWTPWSEREVE7mzp2Lpk2bQq1WAwAuXboESZLw2WefmXQ7KSkpCA0N1U5zs2nTJpOuvyxTpkxB+/btTbpOBseKdvIkoFBonkvi5AQEBWmezaEy1EhEVAmsWLECkiRpHw4ODqhbty7CwsLwxRdfIOcxjtokJydjxowZyMrKMl3Bj2HJkiVYsWKFucsoU3Z2NubMmYP33nsPVlblG4OGDx+OP/74Ax9//DFWrlyJNm3alOv2HjZx4kScPHkSCQkJJlsng6MlatIEOHhQ82ypKkONREQW4sMPP8TKlSsRExOD8ePHA9D8ox4QEIDff//dqHUmJydj5syZDI6PaPny5SgoKMArr7xSrtvJzc3FwYMHMWrUKLzxxhsYOnQo6tevX67bfJinpyd69+5t0pFUnuNIRERUzrp3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i7lz52LUqFHmLqdcXb9+HT4+PlizZk2ZI45yfxdlneNYdNubLVu24P3338eLL76ICRMm4NSpUxg2bBhyc3PRu3dvJBXN0k9ERERkgRQKBSZPnox58+bJukq9Mlu4cCECAgJMd5gaMoPj8ePH0bZtW3Tq1Emn3dHREStWrMDMmTORl5eHvn37IjEx0WTFEREREZnae++9p72KuSr79NNP8euvv5p0nbL2WNGwbkmmT5+Ozz77DPn5+ejXrx/DIxEREVEVJCs4urq64nYZt2l6++23ER0djfz8fPTv3197ex4iIiIiqhpkTcfTrFkzHD16tMxb1owfPx5WVlYYP348+vfvX+ooJRERERFVLrJGHJ9//nlkZmZix44dZfYdN24clixZgvv37+PcuXOPXSARERERWQZZwbF79+4QQsiamBIA/u///g9fffXVYxVGRERERJZF1qHqoKAgpKSkPNJ9KMeMGYN27drJvv0QEREREVk2WcFRkiTtTbUfhaluqE1ERERE5le1JzAiIiIiIpNhcCQiIiIiWRgciYiIiEgWBkciIqJysmLFCkiSpH04ODigbt26CAsLwxdffIGcnByj152cnIwZM2ZYzEWoS5YswYoVK8xdBpUzBkciIqJy9uGHH2LlypWIiYnB+PHjAQATJ05EQEAAfv/9d6PWmZycjJkzZzI4UoWSdVU1ERERGa979+5o06aN9vXUqVOxa9cu9OzZE7169cLZs2fh6Ohoxgorh7t378LJycncZVRrHHEkIqKqKy8P2LVL82xhunTpgunTp+Py5cv4/vvvte2///47RowYAV9fXzg4OMDT0xMjR47ErVu3tH1mzJiBSZMmAQB8fHy0h8IvXboEAIiLi0OXLl2gVCphb2+P5s2bIyYmRq+Go0ePIiwsDLVr14ajoyN8fHwwcuRInT5qtRoLFy6Ev78/HBwc4OHhgcjISNy+fVvbp2HDhjh9+jT27t2rraVz586lfv41a9YgMDAQLi4ucHV1RUBAAKKjo7XLiw7z7927F2PHjoVSqUT9+vW1yxMTExEcHKx9f9u2bbFq1aqydzw9Fo44EhFR1SMEsGkTMGEC8PffgJcXEB0N9OkDPMLNLMrbq6++imnTpmHbtm0YM2YMAGD79u1ITU1FREQEPD09cfr0acTGxuL06dM4dOgQJElCv379cP78eaxevRoLFixA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s9ycF51UhhqJ6PHExMTg9ddfh1KpxHfffWfucqgUVfMcxw0bNKEsPV1z5XJcHHDvnmaamxUrADe38ipZvkWLgP/8B8jJ0dQYG6sZNhk1CvjiCx6qpgpT0hyJarXlzJFYGWqsbirDOY5EJJ/c38WqGRwB4P59ICEBqFkTOHECCA8HnnyyXOo02p07wPr1QP36mvkb+/UD6tY1d1VUTRW/K4unp+YQsaWN4lWGGqsLBkeiqoXBkYiIyg2DI1HVIvd3sWqd40hERJWSBY9hEFULcn8HGRyJiMhsbG1tIUkS7t69a+5SiKq1u3fvQpIk2JZxwnjVmseRiIgqFWtraygUCty8eRP5+flwdXWFjY1NifeaJiLTEUKgoKAA2dnZyM7OhpubW5mT5DM4EhGRWXl6esLR0RE3btxAdna2ucshqnasra1Rp04dKBSKMvsyOBIRkVlJkgQ3NzcoFAoUFhaioKDA3CURVRs2NjawtraWPcrP4EhERBZBkiTY2NjAxob/NBFZKl4cQ0RERESyMDgSERERkSwMjkREREQkC4MjEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLIwOBIRERGRLAyORERERCQLgyMRERERycLgSERERESyMDgSERERkSwMjkREREQkC4MjEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLIwOBIRERGRLAyORERERCQLgyMRERERycLgSERERESyMDgSERERkSwMjkREREQkC4MjEREREcnC4EhEREREsjA4ElHlsWgRULMm4OioeV60yNwVERFVK5IQQpi7iJJkZ2dDoVBApVLB1dXV3OUQkblkZAB16wIPHugvs7UFrl4Fateu+LqqMX4/E1VPHHEkIstXUmgENO1161ZsPURE1RSDIxFZtoULSw6NRR484GFrIqIKwEPVRGTZatYEbt8uu1+NGkBmZvnXQwD4/UxUXXHEkYgsW26uafsREZHRGByJyLI5Opq2HxERGY3BkYgs2wcfyOs3c2b51kFERDzHkYgqATu70i+QsbUF7t+vuHqI389E1RRHHInI8l29qgmHhhTN40hEROWOwZGILF/t2poRxS++0Fw97eCgudr6iy807Zz8m4ioQvBQNRERPTJ+PxNVTzbmLoCISK60NCA+HkhPBzw8gCFDAB8fc1elqzLUSERkLI44EpHFe/AAGDcO+PprwMpK81CrNY/Ro4Evvyz5FEjWWD74/UxUPXHEkYgsXlEgEwIoLNQ8inz9teY5NtY8tRWpDDUSET0ujjgSkUVLTQUaNdIEspJIEnDxovkOCVeGGk2N389E1ROvqiYii7Zqleawb2msrDTnFZpLZaiRiMgUGByJyKKlp8sLZenpFVOPIZWhRiIiU2BwJCKL5uGhucCkNGq1pp+5VIYaiYhMgcGRiCza4MHyQtmQIRVTjyGVoUYiIlNgcCQii+brq5nORpIML5ckzXJzXnRSGWokIjIFTsdDRBbvyy81z6XNkWhulaFGIqLHxel4iKjSKH5XFk9PzSFiSxvFqww1mgK/n4mqJwZHIiJ6ZPx+JqqeeI4jEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLIwOBIRERGRLAyORERERCQLgyMRERERycLgSERERESyMDgSERERkSwMjkREREQkC4MjEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLIwOBIRERGRLAyORERERCQLgyMRERERycLgSERERESyMDgSERERkSwMjkREREQkC4MjEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLIwOBIRERGRLAyORERERCQLgyMRERERycLgSERERESyMDgSERERkSwMjkREREQkC4MjEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLIwOBIRERGRLAyORERERCQLgyMRERERycLgSERERESyMDiaS2YmMGsWMH265nV+PvDOO0BKinnrKu6vvzQ1ffWV5vXVq8C0acC1a+ati6qttDTgo4+A8eM1z2lp5q6IiKh6YXA0hytXgHbtgE8/BXJyNG3nzwPx8UDr1sDeveatDwCOHwdatQJWrADu3dO0nTwJfPklEBgI/PmnWcuj6uXBA+C11wA/P2DGDGDpUs2zn5+m/cEDc1dIRFQ9SEIIYe4iSpKdnQ2FQgGVSgVXV1dzl2M6zz8PpKYCe/YAPj7/tt+9C/TurQltly8Dzs7mqe/BA+DJJwF3d2DrVqBmzX+XXb8OhIQAVlbA778D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sCGcnZ1hZWWFbdu2ISwsDEKIcqu5JI6OjqW+z9PTE2FhYaWuo3bt2sYVR0REVAyDI1UpXl5eAABJkrB8+XJYWck7jXfz5s3Izc1F3759MWfOHL3lKSkpRtdUdAV0Tk6OweWXL182ar1Fn7VWrVolTvVDRERkSrw4hqqUunXrokWLFsjJyUFSUpLs92VmZgIAvL299ZYJIbBq1SqD7ysKhQUFBSWuu169egCAs2fPGlx3YmKi7DqLa9u2LWrXro0zZ87g9OnTRq2DiIjoUTA4UpXz0UcfAdBcgb1582a95UIIHD58GNu2bdO2NWvWDIDmqumiC2EAoLCwEB988EGJF5e4u7vDzs4O169f14bPh3Xt2hUAsHLlSpw5c0bb/uDBA7z33ns4cuTII35CDVtbW+0V5H379sX+/fv1+hQWFmLXrl04dOiQUdsgIiIqjoeqqcoJDw9HdHQ03nnnHfTq1QuNGjVCkyZNoFAocPPmTZw8eRI3btzAe++9h9DQUO17AgMD8dtvv6Fx48YIDg6Gk5MTDh8+jKtXr+K9994zeAjb1tYWvXr1wrp169CyZUt07NgRTzzxBADg66+/BqC5Erx379746aef0KZNG3Ts2BGOjo44duwYsrOzMWHCBERHRxv1Wd944w389ddfmDdvHjp16gR/f380atQIjo6OuH79Ok6cOIGsrCzExMQgKChI1jqvXbuGvn37al9fuXIFAJCQkKCzjiVLlqB169ZG1U1ERJUTgyNVSW+++Sa6dOmCRYsWae/8YmVlBU9PT7Rq1Qo9evTQuXjGxsYGe/bswezZs7F+/Xrs3LkTrq6uePbZZ7F+/Xrk5OQYDI4AsHTpUtSqVQuJiYlYt24dHjx4AODf4AgAP/zwAz766COsWrUKe/bsQY0aNRASEoJZs2Zh3759j/VZ586diz59+mDJkiXYv38/kpKSYGdnhzp16qBz587o2bMn+vXrJ3t9+fn5OHz4sF77zZs3da7ONscV5kREZF6SKI/LRImIiIioyuE5jkREREQkC4MjEREREcnC4EhEREREsjA4EhEREZEsDI5EREREJAuDIxERERHJwuBIRERERLIwOBIRERGRLAyORERERCQLgyMRERERycLgSERERESyMDgSERERkSwMjkREREQky/8DvEpfBBErA5IAAAAASUVORK5CYII=\n",
      "text/plain": [
       "<Figure size 500x500 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "scatter_plot(datasets, use_rep=\"X_barycenter\", plot_before=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4b21ca1f",
   "metadata": {},
   "source": [
    "Unsurprisingly, blue points are mapped to the barycenter of their corresponding class within the red dataset. This is due to the Labels which cause blue points of the same class to have the same matching points within the reference dataset."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dba5e17b",
   "metadata": {},
   "source": [
    "## Linear correction merging\n",
    "\n",
    "Inspired from Seurat, linear correction is a linear merging based on first computing a set of correction vectors, and then use them to correct batches with respect to a reference batch. It not only (1) necessitates to choose a reference batch, but also (2) for all batches to be embedded in a common feature space. It can work with incomplete matchings, meaning not every cell in the query batch necessitates to be matched with a cell in the reference batch. To correct a given batch, the algorithm follows a two-step process: it first computes correction vectors from matched samples to reference samples, and then extrapolates the correction vectors to the unmatched samples.\n",
    "\n",
    "Doing so, it is able to correct cells which possess no match within the reference dataset if they are close enough from a matched cell. The downside is that correction must take place in a common feature space, which makes it unusable when datasets do not share common features. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 58,
   "id": "d6d2fa48",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CUSTOM_MODEL > Transmorph model is initializing.\n",
      "CUSTOM_MODEL > Ready to start the integration of 2 datasets, 19 total samples.\n",
      "CUSTOM_MODEL > Running layer LAYER_INPUT#51.\n",
      "CUSTOM_MODEL > Running layer LAYER_MATCHING#52.\n",
      "LAYER_MATCHING#52 > Calling matching MATCHING_LABELS.\n",
      "CUSTOM_MODEL > Running layer LAYER_MERGING#53.\n",
      "LAYER_MERGING#53 > Running merging MERGING_LINEAR_CORRECTION...\n",
      "CUSTOM_MODEL > Running layer LAYER_OUTPUT#54.\n",
      "CUSTOM_MODEL > Terminated. Total embedding shape: (19, 2)\n",
      "CUSTOM_MODEL > Results have been written in AnnData.obsm['X_linearcorrection'].\n"
     ]
    }
   ],
   "source": [
    "from transmorph.engine.merging import LinearCorrection\n",
    "\n",
    "model_barycenter = create_model_merging(LinearCorrection(n_neighbors=3))\n",
    "model_barycenter.fit(datasets, reference=datasets[\"ref\"], output_representation=\"X_linearcorrection\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 59,
   "id": "a9fa6d82",
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAo4AAAGzCAYAAAChApYOAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjYuMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy89olMNAAAACXBIWXMAAA9hAAAPYQGoP6dpAABdtklEQVR4nO3deVwU9f8H8NcsdxyLBwseiICaSpiKB+VBeUCmeOe31FRQozTT+qZ5VGhappZKqaT2FcvQ+npkUOKV2tdE7fAor0RB01SUlAUVUNjP74/5sbHuAuO6sAu8no/HPtad+czMewZZX35m5jOSEEKAiIiIiKgcKmsXQERERERVA4MjERERESnC4EhEREREijA4EhEREZEiDI5EREREpAiDIxEREREpwuBIRERERIowOBIRERGRIvbWLqAsOp0Oly5dgru7OyRJsnY5RET0/4QQyM3NRf369aFSsQ+CqKaw6eB46dIl+Pr6WrsMIiIqxYULF9CwYUNrl0FElcSmg6O7uzsA+YvJw8PDytUQEVGxnJwc+Pr66r+niahmsOngWHx62sPDg8GRiMgG8TIiopqFF6YQERERkSIMjkRERESkCIMjERERESnC4EhEREREijA4EhEREZEiDI5EREREpAiDIxEREREpwuBIRERERIowOBIRERGRIjb95BgiApCWBuTmlj7f3R1o2rTy6qmp+HMgImJwJLJpaWlAs2bltzt9mqGlIvHnQEQEgKeqiWxbWT1c5rQj8/DnQEQEgMGRiIiIiBRicCQiIiIiRRgciYiIiEgRBkciIiIiUoTBkYiIiIgUYXAkIiIiIkUYHIlsmbu7ZduRefhzICICwAHAiWxb06byoNJ8Yol18edARASAwZHI9jGM2Ab+HIiIeKqaiIiIiJRhcCQiIiIiRRgciYiIiEgRBkciIiIiUoTBkYiIiIgUYXAkIiIiIkUYHImIiIhIEQZHIiIiIlKEwZGIiIiIFGFwJCIiIiJFGByJiIiISBEGRyIiIiJShMGRiIiIiBRhcCQiIiIiRRgciYiIiEgRBkciIiIiUoTBkYiIiIgUYXAkIiIiIkUYHImIiIhIEQZHIiIiIlKEwZGIiIiIFGFwJCIiIiJFGByJiIiISBEGRyIiIiJSxN7aBVhcWhqQm2s4zdcX8PICrl8Hzp0D3N2Bpk2tUl6VUfI43nv8AB5DIiKiGqh6BccrV4BRo4DUVMPpS5YA48cDW7YAzz8vTzt9msGnNGlpQLNm/3w2dfwAHkOqcKb+H1gS//+iDI8jEVlK9QqOPj7A5s3AhQuG03195fennwa++AIYPrzsb9GarvjYfPEF0KKF4fH79Vfg5EkeQ6pw9/7/pTT8/0vZeByJyJKqV3AsKgKcnIBHHwXs7Izn164tByEqm7s7EB4OdOhg+C9J7dryy9UVCA2V34kqiNL/l/D/L2XjcSQiS6peN8ccPQqo1fJ7aRh6yte0KbBtW+ndDw8/DOzfL78TERFRjVG9ehyVKA49VLqiIuDWLTlcm+q5JSIiohqpevU4kmWU13N76BAgSfI7ERER1Rg1Lzgy9BARERGZpeYFRyIiIiIyS/W6xjE4WD69mpdn2KNYqxbg7w/k58tDyZAy9/bKljyOREREVONUr+Do4ABs2gTMmmU4fdgweUzCixfl8QcBecgZMq1ePfl97FjD6cXHUZLkzzyGVIGU/vXiX8Oy8TgSkSVJQghh7SJKk5OTA7VaDa1WCw8PD2ULXb4sv0oq2VN24gQfk6BEecfxwgUeQ6pwfOKJZVTEcTTr+5mIqrzqFxyJiKjC8fuZqGbizTFEREREpAiDIxEREREpwuBIRERERIowOBIRERGRIgyORERERKQIgyMRERERKcLgSERERESKMDgSERERkSIMjkRERESkCIMjERERESnC4EhEREREijA4EhEREZEiDI5EREREpAiDIxEREREpYm/tAoioBkhLA3JzS5/v7g40bVp59dRU/DkQ0QNicCSiipWWBjRrVn6706cZWioSfw5EZAE8VU1EFausHi5z2pF5+HMgIgtgcCQiIiIiRRgciYiIiEgRBkciIiIiUoTBkYiIiIgUYXAkIiIiIkUYHImIiIhIEQZHIqpY7u6WbUfm4c+BiCyAA4ATUcVq2lQeVJpPLLEu/hyIyAIYHImo4jGM2Ab+HIjoAfFUNREREREpwuBIRERERIowOBIRERGRIgyORERERKQIgyMRERERKcLgSERERESKMDgSERERkSIMjkRERESkCIMjERERESnC4EhEREREijA4EhEREZEiDI5EREREpAiDIxEREREpYm/tAmqktDQgN9dwmq8v4OUFXL8OnDsHuLsDTZtapbwqgceQiIio0jE4VrYrV4BRo4DUVMPpS5YA48cDW7YA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NblccSgsLCwsdd0NGjQAAJw8edLkulNSUhTXWVL79u1Rt25dnDhxAsePHzdrHURERPeDwZGqnTlz5gCQ78BOTk42mi+EwMGDB7F9+3b9tBYtWgCQ75ouvhEGAIqKivD222+XenOJl5cXHB0dceXKFX34vFePHj0AAGvWrMGJEyf00+/evYs33ngDP//8833uoczBwUF/B/mAAQPw448/GrUpKirCrl27cODAAbO2QUREVBJPVVO1ExkZibi4OPz73/9G37590aRJEzz88MNQq9W4du0ajh49iqtXr+KNN95AeHi4fpmQkBD8+uuvaNasGcLCwuDq6oqDBw/i0qVLeOONN0yewnZwcEDfvn2xYcMGtG7dGp07d8ZDDz0EAPj0008ByHeC9+vXD9988w3atWuHzp07w8XFBYcOHUJOTg4mTpyIuLg4s/b15Zdfxp9//okFCxagS5cuCAoKQpMmTeDi4oIrV67gyJEjyM7ORnx8PEJDQxWt8/LlyxgwYID+88WLFwEASUlJButYtmwZ2rZta1bdRERUNTE4UrX0yiuvoFu3bvj444/1T35RqVTw8fFBmzZt0Lt3b4ObZ+zt7bFnzx7MnTsXGzduxPfffw8PDw88/vjj2LhxI3Jzc00GRwBYvnw56tSpg5SUFGzYsAF3794F8E9wBICvvvoKc+bMwdq1a7Fnzx7UqlUL3bt3x+zZs7F3794H2tf58+ejf//+WLZsGX788Uds3boVjo6OqFevHp544gn06dMHAwcOVLy+goICHDx40Gj6tWvXDO7OtsYd5kREZF2SqIjbRImIiIio2uE1jkRERESkCIMjERERESnC4EhEREREijA4EhEREZEiDI5EREREpAiDIxEREREpwuBIRERERIowOBIRERGRIgyORERERKQIgyMRERERKcLgSERERESKMDgSERERkSIMjkRERESkyP8BOeXCigypGdAAAAAASUVORK5CYII=\n",
      "text/plain": [
       "<Figure size 500x500 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "scatter_plot(datasets, use_rep=\"X_linearcorrection\", plot_before=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9253daeb",
   "metadata": {},
   "source": [
    "As we can see, instead of collapsing every source point into one single position in the output representation, points are now separated after integration in a similar way than before integration."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39d57cce",
   "metadata": {},
   "source": [
    "## Graph embedding merging\n",
    "\n",
    "Graph embedding is a non-linear embedding method which embeds a joint graph of datasets in a low dimensional space, similarly to what is done within the [CONOS](https://github.com/kharchenkolab/conos) pipeline. It combines both edges of the $k$-nearest neighbors graph of each dataset, and matching edges found between datasets to estimate the joint graph. It is then weighted and embedded using a solve (by default, the UMAP solver). \n",
    "\n",
    "This embedding is great in practice as it does not require a reference to be set. The main drawback is that the output feature space is \"inexpressive\", which is a major obstacle for interpretability. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 30,
   "id": "3fbdc0b5",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CUSTOM_MODEL > Transmorph model is initializing.\n",
      "CUSTOM_MODEL > Ready to start the integration of 2 datasets, 19 total samples.\n",
      "CUSTOM_MODEL > Running layer LAYER_INPUT#31.\n",
      "CUSTOM_MODEL > Running layer LAYER_MATCHING#32.\n",
      "LAYER_MATCHING#32 > Calling matching MATCHING_LABELS.\n",
      "CUSTOM_MODEL > Running layer LAYER_MERGING#33.\n",
      "LAYER_MERGING#33 > Running merging MERGING_GRAPH_EMBEDDING...\n",
      "CUSTOM_MODEL > Running layer LAYER_OUTPUT#34.\n",
      "CUSTOM_MODEL > Terminated. Total embedding shape: (19, 2)\n",
      "CUSTOM_MODEL > Results have been written in AnnData.obsm['X_graphembedding_umap'].\n"
     ]
    }
   ],
   "source": [
    "from transmorph.engine.merging import GraphEmbedding\n",
    "\n",
    "model_barycenter = create_model_merging(GraphEmbedding(n_neighbors=3))\n",
    "model_barycenter.fit(datasets, output_representation=\"X_graphembedding\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 63,
   "id": "b99fa113",
   "metadata": {
    "scrolled": false
   },
   "outputs": [
    {
     "data": {
      "image/png": "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QUGB7rvvvgr3XbRokUaOHKmrrrpKd999tySpdevW6tatmxISEpSdna2+fft67JOdna3WrVvr17/+dbVrz8jI0MKFCzV8+HDde++9ysvL06xZs7R161Zt2LCh0gtEW7du1ZVXXunxPZOkq666SllZWdqxY4c6duxY4f5eMV5KSkpyvyzLMhERER7bzn4lJCSYoKAgExAQYP74xz96e4oyHA6HkWQcDofPxwAA1L7a+v1cVFRktm/fboqKimqlrk8//dRIqvL16aef1sr5qvLuu++awMBAExgYaH7961+b8ePHm3feececOnWqTN/jx4+X2ZaWlmaSk5M9trVq1cpIMhs3bnRve+edd4wkExYWZnbv3u3e/sILLxhJZu3ate5tQ4cONZLM2LFj3ducTqe5+eabTXBwsDlw4IB7uySTmZnp/vquu+4yTZs2NQcPHvSo6Y477jBRUVHlfoazhYeHm6FDh5bZ/vDDD5uQkBBz5MgR97b9+/ebRo0aeZzf29rXr19vJJns7GyP86xevbrc7eXVOWLEiDLb33rrLSPJrF69usJ9vf2Z9noIcteuXe6XZVk6evSox7azX3v27FFAQID69++vJ598smYJEQCAeqp3797atGmTbr31Vn3xxReaNm2a0tLS1Lx5c61YscKjb1hYmPvPDodDBw8eVGpqqnJzc+VwODz6tm/f3uOqUNeuXSVJPXv2VMuWLctsz83NLVPbPffc4/5z6RWtU6dOac2aNeV+FmOMli1bpvT0dBljdPDgQfcrLS1NDofD57sEhwwZopMnT2rp0qXuba+++qqKi4t15513Vrv2JUuWKCoqSr179/aoMyUlRY0bN9batWsrraeoqEghISFltoeGhrrba8rrIci8vDxJrv8AycnJGjBggJ555ply+wYHBysmJoY7IAEAF7wuXbpo+fLlOnXqlL744gu9/vrreu655zRgwAB9/vnnat++vSRpw4YNyszM1KZNm3T8+HGPYzgcDkVFRbm/PjtkSXK3nfv85dLt5857CggIUHJysse20qHbXbt2lfs5Dhw4oCNHjigrK0tZWVnl9vH1xoJ27dqpS5cuys7Odq+ykJ2drW7duqlNmzbVrj0nJ0cOh6PMPDtv6wwLCyt3nteJEyfc7TXldUJq1aqV+89Dhw7Vtdde67ENAABULDg4WF26dFGXLl3Utm1bDR8+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atiwYf4uo0FLSkrS2LFjdeWVV+rKK6/Ua6+9pieeeMLfZQFAg0IAA+Dhtttu02233eb+evny5X6sBgAaJuaAocH69NNPNXjwYLVs2VIhISG6+OKLlZaWprfffrvc/tu3b1dmZqauueYaNW/eXMHBwbrkkkt0ww036LXXXivTf9iwYUpKSpIk7d69u8yctLP7WZalhQsXlnvehQsXyrKsMlf2zt5+6NAh3XfffWrdurVCQkLUo0cPj77vv/+++vXrp6ZNmyo4OFixsbHq27evNm3a5P03DABgG66AoUGaOXOm7r//fjmdTl1++eXq2rWrfvzxR61bt07vvvuuJk+erIkTJ3rsM336dP39739Xu3bt1LFjR0VHR+s///mP1q5dq/fff1+bN2/W9OnT3f27d++uo0ePatmyZQoPD9eAAQPOy2c5ePCgOnfurCNHjujaa69VSkqKgoOD3e3/7//9Pz377LMKCAhQ586dde211+o///mP/vWvf2nlypWaN2+ehg8ffl5qAwD4yAD1QKtWrYwks2DBgir7rl692liWZZo0aWI+/PBDj7Yvv/zStGjRwkgy69at82hbt26d2blzZ5njffPNN+59tmzZ4tGWl5dnJJlWrVpVWM/QoUMrrX3BggVGkhk6dGi52yWZXr16GYfDUWbfrKwsI8m0adPGfPHFFx5tH374oYmIiDDBwcFmx44dFdZXlczMTCPJ3HXXXT4fAwDgiSFI1CvDhw8vdwmKs4fkMjMzZYzR3/72N1133XUe+3fs2NF9Fev555/3aEtNTVVycnKZc1522WV67LHHJElLly6t5U9UtaCgIGVlZSkyMtJju9Pp1KRJkyRJr7zyijp16uTRft111+mxxx7TqVOn9MILL9hVLgDACwxBol6paBmKdu3aSXIN1/3f//2fwsLClJ6eXu4xSsPaxo0by7QdPXpUq1at0tatW3Xw4EGdOnVKkrRv3z5J0rffflsbH6NarrjiinKD4datW7V37161bt1aKSkp5e5b2WcFAPgPAQz1SlXLUOTl5ckYo6KiIoWEhFR6rAMHDnh8vXLlSg0fPlw//fRThfsUFBRUq97akJiYWO723NxcSdLOnTs9Jv2X59zPCgDwLwIYGhSn0ylJaty4sfr37+/1fj/88INuv/12FRUVafz48Ro8eLASExPVuHFjBQQE6N1331VaWpqMMeet5oqEhYVVul98fLzS0tIqPUaTJk18Kw4AcF4QwNCgJCQkSJIsy9KLL76ogADvpjmuXLlSRUVF6tu3r55++uky7Tk5OT7XVHrHYmFhYbntu3fv9um4pZ/1kksuqXCJCwBA3cQkfDQozZo1U6dOnVRYWKjVq1d7vd+hQ4ckSa1atSrTZozR4sWLy92vNFwVFxdXeOzmzZtLkr7++utyj71q1Sqv6zxbly5d1KRJE23fvl3btm3z6RgAAP8ggKHBmTp1qiTXHZMrV64s026M0ZYtW/Tuu++6t/3yl7+U5LrLsXTCvSSVlJRo4sSJFU5ij4mJUXBwsH788Ud3iDvXDTfcIElatGiRtm/f7t5++vRp/fnPf9bHH39czU/oEhQU5L7js2/fvvroo4/K9CkpKdEHH3ygzZs3+3QOAMD5wRAkGpz09HTNnDlTDzzwgG699Va1adNGl112maKionTgwAF98cUX2r9/v/785z+rT58+7n1SUlL06aefqm3btkpNTVV4eLi2bNmivXv36s9//nO5Q5NBQUG69dZbtXTpUl1++eXq3r27LrroIknS/PnzJbnu3Lztttv0r3/9S507d1b37t0VFhamzz77TAUFBRo3bpxmzpzp02e955579J///EfPPPOMrr32WnXo0EFt2rRRWFiYfvzxR33++ec6cuSI5s6dq27dunl1zH379qlv377ur/fs2SNJWrFihccx5syZoyuvvNKnugHgQkcAQ4N07733qmfPnnr++efdK9kHBAQoPj5eV1xxhW6++WaPSfqNGjXSunXr9NRTT2nZsmV6//33FRkZqauvvlrLli1TYWFhuQFMkl544QVdcsklWrVqlZYuXarTp09LOhPAJOnVV1/V1KlTtXjxYq1bt06/+MUv1KtXL02ZMkXr16+v0WedNm2afvvb32rOnDn66KOPtHr1agUHB6tp06bq0aOHbrnlFvXr18/r4508eVJbtmwps/3AgQMed1P6445QAGgoLHM+busCAABAhZgDBgAAYDMCGAAAgM0IYAAAADYjgAEAANiMAAYAAGAzAhgAAIDNCGAAAAA2I4ABAADYjAAGAABgMwIYAACAzQhgAAAANiOAAQAA2IwABgAAYLP/D/OOxAZs8K72AAAAAElFTkSuQmCC\n",
      "text/plain": [
       "<Figure size 500x500 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "scatter_plot(datasets, use_rep=\"X_graphembedding_umap\", plot_before=False)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c253dfe",
   "metadata": {},
   "source": [
    "## Implementing a custom merging\n",
    "\n",
    "Like for transformations and matchings, you can define custom mergings to be used within **transmorph** pipelines. To illustrate it, let us implement a toy merging called \"jittered barycenter\" which works similarly to *Barycenter* merging, but which performs a small perturbation of the output to avoid stacking points with identical matches on top of one another. To do so, we simply generate for each point a sampling of a multivariate normal random variable around its \"exact\" position.\n",
    "\n",
    "Each merging must inherit from the *Merging* class. In this case, we also want our merging to be able to handle a reference dataset, so we also make it inherit the *UsesReference* trait. We then just need to fill the *transform* method which returns a list describing the new embedding of each dataset."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 73,
   "id": "ce21ddc1",
   "metadata": {},
   "outputs": [],
   "source": [
    "import anndata as ad\n",
    "import numpy as np\n",
    "\n",
    "from scipy.stats import norm\n",
    "from typing import List\n",
    "\n",
    "from transmorph.engine.merging import Merging\n",
    "from transmorph.engine.traits.usesreference import UsesReference\n",
    "# As we want our merging to work with a reference, we\n",
    "# must make it inherit the UsesReference trait.\n",
    "\n",
    "\n",
    "# JitteredBarycenter is a Merging which must use a reference dataset\n",
    "class JitteredBarycenter(Merging, UsesReference):\n",
    "\n",
    "    def __init__(self, std: float = 0.05):\n",
    "        # We must initialize both superclasses separately\n",
    "        # preserves_space signals whether the input space for each\n",
    "        # dataset is the same as the output space\n",
    "        Merging.__init__(\n",
    "            self,\n",
    "            preserves_space=False, \n",
    "            str_identifier=\"PartialBarycenter\",\n",
    "            matching_mode=\"normalized\",\n",
    "        )\n",
    "        UsesReference.__init__(self)\n",
    "        # JitteredBarycenter parameter\n",
    "        self.std = std\n",
    "\n",
    "    def transform(\n",
    "        self, datasets: List[ad.AnnData], embeddings: List[np.ndarray]\n",
    "    ) -> List[np.ndarray]:\n",
    "        # Inheriting the UsesReference trait allows us to\n",
    "        # use the reference_index attribute, which contains\n",
    "        # the reference index.\n",
    "        k_ref = self.reference_index\n",
    "        assert k_ref is not None, \"Reference dataset must be set.\"\n",
    "        X_ref = embeddings[k_ref] # We get the reference embedding\n",
    "        result = []\n",
    "        for k, X in enumerate(embeddings):\n",
    "            if X is X_ref: # No need to change the reference\n",
    "                result.append(X_ref)\n",
    "                continue\n",
    "            # Every Merging contains a get_matching(i, j) method\n",
    "            # which accesses the matching matrix between datasets\n",
    "            # i and j as a CSR matrix\n",
    "            T = self.get_matching(k, k_ref)\n",
    "            result.append(norm.rvs(loc=T @ X_ref, scale=self.std))\n",
    "            \n",
    "        # We return the list of new embeddings\n",
    "        return result"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 77,
   "id": "5b0fa134",
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "CUSTOM_MODEL > Transmorph model is initializing.\n",
      "CUSTOM_MODEL > Ready to start the integration of 2 datasets, 19 total samples.\n",
      "CUSTOM_MODEL > Running layer LAYER_INPUT#71.\n",
      "CUSTOM_MODEL > Running layer LAYER_MATCHING#72.\n",
      "LAYER_MATCHING#72 > Calling matching MATCHING_LABELS.\n",
      "CUSTOM_MODEL > Running layer LAYER_MERGING#73.\n",
      "LAYER_MERGING#73 > Running merging MERGING_PartialBarycenter...\n",
      "CUSTOM_MODEL > Running layer LAYER_OUTPUT#74.\n",
      "CUSTOM_MODEL > Terminated. Total embedding shape: (19, 2)\n",
      "CUSTOM_MODEL > Results have been written in AnnData.obsm['X_jitteredbarycenter'].\n"
     ]
    }
   ],
   "source": [
    "model_barycenter = create_model_merging(JitteredBarycenter(std=0.2))\n",
    "model_barycenter.fit(datasets, reference=datasets[\"ref\"], output_representation=\"X_jitteredbarycenter\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 78,
   "id": "236a6bc9",
   "metadata": {},
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAo4AAAGzCAYAAAChApYOAAAAOXRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjYuMCwgaHR0cHM6Ly9tYXRwbG90bGliLm9yZy89olMNAAAACXBIWXMAAA9hAAAPYQGoP6dpAABcW0lEQVR4nO3deVxUVf8H8M9lJ5bBhQEXRMDcCFNxodQwUcgU98zUVFziSTPbNLUUTcvUUimTxB6xDLVcwxJcUntU1DSXcksUtExFERlQAYU5vz/mx8Q4A1yHgRng83695jXOuefe+71XGL+ec885khBCgIiIiIioDFbmDoCIiIiIqgYmjkREREQkCxNHIiIiIpKFiSMRERERycLEkYiIiIhkYeJIRERERLIwcSQiIiIiWZg4EhEREZEsNuYOoDRqtRpXr16Fi4sLJEkydzhERPT/hBDIyclB/fr1YWXFNgiimsKiE8erV6/Cy8vL3GEQEVEJ/v77bzRs2NDcYRBRJbHoxNHFxQWA5ovJ1dXVzNEQEVGR7OxseHl5ab+niahmsOjEsah72tXVlYkjEZEF4mNERDULH0whIiIiIlmYOBIRERGRLEwciYiIiEgWJo5EREREJAsTRyIiIiKShYkjEREREcnCxJGIiIiIZGHiSERERESyMHEkIiIiIlkseuUYo6SkADk5/3728gLc3YHMTODSJU2Ziwvw+ONmCa/K4H0kC/Lwj+PD+KMoD+8jEZVX9UocU1KApk11y5YuBSZMALZtA15++d/y8+f5DVkS3keyIIZ+HA3hj2LpeB+JyBSqV+IIAKGhwGuvAQ0aaD57eWnen38e+O034OxZYPjw0v/bTbyPZDHk/ojxR7F0vI9EZArVK3F8/HFg+3bD22rX1rycnICgIM07Gcb7SNUB+2WJiEyueiWOhYXA3buaZMba2nCdZs2AgwcrN66qhveRqjr2yxIRVYjqNar65ElAodC8k/F4H6mqY78sEVGFqF6JoxzHjgGSpHkn4/E+EhER1Tg1L3EkIiIiIqNUr2ccizzcClarFuDjA+TlaUYDkzy8j0RERFRM9Uoc69XTvI8bp1s+bBjw7bfAlSuaKWQAzYhKMoz3kSyI3B8x/iiWjveRiEyh+iWOV68C167plteqpXlv2FAzByGn4Sgd7yNZkMcf1wx+5sw65cP7SESmUL0SR0CT9BS1mD3MwQFo27Zy46mqeB/JgjCZMQ3eRyIqLw6OIaLqh/2yREQVovq1OBIRsV+WiKhCMHEkouqJSSERkcmxq5qIiIiIZGGLIxFZvpQUdjsTEVkAJo5EZNlSUoCmTcuud/48k0ciogrGrmoislwpKcCvv8qrW1qLJBERmQRbHInIMsltaSQiokrDFkciskxsQSQisjhMHImIiIhIFiaORERERCQLE0ciIiIikoWJIxERERHJwsSRiKoHFxdzR0BEVO0xcSSiqu3bbzn5NxFRJWHiSESWSW4LYocOTBqJiCoJJwAnIsv0+OOalkSuUU1EZDGYOBKRZUpJqZyksbLOQ0RUDTBxJCLLI3e5wfI+21hZ5yEiqib4jCMRWR65yw2Wd1nCyjoPEVE1wcSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSxMHImIiIhIFiaORERERCQLE0cisjxylxuUW8/c5yEiqiY4ATgRWZ7KWm6QyxoSET0SJo5EZJkqK1ljUkhEJBsTRyKybFxLmojIYjBxJCLLxbWkiYgsCgfHEJHl4lrSREQWhYkjEREREcnCxJGIiIiIZGHiSERERESyMHEkIiIiIlmYOBIRERGRLEwciYiIiEgWJo5EZLm4ljQRkUXhBOBEZLm4ljQRkUVh4khElo1JIRGRxWBXNRERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSwcVW0OKSn604t4eQHu7kBmJnDpEqcYkYP30SQM3cbiLOEWVoUYiYhqAiaOle36dWDUKCA5Wbd86VJgwgRg2zbg5Zc1ZefP81/DkvA+mkRKCtC0adn1zHkLq0KMREQ1BRPHyubpCWzZAvz9t265l5fm/fnngW+/BYYPL72JpabjfTQJubfGnLewKsRIRFRTMHGsbIWFgL098OSTgLW1/vbatYEWLSo/rqqG95GIiKjScXBMZTt5ElAoNO8lcXICgoI072QY7yMREVGlY4ujJWrWDDh40NxRVH28j0RERCbFFkciIiIikoWJoyU6dgyQJM07GY/3kYiIyKSYOBIRERGRLHzGsbIFBGgGdOTm6raE1aoF+PgAeXnA2bPmi6+q4H00CRcX09arCFUhRiKimoKJY2WztQU2bQJmz9YtHzZMM+/glSuauQcB/ktYGt5Hk3j8cc3E2Za8KktViJGIqKaQhBDC3EGUJDs7GwqFAiqVCq6uruYOx3SuXdO8iiveUnbmDP8llIP3kchsqu33MxGViokjERE9Mn4/E9VMHBxDRERERLIwcSQiIiIiWZg4EhEREZEsTByJiIiISBYmjkREREQkCxNHIiIiIpKFiSMRERERycLEkYiIiIhkYeJIRERERLIwcSQiIiIiWZg4EhEREZEsTByJiIiISBYmjkREREQkCxNHIiIiIpKFiSMRERERycLEkYiIiIhkYeJIRERERLIwcSQiIiIiWZg4EhEREZEsTByJiIiISBYmjkREREQkCxNHIiIiIpKFiSMRERERycLEkYiIiIhkYeJIRERERLIwcSQiIiIiWZg4EhEREZEsTByJiIiISBYmjkREREQkCxNHIiIiIpKFiSMRERERycLEkYiIiIhkYeJIRERERLIwcSQiIiIiWZg4EhEREZEsTByJiIiISBYmjkREREQkCxNHIiIiIpKFiSMRERERycLEkYiIiIhksTF3AERERAAghEBhYSEKCgrMHQpRjWFjYwNra2tIkiSvfgXHQ0REVCohBLKysnDz5k0UFhaaOxyiGsfa2hpKpRIKhaLMBJKJIxERmdX169eRlZUFV1dXuLq6wsbGRnbrBxEZTwiBgoICZGdn49q1a8jNzUW9evVK3YeJIxERmU1hYSFUKhXc3d1Rt25dc4dDVCO5uLjA3t4eGRkZUCqVsLa2LrEuB8cQEZHZPHjwAEIIODk5mTsUohrNyckJQgg8ePCg1HpscTSHlBQgJ0e3zMsLcHcHMjOBS5cAFxfg8cfNEh6AqhEjEVUb7JomMi+5v4Nscaxs168Do0YBgYG6r++/12zftk3zuWlTTfLGGImIiMhCsMWxsnl6Alu2AH//rVvu5aV5f/554NtvgeHD9Vv8KktViJGIiIgqHVscK1thIWBvDzz5JNC27b8vd3fN9tq1gRYtGCMREVEFWbBgAZo3bw61Wg0AuHTpEiRJwieffGLS86SkpCA0NFQ7zc2WLVtMevyyTJ06FR07djTpMZk4VraTJwGFQvNeEicnIChI824OVSFGIqIqYNWqVZAkSftycHBA/fr1ERYWhs8++ww55ei1SU5OxqxZs5CVlWW6gMth2bJlWLVqlbnDKFN2djbmz5+Pd999F1ZWFZsGjRw5En/88Qc+/PBDrF69Gu3atavQ8z3sjTfewMmTJ5GQkGCyYzJxtETNmgEHD2reLVVViJGIyEJ88MEHWL16NWJiYjBx4kQAmn/UAwIC8Pvvvxt1zOTkZMyePZuJ4yNauXIlCgoK8NJLL1XoeXJzc3Hw4EGMGTMGr732GoYPH46GDRtW6Dkf5unpib59+5q0JZXPOBIREVWwnj176rQ2TZs2Dbt370bv3r3Rp08fnD17Fo6OjmaMsGq4e/duuaduiouLQ58+feDg4GCiqAy7efMmAMDNzc1kxzTm+gcPHowXXngBqamp8PX1LXcMbHG0RMeOAZKkebdUVSFGIqrZtm0DZs4Eli0DLHD9627dumHGjBm4fPkyvv32W23577//jlGjRsHX1xcODg7w9PTE6NGjcevWLW2dWbNmYfLkyQAAHx8fbVf4pUuXAGiSo27dukGpVMLe3h4tW7ZETEyMXgxHjx5FWFgY6tatC0dHR/j4+GD06NE6ddRqNZYsWQJ/f384ODjAw8MDkZGRuH37trZO48aNcfr0afzyyy/aWLp27Vrq9a9btw6BgYFwcXGBq6srAgICEB0drd1e1M3/yy+/YPz48VAqlTotdomJiQgODtbu3759e6xZs6bUc6alpeH3339H9+7dS6yzePFieHt7w9HREcHBwTh16pRenXPnzmHQoEGoXbs2HBwc0K5dO53u4FmzZsHb2xsAMHnyZEiShMaNG2u3Hz9+HD179oSrqyucnZ0REhKCQ4cO6ZxDzvV36dIFTk5OcHFxQa9evXD69Gm9WIuu9Ycffij13sjFFkciIqpezp4F3noLSErSfJYkICYGWLMGCAgwb2wPefnllzF9+nTs2LED48aNAwDs3LkTqampiIiIgKenJ06fPo3Y2FicPn0ahw4dgiRJGDBgAM6fP4+1a9di8eLF2lV33P9/EGNMTAz8/f3Rp08f2NjYYOvWrRg/fjzUajUmTJgAALhx4wZCQ0Ph7u6OqVOnws3NDZcuXcKmTZt0YoyMjMSqVasQERGB119/HWlpaVi6dCmOHz+OAwcOwNbWFkuWLMHEiRPh7OyM9957DwDg4eFR4nXv3LkTL730EkJCQjB//nwAwNmzZ3HgwAFMmjRJp+748ePh7u6OmTNn4u7duwA0SdXo0aPh7++PadOmwc3NDcePH0dSUhKGDh1a4nmTk5MBAG3btjW4/ZtvvkFOTg4mTJiAvLw8REdHo1u3bvjjjz+013P69Gl06tQJDRo0wNSpU+Hk5ITvv/8e/fr1w8aNG9G/f38MGDAAbm5uePPNN/HSSy/h+eefh7Ozs3b/Ll26wNXVFVOmTIGtrS2WL1+Orl274pdfftEbzGLo+levXo2RI0ciLCwM8+fPx7179xATE4POnTvj+PHjOkmqQqGAn58fDhw4gDfffLPEeyObsGAqlUoAECqVytyhmM79+0KcPCnEoUNC/Pbbv6/UVM323Fwhvv1WCEBTzhiJyAKZ6vs5NzdXnDlzRuTm5pomsJUrhbCxEcLXV4jNm4VQq4U4elSI554T4to105zjEcTFxQkA4siRIyXWUSgUok2bNtrP9+7d06uzdu1aAUD873//05YtXLhQABBpaWl69Q0dIywsTPj6+mo/b968uczY9u3bJwCI+Ph4nfKkpCS9cn9/fxEcHFzisYqbNGmScHV1FQUFBSXWKbp3nTt31qmXlZUlXFxcRMeOHfV+btRqdannff/99wUAkZOTo1OelpYmAAhHR0dx5coVbfnhw4cFAPHmm29qy0JCQkRAQIDIy8vTOe/TTz8tHn/8cb1jLly4UOdc/fr1E3Z2duLixYvasqtXrwoXFxfxzDPPlHn9OTk5ws3NTYwbN07nuNevXxcKhUKvXAghQkNDRYsWLUq9N3J/F9lVXdlsbYFNmzQjkotPrj1jhmb7lSua+REBzcosjJGISL6dO4FnnwVOnwb69dO0NgYGAomJmtkiinWvWgpnZ2ed0dXFn3XMy8tDRkYGgoKCAADHZD4eVPwYKpUKGRkZCA4ORmpqKlQqFYB/n7378ccfS1xmbv369VAoFOjRowcyMjK0r8DAQDg7O2PPnj2PdK1F3NzccPfuXezcubPMuuPGjdNZO3nnzp3IycnB1KlT9Z5TLGv1k1u3bsHGxkbb+vewfv36oUGDBtrPHTp0QMeOHbFt2zYAQGZmJnbv3o3BgwcjJydHez9u3bqFsLAwpKSk4J9//inx/IWFhdixYwf69eun87xhvXr1MHToUOzfvx/Z2dllXn9WVhZeeuklnb8Ta2trdOzY0eDfSa1atZCRkVHqvZGLXdXmEBkJ9OmjW1arlua9YUPgt9/Mv5xfVYiRiOhhpT3jtmgR8NlnQHp65cUjw507d6BUKrWfMzMzMXv2bKxbtw43btzQqVuU9JXlwIEDiIqKwsGDB3Hv3j29YygUCgQHB2PgwIGYPXs2Fi9ejK5du6Jfv34YOnQo7O3tAWjmIVSpVDrxFfdwfHKNHz8e33//PXr27IkGDRogNDQUgwcPxnPPPadX18fHR+fzxYsXAQBPPPGEUecuzeMG/k1r2rQpvv//ldMuXLgAIQRmzJiBGUWNKQ+5ceOGTvJZ3M2bN3Hv3j00MzAjSYsWLaBWq/H333/D399fW/7w9af8/4pt3bp1M3gOV1dXvTIhhMmW9WTiaA716mlehjg4aCbbNreqECMRURV35coVqFQqNGnSRFs2ePBgJCcnY/LkyWjdujWcnZ2hVqvx3HPPaSesLs3FixcREhKC5s2bY9GiRfDy8oKdnR22bduGxYsXa48hSRI2bNiAQ4cOYevWrdi+fTtGjx6NTz/9FIcOHdKeV6lUIj4+3uC5ip6pfFRKpRInTpzA9u3bkZiYiMTERMTFxWHEiBH4+uuvdeqacrR5nTp1UFBQgJycHLgY0WNWdO/eeecdhIWFGaxT/O/SFB6+/qIYVq9eDU9PT736Njb6qd3t27e1z8GWFxNHIiKqPl59FVCpgNWrgWLdewCAzEzzxFSK1atXA4A2Cbl9+zZ+/vlnzJ49GzNnztTWK2plKq6kFqStW7ciPz8fCQkJaNSokba8pG7loKAgBAUF4cMPP8SaNWswbNgwrFu3DmPHjoWfnx927dqFTp06lZnAPWqLlp2dHcLDwxEeHg61Wo3x48dj+fLlmDFjRqnJl5+fHwDg1KlTj5ykNW/eHIBmdHWrVq30thu6z+fPn9cONinqXra1tS11ZHZJ3N3d8dhjj+HPP//U23bu3DlYWVnBq2h53xIUXb9SqZQdQ1paGp588slHjtcQPuNIRETVR7NmwNq1QPv2wL59/5a/+66mqzokxHyxPWT37t2YM2cOfHx8MGzYMADQPssmhNCpu2TJEr39i+bze3gCcEPHUKlUiIuL06l3+/ZtvfO0bt0aAJCfnw9A0/pZWFiIOXPm6J2/oKBA59xOTk6yJyMvPrUQAFhZWWkTuaJzlyQ0NBQuLi6YN28e8vLydLY9fD0Pe+qppwBopiEyZMuWLTrPKP766684fPgwevbsCUCTrHXt2hXLly/HtWvX9PYvmruxJNbW1ggNDcUPP/ygnToJANLT07FmzRp07tzZYFdzcWFhYXB1dcVHH31k8NnUh2NQqVS4ePEinn766VKPK5fsFseCggJ8/PHH+Oabb/D333+jXr16GDRoEKZNm4ZaRc++PSQiIgKrV69GgQXOn0VERNXQG28AHTsCkyYBzzyjeV77yy81A2XatgUGDzZLWImJiTh37hwKCgqQnp6O3bt3Y+fOnfD29kZCQoJ2kIerqyueeeYZLFiwAA8ePECDBg2wY8cOpKWl6R0zMDAQAPDee+9hyJAhsLW1RXh4OEJDQ7WteZGRkbhz5w5WrFgBpVKpk+x8/fXXWLZsGfr37w8/Pz/k5ORgxYoVcHV1xfPPPw8ACA4ORmRkJObNm4cTJ04gNDQUtra2SElJwfr16xEdHY1BgwZp44mJicHcuXPRpEkTKJXKEp/DGzt2LDIzM9GtWzc0bNgQly9fxueff47WrVujRYsWpd5LV1dXLF68GGPHjkX79u0xdOhQ1KpVCydPnsS9e/f0urqL8/X1xRNPPIFdu3bpzVcJaLqZO3fujFdffRX5+flYsmQJ6tSpgylTpmjrfPHFF+jcuTMCAgIwbtw4+Pr6Ij09HQcPHsSVK1dwsrTlegHMnTsXO3fuROfOnTF+/HjY2Nhg+fLlyM/Px4IFC0rdt+j6Y2Ji8PLLL6Nt27YYMmQI3N3d8ddff+Gnn35Cp06dsHTpUm39Xbt2QQiBvn37lnlsWUodc11MeHi4sLKyEpIkaV9WVlbCy8tLHDx40OA+o0aNElZWVnJPoadaTsdDRFQNWOx0PEUKC4X4+mvN9DxmVDSlStHLzs5OeHp6ih49eojo6GiRnZ2tt8+VK1dE//79hZubm1AoFOKFF14QV69eFQBEVFSUTt05c+aIBg0aCCsrK52peRISEkSrVq2Eg4ODaNy4sZg/f75YuXKlTp1jx46Jl156STRq1EjY29sLpVIpevfuLY4ePaoXU2xsrAgMDBSOjo7CxcVFBAQEiClTpoirV69q61y/fl306tVLuLi4CAClTs2zYcMGERoaKpRKpbCzsxONGjUSkZGR4lqxKZPKmsooISFBPP3008LR0VG4urqKDh06iLVr15Z4ziKLFi0Szs7OOlMWFZ8659NPPxVeXl7C3t5edOnSRZw8eVLvGBcvXhQjRowQnp6ewtbWVjRo0ED07t1bbNiwweAxH3bs2DERFhYmnJ2dxWOPPSaeffZZkZycrFOnrOvfs2ePCAsLEwqFQjg4OAg/Pz8xatQovb+/F198UXTu3LnM+yL3d1ESoox2XQBr1qzB8OHD4eTkhKlTp6JNmzZISUnBZ599hrS0NDg6OmLLli3o0aOHzn4RERH45ptvUFhYaFRSm52dDYVCAZVKVWbTLRERVR5TfT/n5eUhLS0NPj4+Fb4EHBGg6br19fXFggULMGbMGHOHU6GuX78OHx8frFu3rswWR7m/i7KecSxa9mbbtm1477338Pzzz2PSpEk4deoURowYgdzcXPTt2xdJRbP0ExEREVkghUKBKVOmYOHChbJGqVdlS5YsQUBAgOm6qSEzcTx+/Djat2+PLl266JQ7Ojpi1apVmD17NvLy8tC/f38kJiaaLDgiIiIiU3v33Xe1o5irs48//hi//vqrSY8p644VNeuWZMaMGfjkk0+Qn5+PAQMGMHkkIiIiqoZkJY6urq64XcYyTW+99Raio6ORn5+PgQMHapfnISIiIqLqQdZ0PC1atMDRo0fLXLJm4sSJsLKywsSJEzFw4MBSWymJiIiIqGqR1eL47LPPIjMzE7t27Sqz7oQJE7Bs2TLcv38f586dK3eARERERGQZZCWOPXv2hBBC1sSUAPCf//wHX375ZbkCIyIiIiLLIqurOigoCCkpKY+0DuW4cePQoUMH2csPEREREZFlk5U4SpKkXVT7UZhqQW0iIiIiMr/qPYEREREREZkME0ciIiIikoWJIxERERHJwsSRiIiogqxatQqSJGlfDg4OqF+/PsLCwvDZZ58hJyfH6GMnJydj1qxZFjMIddmyZVi1apW5w6AKxsSRiIiogn3wwQdYvXo1YmJiMHHiRADAG2+8gYCAAPz+++9GHTM5ORmzZ89m4kiVStaoaiIiIjJez5490a5dO+3nadOmYffu3ejduzf69OmDs2fPwtHR0YwRVg13796Fk5OTucOo0djiSERE1VdeHrB7t+bdwnTr1g0zZszA5cuX8e2332rLf//9d4waNQq+vr5wcHCAp6cnRo8ejVu3bmnrzJo1C5MnTwYA+Pj4aLvCL126BACIi4tDt27doFQqYW9vj5YtWyImJkYvhqNHjyIsLAx169aFo6MjfHx8MHr0aJ06arUaS5Ysgb+/PxwcHODh4YHIyEjcvn1bW6dx48Y4ffo0fvnlF20sXbt2LfX6161bh8DAQLi4uMDV1RUBAQGIjo7Wbi/q5v/ll18wfvx4KJVKNGzYULs9MTERwcHB2v3bt2+PNWvWlH3jqVzY4khERNWPEMCWLcCkScDffwNeXkB0NNCvH/AIi1lUtJdffhnTp0/Hjh07MG7cOADAzp07kZqaioiICHh6euL06dOIjY3F6dOncejQIUiShAEDBuD8+fNYu3YtFi9ejLp16wIA3N3dAQAxMTHw9/dHnz59YGNjg61bt2L8+PFQq9WYMGECAODGjRsIDQ2Fu7s7pk6dCjc3N1y6dAmbNm3SiTEyMhKrVq1CREQEXn/9daSlpWHp0qU4fvw4Dhw4AFtbWyxZsgQTJ06Es7Mz3nvvPQCAh4dHide9c+dOvPTSSwgJCcH8+fMBAGfPnsWBAwcwadIknbrjx4+Hu7s7Zs6cibt37wLQJJWjR4+Gv78/pk2bBjc3Nxw/fhxJSUkYOnRoef9aqDSiHC5cuCAmT54sOnXqJJo2bSomT56s3Xbo0CGxfPlykZWVZfTxVSqVACBUKlV5wiQiIhMz1fdzbm6uOHPmjMjNzTVRZEKIs2eFCA4WAhDCykr3PThYs72SxMXFCQDiyJEjJdZRKBSiTZs22s/37t3Tq7N27VoBQPzvf//Tli1cuFAAEGlpaXr1DR0jLCxM+Pr6aj9v3ry5zNj27dsnAIj4+Hid8qSkJL1yf39/ERwcXOKxips0aZJwdXUVBQUFJdYpunedO3fWqZeVlSVcXFxEx44d9X5u1Gq1rPOTPrm/i0Z3VX/99dd44okn8MknnyA5ORkXLlxARkaGdvu9e/fw6quvYvPmzeXJa4mIiB7N6NHA/v2aP6vVuu/792u2WxBnZ2ed0dXFn3XMy8tDRkYGgoKCAADHjh2Tdczix1CpVMjIyEBwcDBSU1OhUqkAAG5ubgCAH3/8EQ8ePDB4nPXr10OhUKBHjx7IyMjQvgIDA+Hs7Iw9e/Y80rUWcXNzw927d7Fz584y644bNw7W1tbazzt37kROTg6mTp0KBwcHnbqPsjQyGceoxPHQoUMYO3Ys7OzssGDBAhw+fBhCCJ06wcHBUCgU2Lp1q0kCJSIikiUnBygsNLytsFCz3YLcuXMHLi4u2s+ZmZmYNGkSPDw84OjoCHd3d/j4+ACANukry4EDB9C9e3c4OTnBzc0N7u7umD59us4xgoODMXDgQMyePRt169ZF3759ERcXh/z8fO1xUlJSoFKpoFQq4e7urvO6c+cObty4YdQ1jx8/Hk2bNkXPnj3RsGFDjB49GklJSQbrFl17kYsXLwIAnnjiCaPOTeVj1DOOCxYsgBACP/30Ezp37mywjpWVFVq3bo0zZ86UK0AiIqLq6sqVK1CpVGjSpIm2bPDgwUhOTsbkyZPRunVrODs7Q61W47nnnoO6qOW0FBcvXkRISAiaN2+ORYsWwcvLC3Z2dti2bRsWL16sPYYkSdiwYQMOHTqErVu3Yvv27Rg9ejQ+/fRTHDp0SHtepVKJ+Ph4g+cqeqbyUSmVSpw4cQLbt29HYmIiEhMTERcXhxEjRuDrr7/WqcvR5pbFqMTxwIED6NChQ4lJYxFPT0/ZzepEREQ1zerVqwEAYWFhAIDbt2/j559/xuzZszFz5kxtvZSUFL19S+qW3bp1K/Lz85GQkIBGjRppy0vqVg4KCkJQUBA+/PBDrFmzBsOGDcO6deswduxY+Pn5YdeuXejUqVOZCdyjdhPb2dkhPDwc4eHhUKvVGD9+PJYvX44ZM2boJNIP8/PzAwCcOnWq1HpUMYzqqs7KytL5YSxJbm4u7t+/b8wpiIiIjOPiAhR7Jk6HtbVmuwXYvXs35syZAx8fHwwbNgwAtM/yPfz415IlS/T2L5rP8OEJwA0dQ6VSIS4uTqfe7du39c7TunVrANB2Vw8ePBiFhYWYM2eO3vkLCgp0zu3k5CR7MvLiUwsBml7KVq1a6Zy7JKGhoXBxccG8efOQ99A0Sw9fD5meUS2OderUweXLl8usd+HCBXh6ehpzCiIiIuOsXAn85z/AL78AVlaagTFF7507A19+WekhJSYm4ty5cygoKEB6ejp2796NnTt3wtvbGwkJCdpBHq6urnjmmWewYMECPHjwAA0aNMCOHTuQlpamd8zAwEAAwHvvvYchQ4bA1tYW4eHhCA0N1bbmRUZG4s6dO1ixYgWUSiWuXbum3f/rr7/GsmXL0L9/f/j5+SEnJwcrVqyAq6srnn/+eQCa5yAjIyMxb948nDhxAqGhobC1tUVKSgrWr1+P6OhoDBo0SBtPTEwM5s6diyZNmkCpVKJbt24G78fYsWORmZmJbt26oWHDhrh8+TI+//xztG7dGi1atCj1Xrq6umLx4sUYO3Ys2rdvj6FDh6JWrVo4efIk7t27p9fVTSZmzJDt/v37CxsbG3Hq1CltmSRJIiIiQvt5//79QpIk8fLLLxtzCiEEp+MhIrJUFj0djxBCqNVCbN4shJeXZhqeRo00nyt5upaiKWWKXnZ2dsLT01P06NFDREdHi+zsbL19rly5Ivr37y/c3NyEQqEQL7zwgrh69aoAIKKionTqzpkzRzRo0EBYWVnpTM2TkJAgWrVqJRwcHETjxo3F/PnzxcqVK3XqHDt2TLz00kuiUaNGwt7eXiiVStG7d29x9OhRvZhiY2NFYGCgcHR0FC4uLiIgIEBMmTJFXL16VVvn+vXrolevXsLFxUUAKHVqng0bNojQ0FChVCqFnZ2daNSokYiMjBTXrl3Tu3clTReUkJAgnn76aeHo6ChcXV1Fhw4dxNq1a0s8J5VO7u+iJMSjt+v+/PPP6NGjB5o2bYp169ahdevWsLKywqhRo7By5UqcPXsW/fr1w4ULF3DgwAHtNAKPKjs7GwqFAiqVCq6urkYdg4iITM9U3895eXlIS0uDj4+P3tQqJpGXByQnA08/DVTE8YmqCbm/i0Y94xgSEoK33noL58+fR2BgIJo2bQpJkrB9+3a0atUKAQEBSElJweTJk41OGomIiMrNwQHo1o1JI5GJGD0B+CeffILly5fD09MTFy5cgBAC165dw6lTp1C7dm18/vnn+Pjjj00ZKxERERGZUbnWqh43bhzGjh2L48ePIzU1FWq1Gl5eXmjfvj1sbLgMNhEREVF1YlR2VzQK6ptvvoEkSWjbti3atm1r6tiIiIiIyIIY1VWdnJzM+RmJiIiIahijEseGDRuWOUEnEREREVUvRiWOvXv3xr59+3D37l1Tx0NEREREFsqoxDEqKgoKhQIDBgyQtYIMEREREVV9Rg2Oefvtt+Hv748ff/wRzZo1Q5s2bdC4cWODC6BLkoT//ve/5Q6UiIiIiMzLqJVjrKysIEmSrMXEJUlCYWGhUcFx5RgiIstUZVaOISJZ5P4uGtXiGBcXZ3RgRERERFQ1GZU4jhw50tRxEBERET2SlJQUTJgwAYcPH0Z2djY2b96Mfv36mTusas3oJQeJiIiodKtWrYIkSdqXg4MD6tevj7CwMHz22WfIyckx+tjJycmYNWsWsrKyTBdwOSxbtgyrVq2q1HOOHDkSf/zxBz788EOsXr0a7dq1q9Tz10RcF5CIiKiCffDBB/Dx8cGDBw9w/fp17N27F2+88QYWLVqEhIQEtGrV6pGPmZycjNmzZ2PUqFFwc3MzfdCPaNmyZahbty5GjRpVKefLzc3FwYMH8d577+G1116rlHOSkYnj6NGjZdflqGoiIqrpevbsqdMaNm3aNOzevRu9e/dGnz59cPbsWYMzk9QkBQUFUKvVsLOzk1X/5s2bAGARSXONIowgSVKpLysrK2FlZaX9s7FUKpUAIFQqldHHICIi0zPV93Nubq44c+aMyM3NNVFkliUuLk4AEEeOHDG4/aOPPhIARGxsrLbs5MmTYuTIkcLHx0fY29sLDw8PERERITIyMrR1oqKiBAC9V1pamhBCiJUrV4pnn31WuLu7Czs7O9GiRQuxbNkyvfMfOXJEhIaGijp16ggHBwfRuHFjERERoVOnsLBQLF68WLRs2VLY29sLpVIpXnnlFZGZmamt4+3trRdLcHBwifclLS1NABALFy4UixcvFr6+vsLKykocP35cCCHE2bNnxcCBA0WtWrWEvb29CAwMFD/88EOp1+/t7V3i+ahscn8XTTqqWq1W4/Lly9i2bRuOHj2KN954A08++aQxpyAiIiq3vDwgORl4+mnAEmf7efnllzF9+nTs2LED48aNAwDs3LkTqampiIiIgKenJ06fPo3Y2FicPn0ahw4dgiRJGDBgAM6fP4+1a9di8eLFqFu3LgDA3d0dABATEwN/f3/06dMHNjY22Lp1K8aPHw+1Wo0JEyYAAG7cuIHQ0FC4u7tj6tSpcHNzw6VLl7Bp0yadGCMjI7Fq1SpERETg9ddfR1paGpYuXYrjx4/jwIEDsLW1xZIlSzBx4kQ4OzvjvffeAwB4eHiUef1xcXHIy8vDK6+8Ant7e9SuXRunT59Gp06d0KBBA0ydOhVOTk74/vvv0a9fP2zcuBH9+/fHgAED4ObmhjfffBMvvfQSnn/+eTg7O5vs74VKUVGZ6+TJk4Wbm5tITU01+hhscSQiskyW3uKoVguxaZMQXl5CAJr3TZs05ZWprBZHIYRQKBSiTZs22s/37t3Tq7N27VoBQPzvf//Tli1cuFCnlbE4Q8cICwsTvr6+2s+bN28uM7Z9+/YJACI+Pl6nPCkpSa/c39+/1FbG4opaHF1dXcWNGzd0toWEhIiAgACRl5enLVOr1eLpp58Wjz/+uN4xFi5cKOucVDq5v4sVNqr6o48+gouLC2bOnFlRpyAiItJz7hzw7LPAgAHAP/9oyv75R/P52Wc12y2Js7Ozzujq4s865uXlISMjA0FBQQCAY8eOyTpm8WOoVCpkZGQgODgYqampUKlUAP59NvDHH3/EgwcPDB5n/fr1UCgU6NGjBzIyMrSvwMBAODs7Y8+ePY90rQ8bOHCgtpUUADIzM7F7924MHjwYOTk52vPdunULYWFhSElJwT9Ff6lkFhWWONrY2KBt27bYtWtXRZ2CiIhIz+jRwP79mj+r1brv+/drtluSO3fuwMXFRfs5MzMTkyZNgoeHBxwdHeHu7g4fHx8A0CZ9ZTlw4AC6d+8OJycnuLm5wd3dHdOnT9c5RnBwMAYOHIjZs2ejbt266Nu3L+Li4pCfn689TkpKClQqFZRKJdzd3XVed+7cwY0bN8p17UXXVeTChQsQQmDGjBl654uKigKAcp+TyqdCp+PJzc3F7du3K/IUREREOnJygJJWui0s1Gy3FFeuXIFKpUKTJk20ZYMHD0ZycjImT56M1q1bw9nZGWq1Gs899xzURRlwKS5evIiQkBA0b94cixYtgpeXF+zs7LBt2zYsXrxYewxJkrBhwwYcOnQIW7duxfbt2zF69Gh8+umnOHTokPa8SqUS8fHxBs9VvLXQGA+PJC+K7Z133kFYWJjBfYrfK6p8FZY4nj17Fvv374eXl1dFnYKIiKhKW716NQBok6Tbt2/j559/xuzZs3Ue9UpJSdHbV5Ikg8fcunUr8vPzkZCQgEaNGmnLS+pWDgoKQlBQED788EOsWbMGw4YNw7p16zB27Fj4+flh165d6NSpU5nTBZUUz6Pw9fUFANja2qJ79+7lPh6ZnlGJ4zfffFPitpycHJw9exarV69GXl4ehg4danRwRERE1dXu3bsxZ84c+Pj4YNiwYQAAa2trAIAQQqfukiVL9PZ3cnICAL2VYwwdQ6VS6c2Icvv2bbi5uekkfK1btwYAbXf14MGDsWzZMsyZMwcfffSRzv4FBQW4c+eO9llJJyencq9io1Qq0bVrVyxfvhwTJ05EvXr1dLbfvHmz3K2cVD5GJY6jRo0q9X8WRT+sffv2xfvvv29cZEREREZwcQGsrQ13V1tba7ZXtsTERJw7dw4FBQVIT0/H7t27sXPnTnh7eyMhIQEO/z9XkKurK5555hksWLAADx48QIMGDbBjxw6kpaXpHTMwMBAA8N5772HIkCGwtbVFeHg4QkNDYWdnh/DwcERGRuLOnTtYsWIFlEolrl27pt3/66+/xrJly9C/f3/4+fkhJycHK1asgKurK55//nkAmucgIyMjMW/ePJw4cQKhoaGwtbVFSkoK1q9fj+joaAwaNEgbT0xMDObOnYsmTZpAqVSiW7duj3yvvvjiC3Tu3BkBAQEYN24cfH19kZ6ejoMHD+LKlSs4efLkIx+TTMeoxHHEiBElJo52dnZo0KABunfvjqeffrpcwRERET2qlSuB//wH+OUXwMpKMzCm6L1zZ+DLLys/pqJuZzs7O9SuXRsBAQFYsmQJIiIidAbGAMCaNWswceJEfPHFFxBCIDQ0FImJiahfv75Ovfbt22POnDn48ssvkZSUBLVajbS0NDRr1gwbNmzA+++/j3feeQeenp549dVX4e7urrPyW3BwMH799VesW7cO6enpUCgU6NChA+Lj43UGrXz55ZcIDAzE8uXLMX36dNjY2KBx48YYPnw4OnXqpHONly9fxoIFC5CTk4Pg4GCjEseWLVvi6NGjmD17NlatWoVbt25BqVSiTZs2nKnFAkji4fZwC5KdnQ2FQgGVSgVXV1dzh0NERP/PVN/PeXl5SEtLg4+Pj7bVzRSEAH74AXj9deDvv4FGjYDoaKBvX8AEj+IRVTtyfxcrdFQ1ERGROUgS0K8f8Nxzlr1yDFFVY9Q8jtbW1hgzZkyZ9caNGwcbG+amRERkHg4OQLduTBqJTMWoxFEIoTfiq7S6RERERFT1VdjKMQBw79492NraVuQpiIiIiKiSVFjimJWVhf379+vNwUREREREVZPsBxCLZnMvsmHDBuzdu9dg3YKCAly/fh2FhYWIjIwsV4BEREREZBlkJ46XLl3S/lmSJNy5cwd37twpsb6dnR369eunN9M8EREREVVNshPHolnrhRDw9fXFoEGDsHDhQoN17ezs4O7uzhHVRERERNWI7MzO29tb++eRI0eiS5cuOmVEREREVL0Z1ST48ELpRERERFT9Veh0PERERERUfZTrIcSjR49iw4YN+PPPP5GdnW1wsm9JkvDzzz+X5zREREREZAGMThzfeecdLF68WJssSpKkkzgWfZa4mjwREVGVJEkSoqKiMGvWLHOHQhbCqK7q9evXY9GiRWjQoAGWL1+O0NBQAMD27duxdOlSPPXUUxBCYOrUqdi9e7dJAyYiIqpK/vjjDwwaNAje3t5wcHBAgwYN0KNHD3z++efmDq3SffTRR9iyZYu5w5AlKysLr7zyCtzd3eHk5IRnn30Wx44dM3dYZmdU4hgbGwtra2v8/PPPGDdunHZ1mB49emD8+PE4cOAA3nvvPSxatAgKhcKkARMREVUVycnJaNeuHU6ePIlx48Zh6dKlGDt2LKysrBAdHW3u8CpdVUkc1Wo1evXqhTVr1uC1117DggULcOPGDXTt2hUpKSnmDs+sjOqqPn78ODp27IjHH3+8xDqzZ8/Gt99+i7lz52LDhg1GB0hERFRVffjhh1AoFDhy5Ajc3Nx0tt24ccM8QVGZNmzYgOTkZKxfvx6DBg0CAAwePBhNmzZFVFQU1qxZY+YIzceoFsecnBw0atRI+9nOzg4AdFaSsbKyQseOHXHgwIFyhkhERCRfSkoKjh07VuKrMluMLl68CH9/f72kEQCUSqXO57i4OHTr1g1KpRL29vZo2bIlYmJi9PZr3Lgxevfujb1796Jdu3ZwdHREQECAdhngTZs2ISAgAA4ODggMDMTx48d19h81ahScnZ2RmpqKsLAwODk5oX79+vjggw8MDnJ92D///IPRo0fDw8MD9vb28Pf3x8qVK8vcT5Ik3L17F19//TUkSYIkSRg1ahT27NkDSZKwefNmvX3WrFkDSZJw8ODBR45drVZjyZIl8Pf3h4ODAzw8PBAZGYnbt2+XGeuGDRvg4eGBAQMGaMvc3d0xePBg/PDDD8jPzy/zGNWVUS2O7u7uyMrK0n6uW7cuAM2yhE888YS2/O7du8jOzi5fhERERDKlpKSgadOmZdY7f/58qb1mpuLt7Y2DBw/i1KlTOv8+GhITEwN/f3/06dMHNjY22Lp1K8aPHw+1Wo0JEybo1L1w4QKGDh2KyMhIDB8+HJ988gnCw8Px5ZdfYvr06Rg/fjwAYN68eRg8eDD+/PNPWFn921ZUWFiI5557DkFBQViwYAGSkpIQFRWFgoICfPDBByXGmJ6ejqCgIEiShNdeew3u7u5ITEzEmDFjkJ2djTfeeKPEfVevXo2xY8eiQ4cOeOWVVwAAfn5+CAoKgpeXF+Lj49G/f3+dfeLj4+Hn54ennnrqkWOPjIzEqlWrEBERgddffx1paWlYunQpjh8/jgMHDsDW1rbEWI8fP462bdvq3DMA6NChA2JjY3H+/HkEBASUuH+1JozQqVMn0bJlS+3n9evXC0mSxLRp07Rl165dEy4uLqJFixbGnEIIIYRKpRIAhEqlMvoYRERkeqb6fs7NzRVnzpwRubm5Jonrt99+EwDKfP32228mOV9ZduzYIaytrYW1tbV46qmnxJQpU8T27dvF/fv39ereu3dPrywsLEz4+vrqlHl7ewsAIjk5WVu2fft2AUA4OjqKy5cva8uXL18uAIg9e/Zoy0aOHCkAiIkTJ2rL1Gq16NWrl7CzsxM3b97UlgMQUVFR2s9jxowR9erVExkZGToxDRkyRCgUCoPXUJyTk5MYOXKkXvm0adOEvb29yMrK0pbduHFD2NjY6Jxfbuz79u0TAER8fLzOeZKSkgyWG4pz9OjReuU//fSTACCSkpJK3b8qkvu7aFRXdUhICM6dO4dLly4BAHr27InatWtj/vz5eOGFF/D222+jY8eOuHv3LgYOHGhsTktERFSl9ejRAwcPHkSfPn1w8uRJLFiwAGFhYWjQoAESEhJ06jo6Omr/rFKpkJGRgeDgYKSmpkKlUunUbdmypU4rXMeOHQEA3bp103mUrKg8NTVVL7bXXntN++eiFsT79+9j165dBq9FCIGNGzciPDwcQghkZGRoX2FhYVCpVEaPOh4xYgTy8/N1xkR89913KCgowPDhwx859vXr10OhUKBHjx46cQYGBsLZ2Rl79uwpNZ7c3FzY29vrlTs4OGi311RGdVUPGTIEV69exd9//43GjRvDyckJcXFxGDJkCDZu3KitFxgYiGnTppksWCIioqqmffv22LRpE+7fv4+TJ09i8+bNWLx4MQYNGoQTJ06gZcuWAIADBw4gKioKBw8exL1793SOoVKpdGYpKZ4cAtBu8/LyMlj+8HN9VlZW8PX11Skr6uIvahR62M2bN5GVlYXY2FjExsYarGPsgJ/mzZujffv2iI+Px5gxYwBouqmDgoLQpEmTR449JSUFKpVK7zlSuXE6OjoafI4xLy9Pu72mMipxbNGiBVasWKFTFh4ejpSUFGzduhWZmZlo0aIFwsPDYW1tbZJAiYiIqjI7Ozu0b98e7du3R9OmTREREYH169cjKioKFy9eREhICJo3b45FixbBy8sLdnZ22LZtGxYvXgy1Wq1zrJL+bS2pXMgY9FKWohiGDx+OkSNHGqzTqlUro48/YsQITJo0CVeuXEF+fj4OHTqEpUuXGh2rUqlEfHy8we3u7u6l7l+vXj1cu3ZNr7yorH79+kbFVR2Ua8nBh9WvXx+RkZGmPCQREVG1065dOwD/JiJbt25Ffn4+EhISdFoTy+pSNZZarUZqaqrOQKLz588D0IzaNsTd3R0uLi4oLCxE9+7djTpvaavJDRkyBG+99RbWrl2L3Nxc2Nra4sUXXzQqdj8/P+zatQudOnUyqnWwdevW2LdvH9Rqtc4AmcOHD+Oxxx6TNQCrujLqGUciIiIq2549ewy29m3btg0A0KxZMwD/thQWr6tSqRAXF1dhsRVvzRNCYOnSpbC1tUVISIjB+tbW1hg4cCA2btyIU6dO6W2/efNmmed0cnLSmZWluLp166Jnz5749ttvER8fj+eee047a8ujxj548GAUFhZizpw5evsWFBSUGEORQYMGIT09HZs2bdKWZWRkYP369QgPDzf4/GNNUa4Wx3379uHzzz9HcnIybt68ieHDh+O///0vAGDnzp3Ys2cPXn/9dXh6epokWCIioqpk4sSJuHfvHvr374/mzZvj/v37SE5OxnfffYfGjRsjIiICABAaGgo7OzuEh4cjMjISd+7cwYoVK6BUKg12mZaXg4MDkpKSMHLkSHTs2BGJiYn46aefMH369FK7cT/++GPs2bMHHTt2xLhx49CyZUtkZmbi2LFj2LVrFzIzM0s9b2BgIHbt2oVFixahfv368PHx0Q7gATTd1UUTbhtK+uTGHhwcjMjISMybNw8nTpxAaGgobG1tkZKSgvXr1yM6Olp7HkMGDRqEoKAgRERE4MyZM6hbty6WLVuGwsJCzJ49u9RrrPaMHbY9Z84cYWVlJSRJ0r4iIiK02w8fPiysrKzEF198YewpOB0PEZGFstTpeM6fPy9rOp7z58+b5HxlSUxMFKNHjxbNmzcXzs7Ows7OTjRp0kRMnDhRpKen69RNSEgQrVq1Eg4ODqJx48Zi/vz5YuXKlQKASEtL09bz9vYWvXr10jsXADFhwgSdsrS0NAFALFy4UFs2cuRI4eTkJC5evChCQ0PFY489Jjw8PERUVJQoLCzUO2bx6XCEECI9PV1MmDBBeHl5CVtbW+Hp6SlCQkJEbGxsmffj3Llz4plnnhGOjo4CgN7UPPn5+aJWrVpCoVAY/Jl4lNiFECI2NlYEBgYKR0dH4eLiIgICAsSUKVPE1atXy4w1MzNTjBkzRtSpU0c89thjIjg4WBw5cqTM/aoqub+LkhCP/sRsYmIievXqhYYNG2LRokUIDg6Gh4cHRo0apTN7vKenJ9q2battkn9U2dnZUCgUUKlUcHV1NeoYRERkeqb6fs7Ly0NaWhp8fHy0U52UV0pKCnJyckrc7uLiUimTf1uqUaNGYcOGDTqrvVmKgoIC1K9fH+Hh4doezOIsOfaqTu7volFd1dHR0bC3t0diYiL8/f1LrPfkk0/W+MXAiYioctXkpLCq27JlC27evIkRI0aYOxQqgVGJ45EjR9ChQ4dSk0ZAMwIrOTnZqMCIiIioZjh8+DB+//13zJkzB23atEFwcLC5Q6ISGDWq+u7du7IGvKhUKr25p4iIiIiKi4mJwauvvgqlUolvvvnG3OFQKYxKHD08PHDhwoUy6/355596s9gTERGR+axatcrinhFctWoVCgoKcPToUTzxxBOl1rO02GsaoxLHzp0748SJEzhw4ECJdX788UdcuHABzz77rNHBEREREZHlMCpxfPvttyFJEgYMGIAtW7agoKBAZ3tSUhLGjh0LW1tbTJw40SSBEhEREZF5GZU4tm3bFp9++ikyMjIwcOBAuLm5QZIkbNy4EW5ubujVqxdu3LiBTz/9VLt4OxERERFVbUYvOThp0iRs27YN7du3R25uLoQQyMnJQXZ2NgICApCQkIDXXnvNlLESERERkRmVa8nBsLAwhIWF4datW0hLS4NarYaXlxfq1atnqviIiIiIyELIShw/++wztGzZEt27dze4vU6dOqhTp45JAyMiIiIiyyKrq/qNN97AmjVrDG7r1q0bFixYYNKgiIiIiMjyGP2MY5G9e/fi3LlzpoiFiIiILIgkSZg1a5a5wyALUu7EkYiIiEr2xx9/YNCgQfD29oaDgwMaNGiAHj164PPPPzd3aJXuo48+wpYtW8wdRpmuXbuGqVOn4tlnn4WLiwskScLevXvNHZZFYOJIRERUQZKTk9GuXTucPHkS48aNw9KlSzF27FhYWVkhOjra3OFVuqqSOP7555+YP38+/vnnHwQEBJg7HItSrlHVREREVLIPP/wQCoUCR44cgZubm862GzdumCcoKlNgYCBu3bqF2rVrY8OGDXjhhRfMHZLFYIsjERFVS4WFhdi7dy/Wrl2LvXv3orCwsNJjuHjxIvz9/fWSRgBQKpU6n+Pi4tCtWzcolUrY29ujZcuWiImJ0duvcePG6N27N/bu3Yt27drB0dERAQEB2q7UTZs2ISAgAA4ODggMDMTx48d19h81ahScnZ2RmpqKsLAwODk5oX79+vjggw8ghCjzmv755x+MHj0aHh4esLe3h7+/P1auXFnmfpIk4e7du/j6668hSRIkScKoUaOwZ88eSJKEzZs36+2zZs0aSJKEgwcPPnLsarUaS5Ysgb+/PxwcHODh4YHIyEjcvn27zFhdXFxQu3btMuvVRLJbHC9cuIBvvvnmkbcBwIgRIx49MiIiIiNt2rQJkyZNwpUrV7RlDRs2RHR0NAYMGFBpcXh7e+PgwYM4deoUnnjiiVLrxsTEwN/fH3369IGNjQ22bt2K8ePHQ61WY8KECTp1L1y4gKFDhyIyMhLDhw/HJ598gvDwcHz55ZeYPn06xo8fDwCYN28eBg8ejD///BNWVv+2FRUWFuK5555DUFAQFixYgKSkJERFRaGgoAAffPBBiTGmp6cjKCgIkiThtddeg7u7OxITEzFmzBhkZ2fjjTfeKHHf1atXY+zYsejQoQNeeeUVAICfnx+CgoLg5eWF+Ph49O/fX2ef+Ph4+Pn54amnnnrk2CMjI7Fq1SpERETg9ddfR1paGpYuXYrjx4/jwIEDsLW1LfXvg0ogZJAkSVhZWRn1sra2lnMKg1QqlQAgVCqV0ccgIiLTM9X3c25urjhz5ozIzc01UWRCbNy4UUiSJADovCRJEpIkiY0bN5rsXGXZsWOHsLa2FtbW1uKpp54SU6ZMEdu3bxf379/Xq3vv3j29srCwMOHr66tT5u3tLQCI5ORkbdn27dsFAOHo6CguX76sLV++fLkAIPbs2aMtGzlypAAgJk6cqC1Tq9WiV69ews7OTty8eVNbDkBERUVpP48ZM0bUq1dPZGRk6MQ0ZMgQoVAoDF5DcU5OTmLkyJF65dOmTRP29vYiKytLW3bjxg1hY2Ojc365se/bt08AEPHx8TrnSUpKMlhemvXr1+vdw+pI7u+irK7qRo0aGf3y8vIyebJLRERkSGFhISZNmmSwy7Wo7I033qi0busePXrg4MGD6NOnD06ePIkFCxYgLCwMDRo0QEJCgk5dR0dH7Z9VKhUyMjIQHByM1NRUqFQqnbotW7bUaYXr2LEjAM3cyo0aNdIrT01N1Yut+LLARS2I9+/fx65duwxeixACGzduRHh4OIQQyMjI0L7CwsKgUqlw7NgxubdGx4gRI5Cfn48NGzZoy7777jsUFBRg+PDhjxz7+vXroVAo0KNHD504AwMD4ezsjD179hgVJ8nsqr506VIFh0FERFR++/bt0+mefpgQAn///Tf27duHrl27VkpM7du3x6ZNm3D//n2cPHkSmzdvxuLFizFo0CCcOHECLVu2BAAcOHAAUVFROHjwIO7du6dzDJVKBYVCof1cPDkEoN32cGNNUfnDz/VZWVnB19dXp6xp06YASv43/+bNm8jKykJsbCxiY2MN1jF2wE/z5s3Rvn17xMfHY8yYMQA03dRBQUFo0qTJI8eekpIClUql9xxpeeOk6jyq+soV4OhRoF8/zecjR4A2bQAbC7rkc+eAf/4BQkIAIYBffwU6dAAkydyRUQ2UlgbExwPp6YCHBzBsGODjY+6odFWFGMm8rl27ZtJ6pmRnZ4f27dujffv2aNq0KSIiIrB+/XpERUXh4sWLCAkJQfPmzbFo0SJ4eXnBzs4O27Ztw+LFi6FWq3WOZW1tbfAcJZUbaoF9VEUxDB8+HCNHjjRYp1WrVkYff8SIEdrnUvPz83Ho0CEsXbrU6FiVSiXi4+MNbnd3dzc6zprOgrIoE5o3D5gxA6hbF3j+eSA7G3j6aaBJE+DHHwE/P/PGV1gITJgALF8OdOyoSRyPHQOCgoAuXYDNmwGu/U2V5MEDzY/jV18BVlaal1oNzJwJjB0LfPEFYO5nyKtCjGQZ6tWrZ9J6FaVdu3YA/k1gt27divz8fCQkJOi0JlZUl6parUZqaqq2pQ4Azp8/D0AzatsQd3d3uLi4oLCwEN27dzfqvFIpDSNDhgzBW2+9hbVr1yI3Nxe2trZ48cUXjYrdz88Pu3btQqdOnXQeAaDyq37T8cTGAtOnA+++C6SkAHZ2mgTy4EFNwtajB3DnjnljnDpV8y/g0qXAL79oytq2BZKSgLNngb59NS2QRJWgKCETQvMr8uCB5l0ITflDgzkZI1m0Ll26oGHDhiUmKJIkwcvLC126dKmUePbs2WOwtW/btm0AgGbNmgH4t6WweF2VSoW4uLgKi614a54QAkuXLoWtrS1CQkIM1re2tsbAgQOxceNGnDp1Sm/7zZs3yzynk5MTsrKyDG6rW7cuevbsiW+//Rbx8fF47rnnULduXaNiHzx4MAoLCzFnzhy9fQsKCkqMgcpWvVocCwqAuXM1/Vcffqi7rV07IDERaNYM+PZb4D//MU+Mt24Bn3+uaREt/q+dJAFhYcDatZrkdvduTUskUQVKTf03ITOkKDGbNs18XcJVIUayHNbW1oiOjsagQYMgSZJOIlaUTC5ZsqTELl1TmzhxIu7du4f+/fujefPmuH//PpKTk/Hdd9+hcePGiIiIAACEhobCzs4O4eHhiIyMxJ07d7BixQoolcoK6VZ3cHBAUlISRo4ciY4dOyIxMRE//fQTpk+fXmo37scff4w9e/agY8eOGDduHFq2bInMzEwcO3YMu3btQmZmZqnnDQwMxK5du7Bo0SLUr18fPj4+2gE8gKa7etCgQQBgMOmTG3twcDAiIyMxb948nDhxAqGhobC1tUVKSgrWr1+v/Rkpzdy5cwEAp0+fBqCZTmj//v0AgPfff7/Ufau1ihzaXV6PPN3DlStCvP66EH/8UXKdPn2E6NnTNAEa48QJISZMEOLGDcPb1WohWrYU4rXXKjcuqpHmzBHC2loITfpl+GVtranHGKk4S56ORwjNlDwNGzbUmY7Hy8urUqfiEUKIxMREMXr0aNG8eXPh7Ows7OzsRJMmTcTEiRNFenq6Tt2EhATRqlUr4eDgIBo3bizmz58vVq5cKQCItLQ0bT1vb2/Rq1cvvXMBEBMmTNApS0tLEwDEwoULtWUjR44UTk5O4uLFiyI0NFQ89thjwsPDQ0RFRYnCwkK9YxafDkcIIdLT08WECROEl5eXsLW1FZ6eniIkJETExsaWeT/OnTsnnnnmGeHo6CgA6E3Nk5+fL2rVqiUUCoXBn4lHiV0IIWJjY0VgYKBwdHQULi4uIiAgQEyZMkVcvXq1zFiL/+w8/KqO5P4uSkJYbp9odnY2FAoFVCoVXF1dTXNQISx/8ElViJGqhYkTNY/aPnhQch1bWyAyUtNQbg5VIcaayFTfz3l5eUhLS4OPjw8cHBxMGKFmap59+/bh2rVrqFevHrp06VJpLY2WbNSoUdiwYQPumPuxLQMKCgpQv359hIeH47///a/edkuOvaqT+7tYvbqqi0YmOzoCJY3sysvTbDcXtRrYtQto0QIwNMdlYaHmZWdX+bFRjePhofmRLI1aralnLlUhRrJM1tbWlTblDpnGli1bcPPmTa44Z8Gq3+CYMWOAt9/WJF8PS07W/Oti5ASlJpGXB7z4ov4zmEXi4zUJJeeYokowdKi8pGzYsMqJx5CqECMRlc/hw4exYsUKvPXWW2jTpg2Cg4PNHRKVoHoljpIELFigGVjywgvA/z/Qirw84Ouvgd69gSeeAAICzBfjY48Bc+Zo+t7Gjwf++ktTrlIBn34KjBunGRRTwqSlRKbk66uZzqakJyMkSbPdnINOqkKMRFQ+MTExePXVV6FUKvHNN9+YOxwqRfV8xnHTJk1Slp6uGbkcFwfcu6eZ5mbVKsDNraJClu/zz4H33wdycjQxxsZqmk3GjAE++4xd1VRpSpojUa22nDkSq0KMNU1VeMaRiOST+7tYPRNHALh/H0hIAGrXBk6cAMLDgccfr5A4jXbnDrBxI9CwoWb+xgEDgPr1zR0V1VDFV2Xx9NR0EVtaK15ViLGmYOJIVL0wcSQiogrDxJGoepH7u1i9nnEkIqIqyYLbMIhqBLm/g0wciYjIbGxtbSFJEu7evWvuUIhqtLt370KSJNiW8cB49ZrHkYiIqhRra2soFArcvHkT+fn5cHV1hY2NTYlrTROR6QghUFBQgOzsbGRnZ8PNza3MSfKZOBIRkVl5enrC0dERN27cQHZ2trnDIapxrK2tUa9ePSgUijLrMnEkIiKzkiQJbm5uUCgUKCwsREFBgblDIqoxbGxsYG1tLbuVn4kjERFZBEmSYGNjAxsb/tNEZKk4OIaIiIiIZGHiSERERESyMHEkIiIiIlmYOBIRERGRLEwciYiIiEgWJo5EREREJAsTRyIiIiKShYkjEREREcnCxJGIiIiIZGHiSERERESyMHEkIiIiIlm4ICgRVQ1paUB8PJCeDnh4AMOGAT4+5o6KiKhGYeJIRJbtwQNgwgTgq68AKyvNS60GZs4Exo4FvvgCsLU1d5RERDUCE0cismxFSaMQQGGh5lXkq68077Gx5omNiKiG4TOORGS5UlP/TRoNEUKzPS2tcuMiIqqhmDgSkeVas0bTNV0aKyvNs49ERFThmDgSkeVKT5eXOKanV048REQ1HBNHIrJcHh6agTClUas19YiIqMIxcSQiyzV0qLzEcdiwyomHiKiGY+JIRJbL11cz5Y4kGd4uSZrtnM+RiKhSMHEkIsv2xRf/Jo/W1po5G62tNdvattV8njuXI6uJiCqBJERJ81yYX3Z2NhQKBVQqFVxdXc0dDhGZU9HKMVevAkeOAL/9pjshuFrNCcErEb+fiWomTgBORFWDjw/w/vvAK69oksaSJgTPzgaeeIJLExIRVQC2OBJR1ZGaCjRpUvKE4EWsrdkSWcH4/UxUM7HFkYiqjqIJwYu3MhrCpQmJiCoEB8cQUdUhZ0JwQ7g0IRGRSTBxJKKqQ86E4CXh0oREROXGxJGIqg45E4KXhEsTEhGVGxNHIqo6ypoQvDRcmpCIqNw4OIaIqpYvvtC8f/XVv/M4FhZyaUIiokrAxJGIqhZbW83o6GnTNM8spqcDnp7AqVPAd98ZnqqHSxMSEZkEE0ciqpqKJgQv8uAB4OKi2xL58DyORERULpwAnIiql6KlCYtaIocOZUtjBeD3M1HNxBZHIqpeHm6JJCIik+GoaiIiIiKShYkjEREREcnCxJGIiIiIZGHiSERERESycHAMEVWe4iOePTw0E3JzxDMRUZXBxJGIKt6DB8CECfpzLM6c+e8ci7a25o6SiIjKwMSRiCpeUdIohGZ5wMLCf7d99ZXmPTbWPLEREZFsnACciCpWairQpInhpQCLSBJw8WKZ3dZVoae7KsRoCvx+JqqZ2OJIRBVrzRpN13TxVsaHWVlpsq0SJu6uCj3dVSFGIqLyYuJIRBUrPV1e4pieXuLmqtDTXRViJCIqL07HQ0QVy8ND0/RWGrVaU8+A1NR/EzJDhNBsT0srZ5zlUBViJCIyBSaORFSxhg6VlzgOG2ZwU1FPd2mKerrNpSrESERkCkwciahi+fpqHvKTJMPbJUmzvYQRJEU93aUpo6e7wlWFGImITIHPOBJRxfviC837wyNH1Op/R46UoJw93ZWiKsRIRGQKnI6HiCpP8blqPD013dhlzFVjwtl8KkxViNHU+P1MVDOxxZGIKo+PT4lT7pSkqKe7pMEnZfR0V4qqECMRkSkwcSQii1eOnu5KUxViJCIqL3ZVE1GVYURPd6WrCjGaAr+fiWomJo5ERPTI+P1MVDNxOh4iIiIikoWJIxERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSxMHImIiIhIFiaORERERCQLE0ciIiIikoWJIxERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSxMHImIiIhIFiaORERERCQLE0ciIiIikoWJIxERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSxMHImIiIhIFiaORERERCQLE0ciIiIikoWJIxERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSxMHImIiIhIFiaORERERCQLE0ciIiIikoWJIxERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSxMHImIiIhIFiaORERERCQLE0ciIiIikoWJIxERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSxMHM0lMxOYMweYMUPzOT8fePttICXFvHEV99dfmpi+/FLz+epVYPp04No188ZFNVZaGjB3LjBxouY9Lc3cERER1SxMHM3hyhWgQwfg44+BnBxN2fnzQHw80LYt8Msv5o0PAI4fB9q0AVatAu7d05SdPAl88QUQGAj8+adZw6Oa5cED4JVXAD8/YNYsYPlyzbufn6b8wQNzR0hEVDNIQghh7iBKkp2dDYVCAZVKBVdXV3OHYzrPPgukpgJ79wI+Pv+W370L9O2rSdouXwacnc0T34MHwOOPA+7uwPbtQO3a/267fh0ICQGsrIDffwckyTwxUo3yyivAV18Bhr6tJAkYOxaIja38uGqyavv9TESlYotjZfv9d03C+MknukkjADg5AStXAllZwLffmiM6jYQETeL61Ve6SSMAeHoCy5YBp04Bu3ebJz6qUVJTS04aAU35V1+x25qIqDIwcaxs9etrEsd+/Qxvb9RI8xyhjU1lRqWrY0dg/37gyScNb3/mGWDcuH+7sIkq0Jo1mgbu0lhZaZ70ICKiimXG7KSGqlsXCA4uvc6cOZUTS0kaNtS8SiJJ7BekSpOerkkMCwtLrmNlpalHREQViy2Ole3uXc0DWSUNgMnMBH7+ueR+ucrwzz/ACy8Aly4Z3p6aChw9WqkhUc3l4QGo1aXXUas19YiIqGIxcaxsjz0GHDqkmeYmO1t3m1oNvPMO8PzzQEaGeeIDADc3YNcu4M039Yer5uZqRir07QsUFJglPKpZhg6VlzgOG1Y58RAR1WRMHCubJAHffANcuAC0bg0sXgycOQOsXg107qyZ/mbFCs2IZnNxctLE+NNPmmmDvvpKE+OyZZqpeJKTNQ+UmfM5TKoxfH01jfQlDeAvGlX98FgzIiIyPSaO5tC2rabVsWNH4N13gc8+A0aMAOztNdPfjBhh7giB8HDNIJ569TQtjJ99ppl1uVkzzcCZrl3NHSHVIF988W/yaG0N2Npq3ouSxi++MHeEREQ1A+dxNDeVStMdXFhouQ9pFXWbW1npT89DVInS0jSN3enpmpmhhg5lS6O51IjvZyLSw8SRiIgeGb+fiWomdlUTERERkSxMHImIiIhIFiaORERERCQLE0ciIiIikoWJIxERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSxMHImIiIhIFhtzB1CaotUQs7OzzRwJEREVV/S9bMGr1hJRBbDoxDEnJwcA4OXlZeZIiIjIkJycHCgUCnOHQUSVRBIW/N9FtVqNq1evwsXFBZIkmTscIiL6f0II5OTkoH79+rCy4lNPRDWFRSeORERERGQ5+N9EIiIiIpKFiSMRERERycLEkYiIiIhkYeJIRERERLIwcSQiIiIiWZg4EhEREZEsTByJiIiISBYmjlQlNG7cGJIklfpasmSJucOsFv7++28sX74cr7zyCgIDA2Fvbw9JkjB27Fhzh0ZERGZm0UsOEj2sU6dOaNKkicFtLVu2rORogEuXLsHHxwfe3t64dOlSpZ+/ImzcuBFvvvmmucMgIiILxMSRqpSxY8di1KhR5g6jWvPx8cHEiRPRtm1btG3bFt9//z0+/PBDc4dFREQWgIkjEeno27cv+vbtq/28adMmM0ZDRESWhM84UrX122+/YdiwYWjUqBHs7e1Ru3ZthIWFYdu2bQbrnzlzBlFRUejUqRMaNGgAOzs71KlTB927d8f333+vV3/UqFHw8fEBAFy+fFnvmcvi9SRJwqpVqwyed9WqVZAkSa8ltXh5ZmYm3njjDfj5+cHe3h5du3bVqfvzzz9jwIABqFevHuzs7KBUKtG/f38cPHhQ/g0jIiIqA1scqVqKjo7GW2+9BbVajdatW6Njx464fv069u7dix07dmD27NmYOXOmzj6LFi3Cf//7XzRv3hwBAQFwc3PDX3/9hT179uDnn3/GoUOHsGjRIm39zp07486dO9i4cSOcnJwwaNCgCrmWjIwMtGvXDllZWejSpQsCAwNhZ2en3f7OO+/g008/hZWVFdq1a4cuXbrgr7/+wg8//ICtW7dixYoViIiIqJDYiIiohhFEVYC3t7cAIOLi4sqsm5SUJCRJEnXr1hW//PKLzrbff/9dNGzYUAAQe/fu1dm2d+9ecfHiRb3jnTt3TrvP4cOHdbalpaUJAMLb27vEeEaOHFlq7HFxcQKAGDlypMFyACIkJESoVCq9fWNjYwUA0aRJE3Hy5Emdbb/88otwcXERdnZ24vz58yXGV5aoqCgBQIwZM8boYxARUfXArmqqUiIiIgxOxVO86zYqKgpCCHz55Zd45plndPYPCAjQthp+/vnnOtuCg4Ph6+urd85mzZphxowZAIANGzaY+IrKZmtri9jYWLi6uuqUq9VqzJo1CwCwbt06tGrVSmf7M888gxkzZuD+/ftYvnx5ZYVLRETVGLuqqUopaTqe5s2bA9B06/76669wdHREeHi4wWMUJZnJycl62+7cuYPExEQcP34cGRkZuH//PgDg2rVrAIA///zTFJfxSNq0aWMwoT1+/DiuXr0KPz8/BAYGGty3tGslIiJ6VEwcqUopazqetLQ0CCGQm5sLe3v7Uo918+ZNnc9bt25FREQEbt26VeI+2dnZjxSvKTRu3NhgeWpqKgDg4sWLOoNxDHn4WomIiIzBxJGqFbVaDQBwdnbGwIEDZe/3zz//4MUXX0Rubi6mTJmCYcOGoXHjxnB2doaVlRV27NiBsLAwCCEqLOaSODo6lrqfp6cnwsLCSj1G3bp1jQuOiIioGCaOVK14eXkBACRJwsqVK2FlJe8x3q1btyI3Nxf9+/fH/Pnz9banpKQYHVPRCOicnByD2y9fvmzUcYuutU6dOiVO9UNERGRKHBxD1Ur9+vXRqlUr5OTkICkpSfZ+mZmZAABvb2+9bUIIrFmzxuB+RUlhQUFBicdu0KABAODs2bMGj52YmCg7zuLat2+PunXr4syZMzh9+rRRxyAiInoUTByp2pk7dy4AzQjsrVu36m0XQuDw4cPYsWOHtqxFixYANKOmiwbCAEBhYSFmzpxZ4uASd3d32NnZ4fr169rk82Hdu3cHAKxevRpnzpzRlj948ADvvvsujhw58ohXqGFra6sdQd6/f3/s379fr05hYSF2796NQ4cOGXUOIiKi4thVTdVOeHg4oqOj8fbbb6NPnz5o0qQJmjVrBoVCgZs3b+LkyZO4ceMG3n33XYSGhmr3CQwMxG+//YamTZsiODgYTk5OOHz4MK5evYp3333XYBe2ra0t+vTpgw0bNqB169bo3LkzHnvsMQDAV199BUAzErxv37744Ycf0K5dO3Tu3BmOjo44duwYsrOzMWnSJERHRxt1ra+99hr++usvLFy4EF26dIG/vz+aNGkCR0dHXL9+HSdOnEBWVhZiYmIQFBQk65jXrl1D//79tZ+vXLkCAEhISNA5xrJly9C2bVuj4iYioqqJiSNVS6+//jq6deuGzz//XLvyi5WVFTw9PdGmTRv06tVLZ/CMjY0N9u7di3nz5mHjxo34+eef4erqiqeffhobN25ETk6OwcQRAJYvX446deogMTERGzZswIMHDwD8mzgCwHfffYe5c+dizZo12Lt3L2rVqoWQkBDMmTMH+/btK9e1LliwAP369cOyZcuwf/9+JCUlwc7ODvXq1UPXrl3Ru3dvDBgwQPbx8vPzcfjwYb3ymzdv6ozONscIcyIiMi9JVMQwUSIiIiKqdviMIxERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSxMHImIiIhIFiaORERERCQLE0ciIiIikoWJIxERERHJwsSRiIiIiGRh4khEREREsjBxJCIiIiJZmDgSERERkSz/BwY2WNdYQXzIAAAAAElFTkSuQmCC\n",
      "text/plain": [
       "<Figure size 500x500 with 2 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "scatter_plot(datasets, use_rep=\"X_jitteredbarycenter\", plot_before=True)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c408368f",
   "metadata": {},
   "source": [
    "Perfect!"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "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.10.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}