API · NumPy

Python numpy.argmax()

A função numpy.argmax() retorna os índices de valores com os valores mais altos no array NumPy dada.

Nesta página

Em Python com NumPy, numpy.argmax() retorna o índice de um valor máximo em um array; não retorna o próprio valor. Use esse índice para acessar o valor ou escolha um axis para obter um índice por fatia. Quando vários valores são iguais ao máximo, a função retorna a primeira ocorrência.

Como numpy.argmax() seleciona o índice de um valor máximo

Com o padrão axis=None, numpy.argmax() pesquisa o array como se seus elementos formassem uma única sequência achatada. Portanto, para uma entrada multidimensional, o índice retornado é uma posição nessa sequência. Ao informar um eixo, a pesquisa é feita nessa dimensão e retorna índices para as fatias restantes.

Sintaxe e parâmetros

A assinatura da função é numpy.argmax(a, axis=None, out=None). O argumento a é o array de entrada ou um objeto semelhante a um array. axis seleciona a dimensão da pesquisa; quando é omitido ou definido como None, a entrada é achatada primeiro. Em um array bidimensional, axis=0 pesquisa cada coluna e retorna índices de linha, enquanto axis=1 pesquisa cada linha e retorna índices de coluna. O eixo selecionado é removido do formato do resultado.

O argumento opcional out é um array que recebe o resultado. Seu formato deve corresponder ao formato do resultado, e seu tipo de dados deve comportar os índices retornados. A função retorna o índice ou um array de índices; use essas posições para acessar os valores máximos correspondentes.

Encontrar o índice de um valor máximo em arrays unidimensionais e multidimensionais

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

a = np.array([2, 6, 1, 5])
index = np.argmax(a)
print(index)
print(a[index])
1
6

Neste caso, o valor máximo é 6 e sua posição é 1, pois os índices do NumPy começam em zero. Para um array multidimensional, o comportamento padrão ainda retorna uma única posição no array achatado, e não um par de linha e coluna. Quando precisar das coordenadas no formato original, converta essa posição com numpy.unravel_index.

import numpy as np

a = np.array([[2, 1, 6],
              [7, 4, 5]])
index = np.argmax(a)
print(index)
print(np.unravel_index(index, a.shape))
3
(np.int64(1), np.int64(0))

A posição 3 no array achatado corresponde à linha 1, coluna 0, onde está o valor 7.

Escolher um eixo para encontrar índices em cada fatia

Em um array bidimensional com formato (2, 3), axis=0 reduz a dimensão das linhas: a saída contém um índice de linha por coluna. axis=1 reduz a dimensão das colunas: a saída contém um índice de coluna por linha. Esses índices são posições dentro de cada fatia pesquisada, não posições no array original achatado.

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

import numpy as np

a = np.array([[2, 1, 6],
              [7, 4, 5]])
print(np.argmax(a, axis=0))
print(np.argmax(a, axis=1))
[1 1 0]
[2 0]

Por exemplo, o maior elemento da primeira coluna é 7, no índice de linha 1; o maior elemento da primeira linha é 6, no índice de coluna 2.

Tratar empates e usar o índice retornado

Se o valor máximo ocorrer mais de uma vez, numpy.argmax() retorna a primeira posição correspondente na ordem pesquisada. Quando um eixo é informado, essa regra se aplica de forma independente a cada fatia. O exemplo unidimensional a seguir mostra a posição retornada e o valor encontrado nela.

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

import numpy as np

a = np.array([2, 6, 1, 6])
index = np.argmax(a)
print(index)
print(a[index])
1
6

Os dois valores máximos são 6, mas o índice 1 vem antes do índice 3. Em uma pesquisa multidimensional sem eixo, “primeiro” se refere à ordem do array achatado; com um eixo, refere-se à ordem dentro de cada fatia.

Gravar o resultado em out

Use out quando quiser gravar o resultado em um array existente. Seu formato deve corresponder ao resultado: um array de formato escalar serve para um resultado escalar, enquanto uma pesquisa com eixo exige um array com o formato da saída. Escolha um tipo de dados inteiro que comporte os índices. A chamada também retorna o mesmo resultado que grava em out.

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

import numpy as np

a = np.array([[2, 1, 6],
              [7, 4, 5]])
result = np.empty((), dtype=np.intp)
np.argmax(a, out=result)
print(result)
3

Nesta pesquisa padrão, o resultado tem formato escalar, portanto result é um array de dimensão zero. Se você adicionar um eixo, crie out com o formato do array de índices resultante.