Bio::G...:Wiggle(3pm)

📦

version 2.40 · 2 versions

2.40 · debian bookworm, debian trixie, ubuntu jammy, ubuntu noble (latest)
2.40 · ubuntu resolute, ubuntu stonking

, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble

💖 Bio::Graphics::Wiggle — binary storage for dense genomic features 💖

okay bestie, so this is Bio::Graphics::Wiggle (perl v5.30.0, dated 2019-11-25 — we'll do a lil sign-off about that at the end 🎀). Strap in, this one's a bop.

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

okay so like, the author is being SO honest here and we respect it 😭. This module stores "wiggle"-style quantitative genome data so a genome browser can display it. The data for each chromosome (or contig, or whatever other reference sequence you got) lives in a single file, formatted like this:

  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 rest of the file is just 8-bit unsigned scaled integer values. Which means — and I need you to hear me on this — all quantitative data will be scaled to 8-bit precision! 💀 that's the vibe, no cap.

If you want a convenient way to make Wiggle files out of UCSC-type WIG input and spit out GFF3, go look at Bio::Graphics::Wiggle::Loader 🫶.

👑 METHODS 👑

🎀 Constructor and Accessors 🎀

$wig = Bio::Graphics::Wiggle->new($filename,$writeable,{options}) — opens or creates a wiggle-format data file. Here's the tea on the args:

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

step is literally the space-saving icon it is 💅 — you can use it to make sparse files. Default step is 1, so a data value gets stored at every single base of the sequence. Set step to 10 and each value corresponds to 10 bp, and the file gets 10x smaller. Obsessed.

Check this step 5 data set for example:

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

We stored the values "20" "60" and "80" at positions 1, 6 and 11 respectively. When you retrieve this data it'll act like 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 actual data file though, we store positions 1, 6, and 11 in adjacent bytes. efficiency queen 👑

ngl there's no locking performed by this module, periodt. If you want multi-user write access to the database files, you're gonna have to flock() the files yourself, bestie. 🔒

$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. And listen — changing the min, max and step after you've written data to the file under another parameter set will produce unexpected (and invalid) results, because the existing data does not automatically update itself to stay consistent. it's giving chaos, do not do it 😭

$trim = $wig->trim([$new_trim]); — sets the trimming method, which trims 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) — sets the value at $position to $value. If a step>1 is in force, then $position gets rounded down to the nearest multiple of step.
$wig->set_range($start=>$end, $value) — sets the value of all bases between $start and $end to $value, honoring step.
$sig->set_values($position => \@values) — writes an array of values into the datababase beginning at $position (or the nearest lower multiple of step). If step>1, then values get written at step intervals.

🌈 Retrieving Data 🌈

$value = $wig->value($position) — retrieves the single data item at position $position, or the nearest lower multiple of $step if step>1.
$values = $wig->values($start=>$end) — retrieves the values in the range $start to $end and returns them as an array ref. Heads up: you will always get an array of size ($end-$start+1) even if step>1; the data in between the step intervals gets filled in. 🫶
$values = $wig->values($start=>$end,$samples) — retrieves a sampling of the values between $start and $end. Nothing very sophisticated is happening here, fr fr; 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>.

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.

and that's the whole page, bestie 🦋✨ this manual was Bio::Graphics::Wiggle(3pm) from perl v5.30.0, dated 2019-11-25 — go forth and store your dense genomic features, you absolute main character 👑💖

📦 where this page comes from

debian bookworm: libbio-graphics-perl 2.40-6 · Perl
debian trixie: libbio-graphics-perl 2.40-6 · Perl
ubuntu jammy: libbio-graphics-perl 2.40-6 · Perl
ubuntu noble: libbio-graphics-perl 2.40-6 · Perl
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-10-14: a language model's rewrite of the original, under its terms