# Pandas DataFrame.where(): Verificar condições em DataFrame

A função `DataFrame.where()` do [Python Pandas](https://www.ionos.com/pt-br/digitalguide/sites-de-internet/desenvolvimento-web/python-pandas/) foi criada para facilitar a **manipulação de dados condicionais** em DataFrames. Ela permite que programadores substituam ou mascarem os valores em um [DataFrame do Pandas](https://www.ionos.com/pt-br/digitalguide/sites-de-internet/desenvolvimento-web/pandas-dataframe-em-python/) com base em uma condição.

## Sintaxe da função Pandas `DataFrame.where()`

A função `where()` aceita até cinco parâmetros e tem a seguinte sintaxe:

```python
DataFrame.where(cond, other=nan, inplace=False, axis=None, level=None)
```

Quando a função é aplicada a um DataFrame, apenas os valores que atendem a uma condição específica (`cond`) permanecem iguais. Qualquer outro valor é substituído de acordo com a especificação do parâmetro `other`.

### Parâmetros da função Pandas `DataFrame.where()`

A função Pandas `DataFrame.where()` aceita a inclusão de diferentes parâmetros que facilitam a administração e modificação flexível dos dados:

<table>
  <thead>
    <tr>
      <th><strong>Parâmetro</strong></th>
      <th><strong>Descrição</strong></th>
      <th><strong>Valor padrão</strong></th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td>`cond`</td>
      <td>A condição que deve ser atendida para que os valores do DataFrame permaneçam inalterados</td>
      <td></td>
    </tr>
    <tr>
      <td>`other`</td>
      <td>O valor que substitui aqueles que não atendem à condição</td>
      <td></td>
    </tr>
    <tr>
      <td>`inplace`</td>
      <td>Quando definido como verdadeiro (`True`), a operação modifica o DataFrame diretamente</td>
      <td>`False`</td>
    </tr>
    <tr>
      <td>`axis`</td>
      <td>Especifica a quais eixos a condição se aplica (`axis=0` para linhas, `axis=1` para colunas)</td>
      <td>`None`</td>
    </tr>
    <tr>
      <td>`level`</td>
      <td>Define o nível de um índice múltiplo ao qual a condição deve ser aplicada</td>
      <td>`None`</td>
    </tr>
  </tbody>
</table>

## Como usar a função Pandas `DataFrame.where()`

A função `where()` pode ser útil em diversas situações que requerem **manipulação de dados** condicional. Isso inclui a limpeza de informações ou a **criação de novas colunas baseadas em condições**.

### Substituir valores com base em condições

Imagine que você tenha um DataFrame com os resultados de vendas da sua empresa e deseje exibir apenas os números positivos, enquanto os negativos deverão ser substituídos por `0`. Para fazer isso, use a função Pandas `DataFrame.where()`. Primeiro, é preciso criar um DataFrame:

```python
import pandas as pd
# Criar um DataFrame de exemplo
data = {
    'Região': ['Norte', 'Sul', 'Leste', 'Oeste'],
    'Vendas_1Q': [15000, -5000, 3000, -1000],
    'Vendas_2Q': [20000, 25000, -7000, 5000]
}
df = pd.DataFrame(data)
print(df)
```

O código acima produzirá o seguinte DataFrame:

```none
Região    Vendas_1Q    Vendas_2Q
0    Norte         15000                     20000
1    Sul                    -5000                        25000
2    Leste             3000                         -7000
3    Oeste         -1000                            5000
```

Com a função Pandas `DataFrame.where()`, você pode substituir todos os valores negativos por `0`. Certifique-se de que **apenas colunas com valores numéricos** serão incluídas, do contrário, o procedimento não funcionará.

```python
# Substituir valores usando condições
df_positivo = df.copy()
df_positivo[['Vendas_1Q', 'Vendas_2Q']] = df[['Vendas_1Q', 'Vendas_2Q']].where(df[['Vendas_1Q', 'Vendas_2Q']] > 0, 0)
print(df_positivo)
```

O DataFrame resultante, `df_positivo`, exibirá apenas os resultados de vendas positivos e substituirá os negativos por `0`:

```none
Região    Vendas_1Q    Vendas_2Q
0    Norte         15000                        20000
1    Sul                             0                                25000
2    Leste                3000                                 0
3    Oeste                    0                                 5000
```

### Mascarar valores usando condições

A função Pandas `DataFrame.where()` também pode ser usada para mascarar valores. Isso significa que apenas as partes específicas de um DataFrame serão exibidas. No exemplo a seguir, queremos mostrar apenas os valores acima de um patamar (neste caso, `10000`). Lembre-se de que, nesse caso, é preciso avaliar apenas colunas com dados numéricos:

```python
# Exibir apenas os valores acima de 10000
df_mascarado = df.copy()
df_mascarado[['Vendas_1Q', 'Vendas_2Q']] = df[['Vendas_1Q', 'Vendas_2Q']].where(df[['Vendas_1Q', 'Vendas_2Q']] > 10000)
print(df_mascarado)
```

O DataFrame produzido, `df_mascarado`, exibirá apenas os valores superiores a `10000`. Todos os demais valores serão substituídos por `NaN`:

```none
Região    Vendas_1Q    Vendas_2Q
0    Norte         15000                        20000
1    Sul                     NaN                             25000
2    Leste             NaN                                 NaN
3    Oeste                NaN                                    NaN
```


This is a markdown version of: [https://www.ionos.com/pt-br/digitalguide/sites-de-internet/desenvolvimento-web/python-pandas-dataframe-where/](https://www.ionos.com/pt-br/digitalguide/sites-de-internet/desenvolvimento-web/python-pandas-dataframe-where/) for AI/LLM consumption.