Skip to content

madsondeluna/evo-hex

Repository files navigation

Evo-Hex: Pipeline de Análise Estrutural e Evolutiva

Pipeline modular em Python para download, limpeza e análise de estruturas proteicas da classe Mainly Alpha do banco de dados CATH. Gera 21 visualizações cobrindo desde composição de aminoácidos em hélices até análises evolutivas com base em restrições estruturais e viés do código genético.


Índice

  1. O que é o CATH e por que Mainly-Alpha?
  2. Instalação
  3. Configuração
  4. Como executar
  5. Etapas do pipeline
  6. Catálogo de análises e gráficos
  7. Estrutura de arquivos gerados
  8. Estrutura do código
  9. Dependências externas
  10. Perguntas frequentes

1. O que é o CATH e por que Mainly-Alpha?

CATH (Class, Architecture, Topology, Homology) é um banco de dados hierárquico de domínios proteicos com estrutura 3D determinada experimentalmente. Cada domínio é classificado pela composição de sua estrutura secundária.

A classe 1 - Mainly Alpha agrupa domínios cuja estrutura é dominada por hélices alpha (≥60% de resíduos em conformação helicoidal). Essa classe é biologicamente relevante por incluir:

  • Proteínas transportadoras de oxigênio (globinas)
  • Receptores acoplados à proteína G (GPCRs)
  • Canais iônicos e proteínas de membrana
  • Fatores de transcrição com motivos helix-turn-helix
  • Proteínas de coiled-coil envolvidas em sinalização

Estudar essa classe em larga escala permite responder perguntas sobre restrições evolutivas na composição de hélices: quais aminoácidos são selecionados pela estrutura? Qual o papel do código genético nessa seleção? Como diferentes tipos de hélice evoluem?


2. Instalação

Pré-requisitos

  • Python 3.10 ou superior
  • mkdssp (obrigatório para análises de estrutura secundária)

Criar e ativar um ambiente virtual

Sempre trabalhe dentro de um ambiente virtual. Isso isola as dependências do projeto e evita conflitos com outros pacotes instalados no sistema.

# Criar o ambiente (apenas uma vez)
python3 -m venv .venv

# Ativar no macOS/Linux
source .venv/bin/activate

# Ativar no Windows
.venv\Scripts\activate

Você saberá que o ambiente está ativo quando o prompt mostrar (.venv) no início. Para desativar ao terminar:

deactivate

Dica: adicione .venv/ ao seu .gitignore para não versionar o ambiente.

Instalar dependências Python

Com o ambiente virtual ativo:

pip install -r requirements.txt

Para o gráfico de PCA também é necessário:

pip install scikit-learn

Instalar DSSP

O DSSP é um programa externo que determina a estrutura secundária a partir de coordenadas atômicas. É necessário para as análises das etapas 4, 5 e 6.

macOS:

brew install brewsci/bio/dssp

Ubuntu/Debian:

sudo apt install dssp

Manual: https://swift.cmbi.umcn.nl/gv/dssp/

Verifique a instalação:

which mkdssp   # deve retornar o caminho do executável

3. Configuração

Toda a configuração está centralizada em cath_analysis/config.py. O único parâmetro que você precisa editar é o diretório base:

# cath_analysis/config.py
BASE_PATH = Path("/seu/caminho/para/cath")

Os demais caminhos são derivados automaticamente:

Constante Caminho padrão Conteúdo
STRUCTURES_PATH BASE_PATH/structures/ PDBs brutos baixados
STRUCTURES_CLEAN_PATH BASE_PATH/structures_clean/ PDBs limpos (cadeia A)
LOGS_PATH BASE_PATH/logs/ Relatórios e logs de erros
ANALYSIS_PATH BASE_PATH/analysis/ Gráficos e CSVs gerados

4. Como executar

Recomendado: usar tmux

A etapa 4 (DSSP unificado) leva 30-60 min no modo S40 ou 3-4h no dataset completo. Use tmux para deixar o pipeline rodando em background sem risco de o processo morrer se o terminal for fechado.

# 1. Criar uma sessao tmux (apenas na primeira vez)
tmux new -s evo-hex

