pySBOL3

https://github.com/synbiodex/pysbol3
Admin
pySBOL3 is a Python implementation of the SBOL 3 specification for synthetic biology, enabling...
Tokens:23,341
Snippets:243
Trust Score:9.5
License:MIT
Update:6 months ago
Show doc for...
Tokens:
Raw
### Install TYTO

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/ontology.md

Install the TYTO module using pip, Python's package installer.

```shell
pip install tyto
```

--------------------------------

### Install pySBOL3 from source

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/installation.md

Install the package locally using the setup.py file after navigating to the directory.

```default
$ cd pysbol3
$ python3 -m pip install .
```

--------------------------------

### Initialize and Load SBOL3 Document

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Setup the environment and load an SBOL3 document from a file path.

```python
import sbol3

import os
import glob
import pathlib
```

```python
doc = sbol3.Document()
```

```python
doc.read(pathlib.Path.cwd().parent / 'test' / 'resources' / 'simple_library.nt')
```

--------------------------------

### Install pySBOL3 from GitHub

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/installation.md

Install the latest development version directly from the source repository.

```default
python3 -m pip install git+https://github.com/synbiodex/pysbol3
```

--------------------------------

### Install pySBOL3 with user permissions

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/installation.md

Use this command if you encounter permission errors during standard installation.

```default
pip install --user sbol3
```

--------------------------------

### Install SBOL Utilities

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Install the SBOL Utilities package using pip. This command also installs its dependencies, pySBOL3 and tyto.

```bash
pip install sbol_utilities
```

--------------------------------

### Install pySBOL3 as super-user

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/installation.md

Alternative installation method for Unix-like platforms requiring root privileges.

```default
sudo pip install sbol3
```

--------------------------------

### Verify pySBOL3 installation

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/installation.md

Test the installation by importing the library in a Python interpreter.

```default
$ python3
Python 3.8.5 (v3.8.5:580fbb018f, Jul 20 2020, 12:11:27)
[Clang 6.0 (clang-600.0.57)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> import sbol3
RDFLib Version: 5.0.0
```

--------------------------------

### Create System Representation

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Initializes a system representation using functional_component and adds it to the document. Use this to start building a new system.

```python
i13504_system = functional_component('i13504_system')
doc.add(i13504_system)
```

--------------------------------

### Run pySBOL3 unit tests

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/installation.md

Execute the built-in test suite to ensure the installation is functioning correctly.

```default
$ python3 -m unittest discover -s test
```

--------------------------------

### Install pySBOL3 via pip

Source: https://github.com/synbiodex/pysbol3/blob/main/README.md

Use this command to install the pySBOL3 library in your Python environment.

```bash
pip install sbol3
```

--------------------------------

### Access Component Roles

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Retrieves and prints the roles associated with the Cas9 component. This example shows an empty list.

```python
cas9.roles
```

--------------------------------

### Validate SBOL Documents

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Shows how to validate SBOL documents and individual objects against the SBOL specification using SHACL rules. Includes examples of checking for errors and warnings.

```python
import sbol3

sbol3.set_namespace('https://example.org/validation')

# Create a document with some objects
doc = sbol3.Document()
component = sbol3.Component('test_part', sbol3.SBO_DNA)
doc.add(component)

# Validate the entire document
report = doc.validate()

# Check validation results
if len(report) == 0:
    print("Document is valid!")
else:
    print(f"Found {len(report)} issues:")

    # Access errors
    for error in report.errors:
        print(f"ERROR: {error}")

    # Access warnings
    for warning in report.warnings:
        print(f"WARNING: {warning}")

# Validate individual objects
component_report = component.validate()

# Example: Creating an invalid sequence (missing encoding)
invalid_seq = sbol3.Sequence('bad_sequence')
invalid_seq.elements = 'atgc'  # Has elements but no encoding

doc2 = sbol3.Document()
doc2.add(invalid_seq)
report2 = doc2.validate()
print(f"Validation report:
{report2}")
# Output: Sequence encoding is required if elements are set

# SHACL validation only
shacl_report = doc.validate_shacl()
```

--------------------------------

### Get File Extension for SBOL3 Format

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Retrieves the file extension for a specified SBOL3 format. For example, TURTLE format corresponds to the '.ttl' extension.

```python
# Get file extension for a format
ext = sbol3.Document.file_extension(sbol3.TURTLE)
print(f"Turtle extension: {ext}")  # .ttl
```

--------------------------------

### Create components with custom paths and namespaces

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Demonstrates creating components using local paths or explicit full URIs to override the default namespace.

```python
>>> # Include a local path in addition to a display_id
>>> second_promoter = sbol3.Component('promoters/second_promoter', sbol3.SBO_DNA)
>>>
>>> # Use a namespace different from the configured default namespace
>>> third_promoter = sbol3.Component('http://sbolstandard.org/other_namespace/third_promoter', sbol3.SBO_DNA)
```

--------------------------------

### Create and Manage SBOL Documents

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Demonstrates creating a new SBOL document, reading from and writing to files, finding objects, and managing document contents. Supports multiple RDF serialization formats.

