memmap
index
/usr/lib/python2.6/dist-packages/numpy/core/memmap.py

Create a memory-map to an array stored in a file on disk.
 
Memory-mapped files are used for accessing small segments of large files
on disk, without reading the entire file into memory.  Numpy's
memmap's are array-like objects.  This differs from Python's ``mmap``
module, which uses file-like objects.
 
Parameters
----------
filename : string or file-like object
    The file name or file object to be used as the array data
    buffer.
dtype : data-type, optional
    The data-type used to interpret the file contents.
    Default is `uint8`
mode : {'r+', 'r', 'w+', 'c'}, optional
    The file is opened in this mode:
 
    +------+-------------------------------------------------------------+
    | 'r'  | Open existing file for reading only.                        |
    +------+-------------------------------------------------------------+
    | 'r+' | Open existing file for reading and writing.                 |
    +------+-------------------------------------------------------------+
    | 'w+' | Create or overwrite existing file for reading and writing.  |
    +------+-------------------------------------------------------------+
    | 'c'  | Copy-on-write: assignments affect data in memory, but       |
    |      | changes are not saved to disk.  The file on disk is         |
    |      | read-only.                                                  |
    +------+-------------------------------------------------------------+
 
    Default is 'r+'.
offset : integer, optional
    In the file, array data starts at this offset.  `offset` should be
    a multiple of the byte-size of `dtype`.  Requires `shape=None`.
    The default is 0.
shape : tuple, optional
    The desired shape of the array. By default, the returned array will be
    1-D with the number of elements determined by file size and data-type.
order : {'C', 'F'}, optional
    Specify the order of the ndarray memory layout: C (row-major) or
    Fortran (column-major).  This only has an effect if the shape is
    greater than 1-D.  The defaullt order is 'C'.
 
Methods
-------
close
    Close the memmap file.
flush
    Flush any changes in memory to file on disk.
    When you delete a memmap object, flush is called first to write
    changes to disk before removing the object.
 
Notes
-----
The memmap object can be used anywhere an ndarray is accepted.
Given a memmap ``fp``, ``isinstance(fp, numpy.ndarray)`` returns
``True``.
 
Notes
-----
 
Memory-mapped arrays use the the Python memory-map object which
(prior to Python 2.5) does not allow files to be larger than a
certain size depending on the platform. This size is always < 2GB
even on 64-bit systems.
 
Examples
--------
>>> data = np.arange(12, dtype='float32')
>>> data.resize((3,4))
 
This example uses a temporary file so that doctest doesn't write
files to your directory. You would use a 'normal' filename.
 
>>> from tempfile import mkdtemp
>>> import os.path as path
>>> filename = path.join(mkdtemp(), 'newfile.dat')
 
Create a memmap with dtype and shape that matches our data:
 
>>> fp = np.memmap(filename, dtype='float32', mode='w+', shape=(3,4))
>>> fp
memmap([[ 0.,  0.,  0.,  0.],
        [ 0.,  0.,  0.,  0.],
        [ 0.,  0.,  0.,  0.]], dtype=float32)
 
Write data to memmap array:
 
