GCXS

Bases: SparseArray, NDArrayOperatorsMixin

A sparse multidimensional array.

This is stored in GCXS format, a generalization of the GCRS/GCCS formats from Efficient storage scheme for n-dimensional sparse array: GCRS/GCCS. GCXS generalizes the CRS/CCS sparse matrix formats.

For arrays with ndim == 2, GCXS is the same CSR/CSC. For arrays with ndim >2, any combination of axes can be compressed, significantly reducing storage.

GCXS consists of 3 arrays. Let the 3 arrays be RO, CO and VL. The first element of array RO is the integer 0 and later elements are the number of cumulative non-zero elements in each row for GCRS, column for GCCS. CO stores column indexes of non-zero elements at each row for GCRS, column for GCCS. VL stores the values of the non-zero array elements.

The superiority of the GCRS/GCCS over traditional (CRS/CCS) is shown by both theoretical analysis and experimental results, outlined in the linked research paper.

Parameters:

Name	Type	Description	Default
arg	tuple(data, indices, indptr)	A tuple of arrays holding the data, indices, and index pointers for the nonzero values of the array.	required
shape	tuple[int](ndim)	The shape of the array.	None
compressed_axes	Iterable[int]	The axes to compress.	None
prune	bool_	A flag indicating whether or not we should prune any fill-values present in the data array.	False
fill_value		The fill value for this array.	None

Attributes:

Name	Type	Description
data	ndarray(nnz)	An array holding the nonzero values corresponding to indices.
indices	ndarray(nnz)	An array holding the coordinates of every nonzero element along uncompressed dimensions.
indptr	ndarray	An array holding the cumulative sums of the nonzeros along the compressed dimensions.
shape	tuple[int](ndim)	The dimensions of this array.

See Also

sparse.DOK : A mostly write-only sparse array.

Source code in sparse/numba_backend/_compressed/compressed.py

