NAME

RandomJungle::File::XML - Low level access to the data in the RandomJungle XML output file

VERSION

Version 0.06

SYNOPSIS

RandomJungle::File::XML provides access to the data contained within RandomJungle's XML output file. See RandomJungle::Jungle and RandomJungle::Tree for higher-level methods.

        use RandomJungle::File::XML;

        my $xml = RandomJungle::File::XML->new( filename => $xmlfile ) || die $RandomJungle::File::XML::ERROR;
        $xml->parse || die $xml->err_str;

        my $file = $xml->get_filename; # returns the filename of the XML file
        my $href = $xml->get_RJ_input_params; # all the input params that were used for RJ
        my $aref = $xml->get_tree_ids; # sorted numerically
        my $href = $xml->get_tree_data; # data for all trees (not RJ::Tree objects)
        my $href = $xml->get_tree_data( tree_id => $id ) || warn $xml->err_str;

        my $href = $xml->get_data; # for debugging only; returns raw data structs

        # Error handling
        $xml->set_err( 'Something went boom' );
        my $msg = $xml->err_str;
        my $trace = $xml->err_trace;

METHODS

new()

Creates and returns a new RandomJungle::File::XML object:

        my $xml = RandomJungle::File::XML->new( filename => $xmlfile );

The 'filename' parameter is required. Sets $ERROR and returns undef on failure.

parse()

Parses the XML file specified in new():

        my $retval = $xml->parse;

Returns a true value on success. Sets err_str and returns undef on failure.

get_filename()

Returns the name of the XML file specified in new():

        my $file = $xml->get_filename;

get_RJ_input_params()

Returns a href containing the input parameters that were used when Random Jungle was run:

        my $href = $xml->get_RJ_input_params; # $href->{$param_name} = $param_value;

This method calls parse() if it has not already been called.

get_tree_ids()

Returns an aref of tree IDs (sorted numerically):

        my $aref = $xml->get_tree_ids;

This method calls parse() if it has not already been called.

get_tree_data()

Returns an href of tree records (not RandomJungle::Tree objects):

        my $href = $xml->get_tree_data; # data for all trees
        my $href = $xml->get_tree_data( tree_id => $id );

If called without parameters, records for all trees will be returned. The tree_id parameter can be used to get a single record (returns undef if $id is invalid).

This method calls parse() if it has not already been called.

$href has the following structure: $tree_id id => $tree_id, var_id_str => varID string from XML, e.g., '((490,967,1102,...))' values_str => values string from XML, e.g., '(((0)),((0)),((1)),...)' branches_str => branches string from XML, e.g., '((1,370),(2,209),(3,160),...)'

$href is suitable for passing to RandomJungle::Tree->new().

get_data()

Returns the data structures contained in $self:

        my $href = $xml->get_data;

This method is for debugging only and should not be used in production code.

set_err()

Sets the error message (provided as a parameter) and creates a stack trace:

        $xml->set_err( 'Something went boom' );

err_str()

Returns the last error message that was set:

        my $msg = $xml->err_str;

err_trace()

Returns a backtrace for the last error that was encountered:

        my $trace = $xml->err_trace;

SEE ALSO

RandomJungle::Jungle, RandomJungle::Tree, RandomJungle::Tree::Node, RandomJungle::XML, RandomJungle::OOB, RandomJungle::RAW, RandomJungle::DB, RandomJungle::Classification_DB

AUTHOR

Robert R. Freimuth

COPYRIGHT

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.

cpanm RandomJungle::Tree

perl -MCPAN -e shell
install RandomJungle::Tree