SequenceViewer¶

class visualife.widget.SequenceViewer(element_id, sequence_name='', sequence='', **kwargs)¶

Bases: visualife.widget.AbstractWidget

Creates a widget that displays an amino acid or a nucleotide sequence

A basic example of the widget is given below:

It has been created by the following code:

from visualife.widget import SequenceViewer

seq = SequenceViewer("show_sequence","4fia A","GRVLQDVFLDWAKKYGPVVRVNVFHKTSVIVTSPESVKKFLMSTKYNKDSKMYRALQTVFGERLFGQGLVSECNYERWHKQRRVIDLAFSRSSLVSLMETFNEKAEQLVEILEAKADGQTPVSMQDMLTYTAMDILAKAAFGMETSMLLGAQKPLSQAVKLMLEGITASRNTKRKQLREVRESIRFLRQVGRDWVQRRREALKRGEEVPADILTQILKAEEGAQDDEGLLDNFVTFFIAGHETSANHLAFTVMELSRQPEIVARLQAEVDEVIGSKRYLDFEDLGRLQYLSQVLKESLRLYPPAWGTFRLLEEETLIDGVRVPGNTPLLFSTYVMGRMDTYFEDPLTFNPDRFGPGAPKPRFTYFPFSLGHRSCIGQQFAQMEVKVVMAKLLQRLEFRLVPGQRFGLQEQATLKPLDPVLCTLRPR")
seq.add_to_region("sel1", first_pos=40, last_pos=80)
seq.region_tooltip("sel1", "first region")

SequenceViewer allows also loading more than one sequence; multiple sequences must be provided as a list

Note, that each of the two sequences has its own numbering. It has been created by the following code:

from visualife.widget import SequenceViewer

seqs = ["GQSSLALHKVIMVGSGGVGKSALTLQFMYDEFVEDYEPTKADSYRKKVVLDGEEVQIDILDTAGLEDYAAIRDNYFRSGEGFLLVFSITEHESFTATAEFREQILRVKAEEDKIPLLVVGNKSDLEERRQVPVEEARSKAEEWGVQYVETSAKTRANVDKVFFDLMREIRTKKMSENK",
    "GSETQAGIKEEIRRQEFLLNSLHRDLQGGIKDLSKEERLWEVQRILTALKRKLREA"]
in_chain_A = [16,18,48,49,50,51,52,65,67,74,75,77,78,81,82,84,85]
in_chain_B = [409,413,416,417,421,426,427,429,430,433,434,437,440,444]
seq2 = SequenceViewer("show_sequence2", "2kwi A, B", seqs, first_residue_id=[8, 391])
for ires in in_chain_A:
    seq2.add_to_region("sel1", 1, first_pos=ires, last_pos=ires, by_residue_id=True)
seq2.region_tooltip("sel1","chain A interacting with chain B")
for ires in in_chain_B:
    seq2.add_to_region("sel2", 2, first_pos=ires, last_pos=ires, by_residue_id=True)
seq2.region_tooltip("sel2", "chain B interacting with chain A")

Programmable events

This widget handles the following events:

CLICK_ON_LEGEND: happens when one clicks on a region’s legend that is given below the sequence; the default behavior is to flip (on/off) the selected region.
CLICK_ON_LETTER: happens when one clicks on a letter of a sequence

The following examples defines a simple alert action for each of the event

from browser import alert
from visualife.widget import SequenceViewer

seq = SequenceViewer("show_sequence3","2gb1A","MTYKLILNGKTLKGETTTEAVDAATAEKVFKQYANDNGVDGEWTYDDATKTFTVTE",
    n_columns_of_ten=6)
seq.add_to_region("sel1", first_pos=23, last_pos=33)
seq.region_tooltip("sel1","alpha-helix")
seq.set_event_callback("CLICK_ON_LEGEND", lambda evt : alert("You clicked on legend for:" + evt.target.id))
seq.set_event_callback("CLICK_ON_LETTER", lambda evt : alert("You clicked on letter:" + evt.target.id))

Parameters:

element_id – ID of a html DIV element that will contain this SequenceViewer instance
sequence_name – name of the sequence to be shown
sequence – the sequence itself (one-letter string, FASTA-style without header)
kwargs – see below

Keyword Arguments:

palette_name (string) – name of a color palette used to mark sequence regions (one color per region)
sequence_colors (dict) – name of a color scheme that is used to color a sequence. The available color schemes are defined in core/styles.py. Each style is just a dictionary that provides a color (either by its name or hex) for every letter that may be found in sequence
n_columns_of_ten (int) – when the widget displays sequence, it puts a space after every 10 residues; by default there are 50 residues in every line, divided in five 10-residues blocks; say n_columns_of_ten=4 to display only 40 residues per line or to n_columns_of_ten=8 if you like to have 80 residues per line
onclick (function) – provide a function that will be called at onclick event; the function must accept sole event object argument
first_residue_id (int or list[int]) – integer index of the very first residue in the given sequence (1 by default); if more than one sequence has been provided, user should provide also a list with first residue IDs
region_cmap (ColorMap or string) – defines a color map that will be used to color letters within a single residue range - in the case where user provides a real value for each letter of a range
show_menu (bool) – if True, a drop-down menu will be shown for that widget (True by default)
show_header (bool) – if True, a header line will be shown for that widget (True by default)
show_blockwise (bool) – if True, a sequence will be displayed in blocks of 10 residues, separated by a space (True by default); otherwise, each row of this widget will be a contiguous line of amino acid or nucleotide symbols

Attributes Summary

`menu`	Provides menu for this object
`region_cmap`	A color map used to color a single sequence region according to real values
`regions_palette`	A name of color palette used to color marked regions.
`secondary_structure`	Protein / nucleotide secondary structure - for coloring purposes only
`sequence_blocks_in_line`	Returns the number of 10-residues long blocks of a sequence that are printed in a single line
`sequence_name`	Name of the sequence displayed by this viewer.
`show_header`	Whether this widget shows a sequence header line or not

Methods Summary

`add_to_region`(region_name[, which_sequence, …])	Add a block of amino acids/nucleotides to a sequence region
`color_background`(color_scheme, **kwargs)	Colors letter background in this sequence
`color_sequence`(color_scheme, **kwargs)	Colors characters in this sequence
`count_sequences`()	Number of sequences displayed by this viewer.
`delete_region`(region_name)	Permanently removes a sequence region
`delete_regions`()	Permanently removes all regions defined for a sequence
`first_residue_id`(which_sequence)	Index of the very first residue in a given sequence
`flip_region`(region_name)	Flips region visibility.
`hide_region`(region_name)	Deactivates a given sequence region
`load_sequence`(fasta_sequence, **kwargs)	Replaces the sequence displayed by this object with a new one
`region_for_name`(region_name)	Returns a sequence region registered under a given name.
`region_for_position`(pos)	Returns a sequence region a given residue belongs to.
`region_legend_id`(region_name)	Returns the ID of a legion legend element
`region_tooltip`(region_name, tooltip)	Sets a text that will show up in a tooltip
`secondary_structure_colors`(hec_string[, …])
`sequence`()	Protein / nucleotide sequences displayed by this viewer.
`show_region`(region_name)	Activates a given region
`which_region_in_legend`(evt)	Returns the sequence region corresponding to a legend item user clicked on.

Attributes Documentation

menu¶

Provides menu for this object

Returns:	MenuWidget object

region_cmap¶

A color map used to color a single sequence region according to real values

Getter:	returns the `ColorMap` object
Setter:	sets the new color map, either by its name or an object by itself
Type:	`string` or `ColorMap` object

regions_palette¶

A name of color palette used to color marked regions.

To display more than one regions, use one of the categorical palettes defined in styles.known_color_scales, such as "tableau10", "pastel1" or "accent". To color residues by a real-valued property, use a continuous color scale such as "violet_red"

Getter:	returns the name of color palette used to color selected regions
Setter:	sets the new palette
Type:	string

secondary_structure¶

Protein / nucleotide secondary structure - for coloring purposes only

Getter:	returns the secondary structure
Setter:	sets secondary structure string for this sequence
Type:	string

sequence_blocks_in_line¶

Returns the number of 10-residues long blocks of a sequence that are printed in a single line

Returns:	number of sequence blocks in a line

sequence_name¶

Name of the sequence displayed by this viewer.

Getter:	returns the sequence name
Setter:	sets a new name for this sequence; if the header line has been hidden, will be made visible
Type:	string

show_header¶

Whether this widget shows a sequence header line or not

Getter:	returns `True` when the sequence header line is displayed
Setter:	switch on or off this sequence header line
Type:	boolean

Methods Documentation

add_to_region(region_name, which_sequence=0, if_show_region=True, **kwargs)¶

Add a block of amino acids/nucleotides to a sequence region

This method updates an existing region. If the given region name has not been used so far, a new region will be created