```python
import sbol3

# Set the default namespace for new objects
sbol3.set_namespace('https://example.org/my_designs')

# Create a new empty document
doc = sbol3.Document()

# Read an existing SBOL file (supports .nt, .ttl, .xml, .json formats)
doc.read('library.nt')

# Check document contents
print(f"Document contains {len(doc)} objects")
print(doc)  # Displays summary of object types and counts
# Output:
# Component.....................15
# Sequence......................12
# Collection....................3
# ---
# Total: .......................30

# Iterate over all objects in the document
for obj in doc.objects:
    print(f"{obj.display_id}: {obj.identity}")

# Find objects by identity URI or display_id
promoter = doc.find('pTetR')  # Find by display_id
promoter = doc.find('https://example.org/my_designs/pTetR')  # Find by full URI

# Write document to file (format inferred from extension)
doc.write('output.nt')  # N-Triples format
doc.write('output.ttl')  # Turtle format
doc.write('output.xml')  # RDF/XML format

# Write with explicit format specification
doc.write('output.nt', sbol3.SORTED_NTRIPLES)

# Get document as string
nt_string = doc.write_string(sbol3.NTRIPLES)

# Copy a document
doc_copy = doc.copy()

# Clear all objects from document
doc.clear()
```

--------------------------------

### Instantiate and Populate Extension Objects

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/extensions.md

Demonstrates creating an instance of the custom Analysis class and assigning a DataSheet object to it.

```python
>>> doc = sbol3.Document()
>>> a = Analysis('http://example.org/sbol3/a1')
>>> doc.add(a)
>>> a.data_sheet = DataSheet()
>>> a.data_sheet.transcription_rate = 96.3
>>> a.data_sheet.transcription_rate
96.3
```

--------------------------------

### Create a Collection of Devices

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Groups multiple devices into a collection. Use the Collection class and provide a list of member components.

```python
interlab16 = doc.add(Collection('interlab16',members=[device1, device2]))
print(f'Members are {", ".join(m.lookup().display_id for m in interlab16.members)}')
```

--------------------------------

### File I/O and Format Conversion

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Shows how to write SBOL documents to various RDF serialization formats and how to use explicit format constants.

```python
import sbol3

sbol3.set_namespace('https://example.org/io')

# Create a sample document
doc = sbol3.Document()
comp = sbol3.Component('test', sbol3.SBO_DNA)
doc.add(comp)

# Write to different formats (format inferred from extension)
doc.write('output.nt')     # N-Triples
doc.write('output.ttl')    # Turtle
doc.write('output.xml')    # RDF/XML
doc.write('output.json')   # JSON-LD

# Write with explicit format
doc.write('output.rdf', sbol3.RDF_XML)
doc.write('output.sbol', sbol3.SORTED_NTRIPLES)

# Supported format constants
# sbol3.NTRIPLES - N-Triples format
# sbol3.SORTED_NTRIPLES - Sorted N-Triples (reproducible output)
```

--------------------------------

### Build source and binary distributions

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/RELEASE.md

Clean previous build artifacts and generate new distribution files.

```shell
# Remove any old builds
rm -rf dist build sbol3.egg-info

# Build source and binary distributions
python3 setup.py sdist bdist_wheel
```

--------------------------------

### Configure Combinatorial Derivation

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Set up the derivation to enumerate combinations of strains and carbon sources.

```python
carbon_source_experiment = CombinatorialDerivation("VaryCarbon", template, strategy=SBOL_ENUMERATE)
carbon_source_experiment.variable_features = [
    VariableFeature(cardinality=SBOL_ONE, variable=sample_strain, variant_collections=[interlab16]),
    VariableFeature(cardinality=SBOL_ONE, variable=sample_carbon_source, variants=[arabinose, glucose, maltose, lactose])
]
```

--------------------------------

### Access SubComponent Location Range

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Retrieve and print the start and end coordinates of a subcomponent's location range. This demonstrates how compute_sequence adds range information to features within a component.

```python
b0015_subcomponent = next(f for f in i13504.features if f.instance_of == b0015.identity)
b0015_range = b0015_subcomponent.locations[0]
print(f'Range of {b0015.display_name}: ({b0015_range.start}, {b0015_range.end})')
```

--------------------------------

### Represent Sample Replicates

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Create Implementation objects for replicates and attach flow cytometry data files.

```python
replicate1 = doc.add(Implementation("Replicate1", built=sample1))
replicate1.attachments.append(doc.add(Attachment("Replicate1_cytometry_fcs", "https://...")))
replicate2 = doc.add(Implementation("Replicate2", built=sample1))
replicate2.attachments.append(doc.add(Attachment("Replicate2_cytometry_fcs", "https://...")))
replicate3 = doc.add(Implementation("Replicate3", built=sample1))
replicate3.attachments.append(doc.add(Attachment("Replicate3_cytometry_fcs", "https://...")))
```

--------------------------------

### Describe Experimental Sample

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Define a sample as a mixture of cells, media, and carbon sources with associated volume and mass measurements.

```python
sample1 = doc.add(functional_component("Sample1"))
add_feature(sample1, m9_media).measures.append(Measure(200, tyto.OM.microliter, types=tyto.SBO.volume))
add_feature(sample1, device1_ecoli).measures.append(Measure(10000, tyto.OM.count, types=tyto.SBO.number_of_entity_pool_constituents))
add_feature(sample1, ed_simple_chemical(pubchem_glucose)).measures.append(Measure(2.5, tyto.OM.milligram, types=tyto.SBO.mass_of_an_entity_pool))
```

--------------------------------

### Copy Objects and Documents

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Illustrates how to copy entire SBOL documents or individual objects, including changing namespaces and copying into existing documents.

