Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Graph::Data(3)	      User Contributed Perl Documentation	Graph::Data(3)

NAME
       GD::Graph::Data - Data set encapsulation	for GD::Graph

SYNOPSIS
       use GD::Graph::Data;

DESCRIPTION
       This module encapsulates	the data structure that	is needed for
       GD::Graph and friends. An object	of this	class contains a list of X
       values, and a number of lists of	corresponding Y	values.	This only
       really makes sense if the Y values are numerical, but you can basically
       store anything.	Undefined values have a	special	meaning	to GD::Graph,
       so they are treated with	care when stored.

       Many of the methods of this module are intended for internal use	by
       GD::Graph and the module	itself,	and will most likely not be useful to
       you. Many won't even seem useful	to you...

EXAMPLES
	 use GD::Graph::Data;
	 use GD::Graph::bars;

	 my $data = GD::Graph::Data->new();

	 $data->read(file => '/data/sales.dat',	delimiter => ',');
	 $data = $data->copy(wanted => [2, 4, 5]);

	 # Add the newer figures from the database
	 use DBI;
	 # do DBI things, like connecting to the database, statement
	 # preparation and execution

	 while (@row = $sth->fetchrow_array)
	 {
	     $data->add_point(@row);
	 }

	 my $chart = GD::Graph::bars->new();
	 my $gd	= $chart->plot($data);

       or for quick changes to legacy code

	 # Legacy code builds array like this
	 @data = ( [qw(Jan Feb Mar)], [1, 2, 3], [5, 4,	3], [6,	3, 7] );

	 # And we quickly need to do some manipulations	on that
	 my $data = GD::Graph::Data->new();
	 $data->copy_from(\@data);

	 # And now do all the new stuff	that's wanted.
	 while (@foo = bar_baz())
	 {
	     $data->add_point(@foo);
	 }

METHODS
   $data = GD::Graph::Data->new()
       Create a	new GD::Graph::Data object.

   $data->set_x($np, $value);
       Set the X value of point	$np to $value. Points are numbered starting
       with 0. You probably will never need this. Returns undef	on failure.

   $data->get_x($np)
       Get the X value of point	$np. See "set_x".

   $data->set_y($nd, $np, $value);
       Set the Y value of point	$np in data set	$nd to $value. Points are
       numbered	starting with 0, data sets are numbered	starting with 1.  You
       probably	will never need	this. Returns undef on failure.

   $data->get_y($nd, $np)
       Get the Y value of point	$np in data set	$nd. See "set_y". This will
       return undef on an error, but the fact that it returns undef does not
       mean there was an error (since undefined	values can be stored, and
       therefore returned).

   $data->get_y_cumulative($nd,	$np)
       Get the cumulative value	of point $np in	data set<$nd>. The cumulative
       value is	obtained by adding all the values of the points	$np in the
       data sets 1 to $nd.

   $data->get_min_max_x
       Returns a list of the minimum and maximum x value or the	empty list on
       failure.

   $data->get_min_max_y($nd)
       Returns a list of the minimum and maximum y value in data set $nd or
       the empty list on failure.

   $data->get_min_max_y_all()
       Returns a list of the minimum and maximum y value in all	data sets or
       the empty list on failure.

   $data->add_point($X,	$Y1, $Y2 ...)
       Adds a point to the data	set. The base for the addition is the current
       number of X values. This	means that if you have a data set with the
       contents

	 (X1,  X2)
	 (Y11, Y12)
	 (Y21)
	 (Y31, Y32, Y33, Y34)

       a $data->add_point(Xx, Y1x, Y2x,	Y3x, Y4x) will result in

	 (X1,	 X2,	Xx )
	 (Y11,	 Y12,	Y1x)
	 (Y21,	 undef,	Y2x)
	 (Y31,	 Y32,	Y3x,  Y34)
	 (undef, undef,	Y4x)

       In other	words: beware how you use this.	As long	as you make sure that
       all data	sets are of equal length, this method is safe to use.

   $data->num_sets()
       Returns the number of data sets.

   $data->num_points()
       In list context,	returns	a list with its	first element the number of X
       values, and the subsequent elements the number of respective Y values
       for each	data set. In scalar context returns the	number of points that
       have an X value set, i.e. the number of data sets that would result
       from a call to "make_strict".

   $data->x_values()
       Return a	list of	all the	X values.

   $data->y_values($nd)
       Return a	list of	the Y values for data set $nd. Data sets are numbered
       from 1. Returns the empty list if $nd is	out of range, or if the	data
       set at $nd is empty.

   $data->reset() OR GD::Graph::Data->reset()
       As an object method: Reset the data container, get rid of all data and
       error messages. As a class method: get rid of accumulated error
       messages	and possible other crud.

   $data->make_strict()
       Make all	data set lists the same	length as the X	list by	truncating
       data sets that are too long, and	filling	data sets that are too short
       with undef values. always returns a true	value.

   $data->cumulate(preserve_undef => boolean)
       The cumulate parameter will summarise the Y value sets as follows: the
       first Y value list will be unchanged, the second	will contain a sum of
       the first and second, the third will contain the	sum of first, second
       and third, and so on.  Returns undef on failure.

       if the argument preserve_undef is set to	a true value, then the sum of
       exclusively undefined values will be preserved as an undefined value.
       If it is	not present or a false value, undef will be treated as zero.
       Note that this still will leave undefined values	in the first data set
       alone.

       Note: Any non-numerical defined Y values	will be	treated	as 0, but you
       really shouldn't	be using this to store that sort of Y data.

   $data->wanted(indexes)
       Removes all data	sets except the	ones in	the argument list. It will
       also reorder the	data sets in the order given. Returns undef on
       failure.

       To remove all data sets except the first, sixth and second, in that
       order:

	 $data->wanted(1, 6, 2)	or die $data->error;

   $data->reverse
       Reverse the order of the	data sets.

   $data->copy_from($data_ref)
       Copy an 'old' style GD::Graph data structure or another GD::Graph::Data
       object into this	object.	This will remove the current data. Returns
       undef on	failure.

   $data->copy()
       Returns a copy of the object, or	undef on failure.

   $data->read(arguments)
       Read a data set from a file. This will remove the current data. returns
       undef on	failure. This method uses the standard module Text::ParseWords
       to parse	lines. If you don't have this for some odd reason, don't use
       this method, or your program will die.

       Data file format: The default data file format is tab separated data
       (which can be changed with the delimiter	argument). Comment lines are
       any lines that start with a #. In the following example I have replaced
       literal tabs with <tab> for clarity

	 # This	is a comment, and will be ignored
	 Jan<tab>12<tab>24
	 Feb<tab>13<tab>37
	 # March is missing
	 Mar<tab><tab>
	 Apr<tab>9<tab>18

       Valid arguments are:

       file, mandatory.	The file name of the file to read from,	or a reference
       to a file handle	or glob.

	 $data->read(file => '/data/foo.dat') or die $data->error;
	 $data->read(file => \*DATA) or	die $data->error;
	 $data->read(file => $file_handle) or die $data->error;

       no_comment, optional. Give this a true value if you don't want lines
       with an initial # to be skipped.

	 $data->read(file => '/data/foo.dat', no_comment => 1);

       delimiter, optional. A regular expression that will become the
       delimiter instead of a single tab.

	 $data->read(file => '/data/foo.dat', delimiter	=> '\s+');
	 $data->read(file => '/data/foo.dat', delimiter	=> qr/\s+/);

   $data->error() OR GD::Graph::Data->error()
       Returns a list of all the errors	that the current object	has
       accumulated. In scalar context, returns the last	error. If called as a
       class method it works at	a class	level.

       This method is inherited, see GD::Graph::Error for more information.

   $data->has_error() OR GD::Graph::Data->has_error()
       Returns true if the object (or class) has errors	pending, false if not.
       In some cases (see "copy") this is the best way to check	for errors.

       This method is inherited, see GD::Graph::Error for more information.

NOTES
       As with all Modules for Perl: Please stick to using the interface. If
       you try to fiddle too much with knowledge of the	internals of this
       module, you could get burned. I may change them at any time.
       Specifically, I probably	won't always keep this implemented as an array
       reference.

AUTHOR
       Martien Verbruggen <mgjv@tradingpost.com.au>

   Copyright
       (c) Martien Verbruggen.

       All rights reserved. This package is free software; you can
       redistribute it and/or modify it	under the same terms as	Perl itself.

SEE ALSO
       GD::Graph, GD::Graph::Error

perl v5.32.1			  2013-06-22			Graph::Data(3)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | METHODS | NOTES | AUTHOR | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=GD::Graph::Data&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help