Fannar
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.
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
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.
| Energia retida × ortogonal. O atalho ocupa os modos dominantes, mas o gato continua representado fora deles: 68% da energia ortogonal fica no animal. | Erros com convicção. 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. |
| Explicação de pares (XGBoost). O que separa um cliente recusado de um aprovado parecido; onde Fannar, SHAP e LIME concordam, a conclusão fica mais firme. | Transformers. As intenções de clientes se separando bloco a bloco de um DistilBERT ajustado, contra o mesmo modelo antes do ajuste fino. |
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.
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
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"(classefixed_classpara 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:
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)
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
# á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
pip install -e ".[test]" && pytest
Licença
This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.
O texto completo está em LICENCE. Para uso comercial do método, há o serviço de
interpretabilidade em fannar.fernandocsdm.com.
Metadata
Release files for fannar 0.3.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| fannar-0.3.1.tar.gz | 54.6 kB | Without provenance | Details for fannar-0.3.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| fannar-0.3.1-py3-none-any.whl | Python 3 | none | any | Details for fannar-0.3.1-py3-none-any.whl |
Total release size: 104.8 kB
Release files / fannar-0.3.1.tar.gz
| Download URL | fannar-0.3.1.tar.gz |
|---|---|
| Size | 54.6 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
424805c9a5a9296cd7f4fd300b35264f74809118c26061eb406168206e6556e1
|
|
BLAKE2b-256 checksum How to use checksums |
b85a9b7899fdf3acf5b9d03b022d5c74d11a5774c11c01b188a3a1107df80bbf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Release files / fannar-0.3.1-py3-none-any.whl
| Download URL | fannar-0.3.1-py3-none-any.whl |
|---|---|
| Size | 50.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
9ba24efc386df0b7f43422cf07045a1d78f435fe63fcb4afd3c86afedc52ad5f
|
|
BLAKE2b-256 checksum How to use checksums |
cf93599197cc62f6ba681a3cb86256f3dc6b7c4977890e3b19ff61d1dc8ab230
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.10
|
Security for fannar 0.3.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.