claude-scientific-skills/scientific-packages/astropy/references/module_overview.md

Astropy Module Overview

This document provides a comprehensive reference of all major astropy subpackages and their capabilities.

Core Data Structures

astropy.units

Purpose: Handle physical units and dimensional analysis in computations.

Key Classes:

• Quantity - Combines numerical values with units
• Unit - Represents physical units

Common Operations:

import astropy.units as u
distance = 5 * u.meter
time = 2 * u.second
velocity = distance / time  # Returns Quantity in m/s
wavelength = 500 * u.nm
frequency = wavelength.to(u.Hz, equivalencies=u.spectral())

Equivalencies:

• u.spectral() - Convert wavelength ↔ frequency
• u.doppler_optical(), u.doppler_radio() - Velocity conversions
• u.temperature() - Temperature unit conversions
• u.pixel_scale() - Pixel to physical units

astropy.constants

Purpose: Provide physical and astronomical constants.

Common Constants:

• c - Speed of light
• G - Gravitational constant
• h - Planck constant
• M_sun, R_sun, L_sun - Solar mass, radius, luminosity
• M_earth, R_earth - Earth mass, radius
• pc, au - Parsec, astronomical unit

astropy.time

Purpose: Represent and manipulate times and dates with astronomical precision.

Time Scales:

• UTC - Coordinated Universal Time
• TAI - International Atomic Time
• TT - Terrestrial Time
• TCB, TCG - Barycentric/Geocentric Coordinate Time
• TDB - Barycentric Dynamical Time
• UT1 - Universal Time

Common Formats:

• iso, isot - ISO 8601 strings
• jd, mjd - Julian/Modified Julian Date
• unix, gps - Unix/GPS timestamps
• datetime - Python datetime objects

Example:

from astropy.time import Time
t = Time('2023-01-01T00:00:00', format='isot', scale='utc')
print(t.mjd)  # Modified Julian Date
print(t.jd)   # Julian Date
print(t.tt)   # Convert to TT scale

astropy.table

Purpose: Work with tabular data optimized for astronomical applications.

Key Features:

• Native support for astropy Quantity, Time, and SkyCoord columns
• Multi-dimensional columns
• Metadata preservation (units, descriptions, formats)
• Advanced operations: joins, grouping, binning
• File I/O via unified interface

Example:

from astropy.table import Table
import astropy.units as u

t = Table()
t['name'] = ['Star1', 'Star2', 'Star3']
t['ra'] = [10.5, 11.2, 12.3] * u.degree
t['dec'] = [41.2, 42.1, 43.5] * u.degree
t['flux'] = [1.2, 2.3, 0.8] * u.Jy

Coordinates and World Coordinate Systems

astropy.coordinates

Purpose: Represent and transform celestial coordinates.

Primary Interface: SkyCoord - High-level class for sky positions

Coordinate Frames:

• ICRS - International Celestial Reference System (default)
• FK5, FK4 - Fifth/Fourth Fundamental Katalog
• Galactic, Supergalactic - Galactic coordinates
• AltAz - Horizontal (altitude-azimuth) coordinates
• GCRS, CIRS, ITRS - Earth-based systems
• BarycentricMeanEcliptic, HeliocentricMeanEcliptic, GeocentricMeanEcliptic - Ecliptic coordinates

Common Operations:

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

# Create coordinate
c = SkyCoord(ra=10.625*u.degree, dec=41.2*u.degree, frame='icrs')

# Transform to galactic
c_gal = c.galactic

# Calculate separation
c2 = SkyCoord(ra=11*u.degree, dec=42*u.degree, frame='icrs')
sep = c.separation(c2)

# Match catalogs
idx, sep2d, dist3d = c.match_to_catalog_sky(catalog_coords)

astropy.wcs

Purpose: Handle World Coordinate System transformations for astronomical images.

Key Class: WCS - Maps between pixel and world coordinates

Common Use Cases:

• Convert pixel coordinates to RA/Dec
• Convert RA/Dec to pixel coordinates
• Handle distortion corrections (SIP, lookup tables)

Example:

from astropy.wcs import WCS
from astropy.io import fits

hdu = fits.open('image.fits')[0]
wcs = WCS(hdu.header)

# Pixel to world
ra, dec = wcs.pixel_to_world_values(100, 200)

# World to pixel
x, y = wcs.world_to_pixel_values(ra, dec)

File I/O

astropy.io.fits

Purpose: Read and write FITS (Flexible Image Transport System) files.

Key Classes:

• HDUList - Container for all HDUs in a file
• PrimaryHDU - Primary header data unit
• ImageHDU - Image extension
• BinTableHDU - Binary table extension
• Header - FITS header keywords

Common Operations:

from astropy.io import fits

# Read FITS file
with fits.open('file.fits') as hdul:
    hdul.info()  # Display structure
    header = hdul[0].header
    data = hdul[0].data

