--- name: "PDL::IO::HDF5::Dataset" section: "3pm" platform: "linux" package: "libpdl-io-hdf5-perl" version: "1:0.761-1" release: "Debian 13 (Trixie)" platforms: ["linux"] url: "https://new.carta.tech/PDL::IO::HDF5::Dataset" --- # PDL::IO::HDF5::Dataset(3pm) PDL::IO::HDF5 Helper Object representing HDF5 datasets. ## NAME PDL::IO::HDF5::Dataset - PDL::IO::HDF5 Helper Object representing HDF5 datasets. ## DESCRIPTION This is a helper-object used by PDL::IO::HDF5 to interface with HDF5 format's dataset objects. Information on the HDF5 Format can be found at the HDF Group's web site at http://www.hdfgroup.org . ## SYNOPSIS See PDL::IO::HDF5 ## MEMBER DATA - ID ID number given to the dataset by the HDF5 library - name Name of the dataset. - parent Ref to parent object (group) that owns this dateset. - fileObj Ref to the PDL::IO::HDF5 object that owns this object. ## METHODS ### new PDL::IO::HDF5::Dataset Constructor - creates new object **Usage:** This object will usually be created using the calling format detailed in the SYNOPSIS. The following syntax is used by the PDL::IO::HDF5 object to build the object. ``` $a = new PDL::IO::HDF5:Dataset( name => $name, parent => $parent, fileObj => $fileObj); Args: $name Name of the dataset $parent Parent Object that owns this dataset $fileObj PDL::HDF object that owns this dateset. ``` ### DESTROY PDL::IO::HDF5::Dataset Destructor - Closes the dataset object **Usage:** ``` No Usage. Automatically called ``` ### set Write data to the HDF5 dataset **Usage:** ``` $dataset->set($pdl, unlimited => 1); # Write the array data in the dataset Options: unlimited If present, the dataset is created with unlimited dimensions. ``` ### get Get data from a HDF5 dataset to a PDL **Usage:** ``` $pdl = $dataset->get; # Read the Array from the HDF5 dataset, create a PDL from it # and put in $pdl # Assuming $dataset is three dimensional # with dimensions (20,100,90) ``` The *get* method can also be used to obtain particular slices or hyperslabs of the dataset array. For example, if `$dataset` is three dimensional with dimensions (20,100,90) then we could do: ``` $start=pdl([0,0,0]); # We begin the slice at the very beginning $end=pdl([19,0,0]); # We take the first vector of the array, $stride=pdl([2,1,1]); # taking only every two values of the vector $pdl = $dataset->get($start,$end,[$stride]); # Read a slice or # hyperslab from the HDF5 dataset. # $start, $end and optionally $stride # should be PDL vectors with length the # number of dimensions of the dataset. # $start gives the starting coordinates # in the array. # $end gives the ending coordinate # in the array # $stride gives the steps taken from one # coordinate to the next of the slice ``` The mapping of HDF5 datatypes in the file to PDL datatypes in memory will be according to the following table. ``` HDF5 File Type PDL Type ------------------------ ----------------- PDL::IO::HDF5::H5T_C_S1() => PDL::Char Object (Special Case for Char Strings) PDL::IO::HDF5::H5T_STD_I8BE() => $PDL::Types::PDL_SB, PDL::IO::HDF5::H5T_STD_I8LE() => $PDL::Types::PDL_SB, PDL::IO::HDF5::H5T_STD_U8BE() => $PDL::Types::PDL_B, PDL::IO::HDF5::H5T_STD_U8LE() => $PDL::Types::PDL_B, PDL::IO::HDF5::H5T_STD_I16BE() => $PDL::Types::PDL_S, PDL::IO::HDF5::H5T_STD_I16LE() => $PDL::Types::PDL_S, PDL::IO::HDF5::H5T_STD_U16BE() => $PDL::Types::PDL_U, PDL::IO::HDF5::H5T_STD_U16LE() => $PDL::Types::PDL_U, PDL::IO::HDF5::H5T_STD_I32BE() => $PDL::Types::PDL_L, PDL::IO::HDF5::H5T_STD_I32LE() => $PDL::Types::PDL_L, PDL::IO::HDF5::H5T_STD_U32LE() => $PDL::Types::PDL_UL, PDL::IO::HDF5::H5T_STD_U32BE() => $PDL::Types::PDL_UL, PDL::IO::HDF5::H5T_STD_I64LE() => $PDL::Types::PDL_LL, PDL::IO::HDF5::H5T_STD_I64BE() => $PDL::Types::PDL_LL, PDL::IO::HDF5::H5T_STD_U64LE() => $PDL::Types::PDL_ULL, PDL::IO::HDF5::H5T_STD_U64BE() => $PDL::Types::PDL_ULL, PDL::IO::HDF5::H5T_IEEE_F32BE() => $PDL::Types::PDL_F, PDL::IO::HDF5::H5T_IEEE_F32LE() => $PDL::Types::PDL_F, PDL::IO::HDF5::H5T_IEEE_F64BE() => $PDL::Types::PDL_D, PDL::IO::HDF5::H5T_IEEE_F64LE() => $PDL::Types::PDL_D ``` For HDF5 File types not in this table, this method will attempt to map it to the default PDL type PDL\_D. If the dataset being read is a scalar reference, the referenced dataset region will be read instead. **Note:** Character arrays are returned as the special PDL::Char fixed-length string type. For fixed-length HDF5 string arrays, this is a direct mapping to the PDL::Char datatype. For HDF5 variable-length string arrays, the data is converted to a fixed-length character array, with a string size equal to the maximum size of all the strings in the array. ### dims Get the dims for a HDF5 dataset. For example, a 3 x 4 array would return a perl array (3,4); **Usage:** ``` @pdl = $dataset->dims; # Get an array of dims. ``` ### attrSet Set the value of an attribute(s) Attribute types supported are null-terminated strings and PDL matrices **Usage:** ``` $dataset->attrSet( 'attr1' => 'attr1Value', 'attr2' => 'attr2 value', 'attr3' => $pdl, . . . ); ``` Returns undef on failure, 1 on success. ### attrDel Delete attribute(s) **Usage:** ``` $dataset->attrDel( 'attr1', 'attr2', . . . ); ``` Returns undef on failure, 1 on success. ### attrs Get a list of all attribute names associated with a dataset **Usage:** ``` @attrs = $dataset->attrs; ``` ### attrGet Get the value of an attribute(s) Currently the attribute types supported are null-terminated strings and PDLs. **Usage:** ``` my @attrs = $dataset->attrGet( 'attr1', 'attr2'); ``` ### IDget Returns the HDF5 library ID for this object **Usage:** ``` my $ID = $dataSetObj->IDget; ``` ### nameGet Returns the HDF5 Dataset Name for this object. **Usage:** ``` my $name = $datasetObj->nameGet; ```