NAME
SYNOPSIS
DESCRIPTION
INTERFACE
Functions
DIAGNOSTICS
CONFIGURATION AND ENVIRONMENT
DEPENDENCIES
INCOMPATIBILITIES
BUGS AND LIMITATIONS
SEE ALSO
VERSION
LICENSE AND COPYRIGHT
AUTHOR

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.

VERSION

Version 0.13

LICENSE AND COPYRIGHT

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>