[R] RFC: "R::Wrapper" perl module

[Aaron J Mackey]

If I actually finished writing this module, would any of you use it?
Would you wish it did something else/different than what's described
below?  Any comments or suggestions on its proposed usage, intent, or
syntax are welcome!  (An alternative, better name would also be
appreciated)  -Aaron

NAME
    R::Wrapper - Wrapper around the RS-Perl R module

SYNOPSIS
      #!/usr/bin/perl -w

      use strict;

      use R::Wrapper qw(:all);

      my @x = 1 .. 10;
      my @y = 1 .. 10;
      @x = cumsum(\@x);

      plot( { x => \@x,
              y => \@y,
              main => 'Test Plot'
            }
          );

      __END__

      # then, at the command line:

      # just view it, nothing else;
      % ./script.pl

      # after viewing, have the option to save as PDF
      # (prompt for filename):
      % ./script.pl --pdf

      # do the same, but specify filenames in advance:
      % ./script.pl --dump=rawdata.txt
      % ./script.pl --pdf=testplot.pdf
      % ./script.pl --ps=testplot.ps

      # only generate the dump, don't preview at all:
      % ./script.pl --nopreview --pdf=testplot.pdf

      # pipe the postscript to something else:
      % ./script.pl --ps="| enscript -Pbiochem_LJ5P"

      # the default argument for lpr is -P
      % ./script.pl --lpr=biochem_LJP

      # send other parameters to lpr (e.g. 2 copies);
      % ./script.pl --lpr="-Pwrp_ph56 -#2"

      # send pdf's to someone:
      % ./script.pl --pdf --email=amackey at virginia.edu --subject="Here's the latest version"

DESCRIPTION
    R::Wrapper is meant to be a utility wrapper around the RS-Perl R module.
    It currently provides three main features: the first is a visually
    "cleaner" interface to the R module's calling interface (and handling
    for a few sticky issues the R module has with vectors versus scalars).

    The second feature is to automatically "annotate" each page of output
    with meta-information about the script (it's name, path, the date,
    arguments to the script, etc etc); These annotations will appear at the
    bottom of the output page, and are meant to aid in the reproduction of
    the data used by the figure(s) at a later date.

    The third feature is that R::Wrapper provides automatic recognition for
    --dump, --pdf, --ps, --lpr and --email command line switches to scripts
    that use R::Wrapper. The point of these switches is that after
    "previewing" any plotted data in a graphical window, R::Wrapper will
    automatically prompt the user if they wish to dump the raw numerical
    data used to generate the plot (--dump), or obtain PDF or postscript
    (--pdf and --ps, respectively) versions of the plot (including
    annotations); if a filename was not specified at the command line, or if
    multiple plots are drawn by the script, the user will be prompted for
    each necessary filename. Instead of specifying filenames for --dump,
    --pdf and --ps, the outputs can also be piped into another process.
    The --lpr option expects arguments to the lpr command, instead of
    filenames. The --email option is used in conjunction with the other
    options, and specifies that the outputs should be MIME-attached to an
    email to be sent to the specified user(s).

    R::Wrapper uses the Getopt::Long module to handle command line options,
    so scripts that make use of it should 'use R::Wrapper' before any other
    processing of @ARGV occurs (R::Wrapper will strip out it's specific
    arguments, leaving any others in @ARGV for processing by the script
    itself).

MOTIVATION
    Currently, our research "flow" looks like this:

      1. Generate/collect raw data
      2. Use Perl scripts to "munge" or otherwise convert raw data into
         tabular format (or import into a relational database)
      3. Use R script(s) to analyze, transform and visualize data read in
         from tabular format (or obtained out of relational database);
         edit script until the desired output formatting/layout is
         achieved
      4. Edit R scripts furiously to redirect plotting output into
         pdf/postscript/etc.
      5. Use either Perl or R to (re)generate tabular-formatted plotting
         data (for import into publication-quality graphing environments)

    R::Wrapper attempts to combine steps 3 through 5 (although it could
    also be used in a "super script" that performed steps 1 and 2, if
    desired).  The advantage of doing this is to keep the definitions for
    data production the same: the same set of Perl and R functions are
    used to generate "preview" data in step 3, generate hardcopy in step 4
    and generate export data in step 5.

SUPPORTED ROUTINES
    Currently, R::Wrapper only supports text output (--dump) for plots
    generated using the following R functions (as a proof of concept, and
    because these are the plotting routines we use most often):

    * plot
    * points
    * lines

TODO

    * Add some kind of templating mechanism, so that text output can be
      user-controlled.
    * Add --dump support for more plotting routines (i.e. 'histogram',
      'barplot', 'boxplot', etc. etc.).

AUTHOR
    Aaron J Mackey, amackey at virginia.edu

SEE ALSO
    perl(1), RS-Perl


-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._