Função Pandas cut

A função pandas.cut() atribui valores numéricos a faixas, também chamadas de bins. Ela retorna uma categoria de intervalo para cada valor de entrada, o que permite agrupar medidas contínuas, como idades ou pontuações, para análise. Você pode fornecer pontos de corte explícitos ou pedir ao pandas que divida uma faixa em uma quantidade escolhida de bins.

Sintaxe, parâmetros e valor de retorno

A chamada da função é pandas.cut(x, bins, right=True, labels=None, retbins=False, precision=3, include_lowest=False, duplicates="raise", ordered=True).

Os argumentos mais usados são:

Normalmente, o resultado contém um valor categórico para cada item de x. Um valor que não pertence a nenhum intervalo é representado por NaN. Com retbins=True, a função retorna um par: o resultado para cada valor e o array de pontos de corte.

Atribuir valores de um DataFrame a bins

Passe uma coluna do DataFrame como x, informe os pontos de corte dos intervalos em bins e atribua a Series retornada a uma nova coluna. Execute este exemplo. Os rótulos de texto exibidos no bloco permanecem em inglês, pois o código e a saída são preservados sem alterações:

import pandas as pd

df = pd.DataFrame(
    {
        "Name": ["Anish", "Birat", "Chirag", "Kabin", "Sachin"],
        "Age": [23, 34, 38, 45, 27],
        "Score": [316, 322, 332, 330, 325],
    }
)

df["Age-Range"] = pd.cut(df["Age"], bins=[20, 30, 40, 50])
print(df[["Age", "Age-Range"]].to_string(index=False))

Há três bins porque quatro pontos de corte definem três intervalos. Cada linha mantém sua posição original, e o valor de Age-Range indica o intervalo que contém a idade daquela linha. Por exemplo, com a convenção padrão de intervalos, a idade 23 pertence a (20, 30], enquanto a idade 45 pertence a (40, 50].

Controlar os limites dos intervalos

Por padrão, right=True cria intervalos fechados à direita. A notação (20, 30] significa valores maiores que 20 e menores ou iguais a 30: 20 é excluído e 30 é incluído. include_lowest=True também inclui o menor ponto de corte no primeiro intervalo. Defina right=False para usar intervalos fechados à esquerda e abertos à direita, como [20, 30), que incluem 20 e excluem 30. Com essa configuração, o maior ponto de corte fica fora do último intervalo. Valores que não correspondem a nenhum intervalo são retornados como NaN.

O exemplo a seguir compara essas opções para idades iguais aos pontos de corte fornecidos e situadas entre eles. Os rótulos de texto exibidos no bloco permanecem em inglês, pois o código e a saída são preservados sem alterações:

import pandas as pd

ages = pd.Series([20, 23, 30, 45, 50], name="Age")
result = pd.DataFrame(
    {
        "Age": ages,
        "default": pd.cut(ages, bins=[20, 30, 40, 50]),
        "include_lowest": pd.cut(
            ages, bins=[20, 30, 40, 50], include_lowest=True
        ),
        "left_closed": pd.cut(
            ages, bins=[20, 30, 40, 50], right=False
        ),
    }
)
print(result.to_string(index=False))

Compare as linhas correspondentes a 20 e 50 para ver como a escolha dos limites afeta a classificação. O padrão inclui 50 no último intervalo, mas exclui 20 do primeiro; include_lowest=True acrescenta 20 ao primeiro intervalo, enquanto right=False inclui 20 e deixa 50 fora do intervalo final.

Atribuir rótulos aos bins

Para exibir nomes de categorias legíveis em vez da notação de intervalo, passe um rótulo para cada bin. Os rótulos seguem a ordem dos intervalos, portanto três bins exigem três rótulos. Os rótulos de texto exibidos no bloco permanecem em inglês, pois o código e a saída são preservados sem alterações:

import pandas as pd

ages = pd.Series([23, 34, 38, 45, 27], name="Age")
labels = ["21 to 30", "31 to 40", "41 to 50"]
age_groups = pd.cut(
    ages,
    bins=[20, 30, 40, 50],
    labels=labels,
)
print(age_groups.to_string(index=False))

Com as opções padrão, o primeiro rótulo corresponde a (20, 30], o segundo a (30, 40] e o terceiro a (40, 50]. Se precisar das posições numéricas dos grupos em vez de nomes, passe labels=False; então, o pandas retorna códigos inteiros dos bins para os valores classificados em um bin.

Retornar os limites dos bins com retbins=True

Defina retbins=True quando precisar tanto das categorias por valor quanto dos pontos de corte usados para criá-las. O primeiro item retornado corresponde a x; o segundo é o array compartilhado de limites dos bins. Este exemplo desempacota os dois resultados. Os rótulos de texto exibidos no bloco permanecem em inglês, pois o código e a saída são preservados sem alterações:

import pandas as pd

ages = pd.Series([23, 34, 38, 45, 27], name="Age")
age_groups, bin_edges = pd.cut(
    ages,
    bins=[20, 30, 40, 50],
    labels=["21 to 30", "31 to 40", "41 to 50"],
    retbins=True,
)
print("Groups:")
print(age_groups.to_string(index=False))
print("Bin edges:")
print(bin_edges)

age_groups contém um resultado rotulado para cada idade, enquanto bin_edges contém [20, 30, 40, 50]. O mesmo padrão é útil quando bins é um inteiro e o pandas calcula pontos de corte de mesma largura: guarde os limites retornados se precisar inspecioná-los ou reutilizá-los.