1 /* @include ensmapper ********************************************************* 2 ** 3 ** Ensembl Mapper functions 4 ** 5 ** @author Copyright (C) 1999 Ensembl Developers 6 ** @author Copyright (C) 2006 Michael K. Schuster 7 ** @version $Revision: 1.27 $ 8 ** @modified 2009 by Alan Bleasby for incorporation into EMBOSS core 9 ** @modified $Date: 2013/02/17 13:04:02 $ by $Author: mks $ 10 ** @@ 11 ** 12 ** This library is free software; you can redistribute it and/or 13 ** modify it under the terms of the GNU Lesser General Public 14 ** License as published by the Free Software Foundation; either 15 ** version 2.1 of the License, or (at your option) any later version. 16 ** 17 ** This library is distributed in the hope that it will be useful, 18 ** but WITHOUT ANY WARRANTY; without even the implied warranty of 19 ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 20 ** Lesser General Public License for more details. 21 ** 22 ** You should have received a copy of the GNU Lesser General Public 23 ** License along with this library; if not, write to the Free Software 24 ** Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, 25 ** MA 02110-1301, USA. 26 ** 27 ******************************************************************************/ 28 29 #ifndef ENSMAPPER_H 30 #define ENSMAPPER_H 31 32 /* ========================================================================= */ 33 /* ============================= include files ============================= */ 34 /* ========================================================================= */ 35 36 #include "enscoordsystem.h" 37 38 AJ_BEGIN_DECLS 39 40 41 42 43 /* ========================================================================= */ 44 /* =============================== constants =============================== */ 45 /* ========================================================================= */ 46 47 /* @enum EnsEMapperunitType *************************************************** 48 ** 49 ** Ensembl Mapper Unit Type enumeration 50 ** 51 ** @value ensEMapperunitTypeNULL Null 52 ** @value ensEMapperunitTypeSource Source 53 ** @value ensEMapperunitTypeTarget Target 54 ** @@ 55 ******************************************************************************/ 56 57 typedef enum EnsOMapperunitType 58 { 59 ensEMapperunitTypeNULL, 60 ensEMapperunitTypeSource, 61 ensEMapperunitTypeTarget 62 } EnsEMapperunitType; 63 64 65 66 67 /* @enum EnsEMapperresultType ************************************************* 68 ** 69 ** Ensembl Mapper Result Type enumeration 70 ** 71 ** @value ensEMapperresultTypeNULL Null 72 ** @value ensEMapperresultTypeCoordinate Coordinate 73 ** @value ensEMapperresultTypeGap Gap 74 ** @value ensEMapperresultTypeInDel Insertion or Deletion 75 ** @@ 76 ******************************************************************************/ 77 78 typedef enum EnsOMapperresultType 79 { 80 ensEMapperresultTypeNULL, 81 ensEMapperresultTypeCoordinate, 82 ensEMapperresultTypeGap, 83 ensEMapperresultTypeInDel 84 } EnsEMapperresultType; 85 86 87 88 89 /* ========================================================================= */ 90 /* ============================== public data ============================== */ 91 /* ========================================================================= */ 92 93 /* @data EnsPMapperunit ******************************************************* 94 ** 95 ** Ensembl Mapper Unit. 96 ** 97 ** One unit of an Ensembl Mapper Pair. 98 ** 99 ** @alias EnsSMapperunit 100 ** @alias EnsOMapperunit 101 ** 102 ** @cc Bio::EnsEMBL::Mapper::Unit 103 ** @attr Objectidentifier [ajuint] Ensembl Object identifier 104 ** @attr Start [ajint] Start coordinate 105 ** @attr End [ajint] End coordinate 106 ** @attr Use [ajuint] Use counter 107 ** @@ 108 ******************************************************************************/ 109 110 typedef struct EnsSMapperunit 111 { 112 ajuint Objectidentifier; 113 ajint Start; 114 ajint End; 115 ajuint Use; 116 } EnsOMapperunit; 117 118 #define EnsPMapperunit EnsOMapperunit* 119 120 121 122 123 /* @data EnsPMapperpair ******************************************************* 124 ** 125 ** Ensembl Mapper Pair. 126 ** 127 ** An Ensembl Mapper Pair consists of two Ensembl Mapper Unit objects. 128 ** 129 ** @alias EnsSMapperpair 130 ** @alias EnsOMapperpair 131 ** 132 ** @cc Bio::EnsEMBL::Mapper::Pair 133 ** @attr Source [EnsPMapperunit] Source Ensembl Mapper Unit 134 ** @attr Target [EnsPMapperunit] Target Ensembl Mapper Unit 135 ** @attr Orientation [ajint] 136 ** Relative orientation of the Ensembl Mapper Unit objects 137 ** @cc Bio::EnsEMBL::Mapper::IndelPair 138 ** @attr Indel [AjBool] Insertion or deletion attribute 139 ** @attr Use [ajuint] Use counter 140 ** @attr Padding [ajuint] Padding to alignment boundary 141 ** @@ 142 ******************************************************************************/ 143 144 typedef struct EnsSMapperpair 145 { 146 EnsPMapperunit Source; 147 EnsPMapperunit Target; 148 ajint Orientation; 149 AjBool Indel; 150 ajuint Use; 151 ajuint Padding; 152 } EnsOMapperpair; 153 154 #define EnsPMapperpair EnsOMapperpair* 155 156 157 158 159 /* @data EnsPMapperresult ***************************************************** 160 ** 161 ** Ensembl Mapper Result. 162 ** 163 ** Representation of a mapped Ensembl Object returned by an Ensembl Mapper when 164 ** the source region maps to valid sequence. 165 ** Depending on the Ensembl Mapper Result type member, 166 ** this can also represent a gap. 167 ** 168 ** @alias EnsSMapperresult 169 ** @alias EnsOMapperresult 170 ** 171 ** @attr Coordsystem [EnsPCoordsystem] Ensembl Coordinate System 172 ** @attr Type [EnsEMapperresultType] Result type 173 ** @cc Bio::EnsEMBL::Mapper::Coordinate 174 ** @cc Bio::EnsEMBL::Mapper::IndelCoordinate 175 ** @attr Objectidentifier [ajuint] Ensembl Object identifier 176 ** @attr CoordinateStart [ajint] Coordinate start 177 ** @attr CoordinateEnd [ajint] Coordinate end 178 ** @attr CoordinateStrand [ajint] Coordinate strand 179 ** @cc Bio::EnsEMBL::Mapper::Gap 180 ** @cc Bio::EnsEMBL::Mapper::IndelCoordinate 181 ** @attr GapStart [ajint] Start coordinate of a gap 182 ** @attr GapEnd [ajint] End coordinate of a gap 183 ** @attr Rank [ajuint] Rank 184 ** @attr Use [ajuint] Use counter 185 ** @attr Padding [ajuint] Padding to alignment boundary 186 ** @@ 187 ** 188 ** NOTE: This object subsumes the following Perl objects returned by the 189 ** Bio::EnsEMBL::Mapper class. 190 ** 191 ** Bio::EnsEMBL::Mapper::Coordinate 192 ** Bio::EnsEMBL::Mapper::Gap 193 ** Bio::EnsEMBL::Mapper::IndelCoordinate 194 ** 195 ** The objects can be distinguished by their Ensembl Mapper Result type member. 196 ******************************************************************************/ 197 198 typedef struct EnsSMapperresult 199 { 200 EnsPCoordsystem Coordsystem; 201 EnsEMapperresultType Type; 202 ajuint Objectidentifier; 203 ajint CoordinateStart; 204 ajint CoordinateEnd; 205 ajint CoordinateStrand; 206 ajint GapStart; 207 ajint GapEnd; 208 ajuint Rank; 209 ajuint Use; 210 ajuint Padding; 211 } EnsOMapperresult; 212 213 #define EnsPMapperresult EnsOMapperresult* 214 215 216 217 218 /* @data EnsPMapperrange ****************************************************** 219 ** 220 ** Ensembl Mapper Range. 221 ** 222 ** An Ensembl Mapper Range defines start and end ccordinates of genome ranges. 223 ** 224 ** @alias EnsSMapperrange 225 ** @alias EnsOMapperrange 226 ** 227 ** @attr Start [ajint] Start coordinate 228 ** @attr End [ajint] End coordinate 229 ** @attr Use [ajuint] Use counter 230 ** @attr Padding [ajuint] Padding to alignment boundary 231 ** @@ 232 ******************************************************************************/ 233 234 typedef struct EnsSMapperrange 235 { 236 ajint Start; 237 ajint End; 238 ajuint Use; 239 ajuint Padding; 240 } EnsOMapperrange; 241 242 #define EnsPMapperrange EnsOMapperrange* 243 244 245 246 247 /* @data EnsPMapperrangeregistry ********************************************** 248 ** 249 ** Ensembl Mapper Range Registry. 250 ** 251 ** An Ensembl Mapper Range Registry maintains a table of registered regions. 252 ** 253 ** @alias EnsSMapperrangeregistry 254 ** @alias EnsOMapperrangeregistry 255 ** 256 ** @attr Registry [AjPTable] 257 ** First-level AJAX Table of AJAX unsigned integer 258 ** (Ensembl Object identifier) key data and 259 ** second-level AJAX List value data of Ensembl Mapper Range objects. 260 ** @attr Use [ajuint] Use counter 261 ** @attr Padding [ajuint] Padding to alignment boundary 262 ** @@ 263 ** The Ensembl Mapper Range Registry maintains an internal list of registered 264 ** regions and is used to quickly ascertain if and what regions of a provided 265 ** range need registration. 266 ******************************************************************************/ 267 268 typedef struct EnsSMapperrangeregistry 269 { 270 AjPTable Registry; 271 ajuint Use; 272 ajuint Padding; 273 } EnsOMapperrangeregistry; 274 275 #define EnsPMapperrangeregistry EnsOMapperrangeregistry* 276 277 278 279 280 /* @data EnsPMapper *********************************************************** 281 ** 282 ** Ensembl Mapper. 283 ** 284 ** Generic mapper to provide coordinate transforms between two 285 ** disjoint Ensembl Coordinate System objects. 286 ** 287 ** @alias EnsSMapper 288 ** @alias EnsOMapper 289 ** 290 ** @cc Bio::EnsEMBL::Mapper 291 ** @attr TypeSource [AjPStr] Source type 292 ** @attr TypeTarget [AjPStr] Target type 293 ** @attr CoordsystemSource [EnsPCoordsystem] Source Ensembl Coordinate System 294 ** @attr CoordsystemTarget [EnsPCoordsystem] Target Ensembl Coordinate System 295 ** @attr Mapperpairs [AjPTable] AJAX Table of AJAX Table objects with 296 ** Ensembl Mapper Pair objects 297 ** @attr Sorted [AjBool] Ensembl Mapper Pair objects are sorted 298 ** @attr Count [ajuint] Number of Ensembl Mapper Pair objects 299 ** @attr Use [ajuint] Use counter 300 ** @attr Padding [ajuint] Padding to alignment boundary 301 ** @@ 302 ** The AJAX Table Mapperpairs forms the top hierarchy of an Ensembl Mapper Pair 303 ** cache. The AJAX Table uses the contents of the TypeSource and TypeTarget 304 ** strings as index and holds a second hierarchy of AJAX Table objects, which 305 ** use AJAX unsigned inetger (Ensembl Object identifier) objects as index. 306 ** Those second-level AJAX Table objects then hold a 307 ** third-level of AJAX List objects of Ensembl Mapper Pair objects. 308 ******************************************************************************/ 309 310 typedef struct EnsSMapper 311 { 312 AjPStr TypeSource; 313 AjPStr TypeTarget; 314 EnsPCoordsystem CoordsystemSource; 315 EnsPCoordsystem CoordsystemTarget; 316 AjPTable Mapperpairs; 317 AjBool Sorted; 318 ajuint Count; 319 ajuint Use; 320 ajuint Padding; 321 } EnsOMapper; 322 323 #define EnsPMapper EnsOMapper* 324 325 326 327 328 /* ========================================================================= */ 329 /* =========================== public functions ============================ */ 330 /* ========================================================================= */ 331 332 /* 333 ** Prototype definitions 334 */ 335 336 /* Ensembl Mapper Unit */ 337 338 EnsPMapperunit ensMapperunitNewCpy(const EnsPMapperunit mu); 339 340 EnsPMapperunit ensMapperunitNewIni(ajuint oid, ajint start, ajint end); 341 342 EnsPMapperunit ensMapperunitNewRef(EnsPMapperunit mu); 343 344 void ensMapperunitDel(EnsPMapperunit *Pmu); 345 346 ajint ensMapperunitGetEnd(const EnsPMapperunit mu); 347 348 ajuint ensMapperunitGetObjectidentifier(const EnsPMapperunit mu); 349 350 ajint ensMapperunitGetStart(const EnsPMapperunit mu); 351 352 AjBool ensMapperunitSetEnd(EnsPMapperunit mu, ajint end); 353 354 AjBool ensMapperunitSetObjectidentifier(EnsPMapperunit mu, ajuint oid); 355 356 AjBool ensMapperunitSetStart(EnsPMapperunit mu, ajint start); 357 358 AjBool ensMapperunitTrace(const EnsPMapperunit mu, ajuint level); 359 360 size_t ensMapperunitCalculateMemsize(const EnsPMapperunit mu); 361 362 /* Ensembl Mapper Pair */ 363 364 EnsPMapperpair ensMapperpairNewCpy(const EnsPMapperpair mp); 365 366 EnsPMapperpair ensMapperpairNewIni(ajuint srcoid, 367 ajint srcstart, 368 ajint srcend, 369 ajuint trgoid, 370 ajint trgstart, 371 ajint trgend, 372 ajint ori, 373 AjBool indel); 374 375 EnsPMapperpair ensMapperpairNewRef(EnsPMapperpair mp); 376 377 EnsPMapperpair ensMapperpairNewUnit(EnsPMapperunit source, 378 EnsPMapperunit target, 379 ajint ori, 380 AjBool indel); 381 382 void ensMapperpairDel(EnsPMapperpair *Pmp); 383 384 AjBool ensMapperpairGetIndel(const EnsPMapperpair mp); 385 386 ajint ensMapperpairGetOrientation(const EnsPMapperpair mp); 387 388 EnsPMapperunit ensMapperpairGetSource(const EnsPMapperpair mp); 389 390 EnsPMapperunit ensMapperpairGetTarget(const EnsPMapperpair mp); 391 392 AjBool ensMapperpairTrace(const EnsPMapperpair mp, ajuint level); 393 394 EnsPMapperunit ensMapperpairCalculateMapperunit(const EnsPMapperpair mp, 395 EnsEMapperunitType type); 396 397 size_t ensMapperpairCalculateMemsize(const EnsPMapperpair mp); 398 399 AjBool ensListMapperpairSortSourceStartAscending(AjPList mps); 400 401 AjBool ensListMapperpairSortTargetStartAscending(AjPList mps); 402 403 /* Ensembl Mapper Result */ 404 405 EnsPMapperresult ensMapperresultNewCoordinate(ajuint oid, 406 ajint crdstart, 407 ajint crdend, 408 ajint crdstrand, 409 EnsPCoordsystem cs, 410 ajuint rank); 411 412 EnsPMapperresult ensMapperresultNewCpy(const EnsPMapperresult mr); 413 414 EnsPMapperresult ensMapperresultNewGap(ajint gapstart, 415 ajint gapend, 416 ajuint rank); 417 418 EnsPMapperresult ensMapperresultNewIndel(ajuint oid, 419 ajint crdstart, 420 ajint crdend, 421 ajint crdstrand, 422 EnsPCoordsystem cs, 423 ajint gapstart, 424 ajint gapend, 425 ajuint rank); 426 427 EnsPMapperresult ensMapperresultNewIni(EnsEMapperresultType type, 428 ajuint oid, 429 ajint crdstart, 430 ajint crdend, 431 ajint crdstrand, 432 EnsPCoordsystem cs, 433 ajint gapstart, 434 ajint gapend, 435 ajuint rank); 436 437 EnsPMapperresult ensMapperresultNewRef(EnsPMapperresult mr); 438 439 void ensMapperresultDel(EnsPMapperresult *Pmr); 440 441 EnsPCoordsystem ensMapperresultGetCoordsystem(const EnsPMapperresult mr); 442 443 ajint ensMapperresultGetCoordinateEnd(const EnsPMapperresult mr); 444 445 ajint ensMapperresultGetCoordinateStart(const EnsPMapperresult mr); 446 447 ajint ensMapperresultGetGapEnd(const EnsPMapperresult mr); 448 449 ajint ensMapperresultGetGapStart(const EnsPMapperresult mr); 450 451 ajuint ensMapperresultGetObjectidentifier(const EnsPMapperresult mr); 452 453 ajuint ensMapperresultGetRank(const EnsPMapperresult mr); 454 455 ajint ensMapperresultGetCoordinateStrand(const EnsPMapperresult mr); 456 457 EnsEMapperresultType ensMapperresultGetType(const EnsPMapperresult mr); 458 459 AjBool ensMapperresultSetCoordinateEnd(EnsPMapperresult mr, 460 ajint crdend); 461 462 AjBool ensMapperresultSetCoordinateStart(EnsPMapperresult mr, 463 ajint crdstart); 464 465 AjBool ensMapperresultSetCoordinateStrand(EnsPMapperresult mr, 466 ajint crdstrand); 467 468 AjBool ensMapperresultSetCoordsystem(EnsPMapperresult mr, 469 EnsPCoordsystem cs); 470 471 AjBool ensMapperresultSetGapEnd(EnsPMapperresult mr, 472 ajint gapend); 473 474 AjBool ensMapperresultSetGapStart(EnsPMapperresult mr, 475 ajint gapstart); 476 477 AjBool ensMapperresultSetObjectidentifier(EnsPMapperresult mr, 478 ajuint oid); 479 480 AjBool ensMapperresultSetRank(EnsPMapperresult mr, 481 ajuint rank); 482 483 AjBool ensMapperresultSetType(EnsPMapperresult mr, 484 EnsEMapperresultType mrt); 485 486 AjBool ensMapperresultTrace(const EnsPMapperresult mr, ajuint level); 487 488 ajuint ensMapperresultCalculateLengthCoordinate(const EnsPMapperresult mr); 489 490 ajuint ensMapperresultCalculateLengthGap(const EnsPMapperresult mr); 491 492 ajuint ensMapperresultCalculateLengthResult(const EnsPMapperresult mr); 493 494 size_t ensMapperresultCalculateMemsize(const EnsPMapperresult mr); 495 496 /* Ensembl Mapper Range */ 497 498 EnsPMapperrange ensMapperrangeNewCpy(const EnsPMapperrange mr); 499 500 EnsPMapperrange ensMapperrangeNewIni(ajint start, ajint end); 501 502 EnsPMapperrange ensMapperrangeNewRef(EnsPMapperrange mr); 503 504 void ensMapperrangeDel(EnsPMapperrange *Pmr); 505 506 ajint ensMapperrangeGetEnd(const EnsPMapperrange mr); 507 508 ajint ensMapperrangeGetStart(const EnsPMapperrange mr); 509 510 AjBool ensMapperrangeTrace(const EnsPMapperrange mr, ajuint level); 511 512 size_t ensMapperrangeCalculateMemsize(const EnsPMapperrange mr); 513 514 /* Ensembl Mapper Range Registry */ 515 516 EnsPMapperrangeregistry ensMapperrangeregistryNew(void); 517 518 EnsPMapperrangeregistry ensMapperrangeregistryNewRef( 519 EnsPMapperrangeregistry mrr); 520 521 AjBool ensMapperrangeregistryClear(EnsPMapperrangeregistry mrr); 522 523 void ensMapperrangeregistryDel(EnsPMapperrangeregistry *Pmrr); 524 525 AjBool ensMapperrangeregistryCheck(EnsPMapperrangeregistry mrr, 526 ajuint oid, 527 ajint chkstart, 528 ajint chkend, 529 ajint regstart, 530 ajint regend, 531 AjPList ranges); 532 533 const AjPList ensMapperrangeregistryCalculateMapperranges( 534 const EnsPMapperrangeregistry mrr, 535 ajuint oid); 536 537 ajuint ensMapperrangeregistryCalculateOverlap( 538 const EnsPMapperrangeregistry mrr, 539 ajuint oid, 540 ajint start, 541 ajint end); 542 543 /* Ensembl Mapper */ 544 545 EnsPMapper ensMapperNewIni(AjPStr srctype, 546 AjPStr trgtype, 547 EnsPCoordsystem srccs, 548 EnsPCoordsystem trgcs); 549 550 EnsPMapper ensMapperNewRef(EnsPMapper mapper); 551 552 AjBool ensMapperClear(EnsPMapper mapper); 553 554 void ensMapperDel(EnsPMapper *Pmapper); 555 556 EnsPCoordsystem ensMapperGetCoordsystemSource(const EnsPMapper mapper); 557 558 EnsPCoordsystem ensMapperGetCoordsystemTarget(const EnsPMapper mapper); 559 560 ajuint ensMapperGetCount(const EnsPMapper mapper); 561 562 AjBool ensMapperGetSorted(const EnsPMapper mapper); 563 564 AjPStr ensMapperGetTypeSource(const EnsPMapper mapper); 565 566 AjPStr ensMapperGetTypeTarget(const EnsPMapper mapper); 567 568 AjBool ensMapperAddCoordinates(EnsPMapper mapper, 569 ajuint srcoid, 570 ajint srcstart, 571 ajint srcend, 572 ajint ori, 573 ajuint trgoid, 574 ajint trgstart, 575 ajint trgend); 576 577 AjBool ensMapperAddIndel(EnsPMapper mapper, 578 ajuint srcoid, 579 ajint srcstart, 580 ajint srcend, 581 ajint ori, 582 ajuint trgoid, 583 ajint trgstart, 584 ajint trgend); 585 586 AjBool ensMapperAddMapperpair(EnsPMapper mapper, EnsPMapperpair mp); 587 588 AjBool ensMapperAddMappers(EnsPMapper mapper1, EnsPMapper mapper2); 589 590 AjBool ensMapperAddMapperunits(EnsPMapper mapper, 591 EnsPMapperunit srcmu, 592 EnsPMapperunit trgmu, 593 ajint ori, 594 AjBool indel); 595 596 AjBool ensMapperList(EnsPMapper mapper, 597 ajuint oid, 598 ajint start, 599 ajint end, 600 const AjPStr type, 601 AjPList mps); 602 603 AjBool ensMapperTrace(const EnsPMapper mapper, ajuint level); 604 605 size_t ensMapperCalculateMemsize(const EnsPMapper mapper); 606 607 AjBool ensMapperFastmap(EnsPMapper mapper, 608 ajuint oid, 609 ajint start, 610 ajint end, 611 ajint strand, 612 const AjPStr type, 613 AjPList mrs); 614 615 AjBool ensMapperMap(EnsPMapper mapper, 616 ajuint oid, 617 ajint start, 618 ajint end, 619 ajint strand, 620 const AjPStr type, 621 AjPList mrs); 622 623 AjBool ensMapperMapindel(EnsPMapper mapper, 624 ajuint oid, 625 ajint start, 626 ajint end, 627 ajint strand, 628 const AjPStr type, 629 AjPList mrs); 630 631 /* 632 ** End of prototype definitions 633 */ 634 635 636 637 638 AJ_END_DECLS 639 640 #endif /* !ENSMAPPER_H */ 641