class GCXS(SparseArray, NDArrayOperatorsMixin):
    r"""
    A sparse multidimensional array.

    This is stored in GCXS format, a generalization of the GCRS/GCCS formats
    from [Efficient storage scheme for n-dimensional sparse array: GCRS/GCCS](
    https://ieeexplore.ieee.org/document/7237032). GCXS generalizes the CRS/CCS
    sparse matrix formats.

    For arrays with ndim == 2, GCXS is the same CSR/CSC.
    For arrays with ndim >2, any combination of axes can be compressed,
    significantly reducing storage.

    GCXS consists of 3 arrays. Let the 3 arrays be RO, CO and VL. The first element
    of array RO is the integer 0 and later elements are the number of
    cumulative non-zero elements in each row for GCRS, column for
    GCCS. CO stores column indexes of non-zero elements at each row for GCRS, column for GCCS.
    VL stores the values of the non-zero array elements.

    The superiority of the GCRS/GCCS over traditional (CRS/CCS) is shown by both
    theoretical analysis and experimental results, outlined in the linked research paper.

    Parameters
    ----------
    arg : tuple (data, indices, indptr)
        A tuple of arrays holding the data, indices, and
        index pointers for the nonzero values of the array.
    shape : tuple[int] (COO.ndim,)
        The shape of the array.
    compressed_axes : Iterable[int]
        The axes to compress.
    prune : bool, optional
        A flag indicating whether or not we should prune any fill-values present in
        the data array.
    fill_value: scalar, optional
        The fill value for this array.

    Attributes
    ----------
    data : numpy.ndarray (nnz,)
        An array holding the nonzero values corresponding to `indices`.
    indices : numpy.ndarray (nnz,)
        An array holding the coordinates of every nonzero element along uncompressed dimensions.
    indptr : numpy.ndarray
        An array holding the cumulative sums of the nonzeros along the compressed dimensions.
    shape : tuple[int] (ndim,)
        The dimensions of this array.

    See Also
    --------
    [`sparse.DOK`][] : A mostly write-only sparse array.
    """

    __array_priority__ = 12

    def __init__(
        self,
        arg,
        shape=None,
        compressed_axes=None,
        prune=False,
        fill_value=None,
        idx_dtype=None,
    ):
        from .._common import _is_scipy_sparse_obj

        if _is_scipy_sparse_obj(arg):
            arg = self.from_scipy_sparse(arg)

        if isinstance(arg, np.ndarray):
            (arg, shape, compressed_axes, fill_value) = _from_coo(COO(arg), compressed_axes)

        elif isinstance(arg, COO):
            (arg, shape, compressed_axes, fill_value) = _from_coo(arg, compressed_axes, idx_dtype)

        elif isinstance(arg, GCXS):
            if compressed_axes is not None and arg.compressed_axes != compressed_axes:
                arg = arg.change_compressed_axes(compressed_axes)
            (arg, shape, compressed_axes, fill_value) = (
                (arg.data, arg.indices, arg.indptr),
                arg.shape,
                arg.compressed_axes,
                arg.fill_value,
            )

        if shape is None:
            raise ValueError("missing `shape` argument")

        check_compressed_axes(len(shape), compressed_axes)

        if len(shape) == 1:
            compressed_axes = None

        self.data, self.indices, self.indptr = arg

        if self.data.ndim != 1:
            raise ValueError("data must be a scalar or 1-dimensional.")

        self.shape = shape

        if fill_value is None:
            fill_value = _zero_of_dtype(self.data.dtype)

        self._compressed_axes = tuple(compressed_axes) if isinstance(compressed_axes, Iterable) else None
        self.fill_value = self.data.dtype.type(fill_value)

        if prune:
            self._prune()

    def copy(self, deep=True):
        """Return a copy of the array.

        Parameters
        ----------
        deep : boolean, optional
            If True (default), the internal coords and data arrays are also
            copied. Set to ``False`` to only make a shallow copy.
        """
        return _copy.deepcopy(self) if deep else _copy.copy(self)

    @classmethod
    def from_numpy(cls, x, compressed_axes=None, fill_value=None, idx_dtype=None):
        coo = COO.from_numpy(x, fill_value=fill_value, idx_dtype=idx_dtype)
        return cls.from_coo(coo, compressed_axes, idx_dtype)

    @classmethod
    def from_coo(cls, x, compressed_axes=None, idx_dtype=None):
        (arg, shape, compressed_axes, fill_value) = _from_coo(x, compressed_axes, idx_dtype)
        return cls(arg, shape=shape, compressed_axes=compressed_axes, fill_value=fill_value)

    @classmethod
    def from_scipy_sparse(cls, x, /, *, fill_value=None):
        if x.format == "csc":
            return cls((x.data, x.indices, x.indptr), shape=x.shape, compressed_axes=(1,), fill_value=fill_value)

        x = x.asformat("csr")
        return cls((x.data, x.indices, x.indptr), shape=x.shape, compressed_axes=(0,), fill_value=fill_value)

    @classmethod
    def from_iter(cls, x, shape=None, compressed_axes=None, fill_value=None, idx_dtype=None):
        return cls.from_coo(
            COO.from_iter(x, shape, fill_value),
            compressed_axes,
            idx_dtype,
        )

    @property
    def dtype(self):
        """
        The datatype of this array.

        Returns
        -------
        numpy.dtype
            The datatype of this array.

        See Also
        --------
        - [`numpy.ndarray.dtype`][] : Numpy equivalent property.
        - [`scipy.sparse.csr_matrix.dtype`][] : Scipy equivalent property.
        """
        return self.data.dtype

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

        Returns
        -------
        int
            The number of nonzero elements in this array.

        See Also
        --------
        - [`sparse.COO.nnz`][] : Equivalent [`sparse.COO`][] array property.
        - [`sparse.DOK.nnz`][] : Equivalent [`sparse.DOK`][] array property.
        - [`numpy.count_nonzero`][] : A similar Numpy function.
        - [`scipy.sparse.coo_matrix.nnz`][] : The Scipy equivalent property.
        """
        return self.data.shape[0]

    @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 "gcxs"

    @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.
        """
        return self.data.nbytes + self.indices.nbytes + self.indptr.nbytes

    @property
    def _axis_order(self):
        axis_order = list(self.compressed_axes)
        axis_order.extend(np.setdiff1d(np.arange(len(self.shape)), self.compressed_axes))
        return axis_order

    @property
    def _axisptr(self):
        # array location where the uncompressed dimensions start
        return len(self.compressed_axes)

    @property
    def _compressed_shape(self):
        row_size = np.prod(self._reordered_shape[: self._axisptr])
        col_size = np.prod(self._reordered_shape[self._axisptr :])
        return (row_size, col_size)

    @property
    def _reordered_shape(self):
        return tuple(self.shape[i] for i in self._axis_order)

    @property
    def T(self):
        return self.transpose()

    @property
    def mT(self):
        if self.ndim < 2:
            raise ValueError("Cannot compute matrix transpose if `ndim < 2`.")

        axis = list(range(self.ndim))
        axis[-1], axis[-2] = axis[-2], axis[-1]

        return self.transpose(axis)

    def __str__(self):
        summary = (
            f"<GCXS: shape={self.shape}, dtype={self.dtype}, nnz={self.nnz}, fill_value={self.fill_value}, "
            f"compressed_axes={self.compressed_axes}>"
        )
        return self._str_impl(summary)

    __repr__ = __str__

    __getitem__ = getitem

    def _reduce_calc(self, method, axis, keepdims=False, **kwargs):
        if axis[0] is None or np.array_equal(axis, np.arange(self.ndim, dtype=np.intp)):
            x = self.flatten().tocoo()
            out = x.reduce(method, axis=None, keepdims=keepdims, **kwargs)
            if keepdims:
                return (out.reshape(np.ones(self.ndim, dtype=np.intp)),)
            return (out,)

        r = np.arange(self.ndim, dtype=np.intp)
        compressed_axes = [a for a in r if a not in set(axis)]
        x = self.change_compressed_axes(compressed_axes)
        idx = np.diff(x.indptr) != 0
        indptr = x.indptr[:-1][idx]
        indices = (np.arange(x._compressed_shape[0], dtype=self.indptr.dtype))[idx]
        data = method.reduceat(x.data, indptr, **kwargs)
        counts = x.indptr[1:][idx] - x.indptr[:-1][idx]
        arr_attrs = (x, compressed_axes, indices)
        n_cols = x._compressed_shape[1]
        return (data, counts, axis, n_cols, arr_attrs)

    def _reduce_return(self, data, arr_attrs, result_fill_value):
        x, compressed_axes, indices = arr_attrs
        # prune data
        mask = ~equivalent(data, result_fill_value)
        data = data[mask]
        indices = indices[mask]
        out = GCXS(
            (data, indices, []),
            shape=(x._compressed_shape[0],),
            fill_value=result_fill_value,
            compressed_axes=None,
        )
        return out.reshape(tuple(self.shape[d] for d in compressed_axes))

    def change_compressed_axes(self, new_compressed_axes):
        """
        Returns a new array with specified compressed axes. This operation is similar to converting
        a scipy.sparse.csc_matrix to a scipy.sparse.csr_matrix.

        Returns
        -------
        GCXS
            A new instance of the input array with compression along the specified dimensions.
        """
        if new_compressed_axes == self.compressed_axes:
            return self

        if self.ndim == 1:
            raise NotImplementedError("no axes to compress for 1d array")

        new_compressed_axes = tuple(
            normalize_axis(new_compressed_axes[i], self.ndim) for i in range(len(new_compressed_axes))
        )

        if new_compressed_axes == self.compressed_axes:
            return self

        if len(new_compressed_axes) >= len(self.shape):
            raise ValueError("cannot compress all axes")
        if len(set(new_compressed_axes)) != len(new_compressed_axes):
            raise ValueError("repeated axis in compressed_axes")

        arg = _transpose(self, self.shape, np.arange(self.ndim), new_compressed_axes)

        return GCXS(
            arg,
            shape=self.shape,
            compressed_axes=new_compressed_axes,
            fill_value=self.fill_value,
        )

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

        Returns
        -------
        sparse.COO
            The converted COO array.
        """
        if self.ndim == 0:
            return COO(
                np.array([]),
                self.data,
                shape=self.shape,
                fill_value=self.fill_value,
            )
        if self.ndim == 1:
            return COO(
                self.indices[None, :],
                self.data,
                shape=self.shape,
                fill_value=self.fill_value,
            )
        uncompressed = uncompress_dimension(self.indptr)
        coords = np.vstack((uncompressed, self.indices))
        order = np.argsort(self._axis_order)
        return (
            COO(
                coords,
                self.data,
                shape=self._compressed_shape,
                fill_value=self.fill_value,
            )
            .reshape(self._reordered_shape)
            .transpose(order)
        )

    def todense(self):
        """
        Convert this [`sparse.GCXS`][] array to a dense [`numpy.ndarray`][]. Note that
        this may take a large amount of memory if the [`sparse.GCXS`][] object's `shape`
        is large.

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

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

        """
        if self.compressed_axes is None:
            out = np.full(self.shape, self.fill_value, self.dtype)
            if len(self.indices) != 0:
                out[self.indices] = self.data
            else:
                if len(self.data) != 0:
                    out[()] = self.data[0]
            return out
        return self.tocoo().todense()

    def todok(self):
        from .. import DOK

        return DOK.from_coo(self.tocoo())  # probably a temporary solution

    def to_scipy_sparse(self, accept_fv=None):
        """
        Converts this [`sparse.GCXS`][] object into a [`scipy.sparse.csr_matrix`][] or [`scipy.sparse.csc_matrix`][].

        Parameters
        ----------
        accept_fv : scalar or list of scalar, optional
            The list of accepted fill-values. The default accepts only zero.

        Returns
        -------
        scipy.sparse.csr_matrix or scipy.sparse.csc_matrix
            The converted Scipy sparse matrix.

        Raises
        ------
        ValueError
            If the array is not two-dimensional.
        ValueError
            If all the array doesn't zero fill-values.
        """
        import scipy.sparse

        check_fill_value(self, accept_fv=accept_fv)
        if self.ndim != 2:
            raise ValueError("Can only convert a 2-dimensional array to a Scipy sparse matrix.")

        if 0 in self.compressed_axes:
            return scipy.sparse.csr_matrix((self.data, self.indices, self.indptr), shape=self.shape)

        return scipy.sparse.csc_matrix((self.data, self.indices, self.indptr), shape=self.shape)

    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)
        ret = None

        if format == "coo":
            ret = self.tocoo()
        elif format == "dok":
            ret = self.todok()
        elif format == "csr":
            ret = CSR(self)
        elif format == "csc":
            ret = CSC(self)
        elif format == "gcxs":
            compressed_axes = kwargs.pop("compressed_axes", self.compressed_axes)
            return self.change_compressed_axes(compressed_axes)

        if len(kwargs) != 0:
            raise TypeError(f"Invalid keyword arguments provided: {kwargs}")

        if ret is None:
            raise NotImplementedError(f"The given format is not supported: {format}")

        return ret

    def maybe_densify(self, max_size=1000, min_density=0.25):
        """
        Converts this [`sparse.GCXS`][] array to a [`numpy.ndarray`][] if not too
        costly.

        Parameters
        ----------
        max_size : int
            Maximum number of elements in output
        min_density : float
            Minimum density of output

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

        See Also
        --------
        - [sparse.GCXS.todense][]: Converts to Numpy function without checking the cost.
        - [sparse.COO.maybe_densify][]: The equivalent COO function.

        Raises
        -------
        ValueError
            If the returned array would be too large.
        """

        if self.size > max_size and self.density < min_density:
            raise ValueError("Operation would require converting large sparse array to dense")

        return self.todense()

    def flatten(self, order="C"):
        """
        Returns a new [`sparse.GCXS`][] array that is a flattened version of this array.

        Returns
        -------
        GCXS
            The flattened output array.

        Notes
        -----
        The `order` parameter is provided just for compatibility with
        Numpy and isn't actually supported.
        """
        if order not in {"C", None}:
            raise NotImplementedError("The `order` parameter is not supported.")

        return self.reshape(-1)

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

        Parameters
        ----------
        shape : tuple[int]
            The desired shape of the output array.
        compressed_axes : Iterable[int], optional
            The axes to compress to store the array. Finds the most efficient storage
            by default.

        Returns
        -------
        GCXS
            The reshaped output array.

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

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

        """
        shape = tuple(shape) if isinstance(shape, Iterable) else (shape,)
        if order not in {"C", None}:
            raise NotImplementedError("The 'order' parameter is not supported")
        if any(d == -1 for d in shape):
            extra = int(self.size / np.prod([d for d in shape if d != -1]))
            shape = tuple([d if d != -1 else extra for d in shape])

        if self.shape == shape:
            return self

        if self.size != reduce(operator.mul, shape, 1):
            raise ValueError(f"cannot reshape array of size {self.size} into shape {shape}")
        if len(shape) == 0:
            return self.tocoo().reshape(shape).asformat("gcxs")

        if compressed_axes is None:
            if len(shape) == self.ndim:
                compressed_axes = self.compressed_axes
            elif len(shape) == 1:
                compressed_axes = None
            else:
                compressed_axes = (np.argmin(shape),)

        if self.ndim == 1:
            arg = _1d_reshape(self, shape, compressed_axes)
        else:
            arg = _transpose(self, shape, np.arange(self.ndim), compressed_axes)
        return GCXS(
            arg,
            shape=tuple(shape),
            compressed_axes=compressed_axes,
            fill_value=self.fill_value,
        )

    @property
    def compressed_axes(self):
        return self._compressed_axes

    def transpose(self, axes=None, compressed_axes=None):
        """
        Returns a new array which has the order of the axes switched.

        Parameters
        ----------
        axes : Iterable[int], optional
            The new order of the axes compared to the previous one. Reverses the axes
            by default.
        compressed_axes : Iterable[int], optional
            The axes to compress to store the array. Finds the most efficient storage
            by default.

        Returns
        -------
        GCXS
            The new array with the axes in the desired order.

        See Also
        --------
        - [`sparse.GCXS.T`][] : A quick property to reverse the order of the axes.
        - [`numpy.ndarray.transpose`][] : Numpy equivalent function.
        """
        if axes is None:
            axes = list(reversed(range(self.ndim)))

        # Normalize all axes indices to positive values
        axes = normalize_axis(axes, self.ndim)

        if len(np.unique(axes)) < len(axes):
            raise ValueError("repeated axis in transpose")

        if not len(axes) == self.ndim:
            raise ValueError("axes don't match array")

        axes = tuple(axes)

        if axes == tuple(range(self.ndim)):
            return self

        if self.ndim == 2:
            return self._2d_transpose()

        shape = tuple(self.shape[ax] for ax in axes)

        if compressed_axes is None:
            compressed_axes = (np.argmin(shape),)
        arg = _transpose(self, shape, axes, compressed_axes, transpose=True)
        return GCXS(
            arg,
            shape=shape,
            compressed_axes=compressed_axes,
            fill_value=self.fill_value,
        )

    def _2d_transpose(self):
        """
        A function for performing constant-time transposes on 2d GCXS arrays.

        Returns
        -------
        GCXS
            The new transposed array with the opposite compressed axes as the input.

        See Also
        --------
        scipy.sparse.csr_matrix.transpose : Scipy equivalent function.
        scipy.sparse.csc_matrix.transpose : Scipy equivalent function.
        numpy.ndarray.transpose : Numpy equivalent function.
        """
        if self.ndim != 2:
            raise ValueError(f"cannot perform 2d transpose on array with dimension {self.ndim}")

        compressed_axes = [(self.compressed_axes[0] + 1) % 2]
        shape = self.shape[::-1]
        return GCXS(
            (self.data, self.indices, self.indptr),
            shape=shape,
            compressed_axes=compressed_axes,
            fill_value=self.fill_value,
        )

    def dot(self, other):
        """
        Performs the equivalent of `x.dot(y)` for [`sparse.GCXS`][].

        Parameters
        ----------
        other : Union[GCXS, COO, numpy.ndarray, scipy.sparse.spmatrix]
            The second operand of the dot product operation.

        Returns
        -------
        {GCXS, numpy.ndarray}
            The result of the dot product. If the result turns out to be dense,
            then a dense array is returned, otherwise, a sparse array.

        Raises
        ------
        ValueError
            If all arguments don't have zero fill-values.

        See Also
        --------
        - [`sparse.dot`][] : Equivalent function for two arguments.
        - [`numpy.dot`][] : Numpy equivalent function.
        - [`scipy.sparse.coo_matrix.dot`][] : Scipy equivalent function.
        """
        from .._common import dot

        return dot(self, other)

    def __matmul__(self, other):
        from .._common import matmul

        try:
            return matmul(self, other)
        except NotImplementedError:
            return NotImplemented

    def __rmatmul__(self, other):
        from .._common import matmul

        try:
            return matmul(other, self)
        except NotImplementedError:
            return NotImplemented

    def _prune(self):
        """
        Prunes data so that if any fill-values are present, they are removed
        from both indices and data.

        Examples
        --------
        >>> coords = np.array([[0, 1, 2, 3]])
        >>> data = np.array([1, 0, 1, 2])
        >>> s = COO(coords, data, shape=(4,)).asformat("gcxs")
        >>> s._prune()
        >>> s.nnz
        3
        """
        mask = ~equivalent(self.data, self.fill_value)
        self.data = self.data[mask]
        if len(self.indptr):
            coords = np.stack((uncompress_dimension(self.indptr), self.indices))
            coords = coords[:, mask]
            self.indices = coords[1]
            row_size = self._compressed_shape[0]
            indptr = np.empty(row_size + 1, dtype=self.indptr.dtype)
            indptr[0] = 0
            np.cumsum(np.bincount(coords[0], minlength=row_size), out=indptr[1:])
            self.indptr = indptr
        else:
            self.indices = self.indices[mask]

    def isinf(self):
        return self.tocoo().isinf().asformat("gcxs", compressed_axes=self.compressed_axes)

    def isnan(self):
        return self.tocoo().isnan().asformat("gcxs", compressed_axes=self.compressed_axes)

