ruwwww/agent-skills

Astropy

Visão Geral

Astropy é o pacote Python principal para astronomia, fornecendo funcionalidades essenciais para pesquisa astronômica e análise de dados. Use astropy para transformações de coordenadas, cálculos de unidades e quantidades, operações com arquivos FITS, cálculos cosmológicos, manipulação precisa de tempo, manipulação de dados tabulares e processamento de imagens astronômicas.

Quando Usar Esta Habilidade

Use astropy quando as tarefas envolverem:

• Converter entre sistemas de coordenadas celestes (ICRS, Galáctico, FK5, AltAz, etc.)
• Trabalhar com unidades e quantidades físicas (converter Jy para mJy, parsecs para km, etc.)
• Ler, escrever ou manipular arquivos FITS (imagens ou tabelas)
• Cálculos cosmológicos (distância de luminosidade, tempo de lookback, parâmetro de Hubble)
• Manipulação precisa de tempo com diferentes escalas (UTC, TAI, TT, TDB) e formatos (JD, MJD, ISO)
• Operações com tabelas (ler catálogos, cruzar referências, filtrar, juntar)
• Transformações WCS entre coordenadas de pixel e mundiais
• Constantes astronômicas e cálculos

Início Rápido

import astropy.units as u
from astropy.coordinates import SkyCoord
from astropy.time import Time
from astropy.io import fits
from astropy.table import Table
from astropy.cosmology import Planck18

# Unidades e quantidades
distancia = 100 * u.pc
distancia_km = distancia.to(u.km)

# Coordenadas
coord = SkyCoord(ra=10.5*u.degree, dec=41.2*u.degree, frame='icrs')
coord_galatico = coord.galactic

# Tempo
t = Time('2023-01-15 12:30:00')
jd = t.jd  # Data Juliana

# Arquivos FITS
dados = fits.getdata('imagem.fits')
cabecalho = fits.getheader('imagem.fits')

# Tabelas
tabela = Table.read('catalogo.fits')

# Cosmologia
d_L = Planck18.luminosity_distance(z=1.0)

Capacidades Principais

1. Unidades e Quantidades (astropy.units)

Lide com quantidades físicas com unidades, realize conversões de unidades e garanta consistência dimensional nos cálculos.

Operações principais:

• Crie quantidades multiplicando valores por unidades
• Converta entre unidades usando o método .to()
• Realize aritmética com tratamento automático de unidades
• Use equivalências para conversões específicas de domínio (espectral, doppler, paralaxe)
• Trabalhe com unidades logarítmicas (magnitudes, decibéis)

Veja: references/units.md para documentação abrangente, sistemas de unidades, equivalências, otimização de desempenho e aritmética de unidades.

2. Sistemas de Coordenadas (astropy.coordinates)

Represente posições celestes e transforme entre diferentes referenciais de coordenadas.

Operações principais:

• Crie coordenadas com SkyCoord em qualquer referencial (ICRS, Galáctico, FK5, AltAz, etc.)
• Transforme entre sistemas de coordenadas
• Calcule separações angulares e ângulos de posição
• Corresponda coordenadas a catálogos
• Inclua distância para operações de coordenadas 3D
• Lide com movimentos próprios e velocidades radiais
• Consulte objetos nomeados de bancos de dados online

Veja: references/coordinates.md para descrições detalhadas de referenciais de coordenadas, transformações, referenciais dependentes do observador (AltAz), correspondência de catálogos e dicas de desempenho.

3. Cálculos Cosmológicos (astropy.cosmology)

Realize cálculos cosmológicos usando modelos cosmológicos padrão.

Operações principais:

• Use cosmologias embutidas (Planck18, WMAP9, etc.)
• Crie modelos cosmológicos personalizados
• Calcule distâncias (luminosidade, comóvel, diâmetro angular)
• Compute idades e tempos de lookback
• Determine o parâmetro de Hubble em qualquer redshift
• Calcule parâmetros de densidade e volumes
• Realize cálculos inversos (encontre z para uma dada distância)

Veja: references/cosmology.md para modelos disponíveis, cálculos de distância, cálculos de tempo, parâmetros de densidade e efeitos de neutrinos.

