{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "787c6977",
   "metadata": {},
   "source": [
    "# Random Boolean network generation\n",
    "\n",
    "This tutorial demonstrates how to generate *random Boolean networks with\n",
    "controlled structural and functional properties* using BoolForge.\n",
    "This ability enables ensemble studies, which are exemplified in the next tutorial.\n",
    "\n",
    "## What you will learn\n",
    "In this tutorial you will learn how to generate random Boolean networks with\n",
    "\n",
    "- prescribed structural properties (e.g., degree, degree distribution, strongly connected),\n",
    "- prescribed functional properties (e.g., canalization, bias),\n",
    "\n",
    "It is strongly recommended to complete Tutorials 4 and 5 on random function generation first.\n",
    "\n",
    "## Setup"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "id": "5d6fe892",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:23.227705Z",
     "iopub.status.busy": "2026-03-31T14:27:23.227125Z",
     "iopub.status.idle": "2026-03-31T14:27:24.340186Z",
     "shell.execute_reply": "2026-03-31T14:27:24.339836Z"
    }
   },
   "outputs": [],
   "source": [
    "import boolforge as bf\n",
    "import numpy as np\n",
    "import matplotlib.pyplot as plt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d11e89b7",
   "metadata": {},
   "source": [
    "## Generating random wiring diagrams\n",
    "\n",
    "The function `random_network(N, n, *args)` generates a random $N$-node\n",
    "Boolean network with degree parameter `n`. \n",
    "The generation follows a two-step process:\n",
    "\n",
    "- A random wiring diagram is created using `random_wiring_diagram(N, n, *args)`.\n",
    "- Random Boolean functions with prescribed properties are generated using \n",
    "  `random_function(n, *args)`, which was discussed in depth in Tutorials 4 and 5.\n",
    "\n",
    "We first consider only the structural parameters that concern the generation of\n",
    "the random wiring diagram. In the absence of optional arguments,\n",
    "the in-degree distribution is assumed to be constant. That is, each node in the \n",
    "network is regulated by `n` nodes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "id": "d8cf0384",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:24.341933Z",
     "iopub.status.busy": "2026-03-31T14:27:24.341773Z",
     "iopub.status.idle": "2026-03-31T14:27:24.396590Z",
     "shell.execute_reply": "2026-03-31T14:27:24.396347Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 400x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N = 5\n",
    "n = 2\n",
    "\n",
    "W = bf.random_wiring_diagram(N, n, rng=2)\n",
    "\n",
    "W.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "dfb7298d",
   "metadata": {},
   "source": [
    "The argument `rng` seeds the random number generator, ensuring reproducible results.\n",
    "\n",
    "The rest of this tutorial describes the various constraints / optional arguments. \n",
    "Each optional argument restricts the family of networks from which\n",
    "`random_wiring_diagram()` and `random_network()` samples.\n",
    "\n",
    "### Allowing self-regulation\n",
    "\n",
    "BoolForge selects the `n` regulators of each node uniformly at random\n",
    "from the set of all other nodes. Thus, self-regulation is disallowed by default.\n",
    "Setting `allow_self_loops=True` allows nodes to regulate themselves."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "id": "4b87f6d9",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:24.397746Z",
     "iopub.status.busy": "2026-03-31T14:27:24.397680Z",
     "iopub.status.idle": "2026-03-31T14:27:24.428880Z",
     "shell.execute_reply": "2026-03-31T14:27:24.428669Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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",
      "text/plain": [
       "<Figure size 400x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N = 5\n",
    "n = 2\n",
    "\n",
    "W = bf.random_wiring_diagram(N,n,allow_self_loops=True,rng = 2)\n",
    "\n",
    "W.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ec4c9470",
   "metadata": {},
   "source": [
    "### Poisson in-degree distributions\n",
    "\n",
    "Classical random Boolean network theory (NK Kauffman models) assume a fixed in-degree,\n",
    "the default in BoolForge. However, this is a strong assumption since the in-degree\n",
    "in curated biological Boolean network models often appears approximately\n",
    "Poisson distributed.\n",
    "BoolForge provides the option to generate random wiring diagrams with Poisson distributed\n",
    "in-degree, using the optional parameter `indegree_distribution`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "id": "34fa7afa",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:24.430066Z",
     "iopub.status.busy": "2026-03-31T14:27:24.430000Z",
     "iopub.status.idle": "2026-03-31T14:27:24.462098Z",
     "shell.execute_reply": "2026-03-31T14:27:24.461884Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "iVBORw0KGgoAAAANSUhEUgAAAYYAAAGGCAYAAAB/gCblAAAAOnRFWHRTb2Z0d2FyZQBNYXRwbG90bGliIHZlcnNpb24zLjEwLjUsIGh0dHBzOi8vbWF0cGxvdGxpYi5vcmcvWftoOwAAAAlwSFlzAAAPYQAAD2EBqD+naQAAXahJREFUeJztnQd8jff3x48ZI6gYpUYURc1aVZsa1Z+9a9aoolZRq7Ro7VJ71qhRqzb927QoSu3Ye8QeEUQQvv/X58ST3hsJGffeZ53365UXSW7u/d7xPJ/ne875nBNHKaVIEARBEF4SV/uPIAiCIAARBkEQBMEJEQZBEATBCREGQRAEwQkRBkEQBMEJEQZBEATBCREGQRAEwQkRBkEQBMEJEQZBEATBCREGwdasW7eOPvjgA0qUKBHFiROHAgICYnxfLVq0oCxZsrh0fYKgByIMQow5cuQI1atXj3x9ffnEmiFDBqpUqRKNHz/+lds+f/6cZs2aReXKlSMfHx/y8vLik2jLli3p33//feX2Z8+epbZt21LWrFn5vpMnT04lS5aksWPH0uPHj12y/jt37lCDBg0oceLENHHiRJo7dy4lTZqUzATECIIW/itXrlx6L00wMXGkV5IQE3bu3Enly5enzJkz0+eff07p0qWjy5cv0+7du/mkfubMmbDb4kRep04dvjovU6YMVa9encXhwoULtHjxYjp16hRdunSJMmbMyLf/448/qH79+iwezZs3p7x589LTp09px44dtHTpUj4ZTps2LdbPAev59NNPaePGjVSxYsVY39+zZ8/oxYsXvG5Pgddi4cKFNH36dKefp0iRgl9nQYgJ8WP0V4LtGTx4MJ989u7dS2+99ZbT727evOn0fY8ePfgkPHr0aPr666+dfte/f3/+ucb58+fps88+413Ili1bKH369GG/69ChAwsOhMMVaOsMv/6YkiBBAtKD+PHjU9OmTXV5bMGiYMcgCNElZ86cqly5cm+83eXLl1X8+PFVpUqVonS/7dq1ww5W/f3337Fa3+LFi1WhQoVUokSJVKpUqVSTJk3UlStXwn5ftmxZfhzHr88//zzS+wsMDFRdunRRvr6+KmHChCpNmjSqYsWKat++fWG3wd/j9697DO1r1qxZYbe7d+8e33fGjBn5vrNly6aGDRumnj9//sbnicdMmjSpCgkJUffv34/hqyUI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",
      "text/plain": [
       "<Figure size 400x400 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N = 5\n",
    "n = 2\n",
    "\n",
    "W = bf.random_wiring_diagram(N,n,indegree_distribution='poisson',rng = 5)\n",
    "\n",
    "W.plot();"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a8cc3ff8",
   "metadata": {},
   "source": [
    "We see that some nodes ($x_1$ and $x_3$) are only regulated by one node,\n",
    "while others ($x_0$ and $x_4$) possess three regulators each.\n",
    "\n",
    "When using a Poisson-distributed in-degree, the in-degree of every node \n",
    "is always at least 1. This avoids the artificial creation of identity nodes\n",
    "(with in-degree 0).\n",
    "\n",
    "### Avoiding output nodes\n",
    "\n",
    "In general, it is possible that some nodes in a generated Boolean network \n",
    "will not regulate other nodes. By setting `min_out_degree_one=True`, we can\n",
    "force every node to regulate at least one node. That is, output nodes can be disallowed.\n",
    "\n",
    "### Strong connectedness\n",
    "\n",
    "The wiring diagram of the generated Boolean network may or may not be strongly\n",
    "connected. Setting `strongly_connected=True` (default False) forces strong\n",
    "connectedness. Uniform sampling among strongly connected networks cannot be achieved by\n",
    "a simple construction method. BoolForge therefore generates candidate\n",
    "networks and rejects them until a strongly connected network is obtained.\n",
    "\n",
    "Careful: When the number of nodes `N` is large and the degree `n` is small, this may take a\n",
    "long time. The number of unsuccessful attempts before raising an error is controlled\n",
    "by the optional parameter `max_strong_connectivity_attempts`. \n",
    "\n",
    "### Fixed wiring diagrams\n",
    "\n",
    "All optional parameters discussed thus far describe properties of the wiring diagram.\n",
    "Instead of generating a new wiring diagram, an existing one (e.g., from a curated\n",
    "biological network model) can be passed directly to `random_network`.\n",
    "\n",
    "In that case, `random_network(I, *args)` does not require `N` and `n`, because\n",
    "these quantities are inferred from the wiring diagram, provided via optional parameter `I`.\n",
    "As described in detail in Tutorial 6, `I` can be either a `WiringDiagram` object \n",
    "or a list of lists describing the regulators of each node.\n",
    "\n",
    "For example, using the previously generated wiring diagram, we can write"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 5,
   "id": "abf37da0",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:24.463191Z",
     "iopub.status.busy": "2026-03-31T14:27:24.463126Z",
     "iopub.status.idle": "2026-03-31T14:27:24.757635Z",
     "shell.execute_reply": "2026-03-31T14:27:24.757302Z"
    }
   },
   "outputs": [],
   "source": [
    "bn = bf.random_network(I=W)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26d4d23e",
   "metadata": {},
   "source": [
    "This feature allows multiple Boolean networks with different update functions\n",
    "to be generated on the same wiring diagram.\n",
    "\n",
    "## Specifying functional constraints\n",
    "\n",
    "Once the wiring diagram is generated, the number of nodes `N` and the in-degree of each node are determined.\n",
    "In step 2, `random_network` now repeatedly calls `random_function` to generate \n",
    "the random Boolean functions. The optional parameters regulating the functional constraints\n",
    "are practically identical to the ones discussed in depth in Tutorial 4, with one\n",
    "important distinction: Most parameters can be sequences of length `N`, in order to\n",
    "specify distinct functional behavior for the different nodes.\n",
    "\n",
    "In the following, we summarize the key concepts.\n",
    "\n",
    "### Parity functions\n",
    "If `parity=True` (default False), parity functions (also known as linear functions)\n",
    "are chosen for all nodes, yielding a linear Boolean network (see @chandrasekhar2023stability).\n",
    "Note that for any degree `n`, there are only two parity functions.\n",
    "\n",
    "### Canalizing functions\n",
    "If a specific `layer_structure` is provided, all functions possess at least these\n",
    "canalizing layers."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 6,
   "id": "a35e2fbc",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:24.759072Z",
     "iopub.status.busy": "2026-03-31T14:27:24.758918Z",
     "iopub.status.idle": "2026-03-31T14:27:24.761562Z",
     "shell.execute_reply": "2026-03-31T14:27:24.761362Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0 1 1 0 0 0 0 0] [1]\n",
      "[0 0 1 1 0 1 1 1] [1, 2]\n",
      "[0 0 0 0 0 0 0 1] [3]\n",
      "[1 1 1 0 1 1 1 1] [3]\n"
     ]
    }
   ],
   "source": [
    "bn = bf.random_network(N=4,n=3,layer_structure=[1],rng = 2)\n",
    "for f in bn.F:\n",
    "    print(f,f.get_layer_structure()['LayerStructure'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e0cd02b",
   "metadata": {},
   "source": [
    "As we see, it is however possible for some functions to randomly possess more canalizing\n",
    "variables in a larger and/or more layers. To ensure `layer_structure` is interpreted\n",
    "as exact layer structure, set `exact_depth=True`. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 7,
   "id": "4b8ed433",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:24.762617Z",
     "iopub.status.busy": "2026-03-31T14:27:24.762552Z",
     "iopub.status.idle": "2026-03-31T14:27:24.765231Z",
     "shell.execute_reply": "2026-03-31T14:27:24.765043Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "[0 1 1 0 0 0 0 0] [1]\n",
      "[1 0 1 1 0 1 1 1] [1]\n",
      "[1 1 0 1 0 1 1 1] [1]\n",
      "[0 1 1 0 1 1 1 1] [1]\n"
     ]
    }
   ],
   "source": [
    "bn = bf.random_network(N=4,n=3,layer_structure=[1],exact_depth=True,rng = 2)\n",
    "for f in bn.F:\n",
    "    print(f,f.get_layer_structure()['LayerStructure'])"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8e4b7c1a",
   "metadata": {},
   "source": [
    "Rather than specifying the exact layer structure, we can also describe the desired\n",
    "*canalizing depth* (i.e., the number of conditionally canalizing variables) via `depth`. \n",
    "As before, the optional argument `exact_depth` (default False) determines if \n",
    "`depth` is interpreted as exact canalizing depth, or as minimum canalizing depth."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 8,
   "id": "afe47136",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:24.766178Z",
     "iopub.status.busy": "2026-03-31T14:27:24.766114Z",
     "iopub.status.idle": "2026-03-31T14:27:24.769688Z",
     "shell.execute_reply": "2026-03-31T14:27:24.769479Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "1 [0 1 1 0 0 0 0 0]\n",
      "3 [0 0 0 0 0 0 1 0]\n",
      "3 [1 1 0 0 1 1 1 0]\n",
      "3 [0 1 1 1 0 0 0 0]\n",
      "\n",
      "1 [0 1 1 0 0 0 0 0]\n",
      "1 [1 0 0 0 0 0 1 0]\n",
      "1 [1 1 0 1 0 1 1 1]\n",
      "1 [0 0 1 0 1 0 0 0]\n"
     ]
    }
   ],
   "source": [
    "#Boolean network whose rules all have minimal canalizing depth 1\n",
    "bn1 = bf.random_network(N=4,n=3,depth=1,exact_depth=False,rng = 2)\n",
    "for f in bn1.F:\n",
    "    print(f.get_canalizing_depth(),f) \n",
    "print()    \n",
    "\n",
    "#Boolean network whose rules all have exact canalizing depth 1\n",
    "bn2 = bf.random_network(N=4,n=3,depth=1,exact_depth=True,rng = 2)\n",
    "for f in bn2.F:\n",
    "    print(f.get_canalizing_depth(),f) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "348ef949",
   "metadata": {},
   "source": [
    "Most optional parameters (e.g., `n`, `depth`, `layer_structure`, `bias`, `absolute_bias`) \n",
    "can also be specified as sequences of length `N`.\n",
    "In that case, each entry applies to one node in the network, allowing\n",
    "different functional constraints for different nodes."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 9,
   "id": "69ad273c",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:24.770728Z",
     "iopub.status.busy": "2026-03-31T14:27:24.770662Z",
     "iopub.status.idle": "2026-03-31T14:27:24.772843Z",
     "shell.execute_reply": "2026-03-31T14:27:24.772624Z"
    }
   },
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "3 [1 1 1 1 0 1 1 1]\n",
      "1 [1 1 0 1 0 1 1 1]\n",
      "2 [1 1 0 1]\n",
      "0 [0 1 1 0]\n"
     ]
    }
   ],
   "source": [
    "bn = bf.random_network(\n",
    "    N=4,\n",
    "    n=[3,3,2,2],\n",
    "    depth=[3,1,2,0],\n",
    "    exact_depth=True,\n",
    "    rng=2\n",
    ")\n",
    "\n",
    "for f in bn.F:\n",
    "    print(f.get_canalizing_depth(),f) "
   ]
  },
  {
   "cell_type": "markdown",
   "id": "33072ffb",
   "metadata": {},
   "source": [
    "### Biased functions\n",
    "When `parity=False` and all canalization parameters are also at their default values,\n",
    "`random_network` generates each update function with a specified *bias*, i.e.\n",
    "\n",
    "  - probability of output 1: `bias`\n",
    "  - probability of output 0: `1-bias`\n",
    "\n",
    "The unbiased case (`bias=0.5`) is the default. Instead of the bias, users can\n",
    "also specify the absolute bias to generate functions with a bimodal Hamming weight\n",
    "distribution. For BoolForge to use the parameter provided via `absolute_bias`, \n",
    "`use_absolute_bias=True` is required. The default is `use_absolute_bias=False`, \n",
    "i.e., by default `bias` is used, resulting in a unimodal Hamming weight distribution."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 10,
   "id": "ae8101a5",
   "metadata": {
    "execution": {
     "iopub.execute_input": "2026-03-31T14:27:24.773850Z",
     "iopub.status.busy": "2026-03-31T14:27:24.773767Z",
     "iopub.status.idle": "2026-03-31T14:27:24.895224Z",
     "shell.execute_reply": "2026-03-31T14:27:24.894998Z"
    }
   },
   "outputs": [
    {
     "data": {
      "image/png": "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fnOclQVAMq9BUrNap06dIm1Xr7Zt27aFqlwAAACJJ0DKkyePbdq0KdJ2bcubN2+oygUAAJB4mtg6d+5sXbp0sV9//dXq1q3rtq1cudJeeeUV6927dzjKCAAAkLADpIEDB1qWLFlszJgx1r9/f7etYMGCNmTIEHv66afDUUYAAICEHSBptGwlaWv5888/3TYFTAAAAMl6HCQPAiMAAJBsA6Rq1arZ0qVLLUeOHFa1alVXixSVDRs2hLJ8AAAACTNAat68uaVLl877dXQBEgAAQLIIkAYPHuz9WsnYAAAASVmMx0EqUaKE/f7775G2nzp1yu0DAABIdgHS3r177cqVK5G2X7hwwQ4cOBCqcgEAACT8Xmyff/6534S12bJl864rYFISd/HixUNfQgAAgIRag9SiRQu3KEG7ffv23nUtDz30kC1evNgNHhlTEydOtGLFiln69Omtdu3atnbt2iiP3bp1q7Vq1codr3KMHz8+0jHKkdI+36Vs2bJ+x5w/f966detmuXLlssyZM7tzHj16NMZlBwAAyTxAunr1qluKFClix44d865rUfPazp077d57743RxWfPnu2mJ1ESuIYHqFy5sjVu3NidP5hz5865PKeRI0da/vz5ozxv+fLl7fDhw97l+++/99uvQS6/+OILmzNnjq1YscIOHTpkLVu2jFHZAQBA0hXjgSL37NkTsouPHTvWze3WoUMHtz558mRbsGCBTZ061fr16xfp+Jo1a7pFgu33SJ06dZQB1OnTp23KlCk2c+ZMu/vuu922adOmWbly5WzNmjV26623hujuAABAsknS1nxrr7/+eqTtEyZMsGeeeea6z3Px4kVbv369NWzY8H+FSZnSra9evdpuxK5du9z8cKpteuSRR2zfvn3efbrmpUuX/K6rJjjVjEV3XdWSnTlzxm8BAABJU4wDpE8++cRuu+22SNvr1q1rH3/88XWf58SJEy65O1++fH7btX7kyJGYFstLeUzvvvuuffXVVzZp0iRX43X77bd7543TudOmTWvZs2eP0XVHjBjhEtM9S+HChWNdRgAAkMQCJI2B5NuDzSNr1qwu6IlvTZs2tdatW1ulSpVcPtOXX37pxmj66KOPbui8/fv3d81znmX//v0hKzMAAEjkAVKpUqVc7UyghQsXxmigyNy5c1uqVKki9R7TenQJ2DGlmqKbb77ZfvnlF7euc6t5T0FTTK6rqVYUBPouAAAgaYpxgKReZ88995zreaYeYFoGDRrkkqbVO+x6qZmrevXqbvwkD/WI03qdOnUsVP766y/bvXu3FShQwK3rmmnSpPG7rnrgKU8plNcFAADJqBdbx44dXcLy8OHDbdiwYW6bxiVSvk+7du1iHGxpTKUaNWpYrVq13LhGZ8+e9fZq0/kKFSrk8n9ENT/btm3zfn3w4EHbtGmTG8tINVvy7LPP2n333WdFixZ13fcVyKmmqm3btm6/mgc7derkrp0zZ05XE9SjRw8XHNGDDQAAxCpAkq5du7rl+PHjliFDBhegxEabNm3cOVQDpQTpKlWquOY7T+K2anXUs81DAU/VqlW966NHj3ZL/fr1bfny5W6bpjtRMKRcqTx58li9evVc93197TFu3Dh3Xg0QqWBPuUpvvvkmPxEAACD2AZKHb9ARW927d3dLMJ6gx0M1VREREdGeb9asWde8pkbt1gjeWgAAAG44B0nJzI899pgbZ0gDMqr5yncBAABIdjVIjz/+uGv6GjhwoEt81lxnAAAAyTpA0rxm3333ncsXAgAASIpi3MSmEaSvlQcEAACQrAIkdcXXmEd79+4NT4kAAAASWxObuuafO3fOSpYsaRkzZnSDLvo6efJkKMsHAACQ8AMk1SABAAAkZTEOkDTyNQAAQFIW4wBJXfyjU6RIkRspDwAAQOILkDSadXRjH125cuVGywQAAJC4AqSNGzf6rV+6dMltGzt2rJvAFgAAINkFSJUrV460rUaNGm7qkVGjRlnLli1DVTYAAIDEMQ5SVMqUKWPr1q0L1ekAAAASTw3SmTNn/NY1qvbhw4dtyJAhVrp06VCWDQAAIHEESNmzZ4+UpK0gSVOQzJo1K5RlAwAASBwB0rJly/zWU6ZMaXny5LFSpUpZ6tQxPh0AAECCc10RTbVq1Wzp0qWWI0cOW7FihT377LNumhEAAIBkm6S9fft2O3v2rPt66NCh3q8BAACSbQ1SlSpVrEOHDlavXj2Xb6Tu/JkzZw567KBBg0JdRgAAgIQXIL377rs2ePBgmz9/vkvQXrhwYdB8I+0jQAIAAMkiQNIYR54eakrKVj5S3rx5w102AACAeBHjbmdXr14NT0kAAACS2kjaAAAASQUBEgAAQAACJAAAgAAESAAAAKEIkE6dOmXvvPOO9e/f306ePOm2bdiwwQ4ePBib0wEAACTuXmw///yzNWzY0LJly2Z79+61zp07W86cOW3u3Lm2b98+mzFjRnhKCgAAkFBrkHr37m2PP/647dq1y9KnT+/dfs8999i3334b6vIBAAAk/ABp3bp19uSTT0baXqhQITty5EioygUAAJB4mtjSpUtnZ86cibT9v//9r+XJkydU5QKShiHZrrH/dFyVBAAQzhqk+++/31588UW7dOmSd/415R49//zz1qpVq5ieDgAAIPEHSGPGjLG//vrLzcX2999/W/369a1UqVKWJUsWGz58eIwLMHHiRCtWrJjLZ6pdu7atXbs2ymO3bt3qgjAdr8Bs/PjxkY4ZMWKE1axZ05VHZWzRooXt3LnT75g777zTvd53eeqpp2JcdgAAkDTFuIlNvdcWL15sK1eutJ9++skFS9WqVXM922Jq9uzZLul78uTJLjhSwNO4cWMX0ASbDPfcuXNWokQJa926tfXq1SvoOVesWGHdunVzQdLly5fthRdesEaNGtm2bdssU6ZM3uPU+041YR4ZM2aMcfkBAEDSFOMASd3427RpY7fddptbPC5evGizZs2ydu3aXfe5xo4d6wKVDh06uHUFSgsWLLCpU6dav379Ih2voEeLBNsvX331ld/6u+++64Kt9evX2x133OEXEOXPn/+6y3rhwgW3eATLwwIAIJhi/RZEu3/vyGZxVhaEqYlNwczp05ETS//8809voHM9FFApaPGteUqZMqVbX716tYWKp6waq8nXBx98YLlz57YKFSq4AS9VOxUdNd2p9syzFC5cOGRlBAAAibwGKSIiwuXsBDpw4IALHK7XiRMn7MqVK5YvXz6/7VrfsWOHhcLVq1ftmWeecTVdCoQ8Hn74YStatKgVLFjQDXypBHM162mwy6goiFJzoG8NEkESAADJPECqWrWqN6G5QYMGljr1/16qQGfPnj3WpEkTS0iUi7Rlyxb7/vvv/bZ36dLF+3XFihWtQIEC7p52795tJUuWjHJ4Ay0AACDpu+4ASb3BZNOmTS6ROnPmzN59adOmdT3LYtLNX81bqVKlsqNHj/pt13pMcoOi0r17d5s/f74b3fumm26K9lgliMsvv/wSZYAEAACSj+sOkAYPHuz+VyCkJG3faUZiQ0FV9erVbenSpd7gS01iWldwE1tqAuzRo4d9+umntnz5citevPg1X6Og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ACRlMQ6Q5NSpU64Lvac3W/ny5a1jx44xHkkbAAAgSczFpi71JUuWtHHjxtnJkyfdouk5tG3Dhg3hKSUAAEBCrkFSd3glaL/99tve6UY0AvUTTzzhBm/89ttvw1FOAACAhBsgqQbJNzhyJ0md2p577jk32CMAAECya2LTOEcavDHQ/v373ajUAAAAya4GSSNfd+rUyUaPHu1GtZaVK1da3759g45aDQBAxekVo92/uf3mOCsLEJYASYGRBoTUHGnKPZI0adJY165dbeTIkTE9HQAAQOIPkNKmTWuvvfaamzx29+7dbpt6sGXMmDEc5QMAAEgc4yCJAqLs2bN7vwYAAEi2SdpqVhs4cKAbFLJYsWJu0dcDBgywS5cuhaeUAAAACbkGqUePHjZ37lx79dVXrU6dOm7b6tWrbciQIfb777/bpEmTwlFOADeIJFkACGOANHPmTJs1a5Y1bdrUu61SpUpWuHBh14uNAAkAACS7JrZ06dK5ZrVAxYsXdwncAAAAyS5A6t69uw0bNswuXLjg3aavhw8f7vYBAAAkuya2jRs32tKlS+2mm26yypUru20//fSTXbx40Ro0aGAtW7b0HqtcJQAAgCQfIKlrf6tWrfy2Kf8IAAAg2QZI06ZNC09JAAAAEvtAkcePH7edO3e6r8uUKWN58uQJZbkAAAAST5L22bNnrWPHjlagQAG744473FKwYEE3ge25c+fCU0oAAICEHCD17t3bVqxYYV988YWdOnXKLZ999pnb1qdPn/CUEgAAICE3sX3yySf28ccf25133undds8991iGDBnswQcfZKBIIKkbki36/cWLxFVJACDh1CCpGS1fvnyRtufNm5cmNgAAkDwDJM2/NnjwYDt//rx3299//21Dhw71zs0GAACQrJrYxo8fb02aNIk0UGT69Olt0aJF4SgjAABAwg6QKlasaLt27bIPPvjAduzY4bZpktpHHnnE5SEBAAAkqwDp0qVLVrZsWZs/f7517tw5fKUCAABILAFSmjRp/HKPgDjtHTXkdFyVBACQzMU4Sbtbt272yiuv2OXLl8NTIgAAgMSWg7Ru3TpbunSpff311y4fKVOmTH77586dG+NCTJw40UaNGmVHjhxxid9vvPGG1apVK8rj58yZYwMHDrS9e/da6dKlXcCmsZg8Hn/8cZs+fbrfaxo3bmxfffWVd/3kyZPW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Bke7du2yZcuWuTyja9m0aZPLf8qbN29I7g0AYvXXe/EicVUSAAm5iU3NVu3bt7caNWpYrVq1bPz48Xb27FnXq000hlGhQoVc05f07NnT6tevb2PGjLFmzZrZrFmz7Mcff7S33nrLGxz985//dF3858+f73KcPPlJyjdSUKaE7h9++MHuuusu15NN67169bJHH33UcuTIEY/vBgAASAjiPUBq06aNHT9+3AYNGuQCmSpVqthXX33lTcRW13zV7HjUrVvXZs6caQMGDLAXXnjBSpcubfPmzbMKFSq4/QcPHrTPP//cfa1z+VJt0p133umayhRYDRkyxPVOK168uAuQfHOMACQA1LYgFipOrxjt/s3tN8dZWZB4xXuAJGpOi6pJbfny5ZG2tW7d2i3BaIRsJWVHR73X1qxZE8vSAgCApC7eB4oEAABIaBJEDRIAhFuxfgui3b93ZLM4KwuAhI8aJAAAgAAESAAAAAEIkAAAAAIQIAEAAAQgQAIAAAhAgAQAABCAAAkAACAA4yABgDCtCQAf1CABAAAEIEACAAAIQIAEAAAQgAAJAAAgAAESAABAAHqxAYg3xfotiHb/3vRxVhQA8EMNEgAAQAACJAAAgAA0sQEAEAsVp1eMdv/m9pvjrCwIPWqQAAAAAhAgAQAABKCJDQhAtTkAgBokAACAAARIAAAAAQiQAAAAAhAgAQAABCBJGwCABI7OI3GPGiQAAIAABEgAAAABCJAAAAACECABAAAkxABp4sSJVqxYMUufPr3Vrl3b1q5dG+3xc+bMsbJly7rjK1asaF9++aXf/oiICBs0aJAVKFDAMmTIYA0bNrRdu3b5HXPy5El75JFHLGvWrJY9e3br1KmT/fXXX2G5P4QuSTG6BQCAJBMgzZ4923r37m2DBw+2DRs2WOXKla1x48Z27NixoMevWrXK2rZt6wKajRs3WosWLdyyZcsW7zGvvvqqvf766zZ58mT74YcfLFOmTO6c58+f9x6j4Gjr1q22ePFimz9/vn377bfWpUuXOLlnAACQsMV7N/+xY8da586drUOHDm5dQc2CBQts6tSp1q9fv0jHv/baa9akSRPr27evWx82bJgLciZMmOBeq9qj8ePH24ABA6x58+bumBkzZli+fPls3rx59tBDD9n27dvtq6++snXr1lmNGjXcMW+88Ybdc889Nnr0aCtYsGCc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4YcfRmr26tGjh2v6ypEjh+XLl8/efvttO3v2rJvRPkuWLG5G8YULF0aqqVq0aJFVrVrVMmTIYHfffbcdO3bMHVeuXDnLmjWrPfzww3bu3Lkom9iKFStmL7/8snXs2NFdR7OMv/XWW37lW7VqlatpSZ8+vdWoUcM1denampk8mAkTJliFChW8657jJ0+e7N3WsGFDGzBggHf9s88+s2rVqrlrlChRws2qfvny5Sib2K63TOvXr3f79d7XrVvXdu7c6ba/++677ho//fSTe50WbQMQGQESgJA7f/68Va9e3RYsWGBbtmyxLl262GOPPWZr1671O2769OmWO3dut13BUteuXa1169buob5hwwZr1KiRe51vsONpJlJAooBh//799uCDD9r48eNt5syZ7ppff/21vfHGG9GWccyYMS6I2Lhxo/3rX/9y1/YEEmfOnLH77rvPBXYqh5rnnn/++WjPV79+fdu2bZsdP37cra9YscLdm4I6uXTpkq1evdoFa/Ldd99Zu3btrGfPnu51//nPf1ywMnz48KDnj0mZ/v3vf7v7+/HHHy116tQuEJQ2bdpYnz59rHz58q75Tou2AQgiAgCuU/v27SNSpUoVkSlTJr8lffr0Efo4+eOPP6J8bbNmzSL69OnjXa9fv35EvXr1vOuXL19253rssce82w4fPuzOu3r1are+bNkyt75kyRLvMSNGjHDbdu/e7d325JNPRjRu3NjvWj179vSuFy1aNOLRRx/1rl+9ejUib968EZMmTXLr+j9XrlwRf//9t/eYt99+211n48aNQe9P59Br5syZ49arVKniypY/f363/v3330ekSZMm4uzZs269QYMGES+//LLfOd57772IAgUKeNd1vU8//fS6yxTs/VmwYIHb5nnd4MGDIypXrhz0HgD8DzVIAGLkrrvuck06vss777zjd8yVK1dcDYdqO5T/kzlzZtcstm/fPr/jKlWq5P06VapUlitXLvcaDzW7iZrQonqdjlFTkpqofLcFviaQ7znU1KR8H89rVJOk/WrK8qhVq1a059M57rjjDldjpGR11QqpZurChQu2Y8cOV6NUs2ZNV1ZRM9eLL77o3hvP0rlzZ1erE1hjFtMy+d5bgQIF3P/Xej8A+CNJG0CMZMqUyeUG+Tpw4IDf+qhRo+y1115zzV4KePQa5QBdvHjR77g0adJECjJ8t2ldrl69GuXrAl/j2Rb4mkCxec21qPlMuUxqPlOOlPKhPEGTAiQ1w3n89ddfLh+oZcuWkc7jGwTFxvW8hwCiRw0SgJBbuXKlNW/e3B599FGrXLmyq93573//a4lFmTJlbPPmza72x2PdunXXfJ0nD2nOnDneXCP9v2TJEveeeLaJkrNVK6RgM3BJmTJlyMoUKG3atK6GD0D0CJAAhFzp0qVt8eLFLol6+/bt9uSTT9rRo0ctsVAvONW4KLlc5Vfz4OjRo/1qZKJq2lKPPCWL+wZI6m2mwOa2227zHjto0CCbMWOGq0XaunWru86sWbP8ermFokyB1INvz549rmn0xIkTfgEXgP8hQAIQcnrIq4akcePGLkBQfk+wASYTKjWNffHFFy6IULd69QpTQHOt5i8FKrfffrv7v169et6gSedTjzk1NXrovZk/f77rcafcpFtvvdXGjRtnRYsWDWmZArVq1cqaNGnicsny5MkTafgFAP8nhTK1///XAIAofPDBB258ptOnT7vxlxKChFgmIKkgSRsAglDzl3KnNNilepxpzCGNtxSfgUhCLBOQVBEgAUAQR44ccU1Y+l9d5TWAZVSDOCbnMgFJFU1sAAAAAUjSBgAACECABAAAEIAACQAAIAABEgAAQAACJAAAgAAESAAAAAEIkAAAAAIQIAEAAJi//wcBdIMkPyMB4QAAAABJRU5ErkJggg==",
      "text/plain": [
       "<Figure size 640x480 with 1 Axes>"
      ]
     },
     "metadata": {},
     "output_type": "display_data"
    }
   ],
   "source": [
    "N = 1000 #network size\n",
    "n = 4   #constant in-degree\n",
    "\n",
    "bn1 = bf.random_network(N=N,n=n,bias=0.75)\n",
    "bn2 = bf.random_network(N=N,n=n,absolute_bias=0.5,use_absolute_bias=True)\n",
    "bn3 = bf.random_network(N=N,n=n,absolute_bias=0.5)\n",
    "bns = [bn1,bn2,bn3]\n",
    "\n",
    "labels = [\"bias = 0.75\", \"absolute bias = 0.5\", \"bias = 0.5 (balanced)\"]\n",
    "possible_hamming_weights = np.arange(2**n + 1)\n",
    "width = 0.3\n",
    "\n",
    "fig, ax = plt.subplots()\n",
    "for i,bn in enumerate(bns):\n",
    "    count = np.zeros(2**n + 1)\n",
    "    for f in bn.F:\n",
    "        count[f.hamming_weight] += 1\n",
    "    ax.bar(possible_hamming_weights - width + i * width, \n",
    "           count / N, \n",
    "           width=width, label=labels[i])\n",
    "\n",
    "ax.legend(frameon=False)\n",
    "ax.set_xticks(possible_hamming_weights)\n",
    "ax.set_xlabel(\"Hamming weight\")\n",
    "ax.set_ylabel(\"Proportion of update functions\");"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1288604",
   "metadata": {},
   "source": [
    "## Summary\n",
    "\n",
    "In this tutorial you learned how to:\n",
    "\n",
    "- generate random wiring diagrams with prescribed structural constraints,\n",
    "- generate, for each node in a wiring diagram, random update functions \n",
    "  with prescribed functional constraints.\n",
    "\n",
    "In the next tutorial, we will explore several situations, in which the ability\n",
    "to generate large ensembles of controlled random Boolean networks is very useful. "
   ]
  }
 ],
 "metadata": {
  "jupytext": {
   "cell_metadata_filter": "-all",
   "main_language": "python",
   "notebook_metadata_filter": "-all"
  },
  "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.12.3"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}