pySBOL2 MapsTo object tutorial

examples/sbol2/CreatingSBOL2Objects/MapsTo.ipynb

@@ -0,0 +1,135 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "id": "cell-001",
+   "metadata": {},
+   "source": [
+    "# MapsTo in pySBOL2\n",
+    "\n",
+    "The `MapsTo` class in the Synthetic Biology Open Language (SBOL) is used to explicitly state that two `ComponentInstance` objects, often from different levels of design hierarchy, represent the same biological entity. It is most often used when `ModuleDefinition` and `ComponentDefinition` objects are composed using `Module` and `ComponentInstance` objects.\n",
+    "\n",
+    "`MapsTo` objects define how a `ComponentInstance` in a higher-level design relates to a `ComponentInstance` in a lower-level design through identity and refinement relationships.\n",
+    "\n",
+    "`MapsTo` objects have the following required properties:\n",
+    "\n",
+    "-   `local`: Refers to the `ComponentInstance` in the higher-level design.\n",
+    "-   `remote`: Refers to the `ComponentInstance` in the lower-level design. The referenced instance must have `access=\"public\"`.\n",
+    "-   `refinement`: Specifies how to interpret the relationship between the local and remote instances using a URI. For example: `http://sbols.org/v2#useRemote`.\n",
+    "\n",
+    "This example demonstrates linking a `FunctionalComponent` in a high-level toggle switch module to one in a lower-level LacI inverter using a `MapsTo` object. We will:\n",
+    "\n",
+    "1. Define two `ModuleDefinition` objects (toggle switch and LacI inverter).\n",
+    "2. Add `FunctionalComponent` instances to both modules.\n",
+    "3. Create a `Module` to instantiate the LacI inverter inside the toggle switch.\n",
+    "4. Add a `MapsTo` to specify how the high-level LacI relates to the inverter's TF.\n",
+    "\n",
+    "For more information on the `MapsTo` class and its properties, refer to page 30 in the SBOL 2.x.x specification document."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "id": "cell-002",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sbol2"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "id": "cell-003",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "doc = sbol2.Document()\n",
+    "\n",
+    "# Set a namespace for the document\n",
+    "sbol2.setHomespace('https://github.com/SynBioDex/SBOL-Notebooks')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "cell-004",
+   "metadata": {},
+   "source": [
+    "Creating a MapsTo Object"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "id": "cell-005",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create lower-level ModuleDefinition\n",
+    "inverter_md = sbol2.ModuleDefinition('laci_inverter')\n",
+    "tf_fc = inverter_md.functionalComponents.create('TF')\n",
+    "tf_fc.definition = tf_fc\n",
+    "tf_fc.access = sbol2.SBOL_ACCESS_PUBLIC\n",
+    "tf_fc.direction = sbol2.SBOL_DIRECTION_IN_OUT\n",
+    "\n",
+    "# Create higher-level ModuleDefinition\n",
+    "toggle_md = sbol2.ModuleDefinition('toggle_switch')\n",
+    "laci_fc = toggle_md.functionalComponents.create('LacI')\n",
+    "laci_fc.definition = laci_fc\n",
+    "laci_fc.access = sbol2.SBOL_ACCESS_PRIVATE\n",
+    "laci_fc.direction = sbol2.SBOL_DIRECTION_IN_OUT\n",
+    "\n",
+    "# Create a Module instance to include the inverter\n",
+    "mod = toggle_md.modules.create('laci_inverter_instance')\n",
+    "mod.definition = inverter_md.identity\n",
+    "\n",
+    "# Create the MapsTo\n",
+    "mapping = mod.mapsTos.create('LacI_mapping')\n",
+    "mapping.local = laci_fc.identity\n",
+    "mapping.remote = tf_fc.identity\n",
+    "mapping.refinement = sbol2.SBOL_REFINEMENT_USE_REMOTE\n",
+    "\n",
+    "# Add ModuleDefinitions to the document\n",
+    "doc.addModuleDefinition(inverter_md)\n",
+    "doc.addModuleDefinition(toggle_md)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "id": "cell-006",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Validate the document\n",
+    "report = doc.validate()\n",
+    "\n",
+    "if report == \"Valid.\":\n",
+    "    doc.write(\"example_mapsto.xml\")\n",
+    "else:\n",
+    "    print(report)"
+   ]
+  }
+ ],
+ "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.13.4"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 5
+}