Introduction

Keras IMDb dataset represents reviews as integer sequences, which is convenient for models but hard to read during debugging. Restoring approximate original text helps inspect preprocessing quality, misclassified samples, and tokenization assumptions. The process is straightforward once you understand the word index offsets used by the dataset loader.

Load IMDb Data and Word Index

Start by loading encoded reviews and the word index mapping.

1from tensorflow.keras.datasets import imdb
2
3# Keep top 10k words for this example.
4(x_train, y_train), (x_test, y_test) = imdb.load_data(num_words=10000)
5word_index = imdb.get_word_index()
6
7print(len(x_train), len(x_test))
8print(x_train[0][:10])

Each review is a list of integers. Those integers do not map directly to word_index values because Keras reserves special IDs.

Understand Reserved Token Offsets

Keras uses these standard reserved tokens:

• 0 for padding,
• 1 for start token,
• 2 for unknown token,
• 3 for unused token.

So when building reverse mapping, add offset +3 to dictionary values.

1index_to_word = {index + 3: word for word, index in word_index.items()}
2index_to_word[0] = "<PAD>"
3index_to_word[1] = "<START>"
4index_to_word[2] = "<UNK>"
5index_to_word[3] = "<UNUSED>"

This gives a readable lookup table for integer tokens.

Decode Review Sequences to Text

Define a helper to convert integer sequences back to text.

1def decode_review(encoded_review):
2    return " ".join(index_to_word.get(i, "<UNK>") for i in encoded_review)
3
4sample_text = decode_review(x_train[0])
5print(sample_text[:700])

Decoded text is approximate token-level reconstruction, not exact original punctuation and casing from raw source.

Still, it is very useful for understanding what the model saw after preprocessing.

Decode with a Custom Vocabulary Limit

If you load with num_words, some tokens are replaced by unknown marker. You can inspect this behavior explicitly.

1num_words = 5000
2(x_train_small, _), _ = imdb.load_data(num_words=num_words)
3
4small_text = " ".join(index_to_word.get(i, "<UNK>") for i in x_train_small[0])
5print(small_text[:400])

Lower vocabulary limits produce more unknown tokens, which may reduce interpretability.

Practical Debugging Workflow

When evaluating misclassifications, decode both review text and predicted probability.

1import numpy as np
2
3# Assume `model` is trained and x_test is padded appropriately.
4# preds = model.predict(x_test_padded)
5# For demonstration, fake probabilities:
6preds = np.random.rand(len(x_test))
7
8idx = 5
9print("true label:", y_test[idx])
10print("pred prob:", float(preds[idx]))
11print(decode_review(x_test[idx])[:800])

This helps you understand whether errors come from sarcasm, rare words, truncation, or noise.

Restore with Tokenizer in Custom Pipelines

If you built your own tokenizer, store word_index and decode similarly.

1from tensorflow.keras.preprocessing.text import Tokenizer
2
3texts = ["great movie", "very bad acting"]
4tok = Tokenizer(num_words=1000, oov_token="<UNK>")
5tok.fit_on_texts(texts)
6seq = tok.texts_to_sequences(["great acting"])[0]
7
8rev = {v: k for k, v in tok.word_index.items()}
9decoded = " ".join(rev.get(i, "<UNK>") for i in seq)
10print(decoded)

The same reverse-lookup principle applies beyond IMDb.

Compare Original and Truncated Views

Many workflows pad or truncate reviews to fixed length. Decode both raw and truncated sequences during debugging so you can see whether important sentiment terms were removed.

1maxlen = 120
2original = x_test[0]
3truncated = original[:maxlen]
4
5print("original length:", len(original))
6print("truncated length:", len(truncated))
7print(decode_review(truncated)[:500])

This quickly reveals when preprocessing choices discard context that model decisions depend on.

Common Pitfalls

A common mistake is forgetting the offset when creating reverse mapping from IMDb word index. Without offset correction, decoded words look incorrect.

Another issue is expecting exact original review text with punctuation and capitalization preserved. The dataset stores tokenized integer sequences, so reconstruction is approximate.

Developers also compare decoded training data against differently preprocessed inference data, then misinterpret results. Keep preprocessing pipeline consistent across train and inference stages.

Summary

• IMDb dataset stores reviews as integer token sequences, not raw text.
• Build reverse mapping with correct reserved-token offsets.
• Decode with helper functions for readable inspection and debugging.
• Expect approximate reconstruction, not exact original formatting.
• Use decoded text to diagnose model errors and preprocessing choices.