4. Manipulação de Arquivos FITS (astropy.io.fits)

Leia, escreva e manipule arquivos FITS (Flexible Image Transport System).

Operações principais:

• Abra arquivos FITS com gerenciadores de contexto
• Acesse HDUs (Header Data Units) por índice ou nome
• Leia e modifique cabeçalhos (palavras-chave, comentários, histórico)
• Trabalhe com dados de imagem (arrays NumPy)
• Lide com dados de tabela (tabelas binárias e ASCII)
• Crie novos arquivos FITS (única ou múltiplas extensões)
• Use mapeamento de memória para arquivos grandes
• Acesse arquivos FITS remotos (S3, HTTP)

Veja: references/fits.md para operações abrangentes de arquivos, manipulação de cabeçalhos, manipulação de imagens e tabelas, arquivos de múltiplas extensões e considerações de desempenho.

5. Operações com Tabelas (astropy.table)

Trabalhe com dados tabulares com suporte a unidades, metadados e vários formatos de arquivo.

Operações principais:

• Crie tabelas a partir de arrays, listas ou dicionários
• Leia/escreva tabelas em vários formatos (FITS, CSV, HDF5, VOTable)
• Acesse e modifique colunas e linhas
• Classifique, filtre e indexe tabelas
• Realize operações do tipo banco de dados (junção, agrupamento, agregação)
• Empilhe e concatene tabelas
• Trabalhe com colunas com unidades (QTable)
• Lide com dados faltantes usando mascaramento

Veja: references/tables.md para criação de tabelas, operações de E/S, manipulação de dados, classificação, filtragem, junções, agrupamento e dicas de desempenho.

6. Manipulação de Tempo (astropy.time)

Representação precisa de tempo e conversão entre escalas e formatos de tempo.

Operações principais:

• Crie objetos Time em vários formatos (ISO, JD, MJD, Unix, etc.)
• Converta entre escalas de tempo (UTC, TAI, TT, TDB, etc.)
• Realize aritmética de tempo com TimeDelta
• Calcule tempo sideral para observadores
• Compute correções de tempo de viagem da luz (baricêntrica, heliocêntrica)
• Trabalhe com arrays de tempo com eficiência
• Lide com tempos mascarados (faltantes)

Veja: references/time.md para formatos de tempo, escalas de tempo, conversões, aritmética, recursos de observação e manipulação de precisão.

7. Sistema de Coordenadas Mundial (astropy.wcs)

Transforme entre coordenadas de pixel em imagens e coordenadas mundiais.

Operações principais:

• Leia WCS de cabeçalhos FITS
• Converta coordenadas de pixel para coordenadas mundiais (e vice-versa)
• Calcule footprints de imagens
• Acesse parâmetros WCS (pixel de referência, projeção, escala)
• Crie objetos WCS personalizados

Veja: references/wcs_and_other_modules.md para operações e transformações WCS.

Capacidades Adicionais

O arquivo references/wcs_and_other_modules.md também cobre:

NDData e CCDData

Contêineres para conjuntos de dados n-dimensionais com metadados, incerteza, mascaramento e informações WCS.

Modelagem

Framework para criar e ajustar modelos matemáticos a dados astronômicos.

Visualização

Ferramentas para exibição de imagens astronômicas com alongamento e escalonamento apropriados.

Constantes

Constantes físicas e astronômicas com unidades adequadas (velocidade da luz, massa solar, constante de Planck, etc.).

Convolução

Kernels de processamento de imagem para suavização e filtragem.

Estatística

Funções estatísticas robustas, incluindo sigma clipping e rejeição de outliers.

Instalação

# Instalação reproduzível contra a versão estável atual
uv pip install "astropy==7.2.0"

# Dependências opcionais recomendadas para plotagem e fluxos de trabalho comuns
uv pip install "astropy[recommended]==7.2.0"

# Conjunto completo de dependências opcionais para fluxos de trabalho amplos de astronomia
uv pip install "astropy[all]==7.2.0"

O Astropy 7.2.0 requer Python 3.11+ e depende de NumPy, PyERFA, PyYAML e packaging. Use um ambiente virtual isolado; não instale o Astropy com privilégios elevados.

