sparse¶
The sparse module defines a dtype for numpy that represents sparse data in n-dimensional coo-format. That is, every array element contains an index into a larger sparse object, and a value, which can be of any numpy supported data type including integers, floating point values and complex data. Additionally, the dtype carries the shape of the sparse object as metadata, which makes the numpy array into an entirely self contained sparse object.
In addition to the dtype, the sparse module provides a range of methods for manipulation of sparse data, such as deduplication of indices, pruning of zeros, sparse addition, and conversion to other sparse or dense data formats.
- nutils.sparse.dtype(shape, vtype=<class 'numpy.float64'>)¶
Numpy data dtype for sparse data.
Returns a structured dtype with fields ‘index’ and ‘value’, where index is again structured with fields ‘i0’, ‘i1’, etc, and value is of type
vtype
. The indices are of the smallest unsigned integer type that can encode all indices withinshape
, and carry the shape as metadata.- Parameters:
shape (
tuple
of integers.) – Shape of the sparse object.vtype (
numpy.dtype
orstr
) – Data dype of the sparse object (i.e. the nonzero values).
- Returns:
dtype – The sparse dtype.
- Return type:
- nutils.sparse.ndim(data)¶
Dimension of the sparse object.
- nutils.sparse.shape(data)¶
Shape of the sparse object.
- nutils.sparse.indices(data)¶
Tuple of indices of the nonzero values of the sparse object.
- nutils.sparse.values(data)¶
Nonzero values of the sparse object.
- nutils.sparse.extract(data)¶
Tuple of indices, values, and shape of the sparse object.
- nutils.sparse.empty(shape, vtype=<class 'numpy.float64'>)¶
Completely sparse array of given shape and data type.
- nutils.sparse.result_type(dtype0, *dtypes)¶
Sparse analogue of
numpy.result_type()
.
- nutils.sparse.dedup(data, inplace=False)¶
Deduplicate indices.
Dedup sorts data in lexicographical order and sums all values with matching indices such that the returned array has at most one value per sparse index. The sorting happens in place, which means that
dedup
changes the order of the input argument. Additionally, ifinplace
is true, the deduplication step reuses the input array’s memory. This may affect the size of the array, which should no longer be used after deduplication in place. In case the input has no duplicates the input array is returned.>>> from nutils.sparse import dtype, dedup >>> from numpy import array >>> A = array([((0,1),.1), ((1,0),.2), ((0,1),.3)], dtype=dtype([2,2])) >>> dedup(A) array([((0, 1), 0.4), ((1, 0), 0.2)], dtype=[('index', [((2, 'i0'), 'u1'), ((2, 'i1'), 'u1')]), ('value', '<f8')])
- nutils.sparse.prune(data, inplace=False, mask=None)¶
Prune zero values.
Prune returns a sparse object with all zero values removed, or all entries for which the boolean vector
mask
is true if it is specified. Ifinplace
is true the returned object reuses the input array’s memory. This may affect the size of the array, which should no longer be used after pruning in place. In case the input has no zeros the input array is returned.>>> from nutils.sparse import dtype, prune >>> from numpy import array >>> A = array([((0,1),.1), ((1,0),0), ((0,1),.3)], dtype=dtype([2,2])) >>> prune(A) array([((0, 1), 0.1), ((0, 1), 0.3)], dtype=[('index', [((2, 'i0'), 'u1'), ((2, 'i1'), 'u1')]), ('value', '<f8')])
- nutils.sparse.add(datas)¶
Add sparse objects.
Returns the sum of a list of sparse objects by concatenating the sparse entries. The returned array is of the data type mandated by Numpy’s promotion rules. In case
datas
contains only one item of nonzero length and this item has the correct data type, then this array is returned as-is.>>> from nutils.sparse import dtype, add >>> from numpy import array >>> A = array([((0,1),.1), ((1,0),.2)], dtype=dtype([2,2])) >>> B = array([((0,1),.3)], dtype=dtype([2,2])) >>> add([A, B]) array([((0, 1), 0.1), ((1, 0), 0.2), ((0, 1), 0.3)], dtype=[('index', [((2, 'i0'), 'u1'), ((2, 'i1'), 'u1')]), ('value', '<f8')])
- nutils.sparse.block(datas)¶
Stack sparse blocks.
- nutils.sparse.take(data, select)¶
Take a multidimensional, ordered subset.
- nutils.sparse.toarray(data)¶
Convert sparse object to a dense array.
>>> from nutils.sparse import dtype, toarray >>> from numpy import array >>> A = array([((0,1),.1), ((1,0),.2), ((0,1),.3)], dtype=dtype([2,2])) >>> toarray(A) array([[ 0. , 0.4], [ 0.2, 0. ]])
- nutils.sparse.fromarray(data)¶
Convert dense array to sparse object.
>>> from nutils.sparse import dtype, fromarray >>> from numpy import array >>> A = array([[0, .4], [.2, 0]]) >>> fromarray(A) array([((0, 0), 0. ), ((0, 1), 0.4), ((1, 0), 0.2), ((1, 1), 0. )], dtype=[('index', [((2, 'i0'), 'u1'), ((2, 'i1'), 'u1')]), ('value', '<f8')])