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.