PyTables User's Guide: Hierarchical datasets in Python - Release 1.3.3
Prev | Chapter 4. Library Reference | Next

# 4.10. The Array class

Represents an array on file. It provides methods to write/read data to/from array objects in the file. This class does not allow you to enlarge the datasets on disk; see the `EArray` descendant in section 4.12 if you want enlargeable dataset support and/or compression features. See also `CArray` in section 4.11

The array data types supported are the same as the set provided by the `numarray` package. For details of these data types see appendix A, or the `numarray` reference manual ([]).

An interesting property of the `Array` class is that it remembers the flavor of the object that has been saved so that if you saved, for example, a `List`, you will get a `List` during readings afterwards, or if you saved a `NumPy` array, you will get a `NumPy` object.

Note that this object inherits all the public attributes and methods that `Leaf` already provides.

## 4.10.1. Array instance variables

flavor

  The object representation for this array. It can be any of "numarray", "numpy", "numeric" or "python" values.

nrows

  The length of the first dimension of the array.

nrow

  On iterators, this is the index of the current row.

type

  The type class of the represented array.

stype

  The string type of the represented array.

itemsize

  The size of the base items. Specially useful for `CharType` objects.

## 4.10.2. Array methods

Note that, as this object has no internal I/O buffers, it is not necessary to use the flush() method inherited from `Leaf` in order to save its internal state to disk. When a writing method call returns, all the data is already on disk.

### 4.10.2.1. getEnum()

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.

### 4.10.2.2. iterrows(start=None, stop=None, step=1)

Returns an iterator yielding `numarray` instances built from rows in array. The return rows are taken from the first dimension in case of an `Array` and `CArray` instance and the enlargeable dimension in case of an `EArray` instance. 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 and `__iter__()` special methods in section 4.10.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:

    		result = [ row for row in arrayInstance.iterrows(step=4) ]

### 4.10.2.3. read(start=None, stop=None, step=1)

Read the array from disk and return it as a `numarray` (default) object, or an object with the same original flavor that it was saved. It accepts start, stop and step parameters to select rows (the first dimension in the case of an `Array` and `CArray` instance and the enlargeable dimension in case of an `EArray`) for reading.

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.

## 4.10.3. Array special methods

Following are described the methods that automatically trigger actions when an `Array` instance is accessed in a special way (e.g., `array[2:3,...,::2]` will be equivalent to a call to `array.__getitem__(slice(2,3, None), Ellipsis, slice(None, None, 2))`).

### 4.10.3.1. __iter__()

It returns the same iterator than `Array.iterrows(0,0,1)`. However, this does not accept parameters.

Example of use:

    		result = [ row[2] for row in array ]

Which is equivalent to:

    		result = [ row[2] for row in array.iterrows(0, 0, 1) ]

### 4.10.3.2. __getitem__(key)

It returns a `numarray` (default) object (or an object with the same original flavor that it was saved) containing the slice of rows stated in the `key` parameter. The set of allowed tokens in `key` is the same as extended slicing in python (the `Ellipsis` token included).

Example of use:

    		array1 = array[4]   # array1.shape == array.shape[1:]
    		array2 = array[4:1000:2]  # len(array2.shape) == len(array.shape)
    		array3 = array[::2, 1:4, :]
    		array4 = array[1, ..., ::2, 1:4, 4:] # General slice selection

### 4.10.3.3. __setitem__(key, value)

Sets an Array element, row or extended slice. It takes different actions depending on the type of the `key` parameter:

`key` is an integer:

  The corresponding row is assigned to value. If needed, this `value` is broadcasted to fit the specified row.

`key` is a slice:

  The row slice determined by it is assigned to `value`. If needed, this `value` is broadcasted to fit in the desired range. If the slice to be updated exceeds the actual shape of the array, only the values in the existing range are updated, i.e. the index error will be silently ignored. If `value` is a multidimensional object, then its shape must be compatible with the slice specified in `key`, otherwise, a `ValueError` will be issued.

Example of use:

    		a1[0] = 333       # Assign an integer to a Integer Array row
    		a2[0] = "b"       # Assign a string to a string Array row
    		a3[1:4] = 5       # Broadcast 5 to slice 1:4
    		a4[1:4:2] = "xXx" # Broadcast "xXx" to slice 1:4:2
    		# General slice update (a5.shape = (4,3,2,8,5,10)
    		a5[1, ..., ::2, 1:4, 4:] = arange(1728, shape=(4,3,2,4,3,6))

Prev | Home | Next
The Column class | Up | The CArray class