```python
import sbol3

sbol3.set_namespace('https://example.org/original')

# Create original document with objects
doc1 = sbol3.Document()
comp1 = sbol3.Component('part1', sbol3.SBO_DNA)
seq1 = sbol3.Sequence('seq1', elements='atgc', encoding=sbol3.IUPAC_DNA_ENCODING)
comp1.sequences = [seq1]
doc1.add([comp1, seq1])

# Copy entire document
doc2 = doc1.copy()

# Copy objects to a new namespace
new_objects = sbol3.copy(
    doc1,
    into_namespace='https://example.org/newnamespace'
)
for obj in new_objects:
    print(f"New identity: {obj.identity}")
# Output: https://example.org/newnamespace/part1
#         https://example.org/newnamespace/seq1

# Copy objects into an existing document with new namespace
target_doc = sbol3.Document()
sbol3.copy(
    [comp1, seq1],
    into_namespace='https://example.org/target',
    into_document=target_doc
)
print(f"Target doc has {len(target_doc)} objects")

# Clone individual objects
comp_clone = comp1.clone()
```

--------------------------------

### Import SBOL3 and Utilities Modules

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Import necessary modules from the sbol3 and sbol_utilities packages for working with the SBOL3 data model.

```python
from sbol3 import *
from sbol_utilities.calculate_sequences import compute_sequence
from sbol_utilities.component import *
from sbol_utilities.helper_functions import url_to_identity
import tyto
```

--------------------------------

### Configure Default Namespace

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Set the default namespace to simplify object creation and ensure SBOL compliance.

```python
>>> sbol3.set_namespace('http://sbolstandard.org/testfiles')
```

--------------------------------

### Organize Objects into Collections

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Groups TopLevel objects into Collections and Experiments, and demonstrates how to resolve member references.

```python
import sbol3

sbol3.set_namespace('https://example.org/library')

# Create several promoters
ptet = sbol3.Component('pTetR', sbol3.SBO_DNA, roles=[sbol3.SO_PROMOTER])
plac = sbol3.Component('pLac', sbol3.SBO_DNA, roles=[sbol3.SO_PROMOTER])
pbad = sbol3.Component('pBAD', sbol3.SBO_DNA, roles=[sbol3.SO_PROMOTER])

# Create a collection of promoters
promoter_library = sbol3.Collection('PromoterLibrary')
promoter_library.name = 'Standard Promoter Library'
promoter_library.description = 'Collection of characterized promoters'
promoter_library.members = [ptet, plac, pbad]

# Create RBS collection
rbs1 = sbol3.Component('RBS1', sbol3.SBO_DNA, roles=[sbol3.SO_RBS])
rbs2 = sbol3.Component('RBS2', sbol3.SBO_DNA, roles=[sbol3.SO_RBS])

rbs_library = sbol3.Collection('RBSLibrary')
rbs_library.members = [rbs1, rbs2]

# Create an Experiment collection for experimental data
experiment = sbol3.Experiment('GFP_characterization')
experiment.name = 'GFP Expression Characterization'
# experiment.members would reference ExperimentalData objects

# Add to document
doc = sbol3.Document()
doc.add([ptet, plac, pbad, rbs1, rbs2])
doc.add([promoter_library, rbs_library, experiment])

# Access collection members
for member_ref in promoter_library.members:
    member = member_ref.lookup()  # Resolve reference to actual object
    print(f"Member: {member.display_id}")
```

--------------------------------

### Visitor Pattern Implementation

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/visitor.md

Demonstrates how to implement and use a visitor to traverse a PySBOL3 document object graph.

```APIDOC
## Visitor Pattern Implementation Example

### Description
This example shows how to define a custom visitor class and use it to traverse a SBOL3 document. The visitor is responsible for directing the traversal by calling the `accept` method on child objects.

### Method
N/A (Illustrative Code)

### Endpoint
N/A (Local Code Execution)

### Parameters
N/A

### Request Example
```python
import sbol3


class MyVisitor:

    def visit_component(self, c: sbol3.Component):
        print(f'Component {c.identity}')
        for f in c.features:
            f.accept(self)

    def visit_sequence(self, s: sbol3.Component):
        print(f'Sequence {s.identity}')

    def visit_sub_component(self, sc: sbol3.Component):
        print(f'SubComponent {sc.identity}')


doc = sbol3.Document()
doc.read('test/SBOLTestSuite/SBOL3/BBa_F2620_PoPSReceiver/BBa_F2620_PoPSReceiver.ttl')
visitor = MyVisitor()
for obj in doc.objects:
    obj.accept(visitor)
```

### Response
N/A (Console Output)

#### Success Response (200)
N/A

#### Response Example
```
Component http://example.com/BBa_F2620_PoPSReceiver/BBa_F2620_PoPSReceiver
Component http://example.com/BBa_F2620_PoPSReceiver/BBa_F2620_PoPSReceiver_part1
Sequence http://example.com/BBa_F2620_PoPSReceiver/BBa_F2620_PoPSReceiver_part1_seq
```
```

--------------------------------

### Define Media Recipe

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Create a media recipe using a map of ingredients to Measure objects and add it to the document.

```python
m9_minimal_media_recipe = {
    LocalSubComponent(SBO_FUNCTIONAL_ENTITY, name="M9 salts"): (20, tyto.OM.milliliter),
    ed_simple_chemical(pubchem_water): (78, tyto.OM.milliliter),
    ed_simple_chemical(pubchem_glucose): (2, tyto.OM.milliliter),
    ed_simple_chemical(pubchem_MgSO4): (200, tyto.OM.microliter),
    ed_simple_chemical(pubchem_CaCl2): (10, tyto.OM.microliter)
}
m9_media = doc.add(media("M9_media", m9_minimal_media_recipe))
```