Observe que os extras [recommended] e [all] trazem dependências transitivas (matplotlib, scipy, etc.) em versões não fixadas. Para ambientes de produção reproduzíveis, fixe a árvore de dependências completa com um arquivo de bloqueio (uv lock em um projeto, ou uv pip compile para arquivos de requisitos) e revise as versões resolvidas antes de implantar.

Fluxos de Trabalho Comuns

Convertendo Coordenadas Entre Sistemas

from astropy.coordinates import SkyCoord
import astropy.units as u

# Crie coordenada
c = SkyCoord(ra='05h23m34.5s', dec='-69d45m22s', frame='icrs')

# Transforme para galáctico
c_gal = c.galactic
print(f"l={c_gal.l.deg}, b={c_gal.b.deg}")

# Transforme para alt-az (requer tempo e localização)
from astropy.time import Time
from astropy.coordinates import EarthLocation, AltAz

tempo_observacao = Time('2023-06-15 23:00:00')
local_observacao = EarthLocation(lat=40*u.deg, lon=-120*u.deg)
fram_aa = AltAz(obstime=tempo_observacao, location=local_observacao)
c_altaz = c.transform_to(fram_aa)
print(f"Alt={c_altaz.alt.deg}, Az={c_altaz.az.deg}")

Lendo e Analisando Arquivos FITS

from astropy.io import fits
import numpy as np

# Abra arquivo FITS
with fits.open('observacao.fits') as hdul:
    # Exiba estrutura
    hdul.info()

    # Obtenha dados de imagem e cabeçalho
    dados = hdul[1].data
    cabecalho = hdul[1].header

    # Acesse valores do cabeçalho
    temp_exp = cabecalho['EXPTIME']
    nome_filtro = cabecalho['FILTER']

    # Analise dados
    media = np.mean(dados)
    mediana = np.median(dados)
    print(f"Média: {media}, Mediana: {mediana}")

Cálculos de Distância Cosmológica

from astropy.cosmology import Planck18
import astropy.units as u
import numpy as np

# Calcule distâncias em z=1.5
z = 1.5
d_L = Planck18.luminosity_distance(z)
d_A = Planck18.angular_diameter_distance(z)

print(f"Distância de luminosidade: {d_L}")
print(f"Distância de diâmetro angular: {d_A}")

# Idade do universo naquele redshift
idade = Planck18.age(z)
print(f"Idade em z={z}: {idade.to(u.Gyr)}")

# Tempo de lookback
t_lookback = Planck18.lookback_time(z)
print(f"Tempo de lookback: {t_lookback.to(u.Gyr)}")

Cruzando Catálogos

from astropy.table import Table
from astropy.coordinates import SkyCoord, match_coordinates_sky
import astropy.units as u

# Leia catálogos
cat1 = Table.read('catalogo1.fits')
cat2 = Table.read('catalogo2.fits')

# Crie objetos de coordenada
coords1 = SkyCoord(ra=cat1['RA']*u.degree, dec=cat1['DEC']*u.degree)
coords2 = SkyCoord(ra=cat2['RA']*u.degree, dec=cat2['DEC']*u.degree)

# Encontre correspondências
idx, sep, _ = coords1.match_to_catalog_sky(coords2)

# Filtre por limite de separação
max_sep = 1 * u.arcsec
correspondencias = sep < max_sep

# Crie catálogos correspondentes
cat1_corresp = cat1[correspondencias]
cat2_corresp = cat2[idx[correspondencias]]
print(f"Encontradas {len(cat1_corresp)} correspondências")

Práticas Recomendadas

