Arrays NumPy e computação vetorizada

O NumPy armazena dados numéricos em arrays para que uma expressão possa operar sobre muitos valores. Importe-o com import numpy as np; o nome curto np é a forma usual de chamar suas funções.

Leia a estrutura de um array

Um ndarray é uma grade retangular cujos elementos compartilham um tipo de dados. Uma dimensão também é chamada de eixo. Comece com uma tabela pequena:

import numpy as np
a = np.array([[1, 2, 3], [4, 5, 6]])

Seus atributos respondem a quatro perguntas diferentes:

O eixo 0 indexa linhas; o eixo 1 indexa colunas. Uma tabela de dados com uma linha por pessoa e colunas para altura, massa e idade teria forma (100, 3) para 100 pessoas. O produto dos valores da forma fornece o número de elementos.

Um vetor não tem eixo de linha ou de coluna

np.array([2, 4, 6, 8]) tem forma (4,) e um eixo. A vírgula faz dela uma tupla de uma entrada. A forma (1, 4) tem dois eixos: uma linha e quatro colunas. A forma (4, 1) também tem dois eixos, mas quatro linhas e uma coluna. Esses arrays contêm quatro valores, mas se comportam de modo diferente quando combinados com outros arrays. np.array(7) é um array de dimensão zero: sua forma é () e seu ndim é 0.

Arrays mudam o significado dos operadores

Uma lista é um contêiner de uso geral do Python. Um array é projetado para cálculos em posições correspondentes.

Na adição de arrays, 1 forma um par com 3 e 2 forma um par com 4. O array mantém o mesmo tamanho.

Por que arrays numéricos são eficientes

Um array numérico recém-criado armazena valores do mesmo tipo juntos na memória. O NumPy executa o laço sobre esses valores em código compilado, evitando uma operação separada em Python para cada número. Um milhão de valores float64 ocupa 8.000.000 de bytes de armazenamento dos elementos, disponíveis como a.nbytes em um array desse tamanho. Uma lista Python também armazena referências a objetos Python, então precisa de muito mais espaço. Os ganhos de desempenho dependem do cálculo e do computador.

O tamanho de um array não aumenta por meio de um método append no próprio objeto. np.append(a, value) aloca um novo array. Para dados coletados um valor por vez, construa uma lista Python e converta uma vez. A entrada aninhada deve ser retangular: np.array([[1, 2], [3]]) gera ValueError porque os comprimentos de suas linhas diferem.

Reconheça os resultados exibidos

print(np.array([1, 2, 3])) mostra [1 2 3]. Uma exibição interativa usa array([1, 2, 3]). Para np.array([5, 6])[0] em um computador de 64 bits, o NumPy 2 exibe np.int64(5); ele participa de operações aritméticas como o número 5.

Escolha uma função de criação perguntando o que você conhece: os valores propriamente ditos, uma forma e um valor de preenchimento, um passo ou uma quantidade necessária de pontos. Essa escolha faz o código expressar como os dados devem ser construídos.

Comece pelos valores ou por uma forma

np.array([3, 1, 4]) cria um vetor. Uma lista de listas de mesmo comprimento cria uma tabela. Passe os valores como uma única sequência; np.array(1, 2, 3) não fornece três elementos corretamente.

Para uma forma multidimensional, os parênteses importam. np.zeros((2, 3)) passa uma tupla. Em np.zeros(2, 3), o Python envia 3 como argumento do tipo de dados, o que causa um erro de tipo. Zeros e uns usam float64 por padrão; full infere seu tipo de dados a partir do valor de preenchimento. Adicione dtype=int quando precisar armazenar números inteiros.

empty não garante zeros nem valores iniciais significativos. Leia seus valores somente depois de atribuir cada elemento que você usará. zeros é uma escolha mais simples quando um zero inicial tem significado.

Escolha um passo ou uma quantidade de pontos

np.arange(start, stop, step) segue a ideia de passos de range do Python. np.arange(2, 11, 3) resulta em [2 5 8]: comece em 2 e some 3 enquanto permanecer abaixo de 11. Com um argumento, np.arange(5) começa em 0 e resulta em [0 1 2 3 4].

Passos de ponto flutuante podem produzir extremos inesperados. Por exemplo, np.arange(1, 1.3, 0.1) inclui o valor exibido 1,3 porque o arredondamento binário afeta o cálculo da sequência. Para uma grade decimal com quantidade fixa de pontos, use linspace:

grid = np.linspace(0, 1, 5)
# array([0.  , 0.25, 0.5 , 0.75, 1.  ])

Ambos os extremos são incluídos por padrão. Cinco pontos formam quatro intervalos. Dez pontos entre 0 e 1 formam nove intervalos, então seu espaçamento é aproximadamente 0,111; passos de 0,1 exigem 11 pontos.

Reutilize uma estrutura existente

np.zeros_like(a), np.ones_like(a) e np.full_like(a, value) criam novos arrays com a forma e o tipo de dados de a. O tipo de dados herdado importa: preencher um modelo de inteiros com um decimal pode causar a perda da parte decimal, a menos que você solicite um tipo de ponto flutuante. np.eye(3) cria uma matriz identidade quadrada com uns na diagonal e zeros nas demais posições.

Aloque uma tabela de dados uma vez

Para a precipitação em milímetros em três estações ao longo de quatro semanas:

rain = np.zeros((3, 4))
rain[0] = [12.0, 0.0, 5.5, 8.0]

A primeira atribuição preenche uma linha e preserva a forma (3, 4). Se o número de leituras for conhecido, reservar a tabela inteira evita alocar repetidamente arrays maiores. Se a quantidade de entradas for desconhecida, acumule os valores em uma lista e chame np.array quando a coleta terminar.

O tipo de dados de um array controla o que ele pode armazenar e quanta memória cada valor precisa. Escolher o tipo adequado também evita que cálculos percam informações sem aviso.

Inspecione o tipo de armazenamento

