The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Statistics-R-IO-0.03
River stage zero No dependents
2 ++
/ Statistics::R::IO

NAME

Statistics::R::IO - Perl interface to serialized R data

VERSION

This documentation refers to version 0.03 of the module.

SYNOPSIS

    use Statistics::R::IO;
    
    my $var = Statistics::R::IO::readRDS('file.rds');
    print $var->to_pl;
    
    my %r_workspace = Statistics::R::IO::readRData('.RData');
    while (my ($var_name, $value) = each %r_workspace) {
        print $var_name, $value;
    }

DESCRIPTION

This module is a pure-Perl implementation for reading native data files produced by the R statistical computing environmnent)

It provides routines for reading files in the two primary file formats used in R for serializing native objects:

RDS

RDS files store a serialization of a single R object (and, if the object contains references to other objects, such as environments, all the referenced objects as well). These files are created in R using the readRDS function and are typically named with the .rds file extension.

RData

RData files store a serialization of a collection of named objects, typically a workspace. These files are created in R using the save function and are typically named with the .RData file extension. (Contents of the R workspace can also be saved automatically on exit to the file named .RData, which is by default automatically read in on startup.)

See "SUBROUTINES" for invocation and usage information on individual subroutines, and the R Internals manual for the specification of the file formats.

EXPORT

Nothing by default. Optionally, subroutines readRDS and readRData, or :all for both.

SUBROUTINES

readRDS EXPR

Reads a file in RDS format whose filename is given by EXPR and returns a Statistics::R::REXP object.

readRData EXPR

Reads a file in RData format whose filename is given by EXPR and returns a hash whose keys are the names of objects stored in the file with corresponding values as Statistics::R::REXP instances.

DEPENDENCIES

Requires perl 5.012 or newer.

Core modules

  • strict

  • warnings

  • overload

  • Carp

  • Exporter

  • Module::Build

  • Scalar::Util

  • Test::More

Additional CPAN modules

  • Moo

  • namespace::clean

  • Test::Fatal

BUGS AND LIMITATIONS

The module currently handles the 'version 2' serialization format, used since R 1.4.0 (released in December 2001). Only XDR and native-order binary is implemented, and since the R documentation describes the ASCII save format as "now mainly of historical interest", this is unlikely to change soon. No check is performed that a file stored in native-order binary was created on a platform that used the same order, and it is up to the caller to ensure compatibility. (Given that the default save format is XDR, and the prevalence of Intel platforms, this is unlikely to be a problem for either publicly-distributed or internal data files.)

Data files compressed with 'gzip' and 'bzip2' are supported, but not 'xz' ones. Again, given the R defaults ('gzip') and the fact that IO::Uncompress::UnXz is not production-ready, this is unlikely to change soon.

There are some R types that are not (yet) implemented, although all typical "user-facing" types -- such as vectors, lists, and environments -- are. The remaining R types will be implemented as-needed; in other words, if you come across one that you need to read a particular file, please send me the type (the id will included in the "unimplemented SEXPTYPE" error message) and, if possible, how it was generated.

There are no known bugs in this module. Please report any bugs or feature requests to bug-statistics-r-io at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Statistics-R-IO. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Statistics::R::IO

You can also look for information at:

AUTHOR

Davor Cubranic, <cubranic at stat.ubc.ca>

LICENSE AND COPYRIGHT

Copyright 2014 University of British Columbia.

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.