# Análises

Uma análise é um avaliador de risco configurado sobre um [tipo de evento](/pt/events/event_types/). Ela acumula o histórico recente dos eventos em janelas deslizantes e, a cada novo evento, devolve uma pontuação de 0 a 100 indicando o quanto aquele comportamento destoa do esperado.

A análise não decide sozinha: a decisão cabe à [regra](/pt/rules/). A regra alimenta a análise com a ação [registrar análise](/pt/rules/actions/record_analysis/), consulta o resultado com a ação [executar análise](/pt/rules/actions/run_analysis/) e usa esse resultado nas condições seguintes.

Destina-se a perguntas de velocidade e de concentração: quantas tentativas este cartão fez na última hora, quantos cartões diferentes passaram por este usuário hoje.

A análise é **transacional**: ela avalia um evento por vez e responde a tempo de a regra agir sobre ele. O termo se refere ao modo de operação, não ao tipo de dado: a análise vale para qualquer tipo de evento, não apenas para transações financeiras. Para acompanhar o comportamento agregado ao longo do tempo, use [métricas e monitoramentos](/pt/behavioral/).

## Onde configurar

Em **Configurações > Tipos de evento**, abra o tipo de evento e vá até a aba **Análises**.

A análise tem um único campo próprio, o **Nome**, que é o identificador usado pelas regras e **não pode ser alterado depois da criação**: as ações que citassem o nome antigo ficariam órfãs. Todo o resto é configurado nas células.

O editor da célula organiza a configuração em quatro grupos: **Identidade** (o identificador da célula), **Janela** (quais eventos entram, com que chave e por quanto tempo), **Medida** (o número extraído da janela) e **Gatilho** (o limite aplicado a esse número). Ele também oferece exemplos prontos, como um contador de tentativas ou um limite de velocidade, que preenchem os quatro grupos de uma vez e podem ser ajustados em seguida.

A lista de células pode ser reordenada por arrasto. A nova ordem grava a **Prioridade** de cada célula e define a ordem da cascata: a primeira da lista decide primeiro.

## Como a análise decide

Uma análise é um conjunto de **células**. Cada célula é uma pergunta independente sobre uma fatia do histórico: um agrupamento, uma janela de tempo, uma medida e um alvo.

Todas as células são avaliadas, e a mais específica entre as que acionaram decide o resultado: vale a menor **Prioridade** e, em caso de empate, a célula que observou a maior amostra. A pontuação devolvida é a dessa célula, e não a maior da análise: uma célula específica que pontuou 91 decide na frente de uma célula abrangente que pontuou 99. A cascata escolhe pelo alcance do bloqueio, não pela magnitude do desvio, para que a ação fique restrita ao menor grupo possível.

Quando nenhuma célula aciona, a pontuação é a maior que alguma célula alcançou e a célula do score não é informada. Ao persistir a célula do score em um campo do evento, ele fica preenchido apenas nos eventos em que alguma célula explicou a pontuação.

Uma célula que não pode ser avaliada, porque o evento não trouxe o campo da dimensão ou porque a janela está vazia, é ignorada, nunca lida como se estivesse normal.

## Campos da célula

| Campo                     | Conteúdo                                                                        |
| :------------------------ | :------------------------------------------------------------------------------ |
| Nome                      | identificador da célula, único dentro da análise; aparece nos resultados da regra |
| Dimensão                  | campo, ou combinação de campos, que agrupa a janela                              |
| Janela                    | tamanho da janela deslizante, em minutos, horas ou dias, até 90 dias             |
| Sinal                     | como a célula julga a janela: estatístico, limite fixo ou sem gatilho             |
| Medida                    | o que a célula mede na janela                                                    |
| Direção                   | qual lado do alvo representa risco                                               |
| Alvo                      | valor de referência; nas medidas de taxa, um número entre 0 e 1                  |
| Limite                    | pontuação de 0 a 100 a partir da qual a célula aciona; padrão 90                 |
| Prioridade                | ordem na cascata; a menor decide primeiro                                        |
| Numerador e Denominador   | filtros que definem a taxa, nas medidas de porcentagem                           |
| Distinto por              | campo contado, ou entidade da taxa, conforme a medida                            |
| Registrar quando          | filtro que decide quais eventos alimentam a janela                               |

**Registrar quando** é a única configuração que enxerga campos que a célula não agrupa nem conta, e é o que permite mudar a pergunta: registrar somente eventos recusados transforma uma célula de "cartões diferentes deste usuário" em "cartões diferentes em que este usuário foi recusado".

Alterar a **dimensão**, a **janela** ou a **medida** reinicia o histórico acumulado, sem reprocessamento: a célula precisa de uma janela inteira de tráfego para voltar a significar alguma coisa. Alterar o alvo, o limite, a prioridade ou os filtros preserva o histórico.

## Medida

| Medida                            | O que mede                                                |
| :-------------------------------- | :--------------------------------------------------------- |
| Quantidade                        | volume de eventos na janela, ou seja, velocidade            |
| Valores distintos                 | quantos valores diferentes de um campo aparecem na janela   |
| Porcentagem                       | a taxa de um resultado, como a de aprovação                 |
| Porcentagem por valores distintos | a mesma taxa, contando cada valor distinto uma única vez    |

**Quantidade** não exige configuração adicional. **Valores distintos** exige o campo **Distinto por**, cujos valores diferentes são contados.

