Add Python examples (#4546)

These examples are referred to from the replacement page of https://portal.hdfgroup.org/display/HDF5/Other+Examples.

HDF5Examples/PYTHON/h5_compound.py

@@ -0,0 +1,33 @@
+#
+# This example creates an HDF5 file compound.h5 and an empty datasets /DSC in it.
+#
+import h5py
+import numpy as np
+#
+# Create a new file using default properties.
+#
+file = h5py.File('compound.h5','w')
+#
+# Create a dataset under the Root group.
+#
+comp_type = np.dtype([('Orbit', 'i'), ('Location', np.str_, 6), ('Temperature (F)', 'f8'), ('Pressure (inHg)', 'f8')])
+dataset = file.create_dataset("DSC",(4,), comp_type)
+data = np.array([(1153, "Sun   ", 53.23, 24.57), (1184, "Moon  ", 55.12, 22.95), (1027, "Venus ", 103.55, 31.23), (1313, "Mars  ", 1252.89, 84.11)], dtype = comp_type)
+dataset[...] = data
+#
+# Close the file before exiting
+#
+file.close()
+file = h5py.File('compound.h5', 'r')
+dataset = file["DSC"]
+print("Reading Orbit and Location fields...")
+orbit = dataset['Orbit']
+print("Orbit: ", orbit)
+location = dataset['Location']
+print("Location: ", location)
+data = dataset[...]
+print("Reading all records:")
+print(data)
+print("Second element of the third record:", dataset[2, 'Location'])
+file.close()
+

HDF5Examples/PYTHON/h5_crtdat.py

@@ -0,0 +1,22 @@
+#
+# This examaple creates an HDF5 file dset.h5 and an empty datasets /dset in it.
+#
+import h5py
+#
+# Create a new file using default properties.
+#
+file = h5py.File('dset.h5','w')
+#
+# Create a dataset under the Root group.
+#
+dataset = file.create_dataset("dset",(4, 6), h5py.h5t.STD_I32BE)
+print("Dataset dataspace is", dataset.shape)
+print("Dataset Numpy datatype is", dataset.dtype)
+print("Dataset name is", dataset.name)
+print("Dataset is a member of the group", dataset.parent)
+print("Dataset was created in the file", dataset.file)
+#
+# Close the file before exiting
+#
+file.close()
+

HDF5Examples/PYTHON/h5_gzip.py

@@ -0,0 +1,37 @@
+#
+# This example creates and writes GZIP compressed dataset.
+#
+import h5py
+import numpy as np
+#
+# Create  gzip.h5 file.
+#
+file = h5py.File('gzip.h5','w')
+#
+# Create /DS1 dataset; in order to use compression, dataset has to be chunked.
+#
+dataset = file.create_dataset('DS1',(32,64),'i',chunks=(4,8),compression='gzip',compression_opts=9) 
+#
+# Initialize data.
+#
+data = np.zeros((32,64))
+for i in range(32):
+    for j in range(64):
+        data[i][j]= i*j-j	 
+#
+# Write data.
+#
+print("Writing data...")
+dataset[...] = data
+file.close()
+#
+# Read data back; display compression properties and dataset max value. 
+#
+file = h5py.File('gzip.h5','r')
+dataset = file['DS1']
+print("Compression method is", dataset.compression)
+print("Compression parameter is", dataset.compression_opts)
+data = dataset[...]
+print("Maximum value in", dataset.name, "is:", max(data.ravel()))
+file.close()
+

HDF5Examples/PYTHON/h5_hype.py

@@ -0,0 +1,54 @@
+#
+# This example shows how to write a hyperslab to an existing dataset.
+#
+import h5py
+import numpy as np
+#
+# Create a file using default properties.
+#
+file = h5py.File('hype.h5','w')
+#
+# Create "IntArray" dataset.
+#
+dim0 = 8
+dim1 = 10
+dataset = file.create_dataset("IntArray", (dim0,dim1), "i")
+#
+# Initialize data object with 0.
+#
+data = np.zeros((dim0, dim1))
+#
+# Initialize data for writing.
+#
+for i in range(dim0):
+    for j in range(dim1):
+        if j < dim1/2: 
+            data[i][j]= 1
+        else:
+            data[i][j] = 2 	 
+#
+# Write data
+#
+dataset[...] = data
+print("Data written to file:")
+print(dataset[...])
+#
+# Close the file before exiting
+#
+file.close()
+#
+# Open the file and dataset.
+#
+file = h5py.File('hype.h5','r+')
+dataset = file['IntArray']
+#
+# Write a selection.
+#
+dataset[1:4, 2:6] = 5
+print("Data after selection is written:")
+print(dataset[...])
+#
+# Close the file before exiting
+#
+file.close()
+

HDF5Examples/PYTHON/h5_hypeb.py

@@ -0,0 +1,31 @@
+#
+# This example shows how to read a hyperslab from an existing dataset.
+#
+import h5py
+import numpy as np
+#
+# Open file and read dataset.
+#
+file = h5py.File('hype.h5', 'r')
+dataset = file['IntArray']
+data_in_file = dataset[...]
+print("Data in file ...")
+print(data_in_file[...])
+#
+# Initialize data with 0s.
+#
+data_selected = np.zeros((8,10), dtype=np.int32)
+#
+# Read selection.
+#
+space_id = dataset.id.get_space()
+space_id.select_hyperslab((1,1), (2,2), stride=(4,4), block=(2,2))
+#---> Doesn't work dataset.id.read(space_id, space_id, data_selected, h5py.h5t.STD_I32LE) 
+dataset.id.read(space_id, space_id, data_selected) 
+print("Selected data read from file....")
+print(data_selected[...])
+#
+# Close the file before exiting
+#
+file.close()
+

HDF5Examples/PYTHON/h5_links.py

@@ -0,0 +1,71 @@
+#
+# This example demonstrates the concepts of hard, soft and external links.
+#
+# We will create file links.h5 with the following members and then will try to access objects
+# using hard, soft and external links.
+# /                        Group
+# /A                       Group
+# /A/a                     Dataset {10}
+# /B                       Group
+# /B/External              External Link {dset.h5//dset}
+# /a                       Dataset, same as /A/a
+# /dangling                Soft Link {/B/XXX}
+# /soft                    Soft Link {/A/a}
+
+import h5py
+import numpy as np
+file = h5py.File('links.h5', 'w')
+#
+# Create a group structure in the file
+#
+A = file.create_group("A")
+B = file.create_group("B")
+a = A.create_dataset("a", (10,), 'i')
+#
+# Create a hard link in a root group pointing to dataset  /A/a
+#
+file["a"] = a
+#
+# Create a soft link (alias) in a root group with a value  /A/a
+#
+file["soft"] = h5py.SoftLink('/A/a')
+#
+# Create a soft link (alias) in a root group with a value /B/XXX that cannot be resolved
+#
+file["dangling"] = h5py.SoftLink('/B/XXX')
+#
+# Create an external link to a dataset "dset" in file dset.h5
+#
+B['External'] = h5py.ExternalLink("dset.h5", "/dset")
+#
+# List objects in the root group in the file
+#
+print("Root group members in links.h5:")
+try:
+        print("Trying to get the items...")
+        print(list(file.items()))
+except:
+        print("...but can only get the keys...")
+        print(list(file.keys()))
+        print("          ")
+        print("Why? Because the library cannot resolve the dangling link.")
+        print("We will delete the 'dangling' link and try again.")
+        del file["dangling"]
+print(list(file.items()))
+print("          ")
+print("Group A members:")
+print(list(A.items()))
+print("          ")
+print("Group B members:")
+print(list(B.items()))
+print("          ")
+print("Reading dataset pointed by the external link...")
+dset = B['External']
+data = np.zeros((4,6))
+data = dset[...]
+print(data)
+#
+# Copy link to /A/a to /B/b
+#
+B["b"]=A["a"]
+file.close()

HDF5Examples/PYTHON/h5_objref.py

@@ -0,0 +1,37 @@
+#
+# This example shows how to create dataset with object references
+#
+import h5py
+import numpy as np
+#
+# Create a new file using default properties.
+#
+file = h5py.File('objref.h5','w')
+#
+# Create a group and scalar datasets under the Root group.
+#
+group = file.create_group("G1")
+dataset = file.create_dataset("DS2",(), 'i')
+#
+# Create references to the group and the dataset and store them in another dataset.
+#
+refs = (group.ref, dataset.ref)
+ref_type = h5py.h5t.special_dtype(ref=h5py.Reference)
+dataset_ref = file.create_dataset("DS1", (2,),ref_type)
+dataset_ref[...] = refs
+
+#
+# Close the file before exiting
+#
+file.close()
+
+file = h5py.File('objref.h5','r')
+dataset_ref = file["DS1"]
+refs = dataset_ref[...]
+refs_list = list(refs)
+for obj in refs_list:
+    index = refs_list.index(obj)
+    print("DS["+str(index)+"]:")
+    print(file[obj])
+file.close()
+

HDF5Examples/PYTHON/h5_readtofloat.py

@@ -0,0 +1,31 @@
+#
+# This example reads integer data from dset.h5 file into Python floatng buffers.
+#
+import h5py
+import numpy as np
+#
+# Open an existing file using default properties.
+#
+file = h5py.File('dset.h5','r+')
+#
+# Open "dset" dataset under the root group.
+#
+dataset = file['/dset']
+#
+# Initialize buffers,read and print data.
+#
+# Python float type is 64-bit, one needs to use NATIVE_DOUBLE HDF5 type to read data. 
+data_read64 = np.zeros((4,6,), dtype=float)
+dataset.id.read(h5py.h5s.ALL, h5py.h5s.ALL, data_read64, mtype=h5py.h5t.NATIVE_DOUBLE)
+print("Printing data 64-bit floating numbers...")
+print(data_read64)
+
+data_read32 = np.zeros((4,6,), dtype=np.float32)
+dataset.id.read(h5py.h5s.ALL, h5py.h5s.ALL, data_read32, mtype=h5py.h5t.NATIVE_FLOAT)
+print("Printing data 32-bit floating numbers...")
+print(data_read32)
+#
+# Close the file before exiting
+#
+file.close()
+

HDF5Examples/PYTHON/h5_regref.py

@@ -0,0 +1,52 @@
+#
+# This example shows how to create a dataset with region references.
+#
+import h5py
+import numpy as np
+#
+# Create a new file using default properties.
+#
+file = h5py.File('regref.h5','w')
+#
+# Create a group and (3x2) dataset under the Root group.
+#
+dataset = file.create_dataset("DS2",(3,2), h5py.h5t.STD_I8LE)
+dataset[...] = np.array([[1,1], [2,2], [3,3]])
+#
+# Create references to each row in the dataset.
+#
+refs = (dataset.regionref[0,:],dataset.regionref[1,:],dataset.regionref[2,:])
+#
+# Create a dataset to store region references.
+#
+ref_type = h5py.h5t.special_dtype(ref=h5py.RegionReference)
+dataset_ref = file.create_dataset("DS1", (3,),ref_type)
+dataset_ref[...] = refs
+#
+# Close the file before exiting.
+#
+file.close()
+#
+# Open the file, read the second element of the dataset with the region references
+# and dereference it to get data.
+#
+file = h5py.File('regref.h5', 'r')
+dataset = file["DS1"]
+regref = dataset[1]
+#
+# Region reference can be used to find a dataset it points to.
+#
+dataset_name = file[regref].name
+print(dataset_name)
+#
+# Get hyperslab the reference points to.
+#
+data = file[dataset_name]
+#
+# Region reference can be used as a slicing argument!
+print(data[regref])
+file.close()
+
+
+
+

HDF5Examples/PYTHON/h5_selecelem.py

@@ -0,0 +1,44 @@
+#
+# This example demonstrates how to do point selection in Python.
+#
+import h5py
+import numpy as np
+file1 = h5py.File('copy1.h5','w')
+file2 = h5py.File('copy2.h5','w')
+dataset1 = file1.create_dataset('Copy1', (3,4), 'i')
+dataset2 = file2.create_dataset('Copy2', (3,4), 'i')
+#
+# Initialize data object with 0.
+#
+data1 = np.zeros((3,4))
+data2 = np.ones((3,4))
+val = (55,59)
+#
+# Write data
+#
+dataset1[...] = data1
+dataset2[...] = data2
+#
+# Modify two elements with the new values. We can choose any number of elements along one dimension.
+#
+dataset1[0, [1,3]] = val
+dataset2[0, [1,3]] = val
+file1.close()
+file2.close()
+#
+# Reopen the files  and read data back
+#
+file1 = h5py.File('copy1.h5', 'r')
+dataset1 = file1['Copy1']
+data1 = dataset1[...]
+print "Dataset Copy1 in copy1.h5:"
+print data1
+
+file2 = h5py.File('copy2.h5', 'r')
+dataset2 = file2['Copy2']
+data2 = dataset2[...]
+print "Dataset Copy2 in copy2.h5:"
+print data2
+
+file1.close()
+file2.close()

HDF5Examples/PYTHON/h5_string.py

@@ -0,0 +1,29 @@
+#
+# This example creates an HDF5 file string.h5 and DSfixed dataset in it.
+# Then it opens the file and reads data back.
+#
+import h5py
+import numpy as np
+#
+# Create a new file using default properties.
+#
+file = h5py.File('string.h5','w')
+#
+# Create a dataset under the Root group using variable-length string type.
+#
+
+fixed_string = np.dtype('a10')
+dataset = file.create_dataset("DSfixed",(4,), dtype=fixed_string)
+data = ("Parting   ", ".is such  ", ".sweet    ", ".sorrow...")
+dataset[...] = data
+#
+# Close the file before exiting
+#
+file.close()
+file = h5py.File('string.h5', 'r')
+dataset = file['DSfixed']
+data_out = dataset[...]
+for i in range(4):	
+    print("DSfixed[i] = ",data_out[i])
+
+file.close()

HDF5Examples/PYTHON/h5_unlim.py

@@ -0,0 +1,46 @@
+#
+# This example creates a dataset and then extends it by rows and then by columns.
+#
+import h5py
+import numpy as np
+#
+# Create  unlim.h5 file.
+#
+file = h5py.File('unlim.h5','w')
+#
+# Create /DS1 dataset; in order to use compression, dataset has to be chunked.
+#
+dataset = file.create_dataset('DS1',(4,7),'i',chunks=(3,3), maxshape=(None, None)) 
+#
+# Initialize data.
+#
+data = np.zeros((4,7))
+#
+# Write data.
+#
+print("Writing data...")
+dataset[...] = data
+file.close()
+#
+# Read data back; display compression properties and dataset max value. 
+#
+file = h5py.File('unlim.h5','r+')
+dataset = file['DS1']
+data = dataset[...]
+print("Data before extension: ")
+print(data)
+#
+# Add two rows filled with 1
+#
+dataset.resize((6,7))
+dataset[4:6] = 1
+#
+# Add three columns filled with 2 
+#
+dataset.resize((6,10))
+dataset[:,7:10] = 2 
+data = dataset[...]
+print("Data after extension: ")
+print(data)
+file.close()
+

HDF5Examples/PYTHON/h5_visit.py

@@ -0,0 +1,9 @@
+import h5py
+f = h5py.File('GATMO-SATMS-npp.h5', 'r+')
+list(f.keys())
+list(f.values())
+members = []
+f.visit(members.append)
+for i in range(len(members)):
+    print(members[i])
+

HDF5Examples/PYTHON/h5_visita.py

@@ -0,0 +1,9 @@
+import h5py
+def print_info(name, obj):
+    print(name) 
+    for name, value in obj.attrs.items():
+        print(name+":", value)
+	
+f = h5py.File('GATMO-SATMS-npp.h5', 'r+')
+f.visititems(print_info)
+f.close()

HDF5Examples/PYTHON/h5_vlstring.py

@@ -0,0 +1,28 @@
+#
+# This example creates an HDF5 file vlstring.h5 and DSvariable dataset in it.
+# Then it opens the file and reads data back.
+#
+import h5py
+#
+# Create a new file using default properties.
+#
+file = h5py.File('vlstring.h5','w')
+#
+# Create a dataset under the Root group using variable-length string type.
+#
+str_type = h5py.new_vlen(str)
+dataset = file.create_dataset("DSvariable",(4,), dtype=str_type)
+data = ("Parting", " is such", " sweet", " sorrow...")
+dataset[...] = data
+#
+# Close the file before exiting
+#
+file.close()
+file = h5py.File('vlstring.h5', 'r')
+dataset = file['DSvariable']
+data_out = dataset[...]
+for i in range(4):	
+    print("DSvariable[",i,"]", "'"+data_out[i]+"'", "has length", len(data_out[i]))
+
+print(data_out)
+file.close()

doxygen/aliases

@@ -252,7 +252,7 @@ ALIASES += sa_metadata_ops="\sa \li H5Pget_all_coll_metadata_ops() \li H5Pget_co
 ALIASES += ref_cons_semantics="<a href=\"https://\RFCURL/RFC%20PHDF5%20Consistency%20Semantics%20MC%20120328.docx.pdf\">Enabling a Strict Consistency Semantics Model in Parallel HDF5</a>"
 ALIASES += ref_file_image_ops="<a href=\"https://\RFCURL/HDF5FileImageOperations.pdf\">HDF5 File Image Operations</a>"
 ALIASES += ref_filter_pipe="<a href=\"https://\DSPURL/HDF5+Data+Flow+Pipeline+for+H5Dread\">Data Flow Pipeline for H5Dread()</a>"
-ALIASES += ref_group_impls="<a href=\"\DOXURL/group___h5_g.html\">Group implementations in HDF5</a>"
+ALIASES += ref_group_impls="<a href=\"https://\DOXURL/group___h5_g.html\">Group implementations in HDF5</a>"
 ALIASES += ref_h5lib_relver="<a href=\"https://\ARCURL/TechNotes/Version.html\">HDF5 Library Release Version Numbers</a>"
 ALIASES += ref_mdc_in_hdf5="<a href=\"https://\DSPURL/Metadata+Caching+in+HDF5\">Metadata Caching in HDF5</a>"
 ALIASES += ref_mdc_logging="<a href=\"https://\DSPURL/H5F_START_MDC_LOGGING\">Metadata Cache Logging</a>"