Florian Merges > PGPLOT-Simple-0.05 > PGPLOT::Simple

Download:
PGPLOT-Simple-0.05.tar.gz

Dependencies

Annotate this POD

Related Modules

Tk::PNG
MIME::Base64
Tk::Graph
Tk::Task
Image::Magick
Tcl::Tk
more...
By perlmonks.org
View/Report Bugs
Module Version: 0.05   Source  

NAME ^

PGPLOT::Simple - Simple Interface to PGPLOT

SYNOPSIS ^

 use strict;
 use PGPLOT::Simple qw(:essential);

 die "Must provide a filename.\n" unless @ARGV;

 my $filename = shift;
 chomp $filename;

 unless ( $filename =~ /\.ps$/ ) {
    $filename .= ".ps";
 }
 
 set_begin({
    file => "$filename/CPS",
 });
 
 set_environment({
     x_min   =>  0,
     x_max   =>  50,
     y_min   =>  0,
     y_max   =>  10,
 });
 
 write_label({
     title  => 'A Simple Graph Using PGPLOT::Simple',
     color  => 'Blue',
     font   => 'Italic',
 });
 
 draw_points({
     x     => [1, 3, 12, 32, 40],
     y     => [1, 5,  5,  3,  9],
     color => 'Blue',
     width => 20,
 });
 
 draw_error_bars({
     x        => [20],
     y1       => [4],
     y2       => [6],
     terminal => 10,
     width    => 10,
     color    => 'Orange',
 });
 
 set_end;

DESCRIPTION ^

PGPLOT::Simple is a simple interface to the PGPLOT library ala Perl, making simple things easy and difficult things possible.

Why simple? Because it has a simple and intiutive interface to the most common things you will need from PGPLOT, but also allowing you low-level access to the PGPLOT library.

FUNCTIONS : ESSENTIAL ^

set_begin

Opens a graphical device or file and prepares it for subsequent plotting.

 set_begin({ file      => "$filename/$type",
             num_x_sub => 2,
             num_y_sub => 1,
 });

All the fields are optional. As default file would be used the Standard Output and a type of Color PostScript (CPS).

The number of X and Y subdivision of the view surface is set to 1 for each.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGBEG

set_end

Close and release any open graphics devices. This is the same as calling pgend directly.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGEND

set_environment

This function starts a new picture and defines the range of variables and the scale of the plot. It also draws and labels the enclosing box and the axes if requested.

"set_environment" establishes the scaling for subsequent calls to "draw_points", "draw_polyline", etc. The plotter is advanced to a new page or panel, clearing the screen if necessary.

 set_environment({
    x_min   =>              $x1,    # Required. Bottom left coordinate
    y_min   =>              $y1,    # Required 
    x_max   =>              $x2,    # Required. Top right coordinate
    y_max   =>              $y2,    # Required
    justify =>                0,    # Default
    axis    =>   'BoxCoordAxes',    # Default
 });

Supported axis codes:

    Clean
    Box
    BoxCoord
    BoxCoordAxes
    BoxCoordAxesGrid
    BoxXLog
    BoxYLog
    BoxXYLog

Also accept the axis number code from the PGPLOT library.

Set justify to something other than 0, to set the scales of the x and y axes (in world coordinates per inch) equal.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGENV

set_viewport

