NAME

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

SYNOPSIS

Functional interface:

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

Plot data from two arrays:

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

or piddles:

    use Chart::Scientific;
    my $plt = Pdplot->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 = Pdplot->new (
                  filename => 'data.tab-separated', 
                  split    => '\t',
                  x_col    => 'time',
                  y_col    => 'vel,acc',
                  err_col  => 'vel_err,acc_err',
                  xlabel   => "time",
                  ylabel   => "velocity and acceleration",
              );
    $plt->plot ();

Plot data in arrays:

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

Plot data in pdls:

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

Plot the above data to a file:

    my $plt = Pdplot->new (
                  x_data => $pdl_x,
                  y_data => [ $pdl_y1, $pdl_y2 ],
                  device => 'myplot.ps/cps',
              );
    $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. 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.

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 yerr_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 yerr_data specified must be of the same datatype, arrays or piddles.

yerr_data

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

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

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

cannot be acompanied by:

    yerr_data => [ \@y_err ]

but

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

would be allowed.

The x_data, y_data, and yerr_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).

yerr_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 xcol => 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

xrange

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

yrange

Specify a comma-separated non-default range for the X values. Example: a yrange value of '-5,5' will plot the data from y=-5 to y=5. If the ylog flag is on, the yrange values must be specified in powers of ten. E.G. -ylog -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

xlog

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

ylog

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

Residual options

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

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

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.

xlabel

A string to specify the label for the x axis.

ylabel

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

A comma-separated string that specifies 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 '5,3,0,4" followed by the sequence 6...99.

Axis drawing options

axis

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

axis_residual

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

Help and verbosity options

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 output. The range is -1 to 4, with increasing verbosity at each level.

SEE ALSO

PDL 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)

cpanm Chart::Scientific

perl -MCPAN -e shell
install Chart::Scientific