.\" 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
.\"
.\" 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::Wiggle 3pm"
.TH Bio::Graphics::Wiggle 3pm "2019-11-25" "perl v5.30.0" "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::Wiggle \-\- Binary storage for dense genomic features
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& # all positions are 1\-based
\&
\& my $wig = Bio::Graphics::Wiggle\->new(\*(Aq./test.wig\*(Aq,
\&                                      $writeable,
\&                                     { seqid => $seqid,
\&                                       start => $start,
\&                                       step  => $step,
\&                                       min   => $min,
\&                                       max   => $max });
\&
\& $wig\->erase;
\&
\& my $seqid = $wig\->seqid(\*(Aqnew_id\*(Aq);
\& 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 => \e@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(\*(Aqmean\*(Aq);                 # when sampling, compute the mean value across sample window
\& my $values = $wig\->values($start,$end,$samples);  # fetch $samples data points from $start to $end
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\s-1IMPORTANT NOTE:\s0 This implementation is still not right. See
http://genomewiki.ucsc.edu/index.php/Wiggle for a more space-efficient
implementation.
.PP
This module stores \*(L"wiggle\*(R" 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:
.PP
.Vb 11
\&  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
.Ve
.PP
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!
.PP
For a convenient method of creating Wiggle files from UCSC-type \s-1WIG\s0
input and creating \s-1GFF3\s0 output, please see
Bio::Graphics::Wiggle::Loader.
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructor and Accessors"
.IX Subsection "Constructor and Accessors"
.ie n .IP "$wig = Bio::Graphics::Wiggle\->new($filename,$writeable,{options})" 4
.el .IP "\f(CW$wig\fR = Bio::Graphics::Wiggle\->new($filename,$writeable,{options})" 4
.IX Item "$wig = Bio::Graphics::Wiggle->new($filename,$writeable,{options})"
Open/create a wiggle-format data file:
.Sp
.Vb 9
\&  $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"
.Ve
.Sp
The \*(L"step\*(R" 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:
.Sp
.Vb 2
\&    1  2  3  4  5  6  7  8  9 10 11 12 13 14
\&   20  .  .  .  . 60  .  .  .  . 80  .  .  .
.Ve
.Sp
We have stored the values \*(L"20\*(R" \*(L"60\*(R" and \*(L"80\*(R" 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.
.Sp
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
\&\fBflock()\fR the files yourself.
.ie n .IP "$seqid = $wig\->seqid(['new_id'])" 4
.el .IP "\f(CW$seqid\fR = \f(CW$wig\fR\->seqid(['new_id'])" 4
.IX Item "$seqid = $wig->seqid(['new_id'])"
.PD 0
.ie n .IP "$max   = $wig\->max([$new_max])" 4
.el .IP "\f(CW$max\fR   = \f(CW$wig\fR\->max([$new_max])" 4
.IX Item "$max = $wig->max([$new_max])"
.ie n .IP "$min   = $wig\->min([$new_min])" 4
.el .IP "\f(CW$min\fR   = \f(CW$wig\fR\->min([$new_min])" 4
.IX Item "$min = $wig->min([$new_min])"
.ie n .IP "$step  = $wig\->step([$new_step])" 4
.el .IP "\f(CW$step\fR  = \f(CW$wig\fR\->step([$new_step])" 4
.IX Item "$step = $wig->step([$new_step])"
.ie n .IP "$span  = $wig\->span([$new_span])" 4
.el .IP "\f(CW$span\fR  = \f(CW$wig\fR\->span([$new_span])" 4
.IX Item "$span = $wig->span([$new_span])"
.ie n .IP "$mean  = $wig\->mean([$new_mean]);" 4
.el .IP "\f(CW$mean\fR  = \f(CW$wig\fR\->mean([$new_mean]);" 4
.IX Item "$mean = $wig->mean([$new_mean]);"
.ie n .IP "$stdev = $wig\->stdev([$new_stdev]);" 4
.el .IP "\f(CW$stdev\fR = \f(CW$wig\fR\->stdev([$new_stdev]);" 4
.IX Item "$stdev = $wig->stdev([$new_stdev]);"
.PD
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.
.ie n .IP "$trim  = $wig\->trim([$new_trim]);" 4
.el .IP "\f(CW$trim\fR  = \f(CW$wig\fR\->trim([$new_trim]);" 4
.IX Item "$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:
.Sp
.Vb 3
\&  none    No trimming
\&  stdev   Trim 1 standard deviation above and below mean
\&  stdevN  Trim N standard deviations above and below the mean
.Ve
.Sp
In \*(L"stdevN\*(R", any can be any positive integer.
.SS "Setting Data"
.IX Subsection "Setting Data"
.ie n .IP "$wig\->set_value($position => $value)" 4
.el .IP "\f(CW$wig\fR\->set_value($position => \f(CW$value\fR)" 4
.IX Item "$wig->set_value($position => $value)"
This method sets the value at \f(CW$position\fR to \f(CW$value\fR. If a step>1 is in
force, then \f(CW$position\fR will be rounded down to the nearest multiple of
step.
.ie n .IP "$wig\->set_range($start=>$end, $value)" 4
.el .IP "\f(CW$wig\fR\->set_range($start=>$end, \f(CW$value\fR)" 4
.IX Item "$wig->set_range($start=>$end, $value)"
This method sets the value of all bases between \f(CW$start\fR and \f(CW$end\fR to
\&\f(CW$value\fR, honoring step.
.ie n .IP "$sig\->set_values($position => \e@values)" 4
.el .IP "\f(CW$sig\fR\->set_values($position => \e@values)" 4
.IX Item "$sig->set_values($position => @values)"
This method writes an array of values into the datababase beginning at
\&\f(CW$position\fR (or the nearest lower multiple of step). If step>1, then
values will be written at step intervals.
.SS "Retrieving Data"
.IX Subsection "Retrieving Data"
.ie n .IP "$value = $wig\->value($position)" 4
.el .IP "\f(CW$value\fR = \f(CW$wig\fR\->value($position)" 4
.IX Item "$value = $wig->value($position)"
Retrieve the single data item at position \f(CW$position\fR, or the nearest
lower multiple of \f(CW$step\fR if step>1.
.ie n .IP "$values = $wig\->values($start=>$end)" 4
.el .IP "\f(CW$values\fR = \f(CW$wig\fR\->values($start=>$end)" 4
.IX Item "$values = $wig->values($start=>$end)"
Retrieve the values in the range \f(CW$start\fR to \f(CW$end\fR 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.
.ie n .IP "$values = $wig\->values($start=>$end,$samples)" 4
.el .IP "\f(CW$values\fR = \f(CW$wig\fR\->values($start=>$end,$samples)" 4
.IX Item "$values = $wig->values($start=>$end,$samples)"
Retrieve a sampling of the values between \f(CW$start\fR and \f(CW$end\fR. Nothing
very sophisticated is done here; the code simply returns the number of
values indicated in \f(CW$samples\fR, smoothed according to the smoothing
method selected (default to \*(L"mean\*(R"), then selected at even intervals
from the range \f(CW$start\fR to \f(CW$end\fR. The return value is an arrayref of
exactly \f(CW$samples\fR values.
.ie n .IP "$string = $wig\->export_to_wif($start,$end)" 4
.el .IP "\f(CW$string\fR = \f(CW$wig\fR\->export_to_wif($start,$end)" 4
.IX Item "$string = $wig->export_to_wif($start,$end)"
.PD 0
.ie n .IP "$string = $wig\->export_to_wif64($start,$end)" 4
.el .IP "\f(CW$string\fR = \f(CW$wig\fR\->export_to_wif64($start,$end)" 4
.IX Item "$string = $wig->export_to_wif64($start,$end)"
.PD
Export the region from start to end in the \*(L"wif\*(R" 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 \s-1GFF3\s0
and \s-1XML.\s0
.ie n .IP "$wig\->import_from_wif($string)" 4
.el .IP "\f(CW$wig\fR\->import_from_wif($string)" 4
.IX Item "$wig->import_from_wif($string)"
.PD 0
.ie n .IP "$wig\->import_from_wif64($string)" 4
.el .IP "\f(CW$wig\fR\->import_from_wif64($string)" 4
.IX Item "$wig->import_from_wif64($string)"
.PD
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 \s-1GFF3\s0 and \s-1XML.\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Bio::Graphics::Wiggle::Loader,
Bio::Graphics::Panel,
Bio::Graphics::Glyph,
Bio::Graphics::Feature,
Bio::Graphics::FeatureFile
.SH "AUTHOR"
.IX Header "AUTHOR"
Lincoln Stein <lstein@cshl.org>.
.PP
Copyright (c) 2007 Cold Spring Harbor Laboratory
.PP
This package and its accompanying libraries is free software; you can
redistribute it and/or modify it under the terms of the \s-1GPL\s0 (either
version 1, or at your option, any later version) or the Artistic
License 2.0.  Refer to \s-1LICENSE\s0 for the full license text. In addition,
please see \s-1DISCLAIMER\s0.txt for disclaimers of warranty.