--------------------------------

### Order Components in a Device

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Orders components within a device, linking promoters to system subcomponents. Use the order function to define the sequence.

```python
device1 = doc.add(functional_component('interlab16device1'))
device1_i13504_system = add_feature(device1, SubComponent(i13504_system))
order(J23101, ComponentReference(device1_i13504_system, i13504_subcomponent), device1)
device2 = doc.add(functional_component('interlab16device2'))
device2_i13504_system = add_feature(device2, SubComponent(i13504_system))
order(J23106, ComponentReference(device2_i13504_system, i13504_subcomponent), device2)
print(f'Device 1 second subcomponent points to {device1.constraints[0].object.lookup().refers_to.lookup().instance_of}')
```

--------------------------------

### Define an SBOL3 Extension Class in Python

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/extensions.md

Illustrates how to create a custom extension class by inheriting from a core SBOL3 class (e.g., sbol3.Component) and adding new properties. This allows for ad-hoc data model expansion.

```python
import sbol3

X_COORDINATE_URI = 'http://example.org/my_vis#x_coordinate'
Y_COORDINATE_URI = 'http://example.org/my_vis#y_coordinate'


class ComponentExtension(sbol3.Component):
    """Override sbol3.Component to add two fields
    for visual display.
    """

    def __init__(self, identity, types,
                 *, type_uri=sbol3.SBOL_COMPONENT):
        super().__init__(identity=identity, types=types, type_uri=type_uri)
        self.x_coordinate = sbol3.IntProperty(self, X_COORDINATE_URI, 0, 1,
                                              initial_value=0)
        self.y_coordinate = sbol3.IntProperty(self, Y_COORDINATE_URI, 0, 1,
                                              initial_value=0)
```

--------------------------------

### Manage Namespaces and Components

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Set a default namespace and create biological components with specific types.

```python
sbol3.set_namespace('http://sbolstandard.org/testfiles')
```

```python
cas9 = sbol3.Component('Cas9', sbol3.SBO_PROTEIN)  # Constructs a protein component
target_promoter = sbol3.Component('target_promoter', sbol3.SBO_DNA)
```

--------------------------------

### Read and Write SBOL Documents

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Initialize a Document container and perform file I/O operations using read and write methods.

```python
>>> import sbol3
>>> doc = sbol3.Document()
>>> doc.read('simple_library.nt')
>>> doc.write('simple_library_out.nt')
```

--------------------------------

### Create CombinatorialDerivation

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Demonstrates how to create a CombinatorialDerivation object, specifying a template and strategy, and assigning variable features.

```python
derivation = sbol3.CombinatorialDerivation(
    'reporter_library',
    template=template,
    strategy=sbol3.SBOL_ENUMERATE  # or SBOL_SAMPLE for random sampling
)
derivation.variable_features = [variable_promoter]

doc = sbol3.Document()
doc.add([template, promoter_placeholder, ptet, plac, pbad, derivation])
```

--------------------------------

### Handle Nested and Custom Namespaces

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Create components with nested paths or custom namespaces overriding the default.

```python
second_promoter = sbol3.Component('promoters/second_promoter', sbol3.SBO_DNA)
second_promoter.identity
```

```python
second_promoter.display_id
```

```python
third_promoter = sbol3.Component('http://sbolstandard.org/other_namespace/third_promoter', sbol3.SBO_DNA)
third_promoter.identity
```

```python
third_promoter.display_id
```

--------------------------------

### Interact with ComponentExtension

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/extensions.md

Demonstrates creating, modifying, and round-tripping a ComponentExtension object through an SBOL3 document.

```python
>>> c = ComponentExtension('http://example.org/sbol3/c1', sbol3.SBO_DNA)
>>> c.x_coordinate
0
>>> c.y_coordinate
0
>>> c.x_coordinate = 150
>>> c.y_coordinate = 100
>>>
>>> # Round trip the document
>>> doc = sbol3.Document()
>>> doc.add(c)
>>> doc2 = sbol3.Document()
>>> doc2.read_string(doc.write_string(sbol3.NTRIPLES), sbol3.NTRIPLES)
>>>
>>> # Fetch the Component out of the new document
>>> c2 = doc2.find('c1')
>>> c2.x_coordinate
150
>>> c2.y_coordinate
100
>>> type(c2).__name__
'ComponentExtension'
```

--------------------------------

### Create Circuit Component and SubComponents

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Creates a main circuit component and then creates SubComponent objects for the previously defined promoter, operator, RBS, and GFP components. The GFP SubComponent is given a specific name.

```python
# Make circuit object and add subcomponents
circuit = sbol3.Component('circuit', sbol3.SBO_DNA)
circuit.roles.append(sbol3.SO_ENGINEERED_REGION)
ptet_sc = sbol3.SubComponent(ptet)
op1_sc = sbol3.SubComponent(op1)
rbs1_sc = sbol3.SubComponent(rbs1)
gfp_sc = sbol3.SubComponent(gfp, name='gfp_name')
```

--------------------------------

### Upload packages to PyPI

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/RELEASE.md

Use twine to upload the generated distribution files to the Python Package Index.

```shell
python3 -m twine upload dist/*
```

--------------------------------

### Recover Extension Data from Document

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/extensions.md

Demonstrates loading a document from a string and highlights that extension properties must be initialized before they are accessible as object attributes.

