Arrays NumPy

Objetos ndarray do NumPy armazenam dados numéricos homogêneos e expõem operações vetorizadas que substituem loops lentos em Python.

Receita

Cartão de referência rápida - pronto para copiar e colar.

import numpy as np
 
# Cria, converte dtype, vetoriza
a = np.array([1, 2, 3], dtype=np.float64)
b = np.arange(3)  # [0, 1, 2]
result = a * 2 + b  # broadcasting + ufunc
print(result.shape, result.dtype)

Quando usar isso:

Transformações numéricas em milhões de valores (matemática, máscaras, agregações)
Álgebra linear, estatística e pré-processamento de imagens/tensores
Interoperabilidade com pandas, SciPy e bibliotecas de ML que esperam entrada ndarray
Qualquer loop crítico que a análise de desempenho mostre gastando tempo em bytecode Python

Exemplo de Trabalho

import numpy as np
 
# Matriz de receita mensal: linhas = regiões, colunas = meses
revenue = np.array(
    [[120_000, 135_000, 128_000],
     [98_000, 102_000, 110_000],
     [150_000, 148_000, 155_000]],

O que isso demonstra:

Criação 2-D com dtype explícito para matemática inteira estável
np.diff ao longo de axis=1 para mudança mês a mês coluna a coluna
Broadcasting com keepdims=True para que estatísticas de linha se alinhem com a forma da matriz
np.where como um condicional vetorizado sem if Python por célula

Mergulho Profundo

Como Funciona

Um ndarray é um buffer contíguo mais metadados de forma/passos - todos os elementos compartilham um único dtype.
Funções universais (ufuncs) aplicam operações elemento a elemento em loops compilados, frequentemente liberando o GIL.
Broadcasting compara formas da direita: dimensões correspondem quando iguais ou um lado é 1.
Views compartilham memória com o array pai; cópias são explícitas (arr.copy()) ou de atribuições incompatíveis.

Padrões de Criação

Função	Uso Típico
`np.array`	De sequências Python
`np.arange` / `np.linspace`	Intervalos espaçados uniformemente
`np.zeros` / `np.ones` / `np.full`	Buffers pré-alocados
`np.random.default_rng`	Dados aleatórios reproduzíveis

Referência Rápida de dtype

dtype	Quando
`int32` / `int64`	Contagens e IDs
`float32`	Grandes recursos de ML onde a troca de precisão é aceitável
`float64`	Precisão padrão de análise
`bool`	Máscaras e predicados

Notas Python

import numpy as np
 
# Prefira dtype explícito na ingestão
ids = np.array(["1", "2", "3"], dtype=np.int64)  # ValueError - converta strings primeiro
 
# Use default_rng, não o legado np.random.seed
rng = np.random.default_rng(42)
samples = rng.normal(0

Armadilhas

Tipos mistos em np.array - np.array([1, 2.5, 3]) se torna float64 e pode surpreender código inteiro downstream. Correção: converta explicitamente na criação.
Divisão inteira - / sempre promove para float; // trunca em direção ao infinito negativo. Correção: use np.floor_divide quando precisar de truncamento consistente.
Cópias silenciosas vs views - indexação fantasiada (arr[[0, 2]]) retorna uma cópia; fatias frequentemente retornam views. Correção: chame .copy() antes de modificar resultados filtrados.
Propagação de NaN - np.mean([1, np.nan, 3]) é NaN a menos que você passe nanmean. Correção: use np.nanmean ou mascare primeiro.
Erros de broadcasting - (3, 4) + (4,) funciona; (3, 4) + (3,) gera erro a menos que você redimensione. Correção: alinhe com arr[:, np.newaxis] ou reshape.

Alternativas

Alternativa	Use Quando	Não Use Quando
Listas Python	Sequências minúsculas, objetos heterogêneos	Transformações numéricas de milhões de elementos
pandas Series	Dados 1-D rotulados com valores ausentes	Álgebra linear bruta em buffers não rotulados
Polars Series	Pipelines colunares preguiçosos em escala	Você só precisa de um ufunc NumPy rápido
Módulo `array` (stdlib)	Arrays numéricos tipados sem dependência NumPy	Você precisa de broadcasting ou álgebra linear

FAQs

Por que os arrays NumPy devem ser homogêneos?

Um único dtype permite ao NumPy armazenar dados contiguamente e vetorizar em C.
Objetos Python mistos vivem em um array de dtype de objeto - mais lento e sem aceleração de ufunc.

Quando o broadcasting copia dados?

Broadcasting cria uma forma virtual expandida através de strides - nenhuma cópia até você materializar com np.broadcast_to(...).copy().
Escrever através de uma view transmitida pode corromper o buffer subjacente.

Como escolho entre float32 e float64?

Use float32 para tensores grandes onde ~7 dígitos decimais são suficientes.
Use float64 para agregações financeiras, a menos que você tenha um ganho de memória medido.

O que substituiu np.random.seed?

import numpy as np
rng = np.random.default_rng(42)
rng.integers(0, 100, size=5)

default_rng é a API moderna e estatisticamente mais segura.

Como somar sem overflow em colunas int32?

Converta para int64 antes de sum: arr.astype(np.int64).sum().
Ou use np.sum(arr, dtype=np.int64).

Posso usar strings NumPy para análise de texto?

Dtypes np.str_ de largura fixa existem, mas pandas/Polars lidam melhor com texto.
Use NumPy para núcleos numéricos; delegue strings para bibliotecas de DataFrame.

Por que minha máscara booleana tem o formato errado?

Máscaras devem fazer broadcast para a forma do array: máscara (n,) em (n, m) precisa de (n, 1).
Use mask[:, np.newaxis] ou np.broadcast_to.

Como evitar modificar uma view?

safe = arr[mask].copy()
safe *= 2  # não toca em arr

np.dot é o mesmo que @?

Para arrays 2-D, @ e np.dot são multiplicação de matrizes.
Para dimensões mais altas, @ segue as regras de empilhamento PEP 465 - prefira @ por clareza.

Como cronometrar NumPy vs Python puro?

Use timeit em tamanhos de array que você realmente processa.
Pequenos n cruzam o ponto onde listas Python ganham devido à sobrecarga de criação.

Relacionados

Indexação e Redimensionamento NumPy - fatias, indexação fantasiada, eixos
Series e DataFrames pandas - tabelas rotuladas construídas sobre NumPy
Desempenho e Memória - redução de dtype e chunking
Noções Básicas de Análise de Dados - primeiro tour de análise

Versões da Pilha: Esta página foi escrita para Python 3.14.0 (estável 3.14, manutenção 3.13), FastAPI 0.115+, Django 5.2, Flask 3.1, Pydantic 2, PyTorch 2.6+, pandas 2.2+, Polars 1.x, ruff 0.9+, e uv 0.6+.

Buscar na documentação

Arrays NumPy