Keyword Arguments:
Parameters:	region_name – name of this sequence region which_sequence – (`integer`) index of a sequence to mark a region; use `0` (the default) to mark a region on all sequences shown by this widget if_show_region – if True, the sequence region will be made visible after this change kwargs – see below
	color (`string`, `int` or `list[float]`) – provides color for this region: by color name as `string` by index of a color in the palette defined by `regions_palette()` by real values: color map will be used to color the region color is assigned only to newly created blocks; extending a block doesn’t change its color tooltip – a tooltip text will be shown when mouse cursor is over the region (mouseover event) by_residue_id (`bool`) – by default is `False`; when set to `True`, `pos_from` and `pos_to` will be considered residue IDs rather than indexes from 1 show_in_legend (`bool`) – if `True`, the region will be also listed in a legend box first_pos (`int`) – first residue included in this region, numbers start from 1; if no last_pos is provided, last_pos will be set to `first_pos` last_pos (`int`) – last residue included in this region, numbers start from 1; if no first_pos is provided, first_pos will be set to `last_pos` sequence (`string`) – a string that is a sequence fragment of this sequence
Returns:	None

color_background(color_scheme, **kwargs)¶

Colors letter background in this sequence

The background color for each character, which by default is white, will be set according to a requested color scheme

Parameters:

color_scheme –

a color scheme to be used (see below):

list[string] - list of colors (names of hex-strings) - the colors will be assigned to letters by one one; the list is cycled, so the colors can re-appear periodically
secondary: by secondary structure: helices, strands and loops (coil) will be red, blue and gray, respectively; this scheme requires secondary structure string to be set (secondary_structure property)
clear: background will be set back to white
clustal: coloured by amino acid code (ClustalX scheme)
maeditor: coloured by amino acid code (Multiple Alignment Editor program scheme)

color_sequence(color_scheme, **kwargs)¶

Colors characters in this sequence

The color of each character, which by default is black, will be set according to a requested color scheme

Parameters:

color_scheme –

a color scheme to be used (see below):

list[string] - list of colors (names of hex-strings) - the colors will be assigned to letters by one one; the list is cycled, so the colors can re-appear periodically
”secondary”: by secondary structure: helices, strands and loops (coil) will be red, blue and gray, respectively; this scheme requires secondary structure string to be set (secondary_structure property)
”clear”: all letters will be turned back to black
”clustal”: letters will be coloured by amino acid code (ClustalW scheme)
”maeditor”: coloured by amino acid code (Multiple Alignment Editor program scheme)

count_sequences()¶

Number of sequences displayed by this viewer.

Returns:	(`int`) number of sequences

delete_region(region_name)¶

Permanently removes a sequence region

If you just want to hide a region, use hide_region() instead :param region_name: name of a sequence region to be deleted :return: None

delete_regions()¶

Permanently removes all regions defined for a sequence

Returns:	None

first_residue_id(which_sequence)¶

Index of the very first residue in a given sequence

Parameters:	which_sequence – (`int`) index of a sequence
Returns:	(`int`) ID of the very first residue of that sequence

flip_region(region_name)¶

Flips region visibility.

Visible region will be hidden while a hidden region will be shown

Parameters:	region_name – name of a sequence region

hide_region(region_name)¶

Deactivates a given sequence region

This method does not remove any region, it just clears the color :param region_name: name of a sequence region to be made cleared off :return: None

load_sequence(fasta_sequence, **kwargs)¶

Replaces the sequence displayed by this object with a new one

Parameters:	fasta_sequence – a new sequence to be loaded (one-letter code)
Returns:	None

region_for_name(region_name)¶

Returns a sequence region registered under a given name.

Parameters:	region_name – (`string`) region name
Returns:	a list of residue ranges (from, to) - both inclusive from 0, e.g. `[(0,5),(7,20)]`

region_for_position(pos)¶

Returns a sequence region a given residue belongs to.

Parameters:	pos – (`int`) residue position from 1
Returns:	a region name and a list of ranges as in `region_for_name()` or None if a given residue doesn’t belong to any region

region_legend_id(region_name)¶

Returns the ID of a legion legend element

Parameters:	region_name – (`string`) a region name, assigned at `add_to_region()` call
Returns:	ID of the DOM element that holds legend for that sequence region

region_tooltip(region_name, tooltip)¶

Sets a text that will show up in a tooltip

The given text will be displayed in a tooltip box when a user hoovers the given sequence region with a mouse pointer. Use empty string to clear a tooltip

Parameters:	region_name – name of a sequence region that needs a tooltip tooltip – tooltip text

static secondary_structure_colors(hec_string, default_color='black')¶

sequence()¶

Protein / nucleotide sequences displayed by this viewer.

Total number of sequences can be checked by count_sequences() :param index: (int) the index of the sequence (from 0) :return: (str) a sequence

show_region(region_name)¶

Activates a given region

Parameters:	region_name – name of a sequence region to be made visible
Returns:	None

which_region_in_legend(evt)¶

Returns the sequence region corresponding to a legend item user clicked on.

Parameters:	evt – event object passed by a browser, that holds the clicked element
Returns:	tuple of two: sequence region name and the residues’ range as a list of lists of int