**Porcentagem** exige um **Numerador** e aceita um **Denominador**, ambos filtros sobre o mesmo campo de resultado: o numerador diz quais valores contam a favor, e com o denominador vazio a base são todos os valores da janela.

**Porcentagem por valores distintos** é a mesma taxa medida sobre entidades em vez de tentativas. Cada valor distinto entra com uma observação, a da sua última tentativa na janela, de modo que um cliente que tentou dez vezes pesa o mesmo que um que tentou uma.

As duas medidas de porcentagem são avaliadas sobre as **100 observações mais recentes** da janela.

## Sinal

Define como a célula julga a janela, e é a escolha que muda o significado do **Alvo**.

Com o sinal **Estatístico**, que é o padrão, o alvo é o comportamento normal esperado e a pontuação exprime o quanto a janela destoa dele. Use quando o objetivo é detectar desvios do normal e o número exato não importa.

Com o sinal **Limite fixo**, o alvo é o próprio ponto de disparo: a célula aciona quando a observação o alcança, e a pontuação é sempre 100 ou 0. Use quando o número faz parte de uma política acordada, por exemplo um teto de tentativas recusadas por período definido em contrato. Traduzir esse número em um alvo estatístico o deixaria acoplado à calibração da análise, e reajustar a calibração moveria silenciosamente um valor que um documento externo fixa.

Ao escolher o limite fixo:

- **Não há proteção contra amostras pequenas.** É a diferença central em relação ao sinal estatístico, e um risco real nas medidas de porcentagem: um limite de 50% aciona com uma única tentativa recusada, porque uma recusa em uma tentativa é 100%. Combine-o com uma janela e um filtro de registro que tornem uma amostra pequena significativa.
- **O campo Limite não se aplica** e some do formulário, já que a pontuação só assume 100 ou 0.
- **A direção é de um lado só**: "Acima" aciona ao alcançar ou passar do alvo, "Abaixo" ao alcançar ou ficar sob ele. "Ambos" é recusado, porque um número único delimita apenas um lado.
- **Nas medidas de volume o alvo precisa ser inteiro**: não se observa 2,5 eventos.

### Sem gatilho

Uma célula com o sinal **Sem gatilho** mantém a janela e expõe o valor medido, sem acionar. **Alvo**, **Direção** e **Limite** não se aplicam, e a célula fica fora da cascata: não decide o resultado nem entra na contagem de células acionadas.

A célula sem gatilho é adequada para expor um número da janela sem transformá-lo em bloqueio: contar as tentativas de um pedido, gravar esse contador em um campo e deixar a decisão para uma condição da regra.

Os três sinais convivem na mesma análise, e os dois que acionam pontuam na mesma escala de 0 a 100.

O formulário mostra uma prévia da célula assim que medida, direção e alvo estiverem preenchidos. Em uma célula de limite fixo, ela mostra a escala saltando direto de 0 para 100 no alvo.

## Usar a análise em uma regra

A análise só produz efeito através de uma regra:

1. a ação [registrar análise](/pt/rules/actions/record_analysis/) alimenta as janelas com o evento atual;
2. a ação [executar análise](/pt/rules/actions/run_analysis/) avalia a análise e disponibiliza o resultado;
3. as condições seguintes decidem o que fazer com esse resultado.

O resultado fica disponível como [variável temporária](/pt/rules/expression-syntax/#variáveis-temporárias-), com a pontuação, a célula que a originou e o conjunto de células acionadas.

Cada célula avaliada também publica o valor bruto que mediu na janela, em `%<resultado>.cells.<célula>.value`. Uma célula sem gatilho entrega o seu número por essa variável, para as condições seguintes ou para um campo do evento.

```
Condição 1:  $amount > 0     → Registrar análise: bot
Condição 2:  $amount > 0     → Executar análise: bot
Condição 3:  %bot.triggered  → Preencher campo: revisao = "true"
Condição 4:  "recusas_por_cartao" in %bot.triggered_cells  → Adicionar à lista: $card_fingerprint em @cartoes_bloqueados
```

Registrar e executar são independentes: uma condição pode alimentar o histórico sem consultá-lo, consultá-lo sem alimentar, ou fazer as duas coisas.

## Regras que usam esta análise

A página da análise apresenta as regras que se ligam a ela, uma linha por versão de regra, separando as que a **executam** das que a **registram**, com os campos que cada uma grava e o nome do resultado.

Como registrar e executar são independentes, a análise pode ficar em um de dois estados incompletos, ambos assinalados nessa relação:

- **pontua sem que ninguém registre**: uma regra consulta a análise, mas nenhuma alimenta as suas janelas, de modo que a pontuação é calculada sobre um histórico que não recebe tráfego;
- **registra sem que ninguém pontue**: as janelas acumulam, mas nenhuma regra lê o resultado, de modo que a análise não produz efeito sobre decisão alguma.

Uma análise nomeada por uma versão de regra publicada ou em observação não pode ser removida. A remoção informa quais regras a mantêm em uso, e passa a ser possível depois que essas regras deixam de nomeá-la.

## Versões

Uma análise é versionada como uma regra: a versão publicada é imutável, a edição de uma célula ou da ordem da cascata parte dela para um rascunho, e a publicação leva a cascata inteira ao ar de uma vez. Uma versão anterior pode ser restaurada, e uma versão pode ser publicada em observação, sobre o mesmo tráfego da versão ativa, sem decidir nada. Consulte [Versionamento](/pt/rules/versioning/#versões-de-análise).