SphericalCoordinates

class sofia_redux.scan.coordinate_systems.spherical_coordinates.SphericalCoordinates(coordinates=None, unit='degree', copy=True)

Bases: Coordinate2D

Initialize a SphericalCoordinates object.

Spherical coordinates are designed to represent longitude/latitude coordinates in a given frame.

Parameters:

coordinateslist or tuple or array-like or units.Quantity, optional

The coordinates used to populate the object during initialization. The first (0) value or index should represent longitudinal coordinates, and the second should represent latitude.

unitunits.Unit or str, optional

The angular unit for the spherical coordinates. The default is ‘degree’.

copybool, optional

Whether to explicitly perform a copy operation on the input coordinates when storing them into these coordinates. Note that it is extremely unlikely for the original coordinates to be passed in as a reference due to the significant checks performed on them.

Attributes Summary

angular_accuracy
coordinate_system	Return the coordinate system.
empty_copy_skip_attributes	Return attributes that are set to None on an empty copy.
fits_latitude_stem	Return the string prefix for latitude.
fits_longitude_stem	Return the string prefix for longitude.
fits_types
id_lookup
ids
lat	Return the latitude.
latitude	Return the latitude.
latitude_axis	Return the latitude axis.
local_coordinate_system	Return the local coordinate system.
lon	Return the longitude.
longitude	Return the longitude.
longitude_axis	Return the longitude axis.
native_latitude	Return the native latitude.
native_longitude	Return the native longitude.
offset_unit	Return the units used for the offset frame.
pi
reverse_latitude	Return True if the latitude axis is reversed.
reverse_longitude	Return True if the longitude axis is reversed.
right_angle
two_letter_code	Return the two-letter code for the coordinate system.
two_pi
x_offset_axis	Return the offset x-axis.
y_offset_axis	Return the offset y-axis.

Methods Summary

add_native_offset(offset)	Add a native offset to the native coordinates.
add_offset(offset)	Add spherical offsets to native coordinates.
add_y(y)	Add y to coordinates.
copy()	Return a copy of the spherical coordinates.
create_axis(label, short_label[, unit])	Create an axis.
create_offset_axis(label, short_label[, unit])	Create an offset axis.
distance_to(reference)	Return the distance from these coordinates to a given reference.
edit_header(header, key_stem[, alt])	Edit the header with spherical coordinate information.
equal_angles(angle1, angle2)	Check whether angles are equal.
get_class_for(spec)	Return a spherical coordinate class for the given specification.
get_default_system()	Return the default and local default coordinate system.
get_fits_class(ctype)	Return a Coordinate class for the given ctype.
get_indices(indices)	Return selected data for given indices.
get_native_offset_from(reference[, offset])	Get the native offset from a reference system.
get_offset_from(reference[, offset])	Get the spherical offset from a native reference position.
get_projected(projection)	Get the projection of this system.
get_two_letter_class(class_id)	Return a Coordinate class for the given class ID.
get_two_letter_code_for(class_type)	Return the two-letter code for a given coordinate class.
insert_blanks(insert_indices)	Insert blank (NaN) values at the requested indices.
inverse_transform(pole, phi0[, ...])	Inversely transform spherical coordinates from a pole.
invert_y()	Scale the y-coordinates by -1.
merge(other)	Append other coordinates to the end of these.
nan([indices])	Set all coordinates to NaN.
parse_header(header, key_stem[, alt, default])	Set the coordinate from the header.
paste(coordinates, indices)	Paste new coordinate values at the given indices.
plot(*args, **kwargs)	Plot the coordinates.
project(projection, output_system)	Project the coordinates onto a new frame.
register(coordinate_class)	Register a given coordinate class as an available spherical system.
register_types()	Register a number of coordinate classes for later extraction.
set(coordinates[, copy])	Set the (LON, LAT) coordinates.
set_latitude(latitude[, copy])	Set the latitude coordinates.
set_longitude(longitude[, copy])	Set the longitude coordinates.
set_native(coordinates[, copy])	Set the native (x, y) coordinates.
set_native_latitude(latitude[, copy])	Set the native latitude coordinates.
set_native_longitude(longitude[, copy])	Set the native longitude coordinates.
set_projected(projection, offset_system)	Project offsets onto this system.
set_shape(shape[, empty])	Set the shape of the coordinates.
set_singular([empty])	Create a single coordinate.
set_y(coordinates[, copy])	Set the y coordinates.
setup_coordinate_system()	Setup the system for the coordinates.
shift(n[, fill_value])	Shift the coordinates by a given number of elements.
standardize()	Get all the coordinates within the correct angular range.
subtract_native_offset(offset)	Subtract native offsets from the native coordinates.
subtract_offset(offset)	Subtract spherical offsets from the native coordinates.
subtract_y(y)	Subtract y from coordinates.
transform(pole, phi0[, from_coordinates, ...])	Transform spherical coordinates to a new pole.
zero([indices])	Set all coordinates to zero.
zero_to_two_pi(values)	Return angles in the range 0 -> 2pi.

