SphericalSkyRegion

class regions.SphericalSkyRegion

Bases: Region

Base class for all spherical sky regions (compared to the implicitly planar SkyRegions).

Attributes Summary

bounding_circle	Bounding circle for the spherical sky region.
bounding_lonlat	Bounding longitude and latitude of the spherical sky region, in the region's frame.
frame	Coordinate frame of the region.

Methods Summary

contains(coord)	Check whether a sky coordinate falls inside the spherical sky region.
discretize_boundary([n_points])	Discretize the boundary into a PolygonSphericalSkyRegion, as an approximation where all sides follow great circles.
intersection(other)	Return a region representing the intersection of this region with other.
serialize([format])	Serialize the region to a region string or table.
symmetric_difference(other)	Return the union of the two regions minus any areas contained in the intersection of the two regions.
to_pixel([wcs, ...])	Convert to a planar PixelRegion instance.
to_sky([wcs, include_boundary_distortions, ...])	Convert to a planar SkyRegion instance.
transform_to(frame[, merge_attributes])	Transform the SphericalSkyRegion instance into another instance with a different coordinate reference frame.
union(other)	Return a region representing the union of this region with other.
write(filename[, format, overwrite])	Write the region to a region file in the specified format.

Attributes Documentation

bounding_circle

Bounding circle for the spherical sky region.

Returns:

circle_sph_sky_region: CircleSphericalSkyRegion

A circle spherical sky region object.

bounding_lonlat

Bounding longitude and latitude of the spherical sky region, in the region’s frame.

Returns:

lons_arrlist of Longitude

List of lower, upper boundary longitude values.

lons_arrlist of Latitude

List of lower, upper boundary latitude values.

frame

Coordinate frame of the region.

Methods Documentation

abstractmethod contains(coord)

Check whether a sky coordinate falls inside the spherical sky region.

Parameters:

coordSkyCoord

The position or positions to check.

abstractmethod discretize_boundary(n_points=10)

Discretize the boundary into a PolygonSphericalSkyRegion, as an approximation where all sides follow great circles.

Parameters:

n_pointsint, optional

Number of points along the region’s boundary.

Returns:

poly_sky_region: PolygonSphericalSkyRegion

Spherical sky polygon object.

intersection(other)

Return a region representing the intersection of this region with other.

Parameters:

otherSphericalSkyRegion

The other region to use for the intersection.

serialize(format=None, **kwargs)

Serialize the region to a region string or table.

This method allows serializing regions in many supported data formats, e.g.,:

>>> reg1_str = reg.serialize(format='ds9')
>>> reg2_str = reg.serialize(format='crtf')
>>> reg3_tbl = reg.serialize(format='fits')

A list of the available formats for Region is available using:

>>> from regions import Region
>>> Region.get_formats()

Parameters:

formatstr, optional

The file format specifier.

**kwargsdict, optional

Keyword arguments passed to the data serializer.

symmetric_difference(other)

Return the union of the two regions minus any areas contained in the intersection of the two regions.

Parameters:

otherSphericalSkyRegion

The other region to use for the symmetric difference.

abstractmethod to_pixel(wcs=None, include_boundary_distortions=False, discretize_kwargs=None)

Convert to a planar PixelRegion instance.

Parameters:

wcsWCS instance, optional

The world coordinate system transformation to use to convert between sky and pixel coordinates. Required if transforming with boundary distortions (if include_boundary_distortions is True). Ignored if boundary distortions not included.

include_boundary_distortionsbool, optional

If True, accounts for boundary boundary distortions in spherical to planar conversions, by discretizing the boundary and converting the boundary polygon. Default is False, which converts to an equivalent idealized shape.

discretize_kwargsdict, optional

Optional keyword arguments to pass to discretize_boundary() method if including boundary distortions.

Returns:

pixel_regionPixelRegion

A pixel region, with an equivalent shape (if include_boundary_distortions is False), or a discretized polygon of the boundary (if include_boundary_distortions is True).

abstractmethod to_sky(wcs=None, include_boundary_distortions=False, discretize_kwargs=None)

Convert to a planar SkyRegion instance.

Parameters:

wcsWCS instance, optional

The world coordinate system transformation to use to convert between sky and pixel coordinates. Required if transforming with boundary distortions (if include_boundary_distortions is True). Ignored if boundary distortions not included.

include_boundary_distortionsbool, optional

If True, accounts for boundary boundary distortions in spherical to planar conversions, by discretizing the boundary and converting the boundary polygon. Default is False, which converts to an equivalent idealized shape.

discretize_kwargsdict, optional

Optional keyword arguments to pass to discretize_boundary() method if including boundary distortions.

Returns:

sky_regionSkyRegion

A planar sky region, with an equivalent shape (if include_boundary_distortions is False), or a discretized polygon of the boundary (if include_boundary_distortions is True).

abstractmethod transform_to(frame, merge_attributes=True)

Transform the SphericalSkyRegion instance into another instance with a different coordinate reference frame.

The precise frame transformed to depends on merge_attributes. If False, the destination frame is used exactly as passed in. But this is often not quite what one wants. E.g., suppose one wants to transform an ICRS coordinate that has an obstime attribute to FK4; in this case, one likely would want to use this information. Thus, the default for merge_attributes is True, in which the precedence is as follows: (1) explicitly set (i.e., non-default) values in the destination frame; (2) explicitly set values in the source; (3) default value in the destination frame.

Note that in either case, any explicitly set attributes on the source astropy.coordinates.SkyCoord that are not part of the destination frame’s definition are kept (stored on the resulting astropy.coordinates.SkyCoord), and thus one can round-trip (e.g., from FK4 to ICRS to FK4 without losing obstime).

Parameters:

framestr, or BaseCoordinateFrame class or instance

The frame to transform this coordinate into.

merge_attributesbool, optional

Whether the default attributes in the destination frame are allowed to be overridden by explicitly set attributes in the source (see note above; default: True).

Returns:

sph_sky_regionSphericalSkyRegion

A new spherical sky region represented in the frame frame.

union(other)

Return a region representing the union of this region with other.

Parameters:

otherSphericalSkyRegion

The other region to use for the union.

write(filename, format=None, overwrite=False, **kwargs)

Write the region to a region file in the specified format.

This method allows writing a file in many supported data formats, e.g.,:

>>> reg.write('new_regions.reg', format='ds9')
>>> reg.write('new_regions.crtf', format='crtf')
>>> reg.write('new_regions.fits', format='fits')

A list of the available formats for Region is available using:

>>> from regions import Region
>>> Region.get_formats()

Parameters:

filenamestr

The filename or URL of the file to write.

formatstr, optional

The file format specifier.

overwritebool, optional

If True, overwrite the output file if it exists. Raises an OSError if False and the output file exists. Default is False.

**kwargsdict, optional

Keyword arguments passed to the data writer.