Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/marcom/plotrna.jl

Plot nucleic acid secondary structures with Julia
https://github.com/marcom/plotrna.jl

julia rna rna-secondary-structure

Last synced: 3 months ago
JSON representation

Plot nucleic acid secondary structures with Julia

Awesome Lists containing this project

README 

        
# PlotRNA.jl



[![Build Status](https://github.com/marcom/PlotRNA.jl/actions/workflows/CI.yml/badge.svg?branch=main)](https://github.com/marcom/PlotRNA.jl/actions/workflows/CI.yml?query=branch%3Amain)

[![Aqua QA](https://raw.githubusercontent.com/JuliaTesting/Aqua.jl/master/badge.svg)](https://github.com/JuliaTesting/Aqua.jl)



Plot nucleic acid secondary structures with Julia.



There are currently four different backends:



- `plot_structure`, `plot_structure_makie`: basic plotting implemented

  in Julia using `Luxor` or `CairoMakie` respectively. These functions

  use `ViennaRNA` behind the scenes to generate the coordinates

- `PlotRNA.uniplot`: basic text-mode plotting in the terminal using

  `UnicodePlots`

- `VARNA.plot`, `VARNA.plot_compare`: uses the

  [VARNA](https://varna.lri.fr/) package implemented in Java, offering

  advanced features

- `R2R.plot`: uses [R2R](https://zashaweinberglab.org/research/) for

  plotting multiple sequence alignments with consensus structures



If you use the VARNA or R2R interface in this package, please make

sure to cite the corresponding VARNA or R2R publication.



Note: to use `plot_structure_makie`, `CairoMakie` must be loaded

before `PlotRNA`. To use `PlotRNA.uniplot`, `UnicodePlots` must be

loaded before loading `PlotRNA`. This is to reduce the loading time of

this package if these features are not used. See below for details.



## Installation



Enter the package mode from the Julia REPL by pressing `]` and then

install with

```

add PlotRNA

```



Please excuse the rather long compile times on installation (around 5

minutes on julia-1.9).



## Usage



### Built-in plotting functionality (basic at the moment)



```julia

using PlotRNA

```



```julia

# plot_structure: draw an image of a secondary structure

dbn = "(((...)))"

seq = "GGGAAACCC"

plot_structure(dbn)

plot_structure(dbn; savepath="rna.png")

```



```julia

# color bases according to their probability of being basepaired or

# unpaired

using ViennaRNA: prob_of_basepairs

plot_structure(dbn; sequence=seq,

                    base_colors=prob_of_basepairs(seq, dbn))

```



There is also an experimental `PlotRNA.plot_structure_makie` which

looks a bit nicer but has a larger time to first plot (on julia-1.9:

about 9 seconds for `using CairoMakie, PlotRNA` and 7 seconds for

`PlotRNA.plot_structure_makie("(((...)))")`). Subsequent plots are

very fast though.



```julia

using CairoMakie, PlotRNA

PlotRNA.plot_structure_makie("(((...)))")

```



### Terminal plotting with UnicodePlots



Plotting in the terminal is supported via UnicodePlots with

coordinates generated by ViennaRNA.



```julia

using UnicodePlots, PlotRNA

PlotRNA.uniplot("(((...)))")

```



Note: this is still considered experimental.  There are still some

problems with plot sizes and aspect ratios. Additionally, when calling

`uniplot` with an illegal structure or unbalanced parentheses it is

possible to produce a segfault (coming from `plot_coords` in ViennaRNA

that is used to generate coordinates for plotting).  See:

[https://github.com/marcom/ViennaRNA.jl/issues/13](https://github.com/marcom/ViennaRNA.jl/issues/13).



### Plot structures with VARNA



This uses the very featureful [VARNA](https://varna.lri.fr/) program

via its command-line interface.



```julia

using PlotRNA



VARNA.plot("(((...)))")

VARNA.plot("(((...)))"; seq="GCGAAACGC", savepath="rna.png")

VARNA.plot_compare(dbn1="(((.....)))", seq1="GCGAAAAACGC",

                   dbn2="((-...---))", seq2="GG-AAA---CC")

```



#### Note: Java must be installed for VARNA plotting to work



You will need a working Java installation (can be headless i think).

You can test this by running:

```julia

Sys.which("java")

```

If you get a file path (e.g. `"/usr/bin/java"`) and not `nothing`,

plotting with VARNA should work.



The VARNA jar file will get downloaded automatically the first time

you plot something with one of the VARNA functions. It gets stored in

the Julia artifacts directory.



#### VARNA plot options



##### Basic options



- `savepath=""`: output file path where the image should be written

  to, or a temporary file if not set. The file ending determines the

  output file type.



- `fileformat="svg"`: output file format, only used if `savepath` is

  not set.



- `verbose=false`: print stdout and stderr captured from VARNA.



##### VARNA options



More details about these parameters can be found in the [VARNA

documentation](https://varna.lri.fr/index.php?lang=en&page=command&css=varna).



- `algorithm=:radiate`: RNA graph layout algorithm to

   use. Options are: `:line`, `:circular`, `:naview`, `:radiate.`.



- `additional_basepairs=""`: the option is called `-auxBPs` in

  VARNA. String of the form `"(i1,j1);(i2,j2):opt1=val1,opt2=val2;..."`.

  - `edge5`, `edge3=[wc|h|s]`: classification of noncanonical basepair

    as defined by Leontis & Westhof. Values are "wc" (Watson-Crick

    edge), "h" (Hoogsteen edge), "s" (sugar edge)

  - `stericity=[cis|trans]`: strand orientation

  - `color`: base pair color as string

  - `thickness`: basepair thickness as integer



  Example: `additional_basepairs="(1,10);(2,9):edge5=h,edge3=s,stericity=cis,color=#ff0000,thickness=5"`



- `annotations=""`: annotation string of the form

  `"text1:opt1=val1,...;type=T2,opt2=val2;..."`.

  - `type=[P|B|H|L]`: can be `P` (static), `B` (anchored on base), `H` (anchored

    on helix), or `L` (anchored on loop)

  - `x`, `y`: x and y coordinates for a static annotation (`P`)

  - `anchor`: which base should annotation be anchored to (not

    applicable for static annotations)

  - `size` font size as an integer

  - `color` as a string e.g. "#FF0000"



  Example: `annotations="Static annotation:type=P,x=100,y=50,size=12,color=#ff0000;Base annotation:type=B,anchor=42"`



- `auto_helices=false`: annotate helix n with "Hn"

- `auto_interior_loops=false`: annotate interior loop n with "In"

- `auto_terminal_loops=false`: annotate terminal loop n with "Tn"

- `backbone_color=""`

- `background_color=""`

- `base_inner_color=""`

- `base_name_color=""`

- `base_num_color=""`

- `base_outline_color=""`



- `base_style_define=String[]`: corresponds to the `-basesStyleX` options in VARNA.

- `base_style_apply_on=String[]`: corresponds to the `-applyBasesStyleXon` options in VARNA.



- `basepair_color=""`



- `basepair_style=""`: can be "none" (no basepairs drawn), "line",

  "rnaviz" (draw square equidistant from both bases), or "lw"

  (Leontis/Westhof rendering).



- `border_dist="0x0"`: x and y distance of drawing area from border,

  e.g. `10x20`



- `chemical_probing=""`: markers on the RNA backbone, for example from

   chemical probing. String of the form

   `"a1-b1:opt1=v1,...;a2-b2:opt1=v2,..."`.  Here a1 and b1 are

   adjacent bases, the marker is placed on the backbone between them.

   - `glyph=[arrow|dot|pin|triangle]`: shape of annotation

   - `dir=[in|out]`: direction of annotation

   - `intensity=float`: annotation thickness

   - `color=color`



  Example: `chemical_probing="2-3:glyph=triangle,dir=in,intensity=1.0,color=#ff0000;4-5:glyph=dot"`



- `color_map=Float64[]`: color map for coloring bases

- `color_map_caption=""`

- `color_map_min=0.0`: color map range minimum

- `color_map_max=1.0`: color map range maximum



- `color_map_style="heat"`: color map style. Predefined styles are:

  "red", "blue", "green", "heat", "energy", and "bw". A custom palette

  can be passed in the form `"0:#ff0000;1:#ffffff"`.



- `draw_backbone=true`

- `draw_bases=true`

- `draw_noncanonical_bp=true`

- `draw_tertiary_bp=true`

- `fill_bases=true`



- `flat_radiate_mode=true`: align exterior loop horizontally in the

  `:radiate` layout algorithm.



- `highlight_region=""`: string for highlighting consecutive regions

  of bases of the format `"i1-j1:opt1=val1,...;i2-j2:opt1=val2,..."`. Options are:

  - `radius`: thickness of highlight

  - `fill=color`: highlight fill color

  - `outline=color`: highlight outline color



  Example: `highlight_region="2-5:radius=10,fill=#00ff00;7-12:radius=10,fill=#00ff00,outline=#000000"`



- `line_mode_bp_vertical_scale=1.0`: vertical scaling of basepair

  lines in the `:line` layout algorithm



- `nonstandard_bases_color=""`

- `numbering_period=10`: numbering interval for bases

- `resolution=1.0`

- `rotation=0.0`: rotate RNA structure by an angle in degrees

- `show_errors=true`

- `show_warnings=true`

- `space_between_bases=1.0`

- `title=""`: plot title

- `title_color=""`

- `title_size=18`: title font size

- `zoom=1.0`



### Plot structures with R2R



This uses the

[R2R](https://bmcbioinformatics.biomedcentral.com/articles/10.1186/1471-2105-12-3)

program via its command-line interface.



```julia

using PlotRNA, BioStockholm

msa = parse(MSA, """

    # STOCKHOLM 1.0

    human        ACACGCGAAA.GCGCAA.CAAACGUGCACGG

    chimp        GAAUGUGAAAAACACCA.CUCUUGAGGACCU

    bigfoot      UUGAG.UUCG..CUCGUUUUCUCGAGUACAC

    #=GC SS_cons ...<<<.....>>>....<<....>>.....

    //

    """)



# or alternatively

msa = MSA{Char}(;

    seq = Dict("human"   => "ACACGCGAAA.GCGCAA.CAAACGUGCACGG",

               "chimp"   => "GAAUGUGAAAAACACCA.CUCUUGAGGACCU",

               "bigfoot" => "UUGAG.UUCG..CUCGUUUUCUCGAGUACAC"),

     GC = Dict("SS_cons" => "...<<<.....>>>....<<....>>.....")

)



# this should show a svg image in Pluto or Jupyter

plot = R2R.plot(msa)



# save the svg image to a file

write("out.svg", plot.svg)

```



## Licensing



All code in this repository is licensed under the MIT license, a copy

of which can be found in the `LICENSE` file. VARNA is licensed under

the GNU GPL as mentioned on the [VARNA

homepage](https://varna.lri.fr/). R2R is licensed under the GNU GPL.



## Related Julia packages for RNA secondary structures



- [FoldRNA.jl](https://github.com/marcom/FoldRNA.jl)

- [Infernal.jl](https://github.com/cossio/Infernal.jl)

- [LinearFold.jl](https://github.com/marcom/LinearFold.jl)

- [Rfam.jl](https://github.com/cossio/Rfam.jl)

- [RNAstructure.jl](https://github.com/marcom/RNAstructure.jl)

- [ViennaRNA.jl](https://github.com/marcom/ViennaRNA.jl)