astropy

# Astropy

## Overview

Astropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis. Use astropy for coordinate transformations, unit and quantity calculations, FITS file operations, cosmological calculations, precise time handling, tabular data manipulation, and astronomical image processing.

## When to Use This Skill

Use astropy when tasks involve:
- Converting between celestial coordinate systems (ICRS, Galactic, FK5, AltAz, etc.)
- Working with physical units and quantities (converting Jy to mJy, parsecs to km, etc.)
- Reading, writing, or manipulating FITS files (images or tables)
- Cosmological calculations (luminosity distance, lookback time, Hubble parameter)
- Precise time handling with different time scales (UTC, TAI, TT, TDB) and formats (JD, MJD, ISO)
- Table operations (reading catalogs, cross-matching, filtering, joining)
- WCS transformations between pixel and world coordinates
- Astronomical constants and calculations

## Quick Start

```python
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

# Units and quantities
distance = 100 * u.pc
distance_km = distance.to(u.km)

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

# Time
t = Time('2023-01-15 12:30:00')
jd = t.jd  # Julian Date

# FITS files
data = fits.getdata('image.fits')
header = fits.getheader('image.fits')

# Tables
table = Table.read('catalog.fits')

# Cosmology
d_L = Planck18.luminosity_distance(z=1.0)
```

## Core Capabilities

### 1. Units and Quantities (`astropy.units`)

Handle physical quantities with units, perform unit conversions, and ensure dimensional consistency in calculations.

**Key operations:**
- Create quantities by multiplying values with units
- Convert between units using `.to()` method
- Perform arithmetic with automatic unit handling
- Use equivalencies for domain-specific conversions (spectral, doppler, parallax)
- Work with logarithmic units (magnitudes, decibels)

**See:** `references/units.md` for comprehensive documentation, unit systems, equivalencies, performance optimization, and unit arithmetic.

### 2. Coordinate Systems (`astropy.coordinates`)

Represent celestial positions and transform between different coordinate frames.

**Key operations:**
- Create coordinates with `SkyCoord` in any frame (ICRS, Galactic, FK5, AltAz, etc.)
- Transform between coordinate systems
- Calculate angular separations and position angles
- Match coordinates to catalogs
- Include distance for 3D coordinate operations
- Handle proper motions and radial velocities
- Query named objects from online databases

**See:** `references/coordinates.md` for detailed coordinate frame descriptions, transformations, observer-dependent frames (AltAz), catalog matching, and performance tips.

### 3. Cosmological Calculations (`astropy.cosmology`)

Perform cosmological calculations using standard cosmological models.

**Key operations:**
- Use built-in cosmologies (Planck18, WMAP9, etc.)
- Create custom cosmological models
- Calculate distances (luminosity, comoving, angular diameter)
- Compute ages and lookback times
- Determine Hubble parameter at any redshift
- Calculate density parameters and volumes
- Perform inverse calculations (find z for given distance)

**See:** `references/cosmology.md` for available models, distance calculations, time calculations, density parameters, and neutrino effects.

### 4. FITS File Handling (`astropy.io.fits`)

Read, write, and manipulate FITS (Flexible Image Transport System) files.

**Key operations:**
- Open FITS files with context managers
- Access HDUs (Header Data Units) by index or name
- Read and modify headers (keywords, comments, history)
- Work with image data (NumPy arrays)
- Handle table data (binary and ASCII tables)
- Create new FITS files (single or multi-extension)
- Use memory mapping for large files
- Access remote FITS files (S3, HTTP)

**See:** `references/fits.md` for comprehensive file operations, header manipulation, image and table handling, multi-extension files, and performance considerations.

### 5. Table Operations (`astropy.table`)

Work with tabular data with support for units, metadata, and various file formats.

**Key operations:**
- Create tables from arrays, lists, or dictionaries
- Read/write tables in multiple formats (FITS, CSV, HDF5, VOTable)
- Access and modify columns and rows
- Sort, filter, and index tables
- Perform database-style operations (join, group, aggregate)
- Stack and concatenate tables
- Work with unit-aware columns (QTable)
- Handle missing data with masking

**See:** `references/tables.md` for table creation, I/O operations, data manipulation, sorting, filtering, joins, grouping, and performance tips.

### 6. Time Handling (`astropy.time`)

Precise time representation and conversion between time scales and formats.

**Key operations:**
- Create Time objects in various formats (ISO, JD, MJD, Unix, etc.)
- Convert between time scales (UTC, TAI, TT, TDB, etc.)
- Perform time arithmetic with TimeDelta
- Calculate sidereal time for observers
- Compute light travel time corrections (barycentric, heliocentric)
- Work with time arrays efficiently
- Handle masked (missing) times

**See:** `references/time.md` for time formats, time scales, conversions, arithmetic, observing features, and precision handling.

### 7. World Coordinate System (`astropy.wcs`)

Transform between pixel coordinates in images and world coordinates.

