seqviz

 

Latest Production Build: Wed Dec 11 17:02:36 EST 2019

Maintained by: Lattice Automation

DNA sequence viewer supporting custom, GenBank, FASTA, NCBI accession, and iGEM part input

• Key Features
• Using the Library
  • Installation
  • Usage
  • Configuration
• Library Demo
• Contact Us
• Contributing
• License

Key Features

This package aims to provide basic sequence viewing in a simple, open-source way, for use anywhere that supports running javascript. It currently provides:

• Multiple input formats: For formats that can be displayed by this viewer see viewer input

• Circular Plasmid viewer :

  • Annotations with names and colors
  • Name of sequence
  • Base pair length of sequence

• Linear Sequence viewer :

  • Annotations with names and colors
  • Sequence and complement nucleotide bases
  • Index line with base pair numbers
  • Enzyme cut sites
  • Highlighted subsequences from search

• Selections:

  • On both Circular and Linear viewers clicking on an annotation or dragging over a section of the viewer will create a selection
  • Information about this selection will be available through the onSelection() option (see viewer options)

Using the Library

Installation

The library source code is in a file named seqviz.min.js. You can either extract this from the GitHub release tarball or download it from our CDN at https://cdn.latticeautomation.com/libs/seqviz/1.0.3/seqviz.min.js.

You will want to import the library in your top level index.html (or whatever is the entry point of your website).

For example you can use:

<script src="https://cdn.latticeautomation.com/libs/seqviz/1.0.3/seqviz.min.js"></script>

This method requires no actual download. You will be served the library directly from our CDN. This method, however, does require you to have internet access in order to use the library.

If you want to load the library locally and be able to view cached parts without internet connection you can download the source file to the same folder as your index.html and use:

<script src="seqviz.min.js"></script>

If you are using Create React App and have the source code stored in your public folder you can use:

<script src="%PUBLIC_URL%/seqviz.min.js"></script>

Usage

You can initialize a viewer with React or vanilla-JS.

React, via the Seqviz component:

const { SeqViz } = window.seqviz;

const CustomViewer = () => (
  <SeqViz
    name="J23100"
    seq="TTGACGGCTAGCTCAGTCCTAGGTACAGTGCTAGC"
    annotations={[{ name: "promoter", start: 0, end: 34 }]}
  />
);

JavaScript, via the Viewer constructor:

<script>
  const seqviz = window.seqviz;
  seqviz
    .Viewer("root", {
      name: "L09136",
      seq: "tcgcgcgtttcggtgatgacggtgaaaacctctgacacatgca"
    })
    .render();
</script>

Viewer

Viewer(${element}, ${ViewerConfig})

• element -- either a string id attribute like "root" or "app-root" or an element; e.g. from document.getElementById()
• ViewerConfig -- ViewerConfig are documented in greater detail below

The Viewer returns an object with three properties:

• viewer.render() -- renders the viewer to the DOM at the node passed in ${element}
• viewer.renderToString() -- renders the viewer and returns as an HTML string
• viewer.setState(ViewerConfig) -- update the viewer's settings and re-renders

Configuration

All the following are usable with both the React implementation (as props) and the JS implementation as properties in a ViewerConfig object passed to the Viewer constructor.

One of the below is required:

• seq (string) the DNA sequence to render
• accession (string) an NCBI accession ID or iGEM part ID
  • populates name, seq, and annotations
• file (File) a File object (FASTA, Genbank, SnapGene, SBOL)
  • populates name, seq, and annotations

Simple optional configuration options:

• viewer (one of ["linear", "circular", "both"]) the type of viewer to show. "both" by default
• name (string) the name of the sequence/plasmid
• compSeq (string) the complement sequence. inferred from seq by default
• showComplement (boolean) whether to show the complement sequence
• showAnnotations (boolean) whether to show annotations
• showIndex (boolean) whether to show the index line and ticks below the sequence
• enzymes ([string]) a list of restriction enzymes whose recognition sites should be shown
  • example: ["PstI", "EcoRI"]
• bpColors ({[string]: string}) map from bp to color.
  • example: { A: "#FF0" T: "#00F" }
