d3v-null/wsclean-skill

Habilidade WSClean

WSClean é uma ferramenta de imageamento por interferometria de rádio que cria imagens limpas a partir de Measurement Sets. Use esta habilidade ao trabalhar com dados de radioastronomia de telescópios como LOFAR, MWA, VLA, ASKAP ou SKA.

Quando Usar

• Imageamento de dados de interferometria de rádio de arquivos Measurement Set (.ms)
• Deconvolução CLEAN de dados de visibilidade
• Limpeza multi-escala para fontes resolvidas
• Síntese multi-frequência (imageamento de banda larga)
• Imageamento polarimétrico
• Imageamento baseado em facetas com correções dependentes de direção
• Laços de autocalibração (geração de modelos)

Acesso via Docker

WSClean é complexo de compilar. Use Docker:

docker run --rm -it d3vnull0/rapthor-mildtec:smoke wsclean [opções] <input.ms>

Monte diretórios de dados: -v /caminho/hosp:/caminho/container:rw

Estrutura Básica de Comando

wsclean [opções] <ms-entrada> [<ms-segundo> [...]]

Crítico: Múltiplos conjuntos de medidas DEVEM ser rotacionados em fase para a mesma posição.

Parâmetros Essenciais

Configuração de Imagem (Sempre Obrigatório)

• -size <l> <a> - Dimensões da imagem em pixels (devem ser pares)
• -scale <valor> - Escala do pixel (ex.: 2asec, 1amin, 0.01deg)
• -name <prefixo> - Prefixo do nome do arquivo de saída (padrão: 'wsclean')

Controle de Deconvolução

• -niter <n> - Máximo de iterações (defina alto, ex.: 1000000)
• -auto-threshold <sigma> - Parar em sigma×RMS (recomendado: 1-5)
• -mgain <ganho> - Ganho do laço principal: 0.85 (seguro), 0.95 (agressivo)
  • Crítico: mgain=1.0 impede autocalibração (sem atualizações MODEL_DATA)
• -auto-mask <sigma> - Limite de máscara automática (recomendado com -auto-threshold)

Ponderação

• -weight briggs <robusto> - Ponderação Briggs (-2 a +2, comum: -0.5, 0, 0.5)
• -weight uniform - Máxima resolução
• -weight natural - Máxima sensibilidade

Funcionalidades Avançadas

• -multiscale - CLEAN multi-escala para fontes resolvidas
• -channels-out <n> - Dividir largura de banda em N imagens
• -join-channels - Deconvolução multi-frequência
• -pol <lista> - Polarizações: I, Q, U, V, ou XX, XY, YX, YY
• -join-polarizations - Deconvolução polarimétrica

Fluxos de Trabalho Comuns

1. Imagem Direta Rápida (Sem Limpeza)

docker run --rm -v $(pwd):/data:rw d3vnull0/rapthor-mildtec:smoke \
  wsclean -size 2048 2048 -scale 5asec -name rapida /data/obs.ms

2. Limpeza Padrão

wsclean -size 4096 4096 -scale 2asec \
  -niter 100000 -auto-threshold 3 \
  -weight briggs 0 -mgain 0.85 \
  -name padrao obs.ms

3. Limpeza Multi-Escala Profunda (Melhor Qualidade)

wsclean -size 8192 8192 -scale 1asec \
  -multiscale -multiscale-scale-bias 0.7 \
  -niter 1000000 -auto-threshold 1 -auto-mask 5 \
  -weight briggs -0.5 -mgain 0.85 \
  -name profunda obs.ms

4. Síntese Multi-Frequência (4 canais)

wsclean -size 4096 4096 -scale 2asec \
  -channels-out 4 -join-channels \
  -multiscale -niter 500000 \
  -auto-threshold 3 -mgain 0.85 \
  -name mfs obs.ms

5. Imageamento Polarimétrico

wsclean -size 4096 4096 -scale 2asec \
  -pol xx,yy -join-polarizations \
  -niter 100000 -auto-threshold 3 \
  -mgain 0.85 -name pol obs.ms

6. Imageamento para Autocalibração

# CRÍTICO: mgain < 1.0 para atualizar MODEL_DATA
wsclean -size 4096 4096 -scale 2asec \
  -niter 100000 -auto-threshold 3 \
  -mgain 0.85 -multiscale -auto-mask 5 \
  -name autocal obs.ms

Arquivos de Saída

Com -name minhaimagem:

• minhaimagem-dirty.fits - Imagem direta (suja)
• minhaimagem-image.fits - Imagem limpa/restaurada
• minhaimagem-model.fits - Modelo (componentes CLEAN)
• minhaimagem-residual.fits - Residual após limpeza
• minhaimagem-psf.fits - Função de espalhamento pontual

Multi-canal: minhaimagem-0000-image.fits, minhaimagem-0001-image.fits, etc. Multi-pol: minhaimagem-I-image.fits, minhaimagem-Q-image.fits, etc.

Referência Rápida – Parâmetros Chave

Parâmetro	Propósito	Valores Típicos
-niter	Máximo de iterações	100000-1000000
-auto-threshold	Parar em N×sigma	1-5 (menor=mais profundo)
-mgain	Ganho do laço principal	0.85 (seguro), 0.95 (rápido)
-auto-mask	Limite da máscara	3-5 sigma
-weight briggs	Robustez da ponderação	-0.5 (res), 0 (balanceado), 0.5 (sens)
-multiscale-scale-bias	Preferência de escala	0.6-0.7
-channels-out	Canais de saída	4-16 típico
-j	Threads da CPU	Padrão: todos os núcleos

Problemas Comuns

Limpeza Diverge

• Reduza -mgain para 0.7 ou 0.8
• Use -multiscale-gain 0.1 se multi-escala
• Tente -major-iteration-mode single

Falta de Memória

• Use -abs-mem 32 (ou GB apropriado)
• Reduza -size ou aumente -scale
• Use -deconvolution-channels para imageamento espectral

Não é Possível Autocalibrar

• Certifique-se de que mgain < 1.0 (não 1.0!)
• A coluna MODEL_DATA só é atualizada com mgain < 1

Má Qualidade de Imagem

• Use -multiscale para fontes resolvidas
• Adicione -auto-mask 5 para limpeza profunda
• Verifique a ponderação: tente -weight briggs 0

Quando Consultar Referências Detalhadas

Para cenários complexos, consulte os arquivos de referência neste diretório:

• reference/parameters.md - Documentação completa de parâmetros
• reference/workflows.md - Fluxos de trabalho avançados (facetas, feixe primário, etc.)
• reference/troubleshooting.md - Guia detalhado de solução de problemas

Use a ferramenta Read para acessar estes arquivos quando necessário.

Melhores Práticas

1. Sempre use -auto-threshold (não limite absoluto)
2. Defina -niter alto e deixe o limite parar a limpeza
3. Use mgain 0.85 para uma limpeza robusta de Cotton-Schwab
4. Multi-escala para fontes resolvidas – sempre melhor que Högbom
5. Combine -auto-mask 5 com -auto-threshold 1 para limpeza profunda
6. As dimensões da imagem devem ser pares – de preferência potência de 2
7. ~5-6 pixels por feixe sintetizado para amostragem adequada

Documentação

• Documentação completa: https://wsclean.readthedocs.io/
• Artigo do algoritmo: Offringa & Smirnov 2017 (https://arxiv.org/abs/1706.06786)