```xml
>>> doc2 = sbol3.Document()
>>> doc2.read_string(doc.write_string(sbol3.NTRIPLES), sbol3.NTRIPLES)
>>> c1a = doc2.find('http://example.org/sbol3/c1')
>>> c1a.display_id
'c1'

# See that x_coordinate is not known
>>> c1a.x_coordinate
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
  File "/path/to/sbol3/object.py", line 35, in __getattribute__
    result = object.__getattribute__(self, name)
AttributeError: 'Component' object has no attribute 'x_coordinate'
```

--------------------------------

### Set Namespace and Initialize Document

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Set the default namespace for SBOL objects and initialize an empty SBOL Document. The igem suffix is used as the default namespace.

```python
set_namespace('https://synbiohub.org/public/igem/')
doc = Document()
```

--------------------------------

### Managing Reference Properties

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Link objects via URI references and resolve them using the lookup method.

```python
>>> gfp = sbol3.Component('GFP', sbol3.SBO_DNA)
>>> doc.add(gfp)
>>> gfp_seq = sbol3.Sequence('GFPSequence', elements='atgnnntaa', encoding=sbol3.IUPAC_DNA_ENCODING)
>>> doc.add(gfp_seq)
>>> gfp.sequences = [ gfp_seq ]
>>> print(gfp.sequences)
['http://sbolstandard.org/testfiles/GFPSequence']
>>> # Look up the sequence via the document
>>> seq2 = gfp.sequences[0].lookup()
>>> seq2 == gfp_seq
True
```

```python
>>> gfp.sequences = [ gfp_seq.identity ]
>>> print(gfp.sequences)
['http://sbolstandard.org/testfiles/GFPSequence']
>>> seq2 = gfp.sequences[0].lookup()
>>> seq2 == gfp_seq
True
```

--------------------------------

### Track Design History with Provenance

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Demonstrates how to use PROV-O classes in pySBOL3 to track the provenance of designs, including agents, plans, activities, and derivations.

```python
import sbol3
import datetime

sbol3.set_namespace('https://example.org/provenance')

# Create an agent (person or software)
designer = sbol3.Agent('alice')
designer.name = 'Alice Smith'
designer.description = 'Synthetic biology researcher'

# Create a plan (protocol or method)
assembly_protocol = sbol3.Plan('gibson_assembly')
assembly_protocol.name = 'Gibson Assembly Protocol'
assembly_protocol.description = 'Standard Gibson Assembly workflow'

# Create a component that was designed
circuit = sbol3.Component('my_circuit', sbol3.SBO_DNA)
circuit.roles = [sbol3.SO_ENGINEERED_REGION]

# Create an activity documenting when/how the circuit was created
design_activity = sbol3.Activity(
    'design_activity_001',
    start_time=datetime.datetime(2024, 1, 15, 10, 0, 0),
    end_time=datetime.datetime(2024, 1, 15, 12, 30, 0)
)

# Link agent to activity via association
association = sbol3.Association(
    agent=designer,
    plan=assembly_protocol,
    roles=['https://example.org/roles/designer']
)
design_activity.association = [association]

# Record that the circuit was generated by this activity
circuit.generated_by = [design_activity]

# Track derivation from source parts
source_promoter = sbol3.Component('source_pTetR', sbol3.SBO_DNA)
circuit.derived_from = [source_promoter]

doc = sbol3.Document()
doc.add([designer, assembly_protocol, circuit, design_activity, source_promoter])
```

--------------------------------

### Access Sequence and Document Management

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Access sequence properties and add components to an SBOL3 document.

```python
print(f"Sequence elements: {gfp_seq.elements}")
print(f"Encoding: {gfp_seq.encoding}")

# Add to document
doc = sbol3.Document()
doc.add(gfp_seq)
doc.add(promoter_seq)
doc.add(gfp)
```

--------------------------------

### Write and Inspect Document

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Save the document to a file and retrieve basic metadata about its contents.

```python
doc.write('simple_library_out.nt')
```

```python
len(doc)
```

```python
print(doc)
```

```python
for obj in doc.objects:
     print(obj.identity)
```

--------------------------------

### Tag the release in Git

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/RELEASE.md

Use these commands to tag the current main branch with a new version number.

```shell
cd <pySBOL3>
git checkout main
git tag -a v1.X -m "Release 1.X" main
git push origin --tags
```

--------------------------------

### Implement a pySBOL3 Visitor

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/visitor.md

Define a visitor class with methods like `visit_component` to handle specific object types. The visitor must manually direct traversal by calling `accept` on child objects.

```python
import sbol3


class MyVisitor:

    def visit_component(self, c: sbol3.Component):
        print(f'Component {c.identity}')
        for f in c.features:
            f.accept(self)

    def visit_sequence(self, s: sbol3.Component):
        print(f'Sequence {s.identity}')

    def visit_sub_component(self, sc: sbol3.Component):
        print(f'SubComponent {sc.identity}')


doc = sbol3.Document()
doc.read('test/SBOLTestSuite/SBOL3/BBa_F2620_PoPSReceiver/BBa_F2620_PoPSReceiver.ttl')
visitor = MyVisitor()
for obj in doc.objects:
    obj.accept(visitor)
```

--------------------------------

### Create RBS Component with Sequence

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Create a Ribosome Binding Site (RBS) component using the 'rbs' function from sbol_utilities, providing its identity, sequence, and name. The function returns the component and its sequence.

```python
b0034, b0034_seq = doc.add(rbs('B0034', sequence='aaagaggagaaa', name='RBS (Elowitz 1999)'))
```

--------------------------------

### List Supported SBOL Property Interfaces

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/extensions.md

Displays the available property interfaces for adding or retrieving extension data from an SBOL object.

