Metadata-Version: 2.4
Name: fannar
Version: 0.3.1
Summary: Representation spaces of trained models from Gram matrices of several sources (kernel-transformation pipeline, Hadamard composition, geometry and spectral energy).
Author: Fernando C. S. Dal' Maria, Cristiane N. Nobre, Pedro Belchior
License-Expression: CC-BY-NC-4.0
Project-URL: Homepage, https://fannar.fernandocsdm.com
Project-URL: Repository, https://github.com/FernandoCsm-Knight/Fannar
Keywords: interpretability,explainability,kernel methods,RKHS,Gram matrix,representation geometry
Classifier: Programming Language :: Python :: 3
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENCE
Requires-Dist: numpy>=1.23
Requires-Dist: matplotlib>=3.6
Provides-Extra: torch
Requires-Dist: torch>=2.0; extra == "torch"
Provides-Extra: sklearn
Requires-Dist: scikit-learn>=1.2; extra == "sklearn"
Provides-Extra: pandas
Requires-Dist: pandas>=1.5; extra == "pandas"
Provides-Extra: all
Requires-Dist: torch>=2.0; extra == "all"
Requires-Dist: scikit-learn>=1.2; extra == "all"
Requires-Dist: pandas>=1.5; extra == "all"
Provides-Extra: test
Requires-Dist: pytest>=7; extra == "test"
Requires-Dist: scikit-learn>=1.2; extra == "test"
Requires-Dist: pandas>=1.5; extra == "test"
Dynamic: license-file

# Fannar

[![CC BY-NC 4.0][cc-by-nc-shield]][cc-by-nc]

Espaços de representação de modelos treinados a partir de matrizes de Gram de várias fontes de
informação: um *kernel* positivamente definido por fonte, transformações admissíveis, composição
pelo produto de Hadamard e a geometria e a energia espectral da matriz resultante.

**Fannar** é o nome do método, e esta biblioteca é a sua implementação, a do artigo *Construção de Espaços via Tensores de Similaridade em
Espaços de Hilbert com Núcleo Reprodutor: Um Método de Interpretabilidade Mecanicista*.

```bash
pip install fannar               # núcleo: numpy + matplotlib
pip install "fannar[all]"        # + PyTorch, scikit-learn e pandas
pip install -e ".[test]"         # a partir deste diretório, para desenvolver
```

## O que ele mostra

<p align="center">
  <img src="https://raw.githubusercontent.com/FernandoCsm-Knight/Fannar/main/docs/readme/visao_atalho.webp" alt="A mesma foto de gato com uma marca no canto, vista por um modelo limpo e por um modelo que aprendeu um atalho, segundo Fannar, SHAP e LIME" width="100%">
</p>

Uma ResNet-18 treinada com uma pequena marca em 95% das fotos de cachorro aprende o atalho:
chama de cachorro 40% dos gatos com a marca. No modelo com atalho, metade do mapa de energia do
Fannar cai sobre a marca, que ocupa 2% da imagem; no modelo limpo, 91% fica sobre o animal.

<table>
  <tr>
    <td width="50%"><img src="https://raw.githubusercontent.com/FernandoCsm-Knight/Fannar/main/docs/readme/visao_energias.webp" alt="Energia retida e energia ortogonal por posição nos dois modelos de visão"></td>
    <td width="50%"><img src="https://raw.githubusercontent.com/FernandoCsm-Knight/Fannar/main/docs/readme/churn_erros_confiantes.webp" alt="Erros de um modelo de churn cometidos com mais de 90% de confiança e quantos deles a geometria sinaliza"></td>
  </tr>
  <tr>
    <td><b>Energia retida × ortogonal.</b> O atalho ocupa os modos dominantes, mas o gato continua representado fora deles: 68% da energia ortogonal fica no animal.</td>
    <td><b>Erros com convicção.</b> 113 dos 136 erros de uma rede de churn vêm com mais de 90% de confiança; a margem geométrica sinaliza 55 deles.</td>
  </tr>
  <tr>
    <td><img src="https://raw.githubusercontent.com/FernandoCsm-Knight/Fannar/main/docs/readme/credito_tres_metodos.webp" alt="Os atributos que mais separam um cliente recusado de um aprovado segundo Fannar, SHAP e LIME"></td>
    <td><img src="https://raw.githubusercontent.com/FernandoCsm-Knight/Fannar/main/docs/readme/texto_camadas.webp" alt="Mensagens de clientes de um banco separadas por intenção, bloco a bloco de um DistilBERT"></td>
  </tr>
  <tr>
    <td><b>Explicação de pares (XGBoost).</b> O que separa um cliente recusado de um aprovado parecido; onde Fannar, SHAP e LIME concordam, a conclusão fica mais firme.</td>
    <td><b>Transformers.</b> As intenções de clientes se separando bloco a bloco de um DistilBERT ajustado, contra o mesmo modelo antes do ajuste fino.</td>
  </tr>