• zoom how zoomed the viewer(s) should be 0-100
  • map from viewer type to zoom level.
    • default: { linear: 50, circular: 0 }

Additional configuration is below:

colors

array of colors to be used for annotations. Annotations are rendered with a random color from a set of defined colors. The library currently explicitly supports hex code color options, but other color options may be inherently supported.

Defaults to:

[
  "#9DEAED", // cyan
  "#8FDE8C", // green
  "#CFF283", // light green
  "#8CDEBD", // teal
  "#F0A3CE", // pink
  "#F7C672", // orange
  "#F07F7F", // red
  "#FAA887", // red-orange
  "#F099F7", // magenta
  "#C59CFF", // purple
  "#6B81FF", // blue
  "#85A6FF" // light blue
];

onSelection

function to be applied to the selection information. The function you specify will have access to the selection object as its only parameter.

Example for a random drag selection

{
  "ref": "",
  "sequenceMeta": {
    "sequence": "aggcggtttgcgtattgggcgctcttccgcttcctcgctcactgactcgctgcgctcggtcgttcggctgcggcgagcggtatcagctcactcaaaggcggtaatacggttatccacagaatcaggggataacgcaggaaagaacatgtgagcaaaaggccagcaaaaggccaggaaccgtaaaaaggccgcgttgctggcgtttttccataggctccgcccccctgacgagcatcacaaaaatcgacgctcaagtcagaggtggcgaaacccgacaggactataaagataccaggcgtttccccctggaagctccctcgtgcgctctcctgttccgaccctgccgcttaccggatacctgtccgcctttctcccttcgggaagcgtggcgctttctcatagctcacgctgtaggtatctcagttcggtgtaggtcgttcgctccaagctgggctgtgtgcacgaaccccccgttcagcccgaccgctgcgccttatccggtaactatcgtcttgagtccaacccggtaagacacgacttatcgccactggcagcagccactggtaacaggattagcagagcgaggtatgtaggcggtgctacagagttcttgaagtggtggcctaactacggctacactagaaggacagtatttggtatctgcgctctgctgaagccagttaccttcggaaaaagagttggtagctcttgatccggcaaacaaaccaccgctggtagcggtggtttttttgtttgcaagcagcagattacgcgcagaaaaaaaggatctcaagaagatcctttgatcttttctacggggtctgacgctcagtggaacgaaaactcacgttaagggattttggtcatgagattatcaaaaaggatcttcacctagatccttttaaattaaaaatgaagttttaaatcaatctaaagtatatatgagtaaacttggtctgacagttaccaatgcttaa",
    "GC": 51.1,
    "Tm": 85
  },
  "selectionMeta": {
    "type": "",
    "start": 650,
    "end": 1627,
    "selectionLength": 977,
    "clockwise": true
  }
}

If the selection is an annotation (generated by clicking on an annotation) there will additionally be a feature field containing information about the annotation. The ref field is the id the svg element of the drawn annotation.

{
  "ref": "lxcC1L3M4z",
  "sequenceMeta": {
    "sequence": "ctatgcggcatcagagcagattgtactgagagtgcaccatatgcggtgtgaaataccgcacagatgcgtaaggagaaaataccgcatcaggcgccattcgccattcaggctgcgcaactgttgggaagggcgatcggtgcgggcctcttcgctattacgccagctggcgaaagggggatgtgctgcaaggcgattaagttgggtaacgccagggttttcccagtcacgacgttgtaaaacgacggccagtgccaagcttgcatgcctgcaggtcgactctagaggatccccgggtaccgagctcgaattcgtaatcatggtcat",
    "GC": 55.3,
    "Tm": 85
  },
  "selectionMeta": {
    "type": "ANNOTATION",
    "start": 133,
    "end": 457,
    "selectionLength": 324,
    "clockwise": true
  },
  "feature": {
    "id": "lxcC1L3M4z",
    "color": "#8FDE8C",
    "name": "lacZ fragment",
    "type": "CDS",
    "start": 133,
    "end": 457,
    "direction": "REVERSE"
  }
}

For examples on how to practically use the selection information see seqviz/demo.

onSearch