Attributes Documentation

angular_accuracy = <Quantity 1.e-12 deg>

coordinate_system

Return the coordinate system.

Returns:

CoordinateSystem

empty_copy_skip_attributes

Return attributes that are set to None on an empty copy.

Returns:

attributesset (str)

fits_latitude_stem

Return the string prefix for latitude.

Returns:

str

fits_longitude_stem

Return the string prefix for longitude.

Returns:

str

fits_types = None

id_lookup = None

ids = None

lat

Return the latitude.

Returns:

latitudeastropy.units.Quantity (float or numpy.ndarray)

latitude

Return the latitude.

Returns:

latitudeastropy.units.Quantity (float or numpy.ndarray)

latitude_axis

Return the latitude axis.

Returns:

CoordinateAxis

local_coordinate_system

Return the local coordinate system.

Returns:

CoordinateSystem

lon

Return the longitude.

Returns:

longitudeastropy.units.Quantity (float or numpy.ndarray)

longitude

Return the longitude.

Returns:

longitudeastropy.units.Quantity (float or numpy.ndarray)

longitude_axis

Return the longitude axis.

Returns:

CoordinateAxis

native_latitude

Return the native latitude.

Returns:

astropy.units.Quantity (float or numpy.ndarray)

native_longitude

Return the native longitude.

Returns:

astropy.units.Quantity (float or numpy.ndarray)

offset_unit

Return the units used for the offset frame.

Returns:

astropy.units.Unit

pi = <Quantity 180. deg>

reverse_latitude

Return True if the latitude axis is reversed.

Returns:

bool

reverse_longitude

Return True if the longitude axis is reversed.

Returns:

bool

right_angle = <Quantity 90. deg>

two_letter_code

Return the two-letter code for the coordinate system.

Returns:

str

two_pi = <Quantity 360. deg>

x_offset_axis

Return the offset x-axis.

Returns:

CoordinateAxis

y_offset_axis

Return the offset y-axis.

Returns:

CoordinateAxis

Methods Documentation

add_native_offset(offset)

Add a native offset to the native coordinates.

Parameters:

offsetCoordinate2D

The (x, y) offsets to add.

Returns:

None

add_offset(offset)

Add spherical offsets to native coordinates.

Parameters:

offsetCoordinate2D

The spherical (x, y) offsets to add.

Returns:

None

add_y(y)

Add y to coordinates.

Parameters:

yastropy.units.Quantity (float or numpy.ndarray)

The value(s) to add.

Returns:

None

copy()

Return a copy of the spherical coordinates.

Returns:

SphericalCoordinates

static create_axis(label, short_label, unit='degree')

Create an axis.

Parameters:

labelstr

The name of the axis.

short_labelstr

A shorthand name for the axis.

unitastropy.units.Unit or str, optional

The axis unit.

Returns:

CoordinateAxis

static create_offset_axis(label, short_label, unit='arcsec')

Create an offset axis.

Parameters:

labelstr

The name of the offset axis.

short_labelstr

The shorthand name for the axis.

unitastropy.units.Unit or str, optional

The offset axis unit.

Returns:

CoordinateAxis

distance_to(reference)

Return the distance from these coordinates to a given reference.

Calculates the distance between two spherical sets of coordinates using either the law of cosines or Vincenty’s formulae. First we calculate c as:

c = sin(y) * sin(ry) + cos(y) * phi

where:

phi = cos(ry) * cos(rx - x)

and x, rx are the longitudinal coordinates or the coordinates and reference coordinates respectively, and (y, ry) are the latitudinal coordinates.

if |c| > 0.9 (indicating intermediate distances), the law of cosines is used to return an angle (a) of:

a = acos(c)

Otherwise, Vincenty’s formula is used to return a value of:

a = atan2(B, c)

where:

B = sqrt((cos(ry) * sin(rx - x))^2 +
         (cos(y) * sin(ry) - sin(y) * phi)^2)

Parameters:

referenceSphericalCoordinates

Returns:

astropy.units.Quantity

The angular separation from coordinates to point as an array of shape (n,) in units of coordinates.

edit_header(header, key_stem, alt='')