>>> fp[:] = data[:]
>>> fp
memmap([[  0.,   1.,   2.,   3.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)
 
Deletion flushes memory changes to disk before removing the object:
 
>>> del fp
 
Load the memmap and verify data was stored:
 
>>> newfp = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))
>>> newfp
memmap([[  0.,   1.,   2.,   3.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)
 
Read-only memmap:
 
>>> fpr = np.memmap(filename, dtype='float32', mode='r', shape=(3,4))
>>> fpr.flags.writeable
False
 
Cannot assign to read-only, obviously:
 
>>> fpr[0, 3] = 56
Traceback (most recent call last):
    ...
RuntimeError: array is not writeable
 
Copy-on-write memmap:
 
>>> fpc = np.memmap(filename, dtype='float32', mode='c', shape=(3,4))
>>> fpc.flags.writeable
True
 
It's possible to assign to copy-on-write array, but values are only
written into the memory copy of the array, and not written to disk:
 
>>> fpc
memmap([[  0.,   1.,   2.,   3.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)
>>> fpc[0,:] = 0
>>> fpc
memmap([[  0.,   0.,   0.,   0.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)
 
File on disk is unchanged:
 
>>> fpr
memmap([[  0.,   1.,   2.,   3.],
        [  4.,   5.,   6.,   7.],
        [  8.,   9.,  10.,  11.]], dtype=float32)
 
Offset into a memmap:
 
>>> fpo = np.memmap(filename, dtype='float32', mode='r', offset=16)
>>> fpo
memmap([  4.,   5.,   6.,   7.,   8.,   9.,  10.,  11.], dtype=float32)

 
Functions
       
__subclasshook__(...)
Abstract classes can override this to customize issubclass().
 
This is invoked early on by abc.ABCMeta.__subclasscheck__().
It should return True, False or NotImplemented.  If it returns
NotImplemented, the normal algorithm is used.  Otherwise, it
overrides the normal algorithm (and the outcome is cached).

 
Data
       
T
Same as transpose() except self is returned for self.ndim < 2.
 
Examples
--------
>>> x = np.array([[1.,2.],[3.,4.]])
>>> x.T
array([[ 1.,  3.],
       [ 2.,  4.]])

__array_interface__
Array protocol: Python side.

__array_priority__ = -100.0
__array_struct__
Array protocol: C-struct side.

__dict__ = <dictproxy object at 0x7e957f8>
__module__ = 'numpy.core.memmap'
base
Base object if memory is from some other object.
 
Examples
--------
 
Base of an array owning its memory is None:
 
>>> x = np.array([1,2,3,4])
>>> x.base is None
True
 
Slicing creates a view, and the memory is shared with x:
 
>>> y = x[2:]
>>> y.base is x
True

ctypes
A ctypes interface object.

data
Buffer object pointing to the start of the data.

dtype
Data-type for the array.

flags
Information about the memory layout of the array.
 
Attributes
----------
C_CONTIGUOUS (C)
    The data is in a single, C-style contiguous segment.
F_CONTIGUOUS (F)
    The data is in a single, Fortran-style contiguous segment.
OWNDATA (O)
    The array owns the memory it uses or borrows it from another object.
WRITEABLE (W)
    The data area can be written to.
ALIGNED (A)
    The data and strides are aligned appropriately for the hardware.
UPDATEIFCOPY (U)
    This array is a copy of some other array. When this array is
    deallocated, the base array will be updated with the contents of
    this array.
 
FNC
    F_CONTIGUOUS and not C_CONTIGUOUS.
FORC
    F_CONTIGUOUS or C_CONTIGUOUS (one-segment test).
BEHAVED (B)
    ALIGNED and WRITEABLE.
CARRAY (CA)
    BEHAVED and C_CONTIGUOUS.
FARRAY (FA)
    BEHAVED and F_CONTIGUOUS and not C_CONTIGUOUS.
 
Notes
-----
The `flags` object can be also accessed dictionary-like, and using
lowercased attribute names. Short flag names are only supported in
dictionary access.
 
Only the UPDATEIFCOPY, WRITEABLE, and ALIGNED flags can be changed by
the user, via assigning to ``flags['FLAGNAME']`` or `ndarray.setflags`.
The array flags cannot be set arbitrarily:
 
- UPDATEIFCOPY can only be set ``False``.
- ALIGNED can only be set ``True`` if the data is truly aligned.
- WRITEABLE can only be set ``True`` if the array owns its own memory
  or the ultimate owner of the memory exposes a writeable buffer
  interface or is a string.

flat
A 1-D flat iterator over the array.
 
This is a `flatiter` instance, which acts similarly to a Python iterator.
 
See Also
--------
flatten : Return a copy of the array collapsed into one dimension.
flatiter
 
Examples
--------
>>> x = np.arange(1, 7).reshape(2, 3)
>>> x
array([[1, 2, 3],
       [4, 5, 6]])
>>> x.flat[3]
4
>>> x.T
array([[1, 4],
       [2, 5],
       [3, 6]])
>>> x.T.flat[3]
5
 
>>> type(x.flat)
<type 'numpy.flatiter'>

imag
The imaginary part of the array.
 
Examples
--------
>>> x = np.sqrt([1+0j, 0+1j])
>>> x.imag
array([ 0.        ,  0.70710678])
>>> x.imag.dtype
dtype('float64')

itemsize
Length of one element in bytes.
 
Examples
--------
>>> x = np.array([1,2,3], dtype=np.float64)
>>> x.itemsize
8
>>> x = np.array([1,2,3], dtype=np.complex128)
>>> x.itemsize
16

nbytes
Number of bytes in the array.
 
Examples
--------
>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.nbytes
480
>>> np.prod(x.shape) * x.itemsize
480

ndim
Number of array dimensions.
 
Examples
--------
 
>>> x = np.array([1,2,3])
>>> x.ndim
1
>>> y = np.zeros((2,3,4))
>>> y.ndim
3

real
The real part of the array.
 
Examples
--------
>>> x = np.sqrt([1+0j, 0+1j])
>>> x.real
array([ 1.        ,  0.70710678])
>>> x.real.dtype
dtype('float64')
 
See Also
--------
numpy.real : equivalent function

shape
Tuple of array dimensions.
 
Examples
--------
>>> x = np.array([1,2,3,4])
>>> x.shape
(4,)
>>> y = np.zeros((4,5,6))
>>> y.shape
(4, 5, 6)
>>> y.shape = (2, 5, 2, 3, 2)
>>> y.shape
(2, 5, 2, 3, 2)

size
Number of elements in the array.
 
Examples
--------
>>> x = np.zeros((3,5,2), dtype=np.complex128)
>>> x.size
30

strides
Tuple of bytes to step in each dimension.
 
The byte offset of element ``(i[0], i[1], ..., i[n])`` in an array `a`
is::
 
    offset = sum(np.array(i) * a.strides)
 
Examples
--------
>>> x = np.reshape(np.arange(5*6*7*8), (5,6,7,8)).transpose(2,3,1,0)
>>> x.strides
(32, 4, 224, 1344)
>>> i = np.array([3,5,2,2])
>>> offset = sum(i * x.strides)
>>> x[3,5,2,2]
813
>>> offset / x.itemsize
813