SBOL-utilities

SBOL-utilities is a collection of scripts and functions for manipulating SBOL 3 data that can be run from the command line or as functions in Python. Additional documentation is online at readthedocs.io.

Installation

SBOL utilities requires Python 3.7+.

To install the package and all dependences, run:

pip3 install sbol-utilities

Certain utilities also have non-Python dependencies, which must be installed separately:

• graph-sbol requires Graphviz to be able to render diagrams.
• sbol-converter requires node.js to be able to locally run Javascript.

🔗 Mapping: Command-Line Tools to Python Modules

This table provides a quick reference to help developers understand where each command-line utility is implemented within the Python package.

Command-line Tool	Python Module	Entry Point Function
excel-to-sbol	sbol_utilities.excel_to_sbol	main
graph-sbol	sbol_utilities.graph_sbol	main
sbol-expand-derivations	sbol_utilities.expand_combinatorial_derivations	main
sbol-calculate-sequences	sbol_utilities.calculate_sequences	main
sbol-calculate-complexity	sbol_utilities.calculate_complexity_scores	main
sbol-converter	sbol_utilities.conversion	main
sbol2-to-sbol3	sbol_utilities.conversion	sbol2to3
sbol3-to-sbol2	sbol_utilities.conversion	sbol3to2
sbol-to-genbank	sbol_utilities.conversion	sbol2genbank
genbank-to-sbol	sbol_utilities.conversion	genbank2sbol
sbol-to-fasta	sbol_utilities.conversion	sbol2fasta
fasta-to-sbol	sbol_utilities.conversion	fasta2sbol
sbol-diff	sbol_utilities.sbol_diff	main

Utilities

Graph SBOL Documents

The graph_sbol utility uses graphviz to render the object tree in an sbol Document. In addition it will write PDF and Graphviz source files.

To use in context of an application:

import sbol3
from sbol_utilities.graph_sbol import graph_sbol

doc = sbol3.Document()
doc.read('my_file.ttl')
graph_sbol(doc)

To run as a commandline executable:

graph-sbol -i my_file.ttl

Convert an Excel template file to SBOL

The excel-to-sbol utility reads an Excel file specifying a library of basic and composite parts, formatted following sbol_library_template.xlsx.

Convert beween SBOL3 and other genetic design formats

The sbol-converter utility converts between any of the SBOL3, SBOL2, GenBank, and FASTA formats.

Additional “macro” utilities convert specifically between SBOL3 and one of the other formats:

• sbol-to-fasta and fasta-to-sbol convert from SBOL3 to FASTA and vice versa
• sbol-to-genbank and genbank-to-sbol convert from SBOL3 to GenBank and vice versa
• sbol3-to-sbol2 and sbol2-to-sbol3 convert to and from SBOL2

Details on contributing to the SBOL2-SBOL3 converter can be found here.

Expand the combinatorial derivations in an SBOL file

The sbol-expand-derivations utility searches through an SBOL file for CombinatorialDerivation objects and expands them to create a library of all of the specific constructs.

Calculate sequences of DNA components in an SBOL file

The sbol-calculate-sequences utility attempts to calculate the sequence of any DNA Component that can be fully specified from the sequences of its sub-components.

Calculate sequence synthesis complexity for DNA sequences in an SBOL file

The sbol-calculate-complexity utility attempts to calculate the synthesis complexity of any DNA sequence in the file, by sending sequences to be evaluated by IDT’s sequence calculator service. Sequences whose complexity is known are not re-calculated.

The system uses the gBlock API, which is intended for sequences from 125 to 3000 bp in length. If it is more than 3000 bp or less than 125 bp your returned score will be 0. A complexity score in the range from 0 to 10 means your sequence is synthesizable, if the score is greater or equal than 10 means it is not synthesizable.

Note that use of this utility requires an account with IDT that is set up to use IDT’s online service API (see: https://www.idtdna.com/pages/tools/apidoc)

Compute the difference between two SBOL3 documents

The sbol-diff utility computes the difference between two SBOL3 documents and reports the differences.

Contributing

We welcome contributions that patch bugs, improve existing utilities or documentation, or add new utilities! For guidance on how to contribute effectively to this project, see CONTRIBUTING.md.