# 2. Dentro da sessao, ativar o ambiente virtual
source /Volumes/promethion/cath/.venv/bin/activate

# 3. Entrar na pasta e rodar
cd /Volumes/promethion/cath
python main.py

# 4. Para sair sem matar o processo: Ctrl+B, depois D
#    O pipeline continua rodando em background.

# 5. Para reconectar e ver o progresso (use sempre este comando ao voltar)
tmux attach -t evo-hex

Se ao tentar criar a sessao aparecer duplicate session: evo-hex, significa que ela ja existe. Use diretamente tmux attach -t evo-hex para entrar nela.

Instalar tmux: brew install tmux (macOS) ou sudo apt install tmux (Linux).

Fluxo básico

# Executa todas as 6 etapas com menus interativos
python main.py

Modo exploração (já tem a base baixada)

Se você já baixou e limpou as estruturas, pule diretamente para a análise:

python main.py --explore

O pipeline detecta automaticamente dados existentes em todas as etapas. Ao re-executar, você será perguntado se deseja repetir cada etapa já concluída:

  Resultados existentes encontrados (gerados em 2025-11-08 15:44).

  Re-executar análise de hélices (DSSP)? [s/N]

Responda N (ou Enter) para pular e usar os dados existentes. Isso permite retomar o pipeline de onde parou sem re-executar etapas demoradas.

Importante: a deteccao e por etapa completa. Se o pipeline for interrompido no meio de uma etapa (ex: Ctrl+C durante o DSSP), sera necessario re-executar essa etapa do zero - nao ha checkpoint parcial por arquivo.

Referência completa de flags

Comando Descrição
python main.py Pipeline completo, modo interativo
python main.py --explore Pula etapas 1-2, vai direto à análise
python main.py --steps 3 4 5 Executa apenas as etapas especificadas
python main.py --force-download Re-baixa e relimpa sem perguntar
python main.py --skip-download Pula etapas 1-2 sem perguntar
python main.py --no-interactive Sem menus, executa tudo automaticamente
python main.py --full-dataset Baixa dataset completo (~50k) sem filtro S40
python main.py --plots g3 g4 Pré-seleciona grupos de gráficos no menu
python main.py --plots helical_wheel_average pca_aa_composition Pré-seleciona gráficos individuais
python main.py --list-plots Lista todos os 21 gráficos disponíveis e sai

Exemplos práticos

# Primeiro uso: baixa tudo e analisa
python main.py

# Sessão de re-análise (dados já existem)
python main.py --explore

# Gerar só gráficos evolutivos e de código genético
python main.py --explore --plots g3 g5 g6

# Pipeline completo em servidor (sem interação)
python main.py --no-interactive --force-download

# Só baixar e limpar
python main.py --steps 1 2

# Ver o que pode plotar
python main.py --list-plots

Menu interativo de gráficos

Após as etapas de análise, o menu aparece automaticamente:

═══════════════════════════════════════════════════════════════════
  EVO-HEX - SELETOR DE GRAFICOS EVOLUTIVOS
═══════════════════════════════════════════════════════════════════

  1. Análise Básica de Hélices
  ───────────────────────────────────────────────────────
  [ ]  1. [DSSP]       Propensão para hélices (observada vs Chou-Fasman)
  [ ]  2. [DSSP]       Preferência por posição na hélice
  ...

  Comandos:
  <número>      Selecionar/deselecionar gráfico
  g<número>     Selecionar/deselecionar grupo inteiro (ex: g3)
  all           Selecionar todos
  none          Desmarcar todos
  info <num>    Ver descrição detalhada
  run           Gerar gráficos selecionados
  q             Sair sem plotar

5. Etapas do pipeline

Etapa 1: Download de estruturas

Baixa o índice de domínios do CATH e faz download paralelo das estruturas PDB da classe Mainly-Alpha (classe 1) diretamente do RCSB.

