Introduction

In TensorFlow, the usual way to replace selected tensor values with values from another tensor is tf.where. It performs element-wise selection based on a condition tensor, which makes it ideal for masking, cleanup, and conditional feature construction as long as shapes and dtypes line up correctly.

The Standard Pattern: tf.where

tf.where(condition, x, y) returns elements from x where the condition is true, and from y where the condition is false.

For replacement tasks, x is often the replacement tensor and y is the original tensor.

1import tensorflow as tf
2
3source = tf.constant([1, -1, 3, -1], dtype=tf.int32)
4replacement = tf.constant([10, 20, 30, 40], dtype=tf.int32)
5
6mask = tf.equal(source, -1)
7result = tf.where(mask, replacement, source)
8
9print(result.numpy())   # [ 1 20  3 40]

This says: wherever source equals -1, take the value from replacement; otherwise keep the original value.

Replacing with a Separate Condition Tensor

The condition does not have to come from the source tensor itself. You can compute it elsewhere and use it directly.

1import tensorflow as tf
2
3source = tf.constant([100, 200, 300, 400], dtype=tf.int32)
4replacement = tf.constant([1, 2, 3, 4], dtype=tf.int32)
5condition = tf.constant([False, True, False, True])
6
7result = tf.where(condition, replacement, source)
8print(result.numpy())   # [100   2 300   4]

This is useful when the mask comes from another model stage or business rule.

Working with Matrices and Higher-Rank Tensors

The same logic works for 2D or higher-dimensional tensors.

1import tensorflow as tf
2
3x = tf.constant([
4    [0.5, -1.0, 2.0],
5    [-1.0, 0.2, -1.0]
6], dtype=tf.float32)
7
8alt = tf.constant([
9    [9.0, 9.0, 9.0],
10    [8.0, 8.0, 8.0]
11], dtype=tf.float32)
12
13mask = x < 0
14out = tf.where(mask, alt, x)
15
16print(out.numpy())

As long as the shapes are compatible, TensorFlow applies the selection element by element.

Sparse Index Updates Are a Different Operation

If you already know the exact indices that should change, tf.tensor_scatter_nd_update can be cleaner than building a full boolean mask.

1import tensorflow as tf
2
3base = tf.constant([10, 20, 30, 40, 50], dtype=tf.int32)
4indices = tf.constant([[1], [3]])
5updates = tf.constant([999, 777], dtype=tf.int32)
6
7updated = tf.tensor_scatter_nd_update(base, indices, updates)
8print(updated.numpy())   # [ 10 999  30 777  50]

This is not the same as tf.where, but it is often the better tool when the update positions are already known.

Shape and Dtype Rules

Most replacement bugs come from these two issues:

• source and replacement tensors have incompatible shapes
• source and replacement tensors have different dtypes

For example, this is usually a problem:

source = tf.constant([1, 2, 3], dtype=tf.int32)
replacement = tf.constant([1.5, 2.5, 3.5], dtype=tf.float32)

Make the dtypes explicit before replacement:

replacement = tf.cast(replacement, source.dtype)

Also be careful with broadcasting. TensorFlow may allow it, but the result may not be the element-wise alignment you intended.

A Small Helper Function

1import tensorflow as tf
2
3def replace_masked(source, replacement, mask):
4    source = tf.convert_to_tensor(source)
5    replacement = tf.convert_to_tensor(replacement, dtype=source.dtype)
6    mask = tf.convert_to_tensor(mask, dtype=tf.bool)
7    return tf.where(mask, replacement, source)
8
9print(replace_masked([1, -1, 3], [5, 6, 7], [False, True, False]).numpy())

Wrapping the pattern once can make data pipelines easier to read and test.

Common Pitfalls

One common mistake is reaching for Python if statements inside tensor code. That does not perform element-wise tensor replacement.

Another issue is relying on broadcasting without checking tensor shapes carefully. The code may run but still produce the wrong alignment.

A third pitfall is using tf.where when you really want sparse index updates. In that case, tf.tensor_scatter_nd_update is usually clearer.

Summary

• Use tf.where for element-wise conditional replacement.
• Build a boolean mask that marks the values to replace.
• Keep source, replacement, and condition shapes compatible.
• Match dtypes explicitly to avoid type errors.
• Use tf.tensor_scatter_nd_update instead when you already know exact update indices.