sboltools allows the manipulation of files describing biological systems using the Synthetic Biology Open Language (SBOL) and other related standards such as FASTA and GenBank.

1. Installation

1.1. Mac, Linux

sboltools requires node.js to be pre-installed on Unix(-like) systems such as macOS and Linux. If you have installed or used node.js before, you can check the available version using:

node --version

sboltools has been tested with node version 12, and so should work with version 12 or above. If such a version of node is not installed, it is recommended to obtain node.js via your package manager, or on Mac to install the latest LTS edition for your system from nodejs.org.

After node.js is installed, simply download sboltools and add the sbol script to an appropriate location. A two-liner:

curl -L https://github.com/sboltools/sboltools/releases/latest/download/sboltools-unix.tar.gz | tar xz
sudo cp -f sbol /usr/local/bin/

Or, manually: download sboltools-unix.zip from the Releases page. Unzip and copy the sbol file to /usr/local/bin or another directory on your PATH.

You can also omit the second step and run the sbol script in situ by specifying the path with each command.

1.2. Windows

Download sboltools-win32-x86.zip or sboltools-win32-x64.zip from the Releases page, and extract to a convenient location.

In order to use the sbol command from the command line, it is necessary to add the location to which sboltools was extracted to the system PATH. See this article for instructions on Windows 10.

2. Usage

sboltools provides the sbol(1) command, which is invoked as follows:
sbol [--input <format>] [--output <format>]
        [--nonsbol-conversion-target <format>]
            [url|filename] [url2|filename2] ...
                [action1] [action1args]
                [action2] [action2args]
                ...

The most simple use case is to specify a filename or URL without any actions, in which case a summary of the resource (a list of its components, etc.) will be displayed. For example:

sbol toggleswitch.xml

or

sbol https://synbiohub.org/public/Togglecomponents/part_pIKE_Toggle_1/1

Any number of actions, with their parameter(s), may be specified following a filename or URL. For example:

sbol toggle.fasta
    annotate-range --start 1 --end 50 --role promoter --name pTet

Multiple filenames or URLs may also be specified. Each is imported into the same RDF knowledge graph, and can be followed by actions with arguments. For example:

sbol lacI_inverter.xml tetR_inverter_genbank.gbf
            add-interaction
                --participant lacI
                --participant pLac 
                --type repression

2.1. Formats and Conversion

Conversion between formats is supported on multiple levels:

  • Input conversion, where non-SBOL formats (FASTA/GenBank) are converted to SBOL1/SBOL2/SBOL3 before being added to the graph using the import action
  • SBOL-SBOL conversion actions, where SBOL of one version in a knowledge graph is converted to SBOL of another version, using the convert or vc-convert actions
  • Output conversion, where the knowledge graph is converted to FASTA/GenBank/SBOL1/SBOL2/SBOL3 before output, using the --output global option to sboltools

1.1.2. Input conversion

Data are loaded into the graph using the import action.

If the filename or URL passed to the import action is RDF (e.g. an SBOL file), it is imported as-is and no conversion takes place.

If the filename or URL passed to the import action is FASTA or GenBank, it is converted to the version of SBOL specified by the --as parameter before being added to the graph. For example:

sbol import --as sbol2 toggle.genbank

would load toggle.genbank into the knowledge graph as SBOL2.

1.1.3. SBOL-SBOL conversion with actions

SBOL-SBOL conversion is implemented via the convert and vc-convert actions. For example,

sbol import toggle.xml
    convert --target sbol3

would load the file toggle.xml into the knowledge graph, convert it to SBOL3, and print a summary.

1.1.4. Output conversion

The supported output formats are: fasta, genbank, sbol1, sbol2, sbol3

For SBOL formats, an RDF serialization may also be specified. For example,

--output sbol2 --serialization xml

would output SBOL2 RDF serialized as XML, while

--output sbol2 --serialization turtle

would output SBOL3 RDF serialized as Turtle.

The supported RDF encodings are: xml, turtle, n3

2.2. Identities

As SBOL is an RDF data model, URIs are used for the identity of objects. Such URIs are impractical to use on the command line. Therefore, sboltools supports two different notations for the identity of objects:

  1. Explicit URIs, e.g. "http://example.com/toggleSwitch/lacI_inverter/pLac"
  2. Identity chains: a chain of displayIds prefixed with and delimited by a : character. For example, :toggleSwitch:lacI_inverter:pLac

Where <identity> is specified as an action parameter, the following combinations of options are accepted for identifying top-level objects (e.g. an SBOL1 DnaComponent, an SBOL2 ComponentDefinition, or an SBOL3 Component):

  • --identity <uri|identity-chain>
  • --namespace <uri>, --identity <uri|identity-chain>
  • --namespace <uri>, --displayId <string>
  • --displayId <string>

Additionally, the following combinations of options are accepted for identifying child objects (e.g. an SBOL1/2 SequenceAnnotation, or an SBOL3 SubComponent):

  • --identity <identity-chain>
  • --namespace <uri>, --identity <identity-chain>
  • --context <uri|identity-chain>, --displayId <string>
  • --namespace <uri>, --context <uri|identity-chain>, --displayId <string>

