1 #ifndef VIENNA_RNA_PACKAGE_PLOT_LAYOUTS_H 2 #define VIENNA_RNA_PACKAGE_PLOT_LAYOUTS_H 3 4 #ifdef VRNA_WARN_DEPRECATED 5 # if defined(__clang__) 6 # define DEPRECATED(func, msg) func __attribute__ ((deprecated("", msg))) 7 # elif defined(__GNUC__) 8 # define DEPRECATED(func, msg) func __attribute__ ((deprecated(msg))) 9 # else 10 # define DEPRECATED(func, msg) func 11 # endif 12 #else 13 # define DEPRECATED(func, msg) func 14 #endif 15 16 /** 17 * @file ViennaRNA/plotting/layouts.h 18 * @ingroup plotting_utils 19 * @brief Secondary structure plot layout algorithms 20 */ 21 22 /** 23 * @addtogroup plot_layout_utils 24 * @{ 25 * @brief Functions to compute coordinate layouts for secondary structure plots 26 */ 27 28 29 /** 30 * @brief RNA secondary structure figure layout 31 * 32 * @see vrna_plot_layout(), vrna_plot_layout_free(), vrna_plot_layout_simple(), 33 * vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), 34 * vrna_plot_layout_puzzler() 35 */ 36 typedef struct vrna_plot_layout_s vrna_plot_layout_t; 37 38 39 #include <ViennaRNA/datastructures/basic.h> 40 #include <ViennaRNA/plotting/naview.h> 41 #include "ViennaRNA/plotting/RNApuzzler/RNAturtle.h" 42 #include "ViennaRNA/plotting/RNApuzzler/RNApuzzler.h" 43 44 45 /** 46 * @brief Definition of Plot type <i>simple</i> 47 * 48 * This is the plot type definition for several RNA structure plotting functions telling 49 * them to use <b>Simple</b> plotting algorithm 50 * 51 * @see rna_plot_type, vrna_file_PS_rnaplot_a(), vrna_file_PS_rnaplot(), svg_rna_plot(), gmlRNA(), ssv_rna_plot(), xrna_plot() 52 */ 53 #define VRNA_PLOT_TYPE_SIMPLE 0 54 55 /** 56 * @brief Definition of Plot type <i>Naview</i> 57 * 58 * This is the plot type definition for several RNA structure plotting functions telling 59 * them to use <b>Naview</b> plotting algorithm @cite bruccoleri:1988. 60 * 61 * @see rna_plot_type, vrna_file_PS_rnaplot_a(), vrna_file_PS_rnaplot(), svg_rna_plot(), gmlRNA(), ssv_rna_plot(), xrna_plot() 62 */ 63 #define VRNA_PLOT_TYPE_NAVIEW 1 64 65 /** 66 * @brief Definition of Plot type <i>Circular</i> 67 * 68 * This is the plot type definition for several RNA structure plotting functions telling 69 * them to produce a <b>Circular plot</b> 70 * 71 * @see rna_plot_type, vrna_file_PS_rnaplot_a(), vrna_file_PS_rnaplot(), svg_rna_plot(), gmlRNA(), ssv_rna_plot(), xrna_plot() 72 */ 73 #define VRNA_PLOT_TYPE_CIRCULAR 2 74 75 /** 76 * @brief Definition of Plot type <i>Turtle</i> @cite wiegreffe:2018 77 * 78 */ 79 #define VRNA_PLOT_TYPE_TURTLE 3 80 81 /** 82 * @brief Definition of Plot type <i>RNApuzzler</i> @cite wiegreffe:2018 83 * 84 */ 85 #define VRNA_PLOT_TYPE_PUZZLER 4 86 87 88 struct vrna_plot_layout_s { 89 unsigned int length; 90 float *x; 91 float *y; 92 double *arcs; 93 int bbox[4]; 94 }; 95 96 97 /** 98 * @brief Create a layout (coordinates, etc.) for a secondary structure plot 99 * 100 * This function can be used to create a secondary structure nucleotide layout 101 * that is then further processed by an actual plotting function. The layout 102 * algorithm can be specified using the @p plot_type parameter, and the following 103 * algorithms are currently supported: 104 * - #VRNA_PLOT_TYPE_SIMPLE 105 * - #VRNA_PLOT_TYPE_NAVIEW 106 * - #VRNA_PLOT_TYPE_CIRCULAR 107 * - #VRNA_PLOT_TYPE_TURTLE 108 * - #VRNA_PLOT_TYPE_PUZZLER 109 * 110 * Passing an unsupported selection leads to the default algorithm #VRNA_PLOT_TYPE_NAVIEW 111 * 112 * @note If only X-Y coordinates of the corresponding structure layout are required, consider 113 * using vrna_plot_coords() instead! 114 * 115 * @see vrna_plot_layout_free(), vrna_plot_layout_simple(), vrna_plot_layout_naview(), 116 * vrna_plot_layout_circular(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), 117 * vrna_plot_coords(), vrna_file_PS_rnaplot_layout() 118 * 119 * @param structure The secondary structure in dot-bracket notation 120 * @param plot_type The layout algorithm to be used 121 * @return The layout data structure for the provided secondary structure 122 */ 123 vrna_plot_layout_t * 124 vrna_plot_layout(const char *structure, 125 unsigned int plot_type); 126 127 128 /** 129 * @brief Create a layout (coordinates, etc.) for a <i>simple</i> secondary structure plot 130 * 131 * This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_SIMPLE. 132 * 133 * @note If only X-Y coordinates of the corresponding structure layout are required, consider 134 * using vrna_plot_coords_simple() instead! 135 * 136 * @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_naview(), 137 * vrna_plot_layout_circular(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), 138 * vrna_plot_coords_simple(), vrna_file_PS_rnaplot_layout() 139 * 140 * @param structure The secondary structure in dot-bracket notation 141 * @return The layout data structure for the provided secondary structure 142 */ 143 vrna_plot_layout_t * 144 vrna_plot_layout_simple(const char *structure); 145 146 147 /** 148 * @brief Create a layout (coordinates, etc.) for a secondary structure plot using the <i>Naview Algorithm</i> @cite bruccoleri:1988. 149 * 150 * This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_NAVIEW. 151 * 152 * @note If only X-Y coordinates of the corresponding structure layout are required, consider 153 * using vrna_plot_coords_naview() instead! 154 * 155 * @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_simple(), 156 * vrna_plot_layout_circular(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), 157 * vrna_plot_coords_naview(), vrna_file_PS_rnaplot_layout() 158 * 159 * @param structure The secondary structure in dot-bracket notation 160 * @return The layout data structure for the provided secondary structure 161 */ 162 vrna_plot_layout_t * 163 vrna_plot_layout_naview(const char *structure); 164 165 166 /** 167 * @brief Create a layout (coordinates, etc.) for a <i>circular</i> secondary structure plot 168 * 169 * This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_CIRCULAR. 170 * 171 * @note If only X-Y coordinates of the corresponding structure layout are required, consider 172 * using vrna_plot_coords_circular() instead! 173 * 174 * @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_naview(), 175 * vrna_plot_layout_simple(), vrna_plot_layout_turtle(), vrna_plot_layout_puzzler(), 176 * vrna_plot_coords_circular(), vrna_file_PS_rnaplot_layout() 177 * 178 * @param structure The secondary structure in dot-bracket notation 179 * @return The layout data structure for the provided secondary structure 180 */ 181 vrna_plot_layout_t * 182 vrna_plot_layout_circular(const char *structure); 183 184 185 /** 186 * @brief Create a layout (coordinates, etc.) for a secondary structure plot using the <i>Turtle Algorithm</i> @cite wiegreffe:2018 187 * 188 * This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_TURTLE. 189 * 190 * @note If only X-Y coordinates of the corresponding structure layout are required, consider 191 * using vrna_plot_coords_turtle() instead! 192 * 193 * @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_simple(), 194 * vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_puzzler(), 195 * vrna_plot_coords_turtle(), vrna_file_PS_rnaplot_layout() 196 * 197 * @param structure The secondary structure in dot-bracket notation 198 * @return The layout data structure for the provided secondary structure 199 */ 200 vrna_plot_layout_t * 201 vrna_plot_layout_turtle(const char *structure); 202 203 204 /** 205 * @brief Create a layout (coordinates, etc.) for a secondary structure plot using the <i>RNApuzzler Algorithm</i> @cite wiegreffe:2018 206 * 207 * This function basically is a wrapper to vrna_plot_layout() that passes the @p plot_type #VRNA_PLOT_TYPE_PUZZLER. 208 * 209 * @note If only X-Y coordinates of the corresponding structure layout are required, consider 210 * using vrna_plot_coords_puzzler() instead! 211 * 212 * @see vrna_plot_layout_free(), vrna_plot_layout(), vrna_plot_layout_simple(), 213 * vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), 214 * vrna_plot_coords_puzzler(), vrna_file_PS_rnaplot_layout() 215 * 216 * @param structure The secondary structure in dot-bracket notation 217 * @return The layout data structure for the provided secondary structure 218 */ 219 vrna_plot_layout_t * 220 vrna_plot_layout_puzzler(const char *structure, 221 vrna_plot_options_puzzler_t *options); 222 223 224 /** 225 * @brief Free memory occupied by a figure layout data structure 226 * 227 * @see #vrna_plot_layout_t, vrna_plot_layout(), vrna_plot_layout_simple(), 228 * vrna_plot_layout_circular(), vrna_plot_layout_naview(), vrna_plot_layout_turtle(), 229 * vrna_plot_layout_puzzler(), vrna_file_PS_rnaplot_layout() 230 * 231 * @param layout The layout data structure to free 232 */ 233 void 234 vrna_plot_layout_free(vrna_plot_layout_t *layout); 235 236 237 /** 238 * @brief Compute nucleotide coordinates for secondary structure plot 239 * 240 * This function takes a secondary structure and computes X-Y coordinates 241 * for each nucleotide that then can be used to create a structure plot. 242 * The parameter @p plot_type is used to select the underlying layout algorithm. 243 * Currently, the following selections are provided: 244 * - #VRNA_PLOT_TYPE_SIMPLE 245 * - #VRNA_PLOT_TYPE_NAVIEW 246 * - #VRNA_PLOT_TYPE_CIRCULAR 247 * - #VRNA_PLOT_TYPE_TURTLE 248 * - #VRNA_PLOT_TYPE_PUZZLER 249 * 250 * Passing an unsupported selection leads to the default algorithm #VRNA_PLOT_TYPE_NAVIEW 251 * 252 * Here is a simple example how to use this function, assuming variable @p structure contains 253 * a valid dot-bracket string: 254 * @code{.c} 255 * float *x, *y; 256 * 257 * if (vrna_plot_coords(structure, &x, &y)) { 258 * printf("all fine"); 259 * } else { 260 * printf("some failure occured!"); 261 * } 262 * 263 * free(x); 264 * free(y); 265 * @endcode 266 * 267 * @note On success, this function allocates memory for X and Y coordinates and assigns 268 * the pointers at addressess @p x and @p y to the corresponding memory locations. It's 269 * the users responsibility to cleanup this memory after usage! 270 * 271 * @see vrna_plot_coords_pt(), vrna_plot_coords_simple(), vrna_plot_coords_naview() 272 * vrna_plot_coords_circular(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler() 273 * 274 * @param structure The secondary structure in dot-bracket notation 275 * @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) 276 * @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) 277 * @param plot_type The layout algorithm to be used 278 * @return The length of the structure on success, 0 otherwise 279 */ 280 int 281 vrna_plot_coords(const char *structure, 282 float **x, 283 float **y, 284 int plot_type); 285 286 287 /** 288 * @brief Compute nucleotide coordinates for secondary structure plot 289 * 290 * Same as vrna_plot_coords() but takes a pair table with the structure 291 * information as input. 292 * 293 * @note On success, this function allocates memory for X and Y coordinates and assigns 294 * the pointers at addressess @p x and @p y to the corresponding memory locations. It's 295 * the users responsibility to cleanup this memory after usage! 296 * 297 * @see vrna_plot_coords(), vrna_plot_coords_simple_pt(), vrna_plot_coords_naview_pt() 298 * vrna_plot_coords_circular_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt() 299 * 300 * @param pt The pair table that holds the secondary structure 301 * @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) 302 * @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) 303 * @param plot_type The layout algorithm to be used 304 * @return The length of the structure on success, 0 otherwise 305 */ 306 int 307 vrna_plot_coords_pt(const short *pt, 308 float **x, 309 float **y, 310 int plot_type); 311 312 313 /** 314 * @brief Compute nucleotide coordinates for secondary structure plot the <i>Simple way</i> 315 * 316 * This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_SIMPLE. 317 * 318 * Here is a simple example how to use this function, assuming variable @p structure contains 319 * a valid dot-bracket string: 320 * @code{.c} 321 * float *x, *y; 322 * 323 * if (vrna_plot_coords_simple(structure, &x, &y)) { 324 * printf("all fine"); 325 * } else { 326 * printf("some failure occured!"); 327 * } 328 * 329 * free(x); 330 * free(y); 331 * @endcode 332 * 333 * @note On success, this function allocates memory for X and Y coordinates and assigns 334 * the pointers at addressess @p x and @p y to the corresponding memory locations. It's 335 * the users responsibility to cleanup this memory after usage! 336 * 337 * @see vrna_plot_coords(), vrna_plot_coords_simple_pt(), vrna_plot_coords_circular(), 338 * vrna_plot_coords_naview(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler() 339 * 340 * @param structure The secondary structure in dot-bracket notation 341 * @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) 342 * @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) 343 * @return The length of the structure on success, 0 otherwise 344 */ 345 int 346 vrna_plot_coords_simple(const char *structure, 347 float **x, 348 float **y); 349 350 351 /** 352 * @brief Compute nucleotide coordinates for secondary structure plot the <i>Simple way</i> 353 * 354 * Same as vrna_plot_coords_simple() but takes a pair table with the structure 355 * information as input. 356 * 357 * @note On success, this function allocates memory for X and Y coordinates and assigns 358 * the pointers at addressess @p x and @p y to the corresponding memory locations. It's 359 * the users responsibility to cleanup this memory after usage! 360 * 361 * @see vrna_plot_coords_pt(), vrna_plot_coords_simple(), vrna_plot_coords_circular_pt(), 362 * vrna_plot_coords_naview_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt() 363 * 364 * @param pt The pair table that holds the secondary structure 365 * @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) 366 * @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) 367 * @return The length of the structure on success, 0 otherwise 368 */ 369 int 370 vrna_plot_coords_simple_pt(const short *pt, 371 float **x, 372 float **y); 373 374 375 /** 376 * @brief Compute coordinates of nucleotides mapped in equal distancies onto a unit circle. 377 * 378 * This function basically is a wrapper to vrna_plot_coords() that passes the @p plot_type #VRNA_PLOT_TYPE_CIRCULAR. 379 * 380 * In order to draw nice arcs using quadratic bezier curves that connect base pairs one may calculate 381 * a second tangential point @f$P^t@f$ in addition to the actual R<sup>2</sup> coordinates. 382 * the simplest way to do so may be to compute a radius scaling factor @f$rs@f$ in the interval @f$[0,1]@f$ that 383 * weights the proportion of base pair span to the actual length of the sequence. This scaling factor 384 * can then be used to calculate the coordinates for @f$P^t@f$, i.e. 385 * @f[ 386 * P^{t}_x[i] = X[i] * rs 387 * @f] 388 * and 389 * @f[ 390 * P^{t}_y[i] = Y[i] * rs 391 * @f]. 392 * 393 * @note On success, this function allocates memory for X and Y coordinates and assigns 394 * the pointers at addressess @p x and @p y to the corresponding memory locations. It's 395 * the users responsibility to cleanup this memory after usage! 396 * 397 * @see vrna_plot_coords(), vrna_plot_coords_circular_pt(), vrna_plot_coords_simple(), 398 * vrna_plot_coords_naview(), vrna_plot_coords_turtle(), vrna_plot_coords_puzzler() 399 * 400 * @param structure The secondary structure in dot-bracket notation 401 * @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) 402 * @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) 403 * @return The length of the structure on success, 0 otherwise 404 */ 405 int 406 vrna_plot_coords_circular(const char *structure, 407 float **x, 408 float **y); 409 410 411 /** 412 * @brief Compute nucleotide coordinates for a <i>Circular Plot</i> 413 * 414 * Same as vrna_plot_coords_circular() but takes a pair table with the structure 415 * information as input. 416 * 417 * @note On success, this function allocates memory for X and Y coordinates and assigns 418 * the pointers at addressess @p x and @p y to the corresponding memory locations. It's 419 * the users responsibility to cleanup this memory after usage! 420 * 421 * @see vrna_plot_coords_pt(), vrna_plot_coords_circular(), vrna_plot_coords_simple_pt(), 422 * vrna_plot_coords_naview_pt(), vrna_plot_coords_turtle_pt(), vrna_plot_coords_puzzler_pt() 423 * 424 * @param pt The pair table that holds the secondary structure 425 * @param[inout] x The address of a pointer of X coordinates (pointer will point to memory, or NULL on failure) 426 * @param[inout] y The address of a pointer of Y coordinates (pointer will point to memory, or NULL on failure) 427 * @return The length of the structure on success, 0 otherwise 428 */ 429 int 430 vrna_plot_coords_circular_pt(const short *pt, 431 float **x, 432 float **y); 433 434 435 /** 436 * @} 437 */ 438 439 440 #ifndef VRNA_DISABLE_BACKWARD_COMPATIBILITY 441 442 /** 443 * @addtogroup plotting_utils_deprecated 444 * @{ 445 */ 446 447 448 /** 449 * @brief this is a workarround for the SWIG Perl Wrapper RNA plot function 450 * that returns an array of type COORDINATE 451 */ 452 typedef struct { 453 float X; /* X coords */ 454 float Y; /* Y coords */ 455 } COORDINATE; 456 457 458 /** 459 * @brief Switch for changing the secondary structure layout algorithm 460 * 461 * Current possibility are 0 for a simple radial drawing or 1 for the modified 462 * radial drawing taken from the @e naview program of @cite bruccoleri:1988. 463 * 464 * @note To provide thread safety please do not rely on this global variable in future implementations 465 * but pass a plot type flag directly to the function that decides which layout algorithm it may use! 466 * 467 * @see #VRNA_PLOT_TYPE_SIMPLE, #VRNA_PLOT_TYPE_NAVIEW, #VRNA_PLOT_TYPE_CIRCULAR 468 * 469 */ 470 extern int rna_plot_type; 471 472 473 /** 474 * @brief Calculate nucleotide coordinates for secondary structure plot the <i>Simple way</i> 475 * 476 * @see make_pair_table(), rna_plot_type, simple_circplot_coordinates(), naview_xy_coordinates(), vrna_file_PS_rnaplot_a(), 477 * vrna_file_PS_rnaplot, svg_rna_plot() 478 * 479 * @deprecated Consider switching to vrna_plot_coords_simple_pt() instead! 480 * 481 * @param pair_table The pair table of the secondary structure 482 * @param X a pointer to an array with enough allocated space to hold the x coordinates 483 * @param Y a pointer to an array with enough allocated space to hold the y coordinates 484 * @return length of sequence on success, 0 otherwise 485 */ 486 DEPRECATED(int 487 simple_xy_coordinates(short *pair_table, 488 float *X, 489 float *Y), 490 "Use vrna_plot_coords_simple_pt() instead!"); 491 492 493 /** 494 * @brief Calculate nucleotide coordinates for <i>Circular Plot</i> 495 * 496 * This function calculates the coordinates of nucleotides mapped in equal distancies onto a unit circle. 497 * 498 * @note In order to draw nice arcs using quadratic bezier curves that connect base pairs one may calculate 499 * a second tangential point @f$P^t@f$ in addition to the actual R<sup>2</sup> coordinates. 500 * the simplest way to do so may be to compute a radius scaling factor @f$rs@f$ in the interval @f$[0,1]@f$ that 501 * weights the proportion of base pair span to the actual length of the sequence. This scaling factor 502 * can then be used to calculate the coordinates for @f$P^t@f$, i.e. @f$ P^{t}_x[i] = X[i] * rs@f$ 503 * and @f$P^{t}_y[i] = Y[i] * rs@f$. 504 * 505 * @see make_pair_table(), rna_plot_type, simple_xy_coordinates(), naview_xy_coordinates(), vrna_file_PS_rnaplot_a(), 506 * vrna_file_PS_rnaplot, svg_rna_plot() 507 * 508 * @deprecated Consider switching to vrna_plot_coords_circular_pt() instead! 509 * 510 * @param pair_table The pair table of the secondary structure 511 * @param x a pointer to an array with enough allocated space to hold the x coordinates 512 * @param y a pointer to an array with enough allocated space to hold the y coordinates 513 * @return length of sequence on success, 0 otherwise 514 */ 515 DEPRECATED(int 516 simple_circplot_coordinates(short *pair_table, 517 float *x, 518 float *y), 519 "Use vrna_plot_coords_circular_pt() instead!"); 520 521 522 /** 523 * @} 524 */ 525 526 #endif 527 528 529 #endif 530