pandas Series & DataFrames

pandas adiciona eixos rotulados a dados colunares: uma Series é uma coluna tipada; um DataFrame é uma tabela de Series alinhadas compartilhando um índice.

Receita

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

import pandas as pd
 
df = pd.DataFrame(
    {"region": ["East", "West"], "revenue": [120, 340]},
    index=pd.Index(["a", "b"], name="row"),
)
east = df.loc[df["region"] == "East", "revenue"]
subset = df.iloc[0:1, [0, 1]]

Quando usar isso:

EDA tabular com tipos de coluna mistos e valores ausentes
Séries temporais rotuladas indexadas por timestamps
Juntar múltiplas tabelas por chaves antes da agregação
Exportar resultados de análise para CSV, Parquet ou Excel

Exemplo de Trabalho

import pandas as pd
 
orders = pd.DataFrame(
    {
        "order_id": [101, 102, 103, 104],
        "region": pd.Categorical(["East", "West", "East", "West"]),
        "revenue": [120.0, 340.0, None, 210.0],
        "ordered_at": pd.to_datetime(
            ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04"], utc=True
        ),
    }
).set_index("order_id")
 
# Seleção baseada em rótulo
east = orders.loc[orders["region"] == "East", ["region", "revenue"]]
 
# Cabeçalho baseado em posição
head = orders.iloc[:2]
 
# Adicionar coluna computada com segurança
orders = orders.copy()
orders["revenue_filled"] = orders["revenue"].fillna(orders["revenue"].median())
 
# Redução de Series
monthly_total = orders["revenue_filled"].sum()
 
print(east)
print("monthly_total:", monthly_total)

O que isso demonstra:

Construção com colunas categóricas e float anuláveis
Análise de datetime UTC no momento do carregamento
Filtragem booleana .loc com subconjunto de colunas
.copy() antes da atribuição para evitar SettingWithCopyWarning

Mergulho Profundo

Como Funciona

Rótulos de índice alinham linhas entre colunas - operações correspondem no índice automaticamente.
Gerenciador de blocos (pandas 2.x) armazena colunas em blocos com backend Arrow/numpy por dtype.
.loc inclui ambos os pontos finais para rótulos; .iloc é meio aberto como fatias do Python.
Backend dtype (string[pyarrow]) altera o comportamento de memória e de valores ausentes.

Tabela de Referência de Seleção

Objetivo	API
Filtrar linhas	`df.loc[mascara]`
Selecionar colunas	`df[["a", "b"]]`
Escalar por rótulo	`df.loc[linha, "coluna"]`
Escalar por posição	`df.iloc[i, j]`

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`index`	Semelhante a Index	Rótulos de linha; padrão é RangeIndex
`columns`	list[str]	Nomes de coluna para DataFrame
`dtype`	str/np.dtype	Força o tipo de coluna na construção

Armadilhas

Atribuição de indexação encadeada - df[df["x"] > 0]["y"] = 1 dispara SettingWithCopyWarning. Correção: df.loc[df["x"] > 0, "y"] = 1.
Rótulos de índice duplicados - .loc["a"] retorna múltiplas linhas; acesso escalar falha. Correção: reset_index() ou impor chaves únicas upstream.
Strings de dtype object - colunas object padrão usam muita RAM. Correção: df["col"] = df["col"].astype("string[pyarrow]") no pandas 2.2+.
Coerção silenciosa de dtype - misturar inteiros e floats atualiza a coluna para float. Correção: usar Int64 anulável quando NA for possível.
Naive vs aware de fuso horário - comparar datetimes mistos gera erro no pandas 2.x. Correção: pd.to_datetime(..., utc=True) em todos os lugares na ingestão.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Polars DataFrame	Scans preguiçosos, dados muito grandes, tipagem estrita	Equipe já padronizada em idiomas pandas
PyArrow Table	Intercâmbio de memória zero entre sistemas	Você precisa de indexação interativa rica
SQL via DuckDB	Dados já em tabelas de data warehouse	Transformações pequenas em memória
Arrays estruturados NumPy	Registros numéricos de esquema fixo	Tipos de coluna heterogêneos

FAQs

Quando devo usar reset_index?

Após groupby quando você precisa da chave do grupo como uma coluna.
Quando rótulos de índice duplicados quebram o acesso escalar .loc.

Qual a diferença entre [] e .loc?

df["col"] seleciona uma Series de coluna.
df.loc[linhas, colunas] é seleção 2D baseada em rótulo com regras de alinhamento.

Como evito cópias em filtros?

Filtrar sempre retorna um novo frame, a menos que use inplace=True (desencorajado).
Para dados enormes, use filter preguiçoso do Polars ou leituras em blocos.

Como leio apenas algumas colunas de um CSV?

import pandas as pd
df = pd.read_csv("big.csv", usecols=["region", "revenue"])

Uma Series pode ter um nome?

Sim - s.name aparece quando a Series se torna uma coluna de DataFrame.
Definido na criação: pd.Series(..., name="revenue").

Como detecto nomes de coluna duplicados?

import pandas as pd
df.columns.duplicated().any()

Nomes duplicados fazem df["x"] retornar múltiplas colunas.

O que copy-on-write faz no pandas 2.x?

Com pd.options.mode.copy_on_write = True, operações encadeadas adiam cópias até a escrita.
Ainda prefira atribuição explícita .loc para clareza.

Como converto o índice em coluna?

df = df.reset_index()

Ou df.rename_axis("order_id").reset_index() para nomear o antigo índice.

Por que minha coluna numérica é dtype object?

Strings e números mistos forçam object.
Releia com dtype ou pd.to_numeric(errors="coerce").

Como amostrar linhas de forma reproduzível?

sample = df.sample(n=100, random_state=42)

Relacionados

Limpeza e Transformação de Dados - dtypes e valores ausentes
GroupBy & Agregação - dividir-aplicar-combinar
Joins & Merges - combinando frames
Noções Básicas de Análise de Dados - tour introdutório

Versões do Stack: 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+.

pandas Series & DataFrames

pandas adiciona eixos rotulados a dados colunares: uma Series é uma coluna tipada; um DataFrame é uma tabela de Series alinhadas compartilhando um índice.

Receita

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

import pandas as pd
 
df = pd.DataFrame(
    {"region": ["East", "West"], "revenue": [120, 340]},
    index=pd.Index(["a", "b"], name="row"),
)
east = df.loc[df["region"] == "East", "revenue"]
subset = df.iloc[0:1, [0, 1]]

Quando usar isso:

EDA tabular com tipos de coluna mistos e valores ausentes
Séries temporais rotuladas indexadas por timestamps
Juntar múltiplas tabelas por chaves antes da agregação
Exportar resultados de análise para CSV, Parquet ou Excel

Exemplo de Trabalho

import pandas as pd
 
orders = pd.DataFrame(
    {
        "order_id": [101, 102, 103, 104],
        "region": pd.Categorical(["East", "West", "East", "West"]),
        "revenue": [120.0, 340.0, None, 210.0],
        "ordered_at": pd.to_datetime(
            ["2025-01-01", "2025-01-02", "2025-01-03", "2025-01-04"], utc=True
        ),
    }
).set_index("order_id")
 
# Seleção baseada em rótulo
east = orders.loc[orders["region"] == "East", ["region", "revenue"]]
 
# Cabeçalho baseado em posição
head = orders.iloc[:2]
 
# Adicionar coluna computada com segurança
orders = orders.copy()
orders["revenue_filled"] = orders["revenue"].fillna(orders["revenue"].median())
 
# Redução de Series
monthly_total = orders["revenue_filled"].sum()
 
print(east)
print("monthly_total:", monthly_total)

O que isso demonstra:

Construção com colunas categóricas e float anuláveis
Análise de datetime UTC no momento do carregamento
Filtragem booleana .loc com subconjunto de colunas
.copy() antes da atribuição para evitar SettingWithCopyWarning

Mergulho Profundo

Como Funciona

Rótulos de índice alinham linhas entre colunas - operações correspondem no índice automaticamente.
Gerenciador de blocos (pandas 2.x) armazena colunas em blocos com backend Arrow/numpy por dtype.
.loc inclui ambos os pontos finais para rótulos; .iloc é meio aberto como fatias do Python.
Backend dtype (string[pyarrow]) altera o comportamento de memória e de valores ausentes.

Tabela de Referência de Seleção

Objetivo	API
Filtrar linhas	`df.loc[mascara]`
Selecionar colunas	`df[["a", "b"]]`
Escalar por rótulo	`df.loc[linha, "coluna"]`
Escalar por posição	`df.iloc[i, j]`

Parâmetros e Valores de Retorno

Parâmetro	Tipo	Descrição
`index`	Semelhante a Index	Rótulos de linha; padrão é RangeIndex
`columns`	list[str]	Nomes de coluna para DataFrame
`dtype`	str/np.dtype	Força o tipo de coluna na construção

Armadilhas

Atribuição de indexação encadeada - df[df["x"] > 0]["y"] = 1 dispara SettingWithCopyWarning. Correção: df.loc[df["x"] > 0, "y"] = 1.
Rótulos de índice duplicados - .loc["a"] retorna múltiplas linhas; acesso escalar falha. Correção: reset_index() ou impor chaves únicas upstream.
Strings de dtype object - colunas object padrão usam muita RAM. Correção: df["col"] = df["col"].astype("string[pyarrow]") no pandas 2.2+.
Coerção silenciosa de dtype - misturar inteiros e floats atualiza a coluna para float. Correção: usar Int64 anulável quando NA for possível.
Naive vs aware de fuso horário - comparar datetimes mistos gera erro no pandas 2.x. Correção: pd.to_datetime(..., utc=True) em todos os lugares na ingestão.

Alternativas

Alternativa	Usar Quando	Não Usar Quando
Polars DataFrame	Scans preguiçosos, dados muito grandes, tipagem estrita	Equipe já padronizada em idiomas pandas
PyArrow Table	Intercâmbio de memória zero entre sistemas	Você precisa de indexação interativa rica
SQL via DuckDB	Dados já em tabelas de data warehouse	Transformações pequenas em memória
Arrays estruturados NumPy	Registros numéricos de esquema fixo	Tipos de coluna heterogêneos

FAQs

Quando devo usar reset_index?

Após groupby quando você precisa da chave do grupo como uma coluna.
Quando rótulos de índice duplicados quebram o acesso escalar .loc.

Qual a diferença entre [] e .loc?

df["col"] seleciona uma Series de coluna.
df.loc[linhas, colunas] é seleção 2D baseada em rótulo com regras de alinhamento.

Como evito cópias em filtros?

Filtrar sempre retorna um novo frame, a menos que use inplace=True (desencorajado).
Para dados enormes, use filter preguiçoso do Polars ou leituras em blocos.

Como leio apenas algumas colunas de um CSV?

import pandas as pd
df = pd.read_csv("big.csv", usecols=["region", "revenue"])

Uma Series pode ter um nome?

Sim - s.name aparece quando a Series se torna uma coluna de DataFrame.
Definido na criação: pd.Series(..., name="revenue").

Como detecto nomes de coluna duplicados?

import pandas as pd
df.columns.duplicated().any()

Nomes duplicados fazem df["x"] retornar múltiplas colunas.

O que copy-on-write faz no pandas 2.x?

Com pd.options.mode.copy_on_write = True, operações encadeadas adiam cópias até a escrita.
Ainda prefira atribuição explícita .loc para clareza.

Como converto o índice em coluna?

df = df.reset_index()

Ou df.rename_axis("order_id").reset_index() para nomear o antigo índice.

Por que minha coluna numérica é dtype object?

Strings e números mistos forçam object.
Releia com dtype ou pd.to_numeric(errors="coerce").

Como amostrar linhas de forma reproduzível?

sample = df.sample(n=100, random_state=42)

Relacionados

Limpeza e Transformação de Dados - dtypes e valores ausentes
GroupBy & Agregação - dividir-aplicar-combinar
Joins & Merges - combinando frames
Noções Básicas de Análise de Dados - tour introdutório

Versões do Stack: 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+.

pandas Series & DataFrames

Buscar na documentação

pandas Series & DataFrames