RandomJungle::Jungle - Consolidated interface for Random Jungle input and output data
Version 0.05
RandomJungle::Jungle provides a simplified interface to access Random Jungle input and output data. See RandomJungle::Tree for methods relating to the classification trees produced by Random Jungle, and RandomJungle::File::DB for lower-level methods that are wrapped by this module.
use RandomJungle::Jungle; my $rj = RandomJungle::Jungle->new( db_file => $file ) || die $RandomJungle::Jungle::ERROR; $rj->store( xml_file => $file, oob_file => $file, raw_file => $file ) || die $rj->err_str; my $href = $rj->summary_data(); # for loaded data my $href = $rj->get_filenames; # filenames specified in store() my $href = $rj->get_rj_input_params; # input params that were used when RJ was run my $aref = $rj->get_variable_labels; # (expected: SEX PHENOTYPE var1 ...) my $aref = $rj->get_sample_labels; # from the IID column of the RAW file # Returns data for the specified sample, where $label is the IID from the RAW file my $href = $rj->get_sample_data_by_label( label => $label ) || warn $rj->err_str; my $aref = $rj->get_tree_ids; my $tree = $rj->get_tree_by_id( $id ) || warn $rj->err_str; # RJ::Tree object # Returns hash of arefs containing lists of tree IDs, by OOB state for the sample my $href = $rj->get_oob_for_sample( $label ) || warn $rj->err_str; # Returns the OOB state for a given sample and tree ID my $val = $rj->get_oob_state( sample => $label, tree_id => $id ) || warn $rj->err_str; # Returns a hash of arefs containing lists of sample labels, by OOB for the tree my $href = $rj->get_oob_for_tree( $tree_id ) || warn $rj->err_str; # Error handling $rj->set_err( 'Something went boom' ); my $msg = $rj->err_str; my $trace = $rj->err_trace;
Creates and returns a new RandomJungle::Jungle object:
my $rj = RandomJungle::Jungle->new( db_file => $file ) || die $RandomJungle::Jungle::ERROR;
The 'db_file' parameter is required. Returns undef and sets $ERROR on failure.
This method loads data into the RandomJungle::File::DB database. All parameters are optional, so files can be loaded in a single call or in multiple calls. Each type of file can only be loaded once; subsequent calls to this method for a given file type will overwrite the previously-loaded data.
$rj->store( xml_file => $file, oob_file => $file, raw_file => $file ) || die $rj->err_str;
Returns true on success. Sets err_str and returns false if an error occurred.
Returns a hash reference containing the names of the files specified in store():
my $href = $rj->get_filenames;
Keys in the href are db, xml, oob, and raw.
Returns a href of the input parameters used when Random Jungle was run:
my $href = $rj->get_rj_input_params; # $href->{$param_name} = $param_value;
Returns a reference to an array that contains the variable labels from the RAW file:
my $aref = $rj->get_variable_labels; # (expected: SEX PHENOTYPE var1 ...)
Returns a reference to an array that contains the sample labels from the IID column of the RAW file:
my $aref = $rj->get_sample_labels;
Returns a hash ref containing data for the sample specified by label => $label, where label is the IID from the RAW file. Sets err_str and returns undef if label is not specified or is invalid.
my $href = $rj->get_sample_data_by_label( label => $label ) || warn $rj->err_str;
$href has the following structure: SEX => $val, PHENOTYPE => $val, orig_data => $line, (unsplit, unspliced) index => $i, (index in aref from get_sample_labels(), can be used to index into OOB matrix) classification_data => $aref, (can be passed to RandomJungle::Tree->classify_data)
Returns an array ref of tree IDs (sorted numerically):
my $aref = $rj->get_tree_ids;
Returns a RandomJungle::Tree object for the specified tree.
my $tree = $rj->get_tree_by_id( $id ) || warn $rj->err_str;
Sets err_str and returns undef if tree ID is undef or invalid, or if an internal error occurred.
Returns lists of tree IDs, by OOB state, for the specified sample label.
my $href = $rj->get_oob_for_sample( $label ) || warn $rj->err_str;
The href contains the following keys, each of which point to an array reference containing tree IDs: sample_used_to_construct_trees => [], sample_not_used_to_construct_trees => [],
Sets err_str and returns undef if the specified sample cannot be found (invalid label) or on error.
Returns the OOB state for a given sample label and tree ID:
my $val = $rj->get_oob_state( sample => $label, tree_id => $id ) || warn $rj->err_str;
Expected values are 0 (the sample is "in bag" for the tree) or 1 (the sample is "out of bag" for the tree).
Sets err_str and returns undef if sample or tree_id are not defined, or if sample label is invalid.
Returns lists of sample labels, by OOB state, for the specified tree ID.
my $href = $rj->get_oob_for_tree( $tree_id ) || warn $rj->err_str;
The href contains the following keys, each of which point to an array reference containing sample labels: in_bag_samples => [], oob_samples => [],
Sets err_str and returns undef if the specified tree ID cannot be found (invalid) or on error.
Returns an href containing a summary of the data that is loaded into the db:
my $href = $rj->summary_data();
$href contains the output of other methods in this class, and it has the following structure:
filenames => get_filenames(), rj_params => get_rj_input_params(), variable_labels => get_variable_labels() and see below, sample_labels => get_sample_labels() and see below, tree_ids => get_tree_ids() and see below,
The keys variable_labels, sample_labels, and tree_ids all point to hrefs. Each href has the following structure:
all_labels => $aref, (for variable_labels and sample_labels) all_ids => $aref, (for tree_ids only) first => $val, (the first element of the all* aref) last => $val, (the last element of the all* aref) count => $val, (the size of the all* aref)
Sets the error message (provided as a parameter) and creates a stack trace:
$rj->set_err( 'Something went boom' );
Returns the last error message that was set:
my $msg = $rj->err_str;
Returns a backtrace for the last error that was encountered:
my $trace = $rj->err_trace;
RandomJungle::Jungle, RandomJungle::Tree, RandomJungle::Tree::Node, RandomJungle::XML, RandomJungle::OOB, RandomJungle::RAW, RandomJungle::DB, RandomJungle::Classification_DB
Robert R. Freimuth
Copyright (c) 2011 Mayo Foundation for Medical Education and Research. All rights reserved.
This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
The full text of the license can be found in the LICENSE file included with this module.
To install RandomJungle::Tree, copy and paste the appropriate command in to your terminal.
cpanm
cpanm RandomJungle::Tree
CPAN shell
perl -MCPAN -e shell install RandomJungle::Tree
For more information on module installation, please visit the detailed CPAN module installation guide.