DOK

Bases: SparseArray, NDArrayOperatorsMixin

A class for building sparse multidimensional arrays.

Parameters:

Name	Type	Description	Default
shape	tuple[int](ndim)	The shape of the array.	required
data	dict	The key-value pairs for the data in this array.	None
dtype	dtype	The data type of this array. If left empty, it is inferred from the first element.	None
fill_value	scalar	The fill value of this array.	None

Attributes:

Name	Type	Description
dtype	dtype	The datatype of this array. Can be None if no elements have been set yet.
shape	tuple[int]	The shape of this array.
data	dict	The keys of this dictionary contain all the indices and the values contain the nonzero entries.

See Also

sparse.COO : A read-only sparse array.

Examples:

You can create sparse.DOK objects from Numpy arrays.

>>> x = np.eye(5, dtype=np.uint8)
>>> x[2, 3] = 5
>>> s = DOK.from_numpy(x)
>>> s
<DOK: shape=(5, 5), dtype=uint8, nnz=6, fill_value=0>

You can also create them from just shapes, and use slicing assignment.

>>> s2 = DOK((5, 5), dtype=np.int64)
>>> s2[1:3, 1:3] = [[4, 5], [6, 7]]
>>> s2
<DOK: shape=(5, 5), dtype=int64, nnz=4, fill_value=0>

You can convert sparse.DOK arrays to sparse.COO arrays, or numpy.ndarray objects.

>>> from sparse import COO
>>> s3 = COO(s2)
>>> s3
<COO: shape=(5, 5), dtype=int64, nnz=4, fill_value=0>
>>> s2.todense()
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]])

>>> s4 = COO.from_numpy(np.eye(4, dtype=np.uint8))
>>> s4
<COO: shape=(4, 4), dtype=uint8, nnz=4, fill_value=0>
>>> s5 = DOK.from_coo(s4)
>>> s5
<DOK: shape=(4, 4), dtype=uint8, nnz=4, fill_value=0>

You can also create sparse.DOK arrays from a shape and a dict of values. Zeros are automatically ignored.

>>> values = {
...     (1, 2, 3): 4,
...     (3, 2, 1): 0,
... }
>>> s6 = DOK((5, 5, 5), values)
>>> s6
<DOK: shape=(5, 5, 5), dtype=int64, nnz=1, fill_value=0.0>

Source code in sparse/numba_backend/_dok.py

