Skip to content

Latest commit

 

History

History
287 lines (220 loc) · 9.72 KB

README.md

File metadata and controls

287 lines (220 loc) · 9.72 KB
Raw

PlotRNA.jl

Build Status Aqua QA

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 package implemented in Java, offering advanced features
  • R2R.plot: uses R2R 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)

using PlotRNA
# plot_structure: draw an image of a secondary structure
dbn = "(((...)))"
seq = "GGGAAACCC"
plot_structure(dbn)
plot_structure(dbn; savepath="rna.png")
# 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.

using CairoMakie, PlotRNA
PlotRNA.plot_structure_makie("(((...)))")

Terminal plotting with UnicodePlots

Plotting in the terminal is supported via UnicodePlots with coordinates generated by ViennaRNA.

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: marcom/ViennaRNA.jl#13.

Plot structures with VARNA

This uses the very featureful VARNA program via its command-line interface.

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:

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.

  • 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 program via its command-line interface.

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. R2R is licensed under the GNU GPL.

Related Julia packages for RNA secondary structures