int64 armazena números inteiros de 64 bits, float64 armazena números binários de ponto flutuante e bool armazena valores verdadeiro ou falso. Tipos Unicode como <U5 armazenam texto com um comprimento máximo de caracteres. a.itemsize é o número de bytes por elemento; a.nbytes é a.size * a.itemsize. Um float64 usa 8 bytes e tem precisão de cerca de 15 algarismos decimais significativos.

Em computadores típicos de 64 bits, entradas de números inteiros usam inteiros de 64 bits. O NumPy 2 também usa esse padrão no Windows de 64 bits. Entradas decimais normalmente resultam em float64.

A inferência escolhe um tipo compartilhado

np.array([1, 2.5]) se torna [1. 2.5]: o inteiro é representado como um número de ponto flutuante. np.array([True, 2]) se torna [1 2]. Misturar números e texto pode transformar o array inteiro em texto, então um rótulo como 'n/a' pode fazer operações aritméticas posteriores falharem. Inspecione dtype quando dados aparentemente numéricos não puderem ser somados ou multiplicados.

Converta de forma consciente

astype retorna uma cópia convertida:

x = np.array([1.7, -1.7, 2.5])
whole = x.astype(int)
# array([ 1, -1,  2])

Essa conversão corta em direção a zero; ela não arredonda. np.round(x).astype(int) resulta em [2 -2 2] porque valores exatamente na metade são arredondados para o valor par mais próximo. Texto como '1.5' é convertido com astype(float), mas 'n/a' gera ValueError. Limpe os marcadores antes da conversão.

Atribuições usam o tipo de dados do destino. Após a = np.array([1, 2, 3]), atribuir a[0] = 9.9 armazena 9 sem aviso. Converter o array inteiro para ponto flutuante antes permite que atribuições posteriores preservem decimais.

Inteiros de tamanho fixo podem sofrer estouro

Um int8 armazena valores de −128 a 127; um uint8 armazena de 0 a 255. Somar dois arrays uint8 que contêm 250 e 10 produz 4 devido ao retorno ao outro extremo da faixa. Multiplicar um array int8 que contém 100 por 2 produz −56. Um inteiro Python que não cabe no tipo do array, como 300 somado a um array int8 no NumPy 2, gera OverflowError. Amplie os tipos inteiros pequenos antes de cálculos que possam exceder sua faixa.

Divisão e decimais aproximados

A divisão com piso arredonda para baixo, em direção ao infinito negativo, o que difere do truncamento para resultados negativos. A divisão verdadeira retorna resultados de ponto flutuante para entradas inteiras.

Muitas frações decimais são aproximações em binário. 0.1 + 0.2 == 0.3 é falso; np.isclose compara valores correspondentes com uma tolerância, e np.allclose fornece uma resposta para o array inteiro.

O marcador de valor ausente np.nan é de ponto flutuante. Arrays de inteiros não podem armazená-lo. Portanto, np.array([1, 2, np.nan]) se torna de ponto flutuante; converter valores ausentes para inteiros não os corrige e pode produzir resultados sem significado.

A indexação localiza valores por posição. O fatiamento seleciona uma sequência regular de posições. Em uma tabela, escreva um seletor para cada eixo, para que o código indique tanto as linhas quanto as colunas necessárias.

Leia um vetor

Para a = np.array([10, 20, 30, 40, 50]), a posição 0 contém 10 e a posição −1 contém 50. Uma fatia tem a forma start:stop:step, com o valor final excluído:

Omitir o início ou o fim estende a seleção até o extremo correspondente. Uma fatia pode ultrapassar o array e ser encurtada automaticamente. Uma única posição inválida, como a[5], gera IndexError.

Dê a cada eixo da tabela seu próprio seletor

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

m[1, 2] lê a linha 1, coluna 2, fornecendo 6. A vírgula separa os eixos. Dois-pontos sozinhos selecionam o eixo inteiro: m[0, :] fornece a primeira linha [1 2 3], e m[:, 1] fornece a segunda coluna [2 5 8]. Para um bloco, m[:2, 1:] seleciona as linhas 0 e 1 e as colunas 1 e 2, fornecendo [[2 3] [5 6]].

Evite tratar a indexação com colchetes repetidos como intercambiável com a indexação por vírgula. m[1][2] localiza o mesmo escalar que m[1, 2]. Mas m[:][0] primeiro seleciona todas as linhas e depois seleciona a primeira linha. Ele não seleciona a primeira coluna, que é m[:, 0].

Preveja quais eixos permanecem

Um único seletor inteiro remove seu eixo. Uma fatia mantém seu eixo mesmo quando apenas uma posição é selecionada. Assim, m[:, 1] tem forma (3,), enquanto m[:, 1:2] tem forma (3, 1). Ambos selecionam 2, 5 e 8, mas apenas o segundo mantém um eixo de coluna. Essa diferença se torna importante ao subtrair ou multiplicar arrays com outras formas.

A mesma regra se estende além das tabelas. Se t.shape é (2, 3, 4), t[0] tem forma (3, 4), t[0, 1] tem forma (4,), e t[:, :, 0] tem forma (2, 3). Quaisquer eixos finais omitidos do índice são selecionados por inteiro.

Altere as posições selecionadas

A atribuição por meio de um índice escreve no array existente. a[1:3] = 0 substitui ambos os valores selecionados por zero; o escalar é aplicado em toda a seleção. m[0] = [0, 0, 0] substitui uma linha completa. Os valores atribuídos devem ser compatíveis com a forma da seleção e são convertidos para seu tipo de dados.

Para quatro estudantes e três provas:

scores = np.array([[78, 85, 92], [64, 70, 58],
                   [88, 91, 95], [72, 68, 80]])

scores[2] é o [88 91 95] do terceiro estudante. scores[:, -1] fornece os resultados da última prova [92 58 95 80]. scores[1:3, :2] fornece [[64 70] [88 91]]: dois estudantes, cada um mantendo duas colunas de provas.

Uma seleção pode compartilhar seus dados com o array original ou ter dados independentes. Saber qual é o caso evita que alterações em uma pequena seleção modifiquem inesperadamente uma tabela maior.

Distinga referências ao mesmo objeto, uma visão e uma cópia