```python
TextProperty
URIProperty
IntProperty
FloatProperty
DateTimeProperty
ReferencedObject
OwnedObject
```

--------------------------------

### Create and Add a DNA Component

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Construct a simple DNA component with a name and description, assign a role, and add it to the SBOL Document. The add method returns the object added.

```python
i13504 = Component('i13504', SBO_DNA)
i13504.name = 'iGEM 2016 interlab reporter'
i13504.description = 'GFP expression cassette used for 2016 iGEM interlab study'
i13504.roles.append(tyto.SO.engineered_region)
```

```python
doc.add(i13504)
```

--------------------------------

### Add Part-Subpart Hierarchy

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Establishes a part-subpart relationship within a system. Use add_feature to link existing components as subparts.

```python
i13504_subcomponent = add_feature(i13504_system, i13504)
```

--------------------------------

### Set and Access Component Description

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Sets a description for the Cas9 component and then retrieves and prints it.

```python
cas9.description = 'This is a Cas9 protein'
cas9.description
```

--------------------------------

### Set Component Roles (Initial)

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Creates a plasmid component and sets its roles to double-stranded and circular using SBO terms.

```python
plasmid = sbol3.Component('pBB1', sbol3.SBO_DNA)
plasmid.roles = [ sbol3.SO_DOUBLE_STRANDED, sbol3.SO_CIRCULAR ]
```

--------------------------------

### Create Component and Sequence Objects

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Create a DNA component for GFP and a corresponding Sequence object with specified elements and encoding.

```python
gfp = sbol3.Component('GFP', sbol3.SBO_DNA)
gfp_seq = sbol3.Sequence('GFPSequence', elements='atgnnntaa', encoding=sbol3.IUPAC_DNA_ENCODING)
```

--------------------------------

### Visit Methods Mapping

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/visitor.md

A table mapping PySBOL3 classes to their corresponding visitor methods.

```APIDOC
## Visit Methods Mapping

### Description
This table lists the PySBOL3 classes that implement the `accept` method and the corresponding `visit_` method that is invoked on a visitor object when `accept` is called on an instance of that class.

### Method
N/A

### Endpoint
N/A

### Parameters
N/A

### Request Example
N/A

### Response
#### Success Response (200)
- **Class** (string) - The name of the PySBOL3 class.
- **Visit Method** (string) - The name of the visitor method to be called.

#### Response Example
```
| Class                   | Visit Method                   |
|-------------------------|--------------------------------|
| Activity                | visit_activity                 |
| Agent                   | visit_agent                    |
| Association             | visit_association              |
| Attachment              | visit_attachment               |
| BinaryPrefix            | visit_binary_prefix            |
| Collection              | visit_collection               |
| CombinatorialDerivation | visit_combinatorial_derivation |
| Component               | visit_component                |
| ComponentReference      | visit_component_reference      |
| Constraint              | visit_constraint               |
| Cut                     | visit_cut                      |
| Document                | visit_document(self)           |
| EntireSequence          | visit_entire_sequence          |
| Experiment              | visit_experiment               |
| ExperimentalData        | visit_experimental_data        |
| ExternallyDefined       | visit_externally_defined       |
| Implementation          | visit_implementation           |
| Interaction             | visit_interaction              |
| Interface               | visit_interface                |
| LocalSubComponent       | visit_local_sub_component      |
| Measure                 | visit_measure                  |
| Model                   | visit_model                    |
| Participation           | visit_participation            |
| Plan                    | visit_plan                     |
| PrefixedUnit            | visit_prefixed_unit            |
| Range                   | visit_range                    |
| SIPrefix                | visit_si_prefix                |
| Sequence                | visit_sequence                 |
| SequenceFeature         | visit_sequence_feature         |
| SingularUnit            | visit_singular_unit            |
| SubComponent            | visit_sub_component            |
| UnitDivision            | visit_unit_division            |
| UnitExponentiation      | visit_unit_exponentiation      |
| UnitMultiplication      | visit_unit_multiplication      |
| Usage                   | visit_usage                    |
| VariableFeature         | visit_variable_feature         |
```
```

--------------------------------

### Link Provenance to Data

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Connect an Activity to an attachment to track the origin of experimental data.

```python
measure_sample_1 = doc.add(Activity("measure_sample_1", types=tyto.NCIT.flow_cytometry, usage=Usage(replicate1.identity)))
doc.find("Replicate1_cytometry_fcs").generated_by.append(measure_sample_1)
```

--------------------------------

### Clone pySBOL3 repository

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/installation.md

Download the source code including submodules for development purposes.

```default
$ git clone --recurse-submodules https://github.com/synbiodex/pysbol3.git
```

--------------------------------

### Lookup Ontology Terms with TYTO

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/ontology.md

Use the TYTO module to look up ontology terms. This is useful when you don't want to remember long URIs.

```python
>>> import tyto
RDFLib Version: 5.0.0
>>> tyto.SO.promoter
'https://identifiers.org/SO:0000167'
>>> tyto.SBO.systems_biology_representation
'https://identifiers.org/SBO:0000000'
```

--------------------------------

### Create a protein component

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Constructs a Component object representing a protein using the SBO_PROTEIN type.

```python
>>> cas9 = sbol3.Component('Cas9', sbol3.SBO_PROTEIN)
```

--------------------------------

### Define Carbon Source Components

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Create Component objects for various sugars to be used as variants in a combinatorial derivation.