Por padrão aplica o filtro S40 (subconjunto não-redundante), baixando apenas ~2-5 mil estruturas representativas em vez das ~50 mil totais. Para o dataset completo use --full-dataset.

  • Fonte do índice CATH: http://download.cathdb.info/...
  • Fonte da lista S40: http://download.cathdb.info/...
  • Fonte dos PDBs: https://files.rcsb.org/download/{}.pdb
  • Download paralelo com até 20 workers simultâneos
  • Retoma automaticamente (pula arquivos já baixados)
  • Gera: logs/download_report.txt, mainly_alpha_pdb_codes.txt

Saída esperada: ~2-5 mil arquivos .pdb em structures/ (modo S40 padrão)

Etapa 2: Limpeza de estruturas

Processa cada PDB para remover ruído e padronizar o formato:

  • Mantém apenas o modelo 0 (primeiro modelo em NMR)
  • Mantém apenas a cadeia A
  • Remove heteroátomos (HETATM): água, íons, ligantes, cofatores
  • Remove resíduos não-padrão (mantém apenas os 20 aminoácidos canônicos)
  • Estruturas sem cadeia A ou com 0 resíduos após limpeza são descartadas
  • Processamento paralelo com ThreadPoolExecutor

Saída esperada: arquivos .pdb limpos em structures_clean/

Etapa 3: Frequência de aminoácidos

Conta a ocorrência de cada aminoácido em todas as estruturas limpas.

  • Contagem global e por estrutura
  • Gera: amino_acid_frequencies_global.txt, amino_acid_frequencies_per_structure.csv

Etapa 4: Passo DSSP unificado

Tempo estimado: 30-60 min para ~2-5k estruturas S40 (7 workers paralelos). Para o dataset completo (~50k), espere 3-4h. Recomenda-se tmux/screen.

Passo DSSP único e abrangente que coleta todos os dados de uma vez para as análises das etapas 4, 5 e 6. Não há mais três passes separados sobre as estruturas — tudo é coletado em uma única varredura paralela.

O que é coletado nessa etapa:

  • Propensão de cada AA para hélices (observada vs. Chou-Fasman)
  • Preferência por posição: N-terminal, meio, C-terminal
  • Classificação de hélices por tipo (H / G / I) e composição por tipo
  • Distribuição de comprimentos por tipo de hélice
  • Padrão heptad de hidrofobicidade
  • Sequências individuais de cada hélice (para momento hidrofóbico e helical wheel)
  • Preferências de N-cap e C-cap (primeiras/últimas 3 posições)
  • Distribuição completa de AAs por posição no heptad
  • Pares de transição entre tipos de hélice
  • Fração helicoidal por estrutura

Resultados salvos em analysis/unified_report.txt e nos CSVs de análise.

Etapa 5: Tipos de hélices (H/G/I)

Tempo estimado: instantâneo (dados coletados na etapa 4).

Apresenta os dados de classificação de hélices já coletados na etapa 4:

Tipo DSSP Nome Ligação de H Resíduos/volta
H Alpha helix i → i+4 3,6
G 3-10 helix i → i+3 3,0
I Pi helix i → i+5 4,4

Etapa 6: Dados evolutivos

Tempo estimado: instantâneo (dados coletados na etapa 4).

Carrega os dados evolutivos do pickle gerado pela etapa 4 e disponibiliza-os para os gráficos dos grupos 3, 4, 5 e 6.


6. Catálogo de análises e gráficos

Grupo 1: Análise Básica de Hélices

1.1 Propensão para hélices

Arquivo: helix_propensities.png

Dois subplots:

  • Barras duplas: compara a propensão observada (calculada dos dados) com a propensão teórica da escala de Chou-Fasman para cada aminoácido.
  • Scatter: frequência global do AA vs. frequência dentro de hélices, com linha diagonal indicando ausência de enriquecimento.

Valor: Revela quais AAs estão sobre- ou sub-representados em hélices. ALA, GLU, LEU com propensão >1.2 são os grandes formadores; GLY e PRO (<0.6) são disruptores. Desvios entre observado e Chou-Fasman indicam pressões específicas do conjunto CATH.


1.2 Preferência por posição na hélice

Arquivo: helix_positions.png

Heatmap 20×3 com a frequência de cada aminoácido no N-terminal, meio e C-terminal da hélice.

Valor: Certas posições são estruturalmente mais restritivas. AAs com capacidade de fazer N-cap (ASN, ASP) aparecem enriquecidos no N-terminal. GLY é tolerado no C-terminal mas raramente no meio de hélices longas. Essa análise é base para identificar restrições evolutivas posicionais.


1.3 Distribuição de comprimentos

Arquivo: helix_lengths.png

Histograma + boxplot dos comprimentos de hélices em resíduos.

Valor: Hélices alpha estáveis tendem a ter 10-20 resíduos. A distribuição de comprimentos reflete a pressão seletiva para manter a hélice coesa: hélices muito curtas (4-6 res.) têm menor estabilidade térmica.


1.4 Padrão heptad

Arquivo: heptad_pattern.png

Frequência de resíduos hidrofóbicos em cada posição do heptad repeat (a-g).

Valor: Em coiled-coils, as posições a e d do heptad são hidrofóbicas para formar a interface entre as cadeias. Esse gráfico revela se o conjunto CATH Mainly-Alpha exibe essa periodicidade, sugerindo presença de coiled-coils ou de pressão seletiva para periodicidade hidrofóbica.


Grupo 2: Tipos de Hélices

2.1 Distribuição de tipos H/G/I

Arquivo: helix_type_distribution.png

Bar chart e pie chart com a contagem e proporção de hélices Alpha (H), 3-10 (G) e Pi (I).

Valor: Em proteínas globulares, >90% das hélices são do tipo H. 3-10 helices aparecem tipicamente nos terminais de hélices maiores ou em loops curtos. Pi helices são raras (<1%) e geralmente associadas a regiões funcionais. A proporção informa o grau de diversidade estrutural do conjunto.


2.2 Composição por tipo (heatmap)

Arquivo: helix_type_composition_heatmap.png

Heatmap 20×3 comparando a frequência de cada AA em H, G e I helices simultaneamente.

Valor: Permite identificar AAs diferencialmente enriquecidos por tipo. PRO, por exemplo, tende a ocorrer em 3-10 helices mais do que em alpha helices. Essas diferenças refletem restrições geométricas distintas de cada tipo.


2.3 Top-10 AAs por tipo

Arquivo: helix_type_top_amino_acids.png

Barras horizontais com os 10 AAs mais frequentes em cada tipo de hélice.


2.4 Comprimento por tipo

Arquivo: helix_length_by_type.png

Boxplot + histograma sobrepostos comparando a distribuição de comprimentos entre H, G e I.

Valor: 3-10 helices são estruturalmente limitadas a 3-6 resíduos pela geometria da ligação de hidrogênio i→i+3. Alpha helices são estáveis de 5 a >30 resíduos. O gráfico quantifica essa distribuição no conjunto real.


2.5 Comparação estatística Alpha vs. 3-10

Arquivo: helix_type_statistical_comparison.png

Barras de diferença de frequência e scatter direto Alpha vs. 3-10 para cada AA.

Valor: Destaca os AAs com maior diferenciação entre os dois tipos. AAs enriquecidos em 3-10 (como PRO, GLY) são candidatos a estudos de transição evolutiva entre tipos de hélice.


Grupo 3: Restrições Estruturais

3.1 Helical wheel composto

Arquivo: helical_wheel_average.png

Projeção polar: frequência de resíduos hidrofóbicos por posição angular na hélice. Cada resíduo ocupa 100° em relação ao anterior, completando ~3,6 resíduos por volta. A escala de cores vai de azul (polar) a vermelho (hidrofóbico).

Valor: Revela a anfipatiticidade do conjunto. Em hélices anfipáticas funcionais (e.g., hélices de membrana, hélices de ligação a lipídeos), um setor angular claro com alta frequência hidrofóbica deve emergir. A ausência desse padrão indica que o conjunto é dominado por hélices de interior proteico com distribuição uniforme. É uma das análises mais diretas de restrição estrutural evolutiva.


3.2 Momento hidrofóbico de Eisenberg

Arquivo: hydrophobic_moment_distribution.png

Distribuição do momento hidrofóbico (μH) por hélice, calculado pela escala de Eisenberg. Hélices são classificadas em anfipáticas baixas (<0,2), médias (0,2-0,4) e altas (≥0,4).

Valor: O momento hidrofóbico é um preditor de função. Hélices com μH alto são associadas a: inserção em membranas, interação com lipídeos, atividade antimicrobiana. A distribuição do μH no conjunto CATH informa a proporção de hélices funcionalmente anfipáticas vs. estruturalmente internas.


3.3 N-cap e C-cap (3 posições)

Arquivo: ncap_ccap_preferences.png

Heatmaps das frequências de AAs nas 3 primeiras posições da hélice (N1, N2, N3) e nas 3 últimas (C3, C2, C1).

Valor: As posições de cap têm preferências fortíssimas sob seleção purificadora:

  • N-cap: ASN e ASP são enriquecidos porque fazem ligações de hidrogênio com os NH da hélice não satisfeitos pelas posições iniciais.
  • C-cap: GLY é favorecido pela flexibilidade que permite a curvatura da cadeia ao sair da hélice.

Desvios dessas preferências podem indicar hélices com funções especiais ou pressões evolutivas distintas (e.g., hélices de proteínas termófilas).


Grupo 4: Composição e Variabilidade

4.1 PCA da composição por estrutura

Arquivo: pca_aa_composition.png

Cada proteína é representada como um vetor de 20 frequências (uma por AA), reduzido para 2 dimensões por PCA. Pontos são coloridos pelo AA dominante.

Valor: Agrupa proteínas por "assinatura" de composição. Estruturas funcionalmente relacionadas devem agrupar. Outliers revelam proteínas com composição incomum. PC1 tipicamente captura a variação hidrofóbico/hidrofílico; PC2 captura outros gradientes físico-químicos. Requer scikit-learn.


4.2 Distribuição de conteúdo helicoidal

Arquivo: helix_content_distribution.png

Histograma + violin plot da fração de resíduos em hélice por proteína.

Valor: Embora todas as proteínas sejam da classe Mainly-Alpha, a distribuição de conteúdo helicoidal varia significativamente. Proteínas com >80% são casos extremos (e.g., hélices de membrana). A distribuição real quantifica a heterogeneidade da classe e pode ser comparada com outras classes CATH como referência evolutiva.


4.3 Co-ocorrência de AAs em hélices

Arquivo: aa_cooccurrence.png

Heatmap 20×20 onde cada célula representa a frequência relativa de pares de AAs que aparecem juntos na mesma hélice.

Valor: Pares com alta co-ocorrência podem refletir:

  • Interações físicas: GLU-LYS e ASP-ARG formam salt bridges (i→i+4) que estabilizam hélices.
  • Perfis evolutivos compartilhados: AAs com propensão similar tendem a ser trocados por mutação e co-ocorrem mais.
  • Viés composicional: LEU e ALA co-ocorrem simplesmente por serem os mais frequentes.

A análise deve ser interpretada com baseline de frequência esperada (produto das frequências marginais).


4.4 Comprimento vs. composição

Arquivo: helix_length_vs_composition.png

Barras agrupadas: frequência de cada grupo físico-químico (hidrofóbico, polar, carregado+, carregado-, especial) em hélices curtas (4-9 res.), médias (10-19) e longas (≥20).

Valor: Hélices longas tendem a ser mais ricas em AAs de alta propensão (ALA, LEU, GLU). Hélices curtas toleram mais GLY e PRO. Essa relação comprimento-composição é uma evidência direta de seleção estrutural: AAs disruptores são tolerados apenas em contextos curtos onde a hélice não precisa ser mantida por muitos resíduos.


Grupo 5: Transições e História Evolutiva

5.1 Matriz de transição H→G→I

Arquivo: helix_transition_matrix.png

Heatmap normalizado com a probabilidade de cada tipo de hélice ser seguido por outro tipo dentro da mesma proteína.

Valor: Revela se existe uma hierarquia de transições. A hipótese evolutiva é que 3-10 helices são estados ancestrais ou transicionais de alpha helices, proteínas que "experimentam" hélices mais curtas antes de estabilizar em alpha. Uma alta taxa de H→G seguida de G→H indicaria coexistência de ambos os tipos no mesmo contexto estrutural.


5.2 Razão 3-10/(H+G+I) por comprimento

Arquivo: g_ratio_by_length.png

Linha com a fração de hélices 3-10 em cada comprimento. Barra cinza de fundo mostra o total de hélices por comprimento.

Valor: Testa diretamente a hipótese de que hélices curtas são predominantemente 3-10. Se a curva cai monotonicamente com o comprimento, confirma a restrição geométrica: hélices longas simplesmente não conseguem manter a geometria 3-10. Picos em comprimentos específicos podem indicar contextos estruturais especiais.


5.3 Entropia de Shannon por posição do heptad

Arquivo: shannon_entropy_heptad.png

Entropia de Shannon calculada a partir da distribuição de AAs em cada posição (a-g) do heptad. Baixa entropia = maior conservação = maior pressão seletiva.

Valor: Em coiled-coils clássicos, posições a e d têm baixa entropia (dominadas por LEU, ILE, VAL) enquanto posições b, c, e, f, g têm alta entropia (qualquer AA). A assinatura heptad de entropia é um indicador da proporção de coiled-coils no conjunto e da magnitude da seleção nessas posições.


Grupo 6: Viés do Código Genético

6.1 Degenerescência de códons vs. propensão

Arquivo: codon_degeneracy_vs_propensity.png

Dois scatters lado a lado:

  • Número de códons do AA (degenerescência) vs. propensão teórica (Chou-Fasman)
  • Número de códons vs. propensão observada no conjunto CATH

Valor: Permite separar dois mecanismos distintos de composição:

  • Seleção estrutural: AAs com alta propensão são favorecidos pela geometria da hélice.
  • Deriva neutra / viés mutacional: AAs com mais códons (LEU=6, SER=6) ocorrem mais por pura probabilidade mutacional.

Se a correlação propensão×códons é fraca, a composição das hélices é dominada por seleção. Se é forte, o viés do código genético tem papel relevante, uma questão aberta aberta em evolução molecular.


6.2 Enriquecimento vs. proteoma humano

Arquivo: proteome_comparison.png

Dois subplots:

  • Barras: razão Observado/Proteoma (>1 = enriquecido em hélices, <1 = depleto)
  • Scatter: frequência no proteoma humano de referência vs. frequência observada

Frequências de referência: proteoma humano médio (UniProt/Swiss-Prot).

Valor: Normaliza a composição das hélices pelo background proteômico. Um AA pode ser frequente nas hélices simplesmente porque é frequente em proteínas em geral (caso do LEU). O enriquecimento real (controlando pelo background) revela a seleção verdadeira. ALA com enriquecimento >1.3 e PRO com <0.5 são esperados; desvios desses valores indicam particularidades da classe Mainly-Alpha.


7. Estrutura de arquivos gerados

BASE_PATH/
├── cath-domain-list.txt              # Índice CATH baixado
├── cath-s40-domains.txt              # Lista S40 não-redundante
├── mainly_alpha_pdb_codes.txt        # Códigos PDB da classe 1 (filtrados S40)
│
├── structures/                       # Etapa 1: PDBs brutos
│   ├── 1abc.pdb
│   └── ...
│
├── structures_clean/                 # Etapa 2: PDBs limpos
│   ├── 1abc.pdb                      # Apenas cadeia A, sem heteroátomos
│   └── ...
│
├── logs/
│   ├── download_report.txt
│   ├── failed_downloads.txt
│   ├── cleaning_report.txt
│   ├── no_chain_a.txt
│   └── cleaning_errors.txt
│
└── analysis/
    ├── amino_acid_frequencies_global.txt
    ├── amino_acid_frequencies_per_structure.csv
    │
    ├── unified_report.txt            # Relatório do passo DSSP unificado
    ├── helix_propensities.csv
    ├── helix_positions.csv
    ├── helix_lengths.csv
    ├── helix_lengths_by_type.csv
    ├── helix_type_composition.csv
    ├── helix_type_top_residues.csv
    ├── helix_type_statistical_comparison.csv
    ├── codon_degeneracy.csv
    ├── proteome_comparison.csv
    ├── evo_data.pkl                  # Dados evolutivos (momento, heptad, caps...)
    │
    └── *.png                         # 21 gráficos gerados

8. Estrutura do código

cath/
├── main.py                           # Ponto de entrada (CLI)
├── requirements.txt
│
└── cath_analysis/
    ├── __init__.py
    ├── config.py                     # Constantes e caminhos
    ├── downloader.py                 # Etapa 1: download CATH + PDB (com filtro S40)
    ├── cleaner.py                    # Etapa 2: limpeza PDB
    ├── frequency_analysis.py         # Etapa 3: frequência de AAs
    ├── unified_dssp.py               # Etapa 4: passo DSSP único (coleta tudo)
    ├── evolutionary_analysis.py      # Funções de cálculo evolutivo (momento, entropia...)
    ├── plotting.py                   # Todas as 21 funções de visualização
    └── menu.py                       # Menu interativo de seleção de gráficos

Dependências entre módulos

config.py ←── todos os módulos
downloader.py ──→ Etapa 1
cleaner.py ──────→ Etapa 2
frequency_analysis.py ──→ Etapa 3 → PCA (plotting)
unified_dssp.py ─────────→ Etapa 4 → dados para etapas 5 e 6
evolutionary_analysis.py → cálculos sobre evo_data → plotting
menu.py ──────────────────────────────→ main.py

9. Dependências externas

Pacote Versão mínima Uso
biopython 1.81 Parser PDB, DSSP, seleção de cadeias
numpy 1.24 Cálculos numéricos
pandas 2.0 DataFrames de resultados
matplotlib 3.7 Visualizações
seaborn 0.12 Heatmaps e estilos
requests 2.28 Download de PDBs
tqdm 4.65 Barras de progresso
scipy 1.11 (reservado para extensões)
scikit-learn - Opcional: PCA (etapa 4.1)
mkdssp - Externo: estrutura secundária

10. Perguntas frequentes

Q: O download trava em alguns PDBs. É normal?

Sim. Alguns códigos PDB foram obsoletados ou renomeados no RCSB. O pipeline marca esses casos como error e continua. Os códigos que falharam ficam em logs/failed_downloads.txt.


Q: DSSP falha em várias estruturas. Por quê?

DSSP requer que os átomos backbone (N, Cα, C, O) estejam presentes e com distâncias razoáveis. Estruturas com resolução muito baixa, modelos incompletos ou erros de modelagem podem falhar. O pipeline registra e pula essas estruturas.


Q: O mkdssp mostra "parse error at line 1: This file does not seem to be an mmCIF file". E um problema?

Nao. O mkdssp 4.x aceita arquivos PDB mas emite esse aviso no stderr porque espera mmCIF por padrao. O BioPython 1.84+ ja trata isso automaticamente passando --output-format=dssp ao detectar mkdssp >= 4.0. O pipeline suprime o aviso e processa normalmente.


Q: Posso usar estruturas de outra fonte (não CATH)?

Sim. Basta colocar os PDBs limpos (cadeia A, sem heteroátomos) em structures_clean/ e executar a partir da etapa 3:

python main.py --steps 3 4 5 6

Q: O PCA não está disponível.

Instale o scikit-learn:

pip install scikit-learn

Q: A limpeza mostra o dobro de estruturas esperadas (ex: 101.978 em vez de ~51.000). Por que?

Isso ocorre quando o diretório structures/ ja contem arquivos de execucoes anteriores do pipeline (ou do notebook original) no momento em que um novo download e iniciado. O cleaner processa todos os PDBs presentes, independente da origem.

Workaround atual: remova manualmente o diretório antes de rodar:

rm -rf /Volumes/promethion/cath/structures/
python main.py

Bug conhecido (a corrigir): o flag --force-download deveria limpar o diretório structures/ antes de iniciar o novo download, garantindo que apenas as estruturas da sessão atual sejam processadas.


Q: Como citar o CATH?

Sillitoe I. et al. (2021). CATH: expanding the horizons of structure-based functional annotations for genome sequences. Nucleic Acids Research, 49(D1), D377-D385. https://doi.org/10.1093/nar/gkaa1079

About

Automated pipeline for downloading, cleaning, and analyzing mainly alpha-helix protein structures from the CATH database.

Topics

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors