scipy.sparse.diags

scipy.sparse.diags(diagonals, offsets=0, shape=None, format=None, dtype=None)

Construct a sparse matrix from diagonals.

Parameters

diagonalssequence of array_like

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

offsetssequence of int or an int, optional

Diagonals to set:

• k = 0 the main diagonal (default)

• k > 0 the k-th upper diagonal

• k < 0 the k-th lower diagonal

shapetuple of int, optional

Shape of the result. If omitted, a square matrix 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 matrix format is returned. This choice is subject to change.

dtypedtype, optional

Data type of the matrix.

See also

spdiags

construct matrix from diagonals

Notes

This function differs from spdiags in the way it handles off-diagonals.

The result from diags is the sparse equivalent of:

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

Repeated diagonal offsets are disallowed.

New in version 0.11.

Examples

>>> from scipy.sparse import diags
>>> diagonals = [[1, 2, 3, 4], [1, 2, 3], [1, 2]]
>>> diags(diagonals, [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([1, -2, 1], [-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([1, 2, 3], 1).toarray()
array([[ 0.,  1.,  0.,  0.],
       [ 0.,  0.,  2.,  0.],
       [ 0.,  0.,  0.,  3.],
       [ 0.,  0.,  0.,  0.]])