diff options
Diffstat (limited to 'api/explore.h')
-rw-r--r-- | api/explore.h | 345 |
1 files changed, 273 insertions, 72 deletions
diff --git a/api/explore.h b/api/explore.h index 8ea6f704..30d3ed13 100644 --- a/api/explore.h +++ b/api/explore.h @@ -29,7 +29,7 @@ * * Version Creation Date: 6/30/98 * -* $Revision: 6.21 $ +* $Revision: 6.37 $ * * File Description: Reengineered and optimized exploration functions * to be used for future code @@ -63,8 +63,8 @@ extern "C" { /***************************************************************************** * * SeqMgrBioseqContext, SeqMgrSegmentContext, SeqMgrDescContext and SeqMgrFeatContext -* are data structures supporting the collection of bioseqs, parts of segmented bioseqs, -* descriptors, and features, respectively +* are data structures supporting the collection of bioseqs, parts of segmented +* bioseqs, descriptors, and features, respectively * *****************************************************************************/ @@ -74,6 +74,7 @@ typedef struct seqmgrbioseqcontext { BioseqPtr bsp; SeqEntryPtr sep; BioseqSetPtr bssp; + Int4 numsegs; Pointer userdata; /* the following fields are for internal use only */ Pointer omdp; @@ -117,6 +118,7 @@ typedef struct seqmgrfeatcontext { CharPtr label; Int4 left; Int4 right; + Int4 dnaStop; Boolean partialL; Boolean partialR; Boolean farloc; @@ -140,10 +142,16 @@ typedef struct seqmgrfeatcontext { * *****************************************************************************/ -NLM_EXTERN Uint2 LIBCALL SeqMgrIndexFeatures PROTO((Uint2 entityID, Pointer ptr)); +NLM_EXTERN Uint2 LIBCALL SeqMgrIndexFeatures ( + Uint2 entityID, + Pointer ptr +); + /***************************************************************************** * +* To find the best protein feature for a CDS, first call SeqMgrGetProtXref. +* If it is NULL, call SeqMgrGetBestProteinFeature. * SeqMgrGetBestProteinFeature and SeqMgrGetCDSgivenProduct take a protein * bioseq to get the best protein feature or encoding CDS * SeqMgrGetRNAgivenProduct takes an mRNA (cDNA) bioseq and gets the encoding @@ -151,14 +159,24 @@ NLM_EXTERN Uint2 LIBCALL SeqMgrIndexFeatures PROTO((Uint2 entityID, Pointer ptr) * *****************************************************************************/ -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetBestProteinFeature PROTO((BioseqPtr bsp, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN ProtRefPtr LIBCALL SeqMgrGetProtXref ( + SeqFeatPtr sfp +); + +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetBestProteinFeature ( + BioseqPtr bsp, + SeqMgrFeatContext PNTR context +); -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetCDSgivenProduct PROTO((BioseqPtr bsp, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetCDSgivenProduct ( + BioseqPtr bsp, + SeqMgrFeatContext PNTR context +); -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetRNAgivenProduct PROTO((BioseqPtr bsp, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetRNAgivenProduct ( + BioseqPtr bsp, + SeqMgrFeatContext PNTR context +); /***************************************************************************** * @@ -170,12 +188,18 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetRNAgivenProduct PROTO((BioseqPtr bsp, * *****************************************************************************/ -NLM_EXTERN GeneRefPtr LIBCALL SeqMgrGetGeneXref PROTO((SeqFeatPtr sfp)); +NLM_EXTERN GeneRefPtr LIBCALL SeqMgrGetGeneXref ( + SeqFeatPtr sfp +); -NLM_EXTERN Boolean LIBCALL SeqMgrGeneIsSuppressed PROTO((GeneRefPtr grp)); +NLM_EXTERN Boolean LIBCALL SeqMgrGeneIsSuppressed ( + GeneRefPtr grp +); -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingGene PROTO((SeqLocPtr slp, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingGene ( + SeqLocPtr slp, + SeqMgrFeatContext PNTR context +); /***************************************************************************** * @@ -186,17 +210,25 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingGene PROTO((SeqLocPtr slp, * *****************************************************************************/ -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingmRNA PROTO((SeqLocPtr slp, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingmRNA ( + SeqLocPtr slp, + SeqMgrFeatContext PNTR context +); -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingCDS PROTO((SeqLocPtr slp, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingCDS ( + SeqLocPtr slp, + SeqMgrFeatContext PNTR context +); -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingPub PROTO((SeqLocPtr slp, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingPub ( + SeqLocPtr slp, + SeqMgrFeatContext PNTR context +); -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingSource PROTO((SeqLocPtr slp, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingSource ( + SeqLocPtr slp, + SeqMgrFeatContext PNTR context +); /***************************************************************************** * @@ -214,13 +246,20 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingSource PROTO((SeqLocPtr slp, * *****************************************************************************/ -NLM_EXTERN ValNodePtr LIBCALL SeqMgrGetNextDescriptor PROTO((BioseqPtr bsp, ValNodePtr curr, - Uint1 seqDescChoice, - SeqMgrDescContext PNTR context)); - -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetNextFeature PROTO((BioseqPtr bsp, SeqFeatPtr curr, - Uint1 seqFeatChoice, Uint1 featDefChoice, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN ValNodePtr LIBCALL SeqMgrGetNextDescriptor ( + BioseqPtr bsp, + ValNodePtr curr, + Uint1 seqDescChoice, + SeqMgrDescContext PNTR context +); + +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetNextFeature ( + BioseqPtr bsp, + SeqFeatPtr curr, + Uint1 seqFeatChoice, + Uint1 featDefChoice, + SeqMgrFeatContext PNTR context +); /***************************************************************************** * @@ -229,13 +268,25 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetNextFeature PROTO((BioseqPtr bsp, SeqFeat * *****************************************************************************/ -typedef Boolean (LIBCALLBACK *SeqMgrBioseqExploreProc) PROTO((BioseqPtr bsp, SeqMgrBioseqContextPtr context)); +typedef Boolean (LIBCALLBACK *SeqMgrBioseqExploreProc) ( + BioseqPtr bsp, + SeqMgrBioseqContextPtr context +); -typedef Boolean (LIBCALLBACK *SeqMgrSegmentExploreProc) PROTO((SeqLocPtr slp, SeqMgrSegmentContextPtr context)); +typedef Boolean (LIBCALLBACK *SeqMgrSegmentExploreProc) ( + SeqLocPtr slp, + SeqMgrSegmentContextPtr context +); -typedef Boolean (LIBCALLBACK *SeqMgrDescExploreProc) PROTO((ValNodePtr sdp, SeqMgrDescContextPtr context)); +typedef Boolean (LIBCALLBACK *SeqMgrDescExploreProc) ( + ValNodePtr sdp, + SeqMgrDescContextPtr context +); -typedef Boolean (LIBCALLBACK *SeqMgrFeatExploreProc) PROTO((SeqFeatPtr sfp, SeqMgrFeatContextPtr context)); +typedef Boolean (LIBCALLBACK *SeqMgrFeatExploreProc) ( + SeqFeatPtr sfp, + SeqMgrFeatContextPtr context +); /***************************************************************************** * @@ -243,33 +294,77 @@ typedef Boolean (LIBCALLBACK *SeqMgrFeatExploreProc) PROTO((SeqFeatPtr sfp, SeqM * SeqMgrExploreFeatures use the bioseq feature indices to quickly present * desired items to the user-supplied callback function, stopping if the callback * returns FALSE -* In contrast to the SeqMgrGetNext functions, the SeqMgrExplore function callbacks pass -* a pointer to the SeqMgr[Bioseq/Segment/Desc/Feat]Context data structures held by the -* explore function, not on the calling function's stack -* If the filter parameters are NULL, every feature or descriptor is returned, otherwise -* the array lengths should be SEQDESCR_MAX, SEQFEAT_MAX, and FEATDEF_MAX, and the -* elements are from the Seq_descr_, SEQFEAT_, and FEATDEF_ lists +* In contrast to the SeqMgrGetNext functions, the SeqMgrExplore function callbacks +* pass a pointer to the SeqMgr[Bioseq/Segment/Desc/Feat]Context data structures +* held by the explore function, not on the calling function's stack +* If the filter parameters are NULL, every feature or descriptor is returned, +* otherwise the array lengths should be SEQDESCR_MAX, SEQFEAT_MAX, and +* FEATDEF_MAX, and the elements are from the Seq_descr_, SEQFEAT_, and FEATDEF_ +* lists * It is expected that these calls would be flanked by BioseqLock and BioseqUnlock, * so object manager reload could ensure that pointers are valid within the loop, * but these explore functions can work on cached-out records +* All of these functions return the number of times the callback was called * *****************************************************************************/ -NLM_EXTERN Boolean LIBCALL SeqMgrExploreBioseqs PROTO((Uint2 entityID, Pointer ptr, Pointer userdata, - SeqMgrBioseqExploreProc userfunc, - Boolean nucs, Boolean prots, Boolean parts)); +NLM_EXTERN Int2 LIBCALL SeqMgrExploreBioseqs ( + Uint2 entityID, + Pointer ptr, + Pointer userdata, + SeqMgrBioseqExploreProc userfunc, + Boolean nucs, + Boolean prots, + Boolean parts +); + +NLM_EXTERN Int2 LIBCALL SeqMgrExploreSegments ( + BioseqPtr bsp, + Pointer userdata, + SeqMgrSegmentExploreProc userfunc +); + +NLM_EXTERN Int2 LIBCALL SeqMgrExploreDescriptors ( + BioseqPtr bsp, + Pointer userdata, + SeqMgrDescExploreProc userfunc, + BoolPtr seqDescFilter +); + +NLM_EXTERN Int2 LIBCALL SeqMgrExploreFeatures ( + BioseqPtr bsp, + Pointer userdata, + SeqMgrFeatExploreProc userfunc, + SeqLocPtr locationFilter, + BoolPtr seqFeatFilter, + BoolPtr featDefFilter +); -NLM_EXTERN Boolean LIBCALL SeqMgrExploreSegments PROTO((BioseqPtr bsp, Pointer userdata, - SeqMgrSegmentExploreProc userfunc)); - -NLM_EXTERN Boolean LIBCALL SeqMgrExploreDescriptors PROTO((BioseqPtr bsp, Pointer userdata, - SeqMgrDescExploreProc userfunc, - BoolPtr seqDescFilter)); +/***************************************************************************** +* +* SeqMgrGetFeatureByLabel returns the a feature with the desired label +* If desired, place a SeqMgrFeatContext data structure on the stack, and pass +* in &context as the last parameter +* SeqMgrGetNextFeatureByLabel works like SeqMgrGetNextFeature, except that +* the order is by alphabetized label, not by chromosomal position +* +*****************************************************************************/ -NLM_EXTERN Boolean LIBCALL SeqMgrExploreFeatures PROTO((BioseqPtr bsp, Pointer userdata, - SeqMgrFeatExploreProc userfunc, - SeqLocPtr locationFilter, - BoolPtr seqFeatFilter, BoolPtr featDefFilter)); +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetFeatureByLabel ( + BioseqPtr bsp, + CharPtr label, + Uint1 seqFeatChoice, + Uint1 featDefChoice, + SeqMgrFeatContext PNTR context +); + +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetNextFeatureByLabel ( + BioseqPtr bsp, + SeqFeatPtr curr, + Uint1 seqFeatChoice, + Uint1 featDefChoice, + SeqMgrFeatContext PNTR context +); /***************************************************************************** * @@ -282,34 +377,124 @@ NLM_EXTERN Boolean LIBCALL SeqMgrExploreFeatures PROTO((BioseqPtr bsp, Pointer u * *****************************************************************************/ -NLM_EXTERN ValNodePtr LIBCALL SeqMgrGetDesiredDescriptor PROTO((Uint2 entityID, BioseqPtr bsp, - Uint2 itemID, Uint2 index, ValNodePtr sdp, - SeqMgrDescContext PNTR context)); +NLM_EXTERN ValNodePtr LIBCALL SeqMgrGetDesiredDescriptor ( + Uint2 entityID, + BioseqPtr bsp, + Uint2 itemID, + Uint2 index, + ValNodePtr sdp, + SeqMgrDescContext PNTR context +); + +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetDesiredFeature ( + Uint2 entityID, + BioseqPtr bsp, + Uint2 itemID, + Uint2 index, + SeqFeatPtr sfp, + SeqMgrFeatContext PNTR context +); + +/***************************************************************************** +* +* SeqMgrVisitDescriptors and SeqMgrVisitFeatures visit all descriptors or +* features in an entity in order of itemID, which is assigned by order of +* packaging within the record +* Both of these functions return the number of times the callback was called +* +*****************************************************************************/ + +NLM_EXTERN Int2 LIBCALL SeqMgrVisitDescriptors ( + Uint2 entityID, + Pointer userdata, + SeqMgrDescExploreProc userfunc, + BoolPtr seqDescFilter +); + +NLM_EXTERN Int2 LIBCALL SeqMgrVisitFeatures ( + Uint2 entityID, + Pointer userdata, + SeqMgrFeatExploreProc userfunc, + BoolPtr seqFeatFilter, + BoolPtr featDefFilter +); + +/***************************************************************************** +* +* BioseqFindFromSeqLoc finds the segmented bioseq if location is join on parts, +* and does so even if some of the intervals are far accessions. +* +*****************************************************************************/ -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetDesiredFeature PROTO((Uint2 entityID, BioseqPtr bsp, - Uint2 itemID, Uint2 index, SeqFeatPtr sfp, - SeqMgrFeatContext PNTR context)); +NLM_EXTERN BioseqPtr BioseqFindFromSeqLoc ( + SeqLocPtr loc +); + +/***************************************************************************** +* +* SeqMgrGetParentOfPart returns the segmented bioseq parent of a part bioseq, +* and fills in the context structure. +* +*****************************************************************************/ + +NLM_EXTERN BioseqPtr LIBCALL SeqMgrGetParentOfPart ( + BioseqPtr bsp, + SeqMgrSegmentContext PNTR context +); + +/***************************************************************************** +* +* SeqMgrGetBioseqContext fills in the context structure for any bioseq. +* +*****************************************************************************/ + +NLM_EXTERN Boolean LIBCALL SeqMgrGetBioseqContext ( + BioseqPtr bsp, + SeqMgrBioseqContext PNTR context +); /***************************************************************************** * * SeqMgrBuildFeatureIndex builds a sorted array index for any feature type * (gene, mRNA, CDS, publication, and biosource have built-in arrays) -* SeqMgrGetOverlappingFeature uses the array to find feature overlap, -* returning the position in the index +* SeqMgrGetOverlappingFeature uses the array, or a feature subtype (chocies +* are FEATDEF_GENE, FEATDEF_CDS, FEATDEF_mRNA, FEATDEF_PUB, or FEATDEF_BIOSRC) +* to find feature overlap, requiring either that the location be completely +* contained within the feature range, or merely that it be overlapped by the +* feature, and returns the position in the index * SeqMgrGetFeatureInIndex gets an arbitrary feature indexed by the array * *****************************************************************************/ -NLM_EXTERN VoidPtr LIBCALL SeqMgrBuildFeatureIndex PROTO((BioseqPtr bsp, Int4Ptr num, - Uint1 seqFeatChoice, Uint1 featDefChoice)); - -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingFeature PROTO((SeqLocPtr slp, VoidPtr featarray, - Int4 numfeats, Int4Ptr position, - SeqMgrFeatContext PNTR context)); - -NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetFeatureInIndex PROTO((BioseqPtr bsp, VoidPtr featarray, - Int4 numfeats, Uint2 index, - SeqMgrFeatContext PNTR context)); +#define SIMPLE_OVERLAP 0 +#define CONTAINED_WITHIN 1 +#define CHECK_INTERVALS 2 +#define INTERVAL_OVERLAP 3 + +NLM_EXTERN VoidPtr LIBCALL SeqMgrBuildFeatureIndex ( + BioseqPtr bsp, + Int4Ptr num, + Uint1 seqFeatChoice, + Uint1 featDefChoice +); + +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetOverlappingFeature ( + SeqLocPtr slp, + Uint2 subtype, + VoidPtr featarray, + Int4 numfeats, + Int4Ptr position, + Int2 overlapType, + SeqMgrFeatContext PNTR context +); + +NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetFeatureInIndex ( + BioseqPtr bsp, + VoidPtr featarray, + Int4 numfeats, + Uint2 index, + SeqMgrFeatContext PNTR context +); /* the following functions are not frequently called by applications */ @@ -320,7 +505,9 @@ NLM_EXTERN SeqFeatPtr LIBCALL SeqMgrGetFeatureInIndex PROTO((BioseqPtr bsp, Void * *****************************************************************************/ -NLM_EXTERN time_t LIBCALL SeqMgrFeaturesAreIndexed PROTO((Uint2 entityID)); +NLM_EXTERN time_t LIBCALL SeqMgrFeaturesAreIndexed ( + Uint2 entityID +); /***************************************************************************** * @@ -329,8 +516,22 @@ NLM_EXTERN time_t LIBCALL SeqMgrFeaturesAreIndexed PROTO((Uint2 entityID)); * *****************************************************************************/ -NLM_EXTERN Boolean LIBCALL SeqMgrClearFeatureIndexes PROTO((Uint2 entityID, Pointer ptr)); +NLM_EXTERN Boolean LIBCALL SeqMgrClearFeatureIndexes ( + Uint2 entityID, + Pointer ptr +); + +/***************************************************************************** +* +* SeqMgrIndexFeaturesEx allows indexing on opposite strand for upside-down Web views +* +*****************************************************************************/ +NLM_EXTERN Uint2 LIBCALL SeqMgrIndexFeaturesEx ( + Uint2 entityID, + Pointer ptr, + Boolean flip +); #ifdef __cplusplus |