Provided by: libbio-graphics-perl_2.37-1_all bug

NAME

       Bio::Graphics::Wiggle -- Binary storage for dense genomic features

SYNOPSIS

        # all positions are 1-based

        my $wig = Bio::Graphics::Wiggle->new('./test.wig',
                                             $writeable,
                                            { seqid => $seqid,
                                              start => $start,
                                              step  => $step,
                                              min   => $min,
                                              max   => $max });

        $wig->erase;

        my $seqid = $wig->seqid('new_id');
        my $max   = $wig->max($new_max);
        my $min   = $wig->min($new_min);
        my $step  = $wig->step($new_step);   # data stored at modulus step == 0; all else is blank

        $wig->set_value($position  => $value);   # store $value at position
        $wig->set_values($position => \@values); # store array of values at position
        $wig->set_range($start=>$end,$value);    # store the same $value from $start to $end

        my $value  = $wig->value($position);     # fetch value from position
        my $values = $wig->values($start,$end);  # fetch range of data from $start to $end

        $wig->window(100);                       # sample window size
        $wig->smoothing('mean');                 # when sampling, compute the mean value across sample window
        my $values = $wig->values($start,$end,$samples);  # fetch $samples data points from $start to $end

DESCRIPTION

       IMPORTANT NOTE: This implementation is still not right. See
       http://genomewiki.ucsc.edu/index.php/Wiggle for a more space-efficient implementation.

       This module stores "wiggle" style quantitative genome data for display in a genome browser
       application. The data for each chromosome (or contig, or other reference sequence) is
       stored in a single file in the following format:

         256 byte header
             50 bytes seqid, zero-terminated C string
             4  byte long integer, value of "step" (explained later)
             4  byte perl native float, the "min" value
             4  byte perl native float, the "max" value
             4  byte long integer, value of "span"
             4  byte perl native float, the mean
             4  byte perl native float, the standard deviation
             2  byte unsigned short, the version number (currently version 0)
             4  byte long integer, sequence start position (in 0-based coordinates)
             null padding to 256 bytes for future use

       The remainder of the file consists of 8-bit unsigned scaled integer values. This means
       that all quantitative data will be scaled to 8-bit precision!

       For a convenient method of creating Wiggle files from UCSC-type WIG input and creating
       GFF3 output, please see Bio::Graphics::Wiggle::Loader.

METHODS

   Constructor and Accessors
       $wig = Bio::Graphics::Wiggle->new($filename,$writeable,{options})
           Open/create a wiggle-format data file:

             $filename  -- path to the file to open/create
             $writeable -- boolean value indicating whether file is
                           writeable. Missing files will only be created
                           if $writeable set to a true value. If path is
                           empty (undef or empty string) and writeable is true,
                           new() will create a temporary file that will be
                           deleted when the object goes out of scope.
             {options}  -- hash ref of the following named options, only valid
                           when creating a new wig file with $writeable true.

                   option name    description                  default
                   -----------    -----                        -------
                     seqid        name/id of sequence          empty name
                     min          minimum value of data points 0
                     max          maximum value of data points 255
                     step         interval between data points 1
                     span         width of data points         value of "step"

           The "step" can be used to create sparse files to save space. By default, step is set
           to 1, in which case a data value will be stored at each base of the sequence. By
           setting step to 10, then each value is taken to correspond to 10 bp, and the file will
           be 10x smaller.  For example, consider this step 5 data set:

               1  2  3  4  5  6  7  8  9 10 11 12 13 14
              20  .  .  .  . 60  .  .  .  . 80  .  .  .

           We have stored the values "20" "60" and "80" at positions 1, 6 and 11, respectively.
           When retrieving this data, it will appear as if positions 1 through 5 have a value of
           20, positions 6-10 have a value of 60, and positions 11-14 have a value of 80. In the
           data file, we store, positions 1,6,and 11 in adjacent bytes.

           Note that no locking is performed by this module. If you wish to allow multi-user
           write access to the databases files, you will need to flock() the files yourself.

       $seqid = $wig->seqid(['new_id'])
       $max   = $wig->max([$new_max])
       $min   = $wig->min([$new_min])
       $step  = $wig->step([$new_step])
       $span  = $wig->span([$new_span])
       $mean  = $wig->mean([$new_mean]);
       $stdev = $wig->stdev([$new_stdev]);
           These accessors get or set the corresponding values. Setting is only allowed if the
           file was opened for writing. Note that changing the min, max and step after writing
           data to the file under another parameter set will produce unexpected (and invalid)
           results, as the existing data is not automatically updated to be consistent.

       $trim  = $wig->trim([$new_trim]);
           The trim method sets the trimming method, which can be used to trim out extreme
           values. Three methods are currently supported:

             none    No trimming
             stdev   Trim 1 standard deviation above and below mean
             stdevN  Trim N standard deviations above and below the mean

           In "stdevN", any can be any positive integer.

   Setting Data
       $wig->set_value($position => $value)
           This method sets the value at $position to $value. If a step>1 is in force, then
           $position will be rounded down to the nearest multiple of step.

       $wig->set_range($start=>$end, $value)
           This method sets the value of all bases between $start and $end to $value, honoring
           step.

       $sig->set_values($position => \@values)
           This method writes an array of values into the datababase beginning at $position (or
           the nearest lower multiple of step). If step>1, then values will be written at step
           intervals.

   Retrieving Data
       $value = $wig->value($position)
           Retrieve the single data item at position $position, or the nearest lower multiple of
           $step if step>1.

       $values = $wig->values($start=>$end)
           Retrieve the values in the range $start to $end and return them as an array ref. Note
           that you will always get an array of size ($end-$start+1) even if step>1; the data in
           between the step intervals will be filled in.

       $values = $wig->values($start=>$end,$samples)
           Retrieve a sampling of the values between $start and $end. Nothing very sophisticated
           is done here; the code simply returns the number of values indicated in $samples,
           smoothed according to the smoothing method selected (default to "mean"), then selected
           at even intervals from the range $start to $end. The return value is an arrayref of
           exactly $samples values.

       $string = $wig->export_to_wif($start,$end)
       $string = $wig->export_to_wif64($start,$end)
           Export the region from start to end in the "wif" format. This data can later be
           imported into another Bio::Graphics::Wiggle object. The first version returns a binary
           string. The second version returns a base64 encoded version that is safe for ascii-
           oriented formata such as GFF3 and XML.

       $wig->import_from_wif($string)
       $wig->import_from_wif64($string)
           Import a wif format data string into the Bio::Graphics::Wiggle object. The first
           version expects a binary string. The second version expects a base64 encoded version
           that is safe for ascii-oriented formata such as GFF3 and XML.

SEE ALSO

       Bio::Graphics::Wiggle::Loader, Bio::Graphics::Panel, Bio::Graphics::Glyph,
       Bio::Graphics::Feature, Bio::Graphics::FeatureFile

AUTHOR

       Lincoln Stein <lstein@cshl.org>.

       Copyright (c) 2007 Cold Spring Harbor Laboratory

       This package and its accompanying libraries is free software; you can redistribute it
       and/or modify it under the terms of the GPL (either version 1, or at your option, any
       later version) or the Artistic License 2.0.  Refer to LICENSE for the full license text.
       In addition, please see DISCLAIMER.txt for disclaimers of warranty.