Edit the header with spherical coordinate information.

Parameters:

headerastropy.io.fits.header.Header

The header to modify.

key_stemstr

The name of the header key to update.

altstr, optional

The alternative coordinate system.

Returns:

None

classmethod equal_angles(angle1, angle2)

Check whether angles are equal.

Parameters:

angle1astropy.units.Quantity

angle2astropy.units.Quantity

Returns:

bool or numpy.ndarray (bool)

classmethod get_class_for(spec)

Return a spherical coordinate class for the given specification.

Parameters:

specstr

The name of, the two-letter code, or an axis ctype name for which to return the correct coordinate class.

Returns:

class (SphericalCoordinates)

classmethod get_default_system()

Return the default and local default coordinate system.

Returns:

system, local_system(CoordinateSystem, CoordinateSystem)

classmethod get_fits_class(ctype)

Return a Coordinate class for the given ctype.

Parameters:

ctypestr

The Coordinate system.

Returns:

class (SphericalCoordinates)

get_indices(indices)

Return selected data for given indices.

Parameters:

indicesslice or list or int or numpy.ndarray (int)

The indices to extract.

Returns:

FlaggedData

get_native_offset_from(reference, offset=None)

Get the native offset from a reference system.

Parameters:

referenceSphericalCoordinates

The native reference position(s).

offsetastropy.units.Quantity, optional

A work array to fill and return as the result. If not supplied, will be an array the same shape as coordinates or reference (whichever is larger).

Returns:

Coordinate2D

get_offset_from(reference, offset=None)

Get the spherical offset from a native reference position.

Parameters:

referenceSphericalCoordinates

The reference position(s).

offsetastropy.units.Quantity, optional

A work array to fill and return as the result. If not supplied, will be an array the same shape as coordinates or reference (whichever is larger).

Returns:

spherical_offsetCoordinate2D

get_projected(projection)

Get the projection of this system.

Parameters:

projectionProjection

Returns:

Coordinate2D

classmethod get_two_letter_class(class_id)

Return a Coordinate class for the given class ID.

Parameters:

class_idstr

The two-letter code for the class.

Returns:

class (SphericalCoordinates)

classmethod get_two_letter_code_for(class_type)

Return the two-letter code for a given coordinate class.

Parameters:

class_typeclass (SphericalCoordinates)

Returns:

two_letter_codestr

insert_blanks(insert_indices)

Insert blank (NaN) values at the requested indices.

Follows the logic of numpy.insert().

Parameters:

insert_indicesnumpy.ndarray (int)

Returns:

None

inverse_transform(pole, phi0, from_coordinates=None, to_coordinates=None)

Inversely transform spherical coordinates from a pole.

Parameters:

poleSphericalCoordinates

The pole from which to transform.

phi0astropy.units.Quantity

The angle phi0.

from_coordinatesSphericalCoordinates, optional

The coordinates to transform from. If not supplied, will be these coordinates.

to_coordinatesSphericalCoordinates, optional

The output coordinate system to transform to on output. The default is this system.

Returns:

outputastropy.units.Quantity (numpy.ndarray)

The transformed coordinates of shape (2, n) or (2,).

invert_y()

Scale the y-coordinates by -1.

Returns:

None

merge(other)

Append other coordinates to the end of these.

Parameters:

otherCoordinate2D

Returns:

None

nan(indices=None)

Set all coordinates to NaN.

Parameters:

indicesslice or numpy.ndarray (int or bool), optional

The indices to set to NaN.

Returns:

None

parse_header(header, key_stem, alt='', default=None)

Set the coordinate from the header.

Parameters:

headerastropy.io.fits.header.Header

The FITS header to read.

key_stemstr

altstr, optional

The alternate coordinate system.

defaultCoordinate2D or units.Quantity or SphericalCoordinates

The (x, y) default coordinate.

Returns:

None

paste(coordinates, indices)

Paste new coordinate values at the given indices.

Parameters:

coordinatesCoordinate2D

indicesnumpy.ndarray (int)

Returns:

None

plot(*args, **kwargs)

Plot the coordinates.

Parameters:

argsvalues

Optional positional parameters to pass into pyplot.plot.

kwargsdict, optional

Optional keyword arguments.

Returns:

None

project(projection, output_system)

Project the coordinates onto a new frame.

Parameters:

projectionProjection

output_systemCoordinate2D

A 2-dimensional output coordinates system.

Returns:

None

classmethod register(coordinate_class)

Register a given coordinate class as an available spherical system.

Parameters:

coordinate_classclass

Returns:

None

classmethod register_types()

Register a number of coordinate classes for later extraction.

Returns:

None

set(coordinates, copy=True)

Set the (LON, LAT) coordinates.

Parameters:

coordinatesastropy.units.Quantity (float or numpy.ndarray)

copybool, optional

If True, copy the coordinates. Otherwise do a reference.

Returns:

None

set_latitude(latitude, copy=True)

Set the latitude coordinates.

Parameters:

latitudeastropy.units.Quantity (numpy.ndarray or float)

The latitude coordinates to update.

copybool, optional

If True, copy the coordinates. Otherwise do a reference.

Returns:

None

set_longitude(longitude, copy=True)

Set the longitude coordinates.

Parameters:

longitudeastropy.units.Quantity (numpy.ndarray or float)

The longitude coordinates to update.

copybool, optional

If True, copy the coordinates. Otherwise do a reference.

Returns:

None

set_native(coordinates, copy=True)

Set the native (x, y) coordinates.

Parameters:

coordinatesCoordinates2D or astropy.units.Quantity (numpy.ndarray)

The native (x, y) coordinates to set. If an array is provided, should be of shape (2,) or (2, n).

copybool, optional

If True, copy the coordinates. Otherwise, reference the coordinates if possible.

Returns:

None

set_native_latitude(latitude, copy=True)

Set the native latitude coordinates.

Parameters:

latitudeastropy.units.Quantity (numpy.ndarray or float)

The native latitude coordinates to update.

copybool, optional

If True, copy the coordinates. Otherwise do a reference.

Returns:

None

set_native_longitude(longitude, copy=True)

Set the native longitude coordinates.

Parameters:

longitudeastropy.units.Quantity (numpy.ndarray or float)

The native longitude coordinates to update.

copybool, optional

If True, copy the coordinates. Otherwise do a reference.

Returns:

None

set_projected(projection, offset_system)

Project offsets onto this system.

Parameters:

projectionProjection

offset_systemCoordinate2D

A 2-dimensional system of offsets.

Returns:

None

set_shape(shape, empty=False)

Set the shape of the coordinates.

Parameters:

shapeint or tuple (int)

emptybool, optional

If True, create an empty array. Otherwise, create a zeroed array.

Returns:

None

set_singular(empty=False)

Create a single coordinate.

Parameters:

emptybool, optional

If True, create an empty coordinate array. Otherwise, create a zeroed array.

Returns:

None

set_y(coordinates, copy=True)

Set the y coordinates.

Parameters:

coordinatesastropy.units.Quantity (float or numpy.ndarray)

copybool, optional

If True, copy the coordinates. Otherwise do a reference.

Returns:

None

setup_coordinate_system()

Setup the system for the coordinates.

Returns:

None

shift(n, fill_value=nan)

Shift the coordinates by a given number of elements.

Parameters:

nint

fill_valuefloat or int or units.Quantity, optional

Returns:

None

standardize()

Get all the coordinates within the correct angular range.

Sets the range of x-coordinates to be in the range -360 < x < 360 degrees, and y-coordinates to the range -180 < y < 180 degrees.

Returns:

None

subtract_native_offset(offset)

Subtract native offsets from the native coordinates.

Parameters:

offsetCoordinate2D

The native (x, y) offsets to subtract.

Returns:

None

subtract_offset(offset)

Subtract spherical offsets from the native coordinates.

Parameters:

offsetCoordinate2D

The spherical (x, y) offsets to subtract.

Returns:

None

subtract_y(y)

Subtract y from coordinates.

Parameters:

yastropy.units.Quantity (float or numpy.ndarray)

The value(s) to subtract.

Returns:

None

transform(pole, phi0, from_coordinates=None, to_coordinates=None, reverse=False)

Transform spherical coordinates to a new pole.

Parameters:

poleSphericalCoordinates

The pole to transform to (or from if reverse`=`True).

phi0astropy.units.Quantity

The angle phi0.

from_coordinatesSphericalCoordinates, optional

The coordinates to transform from. If not supplied, will be these coordinates.

to_coordinatesSphericalCoordinates, optional

The output coordinate system to transform to. The default is this system.

reversebool, optional

If True, perform the inverse transform (from the pole rather than to the pole).

Returns:

outputSphericalCoordinates

zero(indices=None)

Set all coordinates to zero.

Parameters:

indicesslice or numpy.ndarray (int or bool), optional

The indices to set to zero.

Returns:

None

classmethod zero_to_two_pi(values)

Return angles in the range 0 -> 2pi.

Parameters:

valuesastropy.units.Quantity

Returns:

astropy.units.Quantity