Encontre o primeiro índice de elemento em NumPy Array

Para encontrar o primeiro índice de um valor em um array NumPy unidimensional, use np.where(array == value)[0][0] quando houver garantia de que o valor está presente. A expressão retorna a primeira posição correspondente; se o valor puder estar ausente, verifique antes se há uma correspondência. Os índices do NumPy começam em zero.

Encontre o primeiro índice correspondente com np.where()

np.where(condition) retorna uma tupla que contém um array de índices para cada dimensão. Em um array unidimensional, o primeiro item da tupla é a lista de posições correspondentes. Selecione o primeiro item dessa lista para obter a primeira correspondência.

Execute este exemplo:

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

import numpy as np

values = np.array([10, 20, 30, 40, 50, 20])
target = 20
matches = np.where(values == target)[0]
print(int(matches[0]))

1

Neste caso, matches contém as duas posições em que 20 aparece, e matches[0] seleciona a primeira. Se nenhum valor corresponder, matches ficará sem elementos e tentar indexá-lo causará IndexError. Quando não houver garantia de correspondência, verifique matches.size antes de selecionar um índice. Já a forma com três argumentos, np.where(condition, x, y), escolhe valores de x ou y; ela não retorna índices como a forma mostrada aqui.

Use np.nonzero() para encontrar índices correspondentes

Para uma condição booleana, np.nonzero() retorna os índices das entradas verdadeiras. Assim como a forma de um argumento de np.where(), retorna uma tupla de arrays de índices, um para cada dimensão do array. Em um array unidimensional, use o primeiro array dessa tupla.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

import numpy as np

values = np.array([4, 7, 4, 9])
positions = np.nonzero(values == 4)[0]
print(positions.tolist())

O resultado contém todas as posições correspondentes, na ordem do array. Para obter apenas a primeira correspondência, use positions[0] somente depois de verificar que o array não está vazio. Em um array multidimensional, cada item da tupla contém as coordenadas de uma dimensão; combine as entradas correspondentes para localizar cada ocorrência.

Use np.argmax() para encontrar uma correspondência booleana

np.argmax() retorna a posição do maior valor. Aplicada a uma máscara booleana, retorna a posição do primeiro True, pois True é maior que False. Uma máscara em que todos os valores são falsos também resulta em 0; por isso, verifique se há uma correspondência antes de usar o resultado.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

import numpy as np

values = np.array([5, 8, 3, 8])
mask = values == 8
first = int(np.argmax(mask)) if np.any(mask) else None
print(first)

Este padrão retorna None quando o valor procurado está ausente e, caso contrário, retorna a primeira posição correspondente. Para obter todas as posições correspondentes, use np.where() ou np.nonzero().

Use list.index() depois de converter o array

Ao converter um array unidimensional em uma lista Python, você pode usar o método list.index(). Ele retorna a primeira ocorrência. A conversão cria uma lista Python, acrescentando custos de tempo e memória; por isso, essa abordagem costuma ser mais conveniente para arrays pequenos ou para código que já usa listas.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

import numpy as np

values = np.array([10, 20, 30, 20])
items = values.tolist()
target = 20
index = items.index(target) if target in items else None
print(index)

A verificação de pertencimento deixa explícito que o resultado para um valor ausente é None; chamar items.index(target) diretamente quando o valor não está presente causa ValueError. Como a verificação e a busca percorrem a lista, para uma única consulta você pode, em vez disso, capturar ValueError em torno de list.index().

Use um laço para aplicar uma lógica personalizada

Um laço é útil quando cada elemento precisa passar por um teste personalizado que seria difícil expressar como uma condição vetorizada do NumPy. Inicialize o resultado com um valor que indique ausência e interrompa o laço assim que encontrar a primeira correspondência.

O código e os rótulos ou saídas exibidos nesta seção permanecem em inglês.

import numpy as np

values = np.array([12, 15, 18, 21])
index = None

for position, value in enumerate(values):
    if value % 2 == 0 and value > 12:
        index = position
        break

print(index)

O laço examina os elementos um por um e termina quando encontra o primeiro valor que satisfaz as duas condições. Para uma comparação simples de igualdade, uma máscara do NumPy costuma ser mais concisa; use o laço quando a regra de correspondência exigir ramificações ou estado personalizados.

Lide com correspondências ausentes, valores repetidos e dimensões do array

Escolha o formato do resultado de acordo com a tarefa:

• Para encontrar a primeira correspondência em um array unidimensional, obtenha as posições com np.where() ou np.nonzero(), verifique se há pelo menos uma e selecione a primeira posição.
• Para obter todas as correspondências, mantenha o array de índices completo. Valores repetidos geram várias posições; não selecione [0] se precisar de todas elas.
• Em um array bidimensional, np.where(matrix == target) retorna (row_indices, column_indices). As entradas correspondentes formam pares de coordenadas. Por exemplo, (rows[0], columns[0]) representa a linha e a coluna da primeira correspondência, e não um único índice linear.
• Se precisar especificamente de uma posição linear em um array multidimensional, primeiro achate o array e procure nos valores resultantes. Quando necessário, converta essa posição linear de volta em coordenadas com np.unravel_index().
• np.argmax() retorna zero para uma máscara não vazia em que todos os valores são falsos, mas essa posição não indica uma correspondência. Se a máscara estiver vazia, np.argmax() causa ValueError. A expressão protegida acima verifica primeiro np.any(mask), portanto retorna None tanto quando a máscara não contém valores verdadeiros quanto quando está vazia.

Para buscas comuns em arrays numéricos, np.where() é uma opção direta quando você precisa da primeira correspondência ou de todas elas. Use np.nonzero() para obter as mesmas posições que satisfazem uma condição verdadeira, np.argmax() com uma máscara booleana verificada, list.index() quando for útil trabalhar com uma lista Python, e um laço para regras de correspondência personalizadas.