PyTables User's Guide: Hierarchical datasets in Python - Release 1.3.2 | ||
---|---|---|
Prev | Chapter 4. Library Reference | Next |
Instances of this class represents array objects in the object tree with the property that their rows can have a variable number of (homogeneous) elements (called atomic objects, or just atoms). Variable length arrays (or VLA's for short), similarly to Table instances, can have only one dimension, and likewise Table, the compound elements (the atoms) of the rows of VLArrays can be fully multidimensional objects.
VLArray provides methods to read/write data from/to variable length array objects residents on disk. Also, note that this object inherits all the public attributes and methods that Leaf already has.
An Atom (see 4.16.3) instance representing the shape, type and flavor of the atomic objects to be saved.
On iterators, this is the index of the current row.
The total number of rows.
Get the enumerated type associated with this array.
If this array is of an enumerated type, the corresponding Enum instance (see 4.17.4) is returned. If it is not of an enumerated type, a TypeError is raised.
Append objects in the sequence to the array.
This method appends the objects in the sequence to a single row in this array. The type of individual objects must be compliant with the type of atoms in the array. In the case of variable length strings, the very string to append is the sequence.
Example of use (code available in examples/vlarray1.py):
import tables from numpy import * # or, from numarray import * # Create a VLArray: fileh = tables.openFile("vlarray1.h5", mode = "w") vlarray = fileh.createVLArray(fileh.root, 'vlarray1', tables.Int32Atom(flavor="numpy"), "ragged array of ints", Filters(complevel=1)) # Append some (variable length) rows: vlarray.append(array([5, 6])) vlarray.append(array([5, 6, 7])) vlarray.append([5, 6, 9, 8]) # Now, read it through an iterator: for x in vlarray: print vlarray.name+"["+str(vlarray.nrow)+"]-->", x # Close the file fileh.close()
The output of the previous program looks like this:
vlarray1[0]--> [5 6] vlarray1[1]--> [5 6 7] vlarray1[2]--> [5 6 9 8]
The objects argument is only retained for backwards compatibility; please do not use it.
Returns an iterator yielding one row per iteration. If a range is supplied (i.e. some of the start, stop or step parameters are passed), only the appropriate rows are returned. Else, all the rows are returned. See also the __iter__() special methods in section 4.13.3 for a shorter way to call this iterator.
The meaning of the start, stop and step parameters is the same as in the range() python function, except that negative values of step are not allowed. Moreover, if only start is specified, then stop will be set to start+1. If you do not specify neither start nor stop, then all the rows in the object are selected.
Example of use:
for row in vlarray.iterrows(step=4): print vlarray.name+"["+str(vlarray.nrow)+"]-->", row
Returns the actual data in VLArray. As the lengths of the different rows are variable, the returned value is a python list, with as many entries as specified rows in the range parameters.
The meaning of the start, stop and step parameters is the same as in the range() python function, except that negative values of step are not allowed. Moreover, if only start is specified, then stop will be set to start+1. If you do not specify neither start nor stop, then all the rows in the object are selected.
Following are described the methods that automatically trigger actions when a VLArray instance is accessed in a special way (e.g., vlarray[2:5] will be equivalent to a call to vlarray.__getitem__(slice(2,5,None)).
It returns the same iterator than VLArray.iterrows(0,0,1). However, this does not accept parameters.
Example of use:
result = [ row for row in vlarray ]
Which is equivalent to:
result = [ row for row in vlarray.iterrows() ]
It returns the slice of rows determined by key, which can be an integer index or an extended slice. The returned value is a list of objects of type array.atom.type.
Example of use:
list1 = vlarray[4] list2 = vlarray[4:1000:2]
Updates a vlarray row described by keys by setting it to value. Depending on the value of keys, the action taken is different:
It refers to the number of row to be modified. The value object must be type and shape compatible with the object that exists in the vlarray row.
The first element refers to the row to be modified, and the second element to the range (so, it can be an integer or an slice) of the row that will be updated. As above, the value object must be type and shape compatible with the object specified in the vlarray row and range.
Note: When updating VLStrings (codification UTF-8) or Objects atoms, there is a problem: one can only update values with exactly the same bytes than in the original row. With UTF-8 encoding this is problematic because, for instance, 'c' takes 1 byte, but 'ç' takes two. The same applies when using Objects atoms, because when cPickle applies to a class instance (for example), it does not guarantee to return the same number of bytes than over other instance, even of the same class than the former. These facts effectively limit the number of objects than can be updated in VLArrays.
Example of use:
vlarray[0] = vlarray[0]*2+3 vlarray[99,3:] = arange(96)*2+3 # Negative values for start and stop (but not step) are supported vlarray[99,-99:-89:2] = vlarray[5]*2+3