{"id":49563253,"url":"https://github.com/madsondeluna/evo-hex","last_synced_at":"2026-05-03T10:47:23.186Z","repository":{"id":323224016,"uuid":"1092427340","full_name":"madsondeluna/evo-hex","owner":"madsondeluna","description":"Automated pipeline for downloading, cleaning, and analyzing mainly alpha-helix protein structures from the CATH database.","archived":false,"fork":false,"pushed_at":"2026-03-28T01:43:27.000Z","size":51953,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-03T10:47:19.500Z","etag":null,"topics":["bioinformatics","data-science","database-access","protein-evolution","protein-folding","structural-biology"],"latest_commit_sha":null,"homepage":"https://www.cathdb.info/","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/madsondeluna.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T15:59:26.000Z","updated_at":"2026-04-23T19:45:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/madsondeluna/evo-hex","commit_stats":null,"previous_names":["madsondeluna/cath-mainly-alpha","madsondeluna/evo-hex"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/madsondeluna/evo-hex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madsondeluna%2Fevo-hex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madsondeluna%2Fevo-hex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madsondeluna%2Fevo-hex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madsondeluna%2Fevo-hex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/madsondeluna","download_url":"https://codeload.github.com/madsondeluna/evo-hex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/madsondeluna%2Fevo-hex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32566444,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bioinformatics","data-science","database-access","protein-evolution","protein-folding","structural-biology"],"created_at":"2026-05-03T10:47:22.448Z","updated_at":"2026-05-03T10:47:23.172Z","avatar_url":"https://github.com/madsondeluna.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Evo-Hex: Pipeline de Análise Estrutural e Evolutiva\n\nPipeline modular em Python para download, limpeza e análise de estruturas proteicas\nda classe **Mainly Alpha** do banco de dados CATH. Gera 21 visualizações cobrindo\ndesde composição de aminoácidos em hélices até análises evolutivas com base em\nrestrições estruturais e viés do código genético.\n\n---\n\n## Índice\n\n1. [O que é o CATH e por que Mainly-Alpha?](#1-o-que-é-o-cath-e-por-que-mainly-alpha)\n2. [Instalação](#2-instalação)\n3. [Configuração](#3-configuração)\n4. [Como executar](#4-como-executar)\n5. [Etapas do pipeline](#5-etapas-do-pipeline)\n6. [Catálogo de análises e gráficos](#6-catálogo-de-análises-e-gráficos)\n7. [Estrutura de arquivos gerados](#7-estrutura-de-arquivos-gerados)\n8. [Estrutura do código](#8-estrutura-do-código)\n9. [Dependências externas](#9-dependências-externas)\n10. [Perguntas frequentes](#10-perguntas-frequentes)\n\n---\n\n## 1. O que é o CATH e por que Mainly-Alpha?\n\n**CATH** (Class, Architecture, Topology, Homology) é um banco de dados hierárquico\nde domínios proteicos com estrutura 3D determinada experimentalmente. Cada domínio é\nclassificado pela composição de sua estrutura secundária.\n\nA classe **1 - Mainly Alpha** agrupa domínios cuja estrutura é dominada por hélices\nalpha (≥60% de resíduos em conformação helicoidal). Essa classe é biologicamente\nrelevante por incluir:\n\n- Proteínas transportadoras de oxigênio (globinas)\n- Receptores acoplados à proteína G (GPCRs)\n- Canais iônicos e proteínas de membrana\n- Fatores de transcrição com motivos helix-turn-helix\n- Proteínas de coiled-coil envolvidas em sinalização\n\nEstudar essa classe em larga escala permite responder perguntas sobre **restrições\nevolutivas** na composição de hélices: quais aminoácidos são selecionados pela\nestrutura? Qual o papel do código genético nessa seleção? Como diferentes tipos de\nhélice evoluem?\n\n---\n\n## 2. Instalação\n\n### Pré-requisitos\n\n- Python 3.10 ou superior\n- `mkdssp` (obrigatório para análises de estrutura secundária)\n\n### Criar e ativar um ambiente virtual\n\n**Sempre trabalhe dentro de um ambiente virtual.** Isso isola as dependências do\nprojeto e evita conflitos com outros pacotes instalados no sistema.\n\n```bash\n# Criar o ambiente (apenas uma vez)\npython3 -m venv .venv\n\n# Ativar no macOS/Linux\nsource .venv/bin/activate\n\n# Ativar no Windows\n.venv\\Scripts\\activate\n```\n\nVocê saberá que o ambiente está ativo quando o prompt mostrar `(.venv)` no início.\nPara desativar ao terminar:\n\n```bash\ndeactivate\n```\n\n\u003e **Dica:** adicione `.venv/` ao seu `.gitignore` para não versionar o ambiente.\n\n### Instalar dependências Python\n\nCom o ambiente virtual ativo:\n\n```bash\npip install -r requirements.txt\n```\n\nPara o gráfico de PCA também é necessário:\n\n```bash\npip install scikit-learn\n```\n\n### Instalar DSSP\n\nO DSSP é um programa externo que determina a estrutura secundária a partir de\ncoordenadas atômicas. É necessário para as análises das etapas 4, 5 e 6.\n\n**macOS:**\n```bash\nbrew install brewsci/bio/dssp\n```\n\n**Ubuntu/Debian:**\n```bash\nsudo apt install dssp\n```\n\n**Manual:** https://swift.cmbi.umcn.nl/gv/dssp/\n\nVerifique a instalação:\n```bash\nwhich mkdssp   # deve retornar o caminho do executável\n```\n\n---\n\n## 3. Configuração\n\nToda a configuração está centralizada em `cath_analysis/config.py`. O único\nparâmetro que você **precisa editar** é o diretório base:\n\n```python\n# cath_analysis/config.py\nBASE_PATH = Path(\"/seu/caminho/para/cath\")\n```\n\nOs demais caminhos são derivados automaticamente:\n\n| Constante | Caminho padrão | Conteúdo |\n|---|---|---|\n| `STRUCTURES_PATH` | `BASE_PATH/structures/` | PDBs brutos baixados |\n| `STRUCTURES_CLEAN_PATH` | `BASE_PATH/structures_clean/` | PDBs limpos (cadeia A) |\n| `LOGS_PATH` | `BASE_PATH/logs/` | Relatórios e logs de erros |\n| `ANALYSIS_PATH` | `BASE_PATH/analysis/` | Gráficos e CSVs gerados |\n\n---\n\n## 4. Como executar\n\n### Recomendado: usar tmux\n\nA etapa 4 (DSSP unificado) leva 30-60 min no modo S40 ou 3-4h no dataset completo.\nUse **tmux** para deixar o pipeline rodando em background sem risco de o processo\nmorrer se o terminal for fechado.\n\n```bash\n# 1. Criar uma sessao tmux (apenas na primeira vez)\ntmux new -s evo-hex\n\n# 2. Dentro da sessao, ativar o ambiente virtual\nsource /Volumes/promethion/cath/.venv/bin/activate\n\n# 3. Entrar na pasta e rodar\ncd /Volumes/promethion/cath\npython main.py\n\n# 4. Para sair sem matar o processo: Ctrl+B, depois D\n#    O pipeline continua rodando em background.\n\n# 5. Para reconectar e ver o progresso (use sempre este comando ao voltar)\ntmux attach -t evo-hex\n```\n\n\u003e Se ao tentar criar a sessao aparecer `duplicate session: evo-hex`, significa que ela\n\u003e ja existe. Use diretamente `tmux attach -t evo-hex` para entrar nela.\n\n\u003e Instalar tmux: `brew install tmux` (macOS) ou `sudo apt install tmux` (Linux).\n\n### Fluxo básico\n\n```bash\n# Executa todas as 6 etapas com menus interativos\npython main.py\n```\n\n### Modo exploração (já tem a base baixada)\n\nSe você já baixou e limpou as estruturas, pule diretamente para a análise:\n\n```bash\npython main.py --explore\n```\n\nO pipeline detecta automaticamente dados existentes em todas as etapas. Ao re-executar,\nvocê será perguntado se deseja repetir cada etapa já concluída:\n\n```\n  Resultados existentes encontrados (gerados em 2025-11-08 15:44).\n\n  Re-executar análise de hélices (DSSP)? [s/N]\n```\n\nResponda `N` (ou Enter) para pular e usar os dados existentes. Isso permite retomar\no pipeline de onde parou sem re-executar etapas demoradas.\n\n\u003e **Importante:** a deteccao e por etapa completa. Se o pipeline for interrompido no\n\u003e meio de uma etapa (ex: Ctrl+C durante o DSSP), sera necessario re-executar essa\n\u003e etapa do zero - nao ha checkpoint parcial por arquivo.\n\n### Referência completa de flags\n\n| Comando | Descrição |\n|---|---|\n| `python main.py` | Pipeline completo, modo interativo |\n| `python main.py --explore` | Pula etapas 1-2, vai direto à análise |\n| `python main.py --steps 3 4 5` | Executa apenas as etapas especificadas |\n| `python main.py --force-download` | Re-baixa e relimpa sem perguntar |\n| `python main.py --skip-download` | Pula etapas 1-2 sem perguntar |\n| `python main.py --no-interactive` | Sem menus, executa tudo automaticamente |\n| `python main.py --full-dataset` | Baixa dataset completo (~50k) sem filtro S40 |\n| `python main.py --plots g3 g4` | Pré-seleciona grupos de gráficos no menu |\n| `python main.py --plots helical_wheel_average pca_aa_composition` | Pré-seleciona gráficos individuais |\n| `python main.py --list-plots` | Lista todos os 21 gráficos disponíveis e sai |\n\n### Exemplos práticos\n\n```bash\n# Primeiro uso: baixa tudo e analisa\npython main.py\n\n# Sessão de re-análise (dados já existem)\npython main.py --explore\n\n# Gerar só gráficos evolutivos e de código genético\npython main.py --explore --plots g3 g5 g6\n\n# Pipeline completo em servidor (sem interação)\npython main.py --no-interactive --force-download\n\n# Só baixar e limpar\npython main.py --steps 1 2\n\n# Ver o que pode plotar\npython main.py --list-plots\n```\n\n### Menu interativo de gráficos\n\nApós as etapas de análise, o menu aparece automaticamente:\n\n```\n═══════════════════════════════════════════════════════════════════\n  EVO-HEX - SELETOR DE GRAFICOS EVOLUTIVOS\n═══════════════════════════════════════════════════════════════════\n\n  1. Análise Básica de Hélices\n  ───────────────────────────────────────────────────────\n  [ ]  1. [DSSP]       Propensão para hélices (observada vs Chou-Fasman)\n  [ ]  2. [DSSP]       Preferência por posição na hélice\n  ...\n\n  Comandos:\n  \u003cnúmero\u003e      Selecionar/deselecionar gráfico\n  g\u003cnúmero\u003e     Selecionar/deselecionar grupo inteiro (ex: g3)\n  all           Selecionar todos\n  none          Desmarcar todos\n  info \u003cnum\u003e    Ver descrição detalhada\n  run           Gerar gráficos selecionados\n  q             Sair sem plotar\n```\n\n---\n\n## 5. Etapas do pipeline\n\n### Etapa 1: Download de estruturas\n\nBaixa o índice de domínios do CATH e faz download paralelo das estruturas PDB\nda classe Mainly-Alpha (classe 1) diretamente do RCSB.\n\nPor padrão aplica o **filtro S40** (subconjunto não-redundante), baixando apenas\n~2-5 mil estruturas representativas em vez das ~50 mil totais. Para o dataset\ncompleto use `--full-dataset`.\n\n- Fonte do índice CATH: `http://download.cathdb.info/...`\n- Fonte da lista S40: `http://download.cathdb.info/...`\n- Fonte dos PDBs: `https://files.rcsb.org/download/{}.pdb`\n- Download paralelo com até 20 workers simultâneos\n- Retoma automaticamente (pula arquivos já baixados)\n- Gera: `logs/download_report.txt`, `mainly_alpha_pdb_codes.txt`\n\n**Saída esperada:** ~2-5 mil arquivos `.pdb` em `structures/` (modo S40 padrão)\n\n### Etapa 2: Limpeza de estruturas\n\nProcessa cada PDB para remover ruído e padronizar o formato:\n\n- Mantém apenas o **modelo 0** (primeiro modelo em NMR)\n- Mantém apenas a **cadeia A**\n- Remove **heteroátomos** (HETATM): água, íons, ligantes, cofatores\n- Remove resíduos não-padrão (mantém apenas os 20 aminoácidos canônicos)\n- Estruturas sem cadeia A ou com 0 resíduos após limpeza são descartadas\n- Processamento paralelo com `ThreadPoolExecutor`\n\n**Saída esperada:** arquivos `.pdb` limpos em `structures_clean/`\n\n### Etapa 3: Frequência de aminoácidos\n\nConta a ocorrência de cada aminoácido em todas as estruturas limpas.\n\n- Contagem global e por estrutura\n- Gera: `amino_acid_frequencies_global.txt`, `amino_acid_frequencies_per_structure.csv`\n\n### Etapa 4: Passo DSSP unificado\n\n\u003e **Tempo estimado:** 30-60 min para ~2-5k estruturas S40 (7 workers paralelos).\n\u003e Para o dataset completo (~50k), espere 3-4h. Recomenda-se `tmux`/`screen`.\n\nPasso DSSP único e abrangente que **coleta todos os dados de uma vez** para as\nanálises das etapas 4, 5 e 6. Não há mais três passes separados sobre as\nestruturas — tudo é coletado em uma única varredura paralela.\n\nO que é coletado nessa etapa:\n\n- Propensão de cada AA para hélices (observada vs. Chou-Fasman)\n- Preferência por posição: N-terminal, meio, C-terminal\n- Classificação de hélices por tipo (H / G / I) e composição por tipo\n- Distribuição de comprimentos por tipo de hélice\n- Padrão heptad de hidrofobicidade\n- Sequências individuais de cada hélice (para momento hidrofóbico e helical wheel)\n- Preferências de N-cap e C-cap (primeiras/últimas 3 posições)\n- Distribuição completa de AAs por posição no heptad\n- Pares de transição entre tipos de hélice\n- Fração helicoidal por estrutura\n\nResultados salvos em `analysis/unified_report.txt` e nos CSVs de análise.\n\n### Etapa 5: Tipos de hélices (H/G/I)\n\n\u003e **Tempo estimado:** instantâneo (dados coletados na etapa 4).\n\nApresenta os dados de classificação de hélices já coletados na etapa 4:\n\n| Tipo DSSP | Nome | Ligação de H | Resíduos/volta |\n|---|---|---|---|\n| H | Alpha helix | i → i+4 | 3,6 |\n| G | 3-10 helix | i → i+3 | 3,0 |\n| I | Pi helix | i → i+5 | 4,4 |\n\n### Etapa 6: Dados evolutivos\n\n\u003e **Tempo estimado:** instantâneo (dados coletados na etapa 4).\n\nCarrega os dados evolutivos do pickle gerado pela etapa 4 e disponibiliza-os\npara os gráficos dos grupos 3, 4, 5 e 6.\n\n---\n\n## 6. Catálogo de análises e gráficos\n\n### Grupo 1: Análise Básica de Hélices\n\n#### 1.1 Propensão para hélices\n**Arquivo:** `helix_propensities.png`\n\nDois subplots:\n- **Barras duplas:** compara a propensão observada (calculada dos dados) com a\n  propensão teórica da escala de Chou-Fasman para cada aminoácido.\n- **Scatter:** frequência global do AA vs. frequência dentro de hélices, com linha\n  diagonal indicando ausência de enriquecimento.\n\n**Valor:** Revela quais AAs estão sobre- ou sub-representados em hélices.\nALA, GLU, LEU com propensão \u003e1.2 são os grandes formadores; GLY e PRO (\u003c0.6) são\ndisruptores. Desvios entre observado e Chou-Fasman indicam pressões específicas\ndo conjunto CATH.\n\n---\n\n#### 1.2 Preferência por posição na hélice\n**Arquivo:** `helix_positions.png`\n\nHeatmap 20×3 com a frequência de cada aminoácido no N-terminal, meio e C-terminal\nda hélice.\n\n**Valor:** Certas posições são estruturalmente mais restritivas. AAs com capacidade\nde fazer N-cap (ASN, ASP) aparecem enriquecidos no N-terminal. GLY é tolerado no\nC-terminal mas raramente no meio de hélices longas. Essa análise é base para\nidentificar restrições evolutivas posicionais.\n\n---\n\n#### 1.3 Distribuição de comprimentos\n**Arquivo:** `helix_lengths.png`\n\nHistograma + boxplot dos comprimentos de hélices em resíduos.\n\n**Valor:** Hélices alpha estáveis tendem a ter 10-20 resíduos. A distribuição\nde comprimentos reflete a pressão seletiva para manter a hélice coesa: hélices\nmuito curtas (4-6 res.) têm menor estabilidade térmica.\n\n---\n\n#### 1.4 Padrão heptad\n**Arquivo:** `heptad_pattern.png`\n\nFrequência de resíduos hidrofóbicos em cada posição do heptad repeat (a-g).\n\n**Valor:** Em coiled-coils, as posições *a* e *d* do heptad são hidrofóbicas para\nformar a interface entre as cadeias. Esse gráfico revela se o conjunto CATH\nMainly-Alpha exibe essa periodicidade, sugerindo presença de coiled-coils ou\nde pressão seletiva para periodicidade hidrofóbica.\n\n---\n\n### Grupo 2: Tipos de Hélices\n\n#### 2.1 Distribuição de tipos H/G/I\n**Arquivo:** `helix_type_distribution.png`\n\nBar chart e pie chart com a contagem e proporção de hélices Alpha (H), 3-10 (G)\ne Pi (I).\n\n**Valor:** Em proteínas globulares, \u003e90% das hélices são do tipo H. 3-10 helices\naparecem tipicamente nos terminais de hélices maiores ou em loops curtos. Pi helices\nsão raras (\u003c1%) e geralmente associadas a regiões funcionais. A proporção informa\no grau de diversidade estrutural do conjunto.\n\n---\n\n#### 2.2 Composição por tipo (heatmap)\n**Arquivo:** `helix_type_composition_heatmap.png`\n\nHeatmap 20×3 comparando a frequência de cada AA em H, G e I helices\nsimultaneamente.\n\n**Valor:** Permite identificar AAs diferencialmente enriquecidos por tipo. PRO,\npor exemplo, tende a ocorrer em 3-10 helices mais do que em alpha helices. Essas\ndiferenças refletem restrições geométricas distintas de cada tipo.\n\n---\n\n#### 2.3 Top-10 AAs por tipo\n**Arquivo:** `helix_type_top_amino_acids.png`\n\nBarras horizontais com os 10 AAs mais frequentes em cada tipo de hélice.\n\n---\n\n#### 2.4 Comprimento por tipo\n**Arquivo:** `helix_length_by_type.png`\n\nBoxplot + histograma sobrepostos comparando a distribuição de comprimentos entre H,\nG e I.\n\n**Valor:** 3-10 helices são estruturalmente limitadas a 3-6 resíduos pela geometria\nda ligação de hidrogênio i→i+3. Alpha helices são estáveis de 5 a \u003e30 resíduos.\nO gráfico quantifica essa distribuição no conjunto real.\n\n---\n\n#### 2.5 Comparação estatística Alpha vs. 3-10\n**Arquivo:** `helix_type_statistical_comparison.png`\n\nBarras de diferença de frequência e scatter direto Alpha vs. 3-10 para cada AA.\n\n**Valor:** Destaca os AAs com maior diferenciação entre os dois tipos. AAs\nenriquecidos em 3-10 (como PRO, GLY) são candidatos a estudos de transição\nevolutiva entre tipos de hélice.\n\n---\n\n### Grupo 3: Restrições Estruturais\n\n#### 3.1 Helical wheel composto\n**Arquivo:** `helical_wheel_average.png`\n\nProjeção polar: frequência de resíduos hidrofóbicos por posição angular na hélice.\nCada resíduo ocupa 100° em relação ao anterior, completando ~3,6 resíduos por volta.\nA escala de cores vai de azul (polar) a vermelho (hidrofóbico).\n\n**Valor:** Revela a **anfipatiticidade** do conjunto. Em hélices anfipáticas\nfuncionais (e.g., hélices de membrana, hélices de ligação a lipídeos), um setor\nangular claro com alta frequência hidrofóbica deve emergir. A ausência desse padrão\nindica que o conjunto é dominado por hélices de interior proteico com distribuição\nuniforme. É uma das análises mais diretas de restrição estrutural evolutiva.\n\n---\n\n#### 3.2 Momento hidrofóbico de Eisenberg\n**Arquivo:** `hydrophobic_moment_distribution.png`\n\nDistribuição do momento hidrofóbico (μH) por hélice, calculado pela escala de\nEisenberg. Hélices são classificadas em anfipáticas baixas (\u003c0,2), médias (0,2-0,4)\ne altas (≥0,4).\n\n**Valor:** O momento hidrofóbico é um preditor de função. Hélices com μH alto são\nassociadas a: inserção em membranas, interação com lipídeos, atividade antimicrobiana.\nA distribuição do μH no conjunto CATH informa a proporção de hélices funcionalmente\nanfipáticas vs. estruturalmente internas.\n\n---\n\n#### 3.3 N-cap e C-cap (3 posições)\n**Arquivo:** `ncap_ccap_preferences.png`\n\nHeatmaps das frequências de AAs nas 3 primeiras posições da hélice (N1, N2, N3)\ne nas 3 últimas (C3, C2, C1).\n\n**Valor:** As posições de *cap* têm preferências fortíssimas sob seleção purificadora:\n- **N-cap:** ASN e ASP são enriquecidos porque fazem ligações de hidrogênio com\n  os NH da hélice não satisfeitos pelas posições iniciais.\n- **C-cap:** GLY é favorecido pela flexibilidade que permite a curvatura da cadeia\n  ao sair da hélice.\n\nDesvios dessas preferências podem indicar hélices com funções especiais ou pressões\nevolutivas distintas (e.g., hélices de proteínas termófilas).\n\n---\n\n### Grupo 4: Composição e Variabilidade\n\n#### 4.1 PCA da composição por estrutura\n**Arquivo:** `pca_aa_composition.png`\n\nCada proteína é representada como um vetor de 20 frequências (uma por AA), reduzido\npara 2 dimensões por PCA. Pontos são coloridos pelo AA dominante.\n\n**Valor:** Agrupa proteínas por \"assinatura\" de composição. Estruturas funcionalmente\nrelacionadas devem agrupar. Outliers revelam proteínas com composição incomum.\nPC1 tipicamente captura a variação hidrofóbico/hidrofílico; PC2 captura outros\ngradientes físico-químicos. Requer `scikit-learn`.\n\n---\n\n#### 4.2 Distribuição de conteúdo helicoidal\n**Arquivo:** `helix_content_distribution.png`\n\nHistograma + violin plot da fração de resíduos em hélice por proteína.\n\n**Valor:** Embora todas as proteínas sejam da classe Mainly-Alpha, a distribuição\nde conteúdo helicoidal varia significativamente. Proteínas com \u003e80% são casos\nextremos (e.g., hélices de membrana). A distribuição real quantifica a heterogeneidade\nda classe e pode ser comparada com outras classes CATH como referência evolutiva.\n\n---\n\n#### 4.3 Co-ocorrência de AAs em hélices\n**Arquivo:** `aa_cooccurrence.png`\n\nHeatmap 20×20 onde cada célula representa a frequência relativa de pares de AAs\nque aparecem juntos na mesma hélice.\n\n**Valor:** Pares com alta co-ocorrência podem refletir:\n- **Interações físicas:** GLU-LYS e ASP-ARG formam salt bridges (i→i+4) que\n  estabilizam hélices.\n- **Perfis evolutivos compartilhados:** AAs com propensão similar tendem a ser\n  trocados por mutação e co-ocorrem mais.\n- **Viés composicional:** LEU e ALA co-ocorrem simplesmente por serem os mais\n  frequentes.\n\nA análise deve ser interpretada com baseline de frequência esperada (produto das\nfrequências marginais).\n\n---\n\n#### 4.4 Comprimento vs. composição\n**Arquivo:** `helix_length_vs_composition.png`\n\nBarras agrupadas: frequência de cada grupo físico-químico (hidrofóbico, polar,\ncarregado+, carregado-, especial) em hélices curtas (4-9 res.), médias (10-19)\ne longas (≥20).\n\n**Valor:** Hélices longas tendem a ser mais ricas em AAs de alta propensão (ALA,\nLEU, GLU). Hélices curtas toleram mais GLY e PRO. Essa relação comprimento-composição\né uma evidência direta de seleção estrutural: AAs disruptores são tolerados apenas\nem contextos curtos onde a hélice não precisa ser mantida por muitos resíduos.\n\n---\n\n### Grupo 5: Transições e História Evolutiva\n\n#### 5.1 Matriz de transição H→G→I\n**Arquivo:** `helix_transition_matrix.png`\n\nHeatmap normalizado com a probabilidade de cada tipo de hélice ser seguido por\noutro tipo dentro da mesma proteína.\n\n**Valor:** Revela se existe uma hierarquia de transições. A hipótese evolutiva é\nque 3-10 helices são estados ancestrais ou transicionais de alpha helices, proteínas\nque \"experimentam\" hélices mais curtas antes de estabilizar em alpha. Uma alta taxa\nde H→G seguida de G→H indicaria coexistência de ambos os tipos no mesmo contexto\nestrutural.\n\n---\n\n#### 5.2 Razão 3-10/(H+G+I) por comprimento\n**Arquivo:** `g_ratio_by_length.png`\n\nLinha com a fração de hélices 3-10 em cada comprimento. Barra cinza de fundo mostra\no total de hélices por comprimento.\n\n**Valor:** Testa diretamente a hipótese de que hélices curtas são predominantemente\n3-10. Se a curva cai monotonicamente com o comprimento, confirma a restrição\ngeométrica: hélices longas simplesmente não conseguem manter a geometria 3-10.\nPicos em comprimentos específicos podem indicar contextos estruturais especiais.\n\n---\n\n#### 5.3 Entropia de Shannon por posição do heptad\n**Arquivo:** `shannon_entropy_heptad.png`\n\nEntropia de Shannon calculada a partir da distribuição de AAs em cada posição (a-g)\ndo heptad. Baixa entropia = maior conservação = maior pressão seletiva.\n\n**Valor:** Em coiled-coils clássicos, posições *a* e *d* têm baixa entropia\n(dominadas por LEU, ILE, VAL) enquanto posições *b*, *c*, *e*, *f*, *g* têm alta\nentropia (qualquer AA). A assinatura heptad de entropia é um indicador da proporção\nde coiled-coils no conjunto e da magnitude da seleção nessas posições.\n\n---\n\n### Grupo 6: Viés do Código Genético\n\n#### 6.1 Degenerescência de códons vs. propensão\n**Arquivo:** `codon_degeneracy_vs_propensity.png`\n\nDois scatters lado a lado:\n- Número de códons do AA (degenerescência) vs. propensão teórica (Chou-Fasman)\n- Número de códons vs. propensão observada no conjunto CATH\n\n**Valor:** Permite separar dois mecanismos distintos de composição:\n- **Seleção estrutural:** AAs com alta propensão são favorecidos pela geometria da hélice.\n- **Deriva neutra / viés mutacional:** AAs com mais códons (LEU=6, SER=6) ocorrem\n  mais por pura probabilidade mutacional.\n\nSe a correlação propensão×códons é fraca, a composição das hélices é dominada por\nseleção. Se é forte, o viés do código genético tem papel relevante, uma questão aberta\naberta em evolução molecular.\n\n---\n\n#### 6.2 Enriquecimento vs. proteoma humano\n**Arquivo:** `proteome_comparison.png`\n\nDois subplots:\n- **Barras:** razão Observado/Proteoma (\u003e1 = enriquecido em hélices, \u003c1 = depleto)\n- **Scatter:** frequência no proteoma humano de referência vs. frequência observada\n\nFrequências de referência: proteoma humano médio (UniProt/Swiss-Prot).\n\n**Valor:** Normaliza a composição das hélices pelo background proteômico. Um AA\npode ser frequente nas hélices simplesmente porque é frequente em proteínas em geral\n(caso do LEU). O enriquecimento real (controlando pelo background) revela a\nseleção verdadeira. ALA com enriquecimento \u003e1.3 e PRO com \u003c0.5 são esperados;\ndesvios desses valores indicam particularidades da classe Mainly-Alpha.\n\n---\n\n## 7. Estrutura de arquivos gerados\n\n```\nBASE_PATH/\n├── cath-domain-list.txt              # Índice CATH baixado\n├── cath-s40-domains.txt              # Lista S40 não-redundante\n├── mainly_alpha_pdb_codes.txt        # Códigos PDB da classe 1 (filtrados S40)\n│\n├── structures/                       # Etapa 1: PDBs brutos\n│   ├── 1abc.pdb\n│   └── ...\n│\n├── structures_clean/                 # Etapa 2: PDBs limpos\n│   ├── 1abc.pdb                      # Apenas cadeia A, sem heteroátomos\n│   └── ...\n│\n├── logs/\n│   ├── download_report.txt\n│   ├── failed_downloads.txt\n│   ├── cleaning_report.txt\n│   ├── no_chain_a.txt\n│   └── cleaning_errors.txt\n│\n└── analysis/\n    ├── amino_acid_frequencies_global.txt\n    ├── amino_acid_frequencies_per_structure.csv\n    │\n    ├── unified_report.txt            # Relatório do passo DSSP unificado\n    ├── helix_propensities.csv\n    ├── helix_positions.csv\n    ├── helix_lengths.csv\n    ├── helix_lengths_by_type.csv\n    ├── helix_type_composition.csv\n    ├── helix_type_top_residues.csv\n    ├── helix_type_statistical_comparison.csv\n    ├── codon_degeneracy.csv\n    ├── proteome_comparison.csv\n    ├── evo_data.pkl                  # Dados evolutivos (momento, heptad, caps...)\n    │\n    └── *.png                         # 21 gráficos gerados\n```\n\n---\n\n## 8. Estrutura do código\n\n```\ncath/\n├── main.py                           # Ponto de entrada (CLI)\n├── requirements.txt\n│\n└── cath_analysis/\n    ├── __init__.py\n    ├── config.py                     # Constantes e caminhos\n    ├── downloader.py                 # Etapa 1: download CATH + PDB (com filtro S40)\n    ├── cleaner.py                    # Etapa 2: limpeza PDB\n    ├── frequency_analysis.py         # Etapa 3: frequência de AAs\n    ├── unified_dssp.py               # Etapa 4: passo DSSP único (coleta tudo)\n    ├── evolutionary_analysis.py      # Funções de cálculo evolutivo (momento, entropia...)\n    ├── plotting.py                   # Todas as 21 funções de visualização\n    └── menu.py                       # Menu interativo de seleção de gráficos\n```\n\n### Dependências entre módulos\n\n```\nconfig.py ←── todos os módulos\ndownloader.py ──→ Etapa 1\ncleaner.py ──────→ Etapa 2\nfrequency_analysis.py ──→ Etapa 3 → PCA (plotting)\nunified_dssp.py ─────────→ Etapa 4 → dados para etapas 5 e 6\nevolutionary_analysis.py → cálculos sobre evo_data → plotting\nmenu.py ──────────────────────────────→ main.py\n```\n\n---\n\n## 9. Dependências externas\n\n| Pacote | Versão mínima | Uso |\n|---|---|---|\n| `biopython` | 1.81 | Parser PDB, DSSP, seleção de cadeias |\n| `numpy` | 1.24 | Cálculos numéricos |\n| `pandas` | 2.0 | DataFrames de resultados |\n| `matplotlib` | 3.7 | Visualizações |\n| `seaborn` | 0.12 | Heatmaps e estilos |\n| `requests` | 2.28 | Download de PDBs |\n| `tqdm` | 4.65 | Barras de progresso |\n| `scipy` | 1.11 | (reservado para extensões) |\n| `scikit-learn` | - | Opcional: PCA (etapa 4.1) |\n| `mkdssp` | - | Externo: estrutura secundária |\n\n---\n\n## 10. Perguntas frequentes\n\n**Q: O download trava em alguns PDBs. É normal?**\n\nSim. Alguns códigos PDB foram obsoletados ou renomeados no RCSB. O pipeline marca\nesses casos como `error` e continua. Os códigos que falharam ficam em\n`logs/failed_downloads.txt`.\n\n---\n\n**Q: DSSP falha em várias estruturas. Por quê?**\n\nDSSP requer que os átomos backbone (N, Cα, C, O) estejam presentes e com distâncias\nrazoáveis. Estruturas com resolução muito baixa, modelos incompletos ou erros de\nmodelagem podem falhar. O pipeline registra e pula essas estruturas.\n\n---\n\n**Q: O mkdssp mostra \"parse error at line 1: This file does not seem to be an mmCIF file\". E um problema?**\n\nNao. O mkdssp 4.x aceita arquivos PDB mas emite esse aviso no stderr porque espera mmCIF\npor padrao. O BioPython 1.84+ ja trata isso automaticamente passando `--output-format=dssp`\nao detectar mkdssp \u003e= 4.0. O pipeline suprime o aviso e processa normalmente.\n\n---\n\n**Q: Posso usar estruturas de outra fonte (não CATH)?**\n\nSim. Basta colocar os PDBs limpos (cadeia A, sem heteroátomos) em\n`structures_clean/` e executar a partir da etapa 3:\n\n```bash\npython main.py --steps 3 4 5 6\n```\n\n---\n\n**Q: O PCA não está disponível.**\n\nInstale o `scikit-learn`:\n```bash\npip install scikit-learn\n```\n\n---\n\n**Q: A limpeza mostra o dobro de estruturas esperadas (ex: 101.978 em vez de ~51.000). Por que?**\n\nIsso ocorre quando o diretório `structures/` ja contem arquivos de execucoes anteriores\ndo pipeline (ou do notebook original) no momento em que um novo download e iniciado.\nO cleaner processa todos os PDBs presentes, independente da origem.\n\nWorkaround atual: remova manualmente o diretório antes de rodar:\n```bash\nrm -rf /Volumes/promethion/cath/structures/\npython main.py\n```\n\n**Bug conhecido (a corrigir):** o flag `--force-download` deveria limpar o diretório\n`structures/` antes de iniciar o novo download, garantindo que apenas as estruturas\nda sessão atual sejam processadas.\n\n---\n\n**Q: Como citar o CATH?**\n\n\u003e Sillitoe I. et al. (2021). CATH: expanding the horizons of structure-based\n\u003e functional annotations for genome sequences. *Nucleic Acids Research*, 49(D1),\n\u003e D377-D385. https://doi.org/10.1093/nar/gkaa1079\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadsondeluna%2Fevo-hex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmadsondeluna%2Fevo-hex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmadsondeluna%2Fevo-hex/lists"}