# Layouts and Coordinates

Functions to compute coordinate layouts for secondary structure plots.

  Defines

  VRNA_PLOT_TYPE_SIMPLE
    #include <ViennaRNA/plotting/layouts.h>

    Definition of Plot type simple

    This is the plot type definition for several RNA structure plotting functions telling them to use Simple plotting algorithm

    See also

    rna_plot_type, vrna_file_PS_rnaplot_a(), vrna_file_PS_rnaplot(), svg_rna_plot(), gmlRNA(), ssv_rna_plot(), xrna_plot()

  VRNA_PLOT_TYPE_NAVIEW
    #include <ViennaRNA/plotting/layouts.h>

    Definition of Plot type Naview

    This is the plot type definition for several RNA structure plotting functions telling them to use Naview plotting algorithm [Bruccoleri and Heinrich, 1988] .

    See also

    rna_plot_type, vrna_file_PS_rnaplot_a(), vrna_file_PS_rnaplot(), svg_rna_plot(), gmlRNA(), ssv_rna_plot(), xrna_plot()

  VRNA_PLOT_TYPE_CIRCULAR
    #include <ViennaRNA/plotting/layouts.h>

    Definition of Plot type Circular

    This is the plot type definition for several RNA structure plotting functions telling them to produce a Circular plot

    See also

    rna_plot_type, vrna_file_PS_rnaplot_a(), vrna_file_PS_rnaplot(), svg_rna_plot(), gmlRNA(), ssv_rna_plot(), xrna_plot()

  VRNA_PLOT_TYPE_TURTLE
    #include <ViennaRNA/plotting/layouts.h>

    Definition of Plot type Turtle [Wiegreffe et al., 2019] .

  VRNA_PLOT_TYPE_PUZZLER
    #include <ViennaRNA/plotting/layouts.h>

    Definition of Plot type RNApuzzler [Wiegreffe et al., 2019] .

  VRNA_PLOT_TYPE_DEFAULT
    #include <ViennaRNA/plotting/layouts.h>

  Typedefs

  typedef struct vrna_plot_layout_s vrna_plot_layout_t
    #include <ViennaRNA/plotting/layouts.h>

    RNA secondary structure figure layout.

    See also

    vrna_plot_layout(), vrna_plot_layout_free(), vrna_plot_layout_simple(), vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler()

  Functions

  vrna_plot_layout_t *vrna_plot_layout(const char *structure, unsigned int plot_type)
    #include <ViennaRNA/plotting/layouts.h>

    Create a layout (coordinates, etc.) for a secondary structure plot.

    This function can be used to create a secondary structure nucleotide layout that is then further processed by an actual plotting function. The layout algorithm can be specified using the `plot_type` parameter, and the following algorithms are currently supported:

    - VRNA_PLOT_TYPE_SIMPLE

    - VRNA_PLOT_TYPE_NAVIEW

    - VRNA_PLOT_TYPE_CIRCULAR

    - VRNA_PLOT_TYPE_TURTLE

    - VRNA_PLOT_TYPE_PUZZLER

    Passing an unsupported selection leads to the default algorithm VRNA_PLOT_TYPE_NAVIEW

    See also

    vrna_plot_layout_free(), vrna_plot_layout_simple(), vrna_plot_layout_naview(), vrna_plot_layout_circular(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), vrna_plot_coords(), vrna_file_PS_rnaplot_layout()

    Note

    If only X-Y coordinates of the corresponding structure layout are required, consider using vrna_plot_coords() instead!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

      - plot_type – The layout algorithm to be used

    Returns:

      The layout data structure for the provided secondary structure

  vrna_plot_layout_t *vrna_plot_layout_simple(const char *structure)
    #include <ViennaRNA/plotting/layouts.h>

    Create a layout (coordinates, etc.) for a simple secondary structure plot.

    This function basically is a wrapper to vrna_plot_layout() that passes the `plot_type` VRNA_PLOT_TYPE_SIMPLE.

    See also

    vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_naview(), vrna_plot_layout_circular(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), vrna_plot_coords_simple(), vrna_file_PS_rnaplot_layout()

    Note

    If only X-Y coordinates of the corresponding structure layout are required, consider using vrna_plot_coords_simple() instead!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

    Returns:

      The layout data structure for the provided secondary structure

  vrna_plot_layout_t *vrna_plot_layout_circular(const char *structure)
    #include <ViennaRNA/plotting/layouts.h>

    Create a layout (coordinates, etc.) for a circular secondary structure plot.

    This function basically is a wrapper to vrna_plot_layout() that passes the `plot_type` VRNA_PLOT_TYPE_CIRCULAR.

    See also

    vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_naview(), vrna_plot_layout_simple(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), vrna_plot_coords_circular(), vrna_file_PS_rnaplot_layout()

    Note

    If only X-Y coordinates of the corresponding structure layout are required, consider using vrna_plot_coords_circular() instead!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

    Returns:

      The layout data structure for the provided secondary structure

  vrna_plot_layout_t *vrna_plot_layout_turtle(const char *structure)
    #include <ViennaRNA/plotting/layouts.h>

    Create a layout (coordinates, etc.) for a secondary structure plot using the Turtle Algorithm [Wiegreffe et al., 2019] .

    This function basically is a wrapper to vrna_plot_layout() that passes the `plot_type` VRNA_PLOT_TYPE_TURTLE.

    See also

    vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_simple(), vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_puzzler(), vrna_plot_coords_turtle(), vrna_file_PS_rnaplot_layout()

    Note

    If only X-Y coordinates of the corresponding structure layout are required, consider using vrna_plot_coords_turtle() instead!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

    Returns:

      The layout data structure for the provided secondary structure

  vrna_plot_layout_t *vrna_plot_layout_puzzler(const char *structure, vrna_plot_options_puzzler_t *options)
    #include <ViennaRNA/plotting/layouts.h>

    Create a layout (coordinates, etc.) for a secondary structure plot using the RNApuzzler Algorithm [Wiegreffe et al., 2019] .

    This function basically is a wrapper to vrna_plot_layout() that passes the `plot_type` VRNA_PLOT_TYPE_PUZZLER.

    See also

    vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_simple(), vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), vrna_plot_coords_puzzler(), vrna_file_PS_rnaplot_layout()

    Note

    If only X-Y coordinates of the corresponding structure layout are required, consider using vrna_plot_coords_puzzler() instead!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

    Returns:

      The layout data structure for the provided secondary structure

  void vrna_plot_layout_free(vrna_plot_layout_t *layout)
    #include <ViennaRNA/plotting/layouts.h>

    Free memory occupied by a figure layout data structure.

    See also

    vrna_plot_layout_t, vrna_plot_layout(), vrna_plot_layout_simple(), vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), vrna_file_PS_rnaplot_layout()

    Parameters:

      - layout – The layout data structure to free

  int vrna_plot_coords(const char *structure, float **x, float **y, int plot_type)
    #include <ViennaRNA/plotting/layouts.h>

    Compute nucleotide coordinates for secondary structure plot.

    This function takes a secondary structure and computes X-Y coordinates for each nucleotide that then can be used to create a structure plot. The parameter `plot_type` is used to select the underlying layout algorithm. Currently, the following selections are provided:

    - VRNA_PLOT_TYPE_SIMPLE

    - VRNA_PLOT_TYPE_NAVIEW

    - VRNA_PLOT_TYPE_CIRCULAR

    - VRNA_PLOT_TYPE_TURTLE

    - VRNA_PLOT_TYPE_PUZZLER

    Passing an unsupported selection leads to the default algorithm VRNA_PLOT_TYPE_NAVIEW

    Here is a simple example how to use this function, assuming variable `structure` contains a valid dot-bracket string:

        float *x, *y;

        if (vrna_plot_coords(structure, &x, &y)) {
          printf("all fine");
        } else {
          printf("some failure occured!");
        }

        free(x);
        free(y);

    See also

    vrna_plot_coords_pt(), vrna_plot_coords_simple(), vrna_plot_coords_naview() vrna_plot_coords_circular(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler()

    Note

    On success, this function allocates memory for X and Y coordinates and assigns the pointers at addressess `x` and `y` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

      - plot_type – The layout algorithm to be used

    Returns:

      The length of the structure on success, 0 otherwise

  int vrna_plot_coords_pt(const short *pt, float **x, float **y, int plot_type)
    #include <ViennaRNA/plotting/layouts.h>

    Compute nucleotide coordinates for secondary structure plot.

    Same as vrna_plot_coords() but takes a pair table with the structure information as input.

    See also

    vrna_plot_coords(), vrna_plot_coords_simple_pt(), vrna_plot_coords_naview_pt() vrna_plot_coords_circular_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt()

    Note

    On success, this function allocates memory for X and Y coordinates and assigns the pointers at addressess `x` and `y` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - pt – The pair table that holds the secondary structure

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

      - plot_type – The layout algorithm to be used

    Returns:

      The length of the structure on success, 0 otherwise

  int vrna_plot_coords_simple(const char *structure, float **x, float **y)
    #include <ViennaRNA/plotting/layouts.h>

    Compute nucleotide coordinates for secondary structure plot the Simple way

    This function basically is a wrapper to vrna_plot_coords() that passes the `plot_type` VRNA_PLOT_TYPE_SIMPLE.

    Here is a simple example how to use this function, assuming variable `structure` contains a valid dot-bracket string:

        float *x, *y;

        if (vrna_plot_coords_simple(structure, &x, &y)) {
          printf("all fine");
        } else {
          printf("some failure occured!");
        }

        free(x);
        free(y);

    See also

    vrna_plot_coords(), vrna_plot_coords_simple_pt(), vrna_plot_coords_circular(), vrna_plot_coords_naview(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler()

    Note

    On success, this function allocates memory for X and Y coordinates and assigns the pointers at addressess `x` and `y` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

    Returns:

      The length of the structure on success, 0 otherwise

  int vrna_plot_coords_simple_pt(const short *pt, float **x, float **y)
    #include <ViennaRNA/plotting/layouts.h>

    Compute nucleotide coordinates for secondary structure plot the Simple way

    Same as vrna_plot_coords_simple() but takes a pair table with the structure information as input.

    See also

    vrna_plot_coords_pt(), vrna_plot_coords_simple(), vrna_plot_coords_circular_pt(), vrna_plot_coords_naview_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt()

    Note

    On success, this function allocates memory for X and Y coordinates and assigns the pointers at addressess `x` and `y` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - pt – The pair table that holds the secondary structure

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

    Returns:

      The length of the structure on success, 0 otherwise

  int vrna_plot_coords_circular(const char *structure, float **x, float **y)
    #include <ViennaRNA/plotting/layouts.h>

    Compute coordinates of nucleotides mapped in equal distancies onto a unit circle.

    This function basically is a wrapper to vrna_plot_coords() that passes the `plot_type` VRNA_PLOT_TYPE_CIRCULAR.

    In order to draw nice arcs using quadratic bezier curves that connect base pairs one may calculate a second tangential point \(P^t\) in addition to the actual R2 coordinates. the simplest way to do so may be to compute a radius scaling factor \(rs\) in the interval \([0,1]\) that weights the proportion of base pair span to the actual length of the sequence. This scaling factor can then be used to calculate the coordinates for \(P^t\), i.e.

    \[ P^{t}_x[i] = X[i] * rs \]

    and

    \[ P^{t}_y[i] = Y[i] * rs \]
    .

    See also

    vrna_plot_coords(), vrna_plot_coords_circular_pt(), vrna_plot_coords_simple(), vrna_plot_coords_naview(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler()

    Note

    On success, this function allocates memory for X and Y coordinates and assigns the pointers at addressess `x` and `y` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

    Returns:

      The length of the structure on success, 0 otherwise

  int vrna_plot_coords_circular_pt(const short *pt, float **x, float **y)
    #include <ViennaRNA/plotting/layouts.h>

    Compute nucleotide coordinates for a Circular Plot

    Same as vrna_plot_coords_circular() but takes a pair table with the structure information as input.

    See also

    vrna_plot_coords_pt(), vrna_plot_coords_circular(), vrna_plot_coords_simple_pt(), vrna_plot_coords_naview_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt()

    Note

    On success, this function allocates memory for X and Y coordinates and assigns the pointers at addressess `x` and `y` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - pt – The pair table that holds the secondary structure

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

    Returns:

      The length of the structure on success, 0 otherwise

  int vrna_plot_coords_puzzler(const char *structure, float **x, float **y, double **arc_coords, vrna_plot_options_puzzler_t *options)
    #include <ViennaRNA/plotting/RNApuzzler/RNApuzzler.h>

    Compute nucleotide coordinates for secondary structure plot using the RNApuzzler algorithm [Wiegreffe et al., 2019] .

    This function basically is a wrapper to vrna_plot_coords() that passes the `plot_type` VRNA_PLOT_TYPE_PUZZLER.

    Here is a simple example how to use this function, assuming variable `structure` contains a valid dot-bracket string and using the default options (`options` = NULL):

        float  *x, *y;
        double *arcs;

        if (vrna_plot_coords_puzzler(structure, &x, &y, &arcs, NULL)) {
          printf("all fine");
        } else {
          printf("some failure occured!");
        }

        free(x);
        free(y);
        free(arcs);

    See also

    vrna_plot_coords(), vrna_plot_coords_puzzler_pt(), vrna_plot_coords_circular(), vrna_plot_coords_simple(), vrna_plot_coords_turtle(), vrna_plot_coords_naview(), vrna_plot_options_puzzler()

    Note

    On success, this function allocates memory for X, Y and arc coordinates and assigns the pointers at addressess `x`, `y` and `arc_coords` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

      - arc_coords – [inout] The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure)

      - options – The options for the RNApuzzler algorithm (or NULL)

    Returns:

      The length of the structure on success, 0 otherwise

  int vrna_plot_coords_puzzler_pt(short const *const pair_table, float **x, float **y, double **arc_coords, vrna_plot_options_puzzler_t *puzzler)
    #include <ViennaRNA/plotting/RNApuzzler/RNApuzzler.h>

    Compute nucleotide coordinates for secondary structure plot using the RNApuzzler algorithm [Wiegreffe et al., 2019] .

    Same as vrna_plot_coords_puzzler() but takes a pair table with the structure information as input.

    See also

    vrna_plot_coords_pt(), vrna_plot_coords_puzzler(), vrna_plot_coords_circular_pt(), vrna_plot_coords_simple_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_naview_pt()

    Note

    On success, this function allocates memory for X, Y and arc coordinates and assigns the pointers at addressess `x`, `y` and `arc_coords` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - pt – The pair table that holds the secondary structure

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

      - arc_coords – [inout] The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure)

      - options – The options for the RNApuzzler algorithm (or NULL)

    Returns:

      The length of the structure on success, 0 otherwise

  vrna_plot_options_puzzler_t *vrna_plot_options_puzzler(void)
    #include <ViennaRNA/plotting/RNApuzzler/RNApuzzler.h>

    Create an RNApuzzler options data structure.

    See also

    vrna_plot_options_puzzler_free(), vrna_plot_coords_puzzler(), vrna_plot_coords_puzzler_pt(), vrna_plot_layout_puzzler()

    Returns:

      An RNApuzzler options data structure with default settings

  void vrna_plot_options_puzzler_free(vrna_plot_options_puzzler_t *options)
    #include <ViennaRNA/plotting/RNApuzzler/RNApuzzler.h>

    Free memory occupied by an RNApuzzler options data structure.

    See also

    vrna_plot_options_puzzler(), vrna_plot_coords_puzzler(), vrna_plot_coords_puzzler_pt(), vrna_plot_layout_puzzler()

    Parameters:

      - options – A pointer to the options data structure to free

  int vrna_plot_coords_turtle(const char *structure, float **x, float **y, double **arc_coords)
    #include <ViennaRNA/plotting/RNApuzzler/RNAturtle.h>

    Compute nucleotide coordinates for secondary structure plot using the RNAturtle algorithm [Wiegreffe et al., 2019] .

    This function basically is a wrapper to vrna_plot_coords() that passes the `plot_type` VRNA_PLOT_TYPE_TURTLE.

    Here is a simple example how to use this function, assuming variable `structure` contains a valid dot-bracket string:

        float  *x, *y;
        double *arcs;

        if (vrna_plot_coords_turtle(structure, &x, &y, &arcs)) {
          printf("all fine");
        } else {
          printf("some failure occured!");
        }

        free(x);
        free(y);
        free(arcs);

    See also

    vrna_plot_coords(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_circular(), vrna_plot_coords_simple(), vrna_plot_coords_naview(), vrna_plot_coords_puzzler()

    Note

    On success, this function allocates memory for X, Y and arc coordinates and assigns the pointers at addressess `x`, `y` and `arc_coords` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - structure – The secondary structure in dot-bracket notation

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

      - arc_coords – [inout] The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure)

    Returns:

      The length of the structure on success, 0 otherwise

  int vrna_plot_coords_turtle_pt(short const *const pair_table, float **x, float **y, double **arc_coords)
    #include <ViennaRNA/plotting/RNApuzzler/RNAturtle.h>

    Compute nucleotide coordinates for secondary structure plot using the RNAturtle algorithm [Wiegreffe et al., 2019] .

    Same as vrna_plot_coords_turtle() but takes a pair table with the structure information as input.

    See also

    vrna_plot_coords_pt(), vrna_plot_coords_turtle(), vrna_plot_coords_circular_pt(), vrna_plot_coords_simple_pt(), vrna_plot_coords_puzzler_pt(), vrna_plot_coords_naview_pt()

    Note

    On success, this function allocates memory for X, Y and arc coordinates and assigns the pointers at addressess `x`, `y` and `arc_coords` to the corresponding memory locations. It’s the users responsibility to cleanup this memory after usage!

    Parameters:

      - pt – The pair table that holds the secondary structure

      - x – [inout] The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure)

      - y – [inout] The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure)

      - arc_coords – [inout] The address of a pointer that will hold arc coordinates (pointer will point to memory, or NULL on failure)

    Returns:

      The length of the structure on success, 0 otherwise

  struct vrna_plot_layout_s

    Public Members

    unsigned int length
    float *x
    float *y
    double *arcs
    int bbox[4]
  struct vrna_plot_options_puzzler_t
    #include <ViennaRNA/plotting/RNApuzzler/RNApuzzler.h>

    Options data structure for RNApuzzler algorithm implementation.

    Public Members

    short drawArcs
    double paired
    double unpaired
    short checkAncestorIntersections
    short checkSiblingIntersections
    short checkExteriorIntersections
    short allowFlipping
    short optimize
    int maximumNumberOfConfigChangesAllowed
    char *config
    const char *filename
    int numberOfChangesAppliedToConfig
    int psNumber