Regions

0.11 verified Mon Apr 27 auth: no python

An Astropy coordinated package for region handling, providing tools for representing and working with astronomical regions (e.g., circles, ellipses, polygons) in various coordinate systems. Current version is 0.11, requiring Python >= 3.11. Releases follow irregular cadence.

pip install regions

Common errors

error TypeError: 'module' object is not callable ↓

cause Using `regions.Region(...)` which is deprecated and no longer works in newer versions.

fix

Use explicit region constructors like regions.CircleSkyRegion(...) or regions.EllipseSkyRegion(...).

error AttributeError: module 'regions' has no attribute 'read_ds9' ↓

cause The `read_ds9` function was moved to `regions.io.ds9` in version 0.7.

fix

Use from regions.io.ds9 import read_ds9 or regions.io.ds9.read_ds9(filename).

error TypeError: 'str' object has no attribute 'ra' ↓

cause Passing a string coordinate (e.g., '10.68458 41.26917') instead of a `SkyCoord` object to a region constructor.

fix

Convert the string to SkyCoord first: center = SkyCoord('10.68458 41.26917', unit=u.deg).

Warnings

deprecated The old convenience function `regions.Region` for auto-detecting region format from a string is deprecated. Use explicit constructors like `CircleSkyRegion` or `regions.Region.parse()`. ↓

fix Replace `regions.Region('circle ...')` with `regions.CircleSkyRegion(...)` or `regions.Region.parse('circle ...')`.

gotcha Region constructors expect `center` as a `SkyCoord` object for sky regions, not bare tuples or strings. Passing a tuple leads to confusing errors. ↓

fix Always convert coordinates to `SkyCoord` before passing to region constructors.

breaking In version 0.7, the `regions.io` module was reorganized. Functions like `write_ds9` moved to `regions.io.ds9.write_all`. Old imports break. ↓

fix Update imports: `from regions.io.ds9 import write_all` instead of `from regions.io import write_ds9`.

gotcha When reading DS9 region files, the `read_ds9` function returns a `Regions` (list-like) object, not a single region. Looping or indexing is needed to access individual regions. ↓

fix Use `regions = regions.io.ds9.read_ds9(filename)` then iterate or index.

Imports

regions
```
import regions
```

Quickstart

Creates a circular sky region using SkyCoord and basic units.

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

# Create a circular region at RA=10.68458, Dec=41.26917 (degrees) with radius=0.1 deg
center = SkyCoord(10.68458, 41.26917, unit=u.deg)
region = regions.CircleSkyRegion(center, 0.1 * u.deg)
print(region)