# spacepy.coordinates.Coords

class spacepy.coordinates.Coords(data, dtype, carsph[, units, ticks, use_irbem])

  A class holding spatial coordinates and enabling transformation between coordinate systems. Coordinates can be stored as Cartesian or spherical and units are assumed to be Re (distance) and degrees (angle)

  Note

  Although other units may be specified and will be carried through, most functions throughout SpacePy assume distances in Re and angles in degrees, regardless of specified units.

  By default, coordinate transforms are based on the IRBEM library; its manual may prove useful. SpacePy also provides a framework for accurate coordinate transformations. This can be used by setting the use_irbem flag to False. In a future release of SpacePy this will become the default method. For a good reference on heliospheric and magnetospheric coordinate systems, see Franz & Harper, “Heliospheric Coordinate Systems”, Planet. Space Sci., 50, pp 217-233, 2002 (https://doi.org/10.1016/S0032-0633(01)00119-2).

  Parameters
    data list or ndarray, dim = (n,3)

      coordinate points [X,Y,Z] or [rad, lat, lon]

    dtype string

      coordinate system; supported systems are defined in module-level documentation. Common systems include GEO, GSE, GSM, SM, MAG, ECIMOD

    carsph string

      Cartesian or spherical, ‘car’ or ‘sph’

    units list of strings, optional

      standard are [‘Re’, ‘Re’, ‘Re’] or [‘Re’, ‘deg’, ‘deg’] depending on the carsph content. See note.

    ticks Ticktock instance, optional

      used for coordinate transformations (see a.convert)

    use_irbem bool

      New in version 0.3.0.

      Set to True to use IRBEM for coordinate transforms (current default). Otherwise use SpacePy’s coordinate transform library.

  Returns
    out Coords instance

      instance with a.data, a.carsph, etc.

  See also

  `spacepy.coordinates.DEFAULTS`
  `spacepy.time.Ticktock`

  Examples

      >>> from spacepy import coordinates as coord
      >>> cvals = coord.Coords([[1,2,4],[1,2,2]], 'GEO', 'car')
      >>> cvals.x  # returns all x coordinates
      array([1, 1])
      >>> from spacepy.time import Ticktock
      >>> cvals.ticks = Ticktock(['2002-02-02T12:00:00', '2002-02-02T12:00:00'], 'ISO') # add ticks
      >>> newcoord = cvals.convert('GSM', 'sph')
      >>> newcoord

  `append`(other) | Append another Coords instance to the current one
  `convert`(returntype, returncarsph) | Create a new Coords instance with new coordinate types
  `from_skycoord`(skycoord[, use_irbem]) | Create a Coords instance from an Astropy SkyCoord instance

  append(other)

    Append another Coords instance to the current one

    Parameters
      other Coords instance

        Coords instance to append

  convert(returntype, returncarsph)

    Create a new Coords instance with new coordinate types

    Parameters
      returntype string

        coordinate system, see module level documentation for supported systems

      returncarsph string

        coordinate type, possible ‘car’ for Cartesian and ‘sph’ for spherical

    Returns
      out Coords object

        Coords object in the new coordinate system

    Examples

        >>> from spacepy.coordinates import Coords
        >>> y = Coords([[1,2,4],[1,2,2]], 'GEO', 'car')
        >>> from spacepy.time import Ticktock
        >>> y.ticks = Ticktock(['2002-02-02T12:00:00', '2002-02-02T12:00:00'], 'ISO')
        >>> x = y.convert('SM','car')
        >>> x
        Coords( [[ 0.81134097  2.6493305   3.6500375 ]
         [ 0.92060408  2.30678864  1.68262126]] ), dtype=SM,car, units=['Re', 'Re', 'Re']

  classmethod from_skycoord(skycoord, use_irbem=None)

    Create a Coords instance from an Astropy SkyCoord instance

    Parameters
      skycoord astropy.coordinates.SkyCoord

        The coordinate to be converted

    Returns
      out Coords instance

        The converted coordinate

    Notes

    This method requires Astropy to be installed.

    This method uses the GEO coordinate frame as the common frame between the two libraries.

  to_skycoord()

    Create an Astropy SkyCoord instance based on this instance

    Returns
      out astropy.coordinates.SkyCoord

        This coordinate as an Astropy SkyCoord

    Notes

    This method requires Astropy to be installed.

    This method uses the GEO coordinate frame as the common frame between the two libraries.