"Seu paper/produção está pronto para o peer-review? O SciAudit diz sim ou não em 1 minuto."
O SciAudit é o primeiro linter do mundo focado não na qualidade do código, mas na integridade da ciência. Ele escaneia seus scripts Python e Jupyter Notebooks em busca de violações metodológicas comuns que invalidam resultados de Data Science e Machine Learning.
O próprio SciAudit audita este repositório em todo commit; score atual A+ sem violações.
A maioria dos linters (como Pylint ou Flake8) verifica se seu código é bonito. O SciAudit verifica se seu código é honesto.
- Detecta Data Leakage: Identifica se você "vazou" o futuro para o passado (ex: normalizar dados antes do split).
- Garante Reprodutibilidade: Exige sementes determinísticas (
random_state) em funções estocásticas. - Evita o "Multicollinearity Trap": Alerta sobre interpretações de importância de features sem análise de correlação prévia.
- Zero Dependências: Funciona "out of the box" usando apenas a biblioteca padrão do Python.
- Suporte a Notebooks: Audita arquivos
.ipynbdiretamente.
Como o SciAudit não possui dependências, a instalação é instantânea:
pip install sciauditAudite um arquivo ou diretório inteiro:
# Rodar auditoria no diretório atual
sciaudit .
# Rodar em um script específico e gerar um laudo em Markdown
sciaudit meu_experimento.py --reportAo usar a flag --report, o SciAudit gera um arquivo SCIAUDIT_REPORT.md contendo:
- Score Global (A+ a F).
- Tabela de Violações.
- Sugestões de Remediação teóricas e práticas.
- Badge de Integridade para você colar no seu README.
O SciAudit foi projetado para ser integrado ao seu fluxo de trabalho de desenvolvimento.
Adicione isto ao seu .pre-commit-config.yaml:
repos:
- repo: local
hooks:
- id: sciaudit
name: SciAudit
entry: sciaudit
language: system
types: [python]
files: \.(py|ipynb)$Exemplo de workflow para .github/workflows/sciaudit.yml:
name: SciAudit CI
on: [push, pull_request]
jobs:
audit:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with: { python-version: '3.10' }
- run: pip install sciaudit
- run: sciaudit . --exit-code-strategy any-errorVocê pode personalizar o comportamento do SciAudit criando um arquivo .sciaudit.yml na raiz do seu projeto:
rules:
SCI-002: warning # Forçar para warning
SCI-003: off # Desativar regra
SCI-006: error # Forçar para erro
paths:
ignore:
- "venv/"
- "legacy_tests/"
- "notebooks/backup/"Use a flag --suggest-fix para receber dicas acionáveis sobre como resolver cada violação:
sciaudit meu_script.py --suggest-fixNem todo projeto exige o mesmo nível de rigor. O SciAudit oferece três perfis pré-definidos:
| Perfil | Descrição | Uso Ideal |
|---|---|---|
balanced (Padrão) |
Severidades padrão das regras. | Uso geral em Data Science. |
strict |
Eleva quase todas as regras para ERROR. |
Projetos médicos, financeiros ou teses. |
relaxed |
Diminui o rigor de regras controversas. | Protipagem rápida e exploração. |
Se você está adotando o SciAudit em um projeto antigo com centenas de alertas, use o modo baseline. Ele permite ignorar violações antigas e focar apenas no que foi introduzido de novo:
- Crie o baseline inicial:
sciaudit . --create-baseline sciaudit-baseline.json - Use o baseline no CI:
sciaudit . --baseline sciaudit-baseline.json
Nota: O exit code retornará 0 se houver apenas violações presentes no baseline. Violações novas quebrarão o build.
Você pode personalizar o comportamento do SciAudit criando um arquivo .sciaudit.yml na raiz do seu projeto. A configuração no arquivo tem precedência total sobre os perfis.
rules:
SCI-002: warning # Forçar para warning
SCI-003: off # Desativar regra
SCI-006: error # Forçar para erro
paths:
ignore:
- "venv/"
- "legacy_tests/"--exit-code-strategy any-error(Padrão): Falha no build se houver qualquer violaçãoERRORouWARNING(não presente no baseline).--exit-code-strategy errors-only: Falha no build apenas em caso de violaçõesERROR.--exit-code-strategy always-zero: Nunca falha o build.
import pandas as pd
from sklearn.preprocessing import StandardScaler
df = pd.read_csv("data.csv")
# VIOLAÇÃO SCI-001: Fit antes do split!
scaler = StandardScaler()
df_scaled = scaler.fit_transform(df)
train, test = train_test_split(df_scaled) ● SCI-001 [error] Data Leakage
A função 'fit_transform' foi chamada antes de um split de dados ser detectado.
➔ Sugestão: Aplique o split (train_test_split) ANTES de qualquer fit/transform.
Linha 7: df_scaled = scaler.fit_transform(df)
- Análise Estática: O SciAudit usa AST (Abstract Syntax Tree). Ele não executa o código. Se você usar métodos altamente dinâmicos (
exec,getattrcomplexos), a detecção pode ser limitada. - Falsos Positivos: Algumas regras (especialmente SCI-008 e SCI-013) usam heurísticas textuais e de nomenclatura. Elas servem como alertas para revisão humana, não como verdades absolutas.
- Não Substitui o Peer-Review: Esta ferramenta é um assistente, não um juiz final. A integridade científica final é responsabilidade dos autores.
O SciAudit organiza suas regras em categorias críticas, cada uma com uma severidade padrão:
| ID | Nome | Descrição |
|---|---|---|
| SCI-001 | Data Leakage | Transformações (fit/transform) ocorrendo antes do split. |
| SCI-006 | Contaminação | Uso de X_test ou y_test dentro do método fit(). |
| SCI-007 | Time Leakage | Reordenação (sort_values) de dados temporais após o split. |
| SCI-008 | Label Leakage | Criação de features derivadas diretamente da variável alvo. |
| SCI-017 | Time Shuffle | Embaralhamento de dados temporais em splits cronológicos. |
| ID | Nome | Descrição |
|---|---|---|
| SCI-002 | Random Seed | Falta de random_state em funções estocásticas. |
| SCI-004 | P-Value Hacking | Múltiplas comparações estatísticas sem correção de Bonferroni/FDR. |
| SCI-005 | Overfitting Cego | Uso de métricas (accuracy, r2) sem Cross-Validation detectável. |
| SCI-009 | Imbalance Ignored | Uso de acurácia em datasets desbalanceados sem checagem prévia. |
| SCI-014 | Silent NaN Drop | Remoção de dados faltantes (dropna) sem log/print do impacto. |
| ID | Nome | Descrição |
|---|---|---|
| SCI-003 | Multicolinearidade | Interpretação de importância de features sem análise de correlação. |
| SCI-013 | Causal Hubris | Afirmações de causalidade em comentários sem evidência de rigor. |
O SciAudit nasceu para combater a crise de reprodutibilidade na ciência de dados. Acreditamos que a integridade deve ser automatizada e que todo modelo de alta performance deve ser, antes de tudo, um modelo de alta honestidade.
Desenvolvido com ❤️ por Lucas Hoffnung Bernardo (@lbhoffnung) para a comunidade científica.