1. Sempre use unidades: Anexe unidades às quantidades para evitar erros e garantir consistência dimensional
2. Use gerenciadores de contexto para arquivos FITS: Garante o fechamento adequado do arquivo
3. Prefira arrays a loops: Processe múltiplas coordenadas/tempos como arrays para melhor desempenho
4. Verifique referenciais de coordenadas: Confirme o referencial antes das transformações
5. Use cosmologia apropriada: Escolha o modelo cosmológico certo para sua análise
6. Lide com dados faltantes: Use colunas mascaradas para tabelas com valores ausentes
7. Especifique escalas de tempo: Seja explícito sobre escalas de tempo (UTC, TT, TDB) para temporização precisa
8. Use QTable para tabelas com unidades: Quando as colunas da tabela tiverem unidades
9. Verifique validade do WCS: Confirme o WCS antes de usar transformações
10. Armazene em cache valores usados com frequência: Cálculos caros (por exemplo, distâncias cosmológicas) podem ser armazenados em cache
11. Seja explícito sobre acesso à rede: SkyCoord.from_name(), EarthLocation.of_site(refresh_cache=True), EarthLocation.of_address(), download_file(), leituras remotas de FITS e algumas transformações de tempo/coordenadas do IERS podem contatar serviços externos ou atualizar caches locais. Evite enviar nomes de alvos sensíveis, endereços, URLs ou localizações de arquivos proprietários para serviços de terceiros. Ao trabalhar com alvos potencialmente sensíveis ou locais de dados, confirme com o usuário antes de fazer essas chamadas de rede.
12. Fixe para reprodutibilidade: Use versões fixadas como astropy==7.2.0 para ambientes compartilhados; atualize as fixações intencionalmente após revisar as notas de versão.

Notas da Versão Atual

• Versão estável atual pesquisada: Astropy 7.2.0 (lançada em 2025-11-25; verificada como atual em 2026-06-10)
• Requisito Python: 3.11+
• Astropy 8.0 está em estágio de release candidate (8.0.0rc1, 2026-05-26). Principais mudanças a antecipar:
  • Os shims de submódulo astropy.cosmology obsoletos (astropy.cosmology.flrw, .core, .funcs, .connect, .parameter) são removidos — importe tudo diretamente de astropy.cosmology (por exemplo, from astropy.cosmology import FlatLambdaCDM, z_at_value)
  • Os padrões de astropy.constants mudam de CODATA 2018 para CODATA 2022; fixe uma versão de constantes via os estados científicos astropyconst se a reprodutibilidade for importante
  • NumPy 2.0 torna-se a versão mínima suportada; o ramo LTS 7.2.x mantém suporte a NumPy 1.x por seis meses após o lançamento do 8.0
  • O executor de teste embutido (astropy.test(), TestRunner) é formalmente obsoleto — invoque pytest diretamente
• Obsolescências recentes do 7.x a evitar em código novo: passar um identificador de índice de tabela como o primeiro elemento .loc (t.loc["b", 2]) — use t.loc.with_index("b")[2] em vez disso (remoção planejada para 9.0); astropy.utils.isiterable() — use numpy.iterable()
• Remoções recentes do 7.0: APIs FITS obsoletas mais antigas, como (Bin)Table.update, _ExtensionHDU, _NonstandardExtHDU, e o argumento tile_size para CompImageHDU; CompImageHeader está obsoleto. Evite esses padrões legados em novos exemplos.
• Os extras opcionais recomendados são recommended para dependências comuns de plotagem/científicas e all apenas quando um conjunto amplo de funcionalidades opcionais for necessário.

Documentação e Recursos

• Documentação Oficial do Astropy: https://docs.astropy.org/en/stable/
• Tutoriais: https://learn.astropy.org/
• GitHub: https://github.com/astropy/astropy

Arquivos de Referência

Para informações detalhadas sobre módulos específicos:

• references/units.md - Unidades, quantidades, conversões e equivalências
• references/coordinates.md - Sistemas de coordenadas, transformações e correspondência de catálogos
• references/cosmology.md - Modelos e cálculos cosmológicos
• references/fits.md - Operações e manipulação de arquivos FITS
• references/tables.md - Criação, E/S e operações de tabelas
• references/time.md - Formatos, escalas e cálculos de tempo
• references/wcs_and_other_modules.md - WCS, NDData, modelagem, visualização, constantes e utilitários

Citando Habilidades de Agente Científico

Esta habilidade faz parte do Scientific Agent Skills, uma coleção de habilidades especializadas para agentes de IA no domínio científico. Consulte a documentação principal para diretrizes de citação.