HOWTO · NumPy

Converter Pandas Series para NumPy Array

Converta os valores de uma pandas Series em um array NumPy com `Series.to_numpy()` e escolha alternativas compatíveis mantendo o índice separado.

Nesta página

Uma pandas Series armazena valores junto com um índice de rótulos. Para obter um array NumPy com os valores, chame Series.to_numpy() na própria Series. Os rótulos não são incluídos; mantenha ou converta o índice separadamente se precisar dele na etapa seguinte.

Converter uma pandas Series em um array NumPy com Series.to_numpy()

Series.to_numpy() é a escolha direta quando você precisa de um ndarray do NumPy. O exemplo cria uma Series com dois valores numéricos e seus rótulos, converte os valores da Series e examina o array resultante e seu dtype. Ele exibe os valores [82 91] e informa que o dtype do array é int64.

Execute este exemplo:

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

import pandas as pd

scores = pd.Series([82, 91], index=["Mia", "Noah"], name="score")
values = scores.to_numpy()
print(values)
print(values.dtype)
[82 91]
int64

O array contém os valores na ordem da Series. Ele não contém "Mia" nem "Noah"; esses rótulos continuam em scores.index. Essa distinção importa ao passar valores para uma operação do NumPy, que usa a ordem posicional e não leva consigo os rótulos do pandas.

Use Series.array quando precisar do array de extensão do pandas

Use Series.array quando a operação seguinte precisar receber a representação de array do pandas. Dependendo dos dados da Series, essa representação pode ser um array de extensão, em vez de um ndarray do NumPy. Arrays de extensão preservam comportamentos específicos do pandas para valores cujos tipos de dados não correspondem diretamente a um dtype convencional do NumPy. Se a API que receberá o valor exigir especificamente um ndarray, use Series.to_numpy().

Por exemplo, a expressão scores.array acessa a representação de array da Series, enquanto scores.to_numpy() solicita a representação do NumPy. Essas opções atendem a consumidores diferentes; não presuma que o resultado de Series.array seja um ndarray nem o passe a uma API que exija um sem antes verificar os requisitos dela.

Use Series.values ou numpy.asarray() como alternativas compatíveis

Series.values é uma alternativa concisa para obter os valores da Series como um objeto semelhante a um array. O resultado exato pode depender do dtype da Series; por isso, use Series.to_numpy() quando quiser um método explícito de conversão com resultado em ndarray do NumPy. numpy.asarray(scores) é outra forma compatível de solicitar um array a partir de uma Series; ela é útil ao trabalhar com código NumPy que já aceita entradas semelhantes a arrays.

Essas formas tratam dos valores da Series, não de seus rótulos. Escolha conforme o contrato do código que consumirá o resultado: use Series.to_numpy() para uma conversão explícita para ndarray, Series.array para a representação de array do pandas ou Series.values e numpy.asarray() quando essas formas compatíveis se encaixarem no código ao redor. Nenhuma delas converte o índice no array de valores.

Verifique o resultado do array e trate o índice e o dtype separadamente

Examine o resultado quando o dtype puder afetar cálculos posteriores ou o armazenamento. Em geral, uma Series numérica produz um dtype numérico do NumPy; dados representados por valores específicos do pandas ou por valores mistos podem exigir uma representação diferente no NumPy. Verifique values.dtype para saber o resultado real dos seus dados, em vez de presumir que toda Series se torna o mesmo tipo de array. Não mostramos controles opcionais de dtype ou cópia porque as evidências fornecidas para esta tarefa não estabelecem orientações específicas por versão para Series.

Se também precisar dos rótulos, acesse scores.index separadamente e mantenha explícita no programa a relação entre rótulos e valores. Converter apenas os valores elimina o alinhamento por rótulo das operações subsequentes do NumPy. Esse costuma ser o comportamento desejado no processamento numérico, mas, se o código combinar valores de várias Series, confirme primeiro se a ordem delas corresponde. A conversão de uma Series para array não alinha duas Series pelos respectivos rótulos.