{ "cells": [ { "cell_type": "markdown", "id": "ef4ac2a8", "metadata": {}, "source": [ "# Preface {-}\n", "\n", "**BoolForge** is a Python toolbox for generating, analyzing, and simulating\n", "Boolean functions and Boolean networks. Boolean network models are widely used\n", "in systems biology, theoretical biology, and complex systems research to study\n", "regulatory systems whose components operate in two qualitative states\n", "(e.g., active/inactive or ON/OFF).\n", "\n", "In gene regulatory network models, for instance, each node represents a molecular component\n", "(such as a gene, protein, or signaling molecule), and each node is updated by a\n", "Boolean function that represents the regulatory logic controlling that component.\n", "\n", "The tutorials in this document provide a structured introduction to BoolForge\n", "and demonstrate how it can be used to perform computational experiments on\n", "Boolean functions and Boolean networks.\n", "\n", "## Philosophy and scope of BoolForge\n", "\n", "BoolForge was designed to support both **methodological research on Boolean\n", "networks** and **applied analysis of biological regulatory models**.\n", "\n", "Three principles guide its design:\n", "\n", "**1. Fundamental representations**\n", "\n", "Boolean functions are stored internally as truth tables, the most fundamental\n", "representation of Boolean logic. Logical expressions and polynomial forms can\n", "be derived from this representation when needed.\n", "\n", "**2. Controlled random model generation**\n", "\n", "Many research questions require comparing biological networks with suitable\n", "**null models**. BoolForge therefore provides various tools for generating random\n", "Boolean functions and Boolean networks with prescribed structural properties.\n", "\n", "**3. Integration of structure and dynamics**\n", "\n", "Structural properties of regulatory rules (such as canalization, redundancy,\n", "and symmetry) influence dynamical behavior, including attractors, robustness,\n", "and sensitivity to perturbations. BoolForge enables analysis across these levels,\n", "connecting function-level structure to network-level dynamics.\n", "\n", "**Together, these capabilities enable ensemble-based exploration of the\n", "relationship between structure and dynamics in Boolean networks.**\n", "\n", "For example, we can reproduce, in a few lines of code, the classical phase transition \n", "from order to chaos in random Boolean networks predicted by the annealed approximation of\n", "[Derrida and Pomeau (1986)](https://hal.science/hal-03285912/document)." ] }, { "cell_type": "code", "execution_count": 1, "id": "d76c713b", "metadata": { "execution": { "iopub.execute_input": "2026-03-14T05:09:01.908060Z", "iopub.status.busy": "2026-03-14T05:09:01.907677Z", "iopub.status.idle": "2026-03-14T05:09:03.831434Z", "shell.execute_reply": "2026-03-14T05:09:03.831160Z" } }, "outputs": [ { "data": { "image/png": "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HVKBwY0bN1TPivRQyb7S6yPDM9ImCZgMJceW88tMJzm2sXqH8iKBpAx3zZo1Sz2X8+bNyzX8JST4W7p0qeoFOnr0qHq+5TG+++67+qGm2rVrY+jQoeo5keEy3W0SRBZEjjljxgz1XJ08eRKHDx/Gt99+i9mzZ6vb5W9YoUIFNfNr+/btOHv2rApmpN0XL14s9PHJ45JjdO7c2a5KJJB9YwBEVArJFGwJajp16oTXX38dISEh6gNYiiAuWLBA/6Er07YlX+eBBx5QAZHcT3oSikp6G7Zt24bu3burae3ygS5DWTKdWkjOivR8SEAlQzHyof/444/j1VdfxZgxY9RUd+kRkmnwhnrjjTfUEJD0WMixJagylfvvv18NQcm0e8l7kuE+XfCiI71uv/zyi7pN8qfkPp9++qm+R0naKtPdZbhKbh8+fLi+F6ywITLZV6bBS9AjQasEqTItXzfMKFPz5e8g0/RlCE4CUMkZkhygovYISVtlGr0EQRJkEZV2DpIJbelGEBHZIwkIpS6QJDBL7xARmQ8DICIiM5GhPsm3kWFACXrGjh2reuB27Nhh6aYR2R0mQRMRmYlUspYq2DJcJzk7Mux49+w3IjIP9gARERGR3WESNBEREdkdBkBERERkdxgAERERkd1hAERERER2hwEQERER2R0GQERERGR3GAARERGR3WEARERERLA3/wfIDswRahud9QAAAABJRU5ErkJggg==", "text/plain": [ "
" ] }, "metadata": {}, "output_type": "display_data" } ], "source": [ "import boolforge as bf\n", "import matplotlib.pyplot as plt\n", "\n", "N = 100 # network size\n", "ks = range(1,5) # constant in-degree\n", "n_networks = 50 # ensemble size\n", "p = 0.5 # bias p: probability of ones in truth table\n", "\n", "derrida_values = []\n", "for k in ks:\n", " derrida_values.append([])\n", " for _ in range(n_networks):\n", " bn = bf.random_network(N, k, bias = p, allow_degenerate_functions=True)\n", " derrida_values[-1].append( bn.get_derrida_value(exact=True) )\n", "\n", "plt.boxplot(derrida_values, positions=list(ks))\n", "plt.axhline(1, linestyle=\"--\", color=\"gray\", label=\"critical value\")\n", "plt.plot(ks, [2*k*p*(1-p) for k in ks], \"o-\", label=r\"$2kp(1-p)$ (annealed theory)\")\n", "plt.xlabel(\"Constant in-degree k\")\n", "plt.ylabel(\"Derrida value\")\n", "plt.legend(frameon=False);" ] }, { "cell_type": "markdown", "id": "58b56c07", "metadata": {}, "source": [ "The Derrida value measures the average number of nodes affected by a single-bit \n", "random perturbation after one synchronous update of the network.\n", "\n", "\n", "## Structure of the tutorials\n", "\n", "The tutorials gradually introduce the main concepts and tools provided by\n", "BoolForge, moving from individual Boolean functions to full Boolean\n", "network models and their dynamical analysis.\n", "\n", "- **Boolean functions:** representation and structural analysis\n", "- **Canalization:** redundancy and robustness of regulatory rules\n", "- **Random function generation:** sampling functions with prescribed properties\n", "- **Boolean networks:** construction and wiring diagrams\n", "- **Network dynamics:** attractors and state transition graphs\n", "- **Stability and robustness:** sensitivity to perturbations\n", "- **Random network ensembles:** statistical analysis of network dynamics\n", "- **Biological models:** analysis of curated regulatory networks\n", "\n", "Each tutorial contains executable code examples illustrating how these ideas\n", "can be explored using BoolForge.\n", "Readers are encouraged to run the code cells and modify the examples to\n", "explore their own Boolean functions and networks." ] } ], "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 }