NAME

OP::Series

DESCRIPTION

Generate consolidated, interpolated series data from an array of objects.

SYNOPSIS

use OP::Series;

my $series = OP::Series->new();

INSTANCE METHODS

Axis Options

• setXKey($xKey), setYKey($yKey)

  Define which object keys to use for X and Y axis:

  $series->setXKey("timestamp");
  $series->setYKey("value");

X Axis Options

• setXMin($xMin), setXMax($xMax)

  Confine the received data to a range specified by xMin and xMax.

  Set X axis opts (time opts, in this case):

  $series->setXMin(1218508949);
  $series->setXMax(1218508969);

• setXTickSize($size)

  Specify the desired step interval between datapoints on the X axis.

  The unit of measurement would be the same as the value being used for the axis (so, seconds if plotting seconds, widgets if plotting widgets).

  $series->setXTickSize(1); # 1 Second

• setXMajorTickSize($size)

  Apply a "moving average" to the data after expanding base ticks. (Optional/Experimental)

  $series->setXMajorTickSize(60); # 1 Minute

• setXConsolidator($const)

  Specify a function to use for consolidation of overlapping values. Valid arguments are:

  OP::Enum::Consol::Average # Average value
  OP::Enum::Consol::Median  # Median value
  OP::Enum::Consol::Min     # Minimum value
  OP::Enum::Consol::Max     # Maximum value
  OP::Enum::Consol::Sum     # Sum of values
  OP::Enum::Consol::First   # First value seen
  OP::Enum::Consol::Last    # Last value seen
  OP::Enum::Consol::Random  # Random value

  This is an optional argument, and defaults to Average.

  $series->setXConsolidator(
    OP::Enum::Consol::Median
  );

Y Axis Options

• setYInterpolate($const)

  Optional, set interpolation type. Valid args are:

  OP::Enum::Inter::Linear     # Straight Line
  OP::Enum::Inter::Spline     # Cubic Spline
  OP::Enum::Inter::Constant   # Last Known
  OP::Enum::Inter::Undefined  # Unknowns are undef
  OP::Enum::Inter::None       # No Interpolation

  Defaults to Linear.

  $series->setYInterpolate(OP::Enum::Inter::Spline);

• setYRpn($rpnStr)

  Optional, supply an RPN expression

  $series->setYRpn("-1,*"); # Inverted axis

• setYType($const)

  Optional, supply statistic type.

  Derivative is like Counter but permits negative values (rate of change data)

  Valid arguments are:

  OP::Enum::StatType::Gauge
  OP::Enum::StatType::Counter
  OP::Enum::StatType::Derivative

  Defaults to Gauge.

  $series->setYType(OP::Enum::StatType::Counter);

Processing Data

• addObject($object)

  Add an object to the raw data set. The objects don't need to be blessed, they just need to contain similar attributes:

  $series->addObject({
    timestamp => 1218508949,
    value => 99.1
  });
  
  $series->addObject({
    timestamp => 1218508969,
    value => 99.8
  });
  
  ...

• cooked()

  Generate an OP::Hash object, containing consolidated, interpolated, unsorted associative rows:

  ...
  
  for ( @objects ) {
    $series->addObject($_);
  }
  
  my $data = $series->cooked(); # Returns an OP::Hash
  
  # { X => Y, ... }
  #
  # This example has been dealing with time series data
  # (X is time) and the hash will look like:
  #
  # { 
  #   timestamp => value,
  #   timestamp => value,
  #   ...
  # }
  
  #
  # Access the processed series data as a normal Perl hashref,
  # or with any OP::Hash instance method:
  #
  $data->each( sub{
    print "at unix time $_, value was $data->{$_}\n";
  } );

• clearHash()

  Resets all internal data structures to a pre-cooked state.

  ...
  
  my $set1 = $series->cooked();
  
  $series->clearHash();
  
  ...
  
  my $set2 = $series->cooked();

SEE ALSO

Parse::RPN, Math::Spline, Math::VecStat

OP::Class, OP::Array, OP::Hash

Inspired by Tie::Hash::Interpolate

This file is part of OP.

REVISION

$Id: //depotit/tools/snitchd/OP-0.20/lib/OP/Series.pm#1 $