p5-Statistics-NiceR

p5-Statistics-NiceR copied to clipboard

=pod

=encoding UTF-8

=head1 NAME

Statistics::NiceR - interface to the R programming language

=head1 VERSION

version 0.03

=head1 SYNOPSIS

use Statistics::NiceR;

my $r = Statistics::NiceR->new();

say $r->pnorm( [ 0 .. 3 ] )
# [0.5 0.84134475 0.97724987  0.9986501]

=head1 DESCRIPTION

This module provides an interface to the R programming language for statistics by embedding the R interpreter using its C API. This allows direct access to R's functions and allows sending and receiving data efficiently.

=head2 CONVERSION

In order to give the module a hassle-free interface, there is a mechanism to convert Perl types[^1] to R types[^2] and vice-versa for the values sent to and from the R interpreter.

Currently, the conversion is handled by the modules under the LStatistics::NiceR::DataConvert namespace. It is currently undocumented how to extend this to more types or how to change the default behaviour, but this will be addressed in future versions.

[^1]: Such as strings, numbers, and arrays.

[^2]: Such as integers, numerics, data frames, and matrices.

=head1 METHODS

=head2 new

new()

Creates a new instance of a wrapper around the R interpreter.

Example

use Statistics::NiceR;

my $r = Statistics::NiceR->new();

=head2 eval_parse

eval_parse( Str $r_code )

A convenience function that allows for evaluating arbitrary R code.

The return value is the last line of the code in C<$r_code>.

Example:

use Statistics::NiceR;

my $r = Statistics::NiceR->new();
my $dataframe = $r->eval_parse( q< iris[1:20,1:4] > );

=for comment TODO change this wording when the Statistics::NiceR::DataConvert module is documented and when changing the converter behaviour is documented for Statistics::NiceR

=head2 CALLING R FUNCTIONS

R functions can be called by using the name of the function as a method call. For example, to call the L<pnorm|https://stat.ethz.ch/R-manual/R-devel/library/stats/html/Normal.html> function (PDF of the normal distribution), which has the R function signature

pnorm(q, mean = 0, sd = 1, lower.tail = TRUE, log.p = FALSE)

one could run

use Statistics::NiceR;
my $r = Statistics::NiceR->new();

say $r->pnorm( 0 ) # N( μ = 0, σ² = 1) at x = 0
# 0.5

say $r->pnorm( 5, 1, 2 ) # N( μ = 1, σ² = 2) at x = 5
# 0.977249868051821

Since R can have identifiers that contain a period (".") in their name and Perl can not, CStatistics::NiceR maps

=over 4

=item * a single underscore in the Perl function name ("_") to a period in the R function name (".")

=item * two consecutive underscores in the Perl function name ("__") to a single underscore in the R function name ("_").

=back

So in order to call R's C<as.Date> function, one could run:

use Statistics::NiceR;
my $r = Statistics::NiceR->new();

say $r->as_Date( "02/27/92", "%m/%d/%y" ); # one underscore
# [1] "1992-02-27"

or to call R's C<l10n_info> function, one could run:

use Statistics::NiceR;
my $r = Statistics::NiceR->new();

say $r->l10n__info(); # two underscores
# $MBCS
# [1] TRUE
#
# $`UTF-8`
# [1] TRUE
#
# $`Latin-1`
# [1] FALSE

=for comment TODO Need to document how to call functions with named arguments.

=head1 INSTALLATION

On a system with a package manager, it would be best to install the R base package using the package manager.

=head2 Windows

For Windows, both the L<R base|http://cran.r-project.org/bin/windows/base/> and L<Rtools|http://cran.r-project.org/bin/windows/Rtools/> are necessary.

=head1 SEE ALSO

=over 4

=item * L<The R Project for Statistical Computing|http://www.r-project.org/>

=item * Browse and download additional R packages: L<The Comprehensive R Archive Network|http://cran.r-project.org/>

=item * L<R Tutorial: R Introduction|http://www.r-tutor.com/r-introduction>

=back

For developers:

=over 4

=item * L<Writing R Extensions|http://cran.r-project.org/doc/manuals/r-release/R-exts.html>

=item * L<Advanced R by Hadley Wickham: R’s C interface|http://adv-r.had.co.nz/C-interface.html>

=back

=head1 AUTHOR

Zakariyya Mughal [email protected]

=head1 COPYRIGHT AND LICENSE

This software is copyright (c) 2014 by Zakariyya Mughal.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.

=cut