class DOK(SparseArray, NDArrayOperatorsMixin):
    """
    A class for building sparse multidimensional arrays.

    Parameters
    ----------
    shape : tuple[int] (DOK.ndim,)
        The shape of the array.
    data : dict, optional
        The key-value pairs for the data in this array.
    dtype : np.dtype, optional
        The data type of this array. If left empty, it is inferred from
        the first element.
    fill_value : scalar, optional
        The fill value of this array.

    Attributes
    ----------
    dtype : numpy.dtype
        The datatype of this array. Can be `None` if no elements
        have been set yet.
    shape : tuple[int]
        The shape of this array.
    data : dict
        The keys of this dictionary contain all the indices and the values
        contain the nonzero entries.

    See Also
    --------
    [`sparse.COO`][] : A read-only sparse array.

    Examples
    --------
    You can create [`sparse.DOK`][] objects from Numpy arrays.

    >>> x = np.eye(5, dtype=np.uint8)
    >>> x[2, 3] = 5
    >>> s = DOK.from_numpy(x)
    >>> s
    <DOK: shape=(5, 5), dtype=uint8, nnz=6, fill_value=0>

    You can also create them from just shapes, and use slicing assignment.

    >>> s2 = DOK((5, 5), dtype=np.int64)
    >>> s2[1:3, 1:3] = [[4, 5], [6, 7]]
    >>> s2
    <DOK: shape=(5, 5), dtype=int64, nnz=4, fill_value=0>

    You can convert [`sparse.DOK`][] arrays to [`sparse.COO`][] arrays, or [`numpy.ndarray`][]
    objects.

    >>> from sparse import COO
    >>> s3 = COO(s2)
    >>> s3
    <COO: shape=(5, 5), dtype=int64, nnz=4, fill_value=0>
    >>> s2.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]])

    >>> s4 = COO.from_numpy(np.eye(4, dtype=np.uint8))
    >>> s4
    <COO: shape=(4, 4), dtype=uint8, nnz=4, fill_value=0>
    >>> s5 = DOK.from_coo(s4)
    >>> s5
    <DOK: shape=(4, 4), dtype=uint8, nnz=4, fill_value=0>

    You can also create [`sparse.DOK`][] arrays from a shape and a dict of
    values. Zeros are automatically ignored.

    >>> values = {
    ...     (1, 2, 3): 4,
    ...     (3, 2, 1): 0,
    ... }
    >>> s6 = DOK((5, 5, 5), values)
    >>> s6
    <DOK: shape=(5, 5, 5), dtype=int64, nnz=1, fill_value=0.0>
    """

    def __init__(self, shape, data=None, dtype=None, fill_value=None):
        from ._common import _is_scipy_sparse_obj
        from ._coo import COO

        self.data = {}

        if isinstance(shape, COO):
            ar = DOK.from_coo(shape)
            self._make_shallow_copy_of(ar)
            return

        if isinstance(shape, np.ndarray):
            ar = DOK.from_numpy(shape)
            self._make_shallow_copy_of(ar)
            return

        if _is_scipy_sparse_obj(shape):
            ar = DOK.from_scipy_sparse(shape)
            self._make_shallow_copy_of(ar)
            return

        self.dtype = np.dtype(dtype)

        if not data:
            data = {}

        super().__init__(shape, fill_value=fill_value)

        if isinstance(data, dict):
            if not dtype:
                if not len(data):
                    self.dtype = np.dtype("float64")
                else:
                    self.dtype = np.result_type(*(np.asarray(x).dtype for x in data.values()))

            for c, d in data.items():
                self[c] = d
        else:
            raise ValueError("data must be a dict.")

    @classmethod
    def from_scipy_sparse(cls, x, /, *, fill_value=None):
        """
        Create a [`sparse.DOK`][] array from a [`scipy.sparse.spmatrix`][].

        Parameters
        ----------
        x : scipy.sparse.spmatrix
            The matrix to convert.
        fill_value : scalar
            The fill-value to use when converting.

        Returns
        -------
        DOK
            The equivalent [`sparse.DOK`][] array.

        Examples
        --------
        >>> import scipy.sparse
        >>> x = scipy.sparse.rand(6, 3, density=0.2)
        >>> s = DOK.from_scipy_sparse(x)
        >>> np.array_equal(x.todense(), s.todense())
        True
        """
        from sparse import COO

        return COO.from_scipy_sparse(x, fill_value=fill_value).asformat(cls)

    @classmethod
    def from_coo(cls, x):
        """
        Get a [`sparse.DOK`][] array from a [`sparse.COO`][] array.

        Parameters
        ----------
        x : COO
            The array to convert.

        Returns
        -------
        DOK
            The equivalent [`sparse.DOK`][] array.

        Examples
        --------
        >>> from sparse import COO
        >>> s = COO.from_numpy(np.eye(4))
        >>> s2 = DOK.from_coo(s)
        >>> s2
        <DOK: shape=(4, 4), dtype=float64, nnz=4, fill_value=0.0>
        """
        ar = cls(x.shape, dtype=x.dtype, fill_value=x.fill_value)

        for c, d in zip(x.coords.T, x.data, strict=True):
            ar.data[tuple(c)] = d

        return ar

    def to_coo(self):
        """
        Convert this [`sparse.DOK`][] array to a [`sparse.COO`][] array.

        Returns
        -------
        COO
            The equivalent [`sparse.COO`][] array.

        Examples
        --------
        >>> s = DOK((5, 5))
        >>> s[1:3, 1:3] = [[4, 5], [6, 7]]
        >>> s
        <DOK: shape=(5, 5), dtype=float64, nnz=4, fill_value=0.0>
        >>> s2 = s.to_coo()
        >>> s2
        <COO: shape=(5, 5), dtype=float64, nnz=4, fill_value=0.0>
        """
        from ._coo import COO

        return COO(self)

    @classmethod
    def from_numpy(cls, x):
        """
        Get a [`sparse.DOK`][] array from a Numpy array.

        Parameters
        ----------
        x : np.ndarray
            The array to convert.

        Returns
        -------
        DOK
            The equivalent [`sparse.DOK`][] array.

        Examples
        --------
        >>> s = DOK.from_numpy(np.eye(4))
        >>> s
        <DOK: shape=(4, 4), dtype=float64, nnz=4, fill_value=0.0>
        """
        ar = cls(x.shape, dtype=x.dtype)

        coords = np.nonzero(x)
        data = x[coords]

        for c in zip(data, *coords, strict=True):
            d, c = c[0], c[1:]
            ar.data[c] = d

        return ar

    @property
    def nnz(self):
        """
        The number of nonzero elements in this array.

        Returns
        -------
        int
            The number of nonzero elements.

        See Also
        --------
        - [`sparse.COO.nnz`][] : Equivalent [`sparse.COO`][] array property.
        - [`numpy.count_nonzero`][] : A similar Numpy function.
        - [`scipy.sparse.coo_matrix.nnz`][] : The Scipy equivalent property.

        Examples
        --------
        >>> values = {
        ...     (1, 2, 3): 4,
        ...     (3, 2, 1): 0,
        ... }
        >>> s = DOK((5, 5, 5), values)
        >>> s.nnz
        1
        """
        return len(self.data)

    @property
    def format(self):
        """
        The storage format of this array.
        Returns
        -------
        str
            The storage format of this array.
        See Also
        -------
        [`scipy.sparse.dok_matrix.format`][] : The Scipy equivalent property.
        Examples
        -------
        >>> import sparse
        >>> s = sparse.random((5, 5), density=0.2, format="dok")
        >>> s.format
        'dok'
        >>> t = sparse.random((5, 5), density=0.2, format="coo")
        >>> t.format
        'coo'
        """
        return "dok"

    @property
    def nbytes(self):
        """
        The number of bytes taken up by this object. Note that for small arrays,
        this may undercount the number of bytes due to the large constant overhead.

        Returns
        -------
        int
            The approximate bytes of memory taken by this object.

        See Also
        --------
        [`numpy.ndarray.nbytes`][] : The equivalent Numpy property.

        Examples
        --------
        >>> import sparse
        >>> x = sparse.random((100, 100), density=0.1, format="dok")
        >>> x.nbytes
        8000
        """
        return self.nnz * self.dtype.itemsize

    def __getitem__(self, key):
        if not isinstance(key, tuple):
            key = (key,)

        if all(isinstance(k, Iterable) for k in key):
            if len(key) != self.ndim:
                raise NotImplementedError(f"Index sequences for all {self.ndim} array dimensions needed!")
            if not all(len(key[0]) == len(k) for k in key):
                raise IndexError("Unequal length of index sequences!")
            return self._fancy_getitem(key)

        key = normalize_index(key, self.shape)

        ret = self.asformat("coo")[key]
        if isinstance(ret, SparseArray):
            ret = ret.asformat("dok")

        return ret

    def _fancy_getitem(self, key):
        """Subset of fancy indexing, when all dimensions are accessed"""
        new_data = {}
        for i, k in enumerate(zip(*key, strict=True)):
            if k in self.data:
                new_data[i] = self.data[k]
        return DOK(
            shape=(len(key[0])),
            data=new_data,
            dtype=self.dtype,
            fill_value=self.fill_value,
        )

    def __setitem__(self, key, value):
        value = np.asarray(value, dtype=self.dtype)

        # 1D fancy indexing
        if self.ndim == 1 and isinstance(key, Iterable) and all(isinstance(i, int | np.integer) for i in key):
            key = (key,)

        if isinstance(key, tuple) and all(isinstance(k, Iterable) for k in key):
            if len(key) != self.ndim:
                raise NotImplementedError(f"Index sequences for all {self.ndim} array dimensions needed!")
            if not all(len(key[0]) == len(k) for k in key):
                raise IndexError("Unequal length of index sequences!")
            self._fancy_setitem(key, value)
            return

        key = normalize_index(key, self.shape)

        key_list = [int(k) if isinstance(k, Integral) else k for k in key]

        self._setitem(key_list, value)

    def _fancy_setitem(self, idxs, values):
        idxs = tuple(np.asanyarray(idxs) for idxs in idxs)
        if not all(np.issubdtype(k.dtype, np.integer) for k in idxs):
            raise IndexError("Indices must be sequences of integer types!")
        if idxs[0].ndim != 1:
            raise IndexError("Indices are not 1d sequences!")
        if values.ndim == 0:
            values = np.full(idxs[0].size, values, self.dtype)
        elif values.ndim > 1:
            raise ValueError(f"Dimension of values ({values.ndim}) must be 0 or 1!")
        if not idxs[0].shape == values.shape:
            raise ValueError(f"Shape mismatch of indices ({idxs[0].shape}) and values ({values.shape})!")
        fill_value = self.fill_value
        data = self.data
        for idx, value in zip(zip(*idxs, strict=True), values, strict=True):
            if value != fill_value:
                data[idx] = value
            elif idx in data:
                del data[idx]

    def _setitem(self, key_list, value):
        value_missing_dims = len([ind for ind in key_list if isinstance(ind, slice)]) - value.ndim

        if value_missing_dims < 0:
            raise ValueError("setting an array element with a sequence.")

        for i, ind in enumerate(key_list):
            if isinstance(ind, slice):
                step = ind.step if ind.step is not None else 1
                if step > 0:
                    start = ind.start if ind.start is not None else 0
                    start = max(start, 0)
                    stop = ind.stop if ind.stop is not None else self.shape[i]
                    stop = min(stop, self.shape[i])
                    if start > stop:
                        start = stop
                else:
                    start = ind.start or self.shape[i] - 1
                    stop = ind.stop if ind.stop is not None else -1
                    start = min(start, self.shape[i] - 1)
                    stop = max(stop, -1)
                    if start < stop:
                        start = stop

                key_list_temp = key_list[:]
                for v_idx, ki in enumerate(range(start, stop, step)):
                    key_list_temp[i] = ki
                    vi = value if value_missing_dims > 0 else (value[0] if value.shape[0] == 1 else value[v_idx])
                    self._setitem(key_list_temp, vi)

                return
            if not isinstance(ind, Integral):
                raise IndexError("All indices must be slices or integers when setting an item.")

        key = tuple(key_list)
        if not equivalent(value, self.fill_value):
            self.data[key] = value[()]
        elif key in self.data:
            del self.data[key]

    def __str__(self):
        summary = f"<DOK: shape={self.shape!s}, dtype={self.dtype!s}, nnz={self.nnz:d}, fill_value={self.fill_value!s}>"
        return self._str_impl(summary)

    __repr__ = __str__

    def todense(self):
        """
        Convert this [`sparse.DOK`][] array into a Numpy array.

        Returns
        -------
        numpy.ndarray
            The equivalent dense array.

        See Also
        --------
        - [`sparse.COO.todense`][] : Equivalent `COO` array method.
        - [`scipy.sparse.coo_matrix.todense`][] : Equivalent Scipy method.

        Examples
        --------
        >>> s = DOK((5, 5))
        >>> s[1:3, 1:3] = [[4, 5], [6, 7]]
        >>> s.todense()  # doctest: +SKIP
        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.]])
        """
        result = np.full(self.shape, self.fill_value, self.dtype)

        for c, d in self.data.items():
            result[c] = d

        return result

    def asformat(self, format, **kwargs):
        """
        Convert this sparse array to a given format.

        Parameters
        ----------
        format : str
            A format string.

        Returns
        -------
        out : SparseArray
            The converted array.

        Raises
        ------
        NotImplementedError
            If the format isn't supported.
        """
        from ._utils import convert_format

        format = convert_format(format)

        if format == "dok":
            return self

        if format == "coo":
            from ._coo import COO

            if len(kwargs) != 0:
                raise ValueError(f"Extra kwargs found: {kwargs}")
            return COO.from_iter(
                self.data,
                shape=self.shape,
                fill_value=self.fill_value,
                dtype=self.dtype,
            )

        return self.asformat("coo").asformat(format, **kwargs)

    def reshape(self, shape, order="C"):
        """
        Returns a new [`sparse.DOK`][] array that is a reshaped version of this array.

        Parameters
        ----------
        shape : tuple[int]
            The desired shape of the output array.

        Returns
        -------
        DOK
            The reshaped output array.

        See Also
        --------
        [`numpy.ndarray.reshape`][] : The equivalent Numpy function.

        Notes
        -----
        The `order` parameter is provided just for compatibility with
        Numpy and isn't actually supported.

        Examples
        --------
        >>> s = DOK.from_numpy(np.arange(25))
        >>> s2 = s.reshape((5, 5))
        >>> s2.todense()  # doctest: +NORMALIZE_WHITESPACE
        array([[ 0,  1,  2,  3,  4],
               [ 5,  6,  7,  8,  9],
               [10, 11, 12, 13, 14],
               [15, 16, 17, 18, 19],
               [20, 21, 22, 23, 24]])
        """
        if order not in {"C", None}:
            raise NotImplementedError("The 'order' parameter is not supported")

        return DOK.from_coo(self.to_coo().reshape(shape))