Attributes

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.

shape = shape instance-attribute

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

dtype property

The datatype of this array.

Returns:

Type	Description
dtype	The datatype of this array.

See Also

• numpy.ndarray.dtype : Numpy equivalent property.
• scipy.sparse.csr_matrix.dtype : Scipy equivalent property.

nnz property

The number of nonzero elements in this array.

Returns:

Type	Description
int	The number of nonzero elements in this array.

See Also

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

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.

T property

mT property

compressed_axes property

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)

copy(deep=True)

Return a copy of the array.

Parameters:

Name	Type	Description	Default
deep	boolean	If True (default), the internal coords and data arrays are also copied. Set to False to only make a shallow copy.	True

Source code in sparse/numba_backend/_compressed/compressed.py

def copy(self, deep=True):
    """Return a copy of the array.

    Parameters
    ----------
    deep : boolean, optional
        If True (default), the internal coords and data arrays are also
        copied. Set to ``False`` to only make a shallow copy.
    """
    return _copy.deepcopy(self) if deep else _copy.copy(self)

from_numpy(x, compressed_axes=None, fill_value=None, idx_dtype=None) classmethod

Source code in sparse/numba_backend/_compressed/compressed.py

@classmethod
def from_numpy(cls, x, compressed_axes=None, fill_value=None, idx_dtype=None):
    coo = COO.from_numpy(x, fill_value=fill_value, idx_dtype=idx_dtype)
    return cls.from_coo(coo, compressed_axes, idx_dtype)