Para a = np.arange(6) e b = a[2:5], atribuir b[0] = 99 faz a ser igual a [0 1 99 3 4 5]. A primeira posição da visão se refere à posição 2 no original. Isso difere do fatiamento de uma lista Python, que cria uma nova lista.

Copie antes de editar quando o original precisar permanecer intacto. Uma pequena visão mantida também pode manter uma grande área de memória dos dados originais ativa; copiar essa pequena parte permite que ela exista de forma independente.

Selecione posições arbitrárias

A indexação avançada por inteiros usa uma lista ou array de inteiros. Ela permite posições reordenadas e repetidas:

a = np.array([10, 20, 30, 40, 50])
a[[4, 0, 0]]
# array([50, 10, 10])

Para m = np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]), m[[0, 2]] seleciona a primeira e a terceira linhas. m[:, [2, 0]] seleciona a última e a primeira colunas nessa ordem, resultando em [[3 1] [6 4] [9 7]].

Duas listas de inteiros em um índice selecionam coordenadas pareadas. m[[0, 2], [1, 2]] pareia a linha 0 com a coluna 1 e a linha 2 com a coluna 2, produzindo [2 9]. Ela não seleciona todas as combinações. Para obter o bloco formado por ambas as linhas e ambas as colunas, use:

m[np.ix_([0, 2], [1, 2])]
# array([[2, 3], [8, 9]])

Selecionar primeiro as linhas e depois as colunas, m[[0, 2]][:, [1, 2]], fornece o mesmo bloco.

Leitura e atribuição se comportam de modo diferente

A indexação avançada por inteiros e a filtragem booleana retornam cópias. Se c = a[[0, 1]], alterar c[0] deixa a inalterado. Mas a[[0, 1]] = -1 escreve diretamente nessas posições originais. Uma seleção salva e uma atribuição por meio de um índice são operações diferentes.

Isso também explica por que edições encadeadas podem não atingir a origem. Em a[[0, 1]][0] = -1, a primeira seleção já é uma cópia temporária. A escrita final altera esse array temporário, não a.

Verifique o compartilhamento diretamente

np.shares_memory(x, y) verifica se dois arrays ocupam uma área comum na memória. Retorna verdadeiro para uma fatia comum não vazia e falso para uma cópia obtida por indexação avançada por inteiros. O atributo base pode identificar o objeto que detém a memória, mas não precisa identificar o array que você fatiou mais recentemente. Se a = np.arange(6), b = a[2:5] e c = b[0:2], então c.base is a é verdadeiro e c.base is b é falso. Use shares_memory quando a questão for especificamente se dois arrays compartilham dados.

Uma máscara booleana registra quais valores satisfazem uma condição. Depois que uma máscara existe, as mesmas decisões de verdadeiro ou falso podem selecionar valores, contar eventos ou escolher substituições.

Construa e aplique uma máscara

t = np.array([18.5, 22.0, 15.2, 25.8, 21.1])
warm = t > 20
t[warm]
# array([22. , 25.8, 21.1])

A comparação produz [False True False True True]. A indexação booleana mantém as posições verdadeiras e retorna uma cópia. Uma máscara de 1 dimensão usada em um eixo deve ter o mesmo comprimento desse eixo.

Para combinar condições, use & para e, | para ou e ~ para não. Coloque cada comparação entre parênteses:

comfortable = (t > 18) & (t < 23)
t[comfortable]
# array([18.5, 22. , 21.1])

and e or do Python tentam obter um único valor lógico de um array inteiro e falham para arrays com vários elementos. Omitir os parênteses também altera a forma como o Python agrupa a expressão, pois operadores bit a bit têm precedência sobre comparações.

Conte, meça ou teste condições

True contribui com 1 e False contribui com 0. warm.sum() é 3 e warm.mean() é 0,6, a fração de dias acima de 20 °C. np.count_nonzero(warm) também conta as entradas verdadeiras. warm.any() pergunta se pelo menos um dia é quente; warm.all() pergunta se todos os dias são quentes.

Essas operações respondem a perguntas diferentes de t[warm].mean(), que calcula a temperatura média nos dias quentes. A média de uma máscara mede uma proporção; a média das medições selecionadas mantém a unidade da medição.

Substitua valores ou escolha entre alternativas

A atribuição por meio de uma máscara atualiza as posições selecionadas. Com t2 = t.copy(), a linha t2[t2 < 16] = 16 eleva as leituras baixas para 16. np.clip(t, 16, 25) retorna um novo array limitado nos dois extremos, [18.5 22. 16. 25. 21.1].

np.where(condition, x, y) constrói um novo resultado que recebe x nas posições verdadeiras e y nas posições falsas. np.where(t > 20, 'warm', 'cool') fornece um rótulo em cada posição original. Já a filtragem encurta o resultado. Com apenas uma condição, np.where(t > 20) retorna uma tupla de arrays de índices, aqui (array([1, 3, 4]),).

Mantenha valores ou registros completos

Uma máscara de mesma forma em um array de 2 dimensões extrai os elementos correspondentes em um vetor achatado. Em m[m > 5], a estrutura das linhas é perdida. Para manter registros completos, derive um valor booleano por linha a partir de uma coluna:

scores = np.array([[78, 85, 92], [64, 70, 58],
                   [88, 91, 95], [72, 68, 80]])
scores[scores[:, 2] >= 90]
# array([[78, 85, 92], [88, 91, 95]])

Encontre valores ausentes explicitamente

NaN não é igual nem a si mesmo em comparações. Comparações de igualdade e ordem com NaN são falsas; a comparação de desigualdade é verdadeira. Assim, nem x == np.nan nem x != np.nan identifica corretamente as entradas presentes e ausentes. np.isnan(x) marca as posições ausentes, e x[~np.isnan(x)] mantém os valores presentes.

Alterar a forma muda como os valores são agrupados em eixos. Remodelar, transpor e adicionar um eixo têm funções diferentes, mesmo quando algumas dessas operações produzem a mesma forma final.

Remodele sem alterar o número de elementos

a = np.arange(6)
r = a.reshape(2, 3)
# array([[0, 1, 2], [3, 4, 5]])

A ordem padrão preenche uma linha por vez: o último eixo varia mais rapidamente. Remodelar os mesmos valores para (3, 2) resulta em [[0 1] [2 3] [4 5]]. O produto das novas dimensões deve ser igual ao número original de elementos. Doze elementos cabem em (3, 4), mas não em (5, 3).

Uma dimensão pode ser -1, permitindo que o NumPy infira seu comprimento. np.arange(12).reshape(-1, 3) fornece quatro linhas de três elementos; reshape(2, -1) fornece duas linhas de seis elementos. Duas dimensões desconhecidas não são permitidas porque seus comprimentos individuais não podem ser determinados apenas pelo total.

A transposição troca os eixos

Para r acima, r.T é [[0 3] [1 4] [2 5]], com forma (3, 2). Cada coluna antiga agora é uma linha. Essa disposição difere de r.reshape(3, 2), embora as formas resultantes sejam iguais.

Uma transposição é útil quando a próxima operação precisa da ordem inversa dos eixos. Uma remodelagem é útil quando uma sequência já tem um agrupamento significativo, como meses agrupados em trimestres.

A transposição de um array de 1 dimensão não cria uma coluna

v = np.arange(3) tem apenas um eixo, então v.T continua com forma (3,). Adicione um eixo explicitamente:

column = v[:, np.newaxis]  # shape (3, 1)
row = v[np.newaxis, :]     # shape (1, 3)

v.reshape(-1, 1) e np.expand_dims(v, 1) também criam uma coluna. np.squeeze(column) remove seu eixo de comprimento um e retorna a forma (3,). Adicionar um eixo não altera os valores, mas indica como eles devem ser alinhados em operações aritméticas posteriores.

Achatamento e compartilhamento de memória

r.ravel() e r.flatten() listam os valores em um resultado de 1 dimensão. ravel retorna uma visão quando possível; flatten sempre copia. reshape(-1) é outra forma de solicitar uma organização de 1 dimensão, mas o compartilhamento de memória depende da disposição da entrada. A remodelagem pode precisar de uma cópia; a transposição compartilha dados em sua visão do array. Use .copy() quando for necessário armazenamento independente.

Agrupe valores mensais em trimestres

Para monthly = np.array([120, 135, 150, 160, 155, 170, 180, 175, 165, 150, 140, 130]), monthly.reshape(4, 3) cria quatro linhas de trimestres, cada uma com três meses. Somar cada linha com .sum(axis=1) resulta em [405 485 520 420]. O primeiro total é 120 + 135 + 150 = 405. A remodelagem funciona porque a entrada em ordem cronológica já mantém juntos os meses de cada trimestre.

A união combina valores de vários arrays. A divisão corta um array em partes. Primeiro decida se a operação deve estender um eixo existente ou introduzir um novo.

Concatene ao longo de um eixo existente

np.concatenate([a, b], axis=0) une vetores pelas extremidades. Unir [1 2] a [3 4 5] resulta em [1 2 3 4 5].

Para dois arrays, cada um com forma (2, 3), o eixo 0 adiciona linhas e resulta em (4, 3). O eixo 1 adiciona colunas e resulta em (2, 6). Apenas o eixo de união pode ter comprimentos diferentes. Assim, as formas (2, 3) e (2, 2) podem ser unidas ao longo do eixo 1 em (2, 5), mas não ao longo do eixo 0, pois seus números de colunas diferem.

Os arrays devem ser passados juntos como uma sequência, como [a, b]. A união cria um novo array combinado e copia os dados das entradas.

Empilhe ao longo de um novo eixo

Para p = np.array([1, 2, 3]) e q = np.array([4, 5, 6]):

stack exige formas de entrada iguais e adiciona um eixo. concatenate preserva o número de eixos. As funções auxiliares expressam disposições comuns: vstack([p, q]) cria linhas, hstack([p, q]) une essas entradas de 1 dimensão pelas extremidades, e column_stack([p, q]) cria colunas. O comportamento de hstack em 1 dimensão explica por que seu nome, por si só, não basta para prever uma tabela.

Divida por limites ou por quantidade de partes

np.split(np.arange(10), [3, 7]) corta antes das posições 3 e 7, produzindo [0 1 2], [3 4 5 6] e [7 8 9]. As posições de corte não são comprimentos das partes.

Um segundo argumento inteiro solicita partes iguais: np.split(x, 3) pede três partes iguais. Dez elementos não podem ser divididos igualmente em três partes de tamanho inteiro, então isso gera ValueError. np.array_split(np.arange(10), 3) permite comprimentos desiguais e produz 4, 3 e 3. Essas chamadas de divisão retornam uma coleção de arrays, não um único array com um novo eixo de empilhamento.

Construa uma tabela de medições

h = np.array([1.62, 1.75, 1.80])  # meters
w = np.array([55.0, 72.5, 80.0])  # kilograms
data = np.column_stack([h, w])

A forma (3, 2) representa três pessoas com altura e massa em colunas. Selecionar data[:, 1] / data[:, 0] ** 2 calcula a massa dividida pela altura ao quadrado para cada linha, resultando em aproximadamente 21,0; 23,7 e 24,7 kg/m². Manter os dois arrays de medições na mesma ordem de pessoas é essencial.

Se a entrada chegar em lotes, reúna os arrays dos lotes em uma lista Python e chame concatenate uma vez. Unir novamente um array crescente a cada passagem do laço copia repetidamente seus dados existentes.

A vetorização expressa um cálculo para arrays inteiros. O NumPy cuida do trabalho repetido em cada elemento em código compilado, para que a expressão Python permaneça próxima do cálculo desejado.

Transforme um laço em aritmética de posições correspondentes

prices = np.array([2.50, 4.00, 1.20])
qty = np.array([3, 1, 5])
line_totals = prices * qty
order_total = line_totals.sum()

Os produtos são [7.5 4. 6.] e sua soma é 17,5. Cada preço é pareado com sua própria quantidade. Um laço Python que atualiza um total produz o mesmo resultado, mas faz o Python tratar cada par separadamente.

Todos os operadores aritméticos atuam elemento a elemento: +, -, *, /, //, % e **. Um escalar é aplicado a cada entrada. 10 - np.array([1, 2, 3]) resulta em [9 8 7]; a ordem dos operandos continua importante. Dois arrays precisam ter formas iguais ou compatíveis com difusão.

Distinga produtos elemento a elemento de produtos matriciais

* multiplica entradas correspondentes. Para A = np.array([[1, 2], [3, 4]]) e B = np.array([[5, 6], [7, 8]]), A * B resulta em [[5 12] [21 32]]. A multiplicação de matrizes usa @ e resultaria em [[19 22] [43 50]]. Escolha * para medições pareadas, como preço e quantidade.

Comparações também retornam uma resposta por posição

a == b produz um array booleano. Ele não pergunta se dois arrays são iguais como objetos inteiros. Uma instrução if precisa de um valor lógico, então if a == b: falha para resultados com vários elementos. np.array_equal(a, b) testa a igualdade exata dos arrays inteiros. Para decimais aproximados, np.allclose(a, b) testa a concordância dentro de uma tolerância.

Entenda os avisos de divisão

Com as configurações padrão de erro do NumPy, a divisão de ponto flutuante por zero produz um aviso e valores especiais:

np.array([1.0, -1.0, 0.0]) / 0
# array([ inf, -inf, nan])

np.isfinite identifica resultados que não são infinitos nem NaN. Já a divisão inteira com piso por zero retorna zeros inteiros com um aviso. Esses zeros parecem finitos, então inspecione os denominadores inteiros com (d == 0).any() antes da divisão com piso. Um aviso merece atenção mesmo quando o programa continua.

Decida se deve atualizar o próprio objeto

a += value modifica o armazenamento existente e mantém seu tipo de dados. Se a for um array de inteiros, a += 0.5 gera um erro de conversão porque o resultado de ponto flutuante não pode ser armazenado segundo a regra de conversão dessa operação. a = a + 0.5 cria um resultado de ponto flutuante e faz a se referir a ele. Isso difere de atribuir um decimal a um elemento inteiro, o que pode truncar sem aviso.

Construa uma expressão com várias etapas

Para old = np.array([2.50, 4.00, 8.00]) e new = np.array([3.00, 3.00, 8.00]), (new - old) / old * 100 resulta em [20. -25. 0.]. Primeiro encontre cada variação, depois divida-a pelo valor original e expresse a razão como uma porcentagem. Os sinais mostram um aumento, uma queda e nenhuma alteração. Os valores originais devem ser diferentes de zero para esse cálculo percentual.

Uma função universal aplica um cálculo separadamente em cada posição de um array. Essas funções estendem a vetorização além da aritmética comum, incluindo raízes, logaritmos, arredondamento, comparações e outras operações numéricas.

Escolha uma função adequada para arrays

Funções universais unárias recebem uma entrada. np.sqrt(np.array([1, 4, 9])) resulta em [1. 2. 3.], e np.abs(np.array([-2, 3])) resulta em [2 3]. np.exp é a função exponencial, np.log é o logaritmo natural e np.log10 é o logaritmo de base 10. Por exemplo, np.exp(0) é 1,0 e np.log10(1000) é 3,0.

O módulo math do Python opera em números individuais. math.sqrt(np.array([1, 4])) não consegue calcular ambas as raízes e gera um erro de tipo. Use a versão do NumPy para arrays numéricos. Operadores também chamam funções universais: a + b corresponde a np.add(a, b) e a * b a np.multiply(a, b).

Compare valores correspondentes ou reduza um array inteiro

Funções universais binárias recebem duas entradas. np.maximum([1, 5, 3], [4, 2, 6]) resulta em [4 5 6], escolhendo o maior valor em cada posição. np.minimum escolhe o menor, e np.power eleva bases correspondentes a potências.

np.maximum(x, 0) define entradas negativas como zero em um novo resultado. É diferente de np.max(x), uma agregação que retorna um único maior valor. Para [1, 5, 3], max resulta em 5; maximum precisa de outra entrada e mantém a estrutura elemento a elemento.

Arredonde com a regra desejada

np.round(x, 2) mantém duas casas decimais. Valores exatamente na metade seguem a regra do par: np.round([0.5, 1.5, 2.5]) resulta em [0. 2. 2.]. A aproximação binária pode afetar valores decimais que parecem estar exatamente na metade, então interprete os decimais exibidos considerando sua representação em ponto flutuante.

Inspecione valores fora do domínio de uma função

Para entradas reais de ponto flutuante, np.sqrt(-1.0) retorna NaN com um aviso, enquanto np.log(0.0) retorna infinito negativo com um aviso nas configurações padrão de erro. Ao contrário de math.sqrt(-1), essas chamadas normalmente não interrompem a execução com uma exceção de domínio. Verifique as entradas quando a operação matemática exigir uma faixa restrita. np.isnan marca NaN; np.isfinite marca valores que não são NaN nem infinitos; np.isclose compara valores com uma tolerância.

Combine funções universais em um cálculo útil

Para os arrays de coordenadas x = np.array([3, 5, 8]) e y = np.array([4, 12, 15]), calcule a distância da origem com np.sqrt(x ** 2 + y ** 2). Elevar ao quadrado resulta em [9 25 64] e [16 144 225]; somar resulta em [25 169 289]; as raízes são [5. 13. 17.]. np.hypot(x, y) calcula essas distâncias diretamente.

A difusão permite que arrays de formas diferentes participem de cálculos elemento a elemento. Os eixos alinhados determinam quais valores são pareados e quais são repetidos.

Compare dimensões pela direita

Alinhe as formas pelas extremidades direitas. Cada par de comprimentos de eixo deve ser igual ou ter um comprimento igual a 1. Eixos iniciais ausentes contam como comprimento 1. Um eixo de comprimento um se expande conceitualmente para corresponder ao outro comprimento; o NumPy não precisa copiar os valores de entrada repetidos.

