.\" Automatically generated by Pod::Man 4.11 (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 .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Bio::DasI 3pm" .TH Bio::DasI 3pm "2020-10-28" "perl v5.30.3" "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::DasI \- DAS\-style access to a feature database .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& # Open up a feature database somehow... \& $db = Bio::DasI\->new(@args); \& \& @segments = $db\->segment(\-name => \*(AqNT_29921.4\*(Aq, \& \-start => 1, \& \-end => 1000000); \& \& # segments are Bio::Das::SegmentI \- compliant objects \& \& # fetch a list of features \& @features = $db\->features(\-type=>[\*(Aqtype1\*(Aq,\*(Aqtype2\*(Aq,\*(Aqtype3\*(Aq]); \& \& # invoke a callback over features \& $db\->features(\-type=>[\*(Aqtype1\*(Aq,\*(Aqtype2\*(Aq,\*(Aqtype3\*(Aq], \& \-callback => sub { ... } \& ); \& \& $stream = $db\->get_seq_stream(\-type=>[\*(Aqtype1\*(Aq,\*(Aqtype2\*(Aq,\*(Aqtype3\*(Aq]); \& while (my $feature = $stream\->next_seq) { \& # each feature is a Bio::SeqFeatureI\-compliant object \& } \& \& # get all feature types \& @types = $db\->types; \& \& # count types \& %types = $db\->types(\-enumerate=>1); \& \& @feature = $db\->get_feature_by_name($class=>$name); \& @feature = $db\->get_feature_by_target($target_name); \& @feature = $db\->get_feature_by_attribute($att1=>$value1,$att2=>$value2); \& $feature = $db\->get_feature_by_id($id); \& \& $error = $db\->error; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" Bio::DasI is a simplified alternative interface to sequence annotation databases used by the distributed annotation system (see Bio::Das). In this scheme, the genome is represented as a series of features, a subset of which are named. Named features can be used as reference points for retrieving \*(L"segments\*(R" (see Bio::Das::SegmentI), and these can, in turn, be used as the basis for exploring the genome further. .PP In addition to a name, each feature has a \*(L"class\*(R", which is essentially a namespace qualifier and a \*(L"type\*(R", which describes what type of feature it is. Das uses the \s-1GO\s0 consortium's ontology of feature types, and so the type is actually an object of class Bio::Das::FeatureTypeI (see Bio::Das::FeatureTypeI). Bio::DasI provides methods for interrogating the database for the types it contains and the counts of each type. .SH "FEEDBACK" .IX Header "FEEDBACK" .SS "Mailing Lists" .IX Subsection "Mailing Lists" User feedback is an integral part of the evolution of this and other Bioperl modules. Send your comments and suggestions preferably to one of the Bioperl mailing lists. Your participation is much appreciated. .PP .Vb 1 \& bioperl\-l@bioperl.org .Ve .SS "Support" .IX Subsection "Support" Please direct usage questions or support issues to the mailing list: .PP \&\fIbioperl\-l@bioperl.org\fR .PP rather than to the module maintainer directly. Many experienced and reponsive experts will be able look at the problem and quickly address it. Please include a thorough description of the problem with code and data examples if at all possible. .SS "Reporting Bugs" .IX Subsection "Reporting Bugs" Report bugs to the Bioperl bug tracking system to help us keep track the bugs and their resolution. Bug reports can be submitted via the web: .PP .Vb 1 \& https://github.com/bioperl/bioperl\-live/issues .Ve .SH "AUTHOR \- Lincoln Stein" .IX Header "AUTHOR - Lincoln Stein" Email lstein@cshl.org .SH "APPENDIX" .IX Header "APPENDIX" The rest of the documentation details each of the object methods. Internal methods are usually preceded with a _ .SS "new" .IX Subsection "new" .Vb 5 \& Title : new \& Usage : Bio::DasI\->new(@args) \& Function: Create new Bio::DasI object \& Returns : a Bio::DasI object \& Args : see below .Ve .PP The \fBnew()\fR method creates a new object. The argument list is either a single argument consisting of a connection string, or the following list of \-name=>value arguments: .PP .Vb 2 \& Argument Description \& \-\-\-\-\-\-\-\- \-\-\-\-\-\-\-\-\-\-\- \& \& \-dsn Connection string for database \& \-adaptor Name of an adaptor class to use when connecting \& \-aggregator Array ref containing list of aggregators \& "semantic mappers" to apply to database \& \-user Authentication username \& \-pass Authentication password .Ve .PP Implementors of DasI may add other arguments. .SS "types" .IX Subsection "types" .Vb 5 \& Title : types \& Usage : $db\->types(@args) \& Function: return list of feature types in database \& Returns : a list of Bio::Das::FeatureTypeI objects \& Args : see below .Ve .PP This routine returns a list of feature types known to the database. It is also possible to find out how many times each feature occurs. .PP Arguments are \-option=>value pairs as follows: .PP .Vb 1 \& \-enumerate if true, count the features .Ve .PP The returned value will be a list of Bio::Das::FeatureTypeI objects (see Bio::Das::FeatureTypeI. .PP If \-enumerate is true, then the function returns a hash (not a hash reference) in which the keys are the stringified versions of Bio::Das::FeatureTypeI and the values are the number of times each feature appears in the database. .SS "parse_types" .IX Subsection "parse_types" .Vb 6 \& Title : parse_types \& Usage : $db\->parse_types(@args) \& Function: parses list of types \& Returns : an array ref containing [\*(Aqmethod\*(Aq,\*(Aqsource\*(Aq] pairs \& Args : a list of types in \*(Aqmethod:source\*(Aq form \& Status : internal .Ve .PP This method takes an array of type names in the format \*(L"method:source\*(R" and returns an array reference of ['method','source'] pairs. It will also accept a single argument consisting of an array reference with the list of type names. .SS "segment" .IX Subsection "segment" .Vb 5 \& Title : segment \& Usage : $db\->segment(@args); \& Function: create a segment object \& Returns : segment object(s) \& Args : see below .Ve .PP This method generates a Bio::Das::SegmentI object (see Bio::Das::SegmentI). The segment can be used to find overlapping features and the raw sequence. .PP When making the \fBsegment()\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 region spanned by the landmark is used to generate the segment. .PP Arguments are \-option=>value pairs as follows: .PP .Vb 1 \& \-name ID of the landmark sequence. \& \& \-class A namespace qualifier. It is not necessary for the \& database to honor namespace qualifiers, but if it \& does, this is where the qualifier is indicated. \& \& \-version Version number of the landmark. It is not necessary for \& the database to honor versions, but if it does, this is \& where the version is indicated. \& \& \-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 End of the segment relative to the landmark. If not specified, \& defaults to the end of the landmark. .Ve .PP The return value is a list of Bio::Das::SegmentI objects. If the method is called in a scalar context and there are no more than one segments that satisfy the request, then it is allowed to return the segment. Otherwise, the method must throw a \*(L"multiple segment exception\*(R". .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::SeqFeatureI 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 type .PP Arguments are \-option=>value pairs as follows: .PP .Vb 3 \& \-types List of feature types to return. Argument is an array \& of Bio::Das::FeatureTypeI objects or a set of strings \& that can be converted into FeatureTypeI objects. \& \& \-callback A callback to invoke on each feature. The subroutine \& will be passed each Bio::SeqFeatureI object in turn. \& \& \-attributes A hash reference containing attributes to match. .Ve .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 exact string matching, and multiple attributes are ANDed together. See Bio::DB::ConstraintsI for a more sophisticated take on this. .PP If one provides a callback, it will be invoked on each feature in turn. If the callback returns a false value, iteration will be interrupted. When a callback is provided, the method returns undef. .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=>$class,\-name=>$name) \& Function: fetch features by their name \& Returns : a list of Bio::SeqFeatureI objects \& Args : the class and name of the desired feature \& Status : public .Ve .PP This method can be used to fetch named feature(s) from the database. The \-class and \-name arguments have the same meaning as in \fBsegment()\fR, and the method also accepts the following short-cut forms: .PP .Vb 5 \& 1) one argument: the argument is treated as the feature name \& 2) two arguments: the arguments are treated as the class and name \& (note: this uses _rearrange() so the first argument must not \& begin with a hyphen or it will be interpreted as a named \& argument). .Ve .PP This method may return zero, one, or several Bio::SeqFeatureI objects. The implementor may allow the name to contain wildcards, in which case standard C\-shell glob semantics are expected. .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::SeqFeatureI 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. The arguments are the same as \&\fBget_feature_by_name()\fR. If this is not implemented, the interface defaults to using \fBget_feature_by_name()\fR. .SS "get_feature_by_id" .IX Subsection "get_feature_by_id" .Vb 6 \& Title : get_feature_by_id \& Usage : $db\->get_feature_by_target($id) \& Function: fetch a feature by its ID \& Returns : a Bio::SeqFeatureI objects \& Args : the ID of the feature \& Status : public .Ve .PP If the database provides unique feature IDs, this can be used to retrieve a single feature from the database. If not overridden, this interface calls \fBget_feature_by_name()\fR and returns the first element. .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 features by combinations of attribute values \& Returns : a list of Bio::SeqFeatureI 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 ANDed together. If an attribute value is an array reference, the list of values in the array is treated as an alternative set of values to be ORed together. .SS "search_notes" .IX Subsection "search_notes" .Vb 6 \& Title : search_notes \& Usage : $db\->search_notes($search_term,$max_results) \& Function: full\-text search on features, ENSEMBL\-style \& Returns : an array of [$name,$description,$score] \& Args : see below \& Status : public .Ve .PP This routine performs a full-text search on feature attributes (which attributes depend on implementation) and returns a list of [$name,$description,$score], where \f(CW$name\fR is the feature \s-1ID,\s0 \&\f(CW$description\fR is a human-readable description such as a locus line, and \&\f(CW$score\fR is the match strength. .PP Since this is a decidedly non-standard thing to do (but the generic genome browser uses it), the default method returns an empty list. You do not have to implement it. .SS "get_seq_stream" .IX Subsection "get_seq_stream" .Vb 6 \& Title : get_seq_stream \& Usage : $seqio = $db\->get_seq_stream(@args) \& Function: Performs a query and returns an iterator over it \& Returns : a Bio::SeqIO stream capable of returning Bio::SeqFeatureI objects \& Args : As in features() \& Status : public .Ve .PP This routine takes the same arguments as \fBfeatures()\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 In the interface this method is aliased to \fBget_feature_stream()\fR, as the name is more descriptive. .SS "refclass" .IX Subsection "refclass" .Vb 6 \& Title : refclass \& Usage : $class = $db\->refclass \& Function: returns the default class to use for segment() calls \& Returns : a string \& Args : none \& Status : public .Ve .PP For data sources which use namespaces to distinguish reference sequence accessions, this returns the default namespace (or \*(L"class\*(R") to use. This interface defines a default of \*(L"Accession\*(R".