COO¶

class sparse.COO(coords, data=None, shape=None, has_duplicates=True, sorted=False, prune=False, cache=False, fill_value=None)[source]¶

A sparse multidimensional array.

This is stored in COO format. It depends on NumPy and Scipy.sparse for computation, but supports arrays of arbitrary dimension.

Parameters:

coords (numpy.ndarray (COO.ndim, COO.nnz)) – An array holding the index locations of every value Should have shape (number of dimensions, number of non-zeros).
data (numpy.ndarray (COO.nnz,)) – An array of Values. A scalar can also be supplied if the data is the same across all coordinates. If not given, defers to as_coo.
shape (tuple[int] (COO.ndim,)) – The shape of the array.
has_duplicates (bool, optional) – A value indicating whether the supplied value for coords has duplicates. Note that setting this to False when coords does have duplicates may result in undefined behaviour. See COO.sum_duplicates
sorted (bool, optional) – A value indicating whether the values in coords are sorted. Note that setting this to True when coords isn’t sorted may result in undefined behaviour. See COO.sort_indices.
prune (bool, optional) – A flag indicating whether or not we should prune any fill-values present in data.
cache (bool, optional) – Whether to enable cacheing for various operations. See COO.enable_caching
fill_value (scalar, optional) – The fill value for this array.

coords¶

An array holding the coordinates of every nonzero element.

Type:	numpy.ndarray (ndim, nnz)

data¶

An array holding the values corresponding to COO.coords.

Type:	numpy.ndarray (nnz,)

shape¶

The dimensions of this array.

Type:	tuple[int] (ndim,)

See also

DOK: A mostly write-only sparse array.
as_coo: Convert any given format to COO.

Examples

You can create COO objects from Numpy arrays.

>>> x = np.eye(4, dtype=np.uint8)
>>> x[2, 3] = 5
>>> s = COO.from_numpy(x)
>>> s
<COO: shape=(4, 4), dtype=uint8, nnz=5, fill_value=0>
>>> s.data  # doctest: +NORMALIZE_WHITESPACE
array([1, 1, 1, 5, 1], dtype=uint8)
>>> s.coords  # doctest: +NORMALIZE_WHITESPACE
array([[0, 1, 2, 2, 3],
       [0, 1, 2, 3, 3]])

COO objects support basic arithmetic and binary operations.

>>> x2 = np.eye(4, dtype=np.uint8)
>>> x2[3, 2] = 5
>>> s2 = COO.from_numpy(x2)
>>> (s + s2).todense()  # doctest: +NORMALIZE_WHITESPACE
array([[2, 0, 0, 0],
       [0, 2, 0, 0],
       [0, 0, 2, 5],
       [0, 0, 5, 2]], dtype=uint8)
>>> (s * s2).todense()  # doctest: +NORMALIZE_WHITESPACE
array([[1, 0, 0, 0],
       [0, 1, 0, 0],
       [0, 0, 1, 0],
       [0, 0, 0, 1]], dtype=uint8)

Binary operations support broadcasting.

>>> x3 = np.zeros((4, 1), dtype=np.uint8)
>>> x3[2, 0] = 1
>>> s3 = COO.from_numpy(x3)
>>> (s * s3).todense()  # doctest: +NORMALIZE_WHITESPACE
array([[0, 0, 0, 0],
       [0, 0, 0, 0],
       [0, 0, 1, 5],
       [0, 0, 0, 0]], dtype=uint8)

COO objects also support dot products and reductions.

>>> s.dot(s.T).sum(axis=0).todense()   # doctest: +NORMALIZE_WHITESPACE
array([ 1,  1, 31,  6], dtype=uint64)

You can use Numpy ufunc operations on COO arrays as well.

>>> np.sum(s, axis=1).todense()  # doctest: +NORMALIZE_WHITESPACE
array([1, 1, 6, 1], dtype=uint64)
>>> np.round(np.sqrt(s, dtype=np.float64), decimals=1).todense()   # doctest: +SKIP
array([[ 1. ,  0. ,  0. ,  0. ],
       [ 0. ,  1. ,  0. ,  0. ],
       [ 0. ,  0. ,  1. ,  2.2],
       [ 0. ,  0. ,  0. ,  1. ]])

Operations that will result in a dense array will usually result in a different fill value, such as the following.

>>> np.exp(s)
<COO: shape=(4, 4), dtype=float16, nnz=5, fill_value=1.0>

You can also create COO arrays from coordinates and data.

>>> coords = [[0, 0, 0, 1, 1],
...           [0, 1, 2, 0, 3],
...           [0, 3, 2, 0, 1]]
>>> data = [1, 2, 3, 4, 5]
>>> s4 = COO(coords, data, shape=(3, 4, 5))
>>> s4
<COO: shape=(3, 4, 5), dtype=int64, nnz=5, fill_value=0>

If the data is same across all coordinates, you can also specify a scalar.

>>> coords = [[0, 0, 0, 1, 1],
...           [0, 1, 2, 0, 3],
...           [0, 3, 2, 0, 1]]
>>> data = 1
>>> s5 = COO(coords, data, shape=(3, 4, 5))
>>> s5
<COO: shape=(3, 4, 5), dtype=int64, nnz=5, fill_value=0>

Following scipy.sparse conventions you can also pass these as a tuple with rows and columns

>>> rows = [0, 1, 2, 3, 4]
>>> cols = [0, 0, 0, 1, 1]
>>> data = [10, 20, 30, 40, 50]
>>> z = COO((data, (rows, cols)))
>>> z.todense()  # doctest: +NORMALIZE_WHITESPACE
array([[10,  0],
       [20,  0],
       [30,  0],
       [ 0, 40],
       [ 0, 50]])

You can also pass a dictionary or iterable of index/value pairs. Repeated indices imply summation:

>>> d = {(0, 0, 0): 1, (1, 2, 3): 2, (1, 1, 0): 3}
>>> COO(d)
<COO: shape=(2, 3, 4), dtype=int64, nnz=3, fill_value=0>
>>> L = [((0, 0), 1),
...      ((1, 1), 2),
...      ((0, 0), 3)]
>>> COO(L).todense()  # doctest: +NORMALIZE_WHITESPACE
array([[4, 0],
       [0, 2]])

You can convert DOK arrays to COO arrays.

>>> from sparse import DOK
>>> s6 = DOK((5, 5), dtype=np.int64)
>>> s6[1:3, 1:3] = [[4, 5], [6, 7]]
>>> s6
<DOK: shape=(5, 5), dtype=int64, nnz=4, fill_value=0>
>>> s7 = s6.asformat('coo')
>>> s7
<COO: shape=(5, 5), dtype=int64, nnz=4, fill_value=0>
>>> s7.todense()  # doctest: +NORMALIZE_WHITESPACE
array([[0, 0, 0, 0, 0],
       [0, 4, 5, 0, 0],
       [0, 6, 7, 0, 0],
       [0, 0, 0, 0, 0],
       [0, 0, 0, 0, 0]])

Note

COO objects also support operators and indexing

Attributes

`COO.T`	Returns a new array which has the order of the axes reversed.
`COO.dtype`	The datatype of this array.
`COO.nbytes`	The number of bytes taken up by this object.
`COO.ndim`	The number of dimensions of this array.
`COO.nnz`	The number of nonzero elements in this array.
`COO.size`	The number of all elements (including zeros) in this array.
`COO.density`	The ratio of nonzero to all elements in this array.
`COO.imag`	The imaginary part of the array.
`COO.real`	The real part of the array.

Constructing COO objects

`COO.from_iter`(x[, shape, fill_value])	Converts an iterable in certain formats to a `COO` array.
`COO.from_numpy`(x[, fill_value])	Convert the given `numpy.ndarray` to a `COO` object.
`COO.from_scipy_sparse`(x)	Construct a `COO` array from a `scipy.sparse.spmatrix`

Element-wise operations

`COO.astype`(dtype)	Copy of the array, cast to a specified type.
`COO.conj`()	Return the complex conjugate, element-wise.
`COO.clip`([min, max, out])	Clip (limit) the values in the array.
`COO.round`([decimals, out])	Evenly round to the given number of decimals.

Reductions

`COO.reduce`(method[, axis, keepdims])	Performs a reduction operation on this array.
`COO.sum`([axis, keepdims, dtype, out])	Performs a sum operation along the given axes.
`COO.mean`([axis, keepdims, dtype, out])	Compute the mean along the given axes.
`COO.prod`([axis, keepdims, dtype, out])	Performs a product operation along the given axes.
`COO.min`([axis, keepdims, out])	Minimize along the given axes.
`COO.max`([axis, keepdims, out])	Maximize along the given axes.
`COO.any`([axis, keepdims, out])	See if any values along array are `True`.
`COO.all`([axis, keepdims, out])	See if all values in an array are `True`.

Converting to other formats

`COO.asformat`(format)	Convert this sparse array to a given format.
`COO.todense`()	Convert this `COO` array to a dense `numpy.ndarray`.
`COO.maybe_densify`([max_size, min_density])	Converts this `COO` array to a `numpy.ndarray` if not too costly.
`COO.to_scipy_sparse`()	Converts this `COO` object into a `scipy.sparse.coo_matrix`.
`COO.tocsc`()	Converts this array to a `scipy.sparse.csc_matrix`.
`COO.tocsr`()	Converts this array to a `scipy.sparse.csr_matrix`.

Other operations

`COO.copy`([deep])	Return a copy of the array.
`COO.dot`(other)	Performs the equivalent of `x.dot(y)` for `COO`.
`COO.reshape`(shape[, order])	Returns a new `COO` array that is a reshaped version of this array.
`COO.transpose`([axes])	Returns a new array which has the order of the axes switched.
`COO.nonzero`()	Get the indices where this array is nonzero.

Utility functions

`COO.broadcast_to`(shape)	Performs the equivalent of `numpy.broadcast_to` for `COO`.
`COO.enable_caching`()	Enable caching of reshape, transpose, and tocsr/csc operations
`COO.linear_loc`()	The nonzero coordinates of a flattened version of this array.