From 86380806db07ac2f3b3ebb5bd56ce9c977dfc1e0 Mon Sep 17 00:00:00 2001
From: Prashant Vaidyanathan <prash@bu.edu>
Date: Sun, 27 Oct 2024 23:49:17 +0000
Subject: [PATCH] New notebook for Sequence Annotation. Addresses #18

---
 .../SequenceAnnotation.ipynb                  | 114 ++++++++++++++++++
 1 file changed, 114 insertions(+)
 create mode 100644 examples/sbol2/CreatingSBOL2Objects/SequenceAnnotation.ipynb

diff --git a/examples/sbol2/CreatingSBOL2Objects/SequenceAnnotation.ipynb b/examples/sbol2/CreatingSBOL2Objects/SequenceAnnotation.ipynb
new file mode 100644
index 0000000..679218a
--- /dev/null
+++ b/examples/sbol2/CreatingSBOL2Objects/SequenceAnnotation.ipynb
@@ -0,0 +1,114 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# SequenceAnnotation in pySBOL2\n",
+    "\n",
+    "In this notebook, we introduce the `SequenceAnnotation` class in SBOL 2. A `SequenceAnnotation` specifies regions of interest within a sequence by marking them with a location and (optionally) a functional role. This annotation provides valuable insights into the structural and functional elements of a `ComponentDefinition`.\n",
+    "\n",
+    "\n",
+    "## Overview of SequenceAnnotation Properties\n",
+    "\n",
+    "A `SequenceAnnotation` has a few key properties that allow it to describe specific regions within a sequence:\n",
+    "\n",
+    "1. **location** (required): Defines the region within the sequence that the annotation applies to.\n",
+    "   For more details on each location type, please refer to their respective notebooks:\n",
+    "   - [Range Notebook](Range.ipynb)\n",
+    "   - [Cut Notebook](Cut.ipynb)\n",
+    "   - [GenericLocation Notebook](GenericLocation.ipynb)\n",
+    "\n",
+    "   Additionally, see the [Cre-Lox Recombination Notebook](../CreLoxRecombination.ipynb) for a practical example of `GenericLocation` in action, modeling flexible coding sequence boundaries in a recombination system.\n",
+    "\n",
+    "2. **component** (optional)\n",
+    "\n",
+    "The `component` property, if used, links the annotation to a specific `Component` in the same `ComponentDefinition`. This is helpful if you want the annotation to directly refer to a part of the design’s structure, rather than just a sequence region.\n",
+    "\n",
+    "3. **roles** (optional)\n",
+    "\n",
+    "The `roles` property is an optional list of URIs that describe the function of the annotated region (e.g., \"Promoter\" or \"Terminator\"). Using `roles` allows you to define what a sequence region *does*, without needing to associate it with a specific component. When a role is used, the sequenceAnnotation must not have a `component` property, as the annotation is describing the function on its own."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import sbol2\n",
+    "\n",
+    "# Create an SBOL document\n",
+    "doc2 = sbol2.Document()\n",
+    "\n",
+    "# Set a namespace for the document\n",
+    "sbol2.setHomespace('https://github.com/SynBioDex/SBOL-Notebooks')\n",
+    "\n",
+    "\n",
+    "sequence_elements = 'ATGCGTACGTAGCTAGTCTGATCGTAGCTAGTCGATGCAGGGC'\n",
+    "seq = sbol2.Sequence('example_sequence')\n",
+    "seq.elements = sequence_elements\n",
+    "seq.encoding = sbol2.SBOL_ENCODING_IUPAC\n",
+    "\n",
+    "\n",
+    "# Add the sequence to the document\n",
+    "doc2.addSequence(seq)\n",
+    "\n",
+    "# Create a ComponentDefinition for the sequence\n",
+    "comp_def = sbol2.ComponentDefinition('example_component', sbol2.BIOPAX_DNA)\n",
+    "comp_def.sequences = [seq.persistentIdentity]\n",
+    "\n",
+    "# Add the ComponentDefinition to the document\n",
+    "doc2.addComponentDefinition(comp_def)\n",
+    "\n",
+    "\n",
+    "# Create a SequenceAnnotation for a promoter region with the SO term for \"Promoter\"\n",
+    "annotation = sbol2.SequenceAnnotation(\"promoter_annotation\")\n",
+    "annotation.roles = [sbol2.SO_PROMOTER]  # SO term for Promoter\n",
+    "annotation.locations.add(sbol2.Range(\"location1\", 1, 20))  # Define the range for the promoter\n",
+    "comp_def.sequenceAnnotations.add(annotation)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Check if the SBOL document is valid\n",
+    "doc2.validate()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Save the SBOL document to a file\n",
+    "doc2.write(\"sequence_annotation_example.xml\")"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "sbol_env",
+   "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.11.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}