.\" 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::Graphics::FeatureFile 3pm" .TH Bio::Graphics::FeatureFile 3pm "2018-09-21" "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::Graphics::FeatureFile \-\- A set of Bio::Graphics features, stored in a file .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 2 \& use Bio::Graphics::FeatureFile; \& my $data = Bio::Graphics::FeatureFile\->new(\-file => \*(Aqfeatures.txt\*(Aq); \& \& \& # create a new panel and render contents of the file onto it \& my $panel = $data\->new_panel; \& my $tracks_rendered = $data\->render($panel); \& \& # or do it all in one step \& my ($tracks_rendered,$panel) = $data\->render; \& \& # for more control, render tracks individually \& my @feature_types = $data\->types; \& for my $type (@feature_types) { \& my $features = $data\->features($type); \& my %options = $data\->style($type); \& $panel\->add_track($features,%options); # assuming we have a Bio::Graphics::Panel \& } \& \& # get individual settings \& my $est_fg_color = $data\->setting(EST => \*(Aqfgcolor\*(Aq); \& \& # or create the FeatureFile by hand \& \& # add a type \& $data\->add_type(EST => {fgcolor=>\*(Aqblue\*(Aq,height=>12}); \& \& # add a feature \& my $feature = Bio::Graphics::Feature\->new( \& # params \& ); # or some other SeqI \& $data\->add_feature($feature=>\*(AqEST\*(Aq); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" The Bio::Graphics::FeatureFile module reads and parses files that describe sequence features and their renderings. It accepts both \s-1GFF\s0 format and a more human-friendly file format described below. Once a FeatureFile object has been initialized, you can interrogate it for its consistuent features and their settings, or render the entire file onto a Bio::Graphics::Panel. .PP This module is a precursor of Jason Stajich's Bio::Annotation::Collection class, and fulfills a similar function of storing a collection of sequence features. However, it also stores rendering information about the features, and does not currently follow the CollectionI interface. .SH "The File Format" .IX Header "The File Format" There are two types of entry in the file format: feature entries, and formatting entries. They can occur in any order. See the Appendix for a full example. .SS "Formatting Entries" .IX Subsection "Formatting Entries" Formatting entries are in the form: .PP .Vb 4 \& [Stanza Name] \& option1 = value1 \& option2 = value2 \& option3 = value3 \& \& [Stanza Name 2] \& option1 = value1 \& option2 = value2 \& ... .Ve .PP There can be zero or more stanzas, each with a unique name. The names can contain any character except the [] characters. Each stanza consists of one or more option = value pairs, where the option and the value are separated by an \*(L"=\*(R" sign and optional whitespace. Values can be continued across multiple lines by indenting the continuation lines by one or more spaces, as in: .PP .Vb 6 \& [Named Genes] \& feature = gene \& glyph = transcript2 \& description = These are genes that have been named \& by the international commission on gene naming \& (The Hague). .Ve .PP Typically configuration stanzas will consist of several Bio::Graphics formatting options. A \-option=>$value pair passed to Bio::Graphics::Panel\->\fIadd_track()\fR becomes a \*(L"option=value\*(R" pair in the feature file. .SS "Feature Entries" .IX Subsection "Feature Entries" Feature entries can take several forms. At their simplest, they look like this: .PP .Vb 1 \& Gene B0511.1 Chr1:516..11208 .Ve .PP This means that a feature of type \*(L"Gene\*(R" and name \*(L"B0511.1\*(R" occupies the range between bases 516 and 11208 on a sequence entry named Chr1. Columns are separated using whitespace (tabs or spaces). Embedded whitespace can be escaped using quote marks or backslashes: .PP .Vb 1 \& Gene "My Favorite Gene" Chr1:516..11208 .Ve .SS "Specifying Positions and Ranges" .IX Subsection "Specifying Positions and Ranges" A feature position is specified using a sequence \s-1ID\s0 (a genbank accession number, a chromosome name, a contig, or any other meaningful reference system, followed by a colon and a position range. Ranges are two integers separated by double dots or the hyphen. Examples: \&\*(L"Chr1:516..11208\*(R", \*(L"ctgA:1\-5000\*(R". Negative coordinates are allowed, as in \*(L"Chr1:\-187..1000\*(R". .PP A discontinuous range (\*(L"split location\*(R") uses commas to separate the ranges. For example: .PP .Vb 1 \& Gene B0511.1 Chr1:516..619,3185..3294,10946..11208 .Ve .PP In the case of a split location, the sequence id only has to appear in front of the first range. .PP Alternatively, a split location can be indicated by repeating the features type and name on multiple adjacent lines: .PP .Vb 3 \& Gene B0511.1 Chr1:516..619 \& Gene B0511.1 Chr1:3185..3294 \& Gene B0511.1 Chr1:10946..11208 .Ve .PP If all the locations are on the same reference sequence, you can specify a default chromosome using a \*(L"reference=\*(R": .PP .Vb 4 \& reference=Chr1 \& Gene B0511.1 516..619 \& Gene B0511.1 3185..3294 \& Gene B0511.1 10946..11208 .Ve .PP The default seqid is in effect until the next \*(L"reference\*(R" line appears. .SS "Feature Tags" .IX Subsection "Feature Tags" Tags can be added to features by adding a fourth column consisting of \&\*(L"tag=value\*(R" pairs: .PP .Vb 1 \& Gene B0511.1 Chr1:516..619,3185..3294 Note="Putative primase" .Ve .PP Tags and their values take any form you want, and multiple tags can be separated by semicolons. You can also repeat tags multiple times: .PP .Vb 1 \& Gene B0511.1 Chr1:516..619,3185..3294 GO_Term=GO:100;GO_Term=GO:2087 .Ve .PP Several tags have special meanings: .PP .Vb 2 \& Tag Meaning \& \-\-\- \-\-\-\-\-\-\- \& \& Type The primary tag for a subfeature. \& Score The score of a feature or subfeature. \& Phase The phase of a feature or subfeature. \& URL A URL to link to (via the Bio::Graphics library). \& Note A note to attach to the feature for display by the Bio::Graphics library. .Ve .PP For example, in the common case of an mRNA, you can use the \*(L"Type\*(R" tag to distinguish the parts of the mRNA into \s-1UTR\s0 and \s-1CDS:\s0 .PP .Vb 3 \& mRNA B0511.1 Chr1:1..100 Type=UTR \& mRNA B0511.1 Chr1:101..200,300..400,500..800 Type=CDS \& mRNA B0511.1 Chr1:801..1000 Type=UTR .Ve .PP The top level feature's primary tag will be \*(L"mRNA\*(R", and its subparts will have types \s-1UTR\s0 and \s-1CDS\s0 as indicated. Additional tags that are placed in the first line of the feature will be applied to the top level. In this example, the note \*(L"Putative primase\*(R" will be applied to the mRNA at the top level of the feature: .PP .Vb 3 \& mRNA B0511.1 Chr1:1..100 Type=UTR;Note="Putative primase" \& mRNA B0511.1 Chr1:101..200,300..400,500..800 Type=CDS \& mRNA B0511.1 Chr1:801..1000 Type=UTR .Ve .SS "Feature Groups" .IX Subsection "Feature Groups" Features can be grouped so that they are rendered by the \*(L"group\*(R" glyph. To start a group, create a two-column feature entry showing the group type and a name for the group. Follow this with a list of feature entries with a blank type. For example: .PP .Vb 3 \& EST yk53c10 \& yk53c10.3 15000\-15500,15700\-15800 \& yk53c10.5 18892\-19154 .Ve .PP This example is declaring that the ESTs named yk53c10.3 and yk53c10.5 belong to the same group named yk53c10. .SS "Comments" .IX Subsection "Comments" Lines that begin with the # sign are treated as comments and ignored. When a # sign appears within a line, everything to the right of the symbol is also ignored, unless it looks like an \s-1HTML\s0 fragment or an \s-1HTML\s0 color, e.g.: .PP .Vb 5 \& # this is ignored \& [Example] \& glyph = generic # this comment is ignored \& bgcolor = #FF0000 \& link = http://www.google.com/search?q=$name#results .Ve .PP Be careful, because the processing of # signs uses a regexp heuristic. To be safe, always put a space after the # sign to make sure it is treated as a comment. .SS "The #include and #exec Directives" .IX Subsection "The #include and #exec Directives" The special comment \*(L"#include 'filename'\*(R" acts like the C preprocessor directive and will insert the comments of a named file into the position at which it occurs. Relative paths will be treated relative to the file in which the #include occurs. Nested #include directives (a #include located in a file that is itself an include file) are #allowed. You may also use one of the shell wildcard characters * and #? to include all matching files in a directory. .PP The following are examples of valid #include directives: .PP .Vb 4 \& #include "/usr/local/share/my_directives.txt" \& #include \*(Aqmy_directives.txt\*(Aq \& #include chromosome3_features.gff3 \& #include gff.d/*.conf .Ve .PP You can enclose the file path in single or double quotes as shown above. If there are no spaces in the filename the quotes are optional. The #include directive is case insensitive, allowing you to use #INCLUDE or #Include if you prefer. .PP Include file processing is not very smart and will not catch all circular #include references. You have been warned! .PP The special comment \*(L"#exec 'command'\*(R" will spawn a shell and incorporate the output of the command into the configuration file. This command will be executed quite frequently, so it is suggested that any time-consuming processing that does not need to be performed on the fly each time should be cached in a local file. .SS "\s-1METHODS\s0" .IX Subsection "METHODS" .ie n .IP "$version = Bio::Graphics::FeatureFile\->version" 4 .el .IP "\f(CW$version\fR = Bio::Graphics::FeatureFile\->version" 4 .IX Item "$version = Bio::Graphics::FeatureFile->version" Return the version number \*(-- needed for \s-1API\s0 checking by GBrowse .ie n .IP "$features = Bio::Graphics::FeatureFile\->new(@args)" 4 .el .IP "\f(CW$features\fR = Bio::Graphics::FeatureFile\->new(@args)" 4 .IX Item "$features = Bio::Graphics::FeatureFile->new(@args)" Create a new Bio::Graphics::FeatureFile using \f(CW@args\fR to initialize the object. Arguments are \-name=>value pairs: .Sp .Vb 2 \& Argument Value \& \-\-\-\-\-\-\-\- \-\-\-\-\- \& \& \-file Read data from a file path or filehandle. Use \& "\-" to read from standard input. \& \& \-text Read data from a text scalar. \& \& \-allow_whitespace If true, relax GFF2 and GFF3 parsing rules to allow \& columns to be delimited by whitespace rather than \& tabs. \& \& \-map_coords Coderef containing a subroutine to use for remapping \& all coordinates. \& \& \-smart_features Flag indicating that the features created by this \& module should be made aware of the FeatureFile \& object by calling their configurator() method. \& \& \-safe Indicates that the contents of this file is trusted. \& Any option value that begins with the string "sub {" \& or \e&subname will be evaluated as a code reference. \& \& \-safe_world If the \-safe option is not set, and \-safe_world \& is set to a true value, then Bio::Graphics::FeatureFile \& will evalute "sub {}" options in a L \& environment with minimum permissions. Subroutines \& will be able to access and interrogate \& Bio::DB::SeqFeature objects and perform basic Perl \& operations, but will have no ability to load or \& access other modules, to access the file system, \& or to make system calls. This feature depends on \& availability of the CPAN\-installable L \& module. .Ve .Sp The \-file and \-text arguments are mutually exclusive, and \-file will supersede the other if both are present. .Sp \&\-map_coords points to a coderef with the following signature: .Sp .Vb 2 \& ($newref,[$start1,$end1],[$start2,$end2]....) \& = coderef($ref,[$start1,$end1],[$start2,$end2]...) .Ve .Sp See the Bio::Graphics::Browser (part of the generic genome browser package) for an illustration of how to use this to do wonderful stuff. .Sp The \-smart_features flag is used by the generic genome browser to provide features with a way to access the link-generation code. See gbrowse for how this works. .Sp If the file is trusted, and there is an option named \*(L"init_code\*(R" in the [\s-1GENERAL\s0] section of the file, it will be evaluated as perl code immediately after parsing. You can use this to declare global variables and subroutines for use in option values. .ie n .IP "$features = Bio::Graphics::FeatureFile\->new_from_cache(@args)" 4 .el .IP "\f(CW$features\fR = Bio::Graphics::FeatureFile\->new_from_cache(@args)" 4 .IX Item "$features = Bio::Graphics::FeatureFile->new_from_cache(@args)" Like \fInew()\fR but caches the parsed file in /tmp/bio_graphics_ff_cache_* (where * is the \s-1UID\s0 of the current user). This can speed up parsing tremendously for files that have many includes. .Sp Note that the presence of an #exec statement always invalidates the cache and causes a full parse. .ie n .IP "$mtime = Bio::Graphics::FeatureFile\->file_mtime($path)" 4 .el .IP "\f(CW$mtime\fR = Bio::Graphics::FeatureFile\->file_mtime($path)" 4 .IX Item "$mtime = Bio::Graphics::FeatureFile->file_mtime($path)" Return the modification time of the indicated feature file without performing a full parse. This takes into account the various #include and #exec directives and returns the maximum mtime of any of the included files. Any #exec directive will return the current time. This is useful for caching the parsed data structure. .ie n .IP "($rendered,$panel,$tracks) = $features\->render([$panel, $position_to_insert, $options, $max_bump, $max_label, $selector])" 4 .el .IP "($rendered,$panel,$tracks) = \f(CW$features\fR\->render([$panel, \f(CW$position_to_insert\fR, \f(CW$options\fR, \f(CW$max_bump\fR, \f(CW$max_label\fR, \f(CW$selector\fR])" 4 .IX Item "($rendered,$panel,$tracks) = $features->render([$panel, $position_to_insert, $options, $max_bump, $max_label, $selector])" Render features in the data set onto the indicated Bio::Graphics::Panel. If no panel is specified, creates one. .Sp All arguments are optional. .Sp \&\f(CW$panel\fR is a Bio::Graphics::Panel that has previously been created and configured. .Sp \&\f(CW$position_to_insert\fR indicates the position at which to start inserting new tracks. The last current track on the panel is assumed. .Sp \&\f(CW$options\fR is a scalar used to control automatic expansion of the tracks. 0=auto, 1=compact, 2=expanded, 3=expand and label, 4=hyperexpand, 5=hyperexpand and label. .Sp \&\f(CW$max_bump\fR and \f(CW$max_label\fR indicate the maximum number of features before bumping and labeling are turned off. .Sp \&\f(CW$selector\fR is a code ref that can be used to filter which features to render. It receives a feature and should return true to include the feature and false to exclude it. .Sp In a scalar context returns the number of tracks rendered. In a list context, returns a three-element list containing the number of features rendered, the created panel, and an array ref of all the track objects created. .Sp Instead of a Bio::Graphics::Panel object, you can provide a hash reference containing the arguments that you would pass to Bio::Graphics::Panel\->\fInew()\fR. For example, to render an \s-1SVG\s0 image, you could do this: .Sp .Vb 2 \& my ($tracks_rendered,$panel) = $data\->render({\-image_class=>\*(AqGD::SVG\*(Aq}); \& print $panel\->svg; .Ve .ie n .IP "$error = $features\->error([$error])" 4 .el .IP "\f(CW$error\fR = \f(CW$features\fR\->error([$error])" 4 .IX Item "$error = $features->error([$error])" Get/set the current error message. .ie n .IP "$smart_features = $features\->smart_features([$flag]" 4 .el .IP "\f(CW$smart_features\fR = \f(CW$features\fR\->smart_features([$flag]" 4 .IX Item "$smart_features = $features->smart_features([$flag]" Get/set the \*(L"smart_features\*(R" flag. If this is set, then any features added to the featurefile object will have their \fIconfigurator()\fR method called using the featurefile object as the argument. .ie n .IP "$flat = $features\->allow_whitespace([$new_flag])" 4 .el .IP "\f(CW$flat\fR = \f(CW$features\fR\->allow_whitespace([$new_flag])" 4 .IX Item "$flat = $features->allow_whitespace([$new_flag])" If true, then \s-1GFF3\s0 and \s-1GFF2\s0 parsing is relaxed to allow whitespace to delimit the columns. Default is false. .ie n .IP "$features\->add_feature($feature [=>$type])" 4 .el .IP "\f(CW$features\fR\->add_feature($feature [=>$type])" 4 .IX Item "$features->add_feature($feature [=>$type])" Add a new Bio::FeatureI object to the set. If \f(CW$type\fR is specified, the object's \fIprimary_tag()\fR will be set to that type. Otherwise, the method will use the feature's existing \fIprimary_tag()\fR to index and store the feature. .ie n .IP "$features\->add_type($type=>$hashref)" 4 .el .IP "\f(CW$features\fR\->add_type($type=>$hashref)" 4 .IX Item "$features->add_type($type=>$hashref)" Add a new feature type to the set. The type is a string, such as \&\*(L"\s-1EST\*(R".\s0 The hashref is a set of key=>value pairs indicating options to set on the type. Example: .Sp .Vb 1 \& $features\->add_type(EST => { glyph => \*(Aqgeneric\*(Aq, fgcolor => \*(Aqblue\*(Aq}) .Ve .Sp When a feature of type \*(L"\s-1EST\*(R"\s0 is rendered, it will use the generic glyph and have a foreground color of blue. .ie n .IP "$features\->set($type,$tag,$value)" 4 .el .IP "\f(CW$features\fR\->set($type,$tag,$value)" 4 .IX Item "$features->set($type,$tag,$value)" Change an individual option for a particular type. For example, this will change the foreground color of \s-1EST\s0 features to my favorite color: .Sp .Vb 1 \& $features\->set(\*(AqEST\*(Aq,fgcolor=>\*(Aqchartreuse\*(Aq) .Ve .ie n .IP "$value = $features\->setting($stanza => $option)" 4 .el .IP "\f(CW$value\fR = \f(CW$features\fR\->setting($stanza => \f(CW$option\fR)" 4 .IX Item "$value = $features->setting($stanza => $option)" In the two-element form, the \fIsetting()\fR method returns the value of an option in the configuration stanza indicated by \f(CW$stanza\fR. For example: .Sp .Vb 1 \& $value = $features\->setting(general => \*(Aqheight\*(Aq) .Ve .Sp will return the value of the \*(L"height\*(R" option in the [general] stanza. .Sp Call with one element to retrieve all the option names in a stanza: .Sp .Vb 1 \& @options = $features\->setting(\*(Aqgeneral\*(Aq); .Ve .Sp Call with no elements to retrieve all stanza names: .Sp .Vb 1 \& @stanzas = $features\->setting; .Ve .SS "\fIfallback_setting()\fP" .IX Subsection "fallback_setting()" .Vb 1 \& $value = $browser\->setting(gene => \*(Aqfgcolor\*(Aq); .Ve .PP Tries to find the setting for designated label (e.g. \*(L"gene\*(R") first. If this fails, looks in [\s-1TRACK DEFAULTS\s0]. If this fails, looks in [\s-1GENERAL\s0]. .ie n .IP "$value = $features\->code_setting($stanza=>$option);" 4 .el .IP "\f(CW$value\fR = \f(CW$features\fR\->code_setting($stanza=>$option);" 4 .IX Item "$value = $features->code_setting($stanza=>$option);" This works like \fIsetting()\fR except that it is also able to evaluate code references. These are options whose values begin with the characters \&\*(L"sub {\*(R". In this case the value will be passed to an \fIeval()\fR and the resulting codereference returned. Use this with care! .ie n .IP "$value = $features\->safe_setting($stanza=>$option);" 4 .el .IP "\f(CW$value\fR = \f(CW$features\fR\->safe_setting($stanza=>$option);" 4 .IX Item "$value = $features->safe_setting($stanza=>$option);" This works like \fIcode_setting()\fR except that it evaluates anonymous code references in a \*(L"Safe::World\*(R" compartment. This depends on the Safe::World module being installed and the \-safe_world option being set to true during object construction. .ie n .IP "$flag = $features\->safe([$flag]);" 4 .el .IP "\f(CW$flag\fR = \f(CW$features\fR\->safe([$flag]);" 4 .IX Item "$flag = $features->safe([$flag]);" This gets or sets and \*(L"safe\*(R" flag. If the safe flag is set, then calls to \fIsetting()\fR will invoke \fIcode_setting()\fR, allowing values that begin with the string \*(L"sub {\*(R" to be interpreted as anonymous subroutines. This is a potential security risk when used with untrusted files of features, so use it with care. .ie n .IP "$flag = $features\->safe_world([$flag]);" 4 .el .IP "\f(CW$flag\fR = \f(CW$features\fR\->safe_world([$flag]);" 4 .IX Item "$flag = $features->safe_world([$flag]);" This gets or sets and \*(L"safe_world\*(R" flag. If the safe_world flag is set, then values that begin with the string \*(L"sub {\*(R" will be evaluated in a \*(L"safe\*(R" compartment that gives minimal access to the system. This is not a panacea for security risks, so use with care. .ie n .IP "$features\->set_callback_source($type,$tag,$value)" 4 .el .IP "\f(CW$features\fR\->set_callback_source($type,$tag,$value)" 4 .IX Item "$features->set_callback_source($type,$tag,$value)" .PD 0 .ie n .IP "$features\->get_callback_source($type,$tag)" 4 .el .IP "\f(CW$features\fR\->get_callback_source($type,$tag)" 4 .IX Item "$features->get_callback_source($type,$tag)" .PD These routines are used internally to get and set the source of a sub {} callback. .ie n .IP "@args = $features\->style($type)" 4 .el .IP "\f(CW@args\fR = \f(CW$features\fR\->style($type)" 4 .IX Item "@args = $features->style($type)" Given a feature type, returns a list of track configuration arguments suitable for suitable for passing to the Bio::Graphics::Panel\->\fIadd_track()\fR method. .ie n .IP "$glyph = $features\->glyph($type);" 4 .el .IP "\f(CW$glyph\fR = \f(CW$features\fR\->glyph($type);" 4 .IX Item "$glyph = $features->glyph($type);" Return the name of the glyph corresponding to the given type (same as \&\f(CW$features\fR\->setting($type=>'glyph')). .ie n .IP "@types = $features\->\fIconfigured_types()\fR" 4 .el .IP "\f(CW@types\fR = \f(CW$features\fR\->\fIconfigured_types()\fR" 4 .IX Item "@types = $features->configured_types()" Return a list of all the feature types currently known to the feature file set. Roughly equivalent to: .Sp .Vb 1 \& @types = grep {$_ ne \*(Aqgeneral\*(Aq} $features\->setting; .Ve .ie n .IP "@types = $features\->\fItypes()\fR" 4 .el .IP "\f(CW@types\fR = \f(CW$features\fR\->\fItypes()\fR" 4 .IX Item "@types = $features->types()" This is similar to the previous method, but will return *all* feature types, including those that are not configured with a stanza. .ie n .IP "$features = $features\->features($type)" 4 .el .IP "\f(CW$features\fR = \f(CW$features\fR\->features($type)" 4 .IX Item "$features = $features->features($type)" Return a list of all the feature types of type \*(L"$type\*(R". If the featurefile object was created by parsing a file or text scalar, then the features will be of type Bio::Graphics::Feature (which follow the Bio::FeatureI interface). Otherwise the list will contain objects of whatever type you added with calls to \fIadd_feature()\fR. .Sp Two APIs: .Sp .Vb 1 \& 1) original API: \& \& # Reference to an array of all features of type "$type" \& $features = $features\-Efeatures($type) \& \& # Reference to an array of all features of all types \& $features = $features\-Efeatures() \& \& # A list when called in a list context \& @features = $features\-Efeatures() \& \& 2) Bio::Das::SegmentI API: \& \& @features = $features\-Efeatures(\-type=>[\*(Aqlist\*(Aq,\*(Aqof\*(Aq,\*(Aqtypes\*(Aq]); \& \& # variants \& $features = $features\-Efeatures(\-type=>[\*(Aqlist\*(Aq,\*(Aqof\*(Aq,\*(Aqtypes\*(Aq]); \& $features = $features\-Efeatures(\-type=>\*(Aqa type\*(Aq); \& $iterator = $features\-Efeatures(\-type=>\*(Aqa type\*(Aq,\-iterator=>1); \& \& $iterator = $features\-Efeatures(\-type=>\*(Aqa type\*(Aq,\-seq_id=>$id,\-start=>$start,\-end=>$end); .Ve .ie n .IP "@features = $features\->features($type)" 4 .el .IP "\f(CW@features\fR = \f(CW$features\fR\->features($type)" 4 .IX Item "@features = $features->features($type)" Return a list of all the feature types of type \*(L"$type\*(R". If the featurefile object was created by parsing a file or text scalar, then the features will be of type Bio::Graphics::Feature (which follow the Bio::FeatureI interface). Otherwise the list will contain objects of whatever type you added with calls to \fIadd_feature()\fR. .SS "get_seq_stream" .IX Subsection "get_seq_stream" .Vb 6 \& Title : get_seq_stream \& Usage : $stream = $s\->get_seq_stream(@args) \& Function: get a stream of features that overlap this segment \& Returns : a Bio::SeqIO::Stream\-compliant stream \& Args : see below \& Status : Public .Ve .PP This is the same as \fIfeature_stream()\fR, and is provided for Bioperl compatibility. Use like this: .PP .Vb 4 \& $stream = $s\->get_seq_stream(\*(Aqexon\*(Aq); \& while (my $exon = $stream\->next_seq) { \& print $exon\->start,"\en"; \& } .Ve .SS "get_feature_by_name" .IX Subsection "get_feature_by_name" .Vb 5 \& Usage : $db\->get_feature_by_name(\-name => $name) \& Function: fetch features by their name \& Returns : a list of Bio::DB::GFF::Feature objects \& Args : the name of the desired feature \& Status : public .Ve .PP This method can be used to fetch a named feature from the file. .PP The full syntax is as follows. Features can be filtered by their reference, start and end positions .PP .Vb 4 \& @f = $db\->get_feature_by_name(\-name => $name, \& \-ref => $sequence_name, \& \-start => $start, \& \-end => $end); .Ve .PP This method may return zero, one, or several Bio::Graphics::Feature objects. .SS "search_notes" .IX Subsection "search_notes" .Vb 6 \& Title : search_notes \& Usage : @search_results = $db\->search_notes("full text search string",$limit) \& Function: Search the notes for a text string \& Returns : array of results \& Args : full text search string, and an optional row limit \& Status : public .Ve .PP Each row of the returned array is a arrayref containing the following fields: .PP .Vb 3 \& column 1 Display name of the feature \& column 2 The text of the note \& column 3 A relevance score. .Ve .SS "\fIget_feature_stream()\fP, \fItop_SeqFeatures()\fP, \fIall_SeqFeatures()\fP" .IX Subsection "get_feature_stream(), top_SeqFeatures(), all_SeqFeatures()" Provided for compatibility with older BioPerl and/or Bio::DB::GFF APIs. .ie n .IP "@refs = $features\->refs" 4 .el .IP "\f(CW@refs\fR = \f(CW$features\fR\->refs" 4 .IX Item "@refs = $features->refs" Return the list of reference sequences referred to by this data file. .ie n .IP "$min = $features\->min" 4 .el .IP "\f(CW$min\fR = \f(CW$features\fR\->min" 4 .IX Item "$min = $features->min" Return the minimum coordinate of the leftmost feature in the data set. .ie n .IP "$max = $features\->max" 4 .el .IP "\f(CW$max\fR = \f(CW$features\fR\->max" 4 .IX Item "$max = $features->max" Return the maximum coordinate of the rightmost feature in the data set. .ie n .IP "$mtime = $features\->mtime" 4 .el .IP "\f(CW$mtime\fR = \f(CW$features\fR\->mtime" 4 .IX Item "$mtime = $features->mtime" .PD 0 .ie n .IP "$atime = $features\->atime" 4 .el .IP "\f(CW$atime\fR = \f(CW$features\fR\->atime" 4 .IX Item "$atime = $features->atime" .ie n .IP "$ctime = $features\->ctime" 4 .el .IP "\f(CW$ctime\fR = \f(CW$features\fR\->ctime" 4 .IX Item "$ctime = $features->ctime" .ie n .IP "$size = $features\->size" 4 .el .IP "\f(CW$size\fR = \f(CW$features\fR\->size" 4 .IX Item "$size = $features->size" .PD Returns \fIstat()\fR information about the data file, for featurefile objects created using the \-file option. Size is in bytes. mtime, atime, and ctime are in seconds since the epoch. .ie n .IP "$label = $features\->feature2label($feature)" 4 .el .IP "\f(CW$label\fR = \f(CW$features\fR\->feature2label($feature)" 4 .IX Item "$label = $features->feature2label($feature)" Given a feature, determines the configuration stanza that bests describes it. Uses the feature's \fItype()\fR method if it has it (DasI interface) or its \fIprimary_tag()\fR method otherwise. .ie n .IP "$link = $features\->link_pattern($linkrule,$feature,$panel)" 4 .el .IP "\f(CW$link\fR = \f(CW$features\fR\->link_pattern($linkrule,$feature,$panel)" 4 .IX Item "$link = $features->link_pattern($linkrule,$feature,$panel)" Given a feature, tries to generate a \s-1URL\s0 to link out from it. This uses the 'link' option, if one is present. This method is a convenience for the generic genome browser. .ie n .IP "$citation = $features\->citation($feature)" 4 .el .IP "\f(CW$citation\fR = \f(CW$features\fR\->citation($feature)" 4 .IX Item "$citation = $features->citation($feature)" Given a feature, tries to generate a citation for it, using the \&\*(L"citation\*(R" option if one is present. This method is a convenience for the generic genome browser. .ie n .IP "$name = $features\->name([$feature])" 4 .el .IP "\f(CW$name\fR = \f(CW$features\fR\->name([$feature])" 4 .IX Item "$name = $features->name([$feature])" Get/set the name of this feature set. This is a convenience method useful for keeping track of multiple feature sets. .SH "Appendix \*(-- Sample Feature File" .IX Header "Appendix Sample Feature File" .Vb 6 \& # file begins \& [general] \& pixels = 1024 \& bases = 1\-20000 \& reference = Contig41 \& height = 12 \& \& [mRNA] \& glyph = gene \& key = Spliced genes \& \& [Cosmid] \& glyph = segments \& fgcolor = blue \& key = C. elegans conserved regions \& \& [EST] \& glyph = segments \& bgcolor= yellow \& connector = dashed \& height = 5; \& \& [FGENESH] \& glyph = transcript2 \& bgcolor = green \& description = 1 \& \& mRNA B0511.1 Chr1:1..100 Type=UTR;Note="putative primase" \& mRNA B0511.1 Chr1:101..200,300..400,500..800 Type=CDS \& mRNA B0511.1 Chr1:801..1000 Type=UTR \& \& reference = Chr3 \& Cosmid B0511 516..619 \& Cosmid B0511 3185..3294 \& Cosmid B0511 10946..11208 \& Cosmid B0511 13126..13511 \& Cosmid B0511 11394..11539 \& EST yk260e10.5 15569..15724 \& EST yk672a12.5 537..618,3187..3294 \& EST yk595e6.5 552..618 \& EST yk595e6.5 3187..3294 \& EST yk846e07.3 11015..11208 \& EST yk53c10 \& yk53c10.3 15000..15500,15700..15800 \& yk53c10.5 18892..19154 \& EST yk53c10.5 16032..16105 \& SwissProt PECANEX 13153\-13656 Note="Swedish fish" \& FGENESH "Predicted gene 1" 1\-205,518\-616,661\-735,3187\-3365,3436\-3846 "Pfam domain" \& # file ends .Ve .SH "SEE ALSO" .IX Header "SEE ALSO" Bio::Graphics::Panel, Bio::Graphics::Glyph, Bio::DB::SeqFeature::Store::FeatureFileLoader, Bio::Graphics::Feature, Bio::Graphics::FeatureFile .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. See \s-1DISCLAIMER\s0.txt for disclaimers of warranty.