</table>

<p align="center">
  <img src="https://raw.githubusercontent.com/FernandoCsm-Knight/Fannar/main/docs/readme/series_falha.webp" alt="Sinal de vibração com os impactos de uma falha de rolamento e onde cada método aponta no tempo" width="100%">
</p>

Em séries temporais, a energia por instante de uma CNN 1D se concentra nos impactos de uma falha de
rolamento: 66% do mapa cai sobre eles, que ocupam 15% do tempo.

> Estes exemplos vêm de modelos treinados para ilustrar o método, com uma rodada cada; a avaliação
> sistemática está no artigo. Mais casos e o serviço de interpretabilidade em
> [fannar.fernandocsdm.com](https://fannar.fernandocsdm.com).

## A ideia em uma linha

```
G = T( T_1(K_1) ∘ T_2(K_2) ∘ … ∘ T_d(K_d) )
```

`K_l` é a matriz de Gram bruta da fonte `l` (de um *kernel* ou fornecida por você), `T_l` a
transformação da componente, `∘` o produto de Hadamard e `T` a transformação final. Pelo teorema
de Schur, `G` é semidefinida positiva para qualquer escolha, e por isso admite uma geometria
(distâncias, vizinhanças, conjuntos de nível) e uma decomposição espectral de energia.

A biblioteca separa, como o artigo, duas coisas:

* **o método** — a construção acima e as leituras sobre `G` (`KernelPipeline`, `GramSpace`);
* **a instanciação** — quais objetos, quais fontes, quais *kernels* e transformações
  (`TorchSources`, `TreeSources`, ou uma função sua).

## Início rápido: um modelo PyTorch

```python
import copy
import fannar as fa

initial = copy.deepcopy(model)        # guarde antes de treinar: é o piso das leituras
# ... treine `model` ...

interp = fa.Interpreter(
    model, X_test, y_test,            # o modelo treinado e as amostras a interpretar
    layers=["layer1", "layer2", "layer3"],   # nomes de model.named_modules()
    reference_model=initial,          # opcional: piso (a mesma rede na inicialização)
    feature_names=names,              # opcional: para as explicações de pares
)

report = interp.evaluate()            # leituras por camada: conjunta, referências e piso
print(report.to_markdown())           # também: report.to_frame(), report.to_json("r.json")

interp.plot_report(report)            # leituras × camadas
interp.plot_embedding()               # o espaço de cada camada nos seus dois modos dominantes
interp.plot_gram("layer2")            # componentes, produto de Hadamard e Gram final
interp.plot_spectrum("layer2")        # autovalores e posto de participação

expl = interp.explain_pair(0)         # por que a amostra 0 difere do vizinho mais próximo
expl.top(5)                           #   com outra predição? [(atributo, x_i, x_j, parcela)]
expl.plot()                           # parcela de cada atributo, camada a camada
interp.swap_test(50)                  # validação por trocas: método × |Δx| × aleatória

emap = interp.energy_map(image, "layer2")   # CNN: energia retida em cada posição da imagem
```

Por padrão, cada camada fornece três fontes, como no artigo:

| fonte | o que é |
|---|---|
| `activations` | a saída da camada, reduzida a uma grade comum de posições |
| `gradients` | a derivada da margem contrastiva `f_c − média(f_{c'≠c})` em relação a essa saída |
| `parameters` | os filtros que o objeto ativou, `p[:, s] = Σ_c A[c, s] W[c, :]` |

e o *pipeline* `"paper"`: *kernel* linear, `(T_a(K) + J)/2` em cada componente, produto de Hadamard
e `T_tr ∘ T_c`.

### Dois cuidados que o código impõe

* **Alvo do gradiente.** Com `target="predicted"`, o gradiente carrega a própria predição, e as
  leituras sobre a decisão ficam circulares. O padrão é `target="fixed"` (classe `fixed_class`
  para todos os objetos).
* **Piso.** Toda leitura precisa de uma referência. Passe `reference_model` (a mesma arquitetura
  com os pesos iniciais): o relatório mede a geometria dessa rede contra o comportamento da rede
  treinada, de modo que a única diferença entre a leitura e o seu piso é o treinamento.

## Sua própria matriz de Gram

Qualquer componente pode vir de um *kernel* seu, de uma transformação sua ou de uma matriz que
você já calculou:

```python
pipe = fa.KernelPipeline(
    {
        "estado":   fa.Component(fa.Linear(), fa.angular() >> fa.shift(1.0)),
        "texto":    fa.Component(fa.RBF(gamma=0.1), fa.identity),
        "meu":      fa.Component(lambda A, B: (A @ B.T + 1) ** 2),      # qualquer função k(X, Y)
    },
    final=fa.center >> fa.trace_normalize,
)
space = pipe(sources={"estado": S, "texto": T, "meu": M}, labels=y)
space = pipe(grams={"estado": K1, "texto": K2, "meu": K3})           # matrizes já prontas
space = fa.GramSpace(minha_matriz_psd, labels=y)                     # ou direto uma G sua
```

Transformações disponíveis (compõem com `>>`, da esquerda para a direita): `identity`, `center`,
`trace_normalize`, `frobenius_normalize`, `max_eig_normalize`, `angular()`, `shift(c)`,
`whiten()`, `spectral(f)`, `psd_project()`. *Kernels*: `Linear`, `Cosine`, `RBF`, `Polynomial`,
`FunctionKernel`. *Presets*: `fa.paper_pipeline()`, `fa.single_source("activations")`,
`fa.positions_pipeline()`.

> Com *kernels* gaussianos, o produto de Hadamard vira identicamente uma soma das métricas das
> fontes (o produto de gaussianas é a gaussiana da soma dos expoentes). Para preservar a interação
> multiplicativa entre as fontes, prefira `Linear`/`Cosine`.

## O espaço de representação (`GramSpace`)

```python
space.distances               # pseudométrica d(i,j)² = G_ii + G_jj − 2 G_ij
space.neighbors(i, k)         # k vizinhos mais próximos
space.level_band(i, r, delta) # faixa de nível Γ_{r,δ}(i)
space.equivalence_classes()   # objetos indistinguíveis para este espaço
space.participation_rank()    # (tr G)² / ‖G‖²_F, sem decomposição espectral
space.energies()              # E_∥, E_⊥ e E_ratio por objeto
space.containment(labels)     # direções de classe dentro de V_r (r = K − 1)
space.embedding(2)            # coordenadas nos dois modos dominantes (PCA de núcleo)
space.cka(outra)              # alinhamento centrado
space.decompose(K)            # G = a·K + R: o que K explica e o resíduo
```

## Outros modelos

```python
# árvore de decisão do scikit-learn: fontes caminho, folga e distribuição de classes por profundidade
interp = fa.Interpreter(tree, X_test, y_test)

# qualquer modelo: uma função que devolve {camada: {fonte: array}} e as predições
def fontes(X):
    return {"saida": {"proba": modelo.predict_proba(X), "folhas": modelo.apply(X)}}, modelo.predict(X)

interp = fa.Interpreter(modelo, X_test, y_test, extractor=fontes,
                        pipeline=fa.KernelPipeline(["proba", "folhas"]), baselines={})
```

## Leituras do relatório

| leitura | pergunta |
|---|---|
| `knn_prediction` | os vizinhos de um objeto têm a mesma predição que ele? |
| `correctness_auc` | a margem geométrica antecipa onde o modelo erra? |
| `confusion_agreement` | as classes que o modelo confunde estão próximas? (≥ 5 classes) |
| `containment` | as direções de classe estão no subespaço retido? |
| `e_ratio_error_auc` | a energia fora do subespaço retido sinaliza os erros? |

## Custo

Por matriz de Gram, `Θ(n²D + n³)` com a decomposição espectral completa (`n` objetos, `D` a
dimensão total das fontes); o posto de participação sai em `Θ(n²)`. A explicação de um par custa
uma passagem direta e uma reversa sobre `F + 2` linhas, linear no número de atributos `F`.

## Testes

```bash
pip install -e ".[test]" && pytest
```

## Licença

This work is licensed under a
[Creative Commons Attribution-NonCommercial 4.0 International License][cc-by-nc].

[![CC BY-NC 4.0][cc-by-nc-image]][cc-by-nc]

O texto completo está em [`LICENCE`](https://github.com/FernandoCsm-Knight/Fannar/blob/main/LICENCE). Para uso comercial do método, há o serviço de
interpretabilidade em [fannar.fernandocsdm.com](https://fannar.fernandocsdm.com).

[cc-by-nc]: https://creativecommons.org/licenses/by-nc/4.0/
[cc-by-nc-image]: https://licensebuttons.net/l/by-nc/4.0/88x31.png
[cc-by-nc-shield]: https://img.shields.io/badge/License-CC%20BY--NC%204.0-lightgrey.svg
