/ 
Chart-Scientific-0.16
River stage zero No dependents
/ Chart::Scientific

NAME

Chart::Scientific - Generate simple 2-D scientific plots with logging, errbars, etc.

SYNOPSIS

Procedural interface

use Chart::Scientific qw/make_plot/;
make_plot ( x_data => \@x_values, y_data => \@yvalues );

The subroutine make_plot creates a Chart::Scientific object passing along every argument it was given. See OPTIONS below for a full list of allowed arguments.

Object Oriented interface

Plot data from two arrays:

use Chart::Scientific;
my $plt = Chart::Scientific->new (
    x_data => \@x_values,
    y_data => \@y_values,
);
$plt->plot ();

or piddles:

use Chart::Scientific;
my $plt = Chart::Scientific->new (
    x_data => $x_pdl,
    y_data => $y_pdl,
);
$plt->plot ();

Plot data from an arbitrarily-delimitted file (the data in columns "vel" and "acc" vs the data in the column "time", with errorbars from the columns "vel_err" and "acc_err"):

my $plt = Chart::Scientific->new (
              filename => 'data.tab-separated', 
              split    => '\t',
              x_col    => 'time',
              y_col    => 'vel,acc',
              err_col  => 'vel_err,acc_err',
              x_label  => "time",
              y_label  => "velocity and acceleration",
          );
$plt->plot ();

Plot data in arrays:

my $plt = Chart::Scientific->new (
              x_data => \@height,
              y_data => [ \@weight, \@body_mass_index  ],
          );
$plt->plot ();

Plot data in pdls:

my $plt = Chart::Scientific->new (
              x_data => $pdl_x,
              y_data => [ $pdl_y1, $pdl_y2 ],
          );
$plt->plot ();

Plot the above data to a file:

my $plt = Chart::Scientific->new (
              x_data => $pdl_x,
              y_data => [ $pdl_y1, $pdl_y2 ],
              device => 'myplot.ps/cps',
          );
$plt->plot ();

Generate multiple plots with the same object:

my @x1 = 10..19;
my @y1 = 20..29;
my @y2 = 50..59;

my $plt = Chart::Scientific->new (
              x_data  => \@x1,
              y_data  => \@y1,
              x_label => "test x",
              y_label => "test y",
          );
$plt->setvars ( title => 'testa', device => '1/xs' );
$plt->plot ();

$plt->setvars ( title => 'testb', device => '2/xs' );
$plt->plot ();

DESCRIPTION

Chart::Scientific is a simple PDL-based plotter. 2-D plots can be easily made from data in an array or PDL, or from a file containing columns of data. The columns can be delimited with any character(s) or regular expression.

There are many plotting options:

Graph axes can be logged (non-finite data, i.e. negative data that is logged, will be ignored, with a warning), error bars can be plotted, the axes can be displayed, residuals can be plotted, font, line thickness, character size, plot point style, and colors can all be adjusted, line or point plotting, or both, can be supressed. Labels can be written on either axis, and the x and y ranges can be specified.

PUBLIC METHODS

new ( %options | option-values list )

Creates a new Chart::Scientific object, and intializes it with the given options. The options defining plot data (i.e. {filename,x_col,y_col} or {x_data,y_data}) must be specified in the constructor. All other options can be given either as a hash or a simple list of option => value pairs. Legal options are given in the OPTIONS section.

setvars ( %options | option-values list )

Sets new options for a Chart::Scientific instance or overwrites existing options. The input format is identical to the Constructor's. See the OPTIONS section for a complete list of options.

plot

Create the plot. The plot is written the the existing device, whether it is a window or a file.

getvars ( option list )

Returns a list of the values of the options listed in the argument.

restore_defaults

Restore the Chart::Scientific object to the default settings.

clear

Completely clear the Chart::Scientific object, setting it equal to an empty hashref. Arguably less useful than restore_defaults.

OPTIONS

Data from arrays or piddles

Plotting data may come from either arrays, piddles, or a file, but all data must be of the same type.

x_data

An array or piddle that contains the x-data for this plot. The x_data, y_data, and y_err_data specified must be of the same datatype, arrays or piddles.

y_data

An array or piddle that contains the y-data for this plot. Multiple sets of y-data to plot against the same x-data can be specified with an array of arrays or an array of piddles. The x_data, y_data, and y_err_data specified must be of the same datatype, arrays or piddles.

y_err_data

An array or piddle that contains the error bars for the y-data.

There must be the same number of y_err_data as there are y_data, e.g.,

y_data => [ \@y_data1, \@y_data2 ]

cannot be acompanied by:

y_err_data => [ \@y_err ]

but

y_err_data => [ \@y_err1, \@y_err2  ]

would be allowed.

The x_data, y_data, and y_err_data specified must be of the same datatype, arrays or piddles.

Options concerning data from a file
filename

The name of the file to read data from. Specify 'stdin' to read from STDIN (using the constructor or setvars). If split (see below) is not specified, the file is assumed to be an RDB file (see http://hea-www.harvard.edu/MST/simul/software/docs/rdb.html). An kludgy attempt to read the file if the RDB.pm module is not on the local system will be made: RDB comments (leading '#'s) are stripped, the column definition line is ignored, and the body of the file is split into columns on tabs.

split

Used for non-RDB files, split specifies which character(s) (or regex) to split the data from the file on. For a comma-delimitted file, --split ',' would be the correct usage, or --split '\|' for a pipe-delimitted file (the pipe is a special char in perl regexes, so we must escape it). If the file specified by filename is an RDB file, this switch should not be used.

The first line of a file must list the names of the columns, delimmited identically.

x_col

The name of the x column.

y_col

A comma-separated list of the name(s) of the y column(s).

y_err_col

A comma-separated list of the name(s) of the y errorbar column(s).

group_col

(Optional) The name of the grouping column. The grouping column separates a x_col or y_col into different datasets, based on the value of the grouping column in each row. For example, if x_col => x, y__col => y, group => g:

x   y   g
1   2   dataset1
2   3   dataset1
3   4   dataset1
4   5   dataset1
5   12  dataset2
6   13  dataset2
7   14  dataset2
8   15  dataset2

There would be two groups, dataset1 containing x = (1,2,3,4) and y = (2,3,4,5), and dataset2 containing x = (5,6,7,8) and y = (12,13,14,15). The two groups of data would be plotted as separate lines on the plot.

Plot limit Options
x_range

Specify a comma-separated non-default range for the X values. Example: an x_range value of '-5,5' will plot the data from x=-5 to x=5. If the x_log flag is on, the x_range values must be specified in powers of ten. E.G. -x_log -x -1,2 will plot the data on a logged X range from 0.1 to 100.

y_range

Specify a comma-separated non-default range for the X values. Example: a y_range value of '-5,5' will plot the data from y=-5 to y=5. If the y_log flag is on, the y_range values must be specified in powers of ten. E.G. -y_log -y -1,2 will plot the data on a logged Y range from 0.1 to 100.

Output device options
device

The PGPLOT plotting device. Use "filename.ps/cps" to print to a postscript file, or "filename.png/png" to print to a PNG file. All plotting devices supported by PDL::Graphics::PGPLOT are supported. Defaults to '/xs', which prints to a new window.

Plot type options
nopoints

Set to true to supress points plotting. Points are plotted by default.

noline

Set to true to supress line drawing. Lines are drawn by default.

Logarithmic plot options
x_log

Set to true to create a plot with a logged x axis.

y_log

Set to true to create a plot with a logged y axis.

Residual options
residuals

If true, residuals will be calculated and drawn in a second pane. The residuals will be between the first two specified y-values (this needs an upgrade). The default is false.

For plots that pull two or more y-data sets from the same rows (i.e., no group_col column), the residuals are the difference of the first two specified y-data columns. For plots that use a group_col column, the residuals are the interpolated differences between the first and the second group_col-column sets of y-data.

residuals_size

The fraction of the plotting area that the residuals occupy. The default is 0.25, and the range is 0.0 to 1.0.

Legend options
nolegend

Setting this to a true value will suppress legend drawing. The default is 0.

legend_location

A comma-separated list that to specify a location for the plot's legend. The default is .02,-.05. The coordates are in the range [0-1] for x, and [0,-1] for y, with the origin in the upper-left corner of the plot.

legend_text

A comma-separated list, with one item to specify the text for each set of dependent data. The list must be given in in the same order as the data sets are given.

Labelling options
title

A string to specify the title of the plot.

subtitle

A string to specify the subtitle of the plot. If the PGPLOT.pm module is not on the system, the subtitle will be appended to the title.

x_label

A string to specify the label for the x axis.

y_label

A string to specify the label for the y axis.

residuals_label

A string to specify the label for the residuals. The default is "deltas".

residuals_pos

Setting this to a true value will move the numbering on the residuals plot from the left to the right side of the pane.

Formatting options
line_width

The PGPlot line width. The default is 2.

char_size

The PGPlot character size. The default is 1.

colors

A comma-separated string that specifies the color set to use for drawing points and lines. For example, if 'red,blue,black' is the argument, the first set of points will be drawn red, the second blue, the third black, and then the fourth will be drawn red agan. The default is 'black,red,green,blue,yellow,cyan,magenta,gray'.

font

A PGPlot font integer. The default is 1, and the range is 1-4.

symbols

An anonymous array of PGPLOT symbol types, which specify the symbol set to use for drawing points and lines. For example, if [0,3,4] is the argument, the first set of points will be drawn with symbol 0, the second with symbol 3, and the third with symbol 4. The fourth set of points will be drawn with symbol 0, and so forth. The default is [ 3, 0, 5, 4, 6..99 ].

Axis drawing options
axis

Setting this to true will draw the x=0 and y=0 axes on the main plotting pane.

axis_residuals

Setting this to true will draw the x=0 and y=0 axes on the residuals plotting pane.

Help and verbosity options
help

Set this to true to print a short help message and exit.

usage

Set this to true to print a lengthy help message and exit.

defaults

Set this to true to print default values of the arguments and exit.

verbose

A verbose setting of 0 results in nearly silent operation. -1 suppresses all nonfatal output. The range is -1 to 4, with increasing verbosity at each level.

SEE ALSO

PDL, especially PDL::Graphics::PGPLOT, and PGPLOT.pm.

LICENSE

This software is released under the GNU General Public License. You may find a copy at

http://www.fsf.org/copyleft/gpl.html

AUTHOR

Kester Allen (kester@gmail.com)