function to be applied to the search results. The function you specify will have access to the results object as its only parameter.

Example of a search result:

{
  "searchResults": [
    {
      "start": 728,
      "end": 733,
      "row": 0,
      "index": 0
    },
    {
      "start": 1788,
      "end": 1793,
      "row": 0,
      "index": 1
    },
    {
      "start": 1980,
      "end": 1985,
      "row": 0,
      "index": 2
    },
    {
      "start": 2774,
      "end": 2779,
      "row": 0,
      "index": 3
    }
  ],
  "searchIndex": 0
}

The start and end are the indices encapsulating the substring match for the search query. The row is 0 for sequence strand and 1 for complement strand. The index is for tabulation (see searchNext).

searchNext

object used to set the key binding for tabulating search results (focus highlighting sequential search highlights).

This library tries to keep default key bindings to a minimum so there are no key bindings to tabulating the search results, but you can set your own by passing the key binding to searchNext.

Defaults to:

{
    key: "",
    meta: false,
    ctrl: false,
    shift: false,
    alt: false
}

You can use any keyboard key that is not ArrowLeft, ArrowRight, ArrowUp, or ArrowDown. Find the key name for your key press at keycode.info. This library uses the event.key for key bindings. The key to be bound is case sensitive. If you want to make searchNext a special key binding e.g. shift + a, or alt + . you can specify your special key with value true.

copySeq

object used to set the key binding for copying the template strand sequence of your current selection.

This library tries to keep default key bindings to a minimum so there are no key bindings copy, but you can set your own by passing the key binding to copySeq.

Defaults to:

{
    key: "",
    meta: false,
    ctrl: false,
    shift: false,
    alt: false
}

You can use any keyboard key that is not ArrowLeft, ArrowRight, ArrowUp, or ArrowDown. Find the key name for your key press at keycode.info. This library uses the event.key for key bindings. The key to be bound is case sensitive. If you want to make copySeq a special key binding e.g. shift + a, or alt + . you can specify your special key with value true.

searchQuery

object to specify a subsequence search to be conducted on the imported part.

Defaults to:

{ query: "", mismatch: 0 }

query is a string subsequence. The search functionality supports the following common nucleotide wildcards:

{
  y: [ c, t],
  r: [ a, g ],
  w: [ a, t ],
  s: [ g, c ],
  k: [ t, g ],
  m: [ c, a ],
  d: [ a, g, t ],
  v: [ a, c, g ],
  h: [ a, c, t ],
  b: [ c, g, t ],
  x: [ a, c, g, t ],
  n: [ a, c, g, t ]
}

mismatch is an int numeration of the amount of mismatch leeway the search should have. A mismatch of 1 will will allow for one base to not match the query.

backbone

string addition to main sequence. This is a feature specific to BioBricks. The library currently supports BBa_K1362091, BBa_K823055, pSB1A3, pSB1A7, pSB1AC3, pSB1AK3, pSB1AT3, pSB1C3, pSB1K3, pSB1T3 as specified at parts.igem.org. To use the backbone simply specify the backbone name (case insensitive) as a string like so

{
  backbone: "BBa_K1362091",
}

Custom backbones are also minimally supported. Any sequence string you input (ATCGatcg) can be used as the backbone.

translations

array of translation objects for creating translations beneath the sequence. Require 0-based start and end indexes (of the DNA bp) and a direction (FORWARD or REVERSE).

{
  translations: [{ start: 0, end: 89, direction: "FORWARD" }],
}

Library Demo

You can see a demonstration of this library used to fetch BioBricks at

tools.latticeautomation.com/seqviz

For developers, the demo source code is at seqviz/demo.

For a simpler start up, there is an HTML demo which only requires additions to the index.html to get started. See seqviz/demo/simple-ui/index.html.

You can also check out the example for examining NCBI parts included in our SeqViz introductory Medium post.

Contact Us

This library is currently being maintained by Lattice Automation.

You can report bugs at Issues

or contact [e-mail]

Contributing

See Running in Development Mode, CONTRIBUTING, and CODE_OF_CONDUCT

Here are some good guidelines to get started with contributing: Contributing to Open Source.