Usando o PlanetHunter¶
Nesta página você vai aprender
- Instalar o PlanetHunter e conferir que ele funciona.
- O que faz cada comando, quando usar e o que ele imprime.
- Rodar seu primeiro setor do TESS, em escala pequena, do download ao alerta simulado.
- Onde ficam os arquivos e como configurar alertas no Telegram com segurança.
Este é o manual de bolso da ferramenta. Ele usa o vocabulário das aulas: sinal (queda periódica achada na busca), candidato (sinal novo que passou no vetting), dossiê (relatório HTML de um sinal). Se um termo parecer estranho, consulte o glossário.
Instalação¶
Você precisa do uv e do Git. Se ainda não instalou, siga o passo a passo da trilha de programação. Abra o PowerShell (no VS Code: Terminal > New Terminal) e rode:
Se você recebeu a pasta do projeto de outra forma, basta entrar nela com cd e rodar uv sync.
uv sync lê o arquivo pyproject.toml, baixa o Python 3.12 se faltar e instala todas as bibliotecas numa pasta .venv dentro do projeto. Leva alguns minutos na primeira vez.
O cálculo de FPP (probabilidade de falso positivo, aula A3) usa a biblioteca triceratops, que exige versões antigas do NumPy. Por isso ela mora num ambiente separado:
Confira a instalação:
O primeiro mostra a lista de comandos. O segundo roda os testes automáticos, sem internet, em cerca de 45 segundos. Tudo verde: pronto.
Sempre uv run na frente
uv run planethunter ... garante que o comando usa o Python e as bibliotecas do projeto. Rode sempre de dentro da pasta planethunter. Qualquer comando aceita --help, por exemplo uv run planethunter search --help.
Mapa dos comandos¶
O pipeline tem 8 passos (guia, seção 1). Cada comando cobre um ou mais deles.
| Comando | Passo | Usa internet? | Quando usar |
|---|---|---|---|
mirrors sync / mirrors status |
0. Espelhos | sync: sim | Antes de qualquer crossmatch; status quando quiser conferir |
ingest sector / ingest target |
1. Ingestão | sim | Baixar curvas de luz |
search |
2 e 3. Limpeza e busca | não | Procurar sinais nas curvas já baixadas |
crossmatch |
4. "Já existe?" | não | Depois de search |
vet |
5. Vetting básico | não | Depois de crossmatch |
vet-deep |
6. Vetting aprofundado | sim | Para os candidatos que passaram em vet |
candidates |
7 | não | Ver a fila de candidatos |
dossier |
7 | não | Gerar o relatório de um sinal |
alert |
7 | só com --send |
Gerar dossiês e alertar P0/P1 |
review |
depois do 7 | não | Registrar sua decisão sobre um candidato |
run-target |
1 a 4 | sim | Estudar uma estrela só, ponta a ponta |
run-sector |
0 a 7 | sim | Rodar tudo num setor |
benchmark build / benchmark run |
medição | sim | Medir o recall antes e depois de mudar algo |
A regra do projeto é: nada de internet no caminho crítico da busca. Os comandos search, crossmatch e vet trabalham só com cópias locais.
Cada comando¶
mirrors sync e mirrors status¶
sync baixa as cinco listas de objetos conhecidos: NASA Exoplanet Archive, TOIs e CTOIs do ExoFOP, exoplanet.eu e o catálogo de binárias eclipsantes do TESS. O exoplanet.eu leva alguns minutos. status mostra a idade de cada cópia:
archive_pscomppars ok idade= 4.1 h linhas=6445
exoplanet_eu ok idade= 4.1 h linhas=8354
toi ok idade= 4.1 h linhas=8151
ctoi ok idade= 4.1 h linhas=5138
eb_catalog ok idade= 3.9 h linhas=4584
VELHO quer dizer mais de 48 horas. AUSENTE, que a cópia não existe. Nos dois casos, nenhum sinal pode ser classificado como NEW: ele vira UNVERIFIED e não gera alerta.
ingest sector e ingest target¶
uv run planethunter ingest sector 69 --limit 200
uv run planethunter ingest sector 69 --tics 100100827,261136679
uv run planethunter ingest target 261136679 --sectors 1,4,8
ingest sector baixa as curvas SPOC de 2 minutos de um setor. Opções: --limit N (só os N primeiros alvos, para testes), --tics (lista de TICs separados por vírgula, sem espaços) e --workers (downloads simultâneos, padrão 8; seja gentil com o MAST). ingest target baixa todos os setores de uma estrela, ou só os de --sectors.
Arquivos já baixados são pulados. Ao fim aparece um resumo com as contagens ok, skipped (pulados) e errors. Erros de um alvo não derrubam os outros; os primeiros são listados como ERRO.
search¶
Limpa as curvas, remove a variação lenta da estrela e roda a busca TLS em paralelo. Você precisa informar --sector ou --tics. Outras opções: --all-sectors (junta todos os setores de cada alvo), --workers (processos em paralelo; o padrão usa todos os núcleos menos um) e --resume <run_id> (retoma uma busca interrompida, pulando os alvos já feitos).
A saída é uma linha:
Guarde o run_id. Ele identifica a execução e é a entrada dos próximos comandos. O formato é data e hora em UTC, o modo (single para um setor, multi para vários) e o setor (s69, ou sx quando são vários).
crossmatch¶
Compara cada sinal com os espelhos e imprime quantos caíram em cada classe: NEW, KNOWN_PLANET, KNOWN_TOI, KNOWN_CTOI, KNOWN_FP, NEARBY_KNOWN ou UNVERIFIED (guia, passo 4). Muitos NEW é normal: quase todos são ruído ou defeito que nenhum catálogo registra.
vet¶
Roda os testes do vetting básico, sem internet, nos sinais com SDE de pelo menos 9. Depois usa a classe do crossmatch para promover a candidatos só os sinais NEW aprovados. Imprime três coisas: quantos sinais foram testados; a tabela de validação (colunas classe, n, pass, taxa_pass, falhas_comuns, vetos); e quantos candidatos ficaram por severidade, como candidatos: 3 {'P2': 3}.
Use a tabela de validação como termômetro. KNOWN_PLANET deve passar cerca de 80 %. KNOWN_FP deve passar pouco. Se isso mudar muito, algo no vetting mudou.
vet-deep¶
O vetting aprofundado, só para os candidatos: imagem-diferença nos pixels (TPF), vizinhos e binárias do Gaia, tipo da estrela no SIMBAD, presença do sinal em outros setores e FPP com triceratops. Usa internet e guarda o que baixa em data/cache/. O FPP leva cerca de 6 minutos por candidato. Sem run_id, processa todos os candidatos do banco. Imprime signal_id, verdict, score e failed de cada um.
candidates¶
Mostra a fila de candidatos NEW que passaram no vetting, do mais forte ao mais fraco. Sem run_id, mostra os de todos os runs. Candidatos que você rejeitou com review saem da lista. Cada coluna (severity, period_d, rp_rearth, score, failed...) está explicada na seção 4 do guia.
dossier¶
Gera o dossiê HTML de um sinal e imprime o caminho, no formato data/dossiers/tic<TIC>_sig<signal_id>.html. Abra no navegador. Como ler cada seção: guia, seção 4, e aula M5.
alert¶
uv run planethunter alert 20261009T204130Z-single-s69
uv run planethunter alert 20261009T204130Z-single-s69 --send
Gera o dossiê de cada candidato e prepara a mensagem dos que são P0 ou P1. Sem --send, nada sai do seu computador: as mensagens vão para data/outbox/AAAA-MM-DD.md. Com --send, vão para Telegram ou Discord, se configurados (veja abaixo).
Antes de enviar, o comando confere tudo de novo e pula o sinal se: algum espelho estiver velho; a classe deixou de ser NEW; ou o mesmo alvo, com o mesmo período, já foi alertado nos últimos 30 dias. P2 nunca gera alerta imediato. Cada linha impressa diz o sinal, o canal e o resultado, como signal 1071: outbox dry_run.
review¶
uv run planethunter review <signal_id> rejected --reason sistematico --note "ausente nos setores 67, 68 e 97"
uv run planethunter review <signal_id> follow_up --note "sem outros setores; esperar novos dados"
uv run planethunter review <signal_id> approved
Registra sua decisão. O estado é approved, rejected ou follow_up. Rejeitar exige --reason: eb (binária eclipsante), blend (contaminação por vizinha), sistematico (defeito instrumental), ruido, ja_conhecido ou outro. --note é texto livre. Suas decisões viram exemplos de treino para um futuro classificador (aula A4).
run-target¶
uv run planethunter run-target 261136679
uv run planethunter run-target 100100827 --sectors 69
uv run planethunter run-target 261136679 --skip-ingest
Faz ingestão, busca juntando todos os setores da estrela que estão no disco, crossmatch e vetting básico, e gera um dossiê para cada sinal com SDE ≥ 9. Imprime o run_id, uma tabela com cada sinal (signal_id, período, t0_btjd, profundidade, duração, sde, snr, n_transits, classe do crossmatch, objeto casado, veredito e score do vetting) e o caminho de cada dossiê. --sectors limita a ingestão (setores já baixados antes continuam entrando na busca); --skip-ingest usa só o que já está no disco. O vetting aprofundado não roda aqui. Se aparecer AVISO: espelhos ausentes ou velhos, rode mirrors sync.
Bom para estudar estrelas com planetas conhecidos, como Pi Mensae (TIC 261136679, aula B5) e WASP-18 (TIC 100100827, aula P3).
run-sector¶
Tudo ponta a ponta: sincroniza os espelhos se algum estiver perto de vencer, baixa, busca, faz crossmatch, vetting básico, vetting aprofundado dos candidatos, dossiês e alertas. Opções: --limit, --skip-ingest e --send (sem ele, alertas só vão para data/outbox/).
benchmark build e benchmark run¶
build baixa a lista de TOIs do ExoFOP e congela os do setor com SNR de pelo menos --min-snr (padrão 10) e período até 13 dias, em data/benchmark/sector_0069.csv. Com --kind fp, congela os falsos positivos do TFOPWG. run baixa esses alvos, busca e mede o recall: quantos dos TOIs conhecidos o sistema reencontra. Opções: --workers, --skip-ingest e --run <run_id> (avalia um run existente). O relatório vai para docs/benchmarks/ e o detalhe para data/benchmark/result_<run_id>.csv. No setor 69, o recall medido foi 91,1 % (123 de 135 TOIs detectáveis).
Use o benchmark antes e depois de qualquer mudança em config/thresholds.yaml (aula A5).
Roteiro: meu primeiro setor¶
Vamos rodar o setor 69 com só 200 estrelas, passo a passo. Leva poucos minutos.
uv run planethunter mirrors sync
uv run planethunter mirrors status # tudo "ok"?
uv run planethunter ingest sector 69 --limit 200 # baixa 200 curvas
uv run planethunter search --sector 69 # anote o run_id
uv run planethunter crossmatch <run_id>
uv run planethunter vet <run_id>
uv run planethunter candidates <run_id>
uv run planethunter dossier <signal_id> # para cada candidato que quiser ver
uv run planethunter alert <run_id> # simulação em data/outbox/
Troque <run_id> e <signal_id> pelos valores impressos. Atenção: search --sector 69 busca em todas as curvas do setor 69 que já estão no disco, não só nas 200 últimas.
Se preferir, o atalho é uv run planethunter run-sector 69 --limit 200. Mas faça o passo a passo pelo menos uma vez: você vê o que cada etapa produz.
O que esperar. Muitos sinais, quase todos NEW ou KNOWN_*, e talvez nenhum candidato. É o resultado mais comum. Na primeira fatia real do projeto, 2 164 estrelas do setor 69 deram 887 sinais, 648 NEW, 11 aprovados no vetting básico e, depois do vetting aprofundado, 0 P1 e 3 P2. Cada etapa elimina o que não se sustenta.
Na ferramenta
Todos os comandos desta página estão em src/planethunter/cli.py. Cada um tem poucas linhas e chama funções de src/planethunter/pipeline.py. Depois da aula P1, abra o arquivo e procure, por exemplo, def run_target: você vai ver a mesma sequência ingestão, busca e crossmatch descrita acima.
Onde ficam os arquivos¶
| Caminho | Conteúdo |
|---|---|
data/parquet/ |
Curvas de luz, uma por estrela e setor (cerca de 0,5 MB cada) |
data/mirrors/ |
Cópias dos catálogos |
data/planethunter.duckdb |
Banco com sinais, crossmatch, vetting, candidatos e alertas |
data/dossiers/ |
Dossiês HTML |
data/outbox/ |
Alertas simulados, um arquivo por dia |
data/cache/ |
Pixels, Gaia e FPP baixados pelo vet-deep |
data/benchmark/ |
Listas congeladas e resultados do benchmark |
config/thresholds.yaml |
Todos os limites, cada um com o porquê |
A pasta data/ não vai para o Git. Um setor inteiro tem cerca de 20 000 estrelas; nas 2 164 do teste, os Parquet ocuparam cerca de 1 GB. Para guardar os dados em outro disco, defina a variável PLANETHUNTER_DATA antes dos comandos: $env:PLANETHUNTER_DATA = "D:\planethunter-dados". Ela vale para aquele terminal.
Para ler os Parquet e o banco em Python, veja a aula P3.
Alertas no Telegram¶
- No Telegram, converse com @BotFather, envie
/newbote siga as instruções. Ele devolve um token, uma senha do seu bot. - Mande qualquer mensagem para o seu bot novo.
- No navegador, abra
https://api.telegram.org/bot<TOKEN>/getUpdates, trocando<TOKEN>pelo seu. Procure"chat":{"id":e anote o número: é o seu chat id. - No VS Code, crie na raiz do projeto um arquivo chamado exatamente
.env:
Para Discord, acrescente DISCORD_WEBHOOK= com o endereço do webhook do canal. Depois rode alert ou run-sector com --send. Só candidatos P0 ou P1 geram mensagem.
Cuidados¶
O arquivo .env é secreto
Quem tem o token controla o seu bot. O .env já está no .gitignore. Confira com git check-ignore .env: se imprimir .env, está protegido. Nunca o copie para outro lugar, nem o mostre em print de tela. Se vazar, gere um token novo no @BotFather com /revoke.
- Nunca anuncie descoberta. P1 quer dizer que o sinal sobreviveu aos testes automáticos, não que é planeta. O caminho é: sinal, candidato, CTOI, TOI, planeta validado, planeta confirmado. Os últimos passos exigem outros telescópios (guia, seção 7).
- Não mude limites sem medir. Qualquer mudança em
config/thresholds.yamlexige rodar o benchmark antes e depois. - Um comando de cada vez. Dois comandos escrevendo no banco ao mesmo tempo dão erro de "lock".
- Seja gentil com os servidores. Comece com
--limite não aumente--workerssem motivo.
Exercícios¶
Exercício 1. Espelho velho
O mirrors status mostra toi VELHO idade= 52.3 h. O que acontece se você rodar search, crossmatch e alert agora? Como resolver?
Ver resposta
A busca roda normalmente, porque não usa os espelhos. No crossmatch, todo sinal que seria NEW vira UNVERIFIED: com a lista de TOIs desatualizada, não dá para garantir que é novo. Nenhum alerta sai, e o alert informa "espelhos velhos". Solução: uv run planethunter mirrors sync e depois crossmatch <run_id> de novo. O run-sector faz isso sozinho quando algum espelho está a menos de 6 horas de vencer.
Exercício 2. Do run ao alerta
Você rodou search --sector 70 e recebeu um run_id. Escreva a sequência de comandos até ter o vetting aprofundado e um alerta simulado.
Ver resposta
uv run planethunter crossmatch <run_id>
uv run planethunter vet <run_id>
uv run planethunter vet-deep <run_id>
uv run planethunter candidates <run_id>
uv run planethunter alert <run_id>
vet usa a classe do crossmatch para decidir quem vira candidato, e vet-deep só olha os candidatos que vet criou. Sem --send, o alerta fica em data/outbox/.
Exercício 3. Registrar uma rejeição
Um P2 tem rp_rearth 25, depth_ppm 30 000 e failed igual a odd_even. No dossiê, os trânsitos ímpares são bem mais fundos que os pares. Registre sua decisão.
Ver resposta
Profundidades alternadas indicam uma binária eclipsante com o dobro do período (aula B4), e 25 R⊕ é grande demais para um planeta. O motivoeb ajuda o futuro classificador a aprender esse padrão.
Checklist do laboratório¶
- Instalei com
uv syncetools/fpp, e os testes passaram - Sincronizei os espelhos e li o
mirrors status - Rodei
run-targetem Pi Mensae e em WASP-18 - Fiz o roteiro "meu primeiro setor" com
--limit 200 - Abri um dossiê e um arquivo de
data/outbox/ - Registrei pelo menos uma revisão com
review - Conferi que o
.envestá ignorado pelo Git
Para ir além¶
- Guia para leigos do projeto (
docs/GUIA_PARA_LEIGOS.md, no repositório), seções 3 e 4. Explica cada passo e como ler cada coluna e gráfico. - ExoFOP (exofop.ipac.caltech.edu). Página de cada estrela, com TOIs, CTOIs e notas da comunidade; é onde você confere um candidato antes de qualquer decisão.
- Página do TESS no HEASARC da NASA (heasarc.gsfc.nasa.gov). Explica setores, câmeras e cadências das curvas que o
ingestbaixa.