astro py:docs

- Index
- Modules

### Navigation

- next »
- « previous |
- Astropy v0.3 »
- Astronomical Coordinate Systems (`astropy.coordinates`) »
- SphericalCoordinatesBase

# SphericalCoordinatesBase

class `astropy.coordinates.coordsystems.``SphericalCoordinatesBase`(*args, **kwargs)

  Bases: `object`

  Abstract superclass for all coordinate classes representing points in three dimensions.

  Notes

  Subclasses must implement `__init__`, and define the `latangle` and `lonangle` properties. They may also override the `equinox` property, or leave it unaltered to indicate the coordinates are equinoxless.

  `_initialize_latlon` is provided to implement typical initialization features, and should be called from a subclass’ `__init__`. See the classes in `astropy.coordinates.builtin_systems` for examples of this.

  Attributes Summary

  `cartesian` |
  `distance` | The radial distance for this coordinate object as an `Distance` object.
  `equinox` | The equinox of this system, or None to indicate no equinox specified.
  `isscalar` | True if this coordinate contains scalar angles/distances, or False if
  `latangle` | The latitudinal/elevation angle for these coordinates as an `Angle` object.
  `lonangle` | The longitudinal/azimuthal angle for these coordinates as an `Angle` object.
  `x` |
  `y` |
  `z` |

  Methods Summary

  `from_name`(name) | Given a name, query the CDS name resolver to attempt to retrieve coordinate information for that object.
  `is_transformable_to`(tosys) | Determines if this coordinate can be transformed to a particular system.
  `match_to_catalog_3d`(catalogcoord[, nthneighbor]) | Finds the nearest 3-dimensional matches of this coordinate to a set of catalog coordinates.
  `match_to_catalog_sky`(catalogcoord[, nthneighbor]) | Finds the nearest on-sky matches of this coordinate in a set of catalog coordinates.
  `separation`(other) | Computes on-sky separation between this coordinate and another.
  `separation_3d`(other) | Computes three dimensional separation between this coordinate and another.
  `to_string`([style]) | A string representation of the coordinates.
  `transform_to`(tosys) | Transform this coordinate to a new system.

  Attributes Documentation

  `cartesian`
  `distance`

    The radial distance for this coordinate object as an `Distance` object.

    If set as a tuple, the tuple will be passed into the `Distance` constructor.

    Alternatively, this may be `None`, indicating an unknown/not given distance. Where necessary, this object will be interpreted as angles on the unit sphere.

  `equinox`

    The equinox of this system, or None to indicate no equinox specified.

  `isscalar`

    True if this coordinate contains scalar angles/distances, or False if they are array-like

  `latangle`

    The latitudinal/elevation angle for these coordinates as an `Angle` object.

    Subclasses will often provide properties returning the same object, but with a name more appropriate for the particular subclass.

  `lonangle`

    The longitudinal/azimuthal angle for these coordinates as an `Angle` object.

    Subclasses will often provide properties returning the same object, but with a name more appropriate for the particular subclass.

  `x`
  `y`
  `z`

  Methods Documentation

  classmethod `from_name`(name)

    Given a name, query the CDS name resolver to attempt to retrieve coordinate information for that object. The search database, sesame url, and query timeout can be set through configuration items in `astropy.coordinates.name_resolve` – see docstring for `astropy.coordinates.name_resolve.get_icrs_coordinates` for more information.

    Parameters:

    name : str

    > The name of the object to get coordinates for, e.g. m42.

    Returns:

    coord : SphericalCoordinatesBase

    > Instance of a Coordinates class, specified by the class this is called on, e.g. if `Galactic.from_name('m42')`, will get an instance of `Galactic` representing the position of M42.

  `is_transformable_to`(tosys)

    Determines if this coordinate can be transformed to a particular system.

    Parameters:

    tosys : class

    > The system to transform this coordinate into.

    Returns:

    transformable : bool or str

    > True if this can be trasnformed to `tosys`, False if not. The string ‘same’ if `tosys` is the same system as this object (i.e. no transformation is needed).

  `match_to_catalog_3d`(catalogcoord, nthneighbor=1)

    Finds the nearest 3-dimensional matches of this coordinate to a set of catalog coordinates.

    This finds the 3-dimensional closest neighbor, which is only different from the on-sky distance if `distance` is set in this object or the `catalogcoord` object.

    Parameters:

    catalogcoord : `SphericalCoordinatesBase`

    > The base catalog in which to search for matches. Typically this will be a coordinate object that is an array (i.e., `catalogcoord.isscalar == False`)

    nthneighbor : int, optional

    > Which closest neighbor to search for. Typically `1` is desired here, as that is correct for matching one set of coordinates to another. The next likely use case is `2`, for matching a coordinate catalog against itself (`1` is inappropriate because each point will find itself as the closest match).

    Returns:

    idx : integer array

    > Indecies into `catalogcoord` to get the matched points for each `matchcoord`. Shape matches this coordinate.

    sep2d : `Angle`

    > The on-sky separation between the closest match for each `matchcoord` and the `matchcoord`. Shape matches `matchcoord`.

    dist3d : `Quantity`

    > The 3D distance between the closest match for each `matchcoord` and the `matchcoord`. Shape matches this coordinate.

    See also

    `astropy.coordinates.matching.match_coordinates_3d`

    Notes

    This method requires `scipy` to be installed or it will fail.

  `match_to_catalog_sky`(catalogcoord, nthneighbor=1)

    Finds the nearest on-sky matches of this coordinate in a set of catalog coordinates.

    Parameters:

    catalogcoord : `SphericalCoordinatesBase`

    > The base catalog in which to search for matches. Typically this will be a coordinate object that is an array (i.e., `catalogcoord.isscalar == False`)

    nthneighbor : int, optional

    > Which closest neighbor to search for. Typically `1` is desired here, as that is correct for matching one set of coordinates to another. The next likely use case is `2`, for matching a coordinate catalog against itself (`1` is inappropriate because each point will find itself as the closest match).

    Returns:

    idx : integer array

    > Indecies into `catalogcoord` to get the matched points for each `matchcoord`. Shape matches this coordinate.

    sep2d : `Angle`

    > The on-sky separation between the closest match for each `matchcoord` and the `matchcoord`. Shape matches `matchcoord`.

    dist3d : `Quantity`

    > The 3D distance between the closest match for each `matchcoord` and the `matchcoord`. Shape matches this coordinate.

    See also

    `astropy.coordinates.matching.match_coordinates_sky`

    Notes

    This method requires `scipy` to be installed or it will fail.

  `separation`(other)

    Computes on-sky separation between this coordinate and another.

    Parameters:

    other : `SphericalCoordinatesBase`

    > The coordinate to get the separation to.

    Returns:

    sep : `Angle`

    > The on-sky separation between this and the `other` coordinate.

    Notes

    The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [R2].

    [R2] | http://en.wikipedia.org/wiki/Great-circle_distance

  `separation_3d`(other)

    Computes three dimensional separation between this coordinate and another.

    Parameters:

    other : `SphericalCoordinatesBase`

    > The coordinate system to get the distance to.

    Returns:

    sep : `Distance`

    > The real-space distance between these two coordinates.

    Raises:

    ValueError :

    > If this or the other coordinate do not have distances.

  `to_string`(style=None, **kwargs)

    A string representation of the coordinates.

    See `astropy.coordinates.Angle.to_string()` for details and keyword arguments (the two angles forming the coordinates are are both `astropy.coordinates.Angle` instances). Keyword arguments are passed to `astropy.coordinates.Angle.to_string()`.

    Parameters:

    style : {‘hmsdms’, ‘dms’, ‘decimal’, None}

    > The formatting specification to use. These encode the three most common ways to represent coordinates. If `None` is passed, the defaults for the current coordinate class is used.

    kwargs :

    > Keyword arguments are passed to `astropy.coordinates.Angle.to_string()`.

  `transform_to`(tosys)

    Transform this coordinate to a new system.

    Parameters:

    tosys : class

    > The system to transform this coordinate into.

    Returns:

    transcoord :

    > A new object with this coordinate represented in the `tosys` system.

    Raises:

    ValueError :

    > If there is no possible transformation route.