from_coo(x, compressed_axes=None, idx_dtype=None) classmethod

Source code in sparse/numba_backend/_compressed/compressed.py

@classmethod
def from_coo(cls, x, compressed_axes=None, idx_dtype=None):
    (arg, shape, compressed_axes, fill_value) = _from_coo(x, compressed_axes, idx_dtype)
    return cls(arg, shape=shape, compressed_axes=compressed_axes, fill_value=fill_value)

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

Source code in sparse/numba_backend/_compressed/compressed.py

@classmethod
def from_scipy_sparse(cls, x, /, *, fill_value=None):
    if x.format == "csc":
        return cls((x.data, x.indices, x.indptr), shape=x.shape, compressed_axes=(1,), fill_value=fill_value)

    x = x.asformat("csr")
    return cls((x.data, x.indices, x.indptr), shape=x.shape, compressed_axes=(0,), fill_value=fill_value)

from_iter(x, shape=None, compressed_axes=None, fill_value=None, idx_dtype=None) classmethod

Source code in sparse/numba_backend/_compressed/compressed.py

@classmethod
def from_iter(cls, x, shape=None, compressed_axes=None, fill_value=None, idx_dtype=None):
    return cls.from_coo(
        COO.from_iter(x, shape, fill_value),
        compressed_axes,
        idx_dtype,
    )

change_compressed_axes(new_compressed_axes)

Returns a new array with specified compressed axes. This operation is similar to converting a scipy.sparse.csc_matrix to a scipy.sparse.csr_matrix.

Returns:

Type	Description
GCXS	A new instance of the input array with compression along the specified dimensions.

Source code in sparse/numba_backend/_compressed/compressed.py

def change_compressed_axes(self, new_compressed_axes):
    """
    Returns a new array with specified compressed axes. This operation is similar to converting
    a scipy.sparse.csc_matrix to a scipy.sparse.csr_matrix.

    Returns
    -------
    GCXS
        A new instance of the input array with compression along the specified dimensions.
    """
    if new_compressed_axes == self.compressed_axes:
        return self

    if self.ndim == 1:
        raise NotImplementedError("no axes to compress for 1d array")

    new_compressed_axes = tuple(
        normalize_axis(new_compressed_axes[i], self.ndim) for i in range(len(new_compressed_axes))
    )

    if new_compressed_axes == self.compressed_axes:
        return self

    if len(new_compressed_axes) >= len(self.shape):
        raise ValueError("cannot compress all axes")
    if len(set(new_compressed_axes)) != len(new_compressed_axes):
        raise ValueError("repeated axis in compressed_axes")

    arg = _transpose(self, self.shape, np.arange(self.ndim), new_compressed_axes)

    return GCXS(
        arg,
        shape=self.shape,
        compressed_axes=new_compressed_axes,
        fill_value=self.fill_value,
    )

tocoo()

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

Returns:

Type	Description
COO	The converted COO array.

Source code in sparse/numba_backend/_compressed/compressed.py

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

    Returns
    -------
    sparse.COO
        The converted COO array.
    """
    if self.ndim == 0:
        return COO(
            np.array([]),
            self.data,
            shape=self.shape,
            fill_value=self.fill_value,
        )
    if self.ndim == 1:
        return COO(
            self.indices[None, :],
            self.data,
            shape=self.shape,
            fill_value=self.fill_value,
        )
    uncompressed = uncompress_dimension(self.indptr)
    coords = np.vstack((uncompressed, self.indices))
    order = np.argsort(self._axis_order)
    return (
        COO(
            coords,
            self.data,
            shape=self._compressed_shape,
            fill_value=self.fill_value,
        )
        .reshape(self._reordered_shape)
        .transpose(order)
    )

todense()

Convert this sparse.GCXS array to a dense numpy.ndarray. Note that this may take a large amount of memory if the sparse.GCXS object's shape is large.

Returns:

Type	Description
ndarray	The converted dense array.

See Also

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

Source code in sparse/numba_backend/_compressed/compressed.py

def todense(self):
    """
    Convert this [`sparse.GCXS`][] array to a dense [`numpy.ndarray`][]. Note that
    this may take a large amount of memory if the [`sparse.GCXS`][] object's `shape`
    is large.

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

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

    """
    if self.compressed_axes is None:
        out = np.full(self.shape, self.fill_value, self.dtype)
        if len(self.indices) != 0:
            out[self.indices] = self.data
        else:
            if len(self.data) != 0:
                out[()] = self.data[0]
        return out
    return self.tocoo().todense()

todok()

Source code in sparse/numba_backend/_compressed/compressed.py

def todok(self):
    from .. import DOK

    return DOK.from_coo(self.tocoo())  # probably a temporary solution

to_scipy_sparse(accept_fv=None)

Converts this sparse.GCXS object into a scipy.sparse.csr_matrix or scipy.sparse.csc_matrix.

Parameters:

Name	Type	Description	Default
accept_fv	scalar or list of scalar	The list of accepted fill-values. The default accepts only zero.	None

Returns:

Type	Description
csr_matrix or csc_matrix	The converted Scipy sparse matrix.

Raises:

Type	Description
ValueError	If the array is not two-dimensional.
ValueError	If all the array doesn't zero fill-values.

Source code in sparse/numba_backend/_compressed/compressed.py

def to_scipy_sparse(self, accept_fv=None):
    """
    Converts this [`sparse.GCXS`][] object into a [`scipy.sparse.csr_matrix`][] or [`scipy.sparse.csc_matrix`][].

    Parameters
    ----------
    accept_fv : scalar or list of scalar, optional
        The list of accepted fill-values. The default accepts only zero.

    Returns
    -------
    scipy.sparse.csr_matrix or scipy.sparse.csc_matrix
        The converted Scipy sparse matrix.

    Raises
    ------
    ValueError
        If the array is not two-dimensional.
    ValueError
        If all the array doesn't zero fill-values.
    """
    import scipy.sparse

    check_fill_value(self, accept_fv=accept_fv)
    if self.ndim != 2:
        raise ValueError("Can only convert a 2-dimensional array to a Scipy sparse matrix.")

    if 0 in self.compressed_axes:
        return scipy.sparse.csr_matrix((self.data, self.indices, self.indptr), shape=self.shape)

    return scipy.sparse.csc_matrix((self.data, self.indices, self.indptr), shape=self.shape)

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/_compressed/compressed.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)
    ret = None

    if format == "coo":
        ret = self.tocoo()
    elif format == "dok":
        ret = self.todok()
    elif format == "csr":
        ret = CSR(self)
    elif format == "csc":
        ret = CSC(self)
    elif format == "gcxs":
        compressed_axes = kwargs.pop("compressed_axes", self.compressed_axes)
        return self.change_compressed_axes(compressed_axes)

    if len(kwargs) != 0:
        raise TypeError(f"Invalid keyword arguments provided: {kwargs}")

    if ret is None:
        raise NotImplementedError(f"The given format is not supported: {format}")

    return ret

maybe_densify(max_size=1000, min_density=0.25)

Converts this sparse.GCXS array to a numpy.ndarray if not too costly.

Parameters:

Name	Type	Description	Default
max_size	int	Maximum number of elements in output	1000
min_density	float	Minimum density of output	0.25

Returns:

Type	Description
ndarray	The dense array.

See Also

• sparse.GCXS.todense: Converts to Numpy function without checking the cost.
• sparse.COO.maybe_densify: The equivalent COO function.

Raises:

Type	Description
ValueError	If the returned array would be too large.

Source code in sparse/numba_backend/_compressed/compressed.py

def maybe_densify(self, max_size=1000, min_density=0.25):
    """
    Converts this [`sparse.GCXS`][] array to a [`numpy.ndarray`][] if not too
    costly.

    Parameters
    ----------
    max_size : int
        Maximum number of elements in output
    min_density : float
        Minimum density of output

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

    See Also
    --------
    - [sparse.GCXS.todense][]: Converts to Numpy function without checking the cost.
    - [sparse.COO.maybe_densify][]: The equivalent COO function.

    Raises
    -------
    ValueError
        If the returned array would be too large.
    """

    if self.size > max_size and self.density < min_density:
        raise ValueError("Operation would require converting large sparse array to dense")

    return self.todense()

flatten(order='C')

Returns a new sparse.GCXS array that is a flattened version of this array.

Returns:

Type	Description
GCXS	The flattened output array.

Notes

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

Source code in sparse/numba_backend/_compressed/compressed.py

def flatten(self, order="C"):
    """
    Returns a new [`sparse.GCXS`][] array that is a flattened version of this array.

    Returns
    -------
    GCXS
        The flattened output array.

    Notes
    -----
    The `order` parameter is provided just for compatibility with
    Numpy and isn't actually supported.
    """
    if order not in {"C", None}:
        raise NotImplementedError("The `order` parameter is not supported.")

    return self.reshape(-1)

reshape(shape, order='C', compressed_axes=None)

Returns a new sparse.GCXS 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
compressed_axes	Iterable[int]	The axes to compress to store the array. Finds the most efficient storage by default.	None

Returns:

Type	Description
GCXS	The reshaped output array.

See Also

• numpy.ndarray.reshape : The equivalent Numpy function.
• sparse.COO.reshape : The equivalent COO function.

Notes

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

Source code in sparse/numba_backend/_compressed/compressed.py

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

    Parameters
    ----------
    shape : tuple[int]
        The desired shape of the output array.
    compressed_axes : Iterable[int], optional
        The axes to compress to store the array. Finds the most efficient storage
        by default.

    Returns
    -------
    GCXS
        The reshaped output array.

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

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

    """
    shape = tuple(shape) if isinstance(shape, Iterable) else (shape,)
    if order not in {"C", None}:
        raise NotImplementedError("The 'order' parameter is not supported")
    if any(d == -1 for d in shape):
        extra = int(self.size / np.prod([d for d in shape if d != -1]))
        shape = tuple([d if d != -1 else extra for d in shape])

    if self.shape == shape:
        return self

    if self.size != reduce(operator.mul, shape, 1):
        raise ValueError(f"cannot reshape array of size {self.size} into shape {shape}")
    if len(shape) == 0:
        return self.tocoo().reshape(shape).asformat("gcxs")

    if compressed_axes is None:
        if len(shape) == self.ndim:
            compressed_axes = self.compressed_axes
        elif len(shape) == 1:
            compressed_axes = None
        else:
            compressed_axes = (np.argmin(shape),)

    if self.ndim == 1:
        arg = _1d_reshape(self, shape, compressed_axes)
    else:
        arg = _transpose(self, shape, np.arange(self.ndim), compressed_axes)
    return GCXS(
        arg,
        shape=tuple(shape),
        compressed_axes=compressed_axes,
        fill_value=self.fill_value,
    )

transpose(axes=None, compressed_axes=None)

Returns a new array which has the order of the axes switched.

Parameters:

Name	Type	Description	Default
axes	Iterable[int]	The new order of the axes compared to the previous one. Reverses the axes by default.	None
compressed_axes	Iterable[int]	The axes to compress to store the array. Finds the most efficient storage by default.	None

Returns:

Type	Description
GCXS	The new array with the axes in the desired order.

See Also

• sparse.GCXS.T : A quick property to reverse the order of the axes.
• numpy.ndarray.transpose : Numpy equivalent function.

Source code in sparse/numba_backend/_compressed/compressed.py

def transpose(self, axes=None, compressed_axes=None):
    """
    Returns a new array which has the order of the axes switched.

    Parameters
    ----------
    axes : Iterable[int], optional
        The new order of the axes compared to the previous one. Reverses the axes
        by default.
    compressed_axes : Iterable[int], optional
        The axes to compress to store the array. Finds the most efficient storage
        by default.

    Returns
    -------
    GCXS
        The new array with the axes in the desired order.

    See Also
    --------
    - [`sparse.GCXS.T`][] : A quick property to reverse the order of the axes.
    - [`numpy.ndarray.transpose`][] : Numpy equivalent function.
    """
    if axes is None:
        axes = list(reversed(range(self.ndim)))

    # Normalize all axes indices to positive values
    axes = normalize_axis(axes, self.ndim)

    if len(np.unique(axes)) < len(axes):
        raise ValueError("repeated axis in transpose")

    if not len(axes) == self.ndim:
        raise ValueError("axes don't match array")

    axes = tuple(axes)

    if axes == tuple(range(self.ndim)):
        return self

    if self.ndim == 2:
        return self._2d_transpose()

    shape = tuple(self.shape[ax] for ax in axes)

    if compressed_axes is None:
        compressed_axes = (np.argmin(shape),)
    arg = _transpose(self, shape, axes, compressed_axes, transpose=True)
    return GCXS(
        arg,
        shape=shape,
        compressed_axes=compressed_axes,
        fill_value=self.fill_value,
    )

dot(other)

Performs the equivalent of x.dot(y) for sparse.GCXS.

Parameters:

Name	Type	Description	Default
other	Union[GCXS, COO, ndarray, spmatrix]	The second operand of the dot product operation.	required

Returns:

Type	Description
{GCXS, ndarray}	The result of the dot product. If the result turns out to be dense, then a dense array is returned, otherwise, a sparse array.

Raises:

Type	Description
ValueError	If all arguments don't have zero fill-values.

See Also

• sparse.dot : Equivalent function for two arguments.
• numpy.dot : Numpy equivalent function.
• scipy.sparse.coo_matrix.dot : Scipy equivalent function.

Source code in sparse/numba_backend/_compressed/compressed.py

def dot(self, other):
    """
    Performs the equivalent of `x.dot(y)` for [`sparse.GCXS`][].

    Parameters
    ----------
    other : Union[GCXS, COO, numpy.ndarray, scipy.sparse.spmatrix]
        The second operand of the dot product operation.

    Returns
    -------
    {GCXS, numpy.ndarray}
        The result of the dot product. If the result turns out to be dense,
        then a dense array is returned, otherwise, a sparse array.

    Raises
    ------
    ValueError
        If all arguments don't have zero fill-values.

    See Also
    --------
    - [`sparse.dot`][] : Equivalent function for two arguments.
    - [`numpy.dot`][] : Numpy equivalent function.
    - [`scipy.sparse.coo_matrix.dot`][] : Scipy equivalent function.
    """
    from .._common import dot

    return dot(self, other)

isinf()

Source code in sparse/numba_backend/_compressed/compressed.py

def isinf(self):
    return self.tocoo().isinf().asformat("gcxs", compressed_axes=self.compressed_axes)

isnan()

Source code in sparse/numba_backend/_compressed/compressed.py

def isnan(self):
    return self.tocoo().isnan().asformat("gcxs", compressed_axes=self.compressed_axes)