Final doc

docs/annotation.md → docs/style.md

+# 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"]
 

docs/varnaapi.md

-::: varnaapi
-    selection:
-		  filters: ["!^VARNA", "!^_", "__init__", "!Annotation", "!Comparison", "!Motif"]

mkdocs.yml

@@ -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

src/varnaapi/models.py

@@ -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
 

src/varnaapi/param.py

@@ -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 != "":