Commit 2a6a2e9f authored by htyao's avatar htyao
Browse files

Final doc

parent de54bad8
# Style classes for VARNA operations
Two helper class groups can be imported from `#! python varnaapi.param` for two VARNA operations, [add_annotation][varnaapi.BasicDraw.add_annotation] and [add_bases_style][varnaapi.BasicDraw.add_bases_style].
## Annotation
An `Annotation` object represents a textual annotation added to a VARNA drawing.
The object stores the text and other informtation needed.
One can add `Annotation` to drawing using [VARNA.add_annotation](varna.md#varnaapi.Structure.add_annotation).
One can add `Annotation` to drawing using [BasicDraw.add_annotation][varnaapi.BasicDraw.add_annotation].
Four annotation types allowed in VARNA are represented by four objects below.
::: varnaapi.param
selection:
members: ["BaseAnnotation", "LoopAnnotation", "HelixAnnotation", "StaticAnnotation"]
rendering:
heading_level: 3
::: varnaapi.param
selection:
members: ["BasesStyle"]
::: varnaapi
selection:
filters: ["!^VARNA", "!^_", "__init__", "!Annotation", "!Comparison", "!Motif"]
......@@ -14,8 +14,7 @@ nav:
- API:
- Drawing Classes: drawing.md
- Configurations: config.md
- Annotation: annotation.md
- Miscellaneous: varnaapi.md
- Style Classes: style.md
plugins:
- search
......
......@@ -138,7 +138,7 @@ class BasicDraw(_VarnaConfig):
def add_annotation(self, annotation:_Annotation):
"""Add an annotation.
Argument should be a valid [Annotation](annotation.md) object
Argument should be a valid [Annotation](/style#annotation) object
Examples:
>>> v = varnaapi.Structure()
......@@ -150,14 +150,38 @@ class BasicDraw(_VarnaConfig):
raise Exception("Should be a valid annotation object")
self.annotations.append(annotation)
def add_chem_prob(self, i, **kwargs):
def add_chem_prob(self, base:int, glyph:str='arrow', dir:str='in', intensity:float=1, color='#0000B2'):
"""Add chemical probing annotation on two adjacent bases.
Args:
base: index of the first base of adjacent bases
glyph: Shape of the annotation chosen from ['arrow', 'dot', 'pin', 'triangle']
dir: Direction of the annotation chosen from ['in', 'out']
intensity: Annotation intensity, _i.e._ thickness
color (color): Color used to draw the annotation
"""
try:
assert i>=0 and i < self.length-1
assert base>=0 and base < self.length-1
except AssertionError:
raise Exception("Base should be in between 0 and {}".format(self.length-1))
self.chem_prob.append((int(i), _ChemProb(**kwargs)))
self.chem_prob.append((int(base), _ChemProb(glyph=glyph, dir=dir, intensity=intensity, color=color)))
def add_colormap(self, values, vMin=None, vMax=None, caption="", style="energy"):
def add_colormap(self, values, vMin:float=None, vMax:float=None, caption:str="", style="energy"):
"""Add color map on bases.
Args:
values (float list): list of values in float for each base. `0`s are added at the end of the list if the list length is shorter than the number of bases.
vMin: Minium value for the color map
vMax: Maximum value for the color map
caption: Color map caption
style: Color map style, which is one of the following
- predefined style from
['red', 'blue', 'green', 'heat', 'energy', 'bw']
- customized style in a list of pairs, (value, color)
"""
self.colormap = _ColorMap(values, vMin, vMax, caption, style)
def _gen_command(self):
......@@ -174,14 +198,14 @@ class BasicDraw(_VarnaConfig):
# Title cmd
if self._title is not None:
cmd += self._title.to_cmd()
cmd += self._title._to_cmd()
# Aux Base pairs
if len(self.aux_BPs) > 0:
res = []
for i, j, style in self.aux_BPs:
s = "({},{})".format(i,j)
setting = style.to_cmd(self.get_params(complete=True)['bp'])
setting = style._to_cmd(self.get_params(complete=True)['bp'])
if not setting == "":
s += ":" + setting
res.append(s)
......@@ -192,7 +216,7 @@ class BasicDraw(_VarnaConfig):
res = []
for item in self.highlight_regions:
s = "{}-{}".format(item[0], item[1])
setting = item[2].to_cmd()
setting = item[2]._to_cmd()
if not setting == "":
s += ":" + setting
res.append(s)
......@@ -202,21 +226,21 @@ class BasicDraw(_VarnaConfig):
styles = {'fill': 'baseInner', 'outline': 'baseOutline', 'label': 'baseName', 'number': 'baseNum'}
styles_dafault = {v: self.get_params().get(v) for v in styles.values() if v in self.get_params()}
for ind, (style, bases) in enumerate(self.bases_styles.items()):
s = style.to_cmd(**styles_dafault)
s = style._to_cmd(**styles_dafault)
if not s == "":
cmd += ["-basesStyle{}".format(ind + 1), s]
cmd += ["-applyBasesStyle{}on".format(ind + 1), ','.join(map(str, bases))]
# Annotations
if len(self.annotations) > 0:
cmd += ["-annotations", ';'.join([t.to_cmd() for t in self.annotations])]
cmd += ["-annotations", ';'.join([t._to_cmd() for t in self.annotations])]
# Chem Prob
if len(self.chem_prob) > 0:
res = []
for i, style in self.chem_prob:
s = "{}-{}".format(i, i+1)
setting = style.to_cmd()
setting = style._to_cmd()
if not setting == "":
s += ":" + setting
res.append(s)
......@@ -224,7 +248,7 @@ class BasicDraw(_VarnaConfig):
# Color Map
if self.colormap is not None:
cmd += self.colormap.to_cmd()
cmd += self.colormap._to_cmd()
return cmd
......
......@@ -230,7 +230,7 @@ class _DefaultObj:
res[par] = val
return res
def to_cmd(self):
def _to_cmd(self):
res = []
for par, val in self._get_diff().items():
res += ['-'+par, str(val)]
......@@ -261,34 +261,34 @@ class _Highlight(_DefaultObj):
self.values['fill'] = Color(fill)
self.values['outline'] = Color(outline)
def to_cmd(self):
def _to_cmd(self):
return ','.join('{}={}'.format(k, v) for k, v in self._get_diff().items())
class BasesStyle(_DefaultObj):
"""Defines a custom base-style, to be applied later to a set of bases.
A BasesStyle style contains colors used for different components of a base.
See [\_\_init\_\_][varnaapi.param.BasesStyle.__init__] for more details.
BasesStyle is constructed from given colors for different components.
__See Also:__ [VARNA.add_bases_style][varnaapi.Structure.add_bases_style]
"""
def __init__(self, fill=None, outline=None, label=None, number=None):
"""Basesstyle constructor from given colors for different components.
Error:
At least one argument should be given.
Args:
fill (Hex): color of inner part of base
outline (Hex): color of outline of base
label (Hex): base text (name) color
number (Hex): base number color
Args:
fill (color): color of inner part of base
outline (color): color of outline of base
label (color): base text (name) color
number (color): base number color
Examples:
>>> style = BasesStyle(fill='#FF0000', outline='#00FF00')
"""
Examples:
>>> style = BasesStyle(fill='#FF0000', outline='#00FF00')
__See Also:__ [BasicDraw.add_bases_style][varnaapi.BasicDraw.add_bases_style]
"""
def __init__(self, fill=None, outline=None, label=None, number=None):
super().__init__(fill=COLOR_DEFAULT['baseInner'], outline=COLOR_DEFAULT['baseOutline'], label=COLOR_DEFAULT['baseName'], number=COLOR_DEFAULT['baseNum'])
self.update(fill=fill, outline=outline, label=label, number=number)
self._update(fill=fill, outline=outline, label=label, number=number)
def update(self, **kwargs):
def _update(self, **kwargs):
"""Update component _colors.
Same rule as [\_\_init\_\_][varnaapi.param.BasesStyle.__init__]
"""
......@@ -298,8 +298,8 @@ class BasesStyle(_DefaultObj):
if val is not None:
self.values[par] = Color(val)
def to_cmd(self, **kwargs):
"""Custom command generator for BasesStyle
def _to_cmd(self, **kwargs):
"""Custom command generator for BasesStyle.
Function takes the default bases color set by user in kwargs
"""
for par, val in kwargs.items():
......@@ -327,7 +327,7 @@ class _BPStyle(_DefaultObj):
if 'thickness' in kwargs:
self.values['thickness'] = float(kwargs['thickness'])
def to_cmd(self, color):
def _to_cmd(self, color):
self.default['color'] = color
return ','.join('{}={}'.format(k, v) for k, v in self._get_diff().items())
......@@ -352,7 +352,7 @@ class _Annotation(_DefaultObj):
self.values['size'] = int(size)
self.anchor = anchor
def to_cmd(self):
def _to_cmd(self):
res = ["{}={}".format(k, v) for k, v in self._get_diff().items()]
if isinstance(self.anchor, int):
res.append("anchor={}".format(self.anchor))
......@@ -361,15 +361,15 @@ class _Annotation(_DefaultObj):
return "{}:{}".format(self.text, ','.join(res))
class BaseAnnotation(_Annotation):
def __init__(self, text:str, anchor:int, color="#000000", size=12):
"""Annoation on a base.
"""Annoation on a base.
Args:
text: Annotation caption
anchor: Index of base to annotate
color (Hex): Annotation color
size (int): Font size
"""
Args:
text: Annotation caption
anchor: Index of base to annotate
color (color): Annotation color
size (int): Font size
"""
def __init__(self, text:str, anchor:int, color="#000000", size=12):
super().__init__(text, 'B', int(anchor), color, size)
class LoopAnnotation(_Annotation):
......@@ -387,20 +387,21 @@ class HelixAnnotation(_Annotation):
super().__init__(text, 'H', int(anchor), color, size)
class StaticAnnotation(_Annotation):
def __init__(self, text, x, y, color="#000000", size=12):
"""Annotation on a specified position in VARNA drawing.
Unlike [BaseAnnotation][varnaapi.param.BaseAnnotation], argument `anchor` is omitted.
However, arguments `x` and `y` are needed to specify annotation position.
"""Annotation on a specified position in VARNA drawing.
Unlike [BaseAnnotation][varnaapi.param.BaseAnnotation], argument `anchor` is omitted.
However, arguments `x` and `y` are needed to specify annotation position.
__Note:__ It is unrecommended to use static annotation unless you know what you're doing
Danger:
It is unrecommended to use static annotation unless you know what you're doing
Args:
x (int): x-coordinate of position
y (int): y-ccordinate of position
Args:
x (int): x-coordinate of position
y (int): y-ccordinate of position
Examples:
>>> sa = StaticAnnotation("Hello World", 100, 150, color="#FF0000")
"""
Examples:
>>> sa = StaticAnnotation("Hello World", 100, 150, color="#FF0000")
"""
def __init__(self, text, x, y, color="#000000", size=12):
super().__init__(text, 'P', (int(x), int(y)), color, size)
CHEM_DEFAULT = {'glyph': 'arrow', 'dir': 'in', 'intensity': 1, 'color': Color('#0000B2')}
......@@ -421,7 +422,7 @@ class _ChemProb(_DefaultObj):
if 'intensity' in kwargs:
self.values['intensity'] = float(kwargs['intensity'])
def to_cmd(self):
def _to_cmd(self):
return ','.join('{}={}'.format(k, v) for k, v in self._get_diff().items())
CM_DEFAULT = ["red", "blue", "green", "heat", "energy", "bw"]
......@@ -446,7 +447,7 @@ class _ColorMap:
else:
raise ValueError('Style should be either a string of {} or a dictionary'.format(CM_DEFAULT))
def to_cmd(self):
def _to_cmd(self):
cmd = []
cmd += ['-colorMap', ';'.join(map(str, self.values))]
if self.caption != "":
......
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment