HOWTO · Pandas

Como obter a primeira linha de um DataFrame do pandas

Aprenda a selecionar a primeira linha de um DataFrame do pandas com iloc, head(), filtragem, query(), take() e fatiamento, e a escolher entre um resultado Series ou DataFrame.

Nesta página

Use df.iloc[0] para obter a primeira linha como uma Series ou df.head(1) para mantê-la como um DataFrame com uma linha. Para encontrar a primeira linha que atenda a critérios, filtre primeiro e selecione o primeiro resultado em seguida.

Os exemplos usam este pequeno DataFrame para facilitar a identificação dos valores selecionados e dos rótulos originais das linhas. Cada bloco de código é independente e pode ser executado em um ambiente Python com pandas instalado; a saída observada na execução fornecida é exibida após cada exemplo.

Como obter a primeira linha de um DataFrame do pandas usando a propriedade pandas.DataFrame.iloc

pandas.DataFrame.iloc seleciona linhas e colunas por posição inteira. A posição 0 indica a primeira linha, independentemente do rótulo do índice. Selecionar uma linha com df.iloc[0] retorna uma Series cujo índice contém os nomes das colunas do DataFrame. Use df.iloc[0, 1] para selecionar um único valor na posição de linha 0 e na posição de coluna 1.

import pandas as pd

df = pd.DataFrame(
    {
        "C_1": ["A", "B", "C", "D"],
        "C_2": [40, 34, 38, 45],
        "C_3": [430, 980, 200, 350],
    }
)

first_row = df.iloc[0]
print(first_row)
C_1      A
C_2     40
C_3    430
Name: 0, dtype: object

Escolha essa forma quando uma Series for conveniente para cálculos posteriores ou para acessar valores pelo nome da coluna. Para preservar o formato bidimensional de um DataFrame, use df.iloc[[0]] ou um dos métodos abaixo.

Como obter a primeira linha de um DataFrame do pandas usando o método pandas.DataFrame.head()

pandas.DataFrame.head(n) retorna as primeiras n linhas como um DataFrame. Passe 1 para manter apenas a primeira linha, preservando a estrutura das colunas e o rótulo do índice. Essa costuma ser a opção mais clara quando o código seguinte espera um DataFrame.

import pandas as pd

df = pd.DataFrame(
    {
        "C_1": ["A", "B", "C", "D"],
        "C_2": [40, 34, 38, 45],
        "C_3": [430, 980, 200, 350],
    }
)

first_row = df.head(1)
print(first_row)
  C_1  C_2  C_3
0   A   40  430

A escolha principal depende do formato do resultado: df.iloc[0] é unidimensional, enquanto df.head(1) continua sendo um DataFrame.

Como obter a primeira linha de um DataFrame do pandas com base na condição especificada

Filtre as linhas antes de selecionar a primeira correspondência. Neste exemplo, a condição é C_2 < 40 e C_3 > 450; a primeira linha correspondente é aquela cujo rótulo é 1. A máscara booleana coloca cada comparação entre parênteses porque & combina as duas condições.

import pandas as pd

df = pd.DataFrame(
    {
        "C_1": ["A", "B", "C", "D"],
        "C_2": [40, 34, 38, 45],
        "C_3": [430, 980, 500, 350],
    }
)

matches = df[(df["C_2"] < 40) & (df["C_3"] > 450)]
first_match = matches.head(1)
print(first_match)
  C_1  C_2  C_3
1   B   34  980

head(1) retorna um DataFrame vazio se nenhuma linha corresponder. Se você precisar de uma única Series quando houver correspondência, selecione com matches.iloc[0]; verifique matches.empty antes quando for possível que os critérios não encontrem nenhuma linha.

O método query() expressa o mesmo filtro como uma string e pode ser conveniente para escrever expressões legíveis com nomes de colunas. Mantenha o predicado coerente com o exemplo de filtro booleano:

import pandas as pd

df = pd.DataFrame(
    {
        "C_1": ["A", "B", "C", "D"],
        "C_2": [40, 34, 38, 45],
        "C_3": [430, 980, 500, 350],
    }
)

matches = df.query("(C_2 < 40) & (C_3 > 450)")
first_match = matches.head(1)
print(first_match)
  C_1  C_2  C_3
1   B   34  980

Para usar valores de variáveis Python, use @variavel em uma expressão de query(). Por exemplo, limit = 40 pode ser referenciado como df.query("C_2 < @limit").

Como obter a primeira linha de um DataFrame do pandas usando o método pandas.DataFrame.take()

pandas.DataFrame.take() seleciona linhas por posição quando o eixo padrão, que corresponde às linhas, é usado. Passe [0] para selecionar a primeira linha como um DataFrame com uma linha, preservando seu rótulo de índice original.

import pandas as pd

df = pd.DataFrame(
    {
        "C_1": ["A", "B", "C", "D"],
        "C_2": [40, 34, 38, 45],
        "C_3": [430, 980, 200, 350],
    }
)

first_row = df.take([0])
print(first_row)
  C_1  C_2  C_3
0   A   40  430

Use take() quando você já tiver uma lista de posições de linhas. Para selecionar apenas a primeira linha, head(1) ou iloc[[0]] podem comunicar a intenção de forma mais direta.

Como obter a primeira linha de um DataFrame do pandas usando fatiamento

O fatiamento df[:1] seleciona as linhas desde o início até a posição 1, sem incluir essa posição. Ele retorna um DataFrame e preserva o rótulo de índice da linha selecionada.

import pandas as pd

df = pd.DataFrame(
    {
        "C_1": ["A", "B", "C", "D"],
        "C_2": [40, 34, 38, 45],
        "C_3": [430, 980, 200, 350],
    }
)

first_row = df[:1]
print(first_row)
  C_1  C_2  C_3
0   A   40  430

Conclusão

Use df.iloc[0] quando quiser uma Series e df.head(1), df.iloc[[0]], df.take([0]) ou df[:1] quando quiser um DataFrame com uma linha. Para obter a primeira linha que atenda a critérios, filtre com uma condição booleana ou com query() e selecione a primeira linha filtrada em seguida. Se nenhuma correspondência for possível, verifique matches.empty antes de acessar a primeira linha.