-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathhdf5doc.txt
173 lines (127 loc) · 5.9 KB
/
hdf5doc.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
/*
* hdf5doc.txt
* documentation for the yorick hdf5 plugin
*
* $Id: hdf5doc.txt,v 1.1 2007-12-27 15:10:25 frigaut Exp $
*
* Author: Francois Rigaut.
* Written 2004
* last revision/addition: 2007dec26
*
* Copyright (c) 2003, Francois RIGAUT (frigaut@gemini.edu, Gemini
* Observatory, 670 N A'Ohoku Place, HILO HI-96720).
*
* This program is free software; you can redistribute it and/or modify it
* under the terms of the GNU General Public License as published by the
* Free Software Foundation; either version 2 of the License, or (at your
* option) any later version.
*
* This program is distributed in the hope that it will be useful, but
* WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* General Public License for more details (to receive a copy of the GNU
* General Public License, write to the Free Software Foundation, Inc., 675
* Mass Ave, Cambridge, MA 02139, USA).
*
* $Log: hdf5doc.txt,v $
* Revision 1.1 2007-12-27 15:10:25 frigaut
* Initial revision
*
*/
HDF5 yorick plugin documentation
================================
********************************
******* DRAFT 2005dec11 ********
********************************
1. Overview
This plugin uses libhdf5, version 1.6.4 or greater. It will probably
work with slightly lesser version, but I haven't tested it. The
current version avilable from the NSCA site is (dec2005) is 1.6.5.
This plugin provide a minimal interface to HDF5 (Hierarchical Data
Format 5). I am not going to expand on HDF5 here. Suffice to say that
this format provides a way to store heterogeneous data in a single
file entity. The data are stored under a hierarchical directory
structure (hence the name), like:
/header
/header/date
/header/time
/header/author
/2005mar25/data/raw/time_vector
/2005mar25/data/raw/entropy
etc...
A directory (e.g. /header) is called a "Group".
A scalar/vector/array of numbers/strings is called "Dataset".
One can also set and store attribute to groups or datasets.
Here is an example of a file as dumped by the h5info function:
> h5info,"data.h5",att=1
/2005mar04 GROUP
ATTRIB(0): Temp on this date
ATTRIB(1): cups of coffee
/2005mar04/comments DATASET STRING DIMSOF()=[1,2]
/2005mar04/data DATASET DOUBLE DIMSOF()=[1,100]
/2005mar04/dewpoint DATASET DOUBLE SCALAR
/2005mar04/time DATASET DOUBLE DIMSOF()=[1,100]
ATTRIB(0): Units
ATTRIB(1): Units2
/2005mar05 GROUP
/2005mar05/name with blanks DATASET DOUBLE SCALAR
/HL HARDLINK -> /2005mar04
/bestdata SOFTLINK -> /2005mar04
>
which is, I believe, pretty much self-explanatory. Note the hardlink
and softlink references at the end (which are what they say they are:
links to other groups in this file).
2. FUNCTION API
As of v0.6, there are only a handfull of functions, but they should
provide most of the functionality to save regular datas (with the
exception of structure and pointers). These functions are:
DATA I/O:
h5read(fname,target) return data
h5write,fname,fullpath,data,zip= write data
h5open(filename,mode) return file handle
h5close(filename) close file
INFO, GROUP LINKING:
h5info,fname,target,att= print out file info/structure
h5link(fname,group,group2link2,linktype) link datasets
h5delete,fname,object delete data
ATTRIBUTE I/O:
h5awrite(fname,object,aname,attdata) write an object attribute
h5aread(fname,object,aname) read an object attribute
h5adelete,fname,object,aname delete an object attribute
MISC:
h5list_open list open files
h5version return linhdf5 version
ERROR RECOVERY
h5off close all reference to the
h5 library (clean up).
Each function is detailled below:
2.1 Data I/O:
2.1.1 h5open
fd = h5open(filename,mode);
Opens file "filename" in mode "mode".
mode can be "r" (read-only), "w" (write-only) or "a" (append).
This function returns a file descriptor fd that can be used until released by a call to h5close. fd can be used with h5read and h5open (see below).
Warning: when a file is opened with h5open, it will have to be explicitely closed with h5close. If a file is open in read-only and one try to reopen it in write-only, it will cause a error (and vice-versa)
2.1.2 h5write
h5write,filename,fullpath_to_dataset,data,zip=,mode=
write "data" as object "fullpath" in file "fname".
fname can be either a string (filename) or a file descriptor returned
by h5open.
The scalar string fullpath contains the full path to the dataset
(/full/path/dataname).
"data" are the data. Any yorick type is valid and will be saved as
such.
zip is a long 0-9. if set, data will be compressed (the larger the
number, the more compression, and the larger the compression time).
mode can be set here (when fname is a string). Use "a" it to append
data to an existing file. Default is to overwrite ("w").
2.1.3 h5read
result = h5read(filename,dataset)
return the data pointed to by the scalar string "dataset" in file
"filename".
2.1.4 h5close
h5close,file
Close all references to the file pointed at by "file". File can either
be a scalar string or a file descriptor (as the one returned by
h5open()).
to be continued...