PDL::NetCDF - Object-oriented interface between NetCDF files and PDL objects.
Perl extension to allow interface to NetCDF portable binary gridded files via PDL objects.
use PDL; use PDL::NetCDF; use PDL::Char; my $ncobj = PDL::NetCDF->new ("test.nc"); # New file my $pdl = pdl [[1, 2, 3], [4, 5, 6]]; # Specify variable name to put PDL in, plus names of the dimensions. Dimension # lengths are taken from the PDL, in this case, dim1 = 2 and dim2 = 3. $ncobj->put ('var1', ['dim1', 'dim2'], $pdl); # $pdlout = [[1, 2, 3], [4, 5, 6]] my $pdlout = $ncobj->get ('var1'); # Store textual NetCDF arrays using perl strings: (This is a bit primitive, but works) my $str = "Station1 Station2 Station3 "; $obj->puttext('textvar', ['n_station', 'n_string'], [3,10], $str); my $outstr = $obj->gettext('textvar'); # $outstr = "Station1 Station2 Station3 " # Now textual NetCDF arrays can be stored with PDL::Char style PDLs. This is much # more natural and flexible than the above method. $str = PDL::Char->new (['Station1', 'Station2', 'Station3']); $obj->put ('stations', ['dim_station', 'dim_charlen'], $str); $outstr = $obj->get('stations'); print $outstr; # Prints: ['Station1', 'Station2', 'Station3'] # For more info on PDL::Char variables see PDL::Char(3), or perldoc PDL::Char # $dim1size = 2 my $dim1size = $ncobj->dimsize('dim1'); # A slice of the netCDF variable. # [0,0] is the starting point, [1,2] is the count. # $slice = [1,2] my $slice = $ncobj->get ('var1', [0,0], [1,2]); # Attach a double attribute of size 3 to var1 $ncobj->putatt (double([1,2,3]), 'double_attribute', 'var1'); # $attr1 = [1,2,3] my $attr1 = $ncobj->getatt ('double_attribute', 'var1'); # Write a textual, global attribute. 'attr_name' is the attribute name. $ncobj->putatt ('The text of the global attribute', 'attr_name'); # $attr2 = 'The text of the global attribute' my $attr2 = $ncobj->getatt ('attr_name'); # Close the netCDF file. The file is also automatically closed in a DESTROY block # when it passes out of scope. This just makes is explicit. $ncobj->close;
For (much) more information on NetCDF, see
http://www.unidata.ucar.edu/packages/netcdf/index.html
Also see the test file, test.pl in this distribution for some working examples.
This is the PDL interface to the Unidata NetCDF library. It uses the netCDF version 3 library to make a subset of netCDF functionality available to PDL users in a clean, object-oriented interface.
Another NetCDF perl interface, which allows access to the entire range of netCDF functionality (but in a rather C-ish non-object-oriented style) is available through Unidata at http://www.unidata.ucar.edu/packages/netcdf/index.html).
The NetCDF standard allows N-dimensional binary data to be efficiently stored, annotated and exchanged between many platforms.
When one creates a new netCDF object, this object is associated with one netCDF file.
Create an object representing a netCDF file.
Arguments: 1) The name of the file. 2) (optional) An existing netCDF object for a file with identical layout. This allows one to read in many similar netCDF files without incurring the overhead of reading in all variable and dimension names and IDs each time. Caution: Undefined weirdness may occur if you pass the netCDF object from a dissimilar file!
Example:
my $nc = PDL::NetCDF->new ("file1.nc"); ... foreach my $ncfile (@a_bunch_of_similar_format_netcdf_files) { $nc = PDL::NetCDF->new("file2.nc", $nc); # These calls to 'new' are *much* faster ... }
If this file exists and you want to write to it, prepend the name with the '>' character: ">name.nc"
Returns: The netCDF object. Barfs if there is an error.
Put a PDL matrix to a netCDF variable.
Arguments:
1) The name of the variable to create
2) A reference to a list of dimension names for this variable
3) The PDL to put. It must have the same number of dimensions as specified in the dimension name list.
Returns: None.
my $pdl = pdl [[1, 2, 3], [4, 5, 6]]; # Specify variable name to put PDL in, plus names of the dimensions. Dimension # lengths are taken from the PDL, in this case, dim1 = 2 and dim2 = 3. $ncobj->put ('var1', ['dim1', 'dim2'], $pdl); # Now textual NetCDF arrays can be stored with PDL::Char style PDLs. $str = PDL::Char->new (['Station1', 'Station2', 'Station3']); $obj->put ('stations', ['dim_station', 'dim_charlen'], $str); $outstr = $obj->get('stations'); print $outstr; # Prints: ['Station1', 'Station2', 'Station3'] # For more info on PDL::Char variables see PDL::Char(3), or perldoc PDL::Char
Put a PDL matrix to a slice of a NetCDF variable
3) A reference to a list of dimensions for this variable
4) A reference to a list which specifies the N dimensional starting point of the slice.
5) A reference to a list which specifies the N dimensional count of the slice.
6) The PDL to put. It must conform to the size specified by the 4th and 5th arguments. The 2nd and 3rd argument are optional if the variable is already defined in the netcdf object.
my $pdl = pdl [[1, 2, 3], [4, 5, 6]]; # Specify variable name to put PDL in, plus names of the dimensions. Dimension # lengths are taken from the PDL, in this case, dim1 = 2 and dim2 = 3. $ncobj->putslice ('var1', ['dim1', 'dim2', 'dim3'], [2,3,3], [0,0,0], [2,3,1], $pdl); $ncobj->putslice ('var1', [], [], [0,0,2], [2,3,1], $pdl); my $pdl2 = $ncobj->get('var1'); print $pdl2; [ [ [ 1 9.96921e+36 1] [ 2 9.96921e+36 2] [ 3 9.96921e+36 3] ] [ [ 4 9.96921e+36 4] [ 5 9.96921e+36 5] [ 6 9.96921e+36 6] ] ] note that the netcdf missing value (not 0) is filled in.
Get a PDL matrix from a netCDF variable.
1) The name of the netCDF variable to fetch. If this is the only argument, then the entire variable will be returned.
To fetch a slice of the netCDF variable, optional 2nd and 3rd argments must be specified:
2) A pdl which specifies the N dimensional starting point of the slice.
3) A pdl which specifies the N dimensional count of the slice.
Returns: The PDL representing the netCDF variable. Barfs on error.
# A slice of the netCDF variable. # [0,0] is the starting point, [1,2] is the count. my $slice = $ncobj->get ('var1', [0,0], [1,2]); # If var1 contains this: [[1, 2, 3], [4, 5, 6]] # Then $slice contains: [1,2] (Size '1' dimensions are eliminated).
putatt -- Attach a numerical or textual attribute to a NetCDF variable or the entire file.
1) The attribute. Either: A one dimensional PDL (perhaps contining only one number) or a string.
2) The name to give the attribute in the netCDF file. Many attribute names have pre-defined meanings. See the netCDF documentation for more details.
3) Optionally, you may specify the name of the pre-defined netCDF variable to associate this attribute with. If this is left off, the attribute is a global one, pertaining to the entire netCDF file.
Returns: Nothing. Barfs on error.
# Attach a double attribute of size 3 to var1 $ncobj->putatt (double([1,2,3]), 'double_attribute', 'var1'); # Write a textual, global attribute. 'attr_name' is the attribute name. $ncobj->putatt ('The text of the global attribute', 'attr_name');
Get an attribute from a netCDF object.
1) The name of the attribute (a text string).
2) The name of the variable this attribute is attached to. If this argument is not specified, this function returns a global attribute of the input name.
# Get a global attribute my $attr2 = $ncobj->getatt ('attr_name'); # Get an attribute associated with the varibale 'var1' my $attr1 = $ncobj->getatt ('double_attribute', 'var1');
Put a perl text string into a multi-dimensional NetCDF array.
1) The name of the variable to be created (a text string).
2) A reference to a perl list of dimension names to use in creating this NetCDF array.
3) A reference to a perl list of dimension lengths.
4) A perl string to put into the netCDF array. If the NetCDF array is 3 x 10, then the string must have 30 charactars.
my $str = "Station1 Station2 Station3 "; $obj->puttext('textvar', ['n_station', 'n_string'], [3,10], $str);
Get a multi-dimensional NetCDF array into a perl string.
1) The name of the NetCDF variable.
my $outstr = $obj->gettext('textvar');
Get the size of a dimension from a netCDF object.
1) The name of the dimension.
Returns: The size of the dimension.
my $dim1size = $ncobj->dimsize('dim1');
Close a NetCDF object, writing out the file.
Arguments: None
Returns: Nothing
This closing of the netCDF file can be done explicitly though the 'close' method. Alternatively, a DESTROY block does an automatic close whenever the netCDF object passes out of scope.
$ncobj->close();
Get all the dimension names from an open NetCDF object. If a variable name is specified, just return dimension names for *that* variable.
Arguments: none
Returns: An array reference of dimension names
my $varlist = $ncobj->getdimensionnames(); foreach(@$varlist){ print "Found dim $_\n"; }
Get the attribute names for a given variable from an open NetCDF object.
Arguments: Optional variable name, with no arguments it will return the objects global netcdf attributes.
Returns: An array reference of attribute names
my $attlist = $ncobj->getattributenames('var1');
Get all the variable names for an open NetCDF object.
Arguments: none.
Returns: An array reference of variable names
my $varlist = $ncobj->getvariablenames();
Doug Hunt, dhunt\@ucar.edu.
perl(1), PDL(1), netcdf(3).
To install PDL::NetCDF, copy and paste the appropriate command in to your terminal.
cpanm
cpanm PDL::NetCDF
CPAN shell
perl -MCPAN -e shell install PDL::NetCDF
For more information on module installation, please visit the detailed CPAN module installation guide.