Attributes

shape = tuple(int(sh) for sh in shape) instance-attribute

fill_value = self.dtype.type(fill_value) instance-attribute

device property

ndim property

The number of dimensions of this array.

Returns:

Type	Description
int	The number of dimensions of this array.

See Also

• sparse.DOK.ndim : Equivalent property for sparse.DOK arrays.
• numpy.ndarray.ndim : Numpy equivalent property.

Examples:

>>> from sparse import COO
>>> import numpy as np
>>> x = np.random.rand(1, 2, 3, 1, 2)
>>> s = COO.from_numpy(x)
>>> s.ndim
5
>>> s.ndim == x.ndim
True

size property

The number of all elements (including zeros) in this array.

Returns:

Type	Description
int	The number of elements.

See Also

numpy.ndarray.size : Numpy equivalent property.

Examples:

>>> from sparse import COO
>>> import numpy as np
>>> x = np.zeros((10, 10))
>>> s = COO.from_numpy(x)
>>> s.size
100

density property

The ratio of nonzero to all elements in this array.

Returns:

Type	Description
float	The ratio of nonzero to all elements.

See Also

• sparse.COO.size : Number of elements.
• sparse.COO.nnz : Number of nonzero elements.

Examples:

>>> import numpy as np
>>> from sparse import COO
>>> x = np.zeros((8, 8))
>>> x[0, :] = 1
>>> s = COO.from_numpy(x)
>>> s.density
0.125

amax = max class-attribute instance-attribute

amin = min class-attribute instance-attribute

round_ = round class-attribute instance-attribute

real property

The real part of the array.

Examples:

>>> from sparse import COO
>>> x = COO.from_numpy([1 + 0j, 0 + 1j])
>>> x.real.todense()
array([1., 0.])
>>> x.real.dtype
dtype('float64')

Returns:

Name	Type	Description
out	SparseArray	The real component of the array elements. If the array dtype is real, the dtype of the array is used for the output. If the array is complex, the output dtype is float.

See Also

• numpy.ndarray.real : NumPy equivalent attribute.
• numpy.real : NumPy equivalent function.

imag property

The imaginary part of the array.

Examples:

>>> from sparse import COO
>>> x = COO.from_numpy([1 + 0j, 0 + 1j])
>>> x.imag.todense()
array([0., 1.])
>>> x.imag.dtype
dtype('float64')

Returns:

Name	Type	Description
out	SparseArray	The imaginary component of the array elements. If the array dtype is real, the dtype of the array is used for the output. If the array is complex, the output dtype is float.

See Also

• numpy.ndarray.imag : NumPy equivalent attribute.
• numpy.imag : NumPy equivalent function.

data = {} instance-attribute

dtype = np.dtype(dtype) instance-attribute

nnz property

The number of nonzero elements in this array.

Returns:

Type	Description
int	The number of nonzero elements.

See Also

• sparse.COO.nnz : Equivalent sparse.COO array property.
• numpy.count_nonzero : A similar Numpy function.
• scipy.sparse.coo_matrix.nnz : The Scipy equivalent property.

Examples:

>>> values = {
...     (1, 2, 3): 4,
...     (3, 2, 1): 0,
... }
>>> s = DOK((5, 5, 5), values)
>>> s.nnz
1

format property

The storage format of this array.

Returns:

Type	Description
str	The storage format of this array.

See Also

scipy.sparse.dok_matrix.format : The Scipy equivalent property.

Examples:

>>> import sparse
>>> s = sparse.random((5, 5), density=0.2, format="dok")
>>> s.format
'dok'
>>> t = sparse.random((5, 5), density=0.2, format="coo")
>>> t.format
'coo'

nbytes property

The number of bytes taken up by this object. Note that for small arrays, this may undercount the number of bytes due to the large constant overhead.

Returns:

Type	Description
int	The approximate bytes of memory taken by this object.

See Also

numpy.ndarray.nbytes : The equivalent Numpy property.

Examples:

>>> import sparse
>>> x = sparse.random((100, 100), density=0.1, format="dok")
>>> x.nbytes
8000

Functions

to_device(device, /, *, stream=None)

Source code in sparse/numba_backend/_sparse_array.py

def to_device(self, device, /, *, stream=None):
    if device != "cpu":
        raise ValueError("Only `device='cpu'` is supported.")

    return self

reduce(method, axis=(0,), keepdims=False, **kwargs)

Performs a reduction operation on this array.

Parameters:

Name	Type	Description	Default
method	ufunc	The method to use for performing the reduction.	required
axis	Union[int, Iterable[int]]	The axes along which to perform the reduction. Uses all axes by default.	(0,)
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False
**kwargs	dict	Any extra arguments to pass to the reduction operation.	{}

See Also

• numpy.ufunc.reduce : A similar Numpy method.
• sparse.COO.reduce : This method implemented on COO arrays.
• sparse.GCXS.reduce : This method implemented on GCXS arrays.

Source code in sparse/numba_backend/_sparse_array.py

def reduce(self, method, axis=(0,), keepdims=False, **kwargs):
    """
    Performs a reduction operation on this array.

    Parameters
    ----------
    method : numpy.ufunc
        The method to use for performing the reduction.
    axis : Union[int, Iterable[int]], optional
        The axes along which to perform the reduction. Uses all axes by default.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.
    **kwargs : dict
        Any extra arguments to pass to the reduction operation.

    See Also
    --------
    - [`numpy.ufunc.reduce`][] : A similar Numpy method.
    - [`sparse.COO.reduce`][] : This method implemented on COO arrays.
    - [`sparse.GCXS.reduce`][] : This method implemented on GCXS arrays.
    """
    axis = normalize_axis(axis, self.ndim)
    zero_reduce_result = method.reduce([self.fill_value, self.fill_value], **kwargs)
    reduce_super_ufunc = _reduce_super_ufunc.get(method)
    if not equivalent(zero_reduce_result, self.fill_value) and reduce_super_ufunc is None:
        raise ValueError(f"Performing this reduction operation would produce a dense result: {method!s}")

    if not isinstance(axis, tuple):
        axis = (axis,)
    out = self._reduce_calc(method, axis, keepdims, **kwargs)
    if len(out) == 1:
        return out[0]
    data, counts, axis, n_cols, arr_attrs = out
    result_fill_value = self.fill_value
    if reduce_super_ufunc is None:
        missing_counts = counts != n_cols
        data[missing_counts] = method(data[missing_counts], self.fill_value, **kwargs)
    else:
        data = method(
            data,
            reduce_super_ufunc(self.fill_value, n_cols - counts),
        ).astype(data.dtype)
        result_fill_value = reduce_super_ufunc(self.fill_value, n_cols)

    out = self._reduce_return(data, arr_attrs, result_fill_value)

    if keepdims:
        shape = list(self.shape)
        for ax in axis:
            shape[ax] = 1
        out = out.reshape(shape)

    if out.ndim == 0:
        return out[()]

    return out

sum(axis=None, keepdims=False, dtype=None, out=None)

Performs a sum operation along the given axes. Uses all axes by default.

Parameters:

Name	Type	Description	Default
axis	Union[int, Iterable[int]]	The axes along which to sum. Uses all axes by default.	None
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False
dtype	dtype	The data type of the output array.	None

Returns:

Type	Description
SparseArray	The reduced output sparse array.

See Also

• numpy.sum : Equivalent numpy function.
• scipy.sparse.coo_matrix.sum : Equivalent Scipy function.

Source code in sparse/numba_backend/_sparse_array.py

def sum(self, axis=None, keepdims=False, dtype=None, out=None):
    """
    Performs a sum operation along the given axes. Uses all axes by default.

    Parameters
    ----------
    axis : Union[int, Iterable[int]], optional
        The axes along which to sum. Uses all axes by default.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.
    dtype : numpy.dtype
        The data type of the output array.

    Returns
    -------
    SparseArray
        The reduced output sparse array.

    See Also
    --------
    - [`numpy.sum`][] : Equivalent numpy function.
    - [`scipy.sparse.coo_matrix.sum`][] : Equivalent Scipy function.
    """
    return np.add.reduce(self, out=out, axis=axis, keepdims=keepdims, dtype=dtype)

max(axis=None, keepdims=False, out=None)

Maximize along the given axes. Uses all axes by default.

Parameters:

Name	Type	Description	Default
axis	Union[int, Iterable[int]]	The axes along which to maximize. Uses all axes by default.	None
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False
out	dtype	The data type of the output array.	None

Returns:

Type	Description
SparseArray	The reduced output sparse array.

See Also

• numpy.max : Equivalent numpy function.
• scipy.sparse.coo_matrix.max : Equivalent Scipy function.

Source code in sparse/numba_backend/_sparse_array.py

def max(self, axis=None, keepdims=False, out=None):
    """
    Maximize along the given axes. Uses all axes by default.

    Parameters
    ----------
    axis : Union[int, Iterable[int]], optional
        The axes along which to maximize. Uses all axes by default.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.
    out : numpy.dtype
        The data type of the output array.

    Returns
    -------
    SparseArray
        The reduced output sparse array.

    See Also
    --------
    - [`numpy.max`][] : Equivalent numpy function.
    - [`scipy.sparse.coo_matrix.max`][] : Equivalent Scipy function.
    """
    return np.maximum.reduce(self, out=out, axis=axis, keepdims=keepdims)

any(axis=None, keepdims=False, out=None)

See if any values along array are True. Uses all axes by default.

Parameters:

Name	Type	Description	Default
axis	Union[int, Iterable[int]]	The axes along which to minimize. Uses all axes by default.	None
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False

Returns:

Type	Description
SparseArray	The reduced output sparse array.

See Also

numpy.any : Equivalent numpy function.

Source code in sparse/numba_backend/_sparse_array.py

def any(self, axis=None, keepdims=False, out=None):
    """
    See if any values along array are ``True``. Uses all axes by default.

    Parameters
    ----------
    axis : Union[int, Iterable[int]], optional
        The axes along which to minimize. Uses all axes by default.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.

    Returns
    -------
    SparseArray
        The reduced output sparse array.

    See Also
    --------
    [`numpy.any`][] : Equivalent numpy function.
    """
    return np.logical_or.reduce(self, out=out, axis=axis, keepdims=keepdims)

all(axis=None, keepdims=False, out=None)

See if all values in an array are True. Uses all axes by default.

Parameters:

Name	Type	Description	Default
axis	Union[int, Iterable[int]]	The axes along which to minimize. Uses all axes by default.	None
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False

Returns:

Type	Description
SparseArray	The reduced output sparse array.

See Also

numpy.all : Equivalent numpy function.

Source code in sparse/numba_backend/_sparse_array.py

def all(self, axis=None, keepdims=False, out=None):
    """
    See if all values in an array are ``True``. Uses all axes by default.

    Parameters
    ----------
    axis : Union[int, Iterable[int]], optional
        The axes along which to minimize. Uses all axes by default.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.

    Returns
    -------
    SparseArray
        The reduced output sparse array.

    See Also
    --------
    [`numpy.all`][] : Equivalent numpy function.
    """
    return np.logical_and.reduce(self, out=out, axis=axis, keepdims=keepdims)

min(axis=None, keepdims=False, out=None)

Minimize along the given axes. Uses all axes by default.

Parameters:

Name	Type	Description	Default
axis	Union[int, Iterable[int]]	The axes along which to minimize. Uses all axes by default.	None
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False
out	dtype	The data type of the output array.	None

Returns:

Type	Description
SparseArray	The reduced output sparse array.

See Also

• numpy.min : Equivalent numpy function.
• scipy.sparse.coo_matrix.min : Equivalent Scipy function.

Source code in sparse/numba_backend/_sparse_array.py

def min(self, axis=None, keepdims=False, out=None):
    """
    Minimize along the given axes. Uses all axes by default.

    Parameters
    ----------
    axis : Union[int, Iterable[int]], optional
        The axes along which to minimize. Uses all axes by default.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.
    out : numpy.dtype
        The data type of the output array.

    Returns
    -------
    SparseArray
        The reduced output sparse array.

    See Also
    --------
    - [`numpy.min`][] : Equivalent numpy function.
    - [`scipy.sparse.coo_matrix.min`][] : Equivalent Scipy function.
    """
    return np.minimum.reduce(self, out=out, axis=axis, keepdims=keepdims)

prod(axis=None, keepdims=False, dtype=None, out=None)

Performs a product operation along the given axes. Uses all axes by default.

Parameters:

Name	Type	Description	Default
axis	Union[int, Iterable[int]]	The axes along which to multiply. Uses all axes by default.	None
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False
dtype	dtype	The data type of the output array.	None

Returns:

Type	Description
SparseArray	The reduced output sparse array.

See Also

numpy.prod : Equivalent numpy function.

Source code in sparse/numba_backend/_sparse_array.py

def prod(self, axis=None, keepdims=False, dtype=None, out=None):
    """
    Performs a product operation along the given axes. Uses all axes by default.

    Parameters
    ----------
    axis : Union[int, Iterable[int]], optional
        The axes along which to multiply. Uses all axes by default.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.
    dtype : numpy.dtype
        The data type of the output array.

    Returns
    -------
    SparseArray
        The reduced output sparse array.

    See Also
    --------
    [`numpy.prod`][] : Equivalent numpy function.
    """
    return np.multiply.reduce(self, out=out, axis=axis, keepdims=keepdims, dtype=dtype)

round(decimals=0, out=None)

Evenly round to the given number of decimals.

See Also

• numpy.round : NumPy equivalent ufunc.
• sparse.elemwise : Apply an arbitrary element-wise function to one or two arguments.

Source code in sparse/numba_backend/_sparse_array.py

def round(self, decimals=0, out=None):
    """
    Evenly round to the given number of decimals.

    See Also
    --------
    - [`numpy.round`][] :
        NumPy equivalent ufunc.
    - [`sparse.elemwise`][] :
        Apply an arbitrary element-wise function to one or two
        arguments.
    """
    if out is not None and not isinstance(out, tuple):
        out = (out,)
    return self.__array_ufunc__(np.round, "__call__", self, decimals=decimals, out=out)

clip(min=None, max=None, out=None)

Clip (limit) the values in the array.

Return an array whose values are limited to [min, max]. One of min or max must be given.

See Also

• sparse.clip : For full documentation and more details.
• numpy.clip : Equivalent NumPy function.

Source code in sparse/numba_backend/_sparse_array.py

def clip(self, min=None, max=None, out=None):
    """
    Clip (limit) the values in the array.

    Return an array whose values are limited to ``[min, max]``. One of min
    or max must be given.

    See Also
    --------
    - [sparse.clip][] : For full documentation and more details.
    - [`numpy.clip`][] : Equivalent NumPy function.
    """
    if min is None and max is None:
        raise ValueError("One of max or min must be given.")
    if out is not None and not isinstance(out, tuple):
        out = (out,)
    return self.__array_ufunc__(np.clip, "__call__", self, a_min=min, a_max=max, out=out)

astype(dtype, casting='unsafe', copy=True)

Copy of the array, cast to a specified type.

See Also

• scipy.sparse.coo_matrix.astype : SciPy sparse equivalent function
• numpy.ndarray.astype : NumPy equivalent ufunc.
• sparse.elemwise : Apply an arbitrary element-wise function to one or two arguments.

Source code in sparse/numba_backend/_sparse_array.py

def astype(self, dtype, casting="unsafe", copy=True):
    """
    Copy of the array, cast to a specified type.

    See Also
    --------
    - [`scipy.sparse.coo_matrix.astype`][] :
        SciPy sparse equivalent function
    - [`numpy.ndarray.astype`][] :
        NumPy equivalent ufunc.
    - [`sparse.elemwise`][] :
        Apply an arbitrary element-wise function to one or two
        arguments.
    """
    # this matches numpy's behavior
    if self.dtype == dtype and not copy:
        return self
    return self.__array_ufunc__(np.ndarray.astype, "__call__", self, dtype=dtype, copy=copy, casting=casting)

mean(axis=None, keepdims=False, dtype=None, out=None)

Compute the mean along the given axes. Uses all axes by default.

Parameters:

Name	Type	Description	Default
axis	Union[int, Iterable[int]]	The axes along which to compute the mean. Uses all axes by default.	None
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False
dtype	dtype	The data type of the output array.	None

Returns:

Type	Description
SparseArray	The reduced output sparse array.

See Also

• numpy.ndarray.mean : Equivalent numpy method.
• scipy.sparse.coo_matrix.mean : Equivalent Scipy method.

Notes

• The out parameter is provided just for compatibility with Numpy and isn't actually supported.

Examples:

You can use sparse.COO.mean to compute the mean of an array across any dimension.

>>> from sparse import COO
>>> x = np.array([[1, 2, 0, 0], [0, 1, 0, 0]], dtype="i8")
>>> s = COO.from_numpy(x)
>>> s2 = s.mean(axis=1)
>>> s2.todense()
array([0.5, 1.5, 0., 0.])

You can also use the keepdims argument to keep the dimensions after the mean.

>>> s3 = s.mean(axis=0, keepdims=True)
>>> s3.shape
(1, 4)

You can pass in an output datatype, if needed.

>>> s4 = s.mean(axis=0, dtype=np.float16)
>>> s4.dtype
dtype('float16')