```python
pubchem_arabinose = 'https://identifiers.org/pubchem.compound:5460291'
pubchem_maltose = 'https://identifiers.org/pubchem.compound:6255'
pubchem_lactose = 'https://identifiers.org/pubchem.compound:6134'

arabinose = doc.add(Component(url_to_identity(pubchem_arabinose), SBO_SIMPLE_CHEMICAL))
glucose = doc.add(Component(url_to_identity(pubchem_glucose), SBO_SIMPLE_CHEMICAL))
maltose = doc.add(Component(url_to_identity(pubchem_maltose), SBO_SIMPLE_CHEMICAL))
lactose = doc.add(Component(url_to_identity(pubchem_lactose), SBO_SIMPLE_CHEMICAL))
```

--------------------------------

### Define and Assign Extension Properties

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/extensions.md

Associates custom integer properties with an SBOL Component and serializes the result to N-Triples format.

```python
>>> import sbol3
RDFLib Version: 5.0.0
>>> c1 = sbol3.Component('http://example.org/sbol3/c1', sbol3.SBO_DNA)
>>> c1.x_coordinate = sbol3.IntProperty(c1, 'http://example.org/my_vis#x_coordinate', 0, 1)
>>> c1.y_coordinate = sbol3.IntProperty(c1, 'http://example.org/my_vis#y_coordinate', 0, 1)
>>> c1.x_coordinate = 150
>>> c1.y_coordinate = 175
>>> doc = sbol3.Document()
>>> doc.add(c1)
>>> print(doc.write_string(sbol3.SORTED_NTRIPLES).decode())

<http://example.org/sbol3/c1> <http://example.org/my_vis#x_coordinate> "150"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://example.org/sbol3/c1> <http://example.org/my_vis#y_coordinate> "175"^^<http://www.w3.org/2001/XMLSchema#integer> .
<http://example.org/sbol3/c1> <http://sbols.org/v3#displayId> "c1" .
<http://example.org/sbol3/c1> <http://sbols.org/v3#type> <https://identifiers.org/SBO:0000251> .
<http://example.org/sbol3/c1> <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://sbols.org/v3#Component> .

>>>
```

--------------------------------

### Create Combinatorial Design Template

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Define a template component with placeholders for variable features in a multi-factor experiment.

```python
template = doc.add(functional_component("SampleSpec"))
add_feature(template, m9_media).measures.append(Measure(200, tyto.OM.microliter, types=tyto.SBO.volume))
sample_strain = add_feature(template, LocalSubComponent(tyto.NCIT.Strain))
sample_strain.measures.append(Measure(10000, tyto.OM.count, types=tyto.SBO.number_of_entity_pool_constituents))
sample_carbon_source = add_feature(template, LocalSubComponent(SBO_SIMPLE_CHEMICAL))
sample_carbon_source.measures.append(Measure(2.5, tyto.OM.milligram, types=tyto.SBO.mass_of_an_entity_pool))
```

--------------------------------

### Setting Attribute Values

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Assign values to attributes using standard Python assignment syntax.

```python
>>> cas9.description = 'This is a Cas9 protein'
```

```python
>>> plasmid = sbol3.Component('pBB1', sbol3.SBO_DNA)
>>> plasmid.roles = [ sbol3.SO_DOUBLE_STRANDED, sbol3.SO_CIRCULAR ]
```

--------------------------------

### Create Promoter Components

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Defines promoter components with specific DNA sequences. Use the promoter function and add them to the document.

```python
J23101_sequence = 'tttacagctagctcagtcctaggtattatgctagc'
J23101, _ = doc.add(promoter('J23101', sequence=J23101_sequence))
J23106_sequence = 'tttacggctagctcagtcctaggtatagtgctagc'
J23106, _ = doc.add(promoter('J23106', sequence=J23106_sequence))
```

--------------------------------

### Open SBOL3 Document Directly from File

Source: https://context7.com/synbiodex/pysbol3/llms.txt

A convenience method to open and read an SBOL3 Document directly from a file path. Automatically determines the format based on the file extension.

```python
# Open file directly (convenience method)
doc4 = sbol3.Document.open('output.nt')
```

--------------------------------

### Create a Builder Function for Extension Classes

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/extensions.md

Provides a builder function that the SBOL3 parser invokes when it encounters an object of a specific type in an SBOL file. This function is essential for correctly instantiating extension classes during file I/O.

```python
def build_component_extension(*, identity, type_uri):
    """A builder function to be called by the SBOL3 parser
    when it encounters a Component in an SBOL file.
    """

    # `types` is required and not known at build time.
    # Supply a missing value to the constructor, then clear
    # the missing value before returning the built object.
    obj = ComponentExtension(identity=identity,
                             types=[sbol3.PYSBOL3_MISSING],
                             type_uri=type_uri)
    # Remove the placeholder value
    obj.clear_property(sbol3.SBOL_TYPE)
    return obj
```

--------------------------------

### Compare pySBOL3 Constants with TYTO Terms

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/ontology.md

Compare pySBOL3 constants with terms looked up using TYTO to ensure consistency. This demonstrates that both modules reference the same ontology terms.

```python
>>> import sbol3
RDFLib Version: 5.0.0
>>> import tyto
>>> sbol3.SBO_DNA == tyto.SBO.deoxyribonucleic_acid
True
>>> sbol3.SBO_RNA == tyto.SBO.ribonucleic_acid
True
>>> sbol3.SO_PROMOTER == tyto.SO.promoter
True
```

--------------------------------

### Find Component by Identity

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Finds a component in the document using its identity URI and accesses its identity.

