Primeiros passos

Onboarding prático para tecnólogos. Setup, um exemplo real de ponta a ponta, e para onde ir depois.

TL;DR

Em cerca de 30 minutos você sai de uma máquina limpa para uma consulta real ao NCI Genomic Data Commons (GDC) — um portal público de pesquisa em câncer — e a um conjunto pequeno de dados que pode analisar localmente. Esta página percorre o caminho mínimo. Ela não tenta te ensinar biologia do câncer em 5 minutos; isso é função das seções Fundamentos e Ômicas.

Status do projeto

HackCancer é uma versão pública inicial. APIs mudam. PRs e issues bem-vindos em github.com/hack-cancer. Para o estado atual e como ajudar hoje, veja Status do projeto.

---

1. O que você de fato precisa

Ferramenta	Para quê	Versão mínima
Python	rodar exemplos, pipelines	3.8+
Git	clonar o repo, contribuir de volta	qualquer recente
Um terminal	bash, zsh, PowerShell, Windows Terminal	—
Node.js (opcional)	só se quiser rodar o site local	20+
Docker (opcional)	para fluxos em container depois	—

Se você só quer ler a documentação, não precisa de nada — o site está no ar. Se quer rodar exemplos, precisa de Python e Git.

---

2. Setup (5 minutos)

# 1. Clonar
git clone https://github.com/hack-cancer/Hack-Cancer.git
cd Hack-Cancer

# 2. Ambiente virtual Python
python -m venv venv
# macOS/Linux:
source venv/bin/activate
# Windows:
venv\Scripts\activate

# 3. Instalar dependências dos exemplos
pip install -r src/requirements.txt

Se pip install falhar no seu sistema, o mínimo necessário para o exemplo abaixo é:

pip install requests pandas

---

3. Sua primeira consulta real (10 minutos)

O ponto desta seção é levar você a um resultado real contra dados reais de câncer, não a um brinquedo. O snippet abaixo é auto-contido — não precisa ter clonado o repo antes.

Ele consulta o endpoint /cases do GDC por casos de câncer de mama (projeto TCGA-BRCA), retorna 20 e mostra demografia. A API do GDC é pública, bem documentada e não exige autenticação para dados abertos. Fontes: [1]

# gdc_quickstart.py
import json
import requests
import pandas as pd

API = "https://api.gdc.cancer.gov/cases"

# Filtro: casos do projeto TCGA-BRCA (câncer de mama)
filters = {
    "op": "in",
    "content": {"field": "cases.project.project_id", "value": ["TCGA-BRCA"]},
}

params = {
    "filters": json.dumps(filters),
    "fields": "submitter_id,project.project_id,primary_site,"
              "demographic.gender,demographic.age_at_index",
    "format": "json",
    "size": "20",
}

r = requests.get(API, params=params, timeout=30)
r.raise_for_status()
hits = r.json()["data"]["hits"]

rows = []
for c in hits:
    demo = c.get("demographic") or {}
    if isinstance(demo, list):
        demo = demo[0] if demo else {}
    rows.append({
        "submitter_id": c["submitter_id"],
        "project": c["project"]["project_id"],
        "site": c.get("primary_site"),
        "gender": demo.get("gender"),
        "age_at_index": demo.get("age_at_index"),
    })

df = pd.DataFrame(rows)
print(df.head())
print(f"\nDistribuição por gênero:\n{df['gender'].value_counts(dropna=False)}")
ages = pd.to_numeric(df['age_at_index'], errors='coerce')
print(f"\nIdade média ao diagnóstico: {ages.mean():.1f} anos")

Rodar:

python gdc_quickstart.py

O que você deve ver

Uma tabela similar a esta (os IDs exatos variam conforme o GDC evolui):

   submitter_id    project        site  gender  age_at_index
0  TCGA-AR-A1AR  TCGA-BRCA      Breast  female            61
1  TCGA-A2-A0CL  TCGA-BRCA      Breast  female            55
2  TCGA-BH-A0BO  TCGA-BRCA      Breast  female            58
3  TCGA-AC-A2FB  TCGA-BRCA      Breast    male            66
4  TCGA-E2-A14P  TCGA-BRCA      Breast  female            48

Distribuição por gênero:
female    19
male       1

Idade média ao diagnóstico: 58.4 anos

O que aconteceu:

• Você pediu ao GDC metadados clínicos públicos de casos de câncer de mama da coorte TCGA-BRCA.
• Recebeu um pandas.DataFrame pequeno, com uma linha por caso.
• Fez um sanity check (predomínio feminino, idade média na faixa esperada para câncer de mama).
• Nenhum dado saiu do domínio público. Sem PHI. Sem login.

Esta é a menor consulta não-trivial. A partir daqui você puxa mutações, expressão gênica, número de cópias, arquivos etc. — tudo público.

---

4. O exemplo expandido neste repositório

src/examplesapi/gdc_data_access.py traz um script mais completo, com três etapas:

1. Buscar — lista casos em TCGA-BRCA com demografia.
2. Mutações — consulta /ssms por mutações somáticas no primeiro caso.
3. Arquivos — lista arquivos de quantificação RNA-seq da coorte.

Para rodar:

cd src/examplesapi
python gdc_data_access.py

O script usa os mesmos endpoints públicos do GDC; a estrutura de saída segue o contrato da API.Se um problema de rede ou proxy bloquear as chamadas, você verá um RequestException — o snippet do §3 é o fallback mais simples. Fontes: [1]

---

5. Depois de rodar o exemplo — para onde ir

Escolha o que combina com o que você quer fazer a seguir:

Você quer…	Leia
Entender o que câncer é de fato	O que é câncer?
Entender as camadas de dado (DNA, RNA, proteína…)	Visão geral de ômicas
Puxar coortes de paciente e analisar	Dados e APIs, Exemplos
Processar dados brutos de sequenciamento	De FASTQ a variantes
Fazer modelos, mas com responsabilidade	Armadilhas de ML em oncologia, Visão geral de IA & ML
Conhecer o arcabouço legal e ético	Limites e responsabilidade, Regulação e ética, Governança e LGPD
Por que o projeto existe	Missão

---

6. Rodar o site da documentação localmente (opcional)

Para pré-visualizar suas edições:

# Requer Node 20+
npm ci
npm run docs:dev

Abra o URL impresso no terminal (em geral http://localhost:5173). A versão em português fica em /pt-br/.

Para gerar o site estático:

npm run docs:build

Saída em docs/.vitepress/dist.

---

7. Armadilhas comuns

• Erros de rede contra api.gdc.cancer.gov — proxies corporativos e algumas redes locais podem precisar de configuração de proxy. Teste de uma rede pessoal primeiro para isolar.
• Versões de Python incompatíveis — o virtualenv fixa o python com que foi criado; cheque python --version dentro dele.
• Avisos de versão do pandas — em geral inofensivos; fixe versão em requirements.txt se precisar de estabilidade.
• Tratar metadados do GDC como identidade do paciente — não são, mas trate dados baixados com a mesma higiene de qualquer dado de saúde.

---

Veja também

• Status do projeto — o que está pronto, o que não está, e como ajudar hoje
• Missão — o porquê
• Limites e responsabilidade — o que o HackCancer não é
• Roadmap — direção sem promessas
• Contato — quando precisa falar com gente

---

Referências

1. Documentação da API do NCI Genomic Data Commons. https://docs.gdc.cancer.gov/API/Users_Guide/Getting_Started/ — pública, sem autenticação para dados abertos.