By default, this reduces the array down to one number, computing the mean along all axes.

>>> s.mean()
np.float64(0.5)

Source code in sparse/numba_backend/_sparse_array.py

def mean(self, axis=None, keepdims=False, dtype=None, out=None):
    """
    Compute the mean along the given axes. Uses all axes by default.

    Parameters
    ----------
    axis : Union[int, Iterable[int]], optional
        The axes along which to compute the mean. Uses all axes by default.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.
    dtype : numpy.dtype
        The data type of the output array.

    Returns
    -------
    SparseArray
        The reduced output sparse array.

    See Also
    --------
    - [`numpy.ndarray.mean`][] : Equivalent numpy method.
    - [`scipy.sparse.coo_matrix.mean`][] : Equivalent Scipy method.

    Notes
    -----
    * The `out` parameter is provided just for compatibility with
      Numpy and isn't actually supported.

    Examples
    --------
    You can use [`sparse.COO.mean`][] to compute the mean of an array across any
    dimension.

    >>> from sparse import COO
    >>> x = np.array([[1, 2, 0, 0], [0, 1, 0, 0]], dtype="i8")
    >>> s = COO.from_numpy(x)
    >>> s2 = s.mean(axis=1)
    >>> s2.todense()  # doctest: +SKIP
    array([0.5, 1.5, 0., 0.])

    You can also use the `keepdims` argument to keep the dimensions
    after the mean.

    >>> s3 = s.mean(axis=0, keepdims=True)
    >>> s3.shape
    (1, 4)

    You can pass in an output datatype, if needed.

    >>> s4 = s.mean(axis=0, dtype=np.float16)
    >>> s4.dtype
    dtype('float16')

    By default, this reduces the array down to one number, computing the
    mean along all axes.

    >>> s.mean()
    np.float64(0.5)
    """

    if axis is None:
        axis = tuple(range(self.ndim))
    elif not isinstance(axis, tuple):
        axis = (axis,)
    den = reduce(operator.mul, (self.shape[i] for i in axis), 1)

    if dtype is None:
        if issubclass(self.dtype.type, np.integer | np.bool_):
            dtype = inter_dtype = np.dtype("f8")
        else:
            dtype = self.dtype
            inter_dtype = np.dtype("f4") if issubclass(dtype.type, np.float16) else dtype
    else:
        inter_dtype = dtype

    num = self.sum(axis=axis, keepdims=keepdims, dtype=inter_dtype)

    if num.ndim:
        out = np.true_divide(num, den, casting="unsafe")
        return out.astype(dtype) if out.dtype != dtype else out
    return np.divide(num, den, dtype=dtype, out=out)

var(axis=None, dtype=None, out=None, ddof=0, keepdims=False)

Compute the variance along the given axes. Uses all axes by default.

Parameters:

Name	Type	Description	Default
axis	Union[int, Iterable[int]]	The axes along which to compute the variance. Uses all axes by default.	None
dtype	dtype	The output datatype.	None
out	SparseArray	The array to write the output to.	None
ddof	int	The degrees of freedom.	0
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False

Returns:

Type	Description
SparseArray	The reduced output sparse array.

See Also

numpy.ndarray.var : Equivalent numpy method.

Examples:

You can use sparse.COO.var to compute the variance of an array across any dimension.

>>> from sparse import COO
>>> x = np.array([[1, 2, 0, 0], [0, 1, 0, 0]], dtype="i8")
>>> s = COO.from_numpy(x)
>>> s2 = s.var(axis=1)
>>> s2.todense()
array([0.6875, 0.1875])

You can also use the keepdims argument to keep the dimensions after the variance.

>>> s3 = s.var(axis=0, keepdims=True)
>>> s3.shape
(1, 4)

You can pass in an output datatype, if needed.

>>> s4 = s.var(axis=0, dtype=np.float16)
>>> s4.dtype
dtype('float16')

By default, this reduces the array down to one number, computing the variance along all axes.

>>> s.var()
np.float64(0.5)

Source code in sparse/numba_backend/_sparse_array.py

def var(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False):
    """
    Compute the variance along the given axes. Uses all axes by default.

    Parameters
    ----------
    axis : Union[int, Iterable[int]], optional
        The axes along which to compute the variance. Uses all axes by default.
    dtype : numpy.dtype, optional
        The output datatype.
    out : SparseArray, optional
        The array to write the output to.
    ddof : int
        The degrees of freedom.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.

    Returns
    -------
    SparseArray
        The reduced output sparse array.

    See Also
    --------
    [`numpy.ndarray.var`][] : Equivalent numpy method.

    Examples
    --------
    You can use [`sparse.COO.var`][] to compute the variance of an array across any
    dimension.

    >>> from sparse import COO
    >>> x = np.array([[1, 2, 0, 0], [0, 1, 0, 0]], dtype="i8")
    >>> s = COO.from_numpy(x)
    >>> s2 = s.var(axis=1)
    >>> s2.todense()  # doctest: +SKIP
    array([0.6875, 0.1875])

    You can also use the `keepdims` argument to keep the dimensions
    after the variance.

    >>> s3 = s.var(axis=0, keepdims=True)
    >>> s3.shape
    (1, 4)

    You can pass in an output datatype, if needed.

    >>> s4 = s.var(axis=0, dtype=np.float16)
    >>> s4.dtype
    dtype('float16')

    By default, this reduces the array down to one number, computing the
    variance along all axes.

    >>> s.var()
    np.float64(0.5)
    """
    axis = normalize_axis(axis, self.ndim)

    if axis is None:
        axis = tuple(range(self.ndim))

    if not isinstance(axis, tuple):
        axis = (axis,)

    rcount = reduce(operator.mul, (self.shape[a] for a in axis), 1)
    # Make this warning show up on top.
    if ddof >= rcount:
        warnings.warn("Degrees of freedom <= 0 for slice", RuntimeWarning, stacklevel=1)

    # Cast bool, unsigned int, and int to float64 by default
    if dtype is None and issubclass(self.dtype.type, np.integer | np.bool_):
        dtype = np.dtype("f8")

    arrmean = self.sum(axis, dtype=dtype, keepdims=True)[...]
    np.divide(arrmean, rcount, out=arrmean)
    x = self - arrmean
    if issubclass(self.dtype.type, np.complexfloating):
        x = x.real * x.real + x.imag * x.imag
    else:
        x = np.multiply(x, x, out=x)

    ret = x.sum(axis=axis, dtype=dtype, out=out, keepdims=keepdims)

    # Compute degrees of freedom and make sure it is not negative.
    rcount = max([rcount - ddof, 0])

    ret = ret[...]
    np.divide(ret, rcount, out=ret, casting="unsafe")
    return ret[()]

std(axis=None, dtype=None, out=None, ddof=0, keepdims=False)

Compute the standard deviation along the given axes. Uses all axes by default.

Parameters:

Name	Type	Description	Default
axis	Union[int, Iterable[int]]	The axes along which to compute the standard deviation. Uses all axes by default.	None
dtype	dtype	The output datatype.	None
out	SparseArray	The array to write the output to.	None
ddof	int	The degrees of freedom.	0
keepdims	bool_	Whether or not to keep the dimensions of the original array.	False

Returns:

Type	Description
SparseArray	The reduced output sparse array.

See Also

numpy.ndarray.std : Equivalent numpy method.

Examples:

You can use sparse.COO.std to compute the standard deviation of an array across any dimension.

>>> from sparse import COO
>>> x = np.array([[1, 2, 0, 0], [0, 1, 0, 0]], dtype="i8")
>>> s = COO.from_numpy(x)
>>> s2 = s.std(axis=1)
>>> s2.todense()
array([0.8291562, 0.4330127])

You can also use the keepdims argument to keep the dimensions after the standard deviation.

>>> s3 = s.std(axis=0, keepdims=True)
>>> s3.shape
(1, 4)

You can pass in an output datatype, if needed.

>>> s4 = s.std(axis=0, dtype=np.float16)
>>> s4.dtype
dtype('float16')

By default, this reduces the array down to one number, computing the standard deviation along all axes.

>>> s.std()
0.7071067811865476

Source code in sparse/numba_backend/_sparse_array.py

def std(self, axis=None, dtype=None, out=None, ddof=0, keepdims=False):
    """
    Compute the standard deviation along the given axes. Uses all axes by default.

    Parameters
    ----------
    axis : Union[int, Iterable[int]], optional
        The axes along which to compute the standard deviation. Uses
        all axes by default.
    dtype : numpy.dtype, optional
        The output datatype.
    out : SparseArray, optional
        The array to write the output to.
    ddof : int
        The degrees of freedom.
    keepdims : bool, optional
        Whether or not to keep the dimensions of the original array.

    Returns
    -------
    SparseArray
        The reduced output sparse array.

    See Also
    --------
    [`numpy.ndarray.std`][] : Equivalent numpy method.

    Examples
    --------
    You can use [`sparse.COO.std`][] to compute the standard deviation of an array
    across any dimension.

    >>> from sparse import COO
    >>> x = np.array([[1, 2, 0, 0], [0, 1, 0, 0]], dtype="i8")
    >>> s = COO.from_numpy(x)
    >>> s2 = s.std(axis=1)
    >>> s2.todense()  # doctest: +SKIP
    array([0.8291562, 0.4330127])

    You can also use the `keepdims` argument to keep the dimensions
    after the standard deviation.

    >>> s3 = s.std(axis=0, keepdims=True)
    >>> s3.shape
    (1, 4)

    You can pass in an output datatype, if needed.

    >>> s4 = s.std(axis=0, dtype=np.float16)
    >>> s4.dtype
    dtype('float16')

    By default, this reduces the array down to one number, computing the
    standard deviation along all axes.

    >>> s.std()  # doctest: +SKIP
    0.7071067811865476
    """
    ret = self.var(axis=axis, dtype=dtype, out=out, ddof=ddof, keepdims=keepdims)

    return np.sqrt(ret)

conj()

Return the complex conjugate, element-wise.

The complex conjugate of a complex number is obtained by changing the sign of its imaginary part.

Examples:

>>> from sparse import COO
>>> x = COO.from_numpy([1 + 2j, 2 - 1j])
>>> res = x.conj()
>>> res.todense()
array([1.-2.j, 2.+1.j])
>>> res.dtype
dtype('complex128')

Returns:

Name	Type	Description
out	SparseArray	The complex conjugate, with same dtype as the input.

See Also

• numpy.ndarray.conj : NumPy equivalent method.
• numpy.conj : NumPy equivalent function.

Source code in sparse/numba_backend/_sparse_array.py

def conj(self):
    """Return the complex conjugate, element-wise.

    The complex conjugate of a complex number is obtained by changing the
    sign of its imaginary part.

    Examples
    --------
    >>> from sparse import COO
    >>> x = COO.from_numpy([1 + 2j, 2 - 1j])
    >>> res = x.conj()
    >>> res.todense()  # doctest: +SKIP
    array([1.-2.j, 2.+1.j])
    >>> res.dtype
    dtype('complex128')

    Returns
    -------
    out : SparseArray
        The complex conjugate, with same dtype as the input.

    See Also
    --------
    - [`numpy.ndarray.conj`][] : NumPy equivalent method.
    - [`numpy.conj`][] : NumPy equivalent function.
    """
    return np.conj(self)

isinf() abstractmethod

Source code in sparse/numba_backend/_sparse_array.py

@abstractmethod
def isinf(self):
    """ """

isnan() abstractmethod

Source code in sparse/numba_backend/_sparse_array.py

@abstractmethod
def isnan(self):
    """ """

from_scipy_sparse(x, /, *, fill_value=None) classmethod

Create a sparse.DOK array from a scipy.sparse.spmatrix.

Parameters:

Name	Type	Description	Default
x	spmatrix	The matrix to convert.	required
fill_value	scalar	The fill-value to use when converting.	None

Returns:

Type	Description
DOK	The equivalent sparse.DOK array.

Examples:

>>> import scipy.sparse
>>> x = scipy.sparse.rand(6, 3, density=0.2)
>>> s = DOK.from_scipy_sparse(x)
>>> np.array_equal(x.todense(), s.todense())
True

Source code in sparse/numba_backend/_dok.py

@classmethod
def from_scipy_sparse(cls, x, /, *, fill_value=None):
    """
    Create a [`sparse.DOK`][] array from a [`scipy.sparse.spmatrix`][].

    Parameters
    ----------
    x : scipy.sparse.spmatrix
        The matrix to convert.
    fill_value : scalar
        The fill-value to use when converting.

    Returns
    -------
    DOK
        The equivalent [`sparse.DOK`][] array.

    Examples
    --------
    >>> import scipy.sparse
    >>> x = scipy.sparse.rand(6, 3, density=0.2)
    >>> s = DOK.from_scipy_sparse(x)
    >>> np.array_equal(x.todense(), s.todense())
    True
    """
    from sparse import COO

    return COO.from_scipy_sparse(x, fill_value=fill_value).asformat(cls)

from_coo(x) classmethod

Get a sparse.DOK array from a sparse.COO array.

Parameters:

Name	Type	Description	Default
x	COO	The array to convert.	required

Returns:

Type	Description
DOK	The equivalent sparse.DOK array.

Examples:

>>> from sparse import COO
>>> s = COO.from_numpy(np.eye(4))
>>> s2 = DOK.from_coo(s)
>>> s2
<DOK: shape=(4, 4), dtype=float64, nnz=4, fill_value=0.0>

Source code in sparse/numba_backend/_dok.py