**Key operations:**
- Read WCS from FITS headers
- Convert pixel coordinates to world coordinates (and vice versa)
- Calculate image footprints
- Access WCS parameters (reference pixel, projection, scale)
- Create custom WCS objects

**See:** `references/wcs_and_other_modules.md` for WCS operations and transformations.

## Additional Capabilities

The `references/wcs_and_other_modules.md` file also covers:

### NDData and CCDData
Containers for n-dimensional datasets with metadata, uncertainty, masking, and WCS information.

### Modeling
Framework for creating and fitting mathematical models to astronomical data.

### Visualization
Tools for astronomical image display with appropriate stretching and scaling.

### Constants
Physical and astronomical constants with proper units (speed of light, solar mass, Planck constant, etc.).

### Convolution
Image processing kernels for smoothing and filtering.

### Statistics
Robust statistical functions including sigma clipping and outlier rejection.

## Installation

```bash
# Install astropy
uv pip install astropy

# With optional dependencies for full functionality
uv pip install astropy[all]
```

## Common Workflows

### Converting Coordinates Between Systems

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

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

# Transform to galactic
c_gal = c.galactic
print(f"l={c_gal.l.deg}, b={c_gal.b.deg}")

# Transform to alt-az (requires time and location)
from astropy.time import Time
from astropy.coordinates import EarthLocation, AltAz

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

### Reading and Analyzing FITS Files

```python
from astropy.io import fits
import numpy as np

# Open FITS file
with fits.open('observation.fits') as hdul:
    # Display structure
    hdul.info()

    # Get image data and header
    data = hdul[1].data
    header = hdul[1].header

    # Access header values
    exptime = header['EXPTIME']
    filter_name = header['FILTER']

    # Analyze data
    mean = np.mean(data)
    median = np.median(data)
    print(f"Mean: {mean}, Median: {median}")
```

### Cosmological Distance Calculations

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

# Calculate distances at z=1.5
z = 1.5
d_L = Planck18.luminosity_distance(z)
d_A = Planck18.angular_diameter_distance(z)

print(f"Luminosity distance: {d_L}")
print(f"Angular diameter distance: {d_A}")

# Age of universe at that redshift
age = Planck18.age(z)
print(f"Age at z={z}: {age.to(u.Gyr)}")

# Lookback time
t_lookback = Planck18.lookback_time(z)
print(f"Lookback time: {t_lookback.to(u.Gyr)}")
```

### Cross-Matching Catalogs

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

# Read catalogs
cat1 = Table.read('catalog1.fits')
cat2 = Table.read('catalog2.fits')

# Create coordinate objects
coords1 = SkyCoord(ra=cat1['RA']*u.degree, dec=cat1['DEC']*u.degree)
coords2 = SkyCoord(ra=cat2['RA']*u.degree, dec=cat2['DEC']*u.degree)

# Find matches
idx, sep, _ = coords1.match_to_catalog_sky(coords2)

# Filter by separation threshold
max_sep = 1 * u.arcsec
matches = sep < max_sep

# Create matched catalogs
cat1_matched = cat1[matches]
cat2_matched = cat2[idx[matches]]
print(f"Found {len(cat1_matched)} matches")
```

## Best Practices

1. **Always use units**: Attach units to quantities to avoid errors and ensure dimensional consistency
2. **Use context managers for FITS files**: Ensures proper file closing
3. **Prefer arrays over loops**: Process multiple coordinates/times as arrays for better performance
4. **Check coordinate frames**: Verify the frame before transformations
5. **Use appropriate cosmology**: Choose the right cosmological model for your analysis
6. **Handle missing data**: Use masked columns for tables with missing values
7. **Specify time scales**: Be explicit about time scales (UTC, TT, TDB) for precise timing
8. **Use QTable for unit-aware tables**: When table columns have units
9. **Check WCS validity**: Verify WCS before using transformations
10. **Cache frequently used values**: Expensive calculations (e.g., cosmological distances) can be cached

## Documentation and Resources

- Official Astropy Documentation: https://docs.astropy.org/en/stable/
- Tutorials: https://learn.astropy.org/
- GitHub: https://github.com/astropy/astropy

## Reference Files

For detailed information on specific modules:
- `references/units.md` - Units, quantities, conversions, and equivalencies
- `references/coordinates.md` - Coordinate systems, transformations, and catalog matching
- `references/cosmology.md` - Cosmological models and calculations
- `references/fits.md` - FITS file operations and manipulation
- `references/tables.md` - Table creation, I/O, and operations
- `references/time.md` - Time formats, scales, and calculations
- `references/wcs_and_other_modules.md` - WCS, NDData, modeling, visualization, constants, and utilities