These options are used as follows:

  • --namespace The namespace for the object as a URI prefix. For example, --namespace "http://example.com/mydesign/"
  • --identity The identity of the object as a URI or an identity chain. For example, --identity "http://example.com/toggleSwitch/lacI_inverter/pLac" or --identity :toggleSwitch:lacI_inverter:pLac
  • --context The parent object in which to identify a child object as a URI or identity chain. For example, pLac might be created with --context :toggleSwitch:lacI_inverter or --context http://example.com/toggleSwitch/lacI_inverter.
  • --displayId The displayId of the object
  • --versionSBOL2.x only: The version of the object. (Not present in SBOL1, and removed in SBOL3.)

For example, consider an SBOL3 Collection in the "http://example.com/" namespace with the displayId toggleswitch, which contains a Component with the displayId lacI_inverter. The add-component <identity> action could be called in several different ways to create a pLac sub-component:

  • add-component --namespace "http://example.com/" --identity :toggleSwitch:lacI_inverter:pLac
  • add-component --context "http://example.com/toggleswitch/lacI_inverter" --displayId "pLac"
  • add-component --namespace "http://example.com/" --context :toggleSwitch:lacI_inverter --displayId "pLac"

The namespace parameter is optional only in the case that:

  • The context parameter is specified, in which case the namespace is inferred from the parent object.
  • The object being created references another object upon creation, and therefore can default to the namespace of the other object. For example, a component (a) created as a sub-component of another component (b) will use the namespace of (a) unless a namespace is specified explicitly.
  • All of the objects in the currently loaded knowledge graph only use a single namespace. This namespace will be used as the default.

Sometimes, an identity is the value of a parameter. For example, create-sequence --for-component <identity>. In this case, the specification of identity follows the same convention as above, but prefixed with the parameter name, e.g. --namespace becomes --for-component-namespace. For example:

create-sequence --for-component-namespace "http://example.com" --for-component-identity :foo

2.3. SBOL versions

Where an --sbol-version parameter is specified in an action, the value can be 1, 2, or 3. Similar to the namespace option, the parameter is optional only in the case that:

  • The object being created references another object upon creation, and therefore can default to the SBOL version of the other object. For example, a component created as a sub-component of an SBOL3 component will be an SBOL3 component.
  • All of the objects in the currently loaded knowledge graph are of the same SBOL version. The newly created object will also use this SBOL version unless a different version is specified.

3. Actions

For detailed help for a specific action, use

sbol <action> --help
For example,
sbol convert --help

3.1. Graph operations

import

import
    --as <string>
        [source]

Import RDF, FASTA, or GenBank into the current graph

The source may be either the filename or URL of a serialized RDF resource, such as an SBOL1, 2, or 3 file; or the filename or URL of a FASTA or GenBank file.

The –as parameter specifies the RDF conversion target sbol1/sbol/sbol3. For example,

import foo.fasta --as sbol1

would result in a graph containing foo.fasta converted to SBOL1 RDF. Without an –as parameter, the SBOL will be imported as-is. The –as parameter for FASTA/GenBank imports defaults to SBOL3.

3.1. Local SBOL-SBOL conversion

convert

convert
    --target <sbol-version>
        [--online <arg>]

3.2. Online converter/validator

These actions call out to the SBOL Converter/Validator, and therefore require an Internet connection.

validate

validate

3.3. Object creation and deletion

component

component
     <identity>
        --type <arg>
            --role <arg>

Creates a component

constraint

constraint
     <identity>
        --subject <identity>
            --restriction <arg>
                --object <identity>

Creates a constraint

create-component

create-component
    [--within-component <identity>]
         <identity>

Creates a component

interaction

interaction
    [--within-component <identity>]
         <identity>
            --type <arg>

Creates an interaction

module

module
    [--within-module <identity>]
         <identity>

Creates a module (SBOL2 only)

participant

participant
    [--within-interaction <identity>]
         <identity>
            --role <arg>

Shorthand for creating a participation with a participant

participation

participation
    [--within-interaction <identity>]
         <identity>
            --role <arg>
                [--participant <identity>]

Creates a participation

sequence

sequence
    --for-component <identity>
         <identity>
            --source <url>
                --encoding <arg>

Creates a sequence

If the sequence identity is not specified, a default identity will be created from the component identity with _seq appended to its displayId.

If the encoding is not specified, it will be inferred from the component in the case that --for-component is specified (e.g. a DNA component will result in a nucleic acid sequence being created).

If such inference is not possible (e.g. no component is specified, or the specified component is of a type other than DNA, RNA, or Protein), an error will be thrown.

3.4. Relationship creation and deletion

3.5. Sequence annotation

annotate-range

annotate-range
     <identity>
        --in-component <identity>
            --start <arg>
                --end <arg>
                    --role <arg>

Annotates a range in a sequence

3.6. Other

components

components

synbiocad-render

synbiocad-render