/ 
Astro-QDP-Parse-0.13
River stage zero No dependents
/ Astro::QDP::Parse

NAME

Astro::QDP::Parse - extract Data from a QDP input file

SYNOPSIS

use Astro::QDP::Parse qw/ :all /;

$rawlines = read_qdpfile( $filename );
( $data, $hdr ) = parse_qdp( $rawlines, \%options );
( $data, $hdr ) = parse_qdpfile( $filename, \%options );

DESCRIPTION

Astro::QDP::Parse processes files in QDP format (e.g., the QDP output written by XSPEC's wenv command). The QDP file contains QDP commands specifying how the data are to be read, data records and optional PLT commands.

The QDP format encodes data as one or more sets of data vectors, where a set of vectors consists of a single "independent" vector and one or more "dependent" data vectors of the same length. Each pairing of a dependent vector with its matching "independent" vector is considered a separate data group.

A data vector consists of a data column and zero, one, or two error columns.

INTERFACE

Functions

read_qdpfile
$lines = read_qdpfile( $filename );

This function reads data the named QDP file, and returns an array containing logical records. (Lines ending with '-' (the QDP line continuation character) are concatenated to generate the logical lines). It does not interpolate files accessed via the PLT @filename command.

parse_qdp
($data, $hdr) = parse_qdp( \@lines, \%options );

The function extracts the data in the passed array (which must contain data and QDP or PLT command records) and returns the encoded data groups and other metadata. The input array of lines is typically that returned by read_qdpfile. See also parse_qdpfile for a more turnkey approach.

The data is returned as an array of hashes, one per data group, in the order the groups were read from the input file. Each hash has the following keys:

x - the independent data vector
y - the dependent data vector

Data vectors are represented as hashes, with the following keys:

hdg

The zero based index of the vector within its containing data set. The x data vector always has hdg == 0.

vdg

The zero based index of the data set within the set of data sets which contains the vector.

dg

The unary based index of the data group containing the vector. This corresponds to QDP's numbering of data groups.

errtype

This indicates the number of errors associated with the data, either 0, 1 for symmetric sided errors and 2 for asymmetric errors.

data

A array (or piddle, if the as_pdl option was specified) containing the data.

err

A array (or piddle, if the as_pdl option was specified) containing the symmetric error, if available. If the normalize option was specified, then the symmetric error is made available via the elo and ehi elements and this element is not present.

elo

A array (or piddle, if the as_pdl option was specified) containing the lower assymmetric error, if available.

ehi

A array (or piddle, if the as_pdl option was specified) containing the upper assymmetric error, if available.

The meta-data are returned via the $hdr hash, with the following keys:

plt

An array containing the list of PLT commands in the QDP file.

The available options are:

as_pdl

If true, return the data as PDL objects (piddles) rather than arrays.

normalize

If true, symmetric errors masquerade as asymmetric errors.

parse_qdpfile
($data, $hdr) = parse_qdpfile( $filename, \%options );

parse_qdpfile combines the read_qdpfile and parse_qdp functions and takes the same optoins as parse_qdp.

DIAGNOSTICS

piddle output requested, but PDL is not available

The as_pdl option was specified, but the PDL module is not installed.

read_qdpfile: unable to open %s

The specified QDP file does not exist or is not readable.

no data in qdp file?

No data records were found in the QDP file.

unexpected number of data points: got %d expected %d

A data record contained fewer or more data columns than was expected.

unrecognized argument to PLT skip command: %s

The argument to the PLT skip command in the QDP file (or in a file specified via a @filename PLT command was not recognized.

CONFIGURATION AND ENVIRONMENT

Astro::QDP::Parse requires no configuration files or environment variables.

DEPENDENCIES

Required Modules:

Clone
IO::File
Regexp::Common
List::Util
List::MoreUtils
Params::Validate;

Optional Modules:

PDL::Core

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-astro-qdp-parse@rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Astro-QDP-Parse.

SEE ALSO

The QDP web page at http://wwwastro.msfc.nasa.gov/qdp/.

VERSION

Version 0.13

LICENSE AND COPYRIGHT

Copyright (c) 2008 The Smithsonian Astrophysical Observatory

Astro::QDP::Parse 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/>.

AUTHOR

Terry Gaetz <tgaetz@cpan.org>

Diab Jerius <djerius@cpan.org>