@classmethod
def from_coo(cls, x):
    """
    Get a [`sparse.DOK`][] array from a [`sparse.COO`][] array.

    Parameters
    ----------
    x : COO
        The array to convert.

    Returns
    -------
    DOK
        The equivalent [`sparse.DOK`][] array.

    Examples
    --------
    >>> from sparse import COO
    >>> s = COO.from_numpy(np.eye(4))
    >>> s2 = DOK.from_coo(s)
    >>> s2
    <DOK: shape=(4, 4), dtype=float64, nnz=4, fill_value=0.0>
    """
    ar = cls(x.shape, dtype=x.dtype, fill_value=x.fill_value)

    for c, d in zip(x.coords.T, x.data, strict=True):
        ar.data[tuple(c)] = d

    return ar

to_coo()

Convert this sparse.DOK array to a sparse.COO array.

Returns:

Type	Description
COO	The equivalent sparse.COO array.

Examples:

>>> s = DOK((5, 5))
>>> s[1:3, 1:3] = [[4, 5], [6, 7]]
>>> s
<DOK: shape=(5, 5), dtype=float64, nnz=4, fill_value=0.0>
>>> s2 = s.to_coo()
>>> s2
<COO: shape=(5, 5), dtype=float64, nnz=4, fill_value=0.0>

Source code in sparse/numba_backend/_dok.py

def to_coo(self):
    """
    Convert this [`sparse.DOK`][] array to a [`sparse.COO`][] array.

    Returns
    -------
    COO
        The equivalent [`sparse.COO`][] array.

    Examples
    --------
    >>> s = DOK((5, 5))
    >>> s[1:3, 1:3] = [[4, 5], [6, 7]]
    >>> s
    <DOK: shape=(5, 5), dtype=float64, nnz=4, fill_value=0.0>
    >>> s2 = s.to_coo()
    >>> s2
    <COO: shape=(5, 5), dtype=float64, nnz=4, fill_value=0.0>
    """
    from ._coo import COO

    return COO(self)

from_numpy(x) classmethod

Get a sparse.DOK array from a Numpy array.

Parameters:

Name	Type	Description	Default
x	ndarray	The array to convert.	required

Returns:

Type	Description
DOK	The equivalent sparse.DOK array.

Examples:

>>> s = DOK.from_numpy(np.eye(4))
>>> s
<DOK: shape=(4, 4), dtype=float64, nnz=4, fill_value=0.0>

Source code in sparse/numba_backend/_dok.py

@classmethod
def from_numpy(cls, x):
    """
    Get a [`sparse.DOK`][] array from a Numpy array.

    Parameters
    ----------
    x : np.ndarray
        The array to convert.

    Returns
    -------
    DOK
        The equivalent [`sparse.DOK`][] array.

    Examples
    --------
    >>> s = DOK.from_numpy(np.eye(4))
    >>> s
    <DOK: shape=(4, 4), dtype=float64, nnz=4, fill_value=0.0>
    """
    ar = cls(x.shape, dtype=x.dtype)

    coords = np.nonzero(x)
    data = x[coords]

    for c in zip(data, *coords, strict=True):
        d, c = c[0], c[1:]
        ar.data[c] = d

    return ar

todense()

Convert this sparse.DOK array into a Numpy array.

Returns:

Type	Description
ndarray	The equivalent dense array.

See Also

• sparse.COO.todense : Equivalent COO array method.
• scipy.sparse.coo_matrix.todense : Equivalent Scipy method.

Examples:

>>> s = DOK((5, 5))
>>> s[1:3, 1:3] = [[4, 5], [6, 7]]
>>> s.todense()
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.]])

Source code in sparse/numba_backend/_dok.py

def todense(self):
    """
    Convert this [`sparse.DOK`][] array into a Numpy array.

    Returns
    -------
    numpy.ndarray
        The equivalent dense array.

    See Also
    --------
    - [`sparse.COO.todense`][] : Equivalent `COO` array method.
    - [`scipy.sparse.coo_matrix.todense`][] : Equivalent Scipy method.

    Examples
    --------
    >>> s = DOK((5, 5))
    >>> s[1:3, 1:3] = [[4, 5], [6, 7]]
    >>> s.todense()  # doctest: +SKIP
    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.]])
    """
    result = np.full(self.shape, self.fill_value, self.dtype)

    for c, d in self.data.items():
        result[c] = d

    return result

asformat(format, **kwargs)

Convert this sparse array to a given format.

Parameters:

Name	Type	Description	Default
format	str	A format string.	required

Returns:

Name	Type	Description
out	SparseArray	The converted array.

Raises:

Type	Description
NotImplementedError	If the format isn't supported.

Source code in sparse/numba_backend/_dok.py

def asformat(self, format, **kwargs):
    """
    Convert this sparse array to a given format.

    Parameters
    ----------
    format : str
        A format string.

    Returns
    -------
    out : SparseArray
        The converted array.

    Raises
    ------
    NotImplementedError
        If the format isn't supported.
    """
    from ._utils import convert_format

    format = convert_format(format)

    if format == "dok":
        return self

    if format == "coo":
        from ._coo import COO

        if len(kwargs) != 0:
            raise ValueError(f"Extra kwargs found: {kwargs}")
        return COO.from_iter(
            self.data,
            shape=self.shape,
            fill_value=self.fill_value,
            dtype=self.dtype,
        )

    return self.asformat("coo").asformat(format, **kwargs)

reshape(shape, order='C')

Returns a new sparse.DOK array that is a reshaped version of this array.

Parameters:

Name	Type	Description	Default
shape	tuple[int]	The desired shape of the output array.	required

Returns:

Type	Description
DOK	The reshaped output array.

See Also

numpy.ndarray.reshape : The equivalent Numpy function.

Notes

The order parameter is provided just for compatibility with Numpy and isn't actually supported.

Examples:

>>> s = DOK.from_numpy(np.arange(25))
>>> s2 = s.reshape((5, 5))
>>> s2.todense()
array([[ 0,  1,  2,  3,  4],
       [ 5,  6,  7,  8,  9],
       [10, 11, 12, 13, 14],
       [15, 16, 17, 18, 19],
       [20, 21, 22, 23, 24]])

Source code in sparse/numba_backend/_dok.py

def reshape(self, shape, order="C"):
    """
    Returns a new [`sparse.DOK`][] array that is a reshaped version of this array.

    Parameters
    ----------
    shape : tuple[int]
        The desired shape of the output array.

    Returns
    -------
    DOK
        The reshaped output array.

    See Also
    --------
    [`numpy.ndarray.reshape`][] : The equivalent Numpy function.

    Notes
    -----
    The `order` parameter is provided just for compatibility with
    Numpy and isn't actually supported.

    Examples
    --------
    >>> s = DOK.from_numpy(np.arange(25))
    >>> s2 = s.reshape((5, 5))
    >>> s2.todense()  # doctest: +NORMALIZE_WHITESPACE
    array([[ 0,  1,  2,  3,  4],
           [ 5,  6,  7,  8,  9],
           [10, 11, 12, 13, 14],
           [15, 16, 17, 18, 19],
           [20, 21, 22, 23, 24]])
    """
    if order not in {"C", None}:
        raise NotImplementedError("The 'order' parameter is not supported")

    return DOK.from_coo(self.to_coo().reshape(shape))