```python
found_obj = doc.find('http://sbolstandard.org/testfiles/Cas9')
found_obj.identity
```

--------------------------------

### Iterate and Print Sequence URIs

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Iterate through the sequences associated with a component and print each sequence's URI.

```python
for seq in gfp.sequences:
    print(seq)
```

--------------------------------

### Create Terminator Component with Sequence

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/sbol_data_model.md

Create a terminator component using the 'terminator' function, providing its identity, sequence, and name. The function returns the component and its sequence.

```python
b0015_sequence = 'ccaggcatcaaataaaacgaaaggctcagtcgaaagactgggcctttcgttttatctgttgtttgtcggtgaacgctctctactagagtcacactggctcaccttcgggtgggcctttctgcgtttata'
b0015, _ = doc.add(terminator('B0015', sequence=b0015_sequence, name='double terminator'))
```

--------------------------------

### Bind Namespace Prefixes for SBOL3 Document

Source: https://context7.com/synbiodex/pysbol3/llms.txt

Assigns custom prefixes to URIs for namespaces within an SBOL3 Document. This is useful for generating cleaner, more readable output.

```python
# Bind namespace prefixes for cleaner output
doc.bind('ex', 'https://example.org/')
doc.bind('myparts', 'https://example.org/io/')
```

--------------------------------

### Find Component by Identity in Different Namespace

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Finds a component using its specific identity URI from a different namespace.

```python
found_obj = doc.find('http://sbolstandard.org/other_namespace/Cas9')
found_obj.identity
```

--------------------------------

### Copy Objects to a New Namespace with sbol3.copy

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Copies objects from a source document into a new namespace. The `into_namespace` argument specifies the target namespace for the copied objects.

```python
>>> objects = sbol3.copy(doc, into_namespace='https://example.org/foo')
>>> len(objects)
1
>>> for o in objects:
...     print(o)
... 
<Component https://example.org/foo/cd1>
```

--------------------------------

### Access Sequence Ontology Terms

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Construct and retrieve Sequence Ontology (SO) identifiers.

```python
SO_ENGINEERED_FUSION_GENE = sbol3.SO_NS + '0000288'  # Sequence Ontology term
SO_ENGINEERED_FUSION_GENE
```

--------------------------------

### Register a Component Extension Builder

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/extensions.md

Registers a builder function for a specific SBOL component URI to enable custom object instantiation.

```python
sbol3.Document.register_builder(sbol3.SBOL_COMPONENT,
                                build_component_extension)
```

--------------------------------

### Iterate and Print Circuit Features

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Iterate through the circuit's features to access and print their display ID, identity, and instance of properties.

```python
for feat in circuit.features:
    print(f'{feat.display_id}, {feat.identity}, {feat.instance_of}')
```

--------------------------------

### Constructing Ontology Term URIs in Python

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Construct URIs for ontology terms not provided as built-in constants. Ensure the 'tyto' library is imported.

```python
>>> SO_ENGINEERED_FUSION_GENE = tyto.SO.engineered_fusion_gene
>>> SO_ENGINEERED_FUSION_GENE
'https://identifiers.org/SO:0000288'
>>> SBO_DNA_REPLICATION = tyto.SBO.DNA_replication
>>> SBO_DNA_REPLICATION
'https://identifiers.org/SBO:0000204'
```

--------------------------------

### Add Components to Document

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Adds a target promoter and a Cas9 protein component to the document object.

```python
doc.add(target_promoter)
doc.add(cas9)
```

--------------------------------

### Find Target Promoter by Identity

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Finds the target promoter in the document using its identity URI and accesses its identity.

```python
found_obj = doc.find('http://sbolstandard.org/testfiles/target_promoter')
found_obj.identity
```

--------------------------------

### Inspect Document Contents

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Determine the number of objects in a document and print an inventory summary.

```python
>>> len(doc)
67
>>> print(doc)
Collection....................4
CombinatorialDerivation.......6
Component.....................33
Sequence......................24
---
Total: .........................67
```

--------------------------------

### Inspect component identity and display ID

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/getting_started.md

Displays the resulting identity URI and display_id for previously created components.

```python
>>> target_promoter.identity
'http://sbolstandard.org/testfiles/target_promoter'
>>> target_promoter.display_id
'target_promoter'
>>> second_promoter.identity
'http://sbolstandard.org/testfiles/promoters/second_promoter'
>>> second_promoter.display_id
'second_promoter'
>>> third_promoter.identity
'http://sbolstandard.org/other_namespace/third_promoter'
>>> third_promoter.display_id
'third_promoter'
```

--------------------------------

### Define Extension Properties in PySBOL3

Source: https://github.com/synbiodex/pysbol3/blob/main/docs/extensions.md

Demonstrates how to define custom integer properties for visual display on an SBOL object. These properties are associated with specific URIs and have defined ranges.

```python
>>> c1a.x_coordinate = sbol3.IntProperty(c1, 'http://example.org/my_vis#x_coordinate', 0, 1)
>>> c1a.y_coordinate = sbol3.IntProperty(c1, 'http://example.org/my_vis#y_coordinate', 0, 1)
>>> c1a.x_coordinate
150
>>> c1a.y_coordinate
175
```

--------------------------------

### Create Component with Different Namespace

Source: https://github.com/synbiodex/pysbol3/blob/main/examples/getting_started.ipynb

Creates a Cas9 component with an identity in a different namespace.

```python
cas9a = sbol3.Component('http://sbolstandard.org/other_namespace/Cas9', sbol3.SBO_PROTEIN) 
```
Tokens:
Raw