Skip to main content
`Ctrl`+`K`
scipy.sparse.

# diags_array

scipy.sparse.diags_array(diagonals, /, *, offsets=0, shape=None, format=None, dtype=None)

  Construct a sparse array from diagonals.

  Parameters:
    diagonals sequence of array_like

      Sequence of arrays containing the array diagonals, corresponding to offsets.

    offsets sequence of int or an int, optional
      Diagonals to set (repeated offsets are not allowed):

        - k = 0 the main diagonal (default)

        - k > 0 the kth upper diagonal

        - k < 0 the kth lower diagonal

    shape tuple of int, optional

      Shape of the result. If omitted, a square array large enough to contain the diagonals is returned.

    format{“dia”, “csr”, “csc”, “lil”, …}, optional

      Matrix format of the result. By default (format=None) an appropriate sparse array format is returned. This choice is subject to change.

    dtype dtype, optional

      Data type of the array.

  Returns:
    new_array dia_array

      `dia_array` holding the values in diagonals offset from the main diagonal as indicated in offsets.

  See also

  `dia_array`

    constructor for the sparse DIAgonal format.

  Notes

  Repeated diagonal offsets are disallowed.

  The result from `diags_array` is the sparse equivalent of:

      np.diag(diagonals[0], offsets[0])
      + ...
      + np.diag(diagonals[k], offsets[k])

  `diags_array` differs from `dia_array` in the way it handles off-diagonals. Specifically, `dia_array` assumes the data input includes padding (ignored values) at the start/end of the rows for positive/negative offset, while `diags_array` assumes the input data has no padding. Each value in the input diagonals is used.

  Added in version 1.11.

  Examples

      >>> from scipy.sparse import diags_array
      >>> diagonals = [[1, 2, 3, 4], [1, 2, 3], [1, 2]]
      >>> diags_array(diagonals, offsets=[0, -1, 2]).toarray()
      array([[1., 0., 1., 0.],
             [1., 2., 0., 2.],
             [0., 2., 3., 0.],
             [0., 0., 3., 4.]])

  Broadcasting of scalars is supported (but shape needs to be specified):

      >>> diags_array([1, -2, 1], offsets=[-1, 0, 1], shape=(4, 4)).toarray()
      array([[-2.,  1.,  0.,  0.],
             [ 1., -2.,  1.,  0.],
             [ 0.,  1., -2.,  1.],
             [ 0.,  0.,  1., -2.]])

  If only one diagonal is wanted (as in `numpy.diag`), the following works as well:

      >>> diags_array([1, 2, 3], offsets=1).toarray()
      array([[ 0.,  1.,  0.,  0.],
             [ 0.,  0.,  2.,  0.],
             [ 0.,  0.,  0.,  3.],
             [ 0.,  0.,  0.,  0.]])