{
  "format": "aiskill/v1",
  "skill": {
    "name": "astropy",
    "slug": "astropy",
    "version": "1.0.0",
    "description": "Comprehensive Python library for astronomy and astrophysics. This skill should be used when working with astronomical data including celestial coordinates, physical units, FITS files, cosmological calculations, time systems, tables, world coordinate systems (WCS), and astronomical data analysis. Use when tasks involve coordinate transformations, unit conversions, FITS file manipulation, cosmological distance calculations, time scale conversions, or astronomical data processing.",
    "category": "Research",
    "tags": [
      "research-science",
      "python"
    ],
    "platforms": [
      "chatgpt",
      "claude-code",
      "cursor"
    ],
    "tested_environment": "Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and compatible agents",
    "license": "BSD-3-CLAUSE LICENSE"
  },
  "prompts": {
    "system": "# Astropy\r\n\r\n## Overview\r\n\r\nAstropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis. Use astropy for coordinate transformations, unit and quantity calculations, FITS file operations, cosmological calculations, precise time handling, tabular data manipulation, and astronomical image processing.\r\n\r\n## When to Use This Skill\r\n\r\nUse astropy when tasks involve:\r\n- Converting between celestial coordinate systems (ICRS, Galactic, FK5, AltAz, etc.)\r\n- Working with physical units and quantities (converting Jy to mJy, parsecs to km, etc.)\r\n- Reading, writing, or manipulating FITS files (images or tables)\r\n- Cosmological calculations (luminosity distance, lookback time, Hubble parameter)\r\n- Precise time handling with different time scales (UTC, TAI, TT, TDB) and formats (JD, MJD, ISO)\r\n- Table operations (reading catalogs, cross-matching, filtering, joining)\r\n- WCS transformations between pixel and world coordinates\r\n- Astronomical constants and calculations\r\n\r\n## Quick Start\r\n\r\n```python\r\nimport astropy.units as u\r\nfrom astropy.coordinates import SkyCoord\r\nfrom astropy.time import Time\r\nfrom astropy.io import fits\r\nfrom astropy.table import Table\r\nfrom astropy.cosmology import Planck18\r\n\r\n# Units and quantities\r\ndistance = 100 * u.pc\r\ndistance_km = distance.to(u.km)\r\n\r\n# Coordinates\r\ncoord = SkyCoord(ra=10.5*u.degree, dec=41.2*u.degree, frame='icrs')\r\ncoord_galactic = coord.galactic\r\n\r\n# Time\r\nt = Time('2023-01-15 12:30:00')\r\njd = t.jd  # Julian Date\r\n\r\n# FITS files\r\ndata = fits.getdata('image.fits')\r\nheader = fits.getheader('image.fits')\r\n\r\n# Tables\r\ntable = Table.read('catalog.fits')\r\n\r\n# Cosmology\r\nd_L = Planck18.luminosity_distance(z=1.0)\r\n```\r\n\r\n## Core Capabilities\r\n\r\n### 1. Units and Quantities (`astropy.units`)\r\n\r\nHandle physical quantities with units, perform unit conversions, and ensure dimensional consistency in calculations.\r\n\r\n**Key operations:**\r\n- Create quantities by multiplying values with units\r\n- Convert between units using `.to()` method\r\n- Perform arithmetic with automatic unit handling\r\n- Use equivalencies for domain-specific conversions (spectral, doppler, parallax)\r\n- Work with logarithmic units (magnitudes, decibels)\r\n\r\n**See:** `references/units.md` for comprehensive documentation, unit systems, equivalencies, performance optimization, and unit arithmetic.\r\n\r\n### 2. Coordinate Systems (`astropy.coordinates`)\r\n\r\nRepresent celestial positions and transform between different coordinate frames.\r\n\r\n**Key operations:**\r\n- Create coordinates with `SkyCoord` in any frame (ICRS, Galactic, FK5, AltAz, etc.)\r\n- Transform between coordinate systems\r\n- Calculate angular separations and position angles\r\n- Match coordinates to catalogs\r\n- Include distance for 3D coordinate operations\r\n- Handle proper motions and radial velocities\r\n- Query named objects from online databases\r\n\r\n**See:** `references/coordinates.md` for detailed coordinate frame descriptions, transformations, observer-dependent frames (AltAz), catalog matching, and performance tips.\r\n\r\n### 3. Cosmological Calculations (`astropy.cosmology`)\r\n\r\nPerform cosmological calculations using standard cosmological models.\r\n\r\n**Key operations:**\r\n- Use built-in cosmologies (Planck18, WMAP9, etc.)\r\n- Create custom cosmological models\r\n- Calculate distances (luminosity, comoving, angular diameter)\r\n- Compute ages and lookback times\r\n- Determine Hubble parameter at any redshift\r\n- Calculate density parameters and volumes\r\n- Perform inverse calculations (find z for given distance)\r\n\r\n**See:** `references/cosmology.md` for available models, distance calculations, time calculations, density parameters, and neutrino effects.\r\n\r\n### 4. FITS File Handling (`astropy.io.fits`)\r\n\r\nRead, write, and manipulate FITS (Flexible Image Transport System) files.\r\n\r\n**Key operations:**\r\n- Open FITS files with context managers\r\n- Access HDUs (Header Data Units) by index or name\r\n- Read and modify headers (keywords, comments, history)\r\n- Work with image data (NumPy arrays)\r\n- Handle table data (binary and ASCII tables)\r\n- Create new FITS files (single or multi-extension)\r\n- Use memory mapping for large files\r\n- Access remote FITS files (S3, HTTP)\r\n\r\n**See:** `references/fits.md` for comprehensive file operations, header manipulation, image and table handling, multi-extension files, and performance considerations.\r\n\r\n### 5. Table Operations (`astropy.table`)\r\n\r\nWork with tabular data with support for units, metadata, and various file formats.\r\n\r\n**Key operations:**\r\n- Create tables from arrays, lists, or dictionaries\r\n- Read/write tables in multiple formats (FITS, CSV, HDF5, VOTable)\r\n- Access and modify columns and rows\r\n- Sort, filter, and index tables\r\n- Perform database-style operations (join, group, aggregate)\r\n- Stack and concatenate tables\r\n- Work with unit-aware columns (QTable)\r\n- Handle missing data with masking\r\n\r\n**See:** `references/tables.md` for table creation, I/O operations, data manipulation, sorting, filtering, joins, grouping, and performance tips.\r\n\r\n### 6. Time Handling (`astropy.time`)\r\n\r\nPrecise time representation and conversion between time scales and formats.\r\n\r\n**Key operations:**\r\n- Create Time objects in various formats (ISO, JD, MJD, Unix, etc.)\r\n- Convert between time scales (UTC, TAI, TT, TDB, etc.)\r\n- Perform time arithmetic with TimeDelta\r\n- Calculate sidereal time for observers\r\n- Compute light travel time corrections (barycentric, heliocentric)\r\n- Work with time arrays efficiently\r\n- Handle masked (missing) times\r\n\r\n**See:** `references/time.md` for time formats, time scales, conversions, arithmetic, observing features, and precision handling.\r\n\r\n### 7. World Coordinate System (`astropy.wcs`)\r\n\r\nTransform between pixel coordinates in images and world coordinates.\r\n\r\n**Key operations:**\r\n- Read WCS from FITS headers\r\n- Convert pixel coordinates to world coordinates (and vice versa)\r\n- Calculate image footprints\r\n- Access WCS parameters (reference pixel, projection, scale)\r\n- Create custom WCS objects\r\n\r\n**See:** `references/wcs_and_other_modules.md` for WCS operations and transformations.\r\n\r\n## Additional Capabilities\r\n\r\nThe `references/wcs_and_other_modules.md` file also covers:\r\n\r\n### NDData and CCDData\r\nContainers for n-dimensional datasets with metadata, uncertainty, masking, and WCS information.\r\n\r\n### Modeling\r\nFramework for creating and fitting mathematical models to astronomical data.\r\n\r\n### Visualization\r\nTools for astronomical image display with appropriate stretching and scaling.\r\n\r\n### Constants\r\nPhysical and astronomical constants with proper units (speed of light, solar mass, Planck constant, etc.).\r\n\r\n### Convolution\r\nImage processing kernels for smoothing and filtering.\r\n\r\n### Statistics\r\nRobust statistical functions including sigma clipping and outlier rejection.\r\n\r\n## Installation\r\n\r\n```bash\r\n# Install astropy\r\nuv pip install astropy\r\n\r\n# With optional dependencies for full functionality\r\nuv pip install astropy[all]\r\n```\r\n\r\n## Common Workflows\r\n\r\n### Converting Coordinates Between Systems\r\n\r\n```python\r\nfrom astropy.coordinates import SkyCoord\r\nimport astropy.units as u\r\n\r\n# Create coordinate\r\nc = SkyCoord(ra='05h23m34.5s', dec='-69d45m22s', frame='icrs')\r\n\r\n# Transform to galactic\r\nc_gal = c.galactic\r\nprint(f\"l={c_gal.l.deg}, b={c_gal.b.deg}\")\r\n\r\n# Transform to alt-az (requires time and location)\r\nfrom astropy.time import Time\r\nfrom astropy.coordinates import EarthLocation, AltAz\r\n\r\nobserving_time = Time('2023-06-15 23:00:00')\r\nobserving_location = EarthLocation(lat=40*u.deg, lon=-120*u.deg)\r\naa_frame = AltAz(obstime=observing_time, location=observing_location)\r\nc_altaz = c.transform_to(aa_frame)\r\nprint(f\"Alt={c_altaz.alt.deg}, Az={c_altaz.az.deg}\")\r\n```\r\n\r\n### Reading and Analyzing FITS Files\r\n\r\n```python\r\nfrom astropy.io import fits\r\nimport numpy as np\r\n\r\n# Open FITS file\r\nwith fits.open('observation.fits') as hdul:\r\n    # Display structure\r\n    hdul.info()\r\n\r\n    # Get image data and header\r\n    data = hdul[1].data\r\n    header = hdul[1].header\r\n\r\n    # Access header values\r\n    exptime = header['EXPTIME']\r\n    filter_name = header['FILTER']\r\n\r\n    # Analyze data\r\n    mean = np.mean(data)\r\n    median = np.median(data)\r\n    print(f\"Mean: {mean}, Median: {median}\")\r\n```\r\n\r\n### Cosmological Distance Calculations\r\n\r\n```python\r\nfrom astropy.cosmology import Planck18\r\nimport astropy.units as u\r\nimport numpy as np\r\n\r\n# Calculate distances at z=1.5\r\nz = 1.5\r\nd_L = Planck18.luminosity_distance(z)\r\nd_A = Planck18.angular_diameter_distance(z)\r\n\r\nprint(f\"Luminosity distance: {d_L}\")\r\nprint(f\"Angular diameter distance: {d_A}\")\r\n\r\n# Age of universe at that redshift\r\nage = Planck18.age(z)\r\nprint(f\"Age at z={z}: {age.to(u.Gyr)}\")\r\n\r\n# Lookback time\r\nt_lookback = Planck18.lookback_time(z)\r\nprint(f\"Lookback time: {t_lookback.to(u.Gyr)}\")\r\n```\r\n\r\n### Cross-Matching Catalogs\r\n\r\n```python\r\nfrom astropy.table import Table\r\nfrom astropy.coordinates import SkyCoord, match_coordinates_sky\r\nimport astropy.units as u\r\n\r\n# Read catalogs\r\ncat1 = Table.read('catalog1.fits')\r\ncat2 = Table.read('catalog2.fits')\r\n\r\n# Create coordinate objects\r\ncoords1 = SkyCoord(ra=cat1['RA']*u.degree, dec=cat1['DEC']*u.degree)\r\ncoords2 = SkyCoord(ra=cat2['RA']*u.degree, dec=cat2['DEC']*u.degree)\r\n\r\n# Find matches\r\nidx, sep, _ = coords1.match_to_catalog_sky(coords2)\r\n\r\n# Filter by separation threshold\r\nmax_sep = 1 * u.arcsec\r\nmatches = sep < max_sep\r\n\r\n# Create matched catalogs\r\ncat1_matched = cat1[matches]\r\ncat2_matched = cat2[idx[matches]]\r\nprint(f\"Found {len(cat1_matched)} matches\")\r\n```\r\n\r\n## Best Practices\r\n\r\n1. **Always use units**: Attach units to quantities to avoid errors and ensure dimensional consistency\r\n2. **Use context managers for FITS files**: Ensures proper file closing\r\n3. **Prefer arrays over loops**: Process multiple coordinates/times as arrays for better performance\r\n4. **Check coordinate frames**: Verify the frame before transformations\r\n5. **Use appropriate cosmology**: Choose the right cosmological model for your analysis\r\n6. **Handle missing data**: Use masked columns for tables with missing values\r\n7. **Specify time scales**: Be explicit about time scales (UTC, TT, TDB) for precise timing\r\n8. **Use QTable for unit-aware tables**: When table columns have units\r\n9. **Check WCS validity**: Verify WCS before using transformations\r\n10. **Cache frequently used values**: Expensive calculations (e.g., cosmological distances) can be cached\r\n\r\n## Documentation and Resources\r\n\r\n- Official Astropy Documentation: https://docs.astropy.org/en/stable/\r\n- Tutorials: https://learn.astropy.org/\r\n- GitHub: https://github.com/astropy/astropy\r\n\r\n## Reference Files\r\n\r\nFor detailed information on specific modules:\r\n- `references/units.md` - Units, quantities, conversions, and equivalencies\r\n- `references/coordinates.md` - Coordinate systems, transformations, and catalog matching\r\n- `references/cosmology.md` - Cosmological models and calculations\r\n- `references/fits.md` - FITS file operations and manipulation\r\n- `references/tables.md` - Table creation, I/O, and operations\r\n- `references/time.md` - Time formats, scales, and calculations\r\n- `references/wcs_and_other_modules.md` - WCS, NDData, modeling, visualization, constants, and utilities",
    "user_template": ""
  },
  "variables": [],
  "install": {
    "steps": [
      {
        "title": "Download & unzip",
        "detail": "Download the .zip package from SkillVault and unzip it. The astropy/ folder contains SKILL.md plus any companion scripts, references and assets."
      },
      {
        "title": "Copy into your agent skills directory",
        "detail": "Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code), .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or reload the session."
      },
      {
        "title": "Use it",
        "detail": "Describe the task in natural language; the agent loads the skill automatically when the request matches the skill description."
      }
    ]
  },
  "usage": {
    "steps": []
  },
  "metadata": {
    "author": "SkillVault",
    "source": "https://skillvault.top/skills/astropy",
    "exported_at": "2026-11-03T07:42:46.703Z"
  }
}

