NAME¶
PDL::IO::HDF5 - PDL Interface to the HDF5 Data Format.
DESCRIPTION¶
This package provides an object-oriented interface for PDLs to the HDF5
data-format. Information on the HDF5 Format can be found at the NCSA's web
site at
http://www.hdfgroup.org .
LIMITATIONS¶
Currently this interface only provides a subset of the total HDF5 library's
capability.
- •
- Only HDF5 Simple datatypes are supported. No HDF5 Compound
datatypes are supported since PDL doesn't support them.
- •
- Only HDF5 Simple dataspaces are supported.
SYNOPSIS¶
use PDL::IO::HDF5;
# Files #######
my $newfile = new PDL::IO::HDF5("newfile.hdf"); # create new hdf5 or open existing file.
my $attrValue = $existingFile->attrGet('AttrName'); # Get attribute value for file
$existingFile->attSet('AttrName' => 'AttrValue'); # Set attribute value(s) for file
#Groups ######
my $group = $newfile->group("/mygroup"); # create a new or open existing group
my @groups = $existingFile->groups; # get a list of all the groups at the root '/'
# level.
my @groups = $group->groups; # get a list of all the groups at the "mygroup"
# level.
my $group2 = $group->group('newgroup'); # Create/open a new group in existing group "mygroup"
my $attrValue = $group->attrGet('AttrName'); # Get attribute value for a group
$group->attrSet('AttrName' => 'AttrValue'); # Set attribute value(s) for a group
$group->attrDel('AttrName1', 'AttrName2'); # Delete attribute(s) for a group
@attrs = $group->attrs; # Get List of attributes for a group
# Data Sets ########
my $dataset = $group->dataset( 'datasetName'); # create a new or open existing dataset
# in an existing group
my $dataset = $newfile->dataset( 'datasetName'); # create a new or open existing dataset
# in the root group of a file
my $dataset2 = $newfile->dataset( 'datasetName'); # create a new or open existing dataset
# in the root group.
my @datasets = $existingFile->datasets; # get a list of all datasets in the root '/' group
my @datasets = $group->datasets; # get a list of all datasets in a group
@dims = $dataset->dims; # get a list of dimensions for the dataset
$pdl = $dataset->get(); # Get the array data in the dataset
$pdl = $dataset->get($start,$length,$stride); # Get a slice or hyperslab of the array data in the dataset
$dataset->set($pdl); # Set the array data in the dataset
my $attrValue = $dataset->attrGet('AttrName'); # Get attribute value for a dataset
$dataset->attSet('AttrName' => 'AttrValue'); # Set attribute value(s) for a dataset
MEMBER DATA¶
- ID
- ID number given to the file by the HDF5 library
- filename
- Name of the file.
- accessMode
- Access Mode?? ( read /write etc????)
- attrIndex
- Quick lookup index of group names to attribute values.
Autogenerated as-needed by the allAttrValues, allAttrNames, getGroupByAttr
methods. Any attribute writes or group creations will delete this data
member, because it will no longer be valid.
The index is of this form:
{
groupName1 => { attr1 => value, attr2 => value }.
groupName2 => { attr1 => value, attr3 => value }.
.
.
.
}
For the purposes of indexing groups by their attributes, the attributes are
applied hierarchically. i.e. any attributes of the higher level groups are
assumed to be apply for the lower level groups.
- groupIndex
- Quick lookup index of attribute names/values group names.
This index is used by the getGroupByAttr method to quickly find any
group(s) that have attribute that match a desired set.
The index is of this form:
{ "attr1\0attt2" => { "value1\0value2' => [ group1, group2, ...],
"value3\0value3' => [ groupA ],
.
.
.
},
"att1" => { "value1' => [ group1, group2, ...],
"value3' => [ groupA ]
.
.
.
},
.
.
.
}
The first level of the index maps the attribute name combinations that have
indexes built to their index. The second level maps the corresponding
attribute values with the group(s) where these attributes take on these
values.
groupName1 => { attr1 => value, attr2 => value }.
groupName2 => { attr1 => value, attr3 => value }.
.
.
.
}
For the purposes of indexing groups by their attributes, the attributes are
applied hierarchically. i.e. any attributes of the higher level groups are
assumed to be apply for the lower level groups.
METHODS¶
new¶
PDL::IO::HDF5 constructor - creates PDL::IO::HDF5 object for reading or writing
data.
Usage:
$a = new PDL::IO::HDF5( $filename );
Arguments: 1) The name of the file.
If this file exists and you want to write to it, prepend the name with the
'>' character: ">name.nc"
Returns undef on failure.
Example:
$hdf5obj = new PDL::IO::HDF5( "file.hdf" );
filename¶
Get the filename for the HDF5 file
Usage:
my $filename = $HDFfile->filename;
group¶
Open or create a group in the root "/" group (i.e. top level) of the
HDF5 file.
Usage:
$HDFfile->group("groupName");
Returns undef on failure, 1 on success.
groups¶
Get a list of groups in the root "/" group (i.e. top level) of the
HDF5 file.
Usage:
@groups = $HDFfile->groups;
dataset¶
Open or create a dataset in the root "/" group (i.e. top level) of the
HDF5 file.
Usage:
$HDFfile->dataset("groupName");
Returns undef on failure, 1 on success.
Note: This is a convienence method that is equivalent to:
$HDFfile->group("/")->dataset("groupName");
datasets¶
Get a list of all dataset names in the root "/" group.
Usage:
@datasets = $HDF5file->datasets;
Note: This is a convienence method that is equivalent to:
$HDFfile->group("/")->datasets;
attrSet¶
Set the value of an attribute(s) in the root '/' group of the file.
Currently attribute types supported are null-terminated strings and any PDL
type.
Usage:
$HDFfile->attrSet( 'attr1' => 'attr1Value',
'attr2' => 'attr2 value',
'attr3' => $pdl,
.
.
.
);
Returns undef on failure, 1 on success.
Note: This is a convienence method that is equivalent to:
$HDFfile->group("/")->attrSet( 'attr1' => 'attr1Value',
'attr2' => 'attr2 value',
'attr3' => $pdl,
.
.
.
);
attrGet¶
Get the value of an attribute(s) in the root '/' group of the file.
Currently the attribute types supported are null-terminated strings and PDLs.
Usage:
@attrValues = $HDFfile->attrGet( 'attr1', 'attr2' );
attrDel¶
Delete attribute(s) in the root "/" group of the file.
Usage:
$HDFfile->attrDel( 'attr1',
'attr2',
.
.
.
);
Returns undef on failure, 1 on success.
Note: This is a convienence method that is equivalent to:
$HDFfile->group("/")->attrDel( 'attr1',
'attr2',
.
.
.
);
attrs¶
Get a list of all attribute names in the root "/" group of the file.
Usage:
@attrs = $HDFfile->attrs;
Note: This is a convienence method that is equivalent to:
$HDFfile->group("/")->attrs
_buildAttrIndex¶
Internal Method to build the attribute index hash for the object
Usage:
$hdf5obj->_buildAttrIndex;
Output:
Updated attrIndex data member
clearAttrIndex¶
Method to clear the attribute index hash for the object. This is a mostly
internal method that is called whenever some part of the HDF5 file has changed
and the attrIndex index is no longer valid.
Usage:
$hdf5obj->clearAttrIndex;
_buildGroupIndex¶
Internal Method to build the groupIndex hash for the object
Usage:
$hdf5obj->_buildGroupIndex(@attrs);
where:
@attrs List of attribute names to build
a group index on.
Output:
Updated groupIndex data member
clearGroupIndex¶
Method to clear the group index hash for the object. This is a mostly internal
method that is called whenever some part of the HDF5 file has changed and the
groupIndex index is no longer valid.
Usage:
$hdf5obj->clearGroupIndex;
getGroupsByAttr¶
Get the group names which attributes match a given set of values. This method
enables database-like queries to be made. I.e. you can get answers to
questions like 'Which groups have attr1 = value1, and attr3 = value2?'.
Usage:
@groupNames = $hdf5Obj->getGroupsByAttr( 'attr1' => 'value1',
'attr2' => 'value2' );
allAttrValues¶
Returns information about group attributes defined in the HDF5 datafile.
Usage:
# Single Attr Usage. Returns an array of all
# values of attribute 'attrName' in the file.
$hdf5obj->allAttrValues('attrName');
# Multiple Attr Usage. Returns an 2D array of all
# values of attributes 'attr1', 'attr2' in the file.
# Higher-Level
$hdf5obj->allAttrValues('attr1', 'attr2');
allAttrNames¶
Returns a sorted list of all the group attribute names that are defined in the
file.
Usage:
my @attrNames = $hdf5obj->allAttrNames;
IDget¶
Returns the HDF5 library ID for this object
Usage:
my $ID = $hdf5obj->IDget;
nameGet¶
Returns the HDF5 Group Name for this object. (Always '/', i.e. the root group
for this top-level object)
Usage:
my $name = $hdf5obj->nameGet;
DESTROY¶
PDL::IO::HDF5 Desctructor - Closes the HDF5 file
Usage:
No Usage. Automatically called
AUTHOR¶
John Cerney, j-cerney1@raytheon.com
;
# Exit with OK status
1;