Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

https://github.com/Lattice-Automation/seqviz

a JavaScript DNA, RNA, and protein sequence viewer
https://github.com/Lattice-Automation/seqviz

biology dna igem plasmid protein rna synthetic-biology vector

Last synced: 4 months ago
JSON representation

a JavaScript DNA, RNA, and protein sequence viewer

Lists

README 

        


  






  




`SeqViz` is a DNA, RNA, and protein sequence viewer.



#### Used By





  

         

  

         

  

         

  

         

  




## Table of Contents



- [Demo](#demo)

- [Features](#features)

- [Usage](#usage)

  - [Installation](#installation)

  - [Instantiation](#instantiation)

  - [Props](#props)

  - [Custom Viewer Positioning](#custom-viewer-positioning)

  - [Without React](#without-react)

- [Contact Us](#contact-us)



## Demo



You can see a demo at [tools.latticeautomation.com/seqviz](https://tools.latticeautomation.com/seqviz). The source is in [/demo](./demo).



## Features



### Linear and Circular Sequence Viewers



- Annotations, primers, and highlights with names and colors

- Amino acid translations

- Enzyme cut sites

- Searching with mismatches and highlighting



### Sequence and Element Selection



- Selecting a range on the viewer(s), or clicking an `annotation`, `translation`, `primer`, `cutSite`, or `searchResult`, highlights the selection and passes it to the `onSelection()` callback.



## Usage



### Installation



#### npm



```bash

npm install seqviz

```



#### CDN



```html



```



### Instantiation



#### React



```jsx

import { SeqViz } from "seqviz";



export default () => (

  

);

```



#### Non-React



More details are in the [Viewer without React](#without-react) section.



```html



  window.seqviz

    .Viewer("root", {

      name: "L09136",

      seq: "tcgcgcgtttcggtgatgacggtgaaaacctctgacacatgca",

      style: { height: "100vh", width: "100vw" },

    })

    .render();



```



### Props



All the following are usable as props for the React component (`seqviz.SeqViz`) or as options for the plain JS implementation (`seqviz.Viewer()`).



#### Required



#### `seq (='')`



A sequence to render. Can be a DNA, RNA, or amino acid sequence.



#### File or Accession



These props are `@deprecated` and may be removed in a future major release. We recommend parsing sequence files outside of `SeqViz` with the [`seqparse` package](https://github.com/Lattice-Automation/seqparse).



- `file` is a FASTA, GenBank, SnapGene, JBEI, or SBOL file (`string` | [`File`](https://developer.mozilla.org/en-US/docs/Web/API/File))

- `accession` is an NCBI accession-ID (`string`)



For example:



```jsx

import seqparse from "seqparse";



export default () => {

  const [seq, setSeq] = useState({ name: "", seq: "", annotations: [] });



  // fetch and parse a sequence from NCBI: https://www.ncbi.nlm.nih.gov/nuccore/MN623123.1

  useEffect(async () => setSeq(await seqparse("MN623123.1")));



  return ;

};

```



#### Optional



#### `viewer (='both')`



The type and orientation of the sequence viewers. One of `"linear" | "circular" | "both" | "both_flip"`. `both` means the circular viewer fills the left side of SeqViz, and the linear viewer fills the right. `both_flip` is the opposite: the linear viewer is on the left, and the circular viewer is on the right.



#### `name (='')`



The name of the sequence/plasmid. Shown at the center of the circular viewer.



#### `annotations (=[])`



An array of `Annotation`s to render. Each `Annotation` requires 0-based start (inclusive) and end (exclusive) indexes. `name`s are rendered on top of the annotations. Set the annotation's direction to `1` for forward arrows and `-1` for reverse arrows.



```js

annotations = [

  { start: 0, end: 22, name: "Strong promoter", direction: 1 }, // [0, 22)

  { start: 23, end: 273, name: "GFP" },

  { start: 300, end: 325, name: "Weak promoter", direction: -1, color: "#FAA887" },

];

```



In the example above, the "Strong promoter" would span the first to twenty-second base pair.



#### `primers (=[])`



An array of `Primer`s to render. Each `Primer` requires 0-based start (inclusive) and end (exclusive) indexes. `name`s are rendered on top of the primers. Set the primer's direction to `1` for forward primer and `-1` for reverse primer.



```js

primers = [

  { start: 33, end: 53, name: "LacZ Foward Primer", direction: 1 },

  { start: 3098, end: 3128, name: "LacZ Reverse Primer", direction: -1, color: "#FAA887" },

];

```



In the example above, the forward and reverse primers of LacZ are define by the direction parameter. Notice that color could be used optionally.



#### `translations (=[])`



An array of `translations`: sequence ranges to translate and render as amino acids sequences. Requires 0-based `start` (inclusive) and `end` (exclusive) indexes relative the DNA sequence. A direction is required: `1` (FWD) or `-1` (REV).



```js

translations = [

  { start: 0, end: 90, direction: 1 }, // [0, 90)

  { start: 191, end: 522, direction: -1 },

];

```



#### `enzymes (=[])`



An array of restriction `enzymes` to show recognition sites for. A list of pre-defined enzymes in [src/enzymes.ts](src/enzymes.ts) can be referenced by name. Example:



```js

enzymes = [

  "EcoRI",

  "PstI",

  {

    name: "Cas9",

    rseq: "NGG", // recognition sequence

    fcut: 0, // cut index on FWD strand, relative to start of rseq

    rcut: 1, // cut index on REV strand, relative to start of rseq

    color: "#D7E5F0", // color to highlight recognition site with

    // (optional) only show recognition sites between 100th and 250th index [100, 250)

    range: {

      start: 100,

      end: 250,

    },

  },

];

```



#### `highlights (=[])`



Ranges of sequence to highlight. A default color from `colors` is used if none is provided.



```js

highlights = [

  { start: 36, end: 66, color: "magenta" },

  { start: 70, end: 80 },

];

```



#### `zoom (={ linear: 50 })`



How zoomed the viewer(s) should be `0-100`. Key'ed by viewer type, but only `linear` is supported.



#### `colors (=[])`



An array of colors to use for annotations, translations, and highlights. Defaults are in [src/colors.ts](src/colors.ts).



#### `bpColors (={})`



An object mapping base pairs to their color. The key/bp is either a nucleotide type or 0-based index. Example:



```js

bpColors = { A: "#FF0000", T: "blue", 12: "#00FFFF" };

```



#### `style (={})`



Style for `seqviz`'s outer container div. Empty by default. Useful for setting the height and width of the viewer if the element around `seqviz` lacks one. For example:



```js

style = { height: "100vh", width: "100vw" };

```



#### `selection (={})`



This (optional) `selection` prop is useful if you want to externally manage and set the `selection` state:



```js

selection = {

  start: 133,

  end: 457,

  clockwise: true,

};

```



#### `onSelection (=(_: Selection) => {})`



A callback executed after selection events. It accepts a single [`Selection` type](https://github.com/Lattice-Automation/seqviz/blob/01f6e7b956d18281d4d901b47c4a4becd75f0dc6/src/handlers/selection.tsx#L19) argument.



This occurs after drag/drop selections and clicks. It will have meta on `annotation`, `translation`, `enzyme`, `highlight` or `search` elements if one was selected. The example below shows an `annotation` selection:



```js

{

  "end": 457,

  "length": 324,

  "name": "lacZ fragment",

  "start": 133,

  "type": "ANNOTATION",

}

```



#### `search (={})`



Sequence search parameters. Takes a `query` sequence and the [maximum allowable `mismatch`](https://en.wikipedia.org/wiki/Hamming_distance) for a match (default: 0). Matches are highlighted.



```js

search = { query: "aatggtctc", mismatch: 1 };

```



Searching supports wildcard symbols, e.g. `{ query: "AANAA" }`. All symbols supported are in [src/sequence.ts](src/sequence.ts).



#### `onSearch (=(_: Range) => {})`



A callback executed after a search event. This is called once on initial render and every time the sequence changes thereafter. An example of search results is below:



```js

[

  {

    start: 728,

    end: 733,

    direction: 1,

    index: 0,

  },

  {

    start: 1788,

    end: 1793,

    direction: -1,

    index: 1,

  },

];

```



#### `copyEvent (=(e: KeyboardEvent) => e.key === "c" && (e.metaKey || e.ctrlKey))`



A function returning whether to copy the viewer(s) current selection during a keyboard event. The default method copies sequence after any `ctrl+c` or `meta+c` keyboard events.



#### `selectAllEvent (=(e: KeyboardEvent) => e.key === "a" && (e.metaKey || e.ctrlKey))`



A function returning whether to select the whole sequence during a keyboard event. The default method select whole sequence after any `ctrl+a` or `meta+a` keyboard events.



#### `showComplement (=true)`



Whether to show the complement sequence.



#### `rotateOnScroll (=true)`



By default, the circular viewer rotates when scrolling over the viewer. That can be disabled with rotateOnScroll: false.



#### `disableExternalFonts (=false)`



If true, SeqViz will not download fonts from external sites. By default the library will attempt to download "Roboto Mono:300,400,500" after first mount.



#### `refs (={ circular: undefined, linear: undefined })`



See: [custom viewer positioning](#custom-viewer-positioning)



### Custom Viewer Positioning



This makes use of the `children` and `refs` props to allow custom rendering of the sequence viewers. For example, to render the linear viewer above the circular viewer:



```jsx

import { useRef } from "react";

import { Circular, Linear, SeqViz } from "seqviz";



export default () => {

  const circular = useRef();

  const linearRef = useRef();



  return (

    

      {({ circularProps, linearProps, ...props }) => (

        


          


            

          


          


            

          


        


      )}

    

  );

};

```



### Without React



For usability in non-React apps, we provide a thin wrapper around the React component. The viewer's constructor accepts two arguments:



- `element`: either an element id or an [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement)

- `props`: props as documented [above](#optionsprops)



```js

const element = document.getElementById("root");

const viewer = seqviz.Viewer(element, props);

// Render the viewer to the DOM at the node passed in $element`.

viewer.render();

// To later update the viewer's configuration and re-renders.

viewer.setState(props);

// To render the viewer, eg for server-side rendering, and returns it as an HTML string.

viewer.renderToString();

```



## Contact Us



This library is maintained by [Lattice Automation](https://latticeautomation.com/).



You can report bugs and request features at [Issues](https://github.com/Lattice-Automation/seqviz/issues) or contact us directly at [[email protected]]([email protected])