format: aiskill/v1
skill:
  name: astropy
  slug: astropy
  version: 1.0.0
  description: >-
    Comprehensive Python library for astronomy and astrophysics. This skill should be used when
    working with astronomical data including celestial coordinates, physical units, FITS files,
    cosmological calculations, time systems, tables, world coordinate systems (WCS), and
    astronomical data analysis. Use when tasks involve coordinate transformations, unit conversions,
    FITS file manipulation, cosmological distance calculations, time scale conversions, or
    astronomical data processing.
  category: Research
  tags:
    - research-science
    - python
  platforms:
    - chatgpt
    - claude-code
    - cursor
  tested_environment: >-
    Agent Skills convention (SKILL.md) — works with Claude Code, Cursor, ChatGPT/Codex and
    compatible agents
  license: BSD-3-CLAUSE LICENSE
prompts:
  system: "# Astropy\r\n\r\n## Overview\r\n\r\nAstropy is the core Python package for astronomy, providing essential functionality for astronomical research and data analysis. Use astropy for coordinate transformations, unit and quantity calculations, FITS file operations, cosmological calculations, precise time handling, tabular data manipulation, and astronomical image processing.\r\n\r\n## When to Use This Skill\r\n\r\nUse astropy when tasks involve:\r\n- Converting between celestial coordinate systems (ICRS, Galactic, FK5, AltAz, etc.)\r\n- Working with physical units and quantities (converting Jy to mJy, parsecs to km, etc.)\r\n- Reading, writing, or manipulating FITS files (images or tables)\r\n- Cosmological calculations (luminosity distance, lookback time, Hubble parameter)\r\n- Precise time handling with different time scales (UTC, TAI, TT, TDB) and formats (JD, MJD, ISO)\r\n- Table operations (reading catalogs, cross-matching, filtering, joining)\r\n- WCS transformations between pixel and world coordinates\r\n- Astronomical constants and calculations\r\n\r\n## Quick Start\r\n\r\n```python\r\nimport astropy.units as u\r\nfrom astropy.coordinates import SkyCoord\r\nfrom astropy.time import Time\r\nfrom astropy.io import fits\r\nfrom astropy.table import Table\r\nfrom astropy.cosmology import Planck18\r\n\r\n# Units and quantities\r\ndistance = 100 * u.pc\r\ndistance_km = distance.to(u.km)\r\n\r\n# Coordinates\r\ncoord = SkyCoord(ra=10.5*u.degree, dec=41.2*u.degree, frame='icrs')\r\ncoord_galactic = coord.galactic\r\n\r\n# Time\r\nt = Time('2023-01-15 12:30:00')\r\njd = t.jd  # Julian Date\r\n\r\n# FITS files\r\ndata = fits.getdata('image.fits')\r\nheader = fits.getheader('image.fits')\r\n\r\n# Tables\r\ntable = Table.read('catalog.fits')\r\n\r\n# Cosmology\r\nd_L = Planck18.luminosity_distance(z=1.0)\r\n```\r\n\r\n## Core Capabilities\r\n\r\n### 1. Units and Quantities (`astropy.units`)\r\n\r\nHandle physical quantities with units, perform unit conversions, and ensure dimensional consistency in calculations.\r\n\r\n**Key operations:**\r\n- Create quantities by multiplying values with units\r\n- Convert between units using `.to()` method\r\n- Perform arithmetic with automatic unit handling\r\n- Use equivalencies for domain-specific conversions (spectral, doppler, parallax)\r\n- Work with logarithmic units (magnitudes, decibels)\r\n\r\n**See:** `references/units.md` for comprehensive documentation, unit systems, equivalencies, performance optimization, and unit arithmetic.\r\n\r\n### 2. Coordinate Systems (`astropy.coordinates`)\r\n\r\nRepresent celestial positions and transform between different coordinate frames.\r\n\r\n**Key operations:**\r\n- Create coordinates with `SkyCoord` in any frame (ICRS, Galactic, FK5, AltAz, etc.)\r\n- Transform between coordinate systems\r\n- Calculate angular separations and position angles\r\n- Match coordinates to catalogs\r\n- Include distance for 3D coordinate operations\r\n- Handle proper motions and radial velocities\r\n- Query named objects from online databases\r\n\r\n**See:** `references/coordinates.md` for detailed coordinate frame descriptions, transformations, observer-dependent frames (AltAz), catalog matching, and performance tips.\r\n\r\n### 3. Cosmological Calculations (`astropy.cosmology`)\r\n\r\nPerform cosmological calculations using standard cosmological models.\r\n\r\n**Key operations:**\r\n- Use built-in cosmologies (Planck18, WMAP9, etc.)\r\n- Create custom cosmological models\r\n- Calculate distances (luminosity, comoving, angular diameter)\r\n- Compute ages and lookback times\r\n- Determine Hubble parameter at any redshift\r\n- Calculate density parameters and volumes\r\n- Perform inverse calculations (find z for given distance)\r\n\r\n**See:** `references/cosmology.md` for available models, distance calculations, time calculations, density parameters, and neutrino effects.\r\n\r\n### 4. FITS File Handling (`astropy.io.fits`)\r\n\r\nRead, write, and manipulate FITS (Flexible Image Transport System) files.\r\n\r\n**Key operations:**\r\n- Open FITS files with context managers\r\n- Access HDUs (Header Data Units) by index or name\r\n- Read and modify headers (keywords, comments, history)\r\n- Work with image data (NumPy arrays)\r\n- Handle table data (binary and ASCII tables)\r\n- Create new FITS files (single or multi-extension)\r\n- Use memory mapping for large files\r\n- Access remote FITS files (S3, HTTP)\r\n\r\n**See:** `references/fits.md` for comprehensive file operations, header manipulation, image and table handling, multi-extension files, and performance considerations.\r\n\r\n### 5. Table Operations (`astropy.table`)\r\n\r\nWork with tabular data with support for units, metadata, and various file formats.\r\n\r\n**Key operations:**\r\n- Create tables from arrays, lists, or dictionaries\r\n- Read/write tables in multiple formats (FITS, CSV, HDF5, VOTable)\r\n- Access and modify columns and rows\r\n- Sort, filter, and index tables\r\n- Perform database-style operations (join, group, aggregate)\r\n- Stack and concatenate tables\r\n- Work with unit-aware columns (QTable)\r\n- Handle missing data with masking\r\n\r\n**See:** `references/tables.md` for table creation, I/O operations, data manipulation, sorting, filtering, joins, grouping, and performance tips.\r\n\r\n### 6. Time Handling (`astropy.time`)\r\n\r\nPrecise time representation and conversion between time scales and formats.\r\n\r\n**Key operations:**\r\n- Create Time objects in various formats (ISO, JD, MJD, Unix, etc.)\r\n- Convert between time scales (UTC, TAI, TT, TDB, etc.)\r\n- Perform time arithmetic with TimeDelta\r\n- Calculate sidereal time for observers\r\n- Compute light travel time corrections (barycentric, heliocentric)\r\n- Work with time arrays efficiently\r\n- Handle masked (missing) times\r\n\r\n**See:** `references/time.md` for time formats, time scales, conversions, arithmetic, observing features, and precision handling.\r\n\r\n### 7. World Coordinate System (`astropy.wcs`)\r\n\r\nTransform between pixel coordinates in images and world coordinates.\r\n\r\n**Key operations:**\r\n- Read WCS from FITS headers\r\n- Convert pixel coordinates to world coordinates (and vice versa)\r\n- Calculate image footprints\r\n- Access WCS parameters (reference pixel, projection, scale)\r\n- Create custom WCS objects\r\n\r\n**See:** `references/wcs_and_other_modules.md` for WCS operations and transformations.\r\n\r\n## Additional Capabilities\r\n\r\nThe `references/wcs_and_other_modules.md` file also covers:\r\n\r\n### NDData and CCDData\r\nContainers for n-dimensional datasets with metadata, uncertainty, masking, and WCS information.\r\n\r\n### Modeling\r\nFramework for creating and fitting mathematical models to astronomical data.\r\n\r\n### Visualization\r\nTools for astronomical image display with appropriate stretching and scaling.\r\n\r\n### Constants\r\nPhysical and astronomical constants with proper units (speed of light, solar mass, Planck constant, etc.).\r\n\r\n### Convolution\r\nImage processing kernels for smoothing and filtering.\r\n\r\n### Statistics\r\nRobust statistical functions including sigma clipping and outlier rejection.\r\n\r\n## Installation\r\n\r\n```bash\r\n# Install astropy\r\nuv pip install astropy\r\n\r\n# With optional dependencies for full functionality\r\nuv pip install astropy[all]\r\n```\r\n\r\n## Common Workflows\r\n\r\n### Converting Coordinates Between Systems\r\n\r\n```python\r\nfrom astropy.coordinates import SkyCoord\r\nimport astropy.units as u\r\n\r\n# Create coordinate\r\nc = SkyCoord(ra='05h23m34.5s', dec='-69d45m22s', frame='icrs')\r\n\r\n# Transform to galactic\r\nc_gal = c.galactic\r\nprint(f\"l={c_gal.l.deg}, b={c_gal.b.deg}\")\r\n\r\n# Transform to alt-az (requires time and location)\r\nfrom astropy.time import Time\r\nfrom astropy.coordinates import EarthLocation, AltAz\r\n\r\nobserving_time = Time('2023-06-15 23:00:00')\r\nobserving_location = EarthLocation(lat=40*u.deg, lon=-120*u.deg)\r\naa_frame = AltAz(obstime=observing_time, location=observing_location)\r\nc_altaz = c.transform_to(aa_frame)\r\nprint(f\"Alt={c_altaz.alt.deg}, Az={c_altaz.az.deg}\")\r\n```\r\n\r\n### Reading and Analyzing FITS Files\r\n\r\n```python\r\nfrom astropy.io import fits\r\nimport numpy as np\r\n\r\n# Open FITS file\r\nwith fits.open('observation.fits') as hdul:\r\n    # Display structure\r\n    hdul.info()\r\n\r\n    # Get image data and header\r\n    data = hdul[1].data\r\n    header = hdul[1].header\r\n\r\n    # Access header values\r\n    exptime = header['EXPTIME']\r\n    filter_name = header['FILTER']\r\n\r\n    # Analyze data\r\n    mean = np.mean(data)\r\n    median = np.median(data)\r\n    print(f\"Mean: {mean}, Median: {median}\")\r\n```\r\n\r\n### Cosmological Distance Calculations\r\n\r\n```python\r\nfrom astropy.cosmology import Planck18\r\nimport astropy.units as u\r\nimport numpy as np\r\n\r\n# Calculate distances at z=1.5\r\nz = 1.5\r\nd_L = Planck18.luminosity_distance(z)\r\nd_A = Planck18.angular_diameter_distance(z)\r\n\r\nprint(f\"Luminosity distance: {d_L}\")\r\nprint(f\"Angular diameter distance: {d_A}\")\r\n\r\n# Age of universe at that redshift\r\nage = Planck18.age(z)\r\nprint(f\"Age at z={z}: {age.to(u.Gyr)}\")\r\n\r\n# Lookback time\r\nt_lookback = Planck18.lookback_time(z)\r\nprint(f\"Lookback time: {t_lookback.to(u.Gyr)}\")\r\n```\r\n\r\n### Cross-Matching Catalogs\r\n\r\n```python\r\nfrom astropy.table import Table\r\nfrom astropy.coordinates import SkyCoord, match_coordinates_sky\r\nimport astropy.units as u\r\n\r\n# Read catalogs\r\ncat1 = Table.read('catalog1.fits')\r\ncat2 = Table.read('catalog2.fits')\r\n\r\n# Create coordinate objects\r\ncoords1 = SkyCoord(ra=cat1['RA']*u.degree, dec=cat1['DEC']*u.degree)\r\ncoords2 = SkyCoord(ra=cat2['RA']*u.degree, dec=cat2['DEC']*u.degree)\r\n\r\n# Find matches\r\nidx, sep, _ = coords1.match_to_catalog_sky(coords2)\r\n\r\n# Filter by separation threshold\r\nmax_sep = 1 * u.arcsec\r\nmatches = sep < max_sep\r\n\r\n# Create matched catalogs\r\ncat1_matched = cat1[matches]\r\ncat2_matched = cat2[idx[matches]]\r\nprint(f\"Found {len(cat1_matched)} matches\")\r\n```\r\n\r\n## Best Practices\r\n\r\n1. **Always use units**: Attach units to quantities to avoid errors and ensure dimensional consistency\r\n2. **Use context managers for FITS files**: Ensures proper file closing\r\n3. **Prefer arrays over loops**: Process multiple coordinates/times as arrays for better performance\r\n4. **Check coordinate frames**: Verify the frame before transformations\r\n5. **Use appropriate cosmology**: Choose the right cosmological model for your analysis\r\n6. **Handle missing data**: Use masked columns for tables with missing values\r\n7. **Specify time scales**: Be explicit about time scales (UTC, TT, TDB) for precise timing\r\n8. **Use QTable for unit-aware tables**: When table columns have units\r\n9. **Check WCS validity**: Verify WCS before using transformations\r\n10. **Cache frequently used values**: Expensive calculations (e.g., cosmological distances) can be cached\r\n\r\n## Documentation and Resources\r\n\r\n- Official Astropy Documentation: https://docs.astropy.org/en/stable/\r\n- Tutorials: https://learn.astropy.org/\r\n- GitHub: https://github.com/astropy/astropy\r\n\r\n## Reference Files\r\n\r\nFor detailed information on specific modules:\r\n- `references/units.md` - Units, quantities, conversions, and equivalencies\r\n- `references/coordinates.md` - Coordinate systems, transformations, and catalog matching\r\n- `references/cosmology.md` - Cosmological models and calculations\r\n- `references/fits.md` - FITS file operations and manipulation\r\n- `references/tables.md` - Table creation, I/O, and operations\r\n- `references/time.md` - Time formats, scales, and calculations\r\n- `references/wcs_and_other_modules.md` - WCS, NDData, modeling, visualization, constants, and utilities"
  user_template: ""
variables: []
install:
  steps:
    - title: Download & unzip
      detail: >-
        Download the .zip package from SkillVault and unzip it. The astropy/ folder contains
        SKILL.md plus any companion scripts, references and assets.
    - title: Copy into your agent skills directory
      detail: >-
        Move the folder into your agent's skills directory — e.g. ~/.claude/skills/ (Claude Code),
        .codex/skills/, .cursor/skills/ or your project's .claude/skills/ folder — then restart or
        reload the session.
    - title: Use it
      detail: >-
        Describe the task in natural language; the agent loads the skill automatically when the
        request matches the skill description.
usage:
  steps: []
metadata:
  author: SkillVault
  source: https://skillvault.top/skills/astropy
  exported_at: "2026-11-03T07:42:46.703Z"