Commit 5164053a authored by htyao's avatar htyao
Browse files

Add cartoon like example

Update cartoon example

Update

Update to mkdocstring 0.18

Some setup
parent a57a71fc
This diff is collapsed.
This diff is collapsed.
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.VARNA.add_annotation).
One can add `Annotation` to drawing using [VARNA.add_annotation](varna.md#varnaapi.Structure.add_annotation).
Four annotation types allowed in VARNA are represented by four objects below.
::: varnaapi
::: varnaapi.param
selection:
members: ["BaseAnnotation", "LoopAnnotation", "HelixAnnotation", "StaticAnnotation"]
VARNA API is a Python interface for [VARNA](http://varna.lri.fr/index.php), a Java lightweight component and applet for drawing the RNA secondary structure.
VARNA API is a Python interface for [VARNA](http://varna.lri.fr/index.php) (v3-93), a Java lightweight component and applet for drawing the RNA secondary structure.
VARNA allows users to produce drawing in a non-iteractive way via command line.
However, the command line might be massive and complicate in some use cases.
VARNA API aims to simplify such process.
......@@ -13,7 +13,7 @@ on secondary structure `((((((.((((((........)))))).((((((.......))))))..))))))`
java -cp VARNAv3-93.jar fr.orsay.lri.varna.applications.VARNAcmd -sequenceDBN " " -structureDBN "((((((.((((((........)))))).((((((.......))))))..))))))" -o example.png -algorithm radiate -auxBPs "(14,20):color=#FF00FF,thickness=1.0,edge5=s,edge3=wc,stericity=cis" -highlightRegion "11-21:radius=15.0,fill=#9999FF,outline=#3333FF"
```
The equivalence in python is
The equivalence using VARNA API would be
```python
from varnaapi import VARNA
v = VARNA(structure="((((((.((((((........)))))).((((((.......))))))..))))))")
......@@ -28,26 +28,35 @@ python3 -m pip install varnaapi
## Usage
Here, we show the basic usage of varnaapi. Please refer the [API](https://htyao.gitlab.io/varna-api/varna) page for more details.
The first thing after importing `varnaapi` is to setup the location of VARNA used.
The default is `VARNAv3-93.jar` in the current folder.
The first thing after importing `varnaapi` is to setup the location of VARNA to use.
!!! note "By default, the library assumes the VARNA v3-93 in the current folder is used (`./VARNAv3-93.jar`)"
```python
import varnaapi
varnaapi.set_VARNA(path_to_VARNA)
```
Each drawing in VARNA is an object called `VARNA` created from given secondary structure or/and RNA sequence.
Each drawing in VARNA is an object of class inherited from [BasicDraw][varnaapi.BasicDraw]. The standard class to draw from given secondary structure or/and RNA sequence is [Structure][varnaapi.Structure].
```python
ss = "((((((.((((((........)))))).((((((.......))))))..))))))"
v = varnaapi.VARNA(structure=ss)
v = varnaapi.Structure(structure=ss)
```
The object contains a member function to save the drawing into
```python
v.savefig(path_to_store)
```
Then we can add operations on drawing by calling object functions, such as `VARNA.set_algorithm()` to choose a drawing algorithm, `VARNA.add_highlight_region()` to highlight a region etc.
### Configuration
### Operations
Then we can add operations on drawing by calling member functions, such as `VARNA.set_algorithm()` to choose a drawing algorithm, `VARNA.add_highlight_region()` to highlight a region etc.
```python
v.set_algorithm('line')
v.add_highlight_region(0, 5, radius=20)
```
Finally, we can draw the secondary structure
```python
v.savefig(path_to_store)
```
## Credits
Please kindly cite VARNA [supporting manuscript](https://doi.org/10.1093/bioinformatics/btp250) if you use VARNA API in your research.
......
......@@ -2,15 +2,16 @@ In VARNA API, we offer three Python classes [VARNA](#varnaapi.VARNA), [Compariso
The first two correspond to the classic and the comparison mode in VARNA. The last one is the special case for motif drawing.
Both [Comparison](#varnaapi.Comparison) and [Motif](#varnaapi.Motif) are inherited classes of [VARNA](#varnaapi.VARNA).
::: varnaapi
::: varnaapi.models
selection:
members: ["VARNA"]
members: ["Structure"]
inherited_members: True
::: varnaapi
::: varnaapi.models
selection:
members: ["Comparison"]
::: varnaapi
::: varnaapi.models
selection:
filters: ["!savefig"]
members: ["Motif"]
......
......@@ -26,10 +26,10 @@ plugins:
rendering:
show_root_toc_entry: False
watch:
- varnaapi.py
- src/varnaapi
markdown_extensions:
- footnotes
- pymdownx.highlight
- pymdownx.superfences
- admonition
......@@ -114,7 +114,7 @@ class BasicDraw(VarnaConfig):
self._title = _Title(title, color, size)
def add_bases_style(self, style:BasesStyle, bases:list):
"""Apply a [BasesStyle][varnaapi.BasesStyle] to a list of positions.
"""Apply a [BasesStyle][varnaapi.param.BasesStyle] to a list of positions.
If a position is assigned to more than one styles,
one of them will be randomly used.
......@@ -252,22 +252,22 @@ class BasicDraw(VarnaConfig):
self.savefig(tmp.name, show=True)
class Structure(BasicDraw):
def __init__(self, sequence=None, structure=None):
"""Classic VARNA drawing mode. Constructor from given RNA sequence or/and secondary structure.
If sequence and structure have different size, the larger one is used
and ` `s or `.`s will be added to sequence or structure to complement.
"""Classic VARNA drawing mode. Constructor from given RNA sequence or/and secondary structure.
If sequence and structure have different size, the larger one is used
and ` `s or `.`s will be added to sequence or structure to complement.
Args:
seq: Raw nucleotide sequence for the displayed RNA.
Each base must be encoded in a single character.
Letters others than `A`, `C`, `G`, `U` and space are tolerated.
structure (str or list): RNA (pseudoknotted) secondary structure in one of three formats
Args:
seq: Raw nucleotide sequence for the displayed RNA.
Each base must be encoded in a single character.
Letters others than `A`, `C`, `G`, `U` and space are tolerated.
structure (str or list): RNA (pseudoknotted) secondary structure in one of three formats
- Dot-Bracket Notation (DBN)
- List of pair of int representing a list of base-pairs
- List of int, in which i-th value is `j` if `(i,j)` is a base pair or `-1` if i-th base is unpaired
- Dot-Bracket Notation (DBN)
- List of pair of int representing a list of base-pairs
- List of int, in which i-th value is `j` if `(i,j)` is a base pair or `-1` if i-th base is unpaired
"""
"""
def __init__(self, sequence=None, structure=None):
super().__init__()
self.length = -1
......@@ -445,14 +445,14 @@ class Motif(BasicDraw):
return ["-sequenceDBN", self.sequence, "-structureDBN", self.structure]
def set_dummy_bases_style(self, style):
"""Set style for dummy bases. Argument is a [BasesStyle][varnaapi.BasesStyle] object.
"""Set style for dummy bases. Argument is a [BasesStyle][varnaapi.param.BasesStyle] object.
"""
if not isinstance(style, BasesStyle):
raise Exception('The argument should be BasesStyle object')
self.dummyBasesStyle = style
def set_root_bases_style(self, style):
"""Set style for root bases. Argument is a [BasesStyle][varnaapi.BasesStyle] object.
"""Set style for root bases. Argument is a [BasesStyle][varnaapi.param.BasesStyle] object.
"""
if not isinstance(style, BasesStyle):
raise Exception('The argument should be BasesStyle object')
......
......@@ -142,7 +142,7 @@ BP_STYLES = ['none', 'simple', 'rnaviz', 'lw']
| rnaviz | A small square is drawn at equal distance of the two partners |
| lw | Both canonical and non-canonical base-pairs are rendered according to the Leontis/Westhof nomenclature |
__See Also:__ [VARNA.set_bp_style][varnaapi.VARNA.set_bp_style]
__See Also:__ [VARNA.set_bp_style][varnaapi.param.VarnaConfig.set_bp_style]
"""
......@@ -259,9 +259,9 @@ class _Highlight(_DefaultObj):
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.BasesStyle.__init__] for more details.
See [\_\_init\_\_][varnaapi.param.BasesStyle.__init__] for more details.
__See Also:__ [VARNA.add_bases_style][varnaapi.VARNA.add_bases_style]
__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.
......@@ -281,7 +281,7 @@ class BasesStyle(_DefaultObj):
def update(self, **kwargs):
"""Update component _colors.
Same rule as [\_\_init\_\_][varnaapi.BasesStyle.__init__]
Same rule as [\_\_init\_\_][varnaapi.param.BasesStyle.__init__]
"""
# if fill is None and outline is None and label is None and number is None:
# raise Exception("At least one should not be None")
......@@ -364,14 +364,14 @@ class BaseAnnotation(_Annotation):
super().__init__(text, 'B', int(anchor), color, size)
class LoopAnnotation(_Annotation):
"""Same as [BaseAnnotation][varnaapi.BaseAnnotation] but on a loop.
"""Same as [BaseAnnotation][varnaapi.param.BaseAnnotation] but on a loop.
Argument `anchor` can be index of any base in the loop of interest.
"""
def __init__(self, text, anchor, color="#000000", size=12):
super().__init__(text, 'L', int(anchor), color, size)
class HelixAnnotation(_Annotation):
"""Same as [BaseAnnotation][varnaapi.BaseAnnotation] but on an helix.
"""Same as [BaseAnnotation][varnaapi.param.BaseAnnotation] but on an helix.
Argument `anchor` can be index of any base in the helix of interest.
"""
def __init__(self, text, anchor, color="#000000", size=12):
......@@ -380,7 +380,7 @@ class HelixAnnotation(_Annotation):
class StaticAnnotation(_Annotation):
def __init__(self, text, x, y, color="#000000", size=12):
"""Annotation on a specified position in VARNA drawing.
Unlike [BaseAnnotation][varnaapi.BaseAnnotation], argument `anchor` is omitted.
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
......@@ -530,7 +530,7 @@ class VarnaConfig:
self.update(algorithm=algo)
def set_bp_style(self, style):
"""Set default style for base-pairs rendering, chosen among [BP_STYLES][varnaapi.BP_STYLES]
"""Set default style for base-pairs rendering, chosen among [BP_STYLES][varnaapi.param.BP_STYLES]
__Note:__ `lw` is set by default
......
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