Para (4, 3) e (3,), os últimos comprimentos coincidem em 3. A dimensão inicial ausente age como 1 e se expande para 4. O resultado é (4, 3): o vetor se aplica a cada linha. (4, 3) e (4,) falham porque os comprimentos finais 3 e 4 diferem e nenhum deles é 1. Um par incompatível gera ValueError.

Centralize na média ou padronize colunas

X = np.array([[1, 10], [2, 20], [3, 30]])
centered = X - X.mean(axis=0)

As médias das colunas são [2. 20.], de forma (2,). Elas se alinham ao último eixo de (3, 2), resultando em [[-1. -10.] [0. 0.] [1. 10.]]. Dividir o resultado centralizado por X.std(axis=0) padroniza cada coluna, produzindo aproximadamente −1,22; 0 e 1,22 ao longo de ambas as colunas. A dispersão de cada coluna deve ser diferente de zero para essa divisão.

Mantenha um eixo para cálculos por linha

Use uma tabela de notas com quatro estudantes e três provas:

scores = np.array([[78, 85, 92], [64, 70, 58],
                   [88, 91, 95], [72, 68, 80]])

scores.mean(axis=1) tem forma (4,). Ela não pode ser difundida como uma média por linha em relação a (4, 3). Preserve o eixo removido:

row_mean = scores.mean(axis=1, keepdims=True)
centered = scores - row_mean

row_mean agora tem forma (4, 1). Seu 4 inicial corresponde às linhas; seu 1 final se expande pelas três colunas. scores.mean(axis=1)[:, np.newaxis] cria a mesma forma. Para a linha [78, 85, 92], subtrair sua média de 85 resulta em [-7. 0. 7.].

Use a mesma regra para construir uma tabela

np.arange(1, 4)[:, np.newaxis] * np.arange(1, 5) combina (3, 1) e (4,). Ambos os arrays se expandem para a forma resultante (3, 4), produzindo [[1 2 3 4] [2 4 6 8] [3 6 9 12]].

A expansão também pode ser acidental. Uma coluna (3, 1) menos um vetor (3,) cria todas as nove diferenças entre pares, com forma (3, 3). Se você pretendia obter três diferenças correspondentes, deixe ambas as entradas com forma (3,), por exemplo com column.ravel().

Pondere cada coluna antes de somar

Para a mesma tabela de notas e w = np.array([0.2, 0.3, 0.5]), scores * w aplica os três pesos a cada linha. Somar com .sum(axis=1) resulta em [87.1 62.8 92.4 74.8]. O primeiro resultado é 15,6 + 25,5 + 46,0 = 87,1.

Uma agregação combina valores em menos resultados: um total, uma média, um extremo ou uma medida de dispersão. Escolher o eixo faz parte de escolher a pergunta, pois isso determina quais grupos de valores são combinados.

Reduza o eixo que você indicar

Para uma tabela (4, 3) com quatro estudantes e três provas, uma agregação sem axis usa todos os 12 valores. scores.sum() fornece um total. scores.mean(axis=0) reduz o eixo dos estudantes e deixa três médias de provas. scores.mean(axis=1) reduz o eixo das provas e deixa quatro médias de estudantes.

scores = np.array([[78, 85, 92], [64, 70, 58],
                   [88, 91, 95], [72, 68, 80]])

Sua soma geral é 941. As médias das colunas são [75.5 78.5 81.25]; as médias das linhas são aproximadamente [85. 64. 91.33 73.33]. Pergunte qual eixo deve desaparecer. Dizer “o eixo 0 significa cada linha” inverte a operação: o eixo 0 combina linhas.

Escolha a quantidade a retornar

Métodos como a.sum() e funções como np.sum(a) expressam a mesma operação básica. Os métodos do NumPy evitam o comportamento diferente das funções nativas do Python. Por exemplo, sum(scores) do Python soma os arrays das linhas para produzir totais das colunas, enquanto scores.sum() combina todas as entradas. max(scores) do Python tenta comparar linhas e gera um erro de valor lógico ambíguo.

Posições diferem de valores

scores.mean(axis=1).argmax() é 2: o terceiro estudante tem a maior média. argmax retorna a primeira posição quando há empate entre máximos. Sem um eixo em uma tabela, ele retorna um índice achatado em ordem por linhas; scores.argmax() é 8. np.unravel_index(8, scores.shape) recupera a coordenada (2, 2).

Use keepdims=True quando um resumo precisar se alinhar à tabela original. scores.sum(axis=1, keepdims=True) tem forma (4, 1), adequada para um valor de normalização por linha. Sem ele, o resultado tem forma (4,).

Mantenha totais intermediários quando a ordem importar

np.cumsum([3, 1, 4, 1, 5]) resulta em [3 4 8 9 14]. Cada posição é o total até aquele ponto. np.cumprod([1, 2, 3, 4]) resulta de modo semelhante em [1 2 6 24]. np.diff([3, 1, 4, 1, 5]) fornece as quatro variações entre vizinhos [-2 3 -3 4]. Em uma tabela, especifique axis=1 para obter totais acumulados separados ao longo das linhas.

Informe a convenção de dispersão

std e var dividem a soma dos desvios ao quadrado pelo número de valores por padrão: ddof=0. Use ddof=1 para a fórmula amostral, cujo divisor é uma unidade menor. Para [2, 4, 4, 4, 5, 5, 7, 9], a média é 5, o desvio padrão padrão é 2,0 e o desvio padrão amostral é aproximadamente 2,14. Um relatório deve deixar clara a convenção usada.

Resumos baseados na ordem descrevem onde os valores se encontram em uma distribuição ordenada. A ordenação também permite classificar registros, mas uma tabela exige cuidado para manter juntos os campos de cada registro.

Localize o centro e os quartis

Para x = np.array([12, 15, 11, 20, 18, 14]), a ordem crescente é [11 12 14 15 18 20]. Com seis valores, np.median(x) calcula a média dos dois centrais, 14 e 15, resultando em 14,5. Para uma quantidade ímpar, a mediana é o único valor central.

np.percentile(x, q) recebe uma porcentagem de 0 a 100. np.quantile(x, q) recebe a fração equivalente de 0 a 1. Sua interpolação linear padrão pode fornecer um valor entre observações. Para seis valores, a posição do 25º percentil, com contagem a partir de zero, é 0,25 × 5 = 1,25. Ela fica a um quarto do caminho entre 12 e 14, resultando em 12,5. Os percentis 50 e 75 são 14,5 e 17,25, então a amplitude interquartil é 4,75.

A mediana resiste mais a um valor extremo do que a média. Adicionar 200 a esses dados desloca a média de 15,0 para aproximadamente 41,4; a mediana passa de 14,5 para 15,0. Nenhuma das duas medidas descreve sozinha a distribuição inteira.

Escolha entre dados ordenados e posições de ordenação

np.sort(x) retorna uma cópia ordenada. x.sort() altera x e retorna None, então y = x.sort() não coloca valores ordenados em y. Para valores em ordem decrescente, use np.sort(x)[::-1].

Em um array de 2 dimensões, a ordenação usa o último eixo por padrão, ordenando cada linha independentemente. axis=0 ordena cada coluna independentemente. Nenhuma das operações ordena registros. Para tab = np.array([[3, 1], [1, 2], [2, 0]]), np.sort(tab, axis=0) resulta em [[1 0] [2 1] [3 2]], separando valores que originalmente pertenciam uns aos outros.

Para preservar registros, obtenha uma ordem a partir da coluna de chave e aplique-a a linhas inteiras:

order = tab[:, 0].argsort()
ranked = tab[order]
# array([[1, 2], [2, 0], [3, 1]])

A mesma ordem de índices pode reordenar vetores relacionados. Se avg = np.array([85.0, 64.0, 91.33, 73.33]) e names = np.array(['Ana', 'Ben', 'Chen', 'Dara']), order = np.argsort(avg)[::-1] ordena as médias em ordem decrescente. names[order] resulta em ['Chen' 'Ana' 'Dara' 'Ben'].

Conte valores distintos e teste a presença em uma coleção

np.unique retorna valores distintos ordenados. Com return_counts=True, também retorna as contagens correspondentes:

colors = np.array(['red', 'blue', 'red', 'green', 'blue', 'red'])
values, counts = np.unique(colors, return_counts=True)

As saídas são ['blue' 'green' 'red'] e [2 1 3]. values[counts.argmax()] encontra o valor mais frequente, 'red'. As posições das contagens correspondem às posições dos valores distintos.

np.isin(a, allowed) retorna uma máscara de presença em uma coleção. Para a = np.arange(1, 6), np.isin(a, [2, 4]) resulta em [False True False True False], pronta para selecionar esses valores ou seus registros associados.

Dados ausentes e subconjuntos filtrados precisam de uma política explícita de resumo. Um resultado numérico pode estar errado mesmo quando a operação no array é executada corretamente: um marcador pode ser contado como uma medição ou um subconjunto vazio pode ser confundido com uma média significativa.

Identifique valores ausentes antes de resumir

NaN se propaga por somas e médias comuns. Para x = np.array([3.0, np.nan, 5.0]), tanto x.sum() quanto x.mean() resultam em NaN. np.nansum(x) resulta em 8,0 e np.nanmean(x) resulta em 4,0, ignorando a posição ausente. Funções relacionadas incluem nanmax, nanmin, nanstd e nanmedian. Se todos os valores estiverem ausentes, nanmean retorna NaN com um aviso porque não restam valores observados.

Para leituras de sensor em °C:

r = np.array([21.5, np.nan, 22.1, 23.0, np.nan, 21.9])
missing = np.isnan(r)

missing.sum() é 2, missing.mean() é aproximadamente 0,33, e r[~missing] mantém quatro leituras. np.nanmean(r) é 22,125, usando apenas esses quatro valores. A comparação r == np.nan não marcaria as leituras ausentes.

Converta primeiro os códigos usados como marcadores

Um número como −999 pode representar dados ausentes em um sistema de entrada. O NumPy o trata como uma medição real até que você o substitua:

v = np.array([12, -999, 15, -999, 9]).astype(float)
v[v == -999] = np.nan
np.nanmean(v)  # 12.0

Converta primeiro para ponto flutuante porque um array de inteiros não pode armazenar NaN. Essa substituição só é adequada quando −999 está definido como código de valor ausente para esses dados.

O preenchimento altera a distribuição

Substituir temperaturas ausentes por zero faz a média do exemplo ser 14,75, embora nenhuma medição de temperatura zero tenha sido observada. Preenchê-las com a média observada, 22,125, preserva essa média, mas reduz a dispersão aparente. Um valor preenchido é uma estimativa introduzida, então seu efeito deve fazer parte da decisão de análise.

Para uma tabela D de 2 dimensões, np.nanmean(D, axis=0) resume os valores observados de cada coluna. Cada coluna pode ter uma contagem diferente. Para remover linhas que contêm qualquer valor ausente:

complete = ~np.isnan(D).any(axis=1)
clean_rows = D[complete]

A redução cria uma decisão por linha; a negação mantém linhas sem entradas ausentes. Com D = np.array([[1., 2.], [np.nan, 4.], [5., np.nan], [7., 8.]]), isso mantém [[1. 2.] [7. 8.]].

Resuma uma condição ou um grupo

Para temperaturas t, t[t > 20].mean() calcula a média apenas dos dias acima de 20 °C. Em dados agrupados, use uma máscara de rótulos correspondente: com group = np.array(['A', 'B', 'A', 'B', 'A']) e value = np.array([10, 20, 14, 26, 12]), value[group == 'A'].mean() é 12,0 e a média correspondente de B é 23,0. Percorra np.unique(group) para repetir isso para cada grupo.

Antes de resumir um subconjunto filtrado, verifique mask.any(). A média de uma seleção vazia é NaN com um aviso, enquanto sua soma é 0. Esse zero pode ser um total válido para uma seleção vazia, mas não estabelece que alguma medição estivesse presente.

Um gerador de números aleatórios permite amostragem, embaralhamento e simulação. Uma semente torna o estado inicial reproduzível, para que você possa executar novamente uma análise enquanto investiga sua lógica.

Crie um objeto Generator e reutilize-o

rng = np.random.default_rng(42)

O NumPy recomenda essa interface Generator para código novo. Seu gerador de bits padrão é PCG64. Sem uma semente, default_rng() obtém entropia nova do sistema operacional. Chamadas antigas como np.random.seed e np.random.rand usam um estado global compartilhado; objetos Generator permitem que uma análise gerencie diretamente seu próprio estado.

Valores pseudoaleatórios vêm de um algoritmo determinístico. O mesmo estado inicial e a mesma sequência de chamadas reproduzem a sequência no mesmo ambiente. Cada sorteio avança o estado. Criar um novo objeto Generator com a semente 42 em cada passagem de um laço reinicia a sequência, repetindo os mesmos sorteios iniciais em vez de continuá-la. Registre a versão do NumPy e o código, além da semente, pois a compatibilidade da sequência não é garantida entre versões ou em todos os ambientes. Para senhas ou tokens de segurança, use o módulo secrets do Python.

Escolha uma distribuição e uma forma de saída

size pode ser uma quantidade de elementos ou uma tupla de forma. Para normal, loc é a média da distribuição e scale é seu desvio padrão. Portanto, uma variância de 100 precisa de scale=10. A média e o desvio padrão reais de uma pequena amostra não precisam coincidir exatamente com os parâmetros da distribuição.

Para sorteios de inteiros, o limite superior é excluído por padrão. Um dado precisa de integers(1, 7), pois integers(1, 6) não pode sortear 6. integers(1, 6, endpoint=True) inclui o limite superior e também representa um dado.

Obtenha amostras com ou sem reposição

rng.choice(['heads', 'tails'], size=5) faz cinco sorteios com reposição. Um valor pode aparecer várias vezes. Para posições amostradas distintas, use replace=False; solicitar mais posições do que a população possui gera ValueError. As probabilidades podem ser fornecidas como p=[0.7, 0.3], na mesma ordem dos valores, e devem somar 1.

A amostragem sem reposição impede a seleção de uma posição de entrada duas vezes. Se a própria entrada contiver valores duplicados, valores iguais ainda poderão aparecer na amostra.

Embaralhe registros sem separar seus campos

rng.shuffle(a) reorganiza o array existente e retorna None. rng.permutation(a) retorna uma cópia embaralhada. rng.permutation(10) fornece os inteiros de 0 a 9 em ordem aleatória, úteis como índices de linhas.

Para um array de 2 dimensões, o eixo padrão é 0: linhas completas se movem juntas. Isso mantém alinhados os campos de cada observação. Para embaralhar dois arrays relacionados de forma consistente, gere uma permutação dos índices de registros compartilhados e aplique-a a ambos.

Uma simulação vetorizada representa ensaios repetidos como arrays, aplica a regra do evento a esses arrays e resume os resultados. A forma do array deve mostrar o que um ensaio contém.

Transforme um evento em uma proporção

rng = np.random.default_rng(42)
rolls = rng.integers(1, 7, size=100_000)
estimate = (rolls == 6).mean()

A máscara é verdadeira uma vez para cada 6 observado. Sua média estima a probabilidade desse evento, próxima de 1/6, ou aproximadamente 0,1667. rolls.mean() responde a uma pergunta diferente: a média das faces do dado, próxima de 3,5. Uma semente fixa repete uma estimativa; ela não torna essa estimativa exata.

A vetorização evita trabalho no nível do Python para cada sorteio, muitas vezes tornando simulações grandes muito mais rápidas que um laço. O ganho de velocidade depende do cálculo, do tamanho do array e do computador, então não é uma propriedade fixa do evento.

Use uma linha por ensaio com vários valores

Para simular dois dados em cada ensaio:

dice = rng.integers(1, 7, size=(100_000, 2))
totals = dice.sum(axis=1)
p_seven = (totals == 7).mean()

A tabela tem 100.000 linhas de ensaios e duas colunas de dados. Reduzir o eixo 1 produz um total por ensaio. Seis dos 36 pares ordenados igualmente prováveis somam 7, então a probabilidade estimada deve ficar próxima de 6/36. Reduzir o eixo 0 forneceria dois totais para todos os ensaios e perderia o evento de cada ensaio.

Simulações maiores ainda variam

Para ensaios independentes, o erro padrão de uma proporção estimada é:

Aqui $p$ é a probabilidade do evento e $n$ é a quantidade de ensaios. Para o 6 de um dado com 100.000 ensaios, ele é aproximadamente 0,0012. Uma aproximação normal coloca cerca de 95% das estimativas a uma distância máxima de 0,0023 de 1/6. Aumentar a quantidade de ensaios por um fator de 100 reduz o erro padrão por um fator de 10. Mais sorteios não corrigem um evento codificado incorretamente.

Construa e inspecione um passeio aleatório

steps = rng.choice([-1, 1], size=1000) sorteia passos para a esquerda ou para a direita. walk = steps.cumsum() fornece a posição após cada passo. Seu máximo e mínimo localizam as posições extremas visitadas. Para encontrar o primeiro ponto a pelo menos 10 unidades do início:

hit = np.abs(walk) >= 10
if hit.any():
    step_count = hit.argmax() + 1

argmax localiza a primeira entrada verdadeira, mas também retorna 0 quando todas as entradas são falsas. A verificação com any() distingue uma passagem real de nenhuma passagem. Some 1 porque a posição 0 do array é a posição após o passo 1.

Para muitos passeios, rng.choice([-1, 1], size=(5000, 1000)).cumsum(axis=1) acumula separadamente ao longo de cada linha. walks[:, -1] seleciona todas as posições finais; sua média fica próxima de 0 e seu desvio padrão próximo da raiz quadrada de 1.000, aproximadamente 31,6.

Use permutações e verificações exatas

Uma divisão aleatória de 100 registros pode usar idx = rng.permutation(100), seguido de data[idx[:80]] e data[idx[80:]]. As duas fatias sem sobreposição de uma permutação atribuem cada registro exatamente uma vez. Para uma simulação, compare um caso simples com uma resposta exata, como a média 3,5 de um dado, antes de confiar em resultados mais complicados.