# Write FITS file
fits.writeto('output.fits', data, header)

# Update header keyword
fits.setval('file.fits', 'OBJECT', value='M31')

astropy.io.ascii

Purpose: Read and write ASCII tables in various formats.

Supported Formats:

• Basic, CSV, tab-delimited
• CDS/MRT (Machine Readable Tables)
• IPAC, Daophot, SExtractor
• LaTeX tables
• HTML tables

astropy.io.votable

Purpose: Handle Virtual Observatory (VO) table format.

astropy.io.misc

Purpose: Additional formats including HDF5, Parquet, and YAML.

Scientific Calculations

astropy.cosmology

Purpose: Perform cosmological calculations.

Common Models:

• FlatLambdaCDM - Flat universe with cosmological constant (most common)
• LambdaCDM - Universe with cosmological constant
• Planck18, Planck15, Planck13 - Pre-defined Planck parameters
• WMAP9, WMAP7, WMAP5 - Pre-defined WMAP parameters

Common Methods:

from astropy.cosmology import FlatLambdaCDM, Planck18
import astropy.units as u

cosmo = FlatLambdaCDM(H0=70, Om0=0.3)
# Or use built-in: cosmo = Planck18

z = 1.5
print(cosmo.age(z))  # Age of universe at z
print(cosmo.luminosity_distance(z))  # Luminosity distance
print(cosmo.angular_diameter_distance(z))  # Angular diameter distance
print(cosmo.comoving_distance(z))  # Comoving distance
print(cosmo.H(z))  # Hubble parameter at z

astropy.modeling

Purpose: Framework for model evaluation and fitting.

Model Categories:

• 1D models: Gaussian1D, Lorentz1D, Voigt1D, Polynomial1D
• 2D models: Gaussian2D, Disk2D, Moffat2D
• Physical models: BlackBody, Drude1D, NFW
• Polynomial models: Chebyshev, Legendre

Common Fitters:

• LinearLSQFitter - Linear least squares
• LevMarLSQFitter - Levenberg-Marquardt
• SimplexLSQFitter - Downhill simplex

Example:

from astropy.modeling import models, fitting

# Create model
g = models.Gaussian1D(amplitude=10, mean=5, stddev=1)

# Fit to data
fitter = fitting.LevMarLSQFitter()
fitted_model = fitter(g, x_data, y_data)

astropy.convolution

Purpose: Convolve and filter astronomical data.

Common Kernels:

• Gaussian2DKernel - 2D Gaussian smoothing
• Box2DKernel - 2D boxcar smoothing
• Tophat2DKernel - 2D tophat filter
• Custom kernels via arrays

astropy.stats

Purpose: Statistical tools for astronomical data analysis.

Key Functions:

• sigma_clip() - Remove outliers via sigma clipping
• sigma_clipped_stats() - Compute mean, median, std with clipping
• mad_std() - Median Absolute Deviation
• biweight_location(), biweight_scale() - Robust statistics
• circmean(), circstd() - Circular statistics

Example:

from astropy.stats import sigma_clip, sigma_clipped_stats

# Remove outliers
filtered_data = sigma_clip(data, sigma=3, maxiters=5)

# Get statistics
mean, median, std = sigma_clipped_stats(data, sigma=3)

Data Processing

astropy.nddata

Purpose: Handle N-dimensional datasets with metadata.

Key Class: NDData - Container for array data with units, uncertainty, mask, and WCS

astropy.timeseries

Purpose: Work with time series data.

Key Classes:

• TimeSeries - Time-indexed data table
• BinnedTimeSeries - Time-binned data

Common Operations:

• Period finding (Lomb-Scargle)
• Folding time series
• Binning data

astropy.visualization

Purpose: Display astronomical data effectively.

Key Features:

• Image normalization (LogStretch, PowerStretch, SqrtStretch, etc.)
• Interval scaling (MinMaxInterval, PercentileInterval, ZScaleInterval)
• WCSAxes for plotting with coordinate overlays
• RGB image creation with stretching
• Astronomical colormaps

Example:

from astropy.visualization import ImageNormalize, SqrtStretch, PercentileInterval
import matplotlib.pyplot as plt

norm = ImageNormalize(data, interval=PercentileInterval(99),
                     stretch=SqrtStretch())
plt.imshow(data, norm=norm, origin='lower')

Utilities

astropy.samp

Purpose: Simple Application Messaging Protocol for inter-application communication.

Use Case: Connect Python scripts with other astronomical tools (e.g., DS9, TOPCAT).

Module Import Patterns

Standard imports:

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 import constants as const

Performance Tips

1. Pre-compute composite units for repeated operations
2. Use << operator for fast unit assignments: array << u.m instead of array * u.m
3. Vectorize operations rather than looping over coordinates/times
4. Use memmap=True when opening large FITS files
5. Install Bottleneck for faster stats operations