.\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Bio::DB::GFF 3pm" .TH Bio::DB::GFF 3pm "2018-10-27" "perl v5.26.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Bio::DB::GFF \-\- Storage and retrieval of sequence annotation data .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Bio::DB::GFF; \& \& # Open the sequence database \& my $db = Bio::DB::GFF\->new( \-adaptor => \*(Aqdbi::mysqlopt\*(Aq, \& \-dsn => \*(Aqdbi:mysql:elegans\*(Aq); \& \& # fetch a 1 megabase segment of sequence starting at landmark "ZK909" \& my $segment = $db\->segment(\*(AqZK909\*(Aq, 1 => 1000000); \& \& # pull out all transcript features \& my @transcripts = $segment\->features(\*(Aqtranscript\*(Aq); \& \& # for each transcript, total the length of the introns \& my %totals; \& for my $t (@transcripts) { \& my @introns = $t\->Intron; \& $totals{$t\->name} += $_\->length foreach @introns; \& } \& \& # Sort the exons of the first transcript by position \& my @exons = sort {$a\->start <=> $b\->start} $transcripts[0]\->Exon; \& \& # Get a region 1000 bp upstream of first exon \& my $upstream = $exons[0]\->subseq(\-1000,0); \& \& # get its DNA \& my $dna = $upstream\->seq; \& \& # and get all curated polymorphisms inside it \& @polymorphisms = $upstream\->contained_features(\*(Aqpolymorphism:curated\*(Aq); \& \& # get all feature types in the database \& my @types = $db\->types; \& \& # count all feature types in the segment \& my %type_counts = $segment\->types(\-enumerate=>1); \& \& # get an iterator on all curated features of type \*(Aqexon\*(Aq or \*(Aqintron\*(Aq \& my $iterator = $db\->get_seq_stream(\-type => [\*(Aqexon:curated\*(Aq,\*(Aqintron:curated\*(Aq]); \& \& while (my $s = $iterator\->next_seq) { \& print $s,"\en"; \& } \& \& # find all transcripts annotated as having function \*(Aqkinase\*(Aq \& my $iterator = $db\->get_seq_stream(\-type=>\*(Aqtranscript\*(Aq, \& \-attributes=>{Function=>\*(Aqkinase\*(Aq}); \& while (my $s = $iterator\->next_seq) { \& print $s,"\en"; \& } .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Bio::DB::GFF provides fast indexed access to a sequence annotation database. It supports multiple database types (ACeDB, relational), and multiple schemas through a system of adaptors and aggregators. .PP The following operations are supported by this module: .PP .Vb 11 \& \- retrieving a segment of sequence based on the ID of a landmark \& \- retrieving the DNA from that segment \& \- finding all annotations that overlap with the segment \& \- finding all annotations that are completely contained within the \& segment \& \- retrieving all annotations of a particular type, either within a \& segment, or globally \& \- conversion from absolute to relative coordinates and back again, \& using any arbitrary landmark for the relative coordinates \& \- using a sequence segment to create new segments based on relative \& offsets .Ve .PP The data model used by Bio::DB::GFF is compatible with the \s-1GFF\s0 flat file format (). The module can load a set of \s-1GFF\s0 files into the database, and serves objects that have methods corresponding to \s-1GFF\s0 fields. .PP The objects returned by Bio::DB::GFF are compatible with the SeqFeatureI interface, allowing their use by the Bio::Graphics and Bio::DAS modules. .SS "Auxiliary Scripts" .IX Subsection "Auxiliary Scripts" The bioperl distribution includes several scripts that make it easier to work with Bio::DB::GFF databases. They are located in the scripts directory under a subdirectory named Bio::DB::GFF: .IP "\(bu" 4 bp_load_gff.pl .Sp This script will load a Bio::DB::GFF database from a flat \s-1GFF\s0 file of sequence annotations. Only the relational database version of Bio::DB::GFF is supported. It can be used to create the database from scratch, as well as to incrementally load new data. .Sp This script takes a \-\-fasta argument to load raw \s-1DNA\s0 into the database as well. However, \s-1GFF\s0 databases do not require access to the raw \s-1DNA\s0 for most of their functionality. .Sp load_gff.pl also has a \-\-upgrade option, which will perform a non-destructive upgrade of older schemas to newer ones. .IP "\(bu" 4 bp_bulk_load_gff.pl .Sp This script will populate a Bio::DB::GFF database from a flat \s-1GFF\s0 file of sequence annotations. Only the MySQL database version of Bio::DB::GFF is supported. It uses the \*(L"\s-1LOAD DATA INFILE\*(R"\s0 query in order to accelerate loading considerably; however, it can only be used for the initial load, and not for updates. .Sp This script takes a \-\-fasta argument to load raw \s-1DNA\s0 into the database as well. However, \s-1GFF\s0 databases do not require access to the raw \s-1DNA\s0 for most of their functionality. .IP "\(bu" 4 bp_fast_load_gff.pl .Sp This script is as fast as bp_bulk_load_gff.pl but uses Unix pipe tricks to allow for incremental updates. It only supports the MySQL database version of Bio::DB::GFF and is guaranteed not to work on non-Unix platforms. .Sp Arguments are the same as bp_load_gff.pl .IP "\(bu" 4 gadfly_to_gff.pl .Sp This script will convert the GFF-like format used by the Berkeley Drosophila Sequencing project into a format suitable for use with this module. .IP "\(bu" 4 sgd_to_gff.pl .Sp This script will convert the tab-delimited feature files used by the Saccharomyces Genome Database into a format suitable for use with this module. .SS "\s-1GFF\s0 Fundamentals" .IX Subsection "GFF Fundamentals" The \s-1GFF\s0 format is a flat tab-delimited file, each line of which corresponds to an annotation, or feature. Each line has nine columns and looks like this: .PP .Vb 1 \& Chr1 curated CDS 365647 365963 . + 1 Transcript "R119.7" .Ve .PP The 9 columns are as follows: .IP "1." 4 reference sequence .Sp This is the \s-1ID\s0 of the sequence that is used to establish the coordinate system of the annotation. In the example above, the reference sequence is \*(L"Chr1\*(R". .IP "2." 4 source .Sp The source of the annotation. This field describes how the annotation was derived. In the example above, the source is \*(L"curated\*(R" to indicate that the feature is the result of human curation. The names and versions of software programs are often used for the source field, as in \*(L"tRNAScan\-SE/1.2\*(R". .IP "3." 4 method .Sp The annotation method. This field describes the type of the annotation, such as \*(L"\s-1CDS\*(R".\s0 Together the method and source describe the annotation type. .IP "4." 4 start position .Sp The start of the annotation relative to the reference sequence. .IP "5." 4 stop position .Sp The stop of the annotation relative to the reference sequence. Start is always less than or equal to stop. .IP "6." 4 score .Sp For annotations that are associated with a numeric score (for example, a sequence similarity), this field describes the score. The score units are completely unspecified, but for sequence similarities, it is typically percent identity. Annotations that don't have a score can use \*(L".\*(R" .IP "7." 4 strand .Sp For those annotations which are strand-specific, this field is the strand on which the annotation resides. It is \*(L"+\*(R" for the forward strand, \*(L"\-\*(R" for the reverse strand, or \*(L".\*(R" for annotations that are not stranded. .IP "8." 4 phase .Sp For annotations that are linked to proteins, this field describes the phase of the annotation on the codons. It is a number from 0 to 2, or \&\*(L".\*(R" for features that have no phase. .IP "9." 4 group .Sp \&\s-1GFF\s0 provides a simple way of generating annotation hierarchies (\*(L"is composed of\*(R" relationships) by providing a group field. The group field contains the class and \s-1ID\s0 of an annotation which is the logical parent of the current one. In the example given above, the group is the Transcript named \*(L"R119.7\*(R". .Sp The group field is also used to store information about the target of sequence similarity hits, and miscellaneous notes. See the next section for a description of how to describe similarity targets. .Sp The format of the group fields is \*(L"Class \s-1ID\*(R"\s0 with a single space (not a tab) separating the class from the \s-1ID.\s0 It is \s-1VERY IMPORTANT\s0 to follow this format, or grouping will not work properly. .PP The sequences used to establish the coordinate system for annotations can correspond to sequenced clones, clone fragments, contigs or super-contigs. Thus, this module can be used throughout the lifecycle of a sequencing project. .PP In addition to a group \s-1ID,\s0 the \s-1GFF\s0 format allows annotations to have a group class. For example, in the ACeDB representation, \s-1RNA\s0 interference experiments have a class of \*(L"RNAi\*(R" and an \s-1ID\s0 that is unique among the RNAi experiments. Since not all databases support this notion, the class is optional in all calls to this module, and defaults to \*(L"Sequence\*(R" when not provided. .PP Double-quotes are sometimes used in \s-1GFF\s0 files around components of the group field. Strictly, this is only necessary if the group name or class contains whitespace. .SS "Making \s-1GFF\s0 files work with this module" .IX Subsection "Making GFF files work with this module" Some annotations do not need to be individually named. For example, it is probably not useful to assign a unique name to each \s-1ALU\s0 repeat in a vertebrate genome. Others, such as predicted genes, correspond to named biological objects; you probably want to be able to fetch the positions of these objects by referring to them by name. .PP To accommodate named annotations, the \s-1GFF\s0 format places the object class and name in the group field. The name identifies the object, and the class prevents similarly-named objects, for example clones and sequences, from collding. .PP A named object is shown in the following excerpt from a \s-1GFF\s0 file: .PP .Vb 1 \& Chr1 curated transcript 939627 942410 . + . Transcript Y95B8A.2 .Ve .PP This object is a predicted transcript named Y95BA.2. In this case, the group field is used to identify the class and name of the object, even though no other annotation belongs to that group. .PP It now becomes possible to retrieve the region of the genome covered by transcript Y95B8A.2 using the \fIsegment()\fR method: .PP .Vb 1 \& $segment = $db\->segment(\-class=>\*(AqTranscript\*(Aq,\-name=>\*(AqY95B8A.2\*(Aq); .Ve .PP It is not necessary for the annotation's method to correspond to the object class, although this is commonly the case. .PP As explained above, each annotation in a \s-1GFF\s0 file refers to a reference sequence. It is important that each reference sequence also be identified by a line in the \s-1GFF\s0 file. This allows the Bio::DB::GFF module to determine the length and class of the reference sequence, and makes it possible to do relative arithmetic. .PP For example, if \*(L"Chr1\*(R" is used as a reference sequence, then it should have an entry in the \s-1GFF\s0 file similar to this one: .PP .Vb 1 \& Chr1 assembly chromosome 1 14972282 . + . Sequence Chr1 .Ve .PP This indicates that the reference sequence named \*(L"Chr1\*(R" has length 14972282 bp, method \*(L"chromosome\*(R" and source \*(L"assembly\*(R". In addition, as indicated by the group field, Chr1 has class \*(L"Sequence\*(R" and name \&\*(L"Chr1\*(R". .PP The object class \*(L"Sequence\*(R" is used by default when the class is not specified in the \fIsegment()\fR call. This allows you to use a shortcut form of the \fIsegment()\fR method: .PP .Vb 2 \& $segment = $db\->segment(\*(AqChr1\*(Aq); # whole chromosome \& $segment = $db\->segment(\*(AqChr1\*(Aq,1=>1000); # first 1000 bp .Ve .PP For your convenience, if, during loading a \s-1GFF\s0 file, Bio::DB::GFF encounters a line like the following: .PP .Vb 1 \& ##sequence\-region Chr1 1 14972282 .Ve .PP It will automatically generate the following entry: .PP .Vb 1 \& Chr1 reference Component 1 14972282 . + . Sequence Chr1 .Ve .PP This is sufficient to use Chr1 as a reference point. The ##sequence\-region line is frequently found in the \s-1GFF\s0 files distributed by annotation groups. .SS "Specifying the group tag" .IX Subsection "Specifying the group tag" A frequent problem with \s-1GFF\s0 files is the problem distinguishing which of the several tag/value pairs in the 9th column is the grouping pair. Ordinarily the first tag will be used for grouping, but some \&\s-1GFF\s0 manipulating tools do not preserve the order of attributes. To eliminate this ambiguity, this module provides two ways of explicitly specifying which tag to group on: .IP "\(bu" 4 Using \-preferred_groups .Sp When you create a Bio::DB::GFF object, pass it a \-preferred_groups=> argument. This specifies a tag that will be used for grouping. You can pass an array reference to specify a list of such tags. .IP "\(bu" 4 In the \s-1GFF\s0 header .Sp The \s-1GFF\s0 file itself can specify which tags are to be used for grouping. Insert a comment like the following: .Sp .Vb 1 \& ##group\-tags Accession Locus .Ve .Sp This says to use the Accession tag for grouping. If it is not available, use the Locus tag. If neither tag is available, use the first pair to appear. .PP These options only apply when \fBloading\fR a \s-1GFF\s0 file into the database, and have no effect on existing databases. .PP The group-tags comment in the \s-1GFF\s0 file will *override* the preferred groups set when you create the Bio::DB::GFF object. .PP For backward compatibility, the tags Sequence and Transcript are always treated as grouping tags unless preferred_tags are specified. The \*(L"Target\*(R" tag is always used for grouping regardless of the \&\fIpreferred_groups()\fR setting, and the tags \*(L"tstart\*(R", \*(L"tend\*(R" and \*(L"Note\*(R" cannot be used for grouping. These are historical artefacts coming from various interpretations of \s-1GFF2,\s0 and cannot be changed. .SS "Sequence alignments" .IX Subsection "Sequence alignments" There are two cases in which an annotation indicates the relationship between two sequences. The first case is a similarity hit, where the annotation indicates an alignment. The second case is a map assembly, in which the annotation indicates that a portion of a larger sequence is built up from one or more smaller ones. .PP Both cases are indicated by using the \fBTarget\fR tag in the group field. For example, a typical similarity hit will look like this: .PP .Vb 1 \& Chr1 BLASTX similarity 76953 77108 132 + 0 Target Protein:SW:ABL_DROME 493 544 .Ve .PP The group field contains the Target tag, followed by an identifier for the biological object referred to. The \s-1GFF\s0 format uses the notation \&\fIClass\fR:\fIName\fR for the biological object, and even though this is stylistically inconsistent, that's the way it's done. The object identifier is followed by two integers indicating the start and stop of the alignment on the target sequence. .PP Unlike the main start and stop columns, it is possible for the target start to be greater than the target end. The previous example indicates that the the section of Chr1 from 76,953 to 77,108 aligns to the protein \s-1SW:ABL_DROME\s0 starting at position 493 and extending to position 544. .PP A similar notation is used for sequence assembly information as shown in this example: .PP .Vb 2 \& Chr1 assembly Link 10922906 11177731 . . . Target Sequence:LINK_H06O01 1 254826 \& LINK_H06O01 assembly Cosmid 32386 64122 . . . Target Sequence:F49B2 6 31742 .Ve .PP This indicates that the region between bases 10922906 and 11177731 of Chr1 are composed of \s-1LINK_H06O01\s0 from bp 1 to bp 254826. The region of \s-1LINK_H0601\s0 between 32386 and 64122 is, in turn, composed of the bases 5 to 31742 of cosmid F49B2. .SS "Attributes" .IX Subsection "Attributes" While not intended to serve as a general-purpose sequence database (see bioperl-db for that), \s-1GFF\s0 allows you to tag features with arbitrary attributes. Attributes appear in the Group field following the initial class/name pair. For example: .PP .Vb 1 \& Chr1 cur trans 939 942 . + . Transcript Y95B8A.2 ; Gene sma\-3 ; Alias sma3 .Ve .PP This line tags the feature named Transcript Y95B8A.2 as being \*(L"Gene\*(R" named sma\-3 and having the Alias \*(L"sma3\*(R". Features having these attributes can be looked up using the \fIfetch_feature_by_attribute()\fR method. .PP Two attributes have special meaning: \*(L"Note\*(R" is for backward compatibility and is used for unstructured text remarks. \*(L"Alias\*(R" is considered as a synonym for the feature name and will be consulted when looking up a feature by its name. .SS "Adaptors and Aggregators" .IX Subsection "Adaptors and Aggregators" This module uses a system of adaptors and aggregators in order to make it adaptable to use with a variety of databases. .IP "\(bu" 4 Adaptors .Sp The core of the module handles the user \s-1API,\s0 annotation coordinate arithmetic, and other common issues. The details of fetching information from databases is handled by an adaptor, which is specified during Bio::DB::GFF construction. The adaptor encapsulates database-specific information such as the schema, user authentication and access methods. .Sp There are currently five adaptors recommended for general use: .Sp .Vb 2 \& Adaptor Name Description \& \-\-\-\-\-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \& \& memory A simple in\-memory database suitable for testing \& and small data sets. \& \& berkeleydb An indexed file database based on the DB_File module, \& suitable for medium\-sized read\-only data sets. \& \& dbi::mysql An interface to a schema implemented in the Mysql \& relational database management system. \& \& dbi::oracle An interface to a schema implemented in the Oracle \& relational database management system. \& \& dbi::pg An interface to a schema implemented in the PostgreSQL \& relational database management system. .Ve .Sp Check the Bio/DB/GFF/Adaptor directory and subdirectories for other, more specialized adaptors, as well as experimental ones. .IP "\(bu" 4 Aggregators .Sp The \s-1GFF\s0 format uses a \*(L"group\*(R" field to indicate aggregation properties of individual features. For example, a set of exons and introns may share a common transcript group, and multiple transcripts may share the same gene group. .Sp Aggregators are small modules that use the group information to rebuild the hierarchy. When a Bio::DB::GFF object is created, you indicate that it use a set of one or more aggregators. Each aggregator provides a new composite annotation type. Before the database query is generated each aggregator is called to \&\*(L"disaggregate\*(R" its annotation type into list of component types contained in the database. After the query is generated, each aggregator is called again in order to build composite annotations from the returned components. .Sp For example, during disaggregation, the standard \&\*(L"processed_transcript\*(R" aggregator generates a list of component feature types including \*(L"\s-1UTR\*(R", \*(L"CDS\*(R",\s0 and \*(L"polyA_site\*(R". Later, it aggregates these features into a set of annotations of type \&\*(L"processed_transcript\*(R". .Sp During aggregation, the list of aggregators is called in reverse order. This allows aggregators to collaborate to create multi-level structures: the transcript aggregator assembles transcripts from introns and exons; the gene aggregator then assembles genes from sets of transcripts. .Sp Three default aggregators are provided: .Sp .Vb 6 \& transcript assembles transcripts from features of type \& exon, CDS, 5\*(AqUTR, 3\*(AqUTR, TSS, and PolyA \& clone assembles clones from Clone_left_end, Clone_right_end \& and Sequence features. \& alignment assembles gapped alignments from features of type \& "similarity". .Ve .Sp In addition, this module provides the optional \*(L"wormbase_gene\*(R" aggregator, which accommodates the WormBase representation of genes. This aggregator aggregates features of method \*(L"exon\*(R", \*(L"\s-1CDS\*(R", \*(L"5\s0'\s-1UTR\*(R", \&\*(L"3\s0'\s-1UTR\*(R",\s0 \*(L"polyA\*(R" and \*(L"\s-1TSS\*(R"\s0 into a single object. It also expects to find a single feature of type \*(L"Sequence\*(R" that spans the entire gene. .Sp The existing aggregators are easily customized. .Sp Note that aggregation will not occur unless you specifically request the aggregation type. For example, this call: .Sp .Vb 1 \& @features = $segment\->features(\*(Aqalignment\*(Aq); .Ve .Sp will generate an array of aggregated alignment features. However, this call: .Sp .Vb 1 \& @features = $segment\->features(); .Ve .Sp will return a list of unaggregated similarity segments. .Sp For more informnation, see the manual pages for Bio::DB::GFF::Aggregator::processed_transcript, Bio::DB::GFF::Aggregator::clone, etc. .SS "Loading \s-1GFF3\s0 Files" .IX Subsection "Loading GFF3 Files" This module will accept \s-1GFF3\s0 files, as described at http://song.sourceforge.net/gff3.shtml. However, the implementation has some limitations. .IP "\s-1GFF\s0 version string is required" 4 .IX Item "GFF version string is required" The \s-1GFF\s0 file \fBmust\fR contain the version comment: .Sp .Vb 1 \& ##gff\-version 3 .Ve .Sp Unless this version string is present at the top of the \s-1GFF\s0 file, the loader will attempt to parse the file in \s-1GFF2\s0 format, with less-than-desirable results. .IP "Only one level of nesting allowed" 4 .IX Item "Only one level of nesting allowed" A major restriction is that Bio::DB::GFF only allows one level of nesting of features. For nesting, the Target tag will be used preferentially followed by the \s-1ID\s0 tag, followed by the Parent tag. This means that if genes are represented like this: .Sp .Vb 4 \& XXXX XXXX gene XXXX XXXX XXXX ID=myGene \& XXXX XXXX mRNA XXXX XXXX XXXX ID=myTranscript;Parent=myGene \& XXXX XXXX exon XXXX XXXX XXXX Parent=myTranscript \& XXXX XXXX exon XXXX XXXX XXXX Parent=myTranscript .Ve .Sp Then there will be one group called myGene containing the \*(L"gene\*(R" feature and one group called myTranscript containing the mRNA, and two exons. .Sp You can work around this restriction to some extent by using the Alias attribute literally: .Sp .Vb 4 \& XXXX XXXX gene XXXX XXXX XXXX ID=myGene \& XXXX XXXX mRNA XXXX XXXX XXXX ID=myTranscript;Parent=myGene;Alias=myGene \& XXXX XXXX exon XXXX XXXX XXXX Parent=myTranscript;Alias=myGene \& XXXX XXXX exon XXXX XXXX XXXX Parent=myTranscript;Alias=myGene .Ve .Sp This limitation will be corrected in the next version of Bio::DB::GFF. .SH "API" .IX Header "API" The following is the \s-1API\s0 for Bio::DB::GFF. .SH "Querying GFF Databases" .IX Header "Querying GFF Databases" .SS "new" .IX Subsection "new" .Vb 6 \& Title : new \& Usage : my $db = Bio::DB::GFF\->new(@args); \& Function: create a new Bio::DB::GFF object \& Returns : new Bio::DB::GFF object \& Args : lists of adaptors and aggregators \& Status : Public .Ve .PP These are the arguments: .PP .Vb 2 \& \-adaptor Name of the adaptor module to use. If none \& provided, defaults to "dbi::mysqlopt". \& \& \-aggregator Array reference to a list of aggregators \& to apply to the database. If none provided, \& defaults to [\*(Aqprocessed_transcript\*(Aq,\*(Aqalignment\*(Aq]. \& \& \-preferred_groups When interpreteting the 9th column of a GFF2 file, \& the indicated group names will have preference over \& other attributes, even if they do not come first in \& the list of attributes. This can be a scalar value \& or an array reference. \& \& Any other named argument pairs are passed to \& the adaptor for processing. .Ve .PP The adaptor argument must correspond to a module contained within the Bio::DB::GFF::Adaptor namespace. For example, the Bio::DB::GFF::Adaptor::dbi::mysql adaptor is loaded by specifying \&'dbi::mysql'. By Perl convention, the adaptors names are lower case because they are loaded at run time. .PP The aggregator array may contain a list of aggregator names, a list of initialized aggregator objects, or a string in the form \&\*(L"aggregator_name{subpart1,subpart2,subpart3/main_method}\*(R" (the \&\*(L"/main_method\*(R" part is optional, but if present a feature with the main_method must be present in order for aggregation to occur). For example, if you wish to change the components aggregated by the transcript aggregator, you could pass it to the \s-1GFF\s0 constructor this way: .PP .Vb 3 \& my $transcript = \& Bio::DB::Aggregator::transcript\->new(\-sub_parts=>[qw(exon intron utr \& polyA spliced_leader)]); \& \& my $db = Bio::DB::GFF\->new(\-aggregator=>[$transcript,\*(Aqclone\*(Aq,\*(Aqalignment], \& \-adaptor => \*(Aqdbi::mysql\*(Aq, \& \-dsn => \*(Aqdbi:mysql:elegans42\*(Aq); .Ve .PP Alternatively, you could create an entirely new transcript aggregator this way: .PP .Vb 4 \& my $new_agg = \*(Aqtranscript{exon,intron,utr,polyA,spliced_leader}\*(Aq; \& my $db = Bio::DB::GFF\->new(\-aggregator=>[$new_agg,\*(Aqclone\*(Aq,\*(Aqalignment], \& \-adaptor => \*(Aqdbi::mysql\*(Aq, \& \-dsn => \*(Aqdbi:mysql:elegans42\*(Aq); .Ve .PP See Bio::DB::GFF::Aggregator for more details. .PP The \fB\-preferred_groups\fR argument is used to change the default processing of the 9th column of \s-1GFF\s0 version 2 files. By default, the first tag/value pair is used to establish the group class and name. If you pass \-preferred_groups a scalar, the parser will look for a tag of the indicated type and use it as the group even if it is not first in the file. If you pass this argument a list of group classes as an array ref, then the list will establish the precedence for searching. .PP The commonly used 'dbi::mysql' adaptor recognizes the following adaptor-specific arguments: .PP .Vb 2 \& Argument Description \& \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \& \& \-dsn the DBI data source, e.g. \*(Aqdbi:mysql:ens0040\*(Aq \& If a partial name is given, such as "ens0040", the \& "dbi:mysql:" prefix will be added automatically. \& \& \-user username for authentication \& \& \-pass the password for authentication \& \& \-refclass landmark Class; defaults to "Sequence" .Ve .PP The commonly used 'dbi::mysqlopt' adaptor also recognizes the following arguments. .PP .Vb 2 \& Argument Description \& \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \& \& \-fasta path to a directory containing FASTA files for the DNA \& contained in this database (e.g. "/usr/local/share/fasta") \& \& \-acedb an acedb URL to use when converting features into ACEDB \& objects (e.g. sace://localhost:2005) .Ve .SS "types" .IX Subsection "types" .Vb 6 \& Title : types \& Usage : $db\->types(@args) \& Function: return list of feature types in range or database \& Returns : a list of Bio::DB::GFF::Typename objects \& Args : see below \& Status : public .Ve .PP This routine returns a list of feature types known to the database. The list can be database-wide or restricted to a region. It is also possible to find out how many times each feature occurs. .PP For range queries, it is usually more convenient to create a Bio::DB::GFF::Segment object, and then invoke it's \fItypes()\fR method. .PP Arguments are as follows: .PP .Vb 5 \& \-ref ID of reference sequence \& \-class class of reference sequence \& \-start start of segment \& \-stop stop of segment \& \-enumerate if true, count the features .Ve .PP The returned value will be a list of Bio::DB::GFF::Typename objects, which if evaluated in a string context will return the feature type in \&\*(L"method:source\*(R" format. This object class also has \fImethod()\fR and \&\fIsource()\fR methods for retrieving the like-named fields. .PP If \-enumerate is true, then the function returns a hash (not a hash reference) in which the keys are type names in \*(L"method:source\*(R" format and the values are the number of times each feature appears in the database or segment. .PP The argument \-end is a synonum for \-stop, and \-count is a synonym for \&\-enumerate. .SS "classes" .IX Subsection "classes" .Vb 6 \& Title : classes \& Usage : $db\->classes \& Function: return list of landmark classes in database \& Returns : a list of classes \& Args : none \& Status : public .Ve .PP This routine returns the list of reference classes known to the database, or empty if classes are not used by the database. Classes are distinct from types, being essentially qualifiers on the reference namespaces. .SS "segment" .IX Subsection "segment" .Vb 6 \& Title : segment \& Usage : $db\->segment(@args); \& Function: create a segment object \& Returns : segment object(s) \& Args : numerous, see below \& Status : public .Ve .PP This method generates a segment object, which is a Perl object subclassed from Bio::DB::GFF::Segment. The segment can be used to find overlapping features and the raw \s-1DNA.\s0 .PP When making the \fIsegment()\fR call, you specify the \s-1ID\s0 of a sequence landmark (e.g. an accession number, a clone or contig), and a positional range relative to the landmark. If no range is specified, then the entire extent of the landmark is used to generate the segment. .PP You may also provide the \s-1ID\s0 of a \*(L"reference\*(R" sequence, which will set the coordinate system and orientation used for all features contained within the segment. The reference sequence can be changed later. If no reference sequence is provided, then the coordinate system is based on the landmark. .PP Arguments: .PP .Vb 1 \& \-name ID of the landmark sequence. \& \& \-class Database object class for the landmark sequence. \& "Sequence" assumed if not specified. This is \& irrelevant for databases which do not recognize \& object classes. \& \& \-start Start of the segment relative to landmark. Positions \& follow standard 1\-based sequence rules. If not specified, \& defaults to the beginning of the landmark. \& \& \-end Stop of the segment relative to the landmark. If not specified, \& defaults to the end of the landmark. \& \& \-stop Same as \-end. \& \& \-offset For those who prefer 0\-based indexing, the offset specifies the \& position of the new segment relative to the start of the landmark. \& \& \-length For those who prefer 0\-based indexing, the length specifies the \& length of the new segment. \& \& \-refseq Specifies the ID of the reference landmark used to establish the \& coordinate system for the newly\-created segment. \& \& \-refclass Specifies the class of the reference landmark, for those databases \& that distinguish different object classes. Defaults to "Sequence". \& \& \-absolute \& Return features in absolute coordinates rather than relative to the \& parent segment. \& \& \-nocheck Don\*(Aqt check the database for the coordinates and length of this \& feature. Construct a segment using the indicated name as the \& reference, a start coordinate of 1, an undefined end coordinate, \& and a strand of +1. \& \& \-force Same as \-nocheck. \& \& \-seq,\-sequence,\-sourceseq Aliases for \-name. \& \& \-begin,\-end Aliases for \-start and \-stop \& \& \-off,\-len Aliases for \-offset and \-length \& \& \-seqclass Alias for \-class .Ve .PP Here's an example to explain how this works: .PP .Vb 1 \& my $db = Bio::DB::GFF\->new(\-dsn => \*(Aqdbi:mysql:human\*(Aq,\-adaptor=>\*(Aqdbi::mysql\*(Aq); .Ve .PP If successful, \f(CW$db\fR will now hold the database accessor object. We now try to fetch the fragment of sequence whose \s-1ID\s0 is A0000182 and class is \*(L"Accession.\*(R" .PP .Vb 1 \& my $segment = $db\->segment(\-name=>\*(AqA0000182\*(Aq,\-class=>\*(AqAccession\*(Aq); .Ve .PP If successful, \f(CW$segment\fR now holds the entire segment corresponding to this accession number. By default, the sequence is used as its own reference sequence, so its first base will be 1 and its last base will be the length of the accession. .PP Assuming that this sequence belongs to a longer stretch of \s-1DNA,\s0 say a contig, we can fetch this information like so: .PP .Vb 1 \& my $sourceseq = $segment\->sourceseq; .Ve .PP and find the start and stop on the source like this: .PP .Vb 2 \& my $start = $segment\->abs_start; \& my $stop = $segment\->abs_stop; .Ve .PP If we had another segment, say \f(CW$s2\fR, which is on the same contiguous piece of \s-1DNA,\s0 we can pass that to the \fIrefseq()\fR method in order to establish it as the coordinate reference point: .PP .Vb 1 \& $segment\->refseq($s2); .Ve .PP Now calling \fIstart()\fR will return the start of the segment relative to the beginning of \f(CW$s2\fR, accounting for differences in strandedness: .PP .Vb 1 \& my $rel_start = $segment\->start; .Ve .PP \&\s-1IMPORTANT NOTE:\s0 This method can be used to return the segment spanned by an arbitrary named annotation. However, if the annotation appears at multiple locations on the genome, for example an \s-1EST\s0 that maps to multiple locations, then, provided that all locations reside on the same physical segment, the method will return a segment that spans the minimum and maximum positions. If the reference sequence occupies ranges on different physical segments, then it returns them all in an array context, and raises a \*(L"multiple segment exception\*(R" exception in a scalar context. .SS "features" .IX Subsection "features" .Vb 6 \& Title : features \& Usage : $db\->features(@args) \& Function: get all features, possibly filtered by type \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : see below \& Status : public .Ve .PP This routine will retrieve features in the database regardless of position. It can be used to return all features, or a subset based on their method and source. .PP Arguments are as follows: .PP .Vb 2 \& \-types List of feature types to return. Argument is an array \& reference containing strings of the format "method:source" \& \& \-merge Whether to apply aggregators to the generated features. \& \& \-rare Turn on optimizations suitable for a relatively rare feature type, \& where it makes more sense to filter by feature type first, \& and then by position. \& \& \-attributes A hash reference containing attributes to match. \& \& \-iterator Whether to return an iterator across the features. \& \& \-binsize A true value will create a set of artificial features whose \& start and stop positions indicate bins of the given size, and \& whose scores are the number of features in the bin. The \& class and method of the feature will be set to "bin", \& its source to "method:source", and its group to "bin:method:source". \& This is a handy way of generating histograms of feature density. .Ve .PP If \-iterator is true, then the method returns a single scalar value consisting of a Bio::SeqIO object. You can call \fInext_seq()\fR repeatedly on this object to fetch each of the features in turn. If iterator is false or absent, then all the features are returned as a list. .PP Currently aggregation is disabled when iterating over a series of features. .PP Types are indicated using the nomenclature \*(L"method:source\*(R". Either of these fields can be omitted, in which case a wildcard is used for the missing field. Type names without the colon (e.g. \*(L"exon\*(R") are interpreted as the method name and a source wild card. Regular expressions are allowed in either field, as in: \*(L"similarity:BLAST.*\*(R". .PP The \-attributes argument is a hashref containing one or more attributes to match against: .PP .Vb 2 \& \-attributes => { Gene => \*(Aqabc\-1\*(Aq, \& Note => \*(Aqconfirmed\*(Aq } .Ve .PP Attribute matching is simple string matching, and multiple attributes are ANDed together. .SS "get_seq_stream" .IX Subsection "get_seq_stream" .Vb 6 \& Title : get_seq_stream \& Usage : my $seqio = $self\->get_seq_sream(@args) \& Function: Performs a query and returns an iterator over it \& Returns : a Bio::SeqIO stream capable of producing sequence \& Args : As in features() \& Status : public .Ve .PP This routine takes the same arguments as \fIfeatures()\fR, but returns a Bio::SeqIO::Stream\-compliant object. Use it like this: .PP .Vb 4 \& $stream = $db\->get_seq_stream(\*(Aqexon\*(Aq); \& while (my $exon = $stream\->next_seq) { \& print $exon,"\en"; \& } .Ve .PP \&\s-1NOTE:\s0 This is also called \fIget_feature_stream()\fR, since that's what it really does. .SS "get_feature_by_name" .IX Subsection "get_feature_by_name" .Vb 6 \& Title : get_feature_by_name \& Usage : $db\->get_feature_by_name($class => $name) \& Function: fetch features by their name \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : the class and name of the desired feature \& Status : public .Ve .PP This method can be used to fetch a named feature from the database. \&\s-1GFF\s0 annotations are named using the group class and name fields, so for features that belong to a group of size one, this method can be used to retrieve that group (and is equivalent to the \fIsegment()\fR method). Any Alias attributes are also searched for matching names. .PP An alternative syntax allows you to search for features by name within a circumscribed region: .PP .Vb 4 \& @f = $db\->get_feature_by_name(\-class => $class,\-name=>$name, \& \-ref => $sequence_name, \& \-start => $start, \& \-end => $end); .Ve .PP This method may return zero, one, or several Bio::DB::GFF::Feature objects. .PP Aggregation is performed on features as usual. .PP \&\s-1NOTE:\s0 At various times, this function was called \fIfetch_group()\fR, \&\fIfetch_feature()\fR, \fIfetch_feature_by_name()\fR and \fIsegments()\fR. These names are preserved for backward compatibility. .SS "get_feature_by_target" .IX Subsection "get_feature_by_target" .Vb 6 \& Title : get_feature_by_target \& Usage : $db\->get_feature_by_target($class => $name) \& Function: fetch features by their similarity target \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : the class and name of the desired feature \& Status : public .Ve .PP This method can be used to fetch a named feature from the database based on its similarity hit. .SS "get_feature_by_attribute" .IX Subsection "get_feature_by_attribute" .Vb 6 \& Title : get_feature_by_attribute \& Usage : $db\->get_feature_by_attribute(attribute1=>value1,attribute2=>value2) \& Function: fetch segments by combinations of attribute values \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : the class and name of the desired feature \& Status : public .Ve .PP This method can be used to fetch a set of features from the database. Attributes are a list of name=>value pairs. They will be logically \&\s-1ANDED\s0 together. .SS "get_feature_by_id" .IX Subsection "get_feature_by_id" .Vb 6 \& Title : get_feature_by_id \& Usage : $db\->get_feature_by_id($id) \& Function: fetch segments by feature ID \& Returns : a Bio::DB::GFF::Feature object \& Args : the feature ID \& Status : public .Ve .PP This method can be used to fetch a feature from the database using its \&\s-1ID.\s0 Not all \s-1GFF\s0 databases support IDs, so be careful with this. .SS "get_feature_by_gid" .IX Subsection "get_feature_by_gid" .Vb 6 \& Title : get_feature_by_gid \& Usage : $db\->get_feature_by_gid($id) \& Function: fetch segments by feature ID \& Returns : a Bio::DB::GFF::Feature object \& Args : the feature ID \& Status : public .Ve .PP This method can be used to fetch a feature from the database using its group \s-1ID.\s0 Not all \s-1GFF\s0 databases support IDs, so be careful with this. .PP The group \s-1ID\s0 is often more interesting than the feature \s-1ID,\s0 since groups can be complex objects containing subobjects. .SS "delete_fattribute_to_features" .IX Subsection "delete_fattribute_to_features" .Vb 6 \& Title : delete_fattribute_to_features \& Usage : $db\->delete_fattribute_to_features(@ids_or_features) \& Function: delete one or more fattribute_to_features \& Returns : count of fattribute_to_features deleted \& Args : list of features or feature ids \& Status : public .Ve .PP Pass this method a list of numeric feature ids or a set of features. It will attempt to remove the fattribute_to_features rows of those features from the database and return a count of the rows removed. .PP \&\s-1NOTE:\s0 This method is also called \fIdelete_fattribute_to_feature()\fR. Also see \&\fIdelete_groups()\fR and \fIdelete_features()\fR. .SS "delete_features" .IX Subsection "delete_features" .Vb 6 \& Title : delete_features \& Usage : $db\->delete_features(@ids_or_features) \& Function: delete one or more features \& Returns : count of features deleted \& Args : list of features or feature ids \& Status : public .Ve .PP Pass this method a list of numeric feature ids or a set of features. It will attempt to remove the features from the database and return a count of the features removed. .PP \&\s-1NOTE:\s0 This method is also called \fIdelete_feature()\fR. Also see \&\fIdelete_groups()\fR. .SS "delete_groups" .IX Subsection "delete_groups" .Vb 6 \& Title : delete_groups \& Usage : $db\->delete_groups(@ids_or_features) \& Function: delete one or more feature groups \& Returns : count of features deleted \& Args : list of features or feature group ids \& Status : public .Ve .PP Pass this method a list of numeric group ids or a set of features. It will attempt to recursively remove the features and \s-1ALL\s0 members of their group from the database. It returns a count of the number of features (not groups) returned. .PP \&\s-1NOTE:\s0 This method is also called \fIdelete_group()\fR. Also see \&\fIdelete_features()\fR. .SS "delete" .IX Subsection "delete" .Vb 6 \& Title : delete \& Usage : $db\->delete(@args) \& Function: delete features \& Returns : count of features deleted \-\- if available \& Args : numerous, see below \& Status : public .Ve .PP This method deletes all features that overlap the specified region or are of a particular type. If no arguments are provided and the \-force argument is true, then deletes \s-1ALL\s0 features. .PP Arguments: .PP .Vb 1 \& \-name ID of the landmark sequence. \& \& \-ref ID of the landmark sequence (synonym for \-name). \& \& \-class Database object class for the landmark sequence. \& "Sequence" assumed if not specified. This is \& irrelevant for databases which do not recognize \& object classes. \& \& \-start Start of the segment relative to landmark. Positions \& follow standard 1\-based sequence rules. If not specified, \& defaults to the beginning of the landmark. \& \& \-end Stop of the segment relative to the landmark. If not specified, \& defaults to the end of the landmark. \& \& \-offset Zero\-based addressing \& \& \-length Length of region \& \& \-type,\-types Either a single scalar type to be deleted, or an \& reference to an array of types. \& \& \-force Force operation to be performed even if it would delete \& entire feature table. \& \& \-range_type Control the range type of the deletion. One of "overlaps" (default) \& "contains" or "contained_in" .Ve .PP Examples: .PP .Vb 3 \& $db\->delete(\-type=>[\*(Aqintron\*(Aq,\*(Aqrepeat:repeatMasker\*(Aq]); # remove all introns & repeats \& $db\->delete(\-name=>\*(Aqchr3\*(Aq,\-start=>1,\-end=>1000); # remove annotations on chr3 from 1 to 1000 \& $db\->delete(\-name=>\*(Aqchr3\*(Aq,\-type=>\*(Aqexon\*(Aq); # remove all exons on chr3 .Ve .PP The short form of this call, as described in \fIsegment()\fR is also allowed: .PP .Vb 2 \& $db\->delete("chr3",1=>1000); \& $db\->delete("chr3"); .Ve .PP \&\s-1IMPORTANT NOTE:\s0 This method only deletes features. It does *NOT* delete the names of groups that contain the deleted features. Group IDs will be reused if you later load a feature with the same group name as one that was previously deleted. .PP \&\s-1NOTE ON FEATURE COUNTS:\s0 The DBI-based versions of this call return the result code from the \s-1SQL DELETE\s0 operation. Some dbd drivers return the count of rows deleted, while others return 0E0. Caveat emptor. .SS "absolute" .IX Subsection "absolute" .Vb 6 \& Title : absolute \& Usage : $abs = $db\->absolute([$abs]); \& Function: gets/sets absolute mode \& Returns : current setting of absolute mode boolean \& Args : new setting for absolute mode boolean \& Status : public .Ve .PP \&\f(CW$db\fR\->\fIabsolute\fR\|(1) will turn on absolute mode for the entire database. All segments retrieved will use absolute coordinates by default, rather than relative coordinates. You can still set them to use relative coordinates by calling \f(CW$segment\fR\->\fIabsolute\fR\|(0). .PP Note that this is not the same as calling \fIabs_segment()\fR; it continues to allow you to look up groups that are not used directly as reference sequences. .SS "strict_bounds_checking" .IX Subsection "strict_bounds_checking" .Vb 6 \& Title : strict_bounds_checking \& Usage : $flag = $db\->strict_bounds_checking([$flag]) \& Function: gets/sets strict bounds checking \& Returns : current setting of bounds checking flag \& Args : new setting for bounds checking flag \& Status : public .Ve .PP This flag enables extra checks for segment requests that go beyond the ends of their reference sequences. If bounds checking is enabled, then retrieved segments will be truncated to their physical length, and their \fItruncated()\fR methods will return true. .PP If the flag is off (the default), then the module will return segments that appear to extend beyond their physical boundaries. Requests for features beyond the end of the segment will, however, return empty. .SS "get_Seq_by_id" .IX Subsection "get_Seq_by_id" .Vb 6 \& Title : get_Seq_by_id \& Usage : $seq = $db\->get_Seq_by_id(\*(AqROA1_HUMAN\*(Aq) \& Function: Gets a Bio::Seq object by its name \& Returns : a Bio::Seq object \& Args : the id (as a string) of a sequence \& Throws : "id does not exist" exception .Ve .PP \&\s-1NOTE:\s0 Bio::DB::RandomAccessI compliant method .SS "get_Seq_by_accession" .IX Subsection "get_Seq_by_accession" .Vb 6 \& Title : get_Seq_by_accession \& Usage : $seq = $db\->get_Seq_by_accession(\*(AqAL12234\*(Aq) \& Function: Gets a Bio::Seq object by its accession \& Returns : a Bio::Seq object \& Args : the id (as a string) of a sequence \& Throws : "id does not exist" exception .Ve .PP \&\s-1NOTE:\s0 Bio::DB::RandomAccessI compliant method .SS "get_Seq_by_acc" .IX Subsection "get_Seq_by_acc" .Vb 6 \& Title : get_Seq_by_acc \& Usage : $seq = $db\->get_Seq_by_acc(\*(AqX77802\*(Aq); \& Function: Gets a Bio::Seq object by accession number \& Returns : A Bio::Seq object \& Args : accession number (as a string) \& Throws : "acc does not exist" exception .Ve .PP \&\s-1NOTE:\s0 Bio::DB::RandomAccessI compliant method .SS "get_Stream_by_name" .IX Subsection "get_Stream_by_name" .Vb 6 \& Title : get_Stream_by_name \& Usage : $seq = $db\->get_Stream_by_name(@ids); \& Function: Retrieves a stream of Seq objects given their names \& Returns : a Bio::SeqIO stream object \& Args : an array of unique ids/accession numbers, or \& an array reference .Ve .PP \&\s-1NOTE:\s0 This is also called \fIget_Stream_by_batch()\fR .SS "get_Stream_by_id" .IX Subsection "get_Stream_by_id" .Vb 6 \& Title : get_Stream_by_id \& Usage : $seq = $db\->get_Stream_by_id(@ids); \& Function: Retrieves a stream of Seq objects given their ids \& Returns : a Bio::SeqIO stream object \& Args : an array of unique ids/accession numbers, or \& an array reference .Ve .PP \&\s-1NOTE:\s0 This is also called \fIget_Stream_by_batch()\fR .SS "get_Stream_by_batch ()" .IX Subsection "get_Stream_by_batch ()" .Vb 6 \& Title : get_Stream_by_batch \& Usage : $seq = $db\->get_Stream_by_batch(@ids); \& Function: Retrieves a stream of Seq objects given their ids \& Returns : a Bio::SeqIO stream object \& Args : an array of unique ids/accession numbers, or \& an array reference .Ve .PP \&\s-1NOTE:\s0 This is the same as \fIget_Stream_by_id()\fR. .SS "get_Stream_by_group ()" .IX Subsection "get_Stream_by_group ()" Bioperl compatibility. .SS "all_seqfeatures" .IX Subsection "all_seqfeatures" .Vb 6 \& Title : all_seqfeatures \& Usage : @features = $db\->all_seqfeatures(@args) \& Function: fetch all the features in the database \& Returns : an array of features, or an iterator \& Args : See below \& Status : public .Ve .PP This is equivalent to calling \f(CW$db\fR\->\fIfeatures()\fR without any types, and will return all the features in the database. The \-merge and \&\-iterator arguments are recognized, and behave the same as described for \fIfeatures()\fR. .SH "Creating and Loading GFF Databases" .IX Header "Creating and Loading GFF Databases" .SS "initialize" .IX Subsection "initialize" .Vb 6 \& Title : initialize \& Usage : $db\->initialize(\-erase=>$erase,\-option1=>value1,\-option2=>value2); \& Function: initialize a GFF database \& Returns : true if initialization successful \& Args : a set of named parameters \& Status : Public .Ve .PP This method can be used to initialize an empty database. It takes the following named arguments: .PP .Vb 2 \& \-erase A boolean value. If true the database will be wiped clean if it \& already contains data. .Ve .PP Other named arguments may be recognized by subclasses. They become database meta values that control various settable options. .PP As a shortcut (and for backward compatibility) a single true argument is the same as initialize(\-erase=>1). .SS "load_gff" .IX Subsection "load_gff" .Vb 7 \& Title : load_gff \& Usage : $db\->load_gff($file|$directory|$filehandle [,$verbose]); \& Function: load GFF data into database \& Returns : count of records loaded \& Args : a directory, a file, a list of files, \& or a filehandle \& Status : Public .Ve .PP This method takes a single overloaded argument, which can be any of: .IP "\(bu" 4 a scalar corresponding to a \s-1GFF\s0 file on the system .Sp A pathname to a local \s-1GFF\s0 file. Any files ending with the .gz, .Z, or \&.bz2 suffixes will be transparently decompressed with the appropriate command-line utility. .IP "\(bu" 4 an array reference containing a list of \s-1GFF\s0 files on the system .Sp For example ['/home/gff/gff1.gz','/home/gff/gff2.gz'] .IP "\(bu" 4 directory path .Sp The indicated directory will be searched for all files ending in the suffixes .gff, .gff.gz, .gff.Z or .gff.bz2. .IP "\(bu" 4 filehandle .Sp An open filehandle from which to read the \s-1GFF\s0 data. Tied filehandles now work as well. .IP "\(bu" 4 a pipe expression .Sp A pipe expression will also work. For example, a \s-1GFF\s0 file on a remote web server can be loaded with an expression like this: .Sp .Vb 1 \& $db\->load_gff("lynx \-dump \-source http://stein.cshl.org/gff_test |"); .Ve .PP The optional second argument, if true, will turn on verbose status reports that indicate the progress. .PP If successful, the method will return the number of \s-1GFF\s0 lines successfully loaded. .PP NOTE:this method used to be called \fIload()\fR, but has been changed. The old method name is also recognized. .SS "load_gff_file" .IX Subsection "load_gff_file" .Vb 6 \& Title : load_gff_file \& Usage : $db\->load_gff_file($file [,$verbose]); \& Function: load GFF data into database \& Returns : count of records loaded \& Args : a path to a file \& Status : Public .Ve .PP This is provided as an alternative to load_gff_file. It doesn't munge \&\s-1STDIN\s0 or play tricks with \s-1ARGV.\s0 .SS "load_fasta" .IX Subsection "load_fasta" .Vb 7 \& Title : load_fasta \& Usage : $db\->load_fasta($file|$directory|$filehandle); \& Function: load FASTA data into database \& Returns : count of records loaded \& Args : a directory, a file, a list of files, \& or a filehandle \& Status : Public .Ve .PP This method takes a single overloaded argument, which can be any of: .IP "\(bu" 4 scalar corresponding to a \s-1FASTA\s0 file on the system .Sp A pathname to a local \s-1FASTA\s0 file. Any files ending with the .gz, .Z, or \&.bz2 suffixes will be transparently decompressed with the appropriate command-line utility. .IP "\(bu" 4 array reference containing a list of \s-1FASTA\s0 files on the system .Sp For example ['/home/fasta/genomic.fa.gz','/home/fasta/genomic.fa.gz'] .IP "\(bu" 4 path to a directory .Sp The indicated directory will be searched for all files ending in the suffixes .fa, .fa.gz, .fa.Z or .fa.bz2. .IP "\(bu" 4 filehandle .Sp An open filehandle from which to read the \s-1FASTA\s0 data. .IP "\(bu" 4 pipe expression .Sp A pipe expression will also work. For example, a \s-1FASTA\s0 file on a remote web server can be loaded with an expression like this: .Sp .Vb 1 \& $db\->load_gff("lynx \-dump \-source http://stein.cshl.org/fasta_test.fa |"); .Ve .SS "load_fasta_file" .IX Subsection "load_fasta_file" .Vb 6 \& Title : load_fasta_file \& Usage : $db\->load_fasta_file($file [,$verbose]); \& Function: load FASTA data into database \& Returns : count of records loaded \& Args : a path to a file \& Status : Public .Ve .PP This is provided as an alternative to load_fasta. It doesn't munge \&\s-1STDIN\s0 or play tricks with \s-1ARGV.\s0 .SS "load_sequence_string" .IX Subsection "load_sequence_string" .Vb 6 \& Title : load_sequence_string \& Usage : $db\->load_sequence_string($id,$dna) \& Function: load a single DNA entry \& Returns : true if successfully loaded \& Args : a raw sequence string (DNA, RNA, protein) \& Status : Public .Ve .SS "lock_on_load" .IX Subsection "lock_on_load" .Vb 6 \& Title : lock_on_load \& Usage : $lock = $db\->lock_on_load([$lock]) \& Function: set write locking during load \& Returns : current value of lock\-on\-load flag \& Args : new value of lock\-on\-load\-flag \& Status : Public .Ve .PP This method is honored by some of the adaptors. If the value is true, the tables used by the \s-1GFF\s0 modules will be locked for writing during loads and inaccessible to other processes. .SS "meta" .IX Subsection "meta" .Vb 6 \& Title : meta \& Usage : $value = $db\->meta($name [,$newval]) \& Function: get or set a meta variable \& Returns : a string \& Args : meta variable name and optionally value \& Status : abstract .Ve .PP Get or set a named metavalues for the database. Metavalues can be used for database-specific settings. .PP By default, this method does nothing! .SS "default_meta_values" .IX Subsection "default_meta_values" .Vb 6 \& Title : default_meta_values \& Usage : %values = $db\->default_meta_values \& Function: empty the database \& Returns : a list of tag=>value pairs \& Args : none \& Status : protected .Ve .PP This method returns a list of tag=>value pairs that contain default meta information about the database. It is invoked by \fIinitialize()\fR to write out the default meta values. The base class version returns an empty list. .PP For things to work properly, meta value names must be \s-1UPPERCASE.\s0 .SS "error" .IX Subsection "error" .Vb 6 \& Title : error \& Usage : $db\->error( [$new error] ); \& Function: read or set error message \& Returns : error message \& Args : an optional argument to set the error message \& Status : Public .Ve .PP This method can be used to retrieve the last error message. Errors are not reset to empty by successful calls, so contents are only valid immediately after an error condition has been detected. .SS "debug" .IX Subsection "debug" .Vb 6 \& Title : debug \& Usage : $db\->debug( [$flag] ); \& Function: read or set debug flag \& Returns : current value of debug flag \& Args : new debug flag (optional) \& Status : Public .Ve .PP This method can be used to turn on debug messages. The exact nature of those messages depends on the adaptor in use. .SS "automerge" .IX Subsection "automerge" .Vb 6 \& Title : automerge \& Usage : $db\->automerge( [$new automerge] ); \& Function: get or set automerge value \& Returns : current value (boolean) \& Args : an optional argument to set the automerge value \& Status : Public .Ve .PP By default, this module will use the aggregators to merge groups into single composite objects. This default can be changed to false by calling \fIautomerge\fR\|(0). .SS "attributes" .IX Subsection "attributes" .Vb 6 \& Title : attributes \& Usage : @attributes = $db\->attributes($id,$name) \& Function: get the "attributes" on a particular feature \& Returns : an array of string \& Args : feature ID \& Status : public .Ve .PP Some \s-1GFF\s0 version 2 files use the groups column to store a series of attribute/value pairs. In this interpretation of \s-1GFF,\s0 the first such pair is treated as the primary group for the feature; subsequent pairs are treated as attributes. Two attributes have special meaning: \&\*(L"Note\*(R" is for backward compatibility and is used for unstructured text remarks. \*(L"Alias\*(R" is considered as a synonym for the feature name. .PP If no name is provided, then \fIattributes()\fR returns a flattened hash, of attribute=>value pairs. This lets you do: .PP .Vb 1 \& %attributes = $db\->attributes($id); .Ve .PP If no arguments are provided, \fIattributes()\fR will return the list of all attribute names: .PP .Vb 1 \& @attribute_names = $db\->attributes(); .Ve .PP Normally, however, \fIattributes()\fR will be called by the feature: .PP .Vb 1 \& @notes = $feature\->attributes(\*(AqNote\*(Aq); .Ve .PP In a scalar context, \fIattributes()\fR returns the first value of the attribute if a tag is present, otherwise a hash reference in which the keys are attribute names and the values are anonymous arrays containing the values. .SS "fast_queries" .IX Subsection "fast_queries" .Vb 6 \& Title : fast_queries \& Usage : $flag = $db\->fast_queries([$flag]) \& Function: turn on and off the "fast queries" option \& Returns : a boolean \& Args : a boolean flag (optional) \& Status : public .Ve .PP The mysql database driver (and possibly others) support a \*(L"fast\*(R" query mode that caches results on the server side. This makes queries come back faster, particularly when creating iterators. The downside is that while iterating, new queries will die with a \*(L"command synch\*(R" error. This method turns the feature on and off. .PP For databases that do not support a fast query, this method has no effect. .SS "add_aggregator" .IX Subsection "add_aggregator" .Vb 6 \& Title : add_aggregator \& Usage : $db\->add_aggregator($aggregator) \& Function: add an aggregator to the list \& Returns : nothing \& Args : an aggregator \& Status : public .Ve .PP This method will append an aggregator to the end of the list of registered aggregators. Three different argument types are accepted: .PP .Vb 6 \& 1) a Bio::DB::GFF::Aggregator object \-\- will be added \& 2) a string in the form "aggregator_name{subpart1,subpart2,subpart3/main_method}" \& \-\- will be turned into a Bio::DB::GFF::Aggregator object (the /main_method \& part is optional). \& 3) a valid Perl token \-\- will be turned into a Bio::DB::GFF::Aggregator \& subclass, where the token corresponds to the subclass name. .Ve .SS "aggregators" .IX Subsection "aggregators" .Vb 6 \& Title : aggregators \& Usage : $db\->aggregators([@new_aggregators]); \& Function: retrieve list of aggregators \& Returns : list of aggregators \& Args : a list of aggregators to set (optional) \& Status : public .Ve .PP This method will get or set the list of aggregators assigned to the database. If 1 or more arguments are passed, the existing set will be cleared. .SS "clear_aggregators" .IX Subsection "clear_aggregators" .Vb 6 \& Title : clear_aggregators \& Usage : $db\->clear_aggregators \& Function: clears list of aggregators \& Returns : nothing \& Args : none \& Status : public .Ve .PP This method will clear the aggregators stored in the database object. Use \fIaggregators()\fR or \fIadd_aggregator()\fR to add some back. .SS "preferred_groups" .IX Subsection "preferred_groups" .Vb 6 \& Title : preferred_groups \& Usage : $db\->preferred_groups([$group_name_or_arrayref]) \& Function: get/set list of groups for altering GFF2 parsing \& Returns : a list of classes \& Args : new list (scalar or array ref) \& Status : public .Ve .SH "Methods for use by Subclasses" .IX Header "Methods for use by Subclasses" The following methods are chiefly of interest to subclasses and are not intended for use by end programmers. .SS "abscoords" .IX Subsection "abscoords" .Vb 6 \& Title : abscoords \& Usage : $db\->abscoords($name,$class,$refseq) \& Function: finds position of a landmark in reference coordinates \& Returns : ($ref,$class,$start,$stop,$strand) \& Args : name and class of landmark \& Status : public .Ve .PP This method is called by Bio::DB::GFF::RelSegment to obtain the absolute coordinates of a sequence landmark. The arguments are the name and class of the landmark. If successful, \fIabscoords()\fR returns the \s-1ID\s0 of the reference sequence, its class, its start and stop positions, and the orientation of the reference sequence's coordinate system (\*(L"+\*(R" for forward strand, \*(L"\-\*(R" for reverse strand). .PP If \f(CW$refseq\fR is present in the argument list, it forces the query to search for the landmark in a particular reference sequence. .SH "Protected API" .IX Header "Protected API" The following methods are not intended for public consumption, but are intended to be overridden/implemented by adaptors. .SS "default_aggregators" .IX Subsection "default_aggregators" .Vb 6 \& Title : default_aggregators \& Usage : $db\->default_aggregators; \& Function: retrieve list of aggregators \& Returns : array reference containing list of aggregator names \& Args : none \& Status : protected .Ve .PP This method (which is intended to be overridden by adaptors) returns a list of standard aggregators to be applied when no aggregators are specified in the constructor. .SS "do_load_gff" .IX Subsection "do_load_gff" .Vb 6 \& Title : do_load_gff \& Usage : $db\->do_load_gff($handle) \& Function: load a GFF input stream \& Returns : number of features loaded \& Args : A filehandle. \& Status : protected .Ve .PP This method is called to load a \s-1GFF\s0 data stream. The method will read \&\s-1GFF\s0 features from <> and load them into the database. On exit the method must return the number of features loaded. .PP Note that the method is responsible for parsing the \s-1GFF\s0 lines. This is to allow for differences in the interpretation of the \*(L"group\*(R" field, which are legion. .PP You probably want to use \fIload_gff()\fR instead. It is more flexible about the arguments it accepts. .SS "load_sequence" .IX Subsection "load_sequence" .Vb 6 \& Title : load_sequence \& Usage : $db\->load_sequence($handle) \& Function: load a FASTA data stream \& Returns : number of sequences \& Args : a filehandle to the FASTA file \& Status : protected .Ve .PP You probably want to use \fIload_fasta()\fR instead. .SS "setup_load" .IX Subsection "setup_load" .Vb 6 \& Title : setup_load \& Usage : $db\->setup_load \& Function: called before load_gff_line() \& Returns : void \& Args : none \& Status : abstract .Ve .PP This abstract method gives subclasses a chance to do any schema-specific initialization prior to loading a set of \s-1GFF\s0 records. It must be implemented by a subclass. .SS "finish_load" .IX Subsection "finish_load" .Vb 6 \& Title : finish_load \& Usage : $db\->finish_load \& Function: called after load_gff_line() \& Returns : number of records loaded \& Args : none \& Status :abstract .Ve .PP This method gives subclasses a chance to do any schema-specific cleanup after loading a set of \s-1GFF\s0 records. .SS "load_gff_line" .IX Subsection "load_gff_line" .Vb 6 \& Title : load_gff_line \& Usage : $db\->load_gff_line(@args) \& Function: called to load one parsed line of GFF \& Returns : true if successfully inserted \& Args : see below \& Status : abstract .Ve .PP This abstract method is called once per line of the \s-1GFF\s0 and passed a hashref containing parsed \s-1GFF\s0 fields. The fields are: .PP .Vb 10 \& {ref => $ref, \& class => $class, \& source => $source, \& method => $method, \& start => $start, \& stop => $stop, \& score => $score, \& strand => $strand, \& phase => $phase, \& gclass => $gclass, \& gname => $gname, \& tstart => $tstart, \& tstop => $tstop, \& attributes => $attributes} .Ve .SS "do_initialize" .IX Subsection "do_initialize" .Vb 6 \& Title : do_initialize \& Usage : $db\->do_initialize([$erase]) \& Function: initialize and possibly erase database \& Returns : true if successful \& Args : optional erase flag \& Status : protected .Ve .PP This method implements the \fIinitialize()\fR method described above, and takes the same arguments. .SS "dna" .IX Subsection "dna" .Vb 6 \& Title : dna \& Usage : $db\->dna($id,$start,$stop,$class) \& Function: return the raw DNA string for a segment \& Returns : a raw DNA string \& Args : id of the sequence, its class, start and stop positions \& Status : public .Ve .PP This method is invoked by Bio::DB::GFF::Segment to fetch the raw \s-1DNA\s0 sequence. .PP Arguments: \-name sequence name \-start start position \-stop stop position \-class sequence class .PP If start and stop are both undef, then the entire \s-1DNA\s0 is retrieved. So to fetch the whole dna, call like this: .PP .Vb 1 \& $db\->dna($name_of_sequence); .Ve .PP or like this: .PP .Vb 1 \& $db\->dna(\-name=>$name_of_sequence,\-class=>$class_of_sequence); .Ve .PP \&\s-1NOTE:\s0 you will probably prefer to create a Segment and then invoke its \&\fIdna()\fR method. .SS "get_dna" .IX Subsection "get_dna" .Vb 6 \& Title : get_dna \& Usage : $db\->get_dna($id,$start,$stop,$class) \& Function: get DNA for indicated segment \& Returns : the dna string \& Args : sequence ID, start, stop and class \& Status : protected .Ve .PP If start > stop and the sequence is nucleotide, then this method should return the reverse complement. The sequence class may be ignored by those databases that do not recognize different object types. .SS "get_features" .IX Subsection "get_features" .Vb 6 \& Title : get_features \& Usage : $db\->get_features($search,$options,$callback) \& Function: get list of features for a region \& Returns : count of number of features retrieved \& Args : see below \& Status : protected .Ve .PP The first argument is a hash reference containing search criteria for retrieving features. It contains the following keys: .PP .Vb 2 \& rangetype One of "overlaps", "contains" or "contained_in". Indicates \& the type of range query requested. \& \& refseq ID of the landmark that establishes the absolute \& coordinate system. \& \& refclass Class of this landmark. Can be ignored by implementations \& that don\*(Aqt recognize such distinctions. \& \& start Start of the range, inclusive. \& \& stop Stop of the range, inclusive. \& \& types Array reference containing the list of annotation types \& to fetch from the database. Each annotation type is an \& array reference consisting of [source,method]. .Ve .PP The second argument is a hash reference containing certain options that affect the way information is retrieved: .PP .Vb 3 \& sort_by_group \& A flag. If true, means that the returned features should be \& sorted by the group that they\*(Aqre in. \& \& sparse A flag. If true, means that the expected density of the \& features is such that it will be more efficient to search \& by type rather than by range. If it is taking a long \& time to fetch features, give this a try. \& \& binsize A true value will create a set of artificial features whose \& start and stop positions indicate bins of the given size, and \& whose scores are the number of features in the bin. The \& class of the feature will be set to "bin", and its name to \& "method:source". This is a handy way of generating histograms \& of feature density. .Ve .PP The third argument, the \f(CW$callback\fR, is a code reference to which retrieved features are passed. It is described in more detail below. .PP This routine is responsible for getting arrays of \s-1GFF\s0 data out of the database and passing them to the callback subroutine. The callback does the work of constructing a Bio::DB::GFF::Feature object out of that data. The callback expects a list of 13 fields: .PP .Vb 10 \& $refseq The reference sequence \& $start feature start \& $stop feature stop \& $source feature source \& $method feature method \& $score feature score \& $strand feature strand \& $phase feature phase \& $groupclass group class (may be undef) \& $groupname group ID (may be undef) \& $tstart target start for similarity hits (may be undef) \& $tstop target stop for similarity hits (may be undef) \& $feature_id A unique feature ID (may be undef) .Ve .PP These fields are in the same order as the raw \s-1GFF\s0 file, with the exception that the group column has been parsed into group class and group name fields. .PP The feature \s-1ID,\s0 if provided, is a unique identifier of the feature line. The module does not depend on this \s-1ID\s0 in any way, but it is available via Bio::DB::GFF\->\fIid()\fR if wanted. In the dbi::mysql and dbi::mysqlopt adaptor, the \s-1ID\s0 is a unique row \s-1ID.\s0 In the acedb adaptor it is not used. .SS "\fIfeature_summary()\fP, \fIcoverage_array()\fP" .IX Subsection "feature_summary(), coverage_array()" The \s-1DBI\s0 adaptors provide methods for rapidly fetching coverage statistics across a region of interest. Please see Bio::DB::GFF::Adaptor::dbi for more information about these methods. .SS "_feature_by_name" .IX Subsection "_feature_by_name" .Vb 6 \& Title : _feature_by_name \& Usage : $db\->_feature_by_name($class,$name,$location,$callback) \& Function: get a list of features by name and class \& Returns : count of number of features retrieved \& Args : name of feature, class of feature, and a callback \& Status : abstract .Ve .PP This method is used internally. The callback arguments are the same as those used by \fImake_feature()\fR. This method must be overridden by subclasses. .SS "_feature_by_id" .IX Subsection "_feature_by_id" .Vb 6 \& Title : _feature_by_id \& Usage : $db\->_feature_by_id($ids,$type,$callback) \& Function: get a feature based \& Returns : count of number of features retrieved \& Args : arrayref to feature IDs to fetch \& Status : abstract .Ve .PP This method is used internally to fetch features either by their \s-1ID\s0 or their group \s-1ID.\s0 \f(CW$ids\fR is a arrayref containing a list of IDs, \f(CW$type\fR is one of \*(L"feature\*(R" or \*(L"group\*(R", and \f(CW$callback\fR is a callback. The callback arguments are the same as those used by \fImake_feature()\fR. This method must be overridden by subclasses. .SS "overlapping_features" .IX Subsection "overlapping_features" .Vb 6 \& Title : overlapping_features \& Usage : $db\->overlapping_features(@args) \& Function: get features that overlap the indicated range \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : see below \& Status : public .Ve .PP This method is invoked by Bio::DB::GFF::Segment\->\fIfeatures()\fR to find the list of features that overlap a given range. It is generally preferable to create the Segment first, and then fetch the features. .PP This method takes set of named arguments: .PP .Vb 10 \& \-refseq ID of the reference sequence \& \-class Class of the reference sequence \& \-start Start of the desired range in refseq coordinates \& \-stop Stop of the desired range in refseq coordinates \& \-types List of feature types to return. Argument is an array \& reference containing strings of the format "method:source" \& \-parent A parent Bio::DB::GFF::Segment object, used to create \& relative coordinates in the generated features. \& \-rare Turn on an optimization suitable for a relatively rare feature type, \& where it will be faster to filter by feature type first \& and then by position, rather than vice versa. \& \-merge Whether to apply aggregators to the generated features. \& \-iterator Whether to return an iterator across the features. .Ve .PP If \-iterator is true, then the method returns a single scalar value consisting of a Bio::SeqIO object. You can call \fInext_seq()\fR repeatedly on this object to fetch each of the features in turn. If iterator is false or absent, then all the features are returned as a list. .PP Currently aggregation is disabled when iterating over a series of features. .PP Types are indicated using the nomenclature \*(L"method:source\*(R". Either of these fields can be omitted, in which case a wildcard is used for the missing field. Type names without the colon (e.g. \*(L"exon\*(R") are interpreted as the method name and a source wild card. Regular expressions are allowed in either field, as in: \*(L"similarity:BLAST.*\*(R". .SS "contained_features" .IX Subsection "contained_features" .Vb 6 \& Title : contained_features \& Usage : $db\->contained_features(@args) \& Function: get features that are contained within the indicated range \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : see overlapping_features() \& Status : public .Ve .PP This call is similar to \fIoverlapping_features()\fR, except that it only retrieves features whose end points are completely contained within the specified range. .PP Generally you will want to fetch a Bio::DB::GFF::Segment object and call its \fIcontained_features()\fR method rather than call this directly. .SS "contained_in" .IX Subsection "contained_in" .Vb 6 \& Title : contained_in \& Usage : @features = $s\->contained_in(@args) \& Function: get features that contain this segment \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : see features() \& Status : Public .Ve .PP This is identical in behavior to \fIfeatures()\fR except that it returns only those features that completely contain the segment. .SS "get_abscoords" .IX Subsection "get_abscoords" .Vb 6 \& Title : get_abscoords \& Usage : $db\->get_abscoords($name,$class,$refseq) \& Function: get the absolute coordinates of sequence with name & class \& Returns : ($absref,$absstart,$absstop,$absstrand) \& Args : name and class of the landmark \& Status : protected .Ve .PP Given the name and class of a genomic landmark, this function returns a four-element array consisting of: .PP .Vb 4 \& $absref the ID of the reference sequence that contains this landmark \& $absstart the position at which the landmark starts \& $absstop the position at which the landmark stops \& $absstrand the strand of the landmark, relative to the reference sequence .Ve .PP If \f(CW$refseq\fR is provided, the function searches only within the specified reference sequence. .SS "get_types" .IX Subsection "get_types" .Vb 6 \& Title : get_types \& Usage : $db\->get_types($absref,$class,$start,$stop,$count) \& Function: get list of all feature types on the indicated segment \& Returns : list or hash of Bio::DB::GFF::Typename objects \& Args : see below \& Status : protected .Ve .PP Arguments are: .PP .Vb 6 \& $absref the ID of the reference sequence \& $class the class of the reference sequence \& $start the position to start counting \& $stop the position to end counting \& $count a boolean indicating whether to count the number \& of occurrences of each feature type .Ve .PP If \f(CW$count\fR is true, then a hash is returned. The keys of the hash are feature type names in the format \*(L"method:source\*(R" and the values are the number of times a feature of this type overlaps the indicated segment. Otherwise, the call returns a set of Bio::DB::GFF::Typename objects. If \f(CW$start\fR or \f(CW$stop\fR are undef, then all features on the indicated segment are enumerated. If \f(CW$absref\fR is undef, then the call returns all feature types in the database. .SS "make_feature" .IX Subsection "make_feature" .Vb 6 \& Title : make_feature \& Usage : $db\->make_feature(@args) \& Function: Create a Bio::DB::GFF::Feature object from string data \& Returns : a Bio::DB::GFF::Feature object \& Args : see below \& Status : internal \& \& This takes 14 arguments (really!): \& \& $parent A Bio::DB::GFF::RelSegment object \& $group_hash A hashref containing unique list of GFF groups \& $refname The name of the reference sequence for this feature \& $refclass The class of the reference sequence for this feature \& $start Start of feature \& $stop Stop of feature \& $source Feature source field \& $method Feature method field \& $score Feature score field \& $strand Feature strand \& $phase Feature phase \& $group_class Class of feature group \& $group_name Name of feature group \& $tstart For homologies, start of hit on target \& $tstop Stop of hit on target .Ve .PP The \f(CW$parent\fR argument, if present, is used to establish relative coordinates in the resulting Bio::DB::Feature object. This allows one feature to generate a list of other features that are relative to its coordinate system (for example, finding the coordinates of the second exon relative to the coordinates of the first). .PP The \f(CW$group_hash\fR allows the group_class/group_name strings to be turned into rich database objects via the \fImake_obect()\fR method (see above). Because these objects may be expensive to create, \f(CW$group_hash\fR is used to uniquefy them. The index of this hash is the composite key {$group_class,$group_name,$tstart,$tstop}. Values are whatever object is returned by the \fImake_object()\fR method. .PP The remainder of the fields are taken from the \s-1GFF\s0 line, with the exception that \*(L"Target\*(R" features, which contain information about the target of a homology search, are parsed into their components. .SS "make_match_sub" .IX Subsection "make_match_sub" .Vb 6 \& Title : make_match_sub \& Usage : $db\->make_match_sub($types) \& Function: creates a subroutine used for filtering features \& Returns : a code reference \& Args : a list of parsed type names \& Status : protected .Ve .PP This method is used internally to generate a code subroutine that will accept or reject a feature based on its method and source. It takes an array of parsed type names in the format returned by \fIparse_types()\fR, and generates an anonymous subroutine. The subroutine takes a single Bio::DB::GFF::Feature object and returns true if the feature matches one of the desired feature types, and false otherwise. .SS "make_object" .IX Subsection "make_object" .Vb 6 \& Title : make_object \& Usage : $db\->make_object($class,$name,$start,$stop) \& Function: creates a feature object \& Returns : a feature object \& Args : see below \& Status : protected .Ve .PP This method is called to make an object from the \s-1GFF\s0 \*(L"group\*(R" field. By default, all Target groups are turned into Bio::DB::GFF::Homol objects, and everything else becomes a Bio::DB::GFF::Featname. However, adaptors are free to override this method to generate more interesting objects, such as true BioPerl objects, or Acedb objects. .PP Arguments are: .PP .Vb 4 \& $name database ID for object \& $class class of object \& $start for similarities, start of match inside object \& $stop for similarities, stop of match inside object .Ve .SS "do_attributes" .IX Subsection "do_attributes" .Vb 6 \& Title : do_attributes \& Usage : $db\->do_attributes($id [,$tag]); \& Function: internal method to retrieve attributes given an id and tag \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : a feature id and a attribute tag (optional) \& Status : protected .Ve .PP This method is overridden by subclasses in order to return a list of attributes. If called with a tag, returns the value of attributes of that tag type. If called without a tag, returns a flattened array of (tag=>value) pairs. A particular tag can be present multiple times. .SS "clone" .IX Subsection "clone" The \fIclone()\fR method should be used when you want to pass the Bio::DB::GFF object to a child process across a \fIfork()\fR. The child must call \fIclone()\fR before making any queries. .PP The default behavior is to do nothing, but adaptors that use the \s-1DBI\s0 interface may need to implement this in order to avoid database handle errors. See the dbi adaptor for an example. .SH "Internal Methods" .IX Header "Internal Methods" The following methods are internal to Bio::DB::GFF and are not guaranteed to remain the same. .SS "_features" .IX Subsection "_features" .Vb 6 \& Title : _features \& Usage : $db\->_features($search,$options,$parent) \& Function: internal method \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : see below \& Status : internal .Ve .PP This is an internal method that is called by \fIoverlapping_features()\fR, \&\fIcontained_features()\fR and \fIfeatures()\fR to create features based on a parent segment's coordinate system. It takes three arguments, a search options hashref, an options hashref, and a parent segment. .PP The search hashref contains the following keys: .PP .Vb 7 \& rangetype One of "overlaps", "contains" or "contained_in". Indicates \& the type of range query requested. \& refseq reference sequence ID \& refclass reference sequence class \& start start of range \& stop stop of range \& types arrayref containing list of types in "method:source" form .Ve .PP The options hashref contains zero or more of the following keys: .PP .Vb 3 \& sparse turn on optimizations for a rare feature \& automerge if true, invoke aggregators to merge features \& iterator if true, return an iterator .Ve .PP The \f(CW$parent\fR argument is a scalar object containing a Bio::DB::GFF::RelSegment object or descendent. .SS "get_features_iterator" .IX Subsection "get_features_iterator" .Vb 6 \& Title : get_features_iterator \& Usage : $db\->get_features_iterator($search,$options,$callback) \& Function: get an iterator on a features query \& Returns : a Bio::SeqIO object \& Args : as per get_features() \& Status : Public .Ve .PP This method takes the same arguments as \fIget_features()\fR, but returns an iterator that can be used to fetch features sequentially, as per Bio::SeqIO. .PP Internally, this method is simply a front end to \fIrange_query()\fR. The latter method constructs and executes the query, returning a statement handle. This routine passes the statement handle to the constructor for the iterator, along with the callback. .SS "split_group" .IX Subsection "split_group" .Vb 6 \& Title : split_group \& Usage : $db\->split_group($group_field,$gff3_flag) \& Function: parse GFF group field \& Returns : ($gclass,$gname,$tstart,$tstop,$attributes) \& Args : the gff group column and a flag indicating gff3 compatibility \& Status : internal .Ve .PP This is a method that is called by load_gff_line to parse out the contents of one or more group fields. It returns the class of the group, its name, the start and stop of the target, if any, and an array reference containing any attributes that were stuck into the group field, in [attribute_name,attribute_value] format. .SS "_split_gff2_group" .IX Subsection "_split_gff2_group" This is an internal method called by \fIsplit_group()\fR. .SS "gff3_name_munging" .IX Subsection "gff3_name_munging" .Vb 6 \& Title : gff3_name_munging \& Usage : $db\->gff3_name_munging($boolean) \& Function: get/set gff3_name_munging flag \& Returns : $current value of flag \& Args : new value of flag (optional) \& Status : utility .Ve .PP If this is set to true (default false), then features identified in gff3 files with an \s-1ID\s0 in the format foo:bar will be parsed so that \&\*(L"foo\*(R" is the class and \*(L"bar\*(R" is the name. This is mostly for backward compatibility with \s-1GFF2.\s0 .SS "_split_gff3_group" .IX Subsection "_split_gff3_group" This is called internally from \fIsplit_group()\fR. .SS "\fI_delete_features()\fP, \fI_delete_groups()\fP,\fI_delete()\fP,\fI_delete_fattribute_to_features()\fP" .IX Subsection "_delete_features(), _delete_groups(),_delete(),_delete_fattribute_to_features()" .Vb 9 \& Title : _delete_features(), _delete_groups(),_delete(),_delete_fattribute_to_features() \& Usage : $count = $db\->_delete_features(@feature_ids) \& $count = $db\->_delete_groups(@group_ids) \& $count = $db\->_delete(\e%delete_spec) \& $count = $db\->_delete_fattribute_to_features(@feature_ids) \& Function: low\-level feature/group deleter \& Returns : count of groups removed \& Args : list of feature or group ids removed \& Status : for implementation by subclasses .Ve .PP These methods need to be implemented in adaptors. For _delete_features, _delete_groups and _delete_fattribute_to_features, the arguments are a list of feature or group IDs to remove. For \fI_delete()\fR, the argument is a hashref with the three keys 'segments', 'types' and 'force'. The first contains an arrayref of Bio::DB::GFF::RelSegment objects to delete (all \s-1FEATURES\s0 within the segment are deleted). The second contains an arrayref of [method,source] feature types to delete. The two are ANDed together. If 'force' has a true value, this forces the operation to continue even if it would delete all features. .SH "BUGS" .IX Header "BUGS" Features can only belong to a single group at a time. This must be addressed soon. .PP Start coordinate can be greater than stop coordinate for relative addressing. This breaks strict BioPerl compatibility and must be fixed. .SH "SEE ALSO" .IX Header "SEE ALSO" Bio::DB::GFF::RelSegment, Bio::DB::GFF::Aggregator, Bio::DB::GFF::Feature, Bio::DB::GFF::Adaptor::dbi::mysqlopt, Bio::DB::GFF::Adaptor::dbi::oracle, Bio::DB::GFF::Adaptor::memory Bio::DB::GFF::Adaptor::berkeleydb .SH "AUTHOR" .IX Header "AUTHOR" Lincoln Stein . .PP Copyright (c) 2001 Cold Spring Harbor Laboratory. .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.