Change the size and position of the viewport, specifying the viewport in normalized device coordinates. Normalized device coordinates run from 0 to 1 in each dimension. The viewport is the rectangle on the view surface "through" which one views the graph.

 set_viewport({ x_left  => $x1,    # Required. Left coordinate
                x_right => $x2,    # Required. Right coordinate
                y_bot   => $y1,    # Required. Bottom coordinate
                y_top   => $y2,    # Required. Top coordinate
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSVP

set_window

Change the window in the world coordinate space that is to be mapped on the viewport.

 set_window({ x_min => $x1,    # Required. Bottom left coordinate
              y_min => $y1,    # Required 
              x_max => $x2,    # Required. Top right coordinate
              y_max => $y2,    # Required
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSWIN

set_box

Draw a box and optionally label one of both axes with (DD) HH MM SS style nummeric labels (useful for time or RA - DEC plots).

You define a style or options for each label. See documentation for a larger discussion about what's available.

 set_box({ x_style => 'ABCGZHON',    # Default
           y_style =>    'ABCGN',    # Default
           x_tick  =>        0.0,    # Default
           y_tick  =>        0.0,    # Default
           n_x_sub =>          0,    # Default
           n_y_sub =>          0,    # Default
 });

All parameters are optional, in which case the default values will be used.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGTBOX

set_active_panel

Start plotting in a different panel. If the view surface has been divided into panels by "set_begin" or using the PGPLOT functions pgbeg or pgsubp, this routine can be used to move to a different panel.

 set_active_panel({ x_index => 2,    # Required
                    y_index => 1,    # Required
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGPANL

set_range

Choose plotting limits x_low and x_high which encompass the data range x1 to x2.

 set_range({ x_low  => $min - 1,    # Required
             x_high => $max + 1,    # Required
             x1     => $min,        # Required
             x2     => $max,        # Required
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGRNGE

write_label

Set the graphs title and labels.

 write_label({ x          =>        'X',   # Default
               y          =>        'Y',   # Default
               title      => 'Untitled',   # Default
               font       =>   'Normal',   # Default
               color      =>     'Blue',
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGLAB

write_text

Primitive routine for drawing text. The text may be drawn at any angle with the horizontal, and may be centered or left- or right- justified at a specified position.

 write_text({ x          =>                800,     # Required
              y          =>                1.5,     # Required
              string     => "PGPLOT Is Great!",     # Required
              angle      =>                  0,     # Default
              align      =>             'Left',     # Default
              background =>      'BlueMagenta',
              color      =>           'Yellow',
              height     =>                2.5,
              font       =>           'Script',
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGPTXT

write_text_viewport

Write text at a position specified relative to the viewport (outside or inside). This routine is useful for annotating graphs. It is used by routine "write_label".

 write_text_viewport({ string   => "Potatoes",    # Required
                       displace =>       "BR",    # Default
                       coord    =>          1,    # Default
                       justify  =>     'Left',    # Default
                       color    =>     'Cyan',
 });

Displace must include one of the characters 'B', 'L', 'T', or 'R' signifying the Bottom, Left, Top, or Right margin of the viewport. If it includes 'LV' or 'RV', the string is written perpendicular to the frame rather than parallel to it.

Justify can be one of 'Left', 'Right' and 'Center'. It also accept the nummeric values defined for the pgmtxt function.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGMTXT

draw_points

Add graph markers points to an existing graph. Must provide X and Y data and Symbol.

 draw_points({ x      => \@x_data,      # Required
               y      => \@y_data,      # Required
               symbol =>  $symbol,
               color  =>    'Red',
 });

It really draw graph markers, but by default the symbol used to graph is a point. If you want something other, you need to provide a valid symbol code. See PGPLOT documentation to get the list of symbols.

Note: It's called draw_points because mainly you will use it for drawing points, and because it's easier to remember than draw_graph_markers.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGPT
http://www.astro.caltech.edu/~tjp/pgplot/hershey.html

move_pen

Move pen to the point with world coordinates X,Y. No line is drawn.

 move_pen({ x => 200,
            y => 400,
 });

Return the current pen position. Can also be called without X and Y position, in this case only the pen position is returned.

Note: return a list with 2 values, first value correspond to the X value, and second correpond to the Y value.

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGMOVE

draw_line

Draw a line from the current pen position to the point with world coordinates X,Y. The new pen position is X,Y in world coordinates.

 draw_line({ x => 743,  # Required
             y => 324,  # Required
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGDRAW

draw_polyline

Add a line to an existing graph. Must provide X and Y data.

 draw_polyline({ x      => \@x_data,   # Required
                 y      => \@y_data,   # Required
                 color  =>  'Green',
                 width  =>        5,
                style =>  'Dotted',
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGLINE

draw_polygon

Add a polygon to an existing graph. Must provide X and Y data.

 draw_polygon({ x      =>  \@x_data,   # Required
                y      =>  \@y_data,   # Required
                color  =>   'Green',
                width  =>         2,
                style  =>  'Dashed',
                fill   => 'Outline',
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGPOLY

draw_rectangle

Add a rectangle to an existing graph. Must provide X and Y data.

 draw_rectangle({ x1      =>         $x1,  # Required
                  x2      =>         $x2,  # Required
                  y1      =>         $y1,  # Required
                  y2      =>         $y2,  # Required
                  color   =>    'Orange',
                  width   =>           7,
                  style   =>  'FullLine',
                  fill    =>   'Hatched',
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGRECT

draw_circle

Add a circle to an existing graph. Must provide X, Y and Radius data.

 draw_circle({ x      =>                $x,    # Required
               y      =>                $y,    # Required
               radius =>              $rad,    # Required
               color  =>          'Orange',
               width  =>                 7,
               style  =>  'DotDashDotDash',
               fill   =>    'CrossHatched',
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGCIRC

draw_arrow

Add a arrow to an existing graph. Must provide X and Y data.

 draw_arrow({ x1          =>          1320,   # Required 
              x2          =>          1650,   # Required
              y1          =>            20,   # Required
              y2          =>           140,   # Required
              color       => 'GreenYellow',
              width       =>            10,
              arrow_style =>  { 
                fill  => 'Outline',
                angle =>        50,
              },
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGARRO

draw_error_bars

Plot horizontal or vertical error bars. Must provide X and Y data.

 draw_error_bars({ x1        =>  [400, 1000, 2600],     # Required Horizontal
                   x2        =>  [500, 1000, 3000],     # Required
                   y         =>  [1.2,  1.5,  1.4],     # Required
                   terminal  =>                  2,     # Required
                   width     =>                  2,
                   color     =>                 $f,
 });

 draw_error_bars({ y1        =>                \@c,     # Required Vertical
                   y2        =>                \@b,     # Required
                   x         =>                \@a,     # Required
                   terminal  =>                0.0,     # Required
 });

You also need to provide a 'terminal' key which corresponds to the length of terminals to be drawn at the ends of the error bar, as a multiple of the default length; if 'terminal' = 0.0, no terminals will be drawn.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGERRX
http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGERRY

draw_function

Draw functions. Must provide function type:

    'x'  - Function defined by Y = F(X)
    'y'  - Function defined by X = F(Y)
    'xy' - Function defined by X = F(T), Y = G(T)


 draw_function('x', {
         fy    => sub{ sqrt($_[0]) },   # Required
         num   =>    500,               # Required. Num. of points required to
                                        #   define the curve.
         min   =>      0,               # Required
         max   =>     50,               # Required
         flag  =>      1,               # Default.
         color => 'Blue',
         width =>      7,
 });
 
 draw_function('xy', {
         fy    => sub{ 3 * cos $_[0] }, # Required
         fx    => sub{ 5 * sin $_[0] }, # Required
         num   =>         500,          # Required
         min   =>          10,          # Required
         max   =>         100,          # Required
         color => 'GreenCyan',
         width =>           7,
 });

Flag option define if the curve is plotted in the current window and viewport. If the value is 0 pgenv is called automatically by one of the PGPLOT functions subroutines to start a new plot with automatic scaling. Take a look at the "Notes" section to see what this would imply.

References:

PGPLOT to see accepted function pass methods.
http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGFUNX
http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGFUNY
http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGFUNT
http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGENV

draw_histogram

Draw a histogram of unbinned data.

 draw_histogram({ data  =>   \@a,   # Required
                  min   =>     0,
                  max   =>   300,
                  nbin  =>    25,
                  color => 'Red',
                  width =>     2,
                  flag  =>     1,   # Default
 });

Min and max values are the minimum and maximum data value for the histogram. Min and max values defaults to the min and max value of the given array.

Nbin is the number of bins to use. Defaults to the number of elements that has the array modulo 400, which corresponds to the maximum value of bins possible.

Flag option define if the curve is plotted in the current window and viewport. If the value is 0 pgenv is called automatically by one of the PGPLOT functions subroutines to start a new plot with automatic scaling. Take a look at the "Notes" section to see what this would imply.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGHIST
http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGENV

FUNCTIONS : OPTIONAL ^

set_color

Set next primitive color, launch exception if a wrong color supplied.

See "color" to see the valid color code names. Defaults to 'Foreground' if nothing supplied.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSCI

set_text_background

Set next primitive color, launch exception if a wrong color supplied.

Support same color options as "set_color". Defaults to transparent if nothing supplied.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSTBG

set_color_representation

Set a color representation for a index value. This index value can be used later to referring to this color.

To define a color we need to pass the RGB values to the function.

 set_color_representation({ code  =>  20,    # Required
                            red   => 0.1,    # Required
                            green => 0.4,    # Required
                            blue  => 0.8,    # Required
 });

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSCRN

set_line_width

Set line height of the next primitive. Launch exception if something other than a digit is supplied.

See "width" to get the valid width range.Defaults to 2 pixel width if nothing supplied.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSLW

set_line_style

Set line style of the next line primitive. Launch exception if a wrong line style code is supplied.

See "style" to see the supported line style codes.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSLS

set_font

Set the Character Font for the next text plotting.

See "font" to see the supported font types. Defaults to 'Normal' if nothing supplied.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSCF

set_fill_area_style

Set the Fill-Area Style attribute for subsequent area-fill by "draw_polygon", "draw_rectangle", "draw_circle" or the equivalent low level functions call pgpoly, pgrect, pgcirc.

See "fill" to see the supported styles. Defaults to 'Solid' if nothing supplied.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSFS

set_arrow_style

Set the style to be used for arrowheads drawn by "draw_arrow".

See "arrow_style" to see the accepted options.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSAH

set_hatching_style

Set the style to be used for hatching. See "fill_style".

See "hatching_style" to see the accepted options.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSHS

OPTIONS ^

color

Supported color code names:

    Background
    Foreground
    Red 
    Green
    Blue
    Cyan
    Magenta
    Yellow
    Orange
    GreenYellow
    GreenCyan 
    BlueCyan 
    BlueMagenta
    RedMagenta
    DarkGray
    LightGray

Also accept the number color codes (0-255). For color numbers major than 15, you must define the color representation. See "set_color_representation" and PGPLOT docs.

background

See "color".

width

Set the line-width attribute. This attribute affects lines, graph markers, and text. The line width is specified in units of 1/200 (0.005) inch (about 0.13 mm) and must be an integer in the range 1-201.

style

This attribute affects line primitives only; it does not affect graph markers, text, or area fill.

Supported line style code names:

    FullLine
    Dashed
    DotDashDotDash
    Dotted
    DashDotDotDot

Also accept the number line style code (1-5). See PGPLOT docs.

font

Font type for text.

Supported font type code names:

    Normal
    Roman
    Italic
    Symbol

Also accept the font number code (1-4). See PGPLOT docs.

fill

Set the Fill-Area Style attribute for polygons, rectangles or circles.

    Solid
    Outline
    Hatched
    CrossHatched

Also accept the integer value identifiers (1-4). See PGPLOT docs.

align

Supported text align code names:

    Left
    Center
    Right

Also accept the float value identifiers (0, 0.5, 1). See PGPLOT docs.

height

Set the character size attribute. The size affects all text and graph markers drawn later in the program. The default character size is 1.0, corresponding to a character height about 1/40 the height of the view surface. Changing the character size also scales the length of tick marks drawn by "set_box" and terminals drawn by "draw_error_bars".

arrow_style

Set the style to be used for arrowheads drawn by "draw_arrow".

You have 3 keys to define the different parts of an arrow head:

    fill_style  - Can be 'Filled' or 'Outline'.
    angle       - The acute angle of the arrow point.
    barb        - The fraction of the triangular arrow-head that
                  is cut away from the back.

Example:

    arrow_style => { fill   =>  'Filled',   # Default   
                     angle  =>      45.0,   # Default
                     barb   =>       0.3,   # Default
    },

hathing_style

Set the style to be used for hatching. See "fill_style".

    hatching_style => { angle   => 45.0,    # Default
                        spacing =>  1.0,    # Default
                        phase   =>  0.0,    # Default
    },

NOTES ^

Low level PGPLOT Library function call

To make direct call to the PGPLOT Library you only need to call it with the package name. Example:

 print PGPLOT::Simple::pgldev();

Or, if you want to import all the functions into your namespace add the pgplot into your import call. Example:

 use PGPLOT::Simple qw(:pgplot);

Or combine them as you need. Example:

 use PGPLOT::Simple qw( :essential set_color_representation :pgplot );
Attributes settings

Please note that on each function where you can define attributes, this attributes are relative to the given function.

On PGPLOT you set a main style which all function inherit, so that changing the color using a function like set_color implies that each function call after the color setting will be plotted using that "active color".

To don't lose this global attributes settings mechanism, which can be useful, each function call of this module will call a function available from the PGPLOT Library that permits to save the current attributes, and another which permits to restore them.

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGSAVE
http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGUNSA
Functions that provide a flag option

If we set the flag option to 0, pgenv is called automatically by that function to start a new plot, but we should be aware, that each attribute we associated with the function call, for example color settings, will be applied not only to that function, but also be applied to what pgenv generates. E.g.:

 draw_function('x', {
    fy    => sub{ sqrt $_[0] },
    num   =>    500,
    min   =>      0,
    max   =>     50,
    color => 'Blue',
    width =>      7,
    flag  =>      0,    # Here we set it to 0, by default is 1.
 });

Doing this, we will have the boxes, and labels also with a width of 7 and in blue.

References:

http://www.astro.caltech.edu/~tjp/pgplot/subroutines.html#PGENV

SEE ALSO ^

PGPLOT Perl Module by Karl Glazebrook.

PGPLOT Library by Tim Pearson, http://www.astro.caltech.edu/~tjp/pgplot.

AUTHOR ^

Florian Merges, <fmerges@cpan.org>

COPYRIGHT AND LICENSE ^

Copyright (C) 2005 by Florian Merges

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.7 or, at your option, any later version of Perl 5 you may have available.

syntax highlighting: