Introduction

Sparse feature matrices are common in text classification, recommendation systems, and one-hot encoded tabular data. If your training data starts as a SciPy CSR matrix and your model is written in TensorFlow, the key task is converting each mini-batch into a tf.sparse.SparseTensor without densifying the data.

Why CSR Is a Good Starting Format

SciPy’s CSR format stores three compact arrays internally: non-zero values, column indices, and row pointers. That makes it efficient for slicing by rows, which is exactly what mini-batch training needs.

A dense conversion defeats the point of using sparse data. If you call .toarray() on a very high-dimensional matrix, memory usage can explode even when each example contains only a few active features.

So the right workflow is:

1. keep the full dataset as CSR
2. slice row batches from CSR
3. convert each batch to TensorFlow sparse format
4. feed the sparse tensor into a model or training step

Converting CSR to SparseTensor

The easiest bridge is to convert the batch to COO form first, because TensorFlow expects explicit index pairs for non-zero elements.

1import numpy as np
2import scipy.sparse as sp
3import tensorflow as tf
4
5
6def csr_to_sparse_tensor(x_csr: sp.csr_matrix) -> tf.SparseTensor:
7    x_coo = x_csr.tocoo()
8    indices = np.vstack((x_coo.row, x_coo.col)).T.astype(np.int64)
9    values = x_coo.data.astype(np.float32)
10    shape = x_coo.shape
11
12    tensor = tf.SparseTensor(indices=indices, values=values, dense_shape=shape)
13    return tf.sparse.reorder(tensor)
14
15
16x = sp.csr_matrix([
17    [0.0, 1.0, 0.0, 2.0],
18    [3.0, 0.0, 0.0, 0.0],
19    [0.0, 0.0, 4.0, 0.0],
20], dtype=np.float32)
21
22x_tf = csr_to_sparse_tensor(x)
23print(x_tf)

tf.sparse.reorder is worth keeping because some sparse ops expect canonical ordering of the indices.

Mini-Batch Gradient Descent With Sparse Input

The main advantage of CSR for training is efficient row slicing. You can cut the dataset into row ranges, convert each slice, and run a normal TensorFlow training step.

Here is a small logistic-style model using sparse matrix multiplication.

1import numpy as np
2import scipy.sparse as sp
3import tensorflow as tf
4
5rng = np.random.default_rng(42)
6
7x = sp.csr_matrix([
8    [1, 0, 0, 1],
9    [0, 1, 0, 1],
10    [1, 0, 1, 0],
11    [0, 1, 1, 0],
12], dtype=np.float32)
13y = tf.constant([[1.0], [0.0], [1.0], [0.0]], dtype=tf.float32)
14
15w = tf.Variable(tf.zeros((x.shape[1], 1), dtype=tf.float32))
16b = tf.Variable(tf.zeros((1,), dtype=tf.float32))
17optimizer = tf.keras.optimizers.SGD(learning_rate=0.1)
18
19
20def csr_to_sparse_tensor(x_csr):
21    x_coo = x_csr.tocoo()
22    indices = np.vstack((x_coo.row, x_coo.col)).T.astype(np.int64)
23    values = x_coo.data.astype(np.float32)
24    return tf.sparse.reorder(
25        tf.SparseTensor(indices=indices, values=values, dense_shape=x_coo.shape)
26    )
27
28
29for epoch in range(5):
30    for start in range(0, x.shape[0], 2):
31        end = start + 2
32        x_batch = csr_to_sparse_tensor(x[start:end])
33        y_batch = y[start:end]
34
35        with tf.GradientTape() as tape:
36            logits = tf.sparse.sparse_dense_matmul(x_batch, w) + b
37            loss = tf.reduce_mean(
38                tf.nn.sigmoid_cross_entropy_with_logits(labels=y_batch, logits=logits)
39            )
40
41        gradients = tape.gradient(loss, [w, b])
42        optimizer.apply_gradients(zip(gradients, [w, b]))
43
44    print(f"epoch={epoch} loss={float(loss):.4f}")

This stays sparse from the SciPy matrix to the TensorFlow multiply, which is the whole point.

Feeding Sparse Data Through tf.data

You can also build a generator that yields sparse mini-batches into a tf.data.Dataset. That becomes useful when the training loop grows more complex, though the simplest row-slicing loop is often easier to debug first.

The important thing is to batch by rows before conversion. Rebuilding a giant full-dataset sparse tensor and then trying to split it later is usually less convenient than slicing the CSR matrix directly.

Common Pitfalls

The biggest mistake is converting the entire sparse matrix to dense form just to make TensorFlow accept it. That often destroys memory efficiency immediately.

Another frequent issue is forgetting that many TensorFlow layers expect dense input. If you want to stay sparse, use sparse-friendly operations such as tf.sparse.sparse_dense_matmul or confirm that the chosen layer accepts sparse tensors.

Developers also sometimes create incorrect indices by using CSR internals directly instead of converting to COO. COO is simpler because it already exposes row and column coordinates for each non-zero value.

Finally, keep dtypes aligned. Sparse values are often float64 in SciPy by default, while TensorFlow models usually expect float32.

Summary

• Keep the master dataset in SciPy CSR format because row slicing is efficient for mini-batches.
• Convert each batch to COO, then build a tf.sparse.SparseTensor from row-column indices and values.
• Use sparse TensorFlow ops so the data remains sparse through training.
• Avoid dense conversion unless the matrix is genuinely small.
• Align ordering and dtypes so sparse operations behave predictably.