@rcsb/rcsb-saguaro

rcsb-saguaro

RCSB Saguaro 1D Feature Viewer is an open-source TypeScript library used to display protein and genomic sequence annotations over the web. The project is developed and maintained at RCSB PDB and it is currently used to display protein features on its web site. The package offers multiple types of data displays and a rich set of options to customize feature visualization.

When using rcsb-saguaro, please cite:

Joan Segura, Yana Rose, John Westbrook, Stephen K Burley, Jose M Duarte. RCSB Protein Data Bank 1D tools and services, Bioinformatics, 2020; https://doi.org/10.1093/bioinformatics/btaa1012

Node Module Installation

npm install @rcsb/rcsb-saguaro

Testing

Different testing example are available in the src/examples folder

git clone git@github.com:rcsb/rcsb-saguaro.git
cd rcsb-saguaro
npm install
npm run devServer

Go to:

http://localhost:9000/MultipleTracks.html
http://localhost:9000/MultipleAlignment.html

CDN JavaScript

<script src="https://cdn.jsdelivr.net/npm/@rcsb/rcsb-saguaro@3.0.3/build/rcsb-saguaro.min.js" type="text/javascript"></script>

Library Documentation

TypeScript full classes documentation can be found here.

Main Classes and Interfaces

These are the most important elements if you are only interested in using RCSB Saguaro to visualise protein annotations

RcsbFv: Main feature viewer class that can be used to create, configure and render a feature viewer object. It includes different methods to change viewer configuration, add new tracks, replace or update track data or change track visibility
RcsbFvBoardConfigInterface: Feature viewer configuration interface that defines the different properties to configure the feature viewer main panel including track title and annotation cells width, activate tooltips flag and annotation click and hovering callbacks
RcsbFvRowConfigInterface: This interface can be used to set up the configuration for feature viewer tracks. It includes multiple properties that define how track features are displayed (color, shape, overlap flag) and also different track attributes (background color, track height, track title, track visibility)
RcsbFvTrackDataElementInterface Interface that defines properties of an specific annotation object. It includes the location where the annotation will be displayed (begin, end) and additional properties to change the final representation and click-event behaviour

General Board and Track Configuration

Board Configuration

Main feature viewer board object configuration defines the coordinate range, track and title width and axis display. The full set of attributes is defined in RcsbFvBoardConfigInterface interface.

Main Board Configuration properties are:

range: Object that defines the 1D domain coordinates segment as a range of sequential integer values
- min: Numerical value that defines the coordinates start position
- max: Numerical value that defines the coordinates end position
trackWidth: Numerical value that defines the width of the board cells that contains the feature
rowTitleWidth: Numerical value that defines the width of the row title cells
includeAxis: Boolean flag used to include a 1D horizontal axis on the top part of the board

const boardConfig = {
    range: {
        min: 20,
        max: 110
    },
    trackWidth: 940,
    rowTitleWidth: 260,
    includeAxis: true
};

Track Configuration

Row configuration object defines format and content of feature viewer rows. The full set of board row configuration attributes is defined in RcsbFvRowConfigInterface.

Main Row Configuration properties are:

trackHeight: Defines the board row height
trackColor: Color in which row data will be displayed
rowTitle: Board track title, text displayed next to the board row
displayType: Enumerated value used to define how the data is displayed
- Values: sequence, block, pin, line, area, bond, vline
trackData: List of data displayed in the board row. The full set o data attributes are defined in RcsbFvTrackDataElementInterface. Most important data elements attributes are
- begin: Start position of the feature
- end: End position of the feature (optional value). When no end value is available the feature is located on a single position defined by begin
- value: Numerical or string value of the feature in this range (optional value)
- gaps: List of empty regions in the feature. These regions are displayed as a dashed line between blocks. This attribute is only available when displayType is "block"
  - Attributes: begin, end

Track Configuration Examples

Sequence Track

const sequence = "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPTIEDSYRKQVVIDGETCLLDILDTAGQ"+
                 "EEYSAMRDQYMRTGEGFLCVFAINNTKSFEDIHQYREQIKRVKDSDDVPMVLVGNKCDLAA"+
                 "RTVESRQAQDLARSYGIPYIETSAKTRQGVEDAFYTLVREIRQHKLRKLNPPDESGPGCMS"

const sequenceTrack = {
    trackHeight: 20,
    trackColor: "#F9F9F9",
    displayType: "sequence",
    rowTitle: "SEQUENCE",
    trackData: [{
        begin: 1,
        label: sequence
    }]
}

Block Track

const blockTrack= {
    trackId: "blockTrack",
    trackHeight: 20,
    trackColor: "#F9F9F9",
    displayType: "block",
    displayColor: "#FF0000",
    rowTitle: "BLOCK",
    trackData: [{
        begin: 30,
        end: 60,
        gaps:[{
            begin:40,
            end:50
        }]
    },{
        begin: 80,
        end: 90,
        openEnd: true
    }]
}

Feature View Constructor

const pfv = new RcsbFv.Create({
    boardConfigData: boardConfig,
    rowConfigData: [sequenceTrack, blockTrack],
    elementId: "htmlElementId"
});

See this expanded example online here

More Examples

The full collection of examples can be edited and modified at CODEPEN

rcsb-saguaro-app

We also provide a library (rcsb-saguaro-app) to build preconfigured 1D Protein Feature Views of RCSB PDB and UniProtKB annotations.

Contributing

All contributions are welcome. Please, make a pull request or open an issue.

License

The MIT License

Copyright (c) 2019 - now, RCSB PDB and contributors

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.