HDF5(3pm)

✨ NAME ✨

PDL::IO::HDF5 — the PDL interface to the HDF5 data format, bestie 💖

(yes, she's a 3pm page, she's Perl, and she's serving. we stan.)

---

🌸 DESCRIPTION 🌸

okay so this package is your object-oriented plug for getting PDLs talking to the HDF5 data format. it's giving "glue code but make it fancy." if you wanna go read up on the HDF5 format itself, the HDF Group's whole website is sitting at http://www.hdfgroup.org — go drink from that firehose, queen 👑

💀 LIMITATIONS 💀

so real talk, this interface is only doing a subset of everything the full HDF5 library can do. currently:

• Only HDF5 Simple datatypes are supported. No HDF5 Compound datatypes — PDL just doesn't support them, so that door is closed, no cap 😭
• 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"

  $group->unlink('datasetName');                         # Delete a dataset from a group

  $group->reference($dataset,'refName',\@start,\@count); # Create a scalar reference to a subregion of a
                                                         # dataset, with specified start index and count.

  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, unlimited => 1);                   # 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 💾

the little fields that live inside your object. let's go through 'em one at a time, no skipping 🙈

🪪 ID

the ID number that the HDF5 library gives to the file. that's it, that's the whole vibe.

📁 filename

the name of the file. src.

🚪 accessMode

Access Mode?? ( read /write etc????)

not me putting question marks in the docs. she's mysterious, she's lowkey undefined, and we respect her journey 💅

🔍 attrIndex

a quick lookup index that maps group names to attribute values. it gets autogenerated as-needed by the allAttrValues, allAttrNames, and getGroupByAttr methods. heads up tho: any attribute writes or group creations will delete this data member, because after that it's straight up no longer valid. gone. deleted. it's giving expired 😭

the index looks like this:

  {
    groupName1  =>  { attr1 => value, attr2 => value }.
    groupName2  =>  { attr1 => value, attr3 => value }.
   .
   .
   .
  }

and 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. (yes, inherited. the family drama of attribute lookup 🧚)

🔎 groupIndex

a quick lookup index of attribute names/values → group names. this one is what the getGroupByAttr method uses to quickly find any group(s) that have attributes matching a desired set. speed, she is serving speed ⚡

the index looks like this:

  { "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 }.
   .
   .
   .
  }

and yeah — same deal as before: 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. the inheritance thing again, she's iconic like that 👑

still got more of this page coming, bestie. we're not even done. 🫶

🌸 METHODS 🌸

okay bestie, this is the part where the object actually does stuff. each one of these is a method you call on your PDL::IO::HDF5 object. let's go, one by one, no skips 💅

✨ new ✨

the PDL::IO::HDF5 constructor — it makes you a PDL::IO::HDF5 object so you can read or write data. main character entrance, fr fr.

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" — yes the arrow thing goes outside the quotes, don't come for me, that's just how it is 🫶

returns undef on failure.

example:

$hdf5obj = new PDL::IO::HDF5( "file.hdf" );

🎀 filename 🎀

get the filename for the HDF5 file. she tells you her name, iconic.

usage:

my $filename = $HDFfile->filename;

🦋 group 🦋

open or create a group in the root "/" group (aka the top level, the main floor, the lobby) 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 (top level, again bestie) of the HDF5 file.

usage:

@groups = $HDFfile->groups;

🌈 unlink 🌈

unlink an object from the root "/" group (top level, yes) of the HDF5 file. it's giving "goodbye, we don't know her anymore."

usage:

$HDFfile->unlink($name);

⭐ dataset ⭐

open or create a dataset in the root "/" group (top level!!) of the HDF5 file.

usage:

$HDFfile->dataset("groupName");

returns undef on failure, 1 on success.

note: this is a convenience 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 convenience 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 convenience 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. bye bestie 😭

usage:

$HDFfile->attrDel( 'attr1',
                   'attr2',
                   .
                   .
                   .
                  );

returns undef on failure, 1 on success.

note: this is a convenience 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 convenience method that is equivalent to:

$HDFfile->group("/")->attrs

🔥 reference 🔥

create a reference to part of a dataset in the root "/" group of the file. like a little bookmark, except it's a whole reference, slay.

usage:

$HDFfile->reference;

note: this is a convenience method that is equivalent to:

$HDFfile->group("/")->reference($referenceName,$datasetObj,@regionStart,@regionCount);

create a reference named $referenceName within the root group "/" to a subroutine of the dataset $datasetObj. the region to be referenced is defined by the @regionStart and @regionCount arrays.

🌙 _buildAttrIndex 🌙

internal method to build the attribute index hash for the object. it's giving behind-the-scenes, you probably won't call her directly.

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?'. lowkey a whole search engine, highkey obsessed.

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). she's always /, no identity crisis, periodt.

usage:

my $name = $hdf5obj->nameGet;

🎀 DESTROY 🎀

PDL::IO::HDF5 Destructor — closes the HDF5 file.

usage:

No Usage. Automatically called

she doesn't need an invitation, bestie, she just shows up when the object goes away 🙈

---

👑 AUTHORS 👑

• John Cerney, j-cerney1@raytheon.com
• Andrew Benson, abenson@obs.carnegiescience.edu

---

and that's a wrap on the whole page, bestie!! 🎉 this doc is perl v5.42.3, dated 2026-08-21, and it's the HDF5(3pm) manual page — go forth and read/write those HDF5 files like the icon you are 💖✨🦋