2
PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
4
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
5
<title>PyTables User's Guide</title><meta http-equiv="Content-Type" content="text/html"><link rel="schema.DC" href="http://purl.org/dc/elements/1.1/"><meta name="generator" content="The tbook system at http://tbookdtd.sourceforge.net"><meta name="robots" content="index"><meta name="DC.Title" content="PyTables User's Guide"><meta name="DC.Description" content="PyTables User's Guide Hierarchical datasets in Python Release 0.9.1"><meta name="DC.Creator" content="Francesc Altet"><meta name="Author" content="Francesc Altet"><meta name="DC.Creator" content="Scott Prater"><meta name="Author" content="Scott Prater"><meta name="DC.Creator" content="Ivan Vilata"><meta name="Author" content="Ivan Vilata"><meta name="DC.Creator" content="Tom Hedley"><meta name="Author" content="Tom Hedley"><meta name="DC.Date" content="2004-12-02T12:15:05+01:00"><meta name="Date" content="2004-12-02T12:15:05+01:00"><meta name="DC.Rights" content="(c) 2002, 2003, 2004 Francesc Altet"><meta name="Copyright" content="(c) 2002, 2003, 2004 Francesc Altet"><meta name="DC.Type" content="Text"><meta name="DC.Format" content="text/html"><meta name="DC.Language" scheme="rfc3066" content="en"><meta name="Language" content="en"><meta http-equiv="Content-Style-Type" content="text/css"><style type="text/css">
7
font-family: serif; text-align: justify;
8
margin: 0pt; line-height: 1.3; background-color: white; color: black }
9
body.letter { background-image: none }
10
h1, h2, h3, h4, h5, h6, div.partheadline, div.title,
12
font-family: sans-serif; font-weight: bold; font-stretch: condensed;
14
h1, h2, h3, h4, h5, h6, div.partheadline { padding-left: 18pt }
16
h1.toc { clear: none }
17
a:link, a:visited, a:active { text-decoration: none }
18
a:hover[href] { text-decoration: underline; color: #0066FF; }
19
div.document, div.letter { margin-left: 80px; margin-right: 150px;
20
padding-top: 3ex; padding-bottom: 5ex }
21
div.authorlist { font-family: sans-serif;
22
font-stretch: condensed; text-align: left; font-size: x-large;
24
div.authorlist-article { font-size: x-large; text-align: center;
26
div.title { font-size: xx-large; color: gray; margin-bottom: 5ex; }
27
div.title-article { font-size: xx-large; text-align: center;
29
div.date-article { font-size: large; text-align: center;
31
div.subtitle { text-align: left; margin-bottom: 3ex }
32
div.legal { text-align: right }
33
div.legalnotice { margin-top: 3ex; text-align: left }
34
div.partheadline { font-size: xx-large; margin-top: 1ex; margin-bottom: 1ex }
36
hr.footnoterule { text-align: left; width: 40%; margin-right: 60%; color: black }
37
div.mathdisplay { text-align: center;
38
margin-top: 2ex; margin-bottom: 2ex }
39
div.figure, div.table, div.mathml-remark { margin-bottom: 3ex;
41
div.mathml-remark { width: 50%; text-align: left; text-indent: 0pt }
42
div.caption { margin-top: 1ex; width: 20em}
43
div.caption-text { font-size: small;
44
padding-left: 1em; text-indent: -1em; text-align: left}
45
caption { max-width: 100%; min-width: 200px; margin-bottom: 1ex;
47
div.verse { white-space: pre; margin-left: 2em;
48
margin-top: 2ex; margin-bottom: 2ex }
49
div.toc { margin-bottom: 6ex }
51
div.index { width: 100% }
52
div.aphorism { margin-bottom: 2ex; font-style: italic; text-align: right;
54
div.aphorism-origin { margin-top: 1ex }
56
div.subject { margin-top: 3ex; margin-bottom: 3ex }
57
div.opening { margin-top: 3ex; margin-bottom: 3ex }
58
div.closing { margin-top: 3ex; text-align: right }
59
div.to { margin-top: 3ex; margin-bottom: 3ex }
60
span.subject { font-weight: bold }
61
div.speedbar-top, div.speedbar-bottom { margin-left: 1em; margin-right: 1em }
62
div.speedbar-top { margin-top: 2ex }
63
div.speedbar-bottom { margin-bottom: 3ex }
64
table.speedbar { width: 100% }
65
hr.speedbar { clear: both }
66
div.theorem-plain, div.theorem-definition, div.theorem-remark { margin-top: 2ex;
68
div.theorem-plain { font-style: italic }
69
div.proof { margin-top: 2ex; margin-bottom: 2ex }
70
span.theorem-head-plain, span.theorem-head-definition, span.theorem-head-remark
71
{ margin-right: 0.66em }
72
span.theorem-head-plain, span.theorem-head-definition
73
{ font-style: normal; font-weight: bold }
74
span.theorem-head-remark { font-style: italic }
75
span.proof-head { font-style: italic; margin-right: 0.66em }
76
acronym { font-size: 95%; letter-spacing: 0.1em; text-transform: uppercase }
77
td.header { text-align: center; font-weight: bold }
79
table.tabular { font-size: smaller }
80
td.thickline { height: 0pt; border-bottom: medium solid; padding: 2px }
81
td.thinline { height: 0pt; border-bottom: thin solid; padding: 2px }
82
/* FixMe: Following definition Still bad */
83
div.part-toc { margin-top: 2ex; font-weight: bold; font-size: larger }
84
/* FixMe: Following definition: How cleaner? */
85
div.toplevel-toc { margin-top: 1ex; font-weight: bold }
86
td.number1 { width: 1.5em }
87
td.number2 { width: 2em }
88
td.number3 { width: 3em }
89
td.author { text-align: center; width: 50% }
90
div { } /* Must remain empty! */
91
span.captionlabel { font-family: sans-serif; font-weight: bold;
92
margin-right: 0.66em }
93
span.captionlabel:after { content: " " }
95
b.captionlabel:after { content: " " }
96
span.headlinenumber { margin-right: 0.66em }
97
tt.verb {font-family: monospace }
98
span.bibtag { font-weight: bold; margin-right: 1em }
100
span.bib-lastname { font-variant: small-caps }
101
span.bib-title { font-style: italic }
102
span.bib-booktitle { }
104
span.bib-journal-volume { font-weight: bold }
105
span.bib-publisher { }
109
span { } /* Muss leer bleiben! */
110
li.bibitem { margin-left: 1em; text-indent: -1em }
111
img.graphics { border: 0pt }
112
p,div.p { margin: 0pt; text-indent: 18pt }
113
ul, dl, ol { text-indent: 0pt; }
114
p.first, div.p-first { margin: 0pt; text-indent: 0pt }
115
p.bibitem { margin-top: 1.5ex; margin-left: 3em; text-indent: -3em }
116
ul.biblio { list-style: none }
117
mi.ch { font-style: normal }
118
math[display="block"], div.equation {
119
margin-top: 1ex; margin-bottom: 1ex }
120
div.i-lettergroup { font-size: larger; font-weight: bold; padding-left: 18pt;
121
margin-top: 3ex; margin-bottom: 1.5ex }
124
dt { display: compact; font-weight: bold }
125
dd { text-indent: 0pt }
126
pre { text-indent: 0pt }
127
span.i-see { font-style: italic; }
133
body { /* background-image: url("tile.jpg"); */ /* Per a imprimir millor */
134
font: 14px/1.5 Verdana, Arial, Helvetica, sans-serif;
140
/* body { background-image: url("tile.jpg");
141
background-color: white;
143
font-size: 13pt; } */
144
hr.footnoterule { color: white }
145
div.title { font-size: x-large; color: maroon }
146
div.subtitle { font-size: x-large; color: olive }
147
div.title-article { font-size: x-large }
148
div.partheadline { font-size: x-large }
149
</style></head><body><div class="speedbar-top"><table class="speedbar"><tbody><tr><td style="text-align: left; width: 15%"><a href="usersguide8.html">previous</a></td><td style="text-align: center"><a href="usersguide.html#tb:table-of-contents">Table of Contents</a></td><td style="text-align: right; width: 15%"><a href="usersguide10.html">next</a></td></tr><tr><td class="header" colspan="3">Appendix</td></tr></tbody></table><hr class="speedbar"></div><div class="document"><div id="PyTablesInternalFormat"><a name="PyTablesInternalFormat"></a>
150
<h1 id="chapterC"><a name="chapterC"></a>Appendix C: <tt>PyTables</tt> File
153
<p class="first"><tt class="verb">PyTables</tt> has a powerful capability to deal
154
with native HDF5 files created with another tools. However,
155
there are situations were you may want to create truly
156
native <tt class="verb">PyTables</tt> files with those tools while
157
retaining fully compatibility with <tt class="verb">PyTables</tt>
158
format. That is perfectly possible, and in this appendix is
159
presented the format that you should endow to your
160
own-generated files in order to get a fully
161
<tt class="verb">PyTables</tt> compatible file.
164
<p>We are going to describe the <b>1.3
165
version of <tt class="verb">PyTables</tt> file format</b>
166
(introduced in <tt class="verb">PyTables</tt> version 0.9). At this
167
stage, this file format is considered stable enough to do
168
not introduce significant changes during a reasonable amount
169
of time. As time goes by, some changes will be introduced
170
(and documented here) in order to cope with new
171
necessities. However, the changes will be carefully analyzed
172
so as to ensure backward compatibility whenever is possible.
175
<p>A <tt class="verb">PyTables</tt> file is composed with arbitrarily
176
large amounts of HDF5 groups (<tt class="verb">Groups</tt> in
177
<tt class="verb">PyTables</tt> naming scheme) and datasets
178
(<tt class="verb">Leaves</tt> in <tt class="verb">PyTables</tt> naming
179
scheme). For groups, the only requirements are that they
180
must have some <em>system attributes</em> available. By
181
convention, system attributes in <tt class="verb">PyTables</tt> are
182
written in upper case, and user attributes in lower case but
183
this is not enforced by the software. In the case of
184
datasets, besides the mandatory system attributes, some
185
conditions are further needed in their storage layout, as
186
well as in the datatypes used in there, as we will see
190
<p>As a final remark, you can use any filter as you want to
191
create a <tt class="verb">PyTables</tt> file, provided that the
192
filter is a standard one in HDF5, like <em>zlib</em>,
193
<em>shuffle</em> or <em>szip</em> (although the last one
194
cannot be used from within <tt class="verb">PyTables</tt> to create a
195
new file, datasets compressed with szip can be read, because
196
it is the HDF5 library which do the decompression
201
<h2 id="sectionC.1"><span class="headlinenumber"><a name="sectionC.1"></a>C.1 </span>Mandatory attributes for a <tt>File</tt></h2>
203
<p class="first">The <tt class="verb">File</tt> object is, in fact, an special HDF5
204
<em>group</em> structure that is <em>root</em> for the
205
rest of the objects on the object tree. The next
206
attributes are mandatory for the HDF5 <em>root group</em>
207
structure in <tt class="verb">PyTables</tt> files:
211
<dt>CLASS</dt> <dd>This attribute should always be
212
set to <tt class="verb">'GROUP'</tt> for group structures.</dd>
213
<dt>PYTABLES_FORMAT_VERSION</dt> <dd>It represents
214
the internal format version, and currently should be set
215
to the <tt class="verb">'1.2'</tt> string.</dd>
216
<dt>TITLE</dt> <dd>A string where the user can put
217
some description on what is this group used for. </dd>
218
<dt>VERSION</dt> <dd>Should contains the string
219
<tt class="verb">'1.0'</tt>.</dd>
224
<h2 id="sectionC.2"><span class="headlinenumber"><a name="sectionC.2"></a>C.2 </span>Mandatory attributes for a <tt>Group</tt></h2>
226
<p class="first">The next attributes are mandatory for <em>group</em>
231
<dt>CLASS</dt> <dd>This attribute should always be
232
set to <tt class="verb">'GROUP'</tt> for group structures.</dd>
233
<dt>TITLE</dt> <dd>A string where the user can put
234
some description on what is this group used for. </dd>
235
<dt>VERSION</dt> <dd>Should contains the string
236
<tt class="verb">'1.0'</tt>.</dd>
239
<p>There exist a special <tt class="verb">Group</tt>, called the
240
<em>root</em>, that, in addition to the attributes listed
241
above, it requires the next one:
245
<dt>PYTABLES_FORMAT_VERSION</dt> <dd>It represents
246
the internal format version, and currently should be set
247
to the <tt class="verb">'1.3'</tt> string.</dd>
253
<h2 id="sectionC.3"><span class="headlinenumber"><a name="sectionC.3"></a>C.3 </span>Mandatory attributes, storage layout and supported
254
datatypes for <tt>Leaves</tt>
257
<p class="first">This depends on the kind of <tt class="verb">Leaf</tt>. The
258
format for each type follows.
261
<div id="TableFormatDescr"><a name="TableFormatDescr"></a>
262
<h3 id="subsectionC.3.1"><span class="headlinenumber"><a name="subsectionC.3.1"></a>C.3.1 </span><tt>Table</tt>
266
<h4 id="subsubsectionC.3.1.1">Mandatory attributes</h4>
268
<p class="first">The next attributes are mandatory for <em>table</em>
273
<dt>CLASS</dt> <dd>Must be set to
274
<tt class="verb">'TABLE'</tt>.</dd>
276
<dt>TITLE</dt> <dd>A string where the user can
277
put some description on what is this dataset used
280
<dt>VERSION</dt> <dd>Should contain the string
281
<tt class="verb">'2.2'</tt>.</dd>
283
<dt>FIELD_X_NAME</dt> <dd>It contains the names
284
of the different fields. The <tt class="verb">X</tt> means
285
the number of the field (beware, order do
286
matter). You should add as many attributes of this
287
kind as fields you have in your records.
290
<dt>NROWS</dt> <dd>This should contain the
291
number of <em>compound</em> datatype entries in the
292
dataset. It must be an <em>int</em> datatype.</dd>
298
<h4 id="subsubsectionC.3.1.2">Storage Layout</h4>
300
<p class="first">A <tt class="verb">Table</tt> has a <em>dataspace</em> with a
301
<em>1-dimensional chunked</em> layout.
306
<h4 id="subsubsectionC.3.1.3">Datatypes supported</h4>
308
<p class="first">The datatype of the elements (rows) of
309
<tt class="verb">Table</tt> must be the H5T_COMPOUND
310
<em>compound</em> datatype, and each of these compound
311
components must be built with only the next HDF5
312
datatypes <em>classes</em>:
316
<dt>H5T_BITFIELD</dt> <dd>This class is used to
317
represent the <tt class="verb">Bool</tt> type. Such a type
318
must be build using a H5T_NATIVE_B8 datatype,
319
followed by a HDF5 <tt class="verb">H5Tset_precision</tt>
320
call to set its precision to be just 1 bit.
322
<dt>H5T_INTEGER</dt> <dd>This includes the next
325
<dt>H5T_NATIVE_SCHAR</dt> <dd>This
326
represents a <em>signed char</em> C type, but it
327
is effectively used to represent an
328
<tt class="verb">Int8</tt> type.
330
<dt>H5T_NATIVE_UCHAR</dt> <dd>This
331
represents an <em>unsigned char</em> C type, but
332
it is effectively used to represent an
333
<tt class="verb">UInt8</tt> type.
335
<dt>H5T_NATIVE_SHORT</dt> <dd>This
336
represents a <em>short</em> C type, and
337
it is effectively used to represent an
338
<tt class="verb">Int16</tt> type.
340
<dt>H5T_NATIVE_USHORT</dt> <dd>This
341
represents an <em>unsigned short</em> C type, and
342
it is effectively used to represent an
343
<tt class="verb">UInt16</tt> type.
345
<dt>H5T_NATIVE_INT</dt> <dd>This represents
346
an <em>int</em> C type, and it is effectively
347
used to represent an <tt class="verb">Int32</tt> type.
349
<dt>H5T_NATIVE_UINT</dt> <dd>This
350
represents an <em>unsigned int</em> C type, and
351
it is effectively used to represent an
352
<tt class="verb">UInt32</tt> type.
354
<dt>H5T_NATIVE_LONG</dt> <dd>This represents
355
a <em>long</em> C type, and it is effectively
356
used to represent an <tt class="verb">Int32</tt> or an
357
<tt class="verb">Int64</tt>, depending on whether you are
358
running a 32-bit or 64-bit architecture.
360
<dt>H5T_NATIVE_ULONG</dt> <dd>This
361
represents an <em>unsigned long</em> C type, and
362
it is effectively used to represent an
363
<tt class="verb">UInt32</tt> or an <tt class="verb">UInt64</tt>,
364
depending on whether you are running a 32-bit or
367
<dt>H5T_NATIVE_LLONG</dt> <dd>This
368
represents a <em>long long</em> C type
369
(<tt class="verb">__int64</tt>, if you are using a
370
Windows system) and it is effectively
371
used to represent an <tt class="verb">Int64</tt> type.
373
<dt>H5T_NATIVE_ULLONG</dt> <dd>This
374
represents an <em>unsigned long long</em> C type
375
(beware: this type does not have a
376
correspondence on Windows systems) and it is
377
effectively used to represent an
378
<tt class="verb">UInt64</tt> type.
382
<dt>H5T_FLOAT</dt> <dd>This includes the next
385
<dt>H5T_NATIVE_FLOAT</dt> <dd>This
386
represents a <em>float</em> C type and it is
387
effectively used to represent an
388
<tt class="verb">Float32</tt> type.
390
<dt>H5T_NATIVE_DOUBLE</dt> <dd>This
391
represents a <em>double</em> C type and it is
392
effectively used to represent an
393
<tt class="verb">Float64</tt> type.
397
<dt>H5T_STRING</dt> <dd>The datatype used to
398
describe strings in PyTables is H5T_C_S1 (i.e. a
399
<em>string</em> C type) followed with a call to the
400
HDF5 <tt class="verb">H5Tset_size()</tt> function to set
403
<dt>H5T_ARRAY</dt> <dd>This allows the
404
construction of homogeneous, multi-dimensional
405
arrays, so that you can include such objects in
406
compound records. The types supported as elements of
407
H5T_ARRAY datatypes are the ones described
408
above. Currently, <tt class="verb">PyTables</tt> does not
409
support nested H5T_ARRAY types.
411
<dt>H5T_COMPOUND</dt> <dd>This allows the
412
support of complex numbers. Its format is described
415
The H5T_COMPOUND type class contains two
416
members. Both members must have the H5T_FLOAT
417
atomic datatype class. The name of the first
418
member should be "r" and represents the real
419
part. The name of the second member should be "i"
420
and represents the imaginary part. The
421
<em>precision</em> property of both of the
422
H5T_FLOAT members must be either 32 significant
423
bits (e.g. H5T_NATIVE_FLOAT) or 64 significant
424
bits (e.g. H5T_NATIVE_DOUBLE). They represent
425
Complex32 and Complex64 types respectively.
430
<p>Currently, <tt class="verb">PyTables</tt> does not support
431
nested H5T_COMPOUND types, the only exception being
432
supporting complex numbers in <tt class="verb">Table</tt>
433
objects as described above.
440
<div id="ArrayFormatDescr"><a name="ArrayFormatDescr"></a>
441
<h3 id="subsectionC.3.2"><span class="headlinenumber"><a name="subsectionC.3.2"></a>C.3.2 </span><tt>Array</tt>
445
<h4 id="subsubsectionC.3.2.1">Mandatory attributes</h4>
447
<p class="first">The next attributes are mandatory for <em>array</em>
452
<dt>CLASS</dt> <dd>Must be set to
453
<tt class="verb">'ARRAY'</tt>.
456
<dt>FLAVOR</dt> <dd>This is meant to provide the
457
information about the kind of object kept in the
458
<tt class="verb">Array</tt>, i.e. when the dataset is read,
459
it will be converted to the indicated flavor. It can
460
take one the next string values:
463
<dt>"NumArray"</dt> <dd>The dataset will be
464
returned as a <tt class="verb">NumArray</tt> object (from
465
the <tt class="verb">numarray</tt> package).
467
<dt>"CharArray"</dt> <dd>The dataset will be
468
returned as a <tt class="verb">CharArray</tt> object
469
(from the <tt class="verb">numarray</tt> package).
471
<dt>"Numeric"</dt> <dd>The dataset will be
472
returned as an <tt class="verb">array</tt> object
473
(from the <tt class="verb">Numeric</tt> package).
475
<dt>"List"</dt> <dd>The dataset will be
476
returned as a Python <tt class="verb">List</tt> object.
478
<dt>"Tuple"</dt> <dd>The dataset will be
479
returned as a Python <tt class="verb">Tuple</tt> object.
481
<dt>"Int"</dt> <dd>The dataset will be
482
returned as a Python <tt class="verb">Int</tt>
483
object. This is meant mainly for scalar
484
(i.e. without dimensions) integer values.
486
<dt>"Float"</dt> <dd>The dataset will be
487
returned as a Python <tt class="verb">Float</tt>
488
object. This is meant mainly for scalar
489
(i.e. without dimensions) floating point values.
491
<dt>"String"</dt> <dd>The dataset will be
492
returned as a Python <tt class="verb">String</tt>
493
object. This is meant mainly for scalar
494
(i.e. without dimensions) string values.
499
<dt>TITLE</dt> <dd>A string where the user can
500
put some description on what is this dataset used
504
<dt>VERSION</dt> <dd>Should contain the string
505
<tt class="verb">'2.1'</tt>.
511
<h4 id="subsubsectionC.3.2.2">Storage Layout</h4>
513
<p class="first">An <tt class="verb">Array</tt> has a <em>dataspace</em> with a
514
<em>N-dimensional contiguous</em> layout (if you
515
prefer a <em>chunked</em> layout see
516
<tt class="verb">EArray</tt> below).
521
<h4 id="subsubsectionC.3.2.3">Datatypes supported</h4>
523
<p class="first">The elements of <tt class="verb">Array</tt> must have either
524
HDF5 <em>atomic</em> datatypes or a <em>compound</em>
525
datatype representing a complex number. The atomic
526
datatypes can currently be one of the next HDF5
527
datatype <em>classes</em>: H5T_BITFIELD, H5T_INTEGER,
528
H5T_FLOAT and H5T_STRING. See the <tt class="verb">Table</tt>
529
format description in <a href="#TableFormatDescr">section C.3.1</a> for more info
533
<p>In addition to the HDF5 atomic datatypes, the Array
534
format supports complex numbers with the H5T_COMPOUND
535
datatype class. See the <tt class="verb">Table</tt> format
536
description in <a href="#TableFormatDescr">section C.3.1</a> for more info
537
about this special type.
540
<p>You should note that H5T_ARRAY class datatypes are
541
not allowed in <tt class="verb">Array</tt> objects.
547
<div id="EArrayFormatDescr"><a name="EArrayFormatDescr"></a>
548
<h3 id="subsectionC.3.3"><span class="headlinenumber"><a name="subsectionC.3.3"></a>C.3.3 </span><tt>EArray</tt>
552
<h4 id="subsubsectionC.3.3.1">Mandatory attributes</h4>
554
<p class="first">The next attributes are mandatory for <em>earray</em>
559
<dt>CLASS</dt> <dd>Must be set to
560
<tt class="verb">'EARRAY'</tt>.
563
<dt>EXTDIM</dt> <dd>(<em>Integer</em>) Must be
564
set to the extensible dimension. Only one extensible
565
dimension is supported right now.
568
<dt>FLAVOR</dt> <dd>This is meant to provide the
569
information about the kind of objects kept in the
570
<tt class="verb">EArray</tt>, i.e. when the dataset is read,
571
it will be converted to the indicated flavor. It can
572
take the same values as the <tt class="verb">Array</tt>
573
object (see <a href="#ArrayFormatDescr">C.3.2</a>),
574
except <tt class="verb">"Int"</tt> and <tt class="verb">"Float"</tt>.
577
<dt>TITLE</dt> <dd>A string where the user can
578
put some description on what is this dataset used
582
<dt>VERSION</dt> <dd>Should contain the string
583
<tt class="verb">'1.1'</tt>.
590
<h4 id="subsubsectionC.3.3.2">Storage Layout</h4>
592
<p class="first">An <tt class="verb">EArray</tt> has a <em>dataspace</em> with
593
a <em>N-dimensional chunked</em> layout.
598
<h4 id="subsubsectionC.3.3.3">Datatypes supported</h4>
600
<p class="first">The elements of <tt class="verb">EArray</tt> are allowed to
601
have the same datatypes as for the elements in the
602
Array format. They can be one of the HDF5
603
<em>atomic</em> datatype <em>classes</em>:
604
H5T_BITFIELD, H5T_INTEGER, H5T_FLOAT or H5T_STRING,
605
see the <tt class="verb">Table</tt> format description in <a href="#TableFormatDescr">section C.3.1</a> for more info
606
about these types. They can also be a H5T_COMPOUND
607
datatype representing a complex number, see the
608
<tt class="verb">Table</tt> format description in <a href="#TableFormatDescr">section C.3.1</a>.
611
<p>You should note that H5T_ARRAY class datatypes are
612
not allowed in <tt class="verb">EArray</tt> objects.
618
<div id="VLArrayFormatDescr"><a name="VLArrayFormatDescr"></a>
619
<h3 id="subsectionC.3.4"><span class="headlinenumber"><a name="subsectionC.3.4"></a>C.3.4 </span><tt>VLArray</tt>
623
<h4 id="subsubsectionC.3.4.1">Mandatory attributes</h4>
625
<p class="first">The next attributes are mandatory for
626
<em>vlarray</em> structures:
630
<dt>CLASS</dt> <dd>Must be set to
631
<tt class="verb">'VLARRAY'</tt>.
634
<dt>FLAVOR</dt> <dd>This is meant to provide the
635
information about the kind of objects kept in the
636
<tt class="verb">VLArray</tt>, i.e. when the dataset is read,
637
it will be converted to the indicated flavor. It can
638
take one of the next values:
641
<dt>"NumArray"</dt> <dd>The elements in
642
dataset will be returned as
643
<tt class="verb">NumArray</tt> objects (from the
644
<tt class="verb">numarray</tt> package).
646
<dt>"CharArray"</dt> <dd>The elements in
647
dataset will be returned as
648
<tt class="verb">CharArray</tt> objects (from the
649
<tt class="verb">numarray</tt> package).
651
<dt>"String"</dt> <dd>The elements in the
652
dataset will be returned as Python
653
<tt class="verb">String</tt> objects of <em>fixed</em>
654
length (and not as <tt class="verb">CharArrays</tt>).
656
<dt>"Numeric"</dt> <dd>The elements in the
657
dataset will be returned as
658
<tt class="verb">array</tt> objects (from the
659
<tt class="verb">Numeric</tt> package).
661
<dt>"List"</dt> <dd>The elements in the
662
dataset will be returned as Python
663
<tt class="verb">List</tt> objects.
665
<dt>"Tuple"</dt> <dd>The elements in the
666
dataset will be returned as Python
667
<tt class="verb">Tuple</tt> objects.
669
<dt>"Object"</dt> <dd>The elements in the
670
dataset will be interpreted as pickled
671
(i.e. serialized objects through the use of the
672
<tt class="verb">Pickle</tt> Python module) objects and
673
returned as Python <em>generic</em>
674
objects. Only one of such objects will be
675
supported per entry. As the <tt class="verb">Pickle</tt>
676
module is not normally available in other
677
languages, this flavor won't be useful in
680
<dt>"VLString"</dt> <dd>The elements in the
681
dataset will be returned as Python
682
<tt class="verb">String</tt> objects of <em>any</em>
683
length, with the twist that <b>Unicode</b> strings are
684
supported as well (provided you use the <b>UTF-8</b> codification, see
685
below). However, only one of such objects will
686
be supported per entry.
691
<dt>TITLE</dt> <dd>A string where the user can
692
put some description on what is this dataset used
696
<dt>VERSION</dt> <dd>Should contain the string
697
<tt class="verb">'1.1'</tt>.
704
<h4 id="subsubsectionC.3.4.2">Storage Layout</h4>
706
<p class="first">An <tt class="verb">VLArray</tt> has a <em>dataspace</em> with
707
a <em>1-dimensional chunked</em> layout.
712
<h4 id="subsubsectionC.3.4.3">Datatypes supported</h4>
714
<p class="first">The datatype of the elements (rows) of
715
<tt class="verb">VLArray</tt> objects must be the H5T_VLEN
716
<em>variable-length</em> (or VL for short) datatype,
717
and the base datatype specified for the VL datatype
718
can be of any <em>atomic</em> HDF5 datatype that is
719
listed in the <tt class="verb">Table</tt> format <a href="#TableFormatDescr">description
720
section C.3.1</a>. That includes the classes:
723
<li>H5T_BITFIELD</li>
729
<p>They can also be a H5T_COMPOUND datatype representing
730
a complex number, see the <tt class="verb">Table</tt> format
731
description in <a href="#TableFormatDescr">section C.3.1</a> for a detailed
734
<p>You should note that this does not include another VL
735
datatype, or a compound datatype that does not fit the
736
description of a complex number. Note as well that,
737
for <tt class="verb">Object</tt> and <tt class="verb">VLString</tt>
738
special flavors, the base for the VL datatype is
739
always a H5T_NATIVE_UCHAR. That means that the
740
complete row entry in the dataset has to be used in
741
order to fully serialize the object or the variable
744
<p>In addition, if you plan to use a
745
<tt class="verb">VLString</tt> flavor for your text data and
746
you are using ascii-7 (7 bits ASCII) codification for
747
your strings, but you don't know (or just don't want)
748
to convert it to the required UTF-8 codification, you
749
should not worry too much about that because the ASCII
750
characters with values in the range [0x00, 0x7f] are
751
directly mapped to Unicode characters in the range
752
[U+0000, U+007F] and the UTF-8 encoding has the useful
753
property that an UTF-8 encoded ascii-7 string is
754
indistinguishable from a traditional ascii-7 string.
755
So, you will not need any further conversion in order
756
to save your ascii-7 strings and have an
757
<tt class="verb">VLString</tt> flavor.
765
</div></div><div class="speedbar-bottom"><hr class="speedbar"><table class="speedbar"><tbody><tr><td style="text-align: left; width: 15%"><a href="usersguide8.html">previous</a></td><td style="text-align: center"><a href="usersguide.html#tb:table-of-contents">Table of Contents</a></td><td style="text-align: right; width: 15%"><a href="usersguide10.html">next</a></td></tr></tbody></table></div></body></html>
b'\\ No newline at end of file'
added
removed
doc/html/usersguide9.html
