1 #ifndef VIENNA_RNA_PACKAGE_MOVE_H 2 #define VIENNA_RNA_PACKAGE_MOVE_H 3 4 5 /** 6 * @file ViennaRNA/landscape/move.h 7 * @ingroup neighbors 8 * @brief Methods to operate with structural neighbors of RNA secondary structures. 9 */ 10 11 /** 12 * @addtogroup neighbors 13 * @{ 14 */ 15 16 17 /** 18 * @brief A single move that transforms a secondary structure into one of its neighbors 19 */ 20 typedef struct vrna_move_s vrna_move_t; 21 22 /** 23 * @brief Option flag indicating insertion move 24 * @see vrna_neighbors(), vrna_neighbors_successive, vrna_path() 25 */ 26 #define VRNA_MOVESET_INSERTION 4 27 28 /** 29 * @brief Option flag indicating deletion move 30 * @see vrna_neighbors(), vrna_neighbors_successive, vrna_path() 31 */ 32 #define VRNA_MOVESET_DELETION 8 33 34 /** 35 * @brief Option flag indicating shift move 36 * @see vrna_neighbors(), vrna_neighbors_successive, vrna_path() 37 */ 38 #define VRNA_MOVESET_SHIFT 16 39 /** 40 * @brief Option flag indicating moves without lonely base pairs 41 * @see vrna_neighbors(), vrna_neighbors_successive, vrna_path() 42 */ 43 #define VRNA_MOVESET_NO_LP 32 44 45 /** 46 * @brief Option flag indicating default move set, i.e. insertions/deletion of a base pair 47 * @see vrna_neighbors(), vrna_neighbors_successive, vrna_path() 48 */ 49 #define VRNA_MOVESET_DEFAULT (VRNA_MOVESET_INSERTION | VRNA_MOVESET_DELETION) 50 51 52 /** 53 * @brief An atomic representation of the transition / move from one structure to its neighbor 54 * 55 * An atomic transition / move may be one of the following: 56 * - a <strong>base pair insertion</strong>, 57 * - a <strong>base pair removal</strong>, or 58 * - a <strong>base pair shift</strong> where an existing base pair changes one of its 59 * pairing partner. 60 * 61 * These moves are encoded by two integer values that represent the affected 5' and 3' 62 * nucleotide positions. Furthermore, we use the following convention on the signedness 63 * of these encodings: 64 * - both values are positive for <em>insertion moves</em> 65 * - both values are negative for <em>base pair removals</em> 66 * - both values have different signedness for <em>shift moves</em>, where the positive 67 * value indicates the nucleotide that stays constant, and the others absolute value 68 * is the new pairing partner 69 * 70 * @note A value of 0 in either field is used as list-end indicator and doesn't represent 71 * any valid move. 72 */ 73 struct vrna_move_s { 74 int pos_5; /**< @brief The (absolute value of the) 5' position of a base pair, or any position of a shifted pair */ 75 int pos_3; /**< @brief The (absolute value of the) 3' position of a base pair, or any position of a shifted pair */ 76 vrna_move_t *next; /**< @brief The next base pair (if an elementary move changes more than one base pair), or @p NULL 77 * Has to be terminated with move 0,0 78 */ 79 }; 80 81 82 /** 83 * @brief Create an atomic move 84 * 85 * @see #vrna_move_s 86 * 87 * @param pos_5 The 5' position of the move (positive for insertions, negative for removal, any value for shift moves) 88 * @param pos_3 The 3' position of the move (positive for insertions, negative for removal, any value for shift moves) 89 * @return An atomic move as specified by @p pos_5 and @p pos_3 90 */ 91 vrna_move_t 92 vrna_move_init(int pos_5, 93 int pos_3); 94 95 96 /** 97 * delete all moves in a zero terminated list. 98 */ 99 void 100 vrna_move_list_free(vrna_move_t *moves); 101 102 103 /** 104 * @brief Apply a particular move / transition to a secondary structure, i.e. transform a structure 105 * 106 * @param[in,out] pt The pair table representation of the secondary structure 107 * @param[in] m The move to apply 108 */ 109 void 110 vrna_move_apply(short *pt, 111 const vrna_move_t *m); 112 113 114 void 115 vrna_move_apply_db(char *structure, 116 const short *pt, 117 const vrna_move_t *m); 118 119 120 /** 121 * @brief Test whether a move is a base pair removal 122 * 123 * @param m The move to test against 124 * @return Non-zero if the move is a base pair removal, 0 otherwise 125 */ 126 int 127 vrna_move_is_removal(const vrna_move_t *m); 128 129 130 /** 131 * @brief Test whether a move is a base pair insertion 132 * 133 * @param m The move to test against 134 * @return Non-zero if the move is a base pair insertion, 0 otherwise 135 */ 136 int 137 vrna_move_is_insertion(const vrna_move_t *m); 138 139 140 /** 141 * @brief Test whether a move is a base pair shift 142 * 143 * @param m The move to test against 144 * @return Non-zero if the move is a base pair shift, 0 otherwise 145 */ 146 int 147 vrna_move_is_shift(const vrna_move_t *m); 148 149 150 /** 151 * @brief Compare two moves 152 * 153 * The function compares two moves @p a and @p b and returns 154 * whether move @p a is lexicographically smaller (-1), larger (1) 155 * or equal to move @p b. 156 * 157 * If any of the moves @p a or @p b is a shift move, this 158 * comparison only makes sense in a structure context. Thus, 159 * the third argument with the current structure must be provided. 160 * 161 * @note This function returns 0 (equality) upon any error, e.g. missing input 162 * 163 * @warning Currently, shift moves are not supported! 164 * 165 * @param a The first move of the comparison 166 * @param b The second move of the comparison 167 * @param pt The pair table of the current structure that is compatible with both moves (maybe NULL if moves are guaranteed to be no shifts) 168 * @return -1 if @p a < @p b, 1 if @p a > @p b, 0 otherwise 169 */ 170 int 171 vrna_move_compare(const vrna_move_t *a, 172 const vrna_move_t *b, 173 const short *pt); 174 175 176 /** 177 * @} 178 */ 179 180 #endif 181