Provided by: libbio-graphics-perl_2.40-2_all bug

NAME

       Bio::Graphics::FeatureFile -- A set of Bio::Graphics features, stored in a file

SYNOPSIS

        use Bio::Graphics::FeatureFile;
        my $data  = Bio::Graphics::FeatureFile->new(-file => 'features.txt');

        # 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 => 'fgcolor');

        # or create the FeatureFile by hand

        # add a type
        $data->add_type(EST => {fgcolor=>'blue',height=>12});

        # add a feature
        my $feature = Bio::Graphics::Feature->new(
                                                    # params
                                                 ); # or some other SeqI
        $data->add_feature($feature=>'EST');

DESCRIPTION

       The Bio::Graphics::FeatureFile module reads and parses files that describe sequence
       features and their renderings.  It accepts both GFF 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.

       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.

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.

   Formatting Entries
       Formatting entries are in the form:

        [Stanza Name]
        option1 = value1
        option2 = value2
        option3 = value3

        [Stanza Name 2]
        option1 = value1
        option2 = value2
        ...

       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 "=" sign and optional
       whitespace. Values can be continued across multiple lines by indenting the continuation
       lines by one or more spaces, as in:

        [Named Genes]
        feature = gene
        glyph   = transcript2
        description = These are genes that have been named
          by the international commission on gene naming
          (The Hague).

       Typically configuration stanzas will consist of several Bio::Graphics formatting options.
       A -option=>$value pair passed to Bio::Graphics::Panel->add_track() becomes a
       "option=value" pair in the feature file.

   Feature Entries
       Feature entries can take several forms.  At their simplest, they look like this:

        Gene   B0511.1 Chr1:516..11208

       This means that a feature of type "Gene" and name "B0511.1" 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:

        Gene "My Favorite Gene" Chr1:516..11208

   Specifying Positions and Ranges
       A feature position is specified using a sequence ID (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: "Chr1:516..11208", "ctgA:1-5000". Negative coordinates are allowed, as in
       "Chr1:-187..1000".

       A discontinuous range ("split location") uses commas to separate the ranges.  For example:

        Gene B0511.1  Chr1:516..619,3185..3294,10946..11208

       In the case of a split location, the sequence id only has to appear in front of the first
       range.

       Alternatively, a split location can be indicated by repeating the features type and name
       on multiple adjacent lines:

        Gene   B0511.1 Chr1:516..619
        Gene   B0511.1 Chr1:3185..3294
        Gene   B0511.1 Chr1:10946..11208

       If all the locations are on the same reference sequence, you can specify a default
       chromosome using a "reference=<seqid>":

        reference=Chr1
        Gene   B0511.1 516..619
        Gene   B0511.1 3185..3294
        Gene   B0511.1 10946..11208

       The default seqid is in effect until the next "reference" line appears.

   Feature Tags
       Tags can be added to features by adding a fourth column consisting of "tag=value" pairs:

        Gene  B0511.1  Chr1:516..619,3185..3294 Note="Putative primase"

       Tags and their values take any form you want, and multiple tags can be separated by
       semicolons. You can also repeat tags multiple times:

        Gene  B0511.1  Chr1:516..619,3185..3294 GO_Term=GO:100;GO_Term=GO:2087

       Several tags have special meanings:

        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.

       For example, in the common case of an mRNA, you can use the "Type" tag to distinguish the
       parts of the mRNA into UTR and CDS:

        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

       The top level feature's primary tag will be "mRNA", and its subparts will have types UTR
       and CDS 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 "Putative primase" will be
       applied to the mRNA at the top level of the feature:

        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

   Feature Groups
       Features can be grouped so that they are rendered by the "group" 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:

        EST    yk53c10
               yk53c10.3       15000-15500,15700-15800
               yk53c10.5       18892-19154

       This example is declaring that the ESTs named yk53c10.3 and yk53c10.5 belong to the same
       group named yk53c10.

   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 HTML fragment or an HTML color, e.g.:

        # this is ignored
        [Example]
        glyph   = generic   # this comment is ignored
        bgcolor = #FF0000
        link    = http://www.google.com/search?q=$name#results

       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.

   The #include and #exec Directives
       The special comment "#include 'filename'" 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.

       The following are examples of valid #include directives:

        #include "/usr/local/share/my_directives.txt"
        #include 'my_directives.txt'
        #include chromosome3_features.gff3
        #include gff.d/*.conf

       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.

       Include file processing is not very smart and will not catch all circular #include
       references. You have been warned!

       The special comment "#exec 'command'" 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.

   METHODS
       $version = Bio::Graphics::FeatureFile->version
           Return the version number -- needed for API checking by GBrowse

       $features = Bio::Graphics::FeatureFile->new(@args)
           Create a new Bio::Graphics::FeatureFile using @args to initialize the object.
           Arguments are -name=>value pairs:

             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 \&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<Safe::World>
                              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<Safe::World>
                              module.

           The -file and -text arguments are mutually exclusive, and -file will supersede the
           other if both are present.

           -map_coords points to a coderef with the following signature:

             ($newref,[$start1,$end1],[$start2,$end2]....)
                       = coderef($ref,[$start1,$end1],[$start2,$end2]...)

           See the Bio::Graphics::Browser (part of the generic genome browser package) for an
           illustration of how to use this to do wonderful stuff.

           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.

           If the file is trusted, and there is an option named "init_code" in the [GENERAL]
           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.

       $features = Bio::Graphics::FeatureFile->new_from_cache(@args)
           Like new() but caches the parsed file in /tmp/bio_graphics_ff_cache_* (where * is the
           UID of the current user). This can speed up parsing tremendously for files that have
           many includes.

           Note that the presence of an #exec statement always invalidates the cache and causes a
           full parse.

       $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.

       ($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.

           All arguments are optional.

           $panel is a Bio::Graphics::Panel that has previously been created and configured.

           $position_to_insert indicates the position at which to start inserting new tracks. The
           last current track on the panel is assumed.

           $options 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.

           $max_bump and $max_label indicate the maximum number of features before bumping and
           labeling are turned off.

           $selector 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.

           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.

           Instead of a Bio::Graphics::Panel object, you can provide a hash reference containing
           the arguments that you would pass to Bio::Graphics::Panel->new(). For example, to
           render an SVG image, you could do this:

             my ($tracks_rendered,$panel) = $data->render({-image_class=>'GD::SVG'});
             print $panel->svg;

       $error = $features->error([$error])
           Get/set the current error message.

       $smart_features = $features->smart_features([$flag]
           Get/set the "smart_features" flag.  If this is set, then any features added to the
           featurefile object will have their configurator() method called using the featurefile
           object as the argument.

       $flat = $features->allow_whitespace([$new_flag])
           If true, then GFF3 and GFF2 parsing is relaxed to allow whitespace to delimit the
           columns. Default is false.

       $features->add_feature($feature [=>$type])
           Add a new Bio::FeatureI object to the set.  If $type is specified, the object's
           primary_tag() will be set to that type. Otherwise, the method will use the feature's
           existing primary_tag() to index and store the feature.

       $features->add_type($type=>$hashref)
           Add a new feature type to the set.  The type is a string, such as "EST".  The hashref
           is a set of key=>value pairs indicating options to set on the type.  Example:

             $features->add_type(EST => { glyph => 'generic', fgcolor => 'blue'})

           When a feature of type "EST" is rendered, it will use the generic glyph and have a
           foreground color of blue.

       $features->set($type,$tag,$value)
           Change an individual option for a particular type.  For example, this will change the
           foreground color of EST features to my favorite color:

             $features->set('EST',fgcolor=>'chartreuse')

       $value = $features->setting($stanza => $option)
           In the two-element form, the setting() method returns the value of an option in the
           configuration stanza indicated by $stanza.  For example:

             $value = $features->setting(general => 'height')

           will return the value of the "height" option in the [general] stanza.

           Call with one element to retrieve all the option names in a stanza:

             @options = $features->setting('general');

           Call with no elements to retrieve all stanza names:

             @stanzas = $features->setting;

   fallback_setting()
         $value = $browser->setting(gene => 'fgcolor');

       Tries to find the setting for designated label (e.g. "gene") first. If this fails, looks
       in [TRACK DEFAULTS]. If this fails, looks in [GENERAL].

       $value = $features->code_setting($stanza=>$option);
           This works like setting() except that it is also able to evaluate code references.
           These are options whose values begin with the characters "sub {".  In this case the
           value will be passed to an eval() and the resulting codereference returned.  Use this
           with care!

       $value = $features->safe_setting($stanza=>$option);
           This works like code_setting() except that it evaluates anonymous code references in a
           "Safe::World" compartment. This depends on the Safe::World module being installed and
           the -safe_world option being set to true during object construction.

       $flag = $features->safe([$flag]);
           This gets or sets and "safe" flag.  If the safe flag is set, then calls to setting()
           will invoke code_setting(), allowing values that begin with the string "sub {" to be
           interpreted as anonymous subroutines.  This is a potential security risk when used
           with untrusted files of features, so use it with care.

       $flag = $features->safe_world([$flag]);
           This gets or sets and "safe_world" flag.  If the safe_world flag is set, then values
           that begin with the string "sub {" will be evaluated in a "safe" compartment that
           gives minimal access to the system. This is not a panacea for security risks, so use
           with care.

       $features->set_callback_source($type,$tag,$value)
       $features->get_callback_source($type,$tag)
           These routines are used internally to get and set the source of a sub {} callback.

       @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->add_track() method.

       $glyph = $features->glyph($type);
           Return the name of the glyph corresponding to the given type (same as
           $features->setting($type=>'glyph')).

       @types = $features->configured_types()
           Return a list of all the feature types currently known to the feature file set.
           Roughly equivalent to:

             @types = grep {$_ ne 'general'} $features->setting;

       @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.

       $features = $features->features($type)
           Return a list of all the feature types of type "$type".  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 add_feature().

           Two APIs:

             1) original API:

                 # Reference to an array of all features of type "$type"
                 $features = $features-E<gt>features($type)

                 # Reference to an array of all features of all types
                 $features = $features-E<gt>features()

                 # A list when called in a list context
                 @features = $features-E<gt>features()

              2) Bio::Das::SegmentI API:

                  @features = $features-E<gt>features(-type=>['list','of','types']);

                  # variants
                  $features = $features-E<gt>features(-type=>['list','of','types']);
                  $features = $features-E<gt>features(-type=>'a type');
                  $iterator = $features-E<gt>features(-type=>'a type',-iterator=>1);

                  $iterator = $features-E<gt>features(-type=>'a type',-seq_id=>$id,-start=>$start,-end=>$end);

       @features = $features->features($type)
           Return a list of all the feature types of type "$type".  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 add_feature().

   get_seq_stream
        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

       This is the same as feature_stream(), and is provided for Bioperl compatibility.  Use like
       this:

        $stream = $s->get_seq_stream('exon');
        while (my $exon = $stream->next_seq) {
           print $exon->start,"\n";
        }

   get_feature_by_name
        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

       This method can be used to fetch a named feature from the file.

       The full syntax is as follows.  Features can be filtered by their reference, start and end
       positions

         @f = $db->get_feature_by_name(-name  => $name,
                                       -ref   => $sequence_name,
                                       -start => $start,
                                       -end   => $end);

       This method may return zero, one, or several Bio::Graphics::Feature objects.

   search_notes
        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

       Each row of the returned array is a arrayref containing the following fields:

         column 1     Display name of the feature
         column 2     The text of the note
         column 3     A relevance score.

   get_feature_stream(), top_SeqFeatures(), all_SeqFeatures()
       Provided for compatibility with older BioPerl and/or Bio::DB::GFF APIs.

       @refs = $features->refs
           Return the list of reference sequences referred to by this data file.

       $min = $features->min
           Return the minimum coordinate of the leftmost feature in the data set.

       $max = $features->max
           Return the maximum coordinate of the rightmost feature in the data set.

       $mtime = $features->mtime
       $atime = $features->atime
       $ctime = $features->ctime
       $size = $features->size
           Returns stat() 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.

       $label = $features->feature2label($feature)
           Given a feature, determines the configuration stanza that bests describes it.  Uses
           the feature's type() method if it has it (DasI interface) or its primary_tag() method
           otherwise.

       $link = $features->link_pattern($linkrule,$feature,$panel)
           Given a feature, tries to generate a URL to link out from it.  This uses the 'link'
           option, if one is present.  This method is a convenience for the generic genome
           browser.

       $citation = $features->citation($feature)
           Given a feature, tries to generate a citation for it, using the "citation" option if
           one is present.  This method is a convenience for the generic genome browser.

       $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.

Appendix -- Sample Feature File

        # 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

SEE ALSO

       Bio::Graphics::Panel, Bio::Graphics::Glyph, Bio::DB::SeqFeature::Store::FeatureFileLoader,
       Bio::Graphics::Feature, Bio::Graphics::FeatureFile

AUTHOR

       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2001 Cold Spring Harbor Laboratory

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See DISCLAIMER.txt for disclaimers of warranty.