Compressed Sparse Matrices
The CSR
class is the entry point for pure Python code to work with the
CSR package.
- class csr.CSR(nrows, ncols, nnz, rps, cis, vs, _cast=True)
Simple compressed sparse row matrix. This is like
scipy.sparse.csr_matrix
, with a few useful differences:The value array is optional, for cases in which only the matrix structure is required.
The value array, if present, is always double-precision.
It is usable from code compiled in Numba’s nopython mode.
You generally don’t want to create this class yourself with the constructor. Instead, use one of its class or static methods. If you do use the constructor, be advised that the class may reuse the arrays that you pass, but does not guarantee that they will be used.
Not all methods are available from Numba, and a few have restricted signatures. The documentation for each method notes deviations when in Numba-compiled code.
At the Numba level, matrices with and without value arrays have different types. For the most part, this is transparent, but if you want to write a Numba function that works on the values array but only if it is present, it requires writing two versions of the function and using
numba.extending.overload()
to dispatch to the correct one. There are several examples of doing this in the CSR source code. The methodCSRType.has_values()
lets you quickly see if a CSR type instance has values or not.- rowptrs
the row pointers.
- Type:
- colinds
the column indices.
- Type:
- values
the values.
- Type:
numpy.ndarray or None
Constructing Matrices
In addition to the CSR constructor, there are several utility methods for constructing sparse matrices.
- classmethod CSR.from_coo(rows, cols, vals, shape=None, *, rpdtype=<class 'numpy.int32'>)
Create a CSR matrix from data in COO format.
- Parameters:
rows (array-like) – the row indices.
cols (array-like) – the column indices.
vals (array-like) – the data values; can be
None
.shape (tuple) – the array shape, or
None
to infer from row & column indices.
- classmethod CSR.empty(nrows, ncols, row_nnzs=None, values=True)
Create an uninitialized CSR matrix.
- Parameters:
nrows (int) – the number of rows.
ncols (int) – the number of columns.
row_nnzs (array-like) – the number of nonzero entries for each row, or None for an empty matrix.
values (bool, str, or numpy.dtype) – whether it has values or only structure; can be a NumPy data type to specify a type other than f8.
Constructing from Numba
Numba does not provide access to CSR’s class methods; instead, use the creation functions (these also work from pure Python):
- csr.create(nrows, ncols, nnz, rowptrs, colinds, values)
Create a CSR.
- csr.create_novalues(nrows, ncols, nnz, rowptrs, colinds)
Create a CSR without values.
- csr.create_empty(nrows, ncols)
Create an empty CSR of the specified size.
Note
This function can be used from Numba.
- csr.create_from_sizes(nrows, ncols, sizes)
Create a CSR with uninitialized values and specified row sizes.
This function is Numba-accessible, but is limited to creating matrices with fewer than \(2^{31}\) nonzero entries and present value arrays.
- Parameters:
nrows (int) – the number of rows
ncols (int) – the number of columns
sizes (numpy.ndarray) – the number of nonzero values in each row
Accessing Rows
The CSR data itself is exposed through attributes. There are also several methods to extract row data in a more convenient form.
- CSR.row_extent(row)
Get the extent of a row in the underlying column index and value arrays.
- CSR.row_cs(row)
Get the column indcies for the stored values of a row.
- CSR.row_vs(row)
Get the stored values of a row. If only the matrix structure is stored, this returns a vector of 1s.
- CSR.row(row)
Return one or more rows of this matrix as a dense ndarray.
- Parameters:
row (int or numpy.ndarray) – the row index or indices.
- Returns:
the row, with 0s in the place of missing values. If the CSR only stores matrix structure, the returned vector has 1s where the CSR records an entry.
- Return type:
Transforming and Manipulating Matrices
- CSR.copy(include_values=True, *, copy_structure=True)
Create a copy of this CSR.
- CSR.subset_rows(begin, end)
Subset the rows in this matrix.
Note
This method is not available from Numba.
- CSR.filter_nnzs(filt)
Filter the values along the full NNZ axis.
Note
This method is not available from Numba.
- CSR.transpose(include_values=True)
Transpose a CSR matrix.
Note
In Numba, this method takes no paramters. Call
transpose_structure()
for a structure-only transpose.
- CSR.normalize_rows(normalization)
Normalize the rows of the matrix.
Note
The normalization ignores missing values instead of treating them as 0.
Note
This method is not available from Numba.
- Parameters:
normalization (str) –
The normalization to perform. Can be one of:
'center'
- center rows about the mean'unit'
- convert rows to a unit vector
- Returns:
The normalization values for each row.
- Return type:
- CSR.drop_values()
Remove the value array from this CSR. This is an in-place operation.
Warning
This method is deprecated.
Note
This method is not available from Numba.
- CSR.fill_values(value)
Fill the values of this CSR with the specified value. If the CSR is structure-only, a value array is added. This is an in-place operation.
Warning
This method is deprecated.
Note
This method is not available from Numba.
Arithmetic
CSRs do not yet support the full suite of SciPy/NumPy matrix operations, but they do support multiplications:
- CSR.mult_vec(v)
Multiply this matrix by a vector.
- Parameters:
other (numpy.ndarray) – A vector, of length ncols.
- Returns:
\(A\vec{x}\), as a vector.
- Return type:
- CSR.multiply(other, transpose=False)
Multiply this matrix by another.
Note
In Numba,
transpose
is a mandatory positional argument. Numba users may wish to directly use the kernel API.- Parameters:
- Returns
CSR: the product of the two matrices.
SciPy Integration
CSR matrices can be converted to and from SciPy sparse matrices (in any layout):
- classmethod CSR.from_scipy(mat, copy=True)
Convert a scipy sparse matrix to a CSR.
- Parameters:
mat (scipy.sparse.spmatrix) – a SciPy sparse matrix.
copy (bool) – if
False
, reuse the SciPy storage if possible.
- Returns:
a CSR matrix.
- Return type:
- CSR.to_scipy()
Convert a CSR matrix to a SciPy
scipy.sparse.csr_matrix
. Avoids copying if possible.- Parameters:
self (CSR) – A CSR matrix.
- Returns:
A SciPy sparse matrix with the same data.
- Return type: