GCXS

基类：SparseArray, NDArrayOperatorsMixin

稀疏多维数组。

这以 GCXS 格式存储，它是 用于 n 维稀疏数组的高效存储方案：GCRS/GCCS 中 GCRS/GCCS 格式的推广。GCXS 推广了 CRS/CCS 稀疏矩阵格式。

对于 ndim == 2 的数组，GCXS 与 CSR/CSC 相同。对于 ndim > 2 的数组，任何轴的组合都可以被压缩，从而显著减少存储空间。

GCXS 由 3 个数组组成。这 3 个数组是 RO、CO 和 VL。数组 RO 的第一个元素是整数 0，随后的元素是 GCRS 中每行、GCCS 中每列的累积非零元素数量。CO 存储 GCRS 中每行、GCCS 中每列的非零元素的列索引。VL 存储非零数组元素的值。

GCRS/GCCS 优于传统 (CRS/CCS) 的优势已通过理论分析和实验结果证明，并已在链接的研究论文中概述。

参数

名称	类型	描述	默认值
arg	tuple(data, indices, indptr)	一个元组，包含数组非零值的数据、索引和索引指针数组。	必需
shape	tuple[int](ndim)	数组的形状。	无
compressed_axes	Iterable[int]	要压缩的轴。	无
prune	bool_	一个标志，指示是否应修剪数据数组中存在的任何填充值。	False
fill_value		此数组的填充值。	无

属性

名称	类型	描述
数据	ndarray(nnz)	一个数组，包含与 indices 对应的非零值。
indices	ndarray(nnz)	一个数组，包含非压缩维度上每个非零元素的坐标。
indptr	ndarray	一个数组，包含沿压缩维度非零值的累积和。
shape	tuple[int](ndim)	此数组的维度。

另请参阅

sparse.DOK : 一个主要只写的稀疏数组。

源代码在 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):
        is_csc = x.format == "csc"
        ca = (1,) if is_csc else (0,)
        if not is_csc:
            x = x.asformat("csr")
        if not x.has_canonical_format:
            x.eliminate_zeros()
            x.sum_duplicates()
        return cls((x.data, x.indices, x.indptr), shape=x.shape, compressed_axes=ca, 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)

属性

device 属性

ndim 属性

此数组的维度数。

返回

类型	描述
int	此数组的维度数。

另请参阅

• sparse.DOK.ndim : sparse.DOK 数组的等效属性。
• numpy.ndarray.ndim : Numpy 等效属性。

示例

>>> 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 属性

此数组中所有元素（包括零）的数量。

返回

类型	描述
int	元素数量。

另请参阅

numpy.ndarray.size : Numpy 等效属性。

示例

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

density 属性

此数组中非零元素与所有元素的比率。

返回

类型	描述
float	非零元素与所有元素的比率。

另请参阅

• sparse.COO.size : 元素数量。
• sparse.COO.nnz : 非零元素数量。

示例

>>> 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 类属性 实例属性

amin = min 类属性 实例属性

round_ = round 类属性 实例属性

real 属性

数组的实部。

示例

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

返回

名称	类型	描述
out	SparseArray	数组元素的实部。如果数组 dtype 是实数，则输出使用数组的 dtype。如果数组是复数，则输出 dtype 为浮点数。

另请参阅

• numpy.ndarray.real : NumPy 等效属性。
• numpy.real : NumPy 等效函数。

imag 属性

数组的虚部。

示例

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

返回

名称	类型	描述
out	SparseArray	数组元素的虚部。如果数组 dtype 是实数，则输出使用数组的 dtype。如果数组是复数，则输出 dtype 为浮点数。

另请参阅

• numpy.ndarray.imag : NumPy 等效属性。
• numpy.imag : NumPy 等效函数。

shape = shape 实例属性

fill_value = self.data.dtype.type(fill_value) 实例属性

dtype 属性

此数组的数据类型。

返回

类型	描述
dtype	此数组的数据类型。

另请参阅

• numpy.ndarray.dtype : Numpy 等效属性。
• scipy.sparse.csr_matrix.dtype : Scipy 等效属性。

nnz 属性

此数组中非零元素的数量。

返回

类型	描述
int	此数组中非零元素的数量。

另请参阅

• sparse.COO.nnz : 等效的 sparse.COO 数组属性。
• sparse.DOK.nnz : 等效的 sparse.DOK 数组属性。
• numpy.count_nonzero : 一个类似的 Numpy 函数。
• scipy.sparse.coo_matrix.nnz : Scipy 等效属性。

format 属性

此数组的存储格式。

返回

类型	描述
str	此数组的存储格式。

另请参阅

scipy.sparse.dok_matrix.format : Scipy 等效属性。

示例

>>> 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 属性

此对象占用的字节数。请注意，对于小型数组，由于恒定开销较大，此值可能会低估字节数。

返回

类型	描述
int	此对象占用的近似内存字节数。

另请参阅

numpy.ndarray.nbytes : 等效的 Numpy 属性。

T 属性

mT 属性

compressed_axes 属性

函数

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

源代码在 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)

对此数组执行归约操作。

参数

名称	类型	描述	默认值
method	ufunc	用于执行归约的方法。	必需
axis	Union[int, Iterable[int]]	执行归约的轴。默认使用所有轴。	(0,)
keepdims	bool_	是否保留原始数组的维度。	False
**kwargs	dict	传递给归约操作的任何额外参数。	{}

另请参阅

• numpy.ufunc.reduce : 一个类似的 Numpy 方法。
• sparse.COO.reduce : 在 COO 数组上实现的此方法。
• sparse.GCXS.reduce : 在 GCXS 数组上实现的此方法。

源代码在 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)

沿给定轴执行求和操作。默认使用所有轴。

参数

名称	类型	描述	默认值
axis	Union[int, Iterable[int]]	进行求和的轴。默认使用所有轴。	无
keepdims	bool_	是否保留原始数组的维度。	False
dtype	dtype	输出数组的数据类型。	无

返回

类型	描述
SparseArray	归约后的稀疏输出数组。

另请参阅

• numpy.sum : 等效的 numpy 函数。
• scipy.sparse.coo_matrix.sum : 等效的 Scipy 函数。

源代码在 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)

沿给定轴取最大值。默认使用所有轴。

参数

名称	类型	描述	默认值
axis	Union[int, Iterable[int]]	取最大值的轴。默认使用所有轴。	无
keepdims	bool_	是否保留原始数组的维度。	False
out	dtype	输出数组的数据类型。	无

返回

类型	描述
SparseArray	归约后的稀疏输出数组。

另请参阅

• numpy.max : 等效的 numpy 函数。
• scipy.sparse.coo_matrix.max : 等效的 Scipy 函数。

源代码在 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)

检查数组中是否有任何值为 True。默认使用所有轴。

参数

名称	类型	描述	默认值
axis	Union[int, Iterable[int]]	取最小值的轴。默认使用所有轴。	无
keepdims	bool_	是否保留原始数组的维度。	False

返回

类型	描述
SparseArray	归约后的稀疏输出数组。

另请参阅

numpy.any : 等效的 numpy 函数。

源代码在 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)

检查数组中所有值是否都为 True。默认使用所有轴。

参数

名称	类型	描述	默认值
axis	Union[int, Iterable[int]]	取最小值的轴。默认使用所有轴。	无
keepdims	bool_	是否保留原始数组的维度。	False

返回

类型	描述
SparseArray	归约后的稀疏输出数组。

另请参阅

numpy.all : 等效的 numpy 函数。

源代码在 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)

沿给定轴取最小值。默认使用所有轴。

参数

名称	类型	描述	默认值
axis	Union[int, Iterable[int]]	取最小值的轴。默认使用所有轴。	无
keepdims	bool_	是否保留原始数组的维度。	False
out	dtype	输出数组的数据类型。	无

返回

类型	描述
SparseArray	归约后的稀疏输出数组。

另请参阅

• numpy.min : 等效的 numpy 函数。
• scipy.sparse.coo_matrix.min : 等效的 Scipy 函数。

源代码在 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)

沿给定轴执行乘积操作。默认使用所有轴。

参数

名称	类型	描述	默认值
axis	Union[int, Iterable[int]]	进行乘法的轴。默认使用所有轴。	无
keepdims	bool_	是否保留原始数组的维度。	False
dtype	dtype	输出数组的数据类型。	无

返回

类型	描述
SparseArray	归约后的稀疏输出数组。

另请参阅

numpy.prod : 等效的 numpy 函数。

源代码在 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)

均匀地四舍五入到给定的小数位数。

另请参阅

• numpy.round : NumPy 等效的 ufunc。
• sparse.elemwise : 对一个或两个参数应用任意的元素级函数。

源代码在 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)

裁剪（限制）数组中的值。

返回一个值限制在 [min, max] 范围内的数组。必须提供 min 或 max 之一。

另请参阅

• sparse.clip : 完整的文档和更多详情。
• numpy.clip : 等效的 NumPy 函数。

源代码在 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 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)

数组的副本，转换为指定类型。

另请参阅

• scipy.sparse.coo_matrix.astype : SciPy 稀疏等效函数
• numpy.ndarray.astype : NumPy 等效的 ufunc。
• sparse.elemwise : 对一个或两个参数应用任意的元素级函数。

源代码在 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)

沿给定轴计算均值。默认使用所有轴。

参数

名称	类型	描述	默认值
axis	Union[int, Iterable[int]]	计算均值的轴。默认使用所有轴。	无
keepdims	bool_	是否保留原始数组的维度。	False
dtype	dtype	输出数组的数据类型。	无

返回

类型	描述
SparseArray	归约后的稀疏输出数组。

另请参阅

• numpy.ndarray.mean : 等效的 numpy 方法。
• scipy.sparse.coo_matrix.mean : 等效的 Scipy 方法。

备注

• 提供 out 参数仅为了与 Numpy 兼容，实际上并不受支持。

示例

您可以使用 sparse.COO.mean 计算数组沿任意维度的均值。

>>> 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.])

您还可以使用 keepdims 参数在计算均值后保留维度。

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

如果需要，可以传入输出数据类型。

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

默认情况下，这将数组归约为一个数字，计算沿所有轴的均值。

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

源代码在 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)

沿给定轴计算方差。默认使用所有轴。

参数

名称	类型	描述	默认值
axis	Union[int, Iterable[int]]	计算方差的轴。默认使用所有轴。	无
dtype	dtype	输出数据类型。	无
out	SparseArray	写入输出的数组。	无
ddof	int	自由度。	0
keepdims	bool_	是否保留原始数组的维度。	False

返回

类型	描述
SparseArray	归约后的稀疏输出数组。

另请参阅

numpy.ndarray.var : 等效的 numpy 方法。

示例

您可以使用 sparse.COO.var 计算数组沿任意维度的方差。

>>> 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])

您还可以使用 keepdims 参数在计算方差后保留维度。

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

如果需要，可以传入输出数据类型。

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

默认情况下，这将数组归约为一个数字，计算沿所有轴的方差。

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

源代码在 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)

沿给定轴计算标准差。默认使用所有轴。

参数

名称	类型	描述	默认值
axis	Union[int, Iterable[int]]	计算标准差的轴。默认使用所有轴。	无
dtype	dtype	输出数据类型。	无
out	SparseArray	写入输出的数组。	无
ddof	int	自由度。	0
keepdims	bool_	是否保留原始数组的维度。	False

返回

类型	描述
SparseArray	归约后的稀疏输出数组。

另请参阅

numpy.ndarray.std : 等效的 numpy 方法。

示例

您可以使用 sparse.COO.std 计算数组沿任意维度的标准差。

>>> 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])

您还可以使用 keepdims 参数在计算标准差后保留维度。

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

如果需要，可以传入输出数据类型。

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

默认情况下，这将数组归约为一个数字，计算沿所有轴的标准差。

>>> s.std()
0.7071067811865476

源代码在 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()

按元素返回复共轭。

复数的复共轭是通过改变其虚部的符号获得的。

示例

>>> 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')

返回

名称	类型	描述
out	SparseArray	复共轭，与输入具有相同的 dtype。

另请参阅

• numpy.ndarray.conj : NumPy 等效方法。
• numpy.conj : NumPy 等效函数。

源代码在 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)

返回数组的副本。

参数

名称	类型	描述	默认值
deep	布尔值	如果为 True（默认），则内部的 coords 和 data 数组也会被复制。设置为 False 则只进行浅复制。	True

源代码在 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) 类方法

源代码在 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) 类方法

源代码在 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) 类方法

源代码在 sparse/numba_backend/_compressed/compressed.py 中

@classmethod
def from_scipy_sparse(cls, x, /, *, fill_value=None):
    is_csc = x.format == "csc"
    ca = (1,) if is_csc else (0,)
    if not is_csc:
        x = x.asformat("csr")
    if not x.has_canonical_format:
        x.eliminate_zeros()
        x.sum_duplicates()
    return cls((x.data, x.indices, x.indptr), shape=x.shape, compressed_axes=ca, fill_value=fill_value)

from_iter(x, shape=None, compressed_axes=None, fill_value=None, idx_dtype=None) 类方法

源代码在 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)

返回一个具有指定压缩轴的新数组。此操作类似于将 scipy.sparse.csc_matrix 转换为 scipy.sparse.csr_matrix。

返回

类型	描述
GCXS	输入数组的新实例，沿指定维度进行压缩。

源代码在 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()

将此 sparse.GCXS 数组转换为 sparse.COO。

返回

类型	描述
COO	转换后的 COO 数组。

源代码在 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()

将此 sparse.GCXS 数组转换为密集的 numpy.ndarray。请注意，如果 sparse.GCXS 对象的 shape 较大，这可能会占用大量内存。

返回

类型	描述
ndarray	转换后的密集数组。

另请参阅

• sparse.DOK.todense : 等效的 sparse.DOK 数组方法。
• sparse.COO.todense : 等效的 sparse.COO 数组方法。
• scipy.sparse.coo_matrix.todense : 等效的 Scipy 方法。

源代码在 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()

源代码在 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)

将此 sparse.GCXS 对象转换为 scipy.sparse.csr_matrix 或 scipy.sparse.csc_matrix。

参数

名称	类型	描述	默认值
accept_fv	标量或标量列表	接受的填充值列表。默认只接受零。	无

返回

类型	描述
csr_matrix 或 csc_matrix	转换后的 Scipy 稀疏矩阵。

引发

类型	描述
ValueError	如果数组不是二维的。
ValueError	如果所有数组都没有零填充值。

源代码在 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)

将此稀疏数组转换为给定格式。

参数

名称	类型	描述	默认值
format	str	格式字符串。	必需

返回

名称	类型	描述
out	SparseArray	转换后的数组。

引发

类型	描述
NotImplementedError	如果不支持该格式。

源代码在 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)

如果成本不高，则将此 sparse.GCXS 数组转换为 numpy.ndarray。

参数

名称	类型	描述	默认值
max_size	int	输出中的最大元素数量	1000
min_density	float	输出的最小密度	0.25

返回

类型	描述
ndarray	密集数组。

另请参阅

• sparse.GCXS.todense: 转换为 Numpy 函数，不检查成本。
• sparse.COO.maybe_densify: 等效的 COO 函数。

引发

类型	描述
ValueError	如果返回的数组太大。

源代码在 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')

返回一个新 sparse.GCXS 数组，它是此数组的扁平化版本。

返回

类型	描述
GCXS	扁平化输出数组。

备注

提供 order 参数仅为了与 Numpy 兼容，实际上并不受支持。

源代码在 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)

返回一个新 sparse.GCXS 数组，它是此数组的重塑版本。

参数

名称	类型	描述	默认值
shape	tuple[int]	所需输出数组的形状。	必需
compressed_axes	Iterable[int]	用于存储数组的压缩轴。默认情况下查找最有效的存储方式。	无

返回

类型	描述
GCXS	重塑后的输出数组。

另请参阅

• numpy.ndarray.reshape : 等效的 Numpy 函数。
• sparse.COO.reshape : 等效的 COO 函数。

备注

提供 order 参数仅为了与 Numpy 兼容，实际上并不受支持。

源代码在 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)

返回一个轴顺序已交换的新数组。

参数

名称	类型	描述	默认值
axes	Iterable[int]	与前一个轴顺序相比的新轴顺序。默认情况下反转轴。	无
compressed_axes	Iterable[int]	用于存储数组的压缩轴。默认情况下查找最有效的存储方式。	无

返回

类型	描述
GCXS	轴以所需顺序排列的新数组。

另请参阅

• sparse.GCXS.T : 一个快速反转轴顺序的属性。
• numpy.ndarray.transpose : Numpy 等效函数。

源代码在 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)

对 sparse.GCXS 执行 x.dot(y) 的等效操作。

参数

名称	类型	描述	默认值
other	联合[GCXS, COO, ndarray, spmatrix]	点积操作的第二个操作数。	必需

返回

类型	描述
{GCXS, ndarray}	点积的结果。如果结果是密集的，则返回密集数组，否则返回稀疏数组。

引发

类型	描述
ValueError	如果所有参数都没有零填充值。

另请参阅

• sparse.dot : 两个参数的等效函数。
• numpy.dot : Numpy 等效函数。
• scipy.sparse.coo_matrix.dot : Scipy 等效函数。

源代码在 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()

源代码在 sparse/numba_backend/_compressed/compressed.py 中

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

isnan()

源代码在 sparse/numba_backend/_compressed/compressed.py 中

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