Skip to content

An In-Depth Guide to Boolean Indexing and Masking in NumPy

Updated: at 01:28 AM

NumPy, short for Numerical Python, is one of the most popular Python libraries for scientific computing and working with multi-dimensional array data. NumPy provides powerful capabilities for indexing and extracting elements from arrays based on boolean conditions, known as boolean indexing or masking. Mastering boolean indexing and masking enables efficient data manipulation and analysis using NumPy.

This comprehensive guide will explain everything you need to know about boolean indexing and masking in NumPy, including key concepts, usage, and examples to help you leverage these techniques in your own projects.

Table of Contents

Open Table of Contents

Introduction to Boolean Indexing and Masking

Boolean indexing refers to the process of selecting array elements based on boolean conditions or masks. The mask can be an array or list of booleans where True indicates elements to select. Boolean masking follows the same principle but uses NumPy boolean arrays rather than lists.

Here are some key points about boolean indexing and masking in NumPy:

Working with boolean arrays is a critical skill for data analysis and handling multidimensional data using NumPy. Read on as we explore this topic in-depth with examples.

Creating Boolean Arrays

Before we apply boolean indexing, let’s see how to create boolean arrays or masks in NumPy:

import numpy as np

# From a list
bool_arr = np.array([True, False, True])

# Using Boolean NumPy array
mask = np.ones(3, dtype=bool)
mask[1] = False

# Comparison operators
num_arr = np.array([1, 2, 3])
mask = num_arr > 1

# [ True False  True]

# [False  True  True]

We can create boolean masks using lists, comparison operators like >, <, ==, NumPy boolean arrays, and functions like np.ones(). The key point is that the boolean array must be the same shape as the input data array.

Boolean Indexing in NumPy

Boolean indexing allows selecting array elements where the boolean array/mask is True. Let’s see an example:

import numpy as np

arr = np.array([1, 2, 3, 4])
mask = np.array([True, False, True, False])

result = arr[mask]
# [1 3]

Here the returned array contains only values corresponding to True in the boolean mask.

We can also use boolean lists for indexing:

idx = [True, False, True, False]
result = arr[idx]
# [1 3]

Some key points about boolean indexing in NumPy:

Let’s look at some more examples of boolean indexing on multidimensional arrays:

arr = np.array([[1,2,3], [4,5,6], [7,8,9]])

# Select second column
mask = np.array([False, True, False])
arr[:, mask]

# [[2]
#  [5]
#  [8]]

# Select first and third row
mask = np.array([True, False, True])
arr[mask, :]

# [[1 2 3]
#  [7 8 9]]

As you can see, boolean arrays allow flexible selection from multi-dimensional data.

Broadcasting in Boolean Indexing

An important feature of NumPy boolean indexing is broadcasting. If the boolean array is smaller than the dimension it indexes, it gets repeated to match the size.

Observe the broadcasting at work in this example:

arr = np.arange(6).reshape(2,3)

# [[0 1 2]
#  [3 4 5]]

mask = np.array([True, False]) # Shape (2,)

arr[mask, :]

# [[0 1 2]   # First row selected
#  [3 4 5]]   # Second row ignored

The 1D boolean array mask implicitly repeats to match the 2D input array shape during indexing.

Understanding broadcasting avoids errors from shape mismatches in boolean indexing.

Boolean Masking in NumPy

Boolean masking applies the same concept as boolean indexing but uses NumPy boolean arrays rather than lists:

arr = np.array([1, 2, 3, 4])

bool_mask = (arr % 2 == 0)
# Evaluates to [False, True, False, True]

# [2, 4]

We can also combine masks using NumPy logical operators like & (AND), | (OR):

mask1 = arr > 2
mask2 = arr % 2 == 0

arr[mask1 & mask2]
# [4] Intersection
arr[mask1 | mask2]
# [2, 3, 4] Union

This provides a flexible way to query arrays based on boolean conditions.

Assigning Values Using Boolean Masks

Boolean masks can also be used to assign values in NumPy arrays:

arr = np.zeros(5, dtype=int)

mask = np.array([True, False, True, True, False])

arr[mask] = 1

# [1 0 1 1 0]

Here we assign 1 to indices where mask is True.

This provides an efficient way to conditionally insert values into arrays.

Inverting a Boolean Mask

We can invert a boolean mask using the ~ operator:

mask = np.array([True, False, True])

# [False  True False] // Inverted

Inverting masks is useful when you want to select the complement set of elements.

Performance of Boolean Indexing

An important advantage of NumPy boolean indexing is performance. Boolean arrays can filter array data much faster compared to conditional selection using Python loops and if statements.

Consider this benchmark:

import numpy as np
import time

size = 1000000
arr = np.random.rand(size)

# NumPy boolean masking
mask = arr > 0.5
%time arr[mask]
# CPU times: user 19 ms, sys: 0 ns, total: 19 ms

# Slow loop version
%time [x for x in arr if x > 0.5]
# CPU times: user 223 ms, sys: 38 ms, total: 261 ms

Even for large arrays, NumPy boolean indexing provides order-of-magnitude faster performance compared to native Python conditional filtering.

Real World Examples

Here are some examples of how boolean indexing and masking are used in real-world data science applications:

Subsetting Data

Select rows from a DataFrame where ages are > 30:

import pandas as pd
import numpy as np

df = pd.DataFrame({'Name': ['Alice', 'Bob', 'Charlie'],
                   'Age': [25, 45, 35]})

mask = np.array(df['Age'] > 30)

Statistics on Subsets

Calculate statistics like mean income for subsets matching a criteria:

incomes = [50000, 60000, 40000, 70000]
mask = incomes > 50000

incomes[mask].mean() # 60000

Image Processing

Masking pixels based on color thresholds for green screen processing:

image = load_image()
green_screen_mask = (image[:, :, 1] > 240) & (image[:, :, 2] < 10)

image[green_screen_mask] = [0, 0, 0] # Remove green background

As you can see, boolean indexing and masking have many applications working with real-world data.


This guide covered the fundamentals of boolean indexing and masking in NumPy in depth. The key takeaways are:

There are many possibilities to use these techniques for efficient array querying and conditional data selection. Combine boolean indexing and masking with NumPy’s other features like fancy indexing, vectorization, and broadcasting to unlock the library’s full potential for your data projects.