boinor.frames.fixed =================== .. py:module:: boinor.frames.fixed .. autoapi-nested-parse:: module fixed from the sub-package frames to handle body-fixed frames in the solar system Attributes ---------- .. autoapisummary:: boinor.frames.fixed.ITRS Classes ------- .. autoapisummary:: boinor.frames.fixed.SunFixed boinor.frames.fixed.MercuryFixed boinor.frames.fixed.VenusFixed boinor.frames.fixed.MarsFixed boinor.frames.fixed.JupiterFixed boinor.frames.fixed.SaturnFixed boinor.frames.fixed.UranusFixed boinor.frames.fixed.NeptuneFixed Module Contents --------------- .. py:data:: ITRS .. py:class:: SunFixed(*args, copy=True, representation_type=None, differential_type=None, **kwargs) Bases: :py:obj:`_PlanetaryFixed` non-inertial, body-fixed reference frame: Sun .. py:attribute:: body .. py:attribute:: equatorial .. py:attribute:: obstime .. py:method:: to_equatorial(fixed_coo, equatorial_frame) :staticmethod: convert coordinates of a fixed coordinate system to an equatorial one .. py:method:: from_equatorial(equatorial_coo, fixed_frame) :staticmethod: convert coordinates of an equatorial coordinate system to a fixed one .. py:method:: rot_elements_at_epoch(epoch=J2000) :classmethod: Provides rotational elements at epoch. Provides north pole of body and angle to prime meridian. :param epoch: Epoch, default to J2000. :type epoch: ~astropy.time.Time, optional :returns: **ra, dec, W** -- Right ascension and declination of north pole, and angle of the prime meridian. :rtype: tuple (~astropy.units.Quantity) .. py:attribute:: frame_specific_representation_info .. py:attribute:: default_representation .. py:attribute:: default_differential .. py:attribute:: frame_attributes .. py:attribute:: info .. py:method:: __init_subclass__(**kwargs) :classmethod: .. py:method:: cache() Cache for this frame, a dict. It stores anything that should be computed from the coordinate data (*not* from the frame attributes). This can be used in functions to store anything that might be expensive to compute but might be reused by some other function. E.g.:: if 'user_data' in myframe.cache: data = myframe.cache['user_data'] else: myframe.cache['user_data'] = data = expensive_func(myframe.lat) If in-place modifications are made to the frame data, the cache should be cleared:: myframe.cache.clear() .. py:property:: data The coordinate data for this object. If this frame has no data, a `ValueError` will be raised. Use `has_data` to check if data is present on this frame object. .. py:property:: has_data True if this frame has `data`, False otherwise. .. py:property:: shape The shape of the underlying data. .. py:method:: __bool__() Any instance should evaluate to True, except when it is empty. .. py:property:: size The size of the object, as calculated from its shape. .. py:property:: masked Whether the underlying data is masked. :raises ValueError: If the frame has no associated data. .. py:method:: get_mask(*attrs) Get the mask associated with these coordinates. :param \*attrs: Attributes from which to get the masks to combine. Items can be dotted, like ``"data.lon", "data.lat"``. By default, get the combined mask of all components (including from differentials), ignoring possible masks of attributes. :type \*attrs: str :returns: **mask** -- The combined, read-only mask. If the instance is not masked, it is an array of `False` with the correct shape. :rtype: ~numpy.ndarray of bool :raises ValueError: If the coordinate frame has no associated data. .. py:attribute:: mask The mask. .. py:method:: get_frame_attr_defaults() :classmethod: Return a dict with the defaults for each frame attribute. .. py:method:: get_representation_cls(which='base') The class used for part of this frame's data. :param which: The class of which part to return. 'base' means the class used to represent the coordinates; 's' the first derivative to time, i.e., the class representing the proper motion and/or radial velocity. If `None`, return a dict with both. :type which: ('base', 's', `None`) :returns: **representation** :rtype: `~astropy.coordinates.BaseRepresentation` or `~astropy.coordinates.BaseDifferential`. .. py:method:: set_representation_cls(base=None, s='base') Set representation and/or differential class for this frame's data. :param base: The name or subclass to use to represent the coordinate data. :type base: str, `~astropy.coordinates.BaseRepresentation` subclass, optional :param s: The differential subclass to use to represent any velocities, such as proper motion and radial velocity. If equal to 'base', which is the default, it will be inferred from the representation. If `None`, the representation will drop any differentials. :type s: `~astropy.coordinates.BaseDifferential` subclass, optional .. py:attribute:: representation_type .. py:property:: differential_type The differential used for this frame's data. This will be a subclass from `~astropy.coordinates.BaseDifferential`. For simultaneous setting of representation and differentials, see the ``set_representation_cls`` method. .. py:method:: representation_info() A dictionary with the information of what attribute names for this frame apply to particular representations. .. py:method:: get_representation_component_names(which='base') .. py:method:: get_representation_component_units(which='base') .. py:attribute:: representation_component_names .. py:attribute:: representation_component_units .. py:method:: replicate(copy=False, **kwargs) Return a replica of the frame, optionally with new frame attributes. The replica is a new frame object that has the same data as this frame object and with frame attributes overridden if they are provided as extra keyword arguments to this method. If ``copy`` is set to `True` then a copy of the internal arrays will be made. Otherwise the replica will use a reference to the original arrays when possible to save memory. The internal arrays are normally not changeable by the user so in most cases it should not be necessary to set ``copy`` to `True`. :param copy: If True, the resulting object is a copy of the data. When False, references are used where possible. This rule also applies to the frame attributes. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: replicate_without_data(copy=False, **kwargs) Return a replica without data, optionally with new frame attributes. The replica is a new frame object without data but with the same frame attributes as this object, except where overridden by extra keyword arguments to this method. The ``copy`` keyword determines if the frame attributes are truly copied vs being references (which saves memory for cases where frame attributes are large). This method is essentially the converse of `realize_frame`. :param copy: If True, the resulting object has copies of the frame attributes. When False, references are used where possible. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but without data and possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: realize_frame(data, **kwargs) Generates a new frame with new data from another frame (which may or may not have data). Roughly speaking, the converse of `replicate_without_data`. :param data: The representation to use as the data for the new frame. :type data: `~astropy.coordinates.BaseRepresentation` :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. In particular, `representation_type` can be specified. :returns: **frameobj** -- A new object in *this* frame, with the same frame attributes as this one, but with the ``data`` as the coordinate data. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: represent_as(base, s='base', in_frame_units=False) Generate and return a new representation of this frame's `data` as a Representation object. Note: In order to make an in-place change of the representation of a Frame or SkyCoord object, set the ``representation`` attribute of that object to the desired new representation, or use the ``set_representation_cls`` method to also set the differential. :param base: The type of representation to generate. Must be a *class* (not an instance), or the string name of the representation class. :type base: subclass of BaseRepresentation or string :param s: Class in which any velocities should be represented. Must be a *class* (not an instance), or the string name of the differential class. If equal to 'base' (default), inferred from the base class. If `None`, all velocity information is dropped. :type s: subclass of `~astropy.coordinates.BaseDifferential`, str, optional :param in_frame_units: Force the representation units to match the specified units particular to this frame :type in_frame_units: bool, keyword-only :returns: **newrep** -- A new representation object of this frame's `data`. :rtype: BaseRepresentation-derived object :raises AttributeError: If this object had no `data` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import SkyCoord, CartesianRepresentation >>> coord = SkyCoord(0*u.deg, 0*u.deg) >>> coord.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP >>> coord.representation_type = CartesianRepresentation >>> coord # doctest: +FLOAT_CMP .. py:method:: transform_to(new_frame) Transform this object's coordinate data to a new frame. :param new_frame: The frame to transform this coordinate frame into. :type new_frame: coordinate-like :returns: **transframe** -- A new object with the coordinate data represented in the ``newframe`` system. :rtype: coordinate-like :raises ValueError: If there is no possible transformation route. .. py:method:: is_transformable_to(new_frame) Determines if this coordinate frame can be transformed to another given frame. :param new_frame: The proposed frame to transform into. :type new_frame: `~astropy.coordinates.BaseCoordinateFrame` subclass or instance :returns: **transformable** -- `True` if this can be transformed to ``new_frame``, `False` if not, or the string 'same' if ``new_frame`` is the same system as this object but no transformation is defined. :rtype: bool or str .. rubric:: Notes A return value of 'same' means the transformation will work, but it will just give back a copy of this object. The intended usage is:: if coord.is_transformable_to(some_unknown_frame): coord2 = coord.transform_to(some_unknown_frame) This will work even if ``some_unknown_frame`` turns out to be the same frame class as ``coord``. This is intended for cases where the frame is the same regardless of the frame attributes (e.g. ICRS), but be aware that it *might* also indicate that someone forgot to define the transformation between two objects of the same frame class but with different attributes. .. py:method:: is_frame_attr_default(attrnm) Determine whether or not a frame attribute has its value because it's the default value, or because this frame was created with that value explicitly requested. :param attrnm: The name of the attribute to check. :type attrnm: str :returns: **isdefault** -- True if the attribute ``attrnm`` has its value by default, False if it was specified at creation of this frame. :rtype: bool .. py:method:: is_equivalent_frame(other) Checks if this object is the same frame as the ``other`` object. To be the same frame, two objects must be the same frame class and have the same frame attributes. Note that it does *not* matter what, if any, data either object has. :param other: the other frame to check :type other: :class:`~astropy.coordinates.BaseCoordinateFrame` :returns: **isequiv** -- True if the frames are the same, False if not. :rtype: bool :raises TypeError: If ``other`` isn't a `~astropy.coordinates.BaseCoordinateFrame` or subclass. .. py:method:: __repr__() .. py:method:: __setitem__(item, value) .. py:method:: insert(obj, values, axis=0) .. py:method:: __dir__() Override the builtin `dir` behavior to include representation names. TODO: dynamic representation transforms (i.e. include cylindrical et al.). .. py:method:: __getattr__(attr) Allow access to attributes on the representation and differential as found via ``self.get_representation_component_names``. TODO: We should handle dynamic representation transforms here (e.g., `.cylindrical`) instead of defining properties as below. .. py:method:: __setattr__(attr, value) .. py:method:: __eq__(value) Equality operator for frame. This implements strict equality and requires that the frames are equivalent and that the representation data are exactly equal. .. py:method:: __ne__(value) .. py:method:: position_angle(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord]) -> astropy.coordinates.angles.Angle Compute the on-sky position angle to another coordinate. :param other: The other coordinate to compute the position angle to. It is treated as the "head" of the vector of the position angle. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: The (positive) position angle of the vector pointing from ``self`` to ``other``, measured East from North. If either ``self`` or ``other`` contain arrays, this will be an array following the appropriate `numpy` broadcasting rules. :rtype: `~astropy.coordinates.Angle` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import ICRS, SkyCoord >>> c1 = SkyCoord(0*u.deg, 0*u.deg) >>> c2 = ICRS(1*u.deg, 0*u.deg) >>> c1.position_angle(c2).to(u.deg) >>> c2.position_angle(c1).to(u.deg) >>> c3 = SkyCoord(1*u.deg, 1*u.deg) >>> c1.position_angle(c3).to(u.deg) # doctest: +FLOAT_CMP .. py:method:: separation(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord], *, origin_mismatch: Literal['ignore', 'warn', 'error'] = 'warn') -> astropy.coordinates.angles.Angle Computes on-sky separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate to get the separation to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :param origin_mismatch: If the ``other`` coordinates are in a different frame then they will have to be transformed, and if the transformation is not a pure rotation then ``self.separation(other)`` can be different from ``other.separation(self)``. With ``origin_mismatch="warn"`` (default) the transformation is always performed, but a warning is emitted if it is not a pure rotation. If ``origin_mismatch="ignore"`` then the required transformation is always performed without warnings. If ``origin_mismatch="error"`` then only transformations that are pure rotations are allowed. :type origin_mismatch: {"warn", "ignore", "error"}, keyword-only :returns: **sep** -- The on-sky separation between this and the ``other`` coordinate. :rtype: `~astropy.coordinates.Angle` .. rubric:: Notes The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [1]_. .. [1] https://en.wikipedia.org/wiki/Great-circle_distance .. py:method:: separation_3d(other) Computes three dimensional separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate system to get the distance to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: **sep** -- The real-space distance between these two coordinates. :rtype: `~astropy.coordinates.Distance` :raises ValueError: If this or the other coordinate do not have distances. .. py:property:: cartesian Shorthand for a cartesian representation of the coordinates in this object. .. py:property:: cylindrical Shorthand for a cylindrical representation of the coordinates in this object. .. py:property:: spherical Shorthand for a spherical representation of the coordinates in this object. .. py:property:: sphericalcoslat Shorthand for a spherical representation of the positional data and a `~astropy.coordinates.SphericalCosLatDifferential` for the velocity data in this object. .. py:property:: velocity Shorthand for retrieving the Cartesian space-motion as a `~astropy.coordinates.CartesianDifferential` object. This is equivalent to calling ``self.cartesian.differentials['s']``. .. py:property:: proper_motion Shorthand for the two-dimensional proper motion as a `~astropy.units.Quantity` object with angular velocity units. In the returned `~astropy.units.Quantity`, ``axis=0`` is the longitude/latitude dimension so that ``.proper_motion[0]`` is the longitudinal proper motion and ``.proper_motion[1]`` is latitudinal. The longitudinal proper motion already includes the cos(latitude) term. .. py:property:: radial_velocity Shorthand for the radial or line-of-sight velocity as a `~astropy.units.Quantity` object. .. py:method:: to_table() -> astropy.table.QTable Convert this |BaseFrame| to a |QTable|. Any attributes that have the same length as the |BaseFrame| will be converted to columns of the |QTable|. All other attributes will be recorded as metadata. :returns: A |QTable| containing the data of this |BaseFrame|. :rtype: `~astropy.table.QTable` .. rubric:: Examples >>> from astropy.coordinates import ICRS >>> coord = ICRS(ra=[40, 70]*u.deg, dec=[0, -20]*u.deg) >>> t = coord.to_table() >>> t ra dec deg deg float64 float64 ------- ------- 40.0 0.0 70.0 -20.0 >>> t.meta {'representation_type': 'spherical'} .. py:property:: unmasked Get an instance without the mask. Note that while one gets a new instance, the underlying data will be shared. .. seealso:: :py:obj:`filled` get a copy of the underlying data, with masked values filled in. .. py:method:: filled(fill_value) Get a copy of the underlying data, with masked values filled in. :param fill_value: Value to replace masked values with. :type fill_value: object :returns: **filled** -- Copy of ``self`` with masked items replaced by ``fill_value``. :rtype: instance .. seealso:: :py:obj:`unmasked` get an instance without the mask. .. py:property:: ndim :type: int The number of dimensions of the instance and underlying arrays. .. py:property:: isscalar :type: bool .. py:method:: __len__() -> int .. py:method:: __getitem__(item) .. py:method:: __iter__() .. py:method:: __array_function__(function, types, args, kwargs) Wrap numpy functions that make sense. .. py:method:: copy(*args, **kwargs) Return an instance containing copies of the internal data. Parameters are as for :meth:`~numpy.ndarray.copy`. .. py:method:: reshape(*args, **kwargs) Returns an instance containing the same data with a new shape. Parameters are as for :meth:`~numpy.ndarray.reshape`. Note that it is not always possible to change the shape of an array without copying the data (see :func:`~numpy.reshape` documentation). If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute (note: this may not be implemented for all classes using ``NDArrayShapeMethods``). .. py:method:: ravel(*args, **kwargs) Return an instance with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.ravel`. Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape ``(-1,)`` to the shape attribute. .. py:method:: flatten(*args, **kwargs) Return a copy with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.flatten`. .. py:method:: transpose(*args, **kwargs) Return an instance with the data transposed. Parameters are as for :meth:`~numpy.ndarray.transpose`. All internal data are views of the data of the original. .. py:property:: T :type: Self Return an instance with the data transposed. Parameters are as for :attr:`~numpy.ndarray.T`. All internal data are views of the data of the original. .. py:method:: swapaxes(*args, **kwargs) Return an instance with the given axes interchanged. Parameters are as for :meth:`~numpy.ndarray.swapaxes`: ``axis1, axis2``. All internal data are views of the data of the original. .. py:method:: diagonal(*args, **kwargs) Return an instance with the specified diagonals. Parameters are as for :meth:`~numpy.ndarray.diagonal`. All internal data are views of the data of the original. .. py:method:: squeeze(*args, **kwargs) Return an instance with single-dimensional shape entries removed. Parameters are as for :meth:`~numpy.ndarray.squeeze`. All internal data are views of the data of the original. .. py:method:: take(indices, axis=None, out=None, mode='raise') Return a new instance formed from the elements at the given indices. Parameters are as for :meth:`~numpy.ndarray.take`, except that, obviously, no output array can be given. .. py:class:: MercuryFixed(*args, copy=True, representation_type=None, differential_type=None, **kwargs) Bases: :py:obj:`_PlanetaryFixed` non-inertial, body-fixed reference frame: Mercury .. py:attribute:: body .. py:attribute:: equatorial .. py:attribute:: obstime .. py:method:: to_equatorial(fixed_coo, equatorial_frame) :staticmethod: convert coordinates of a fixed coordinate system to an equatorial one .. py:method:: from_equatorial(equatorial_coo, fixed_frame) :staticmethod: convert coordinates of an equatorial coordinate system to a fixed one .. py:method:: rot_elements_at_epoch(epoch=J2000) :classmethod: Provides rotational elements at epoch. Provides north pole of body and angle to prime meridian. :param epoch: Epoch, default to J2000. :type epoch: ~astropy.time.Time, optional :returns: **ra, dec, W** -- Right ascension and declination of north pole, and angle of the prime meridian. :rtype: tuple (~astropy.units.Quantity) .. py:attribute:: frame_specific_representation_info .. py:attribute:: default_representation .. py:attribute:: default_differential .. py:attribute:: frame_attributes .. py:attribute:: info .. py:method:: __init_subclass__(**kwargs) :classmethod: .. py:method:: cache() Cache for this frame, a dict. It stores anything that should be computed from the coordinate data (*not* from the frame attributes). This can be used in functions to store anything that might be expensive to compute but might be reused by some other function. E.g.:: if 'user_data' in myframe.cache: data = myframe.cache['user_data'] else: myframe.cache['user_data'] = data = expensive_func(myframe.lat) If in-place modifications are made to the frame data, the cache should be cleared:: myframe.cache.clear() .. py:property:: data The coordinate data for this object. If this frame has no data, a `ValueError` will be raised. Use `has_data` to check if data is present on this frame object. .. py:property:: has_data True if this frame has `data`, False otherwise. .. py:property:: shape The shape of the underlying data. .. py:method:: __bool__() Any instance should evaluate to True, except when it is empty. .. py:property:: size The size of the object, as calculated from its shape. .. py:property:: masked Whether the underlying data is masked. :raises ValueError: If the frame has no associated data. .. py:method:: get_mask(*attrs) Get the mask associated with these coordinates. :param \*attrs: Attributes from which to get the masks to combine. Items can be dotted, like ``"data.lon", "data.lat"``. By default, get the combined mask of all components (including from differentials), ignoring possible masks of attributes. :type \*attrs: str :returns: **mask** -- The combined, read-only mask. If the instance is not masked, it is an array of `False` with the correct shape. :rtype: ~numpy.ndarray of bool :raises ValueError: If the coordinate frame has no associated data. .. py:attribute:: mask The mask. .. py:method:: get_frame_attr_defaults() :classmethod: Return a dict with the defaults for each frame attribute. .. py:method:: get_representation_cls(which='base') The class used for part of this frame's data. :param which: The class of which part to return. 'base' means the class used to represent the coordinates; 's' the first derivative to time, i.e., the class representing the proper motion and/or radial velocity. If `None`, return a dict with both. :type which: ('base', 's', `None`) :returns: **representation** :rtype: `~astropy.coordinates.BaseRepresentation` or `~astropy.coordinates.BaseDifferential`. .. py:method:: set_representation_cls(base=None, s='base') Set representation and/or differential class for this frame's data. :param base: The name or subclass to use to represent the coordinate data. :type base: str, `~astropy.coordinates.BaseRepresentation` subclass, optional :param s: The differential subclass to use to represent any velocities, such as proper motion and radial velocity. If equal to 'base', which is the default, it will be inferred from the representation. If `None`, the representation will drop any differentials. :type s: `~astropy.coordinates.BaseDifferential` subclass, optional .. py:attribute:: representation_type .. py:property:: differential_type The differential used for this frame's data. This will be a subclass from `~astropy.coordinates.BaseDifferential`. For simultaneous setting of representation and differentials, see the ``set_representation_cls`` method. .. py:method:: representation_info() A dictionary with the information of what attribute names for this frame apply to particular representations. .. py:method:: get_representation_component_names(which='base') .. py:method:: get_representation_component_units(which='base') .. py:attribute:: representation_component_names .. py:attribute:: representation_component_units .. py:method:: replicate(copy=False, **kwargs) Return a replica of the frame, optionally with new frame attributes. The replica is a new frame object that has the same data as this frame object and with frame attributes overridden if they are provided as extra keyword arguments to this method. If ``copy`` is set to `True` then a copy of the internal arrays will be made. Otherwise the replica will use a reference to the original arrays when possible to save memory. The internal arrays are normally not changeable by the user so in most cases it should not be necessary to set ``copy`` to `True`. :param copy: If True, the resulting object is a copy of the data. When False, references are used where possible. This rule also applies to the frame attributes. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: replicate_without_data(copy=False, **kwargs) Return a replica without data, optionally with new frame attributes. The replica is a new frame object without data but with the same frame attributes as this object, except where overridden by extra keyword arguments to this method. The ``copy`` keyword determines if the frame attributes are truly copied vs being references (which saves memory for cases where frame attributes are large). This method is essentially the converse of `realize_frame`. :param copy: If True, the resulting object has copies of the frame attributes. When False, references are used where possible. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but without data and possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: realize_frame(data, **kwargs) Generates a new frame with new data from another frame (which may or may not have data). Roughly speaking, the converse of `replicate_without_data`. :param data: The representation to use as the data for the new frame. :type data: `~astropy.coordinates.BaseRepresentation` :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. In particular, `representation_type` can be specified. :returns: **frameobj** -- A new object in *this* frame, with the same frame attributes as this one, but with the ``data`` as the coordinate data. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: represent_as(base, s='base', in_frame_units=False) Generate and return a new representation of this frame's `data` as a Representation object. Note: In order to make an in-place change of the representation of a Frame or SkyCoord object, set the ``representation`` attribute of that object to the desired new representation, or use the ``set_representation_cls`` method to also set the differential. :param base: The type of representation to generate. Must be a *class* (not an instance), or the string name of the representation class. :type base: subclass of BaseRepresentation or string :param s: Class in which any velocities should be represented. Must be a *class* (not an instance), or the string name of the differential class. If equal to 'base' (default), inferred from the base class. If `None`, all velocity information is dropped. :type s: subclass of `~astropy.coordinates.BaseDifferential`, str, optional :param in_frame_units: Force the representation units to match the specified units particular to this frame :type in_frame_units: bool, keyword-only :returns: **newrep** -- A new representation object of this frame's `data`. :rtype: BaseRepresentation-derived object :raises AttributeError: If this object had no `data` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import SkyCoord, CartesianRepresentation >>> coord = SkyCoord(0*u.deg, 0*u.deg) >>> coord.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP >>> coord.representation_type = CartesianRepresentation >>> coord # doctest: +FLOAT_CMP .. py:method:: transform_to(new_frame) Transform this object's coordinate data to a new frame. :param new_frame: The frame to transform this coordinate frame into. :type new_frame: coordinate-like :returns: **transframe** -- A new object with the coordinate data represented in the ``newframe`` system. :rtype: coordinate-like :raises ValueError: If there is no possible transformation route. .. py:method:: is_transformable_to(new_frame) Determines if this coordinate frame can be transformed to another given frame. :param new_frame: The proposed frame to transform into. :type new_frame: `~astropy.coordinates.BaseCoordinateFrame` subclass or instance :returns: **transformable** -- `True` if this can be transformed to ``new_frame``, `False` if not, or the string 'same' if ``new_frame`` is the same system as this object but no transformation is defined. :rtype: bool or str .. rubric:: Notes A return value of 'same' means the transformation will work, but it will just give back a copy of this object. The intended usage is:: if coord.is_transformable_to(some_unknown_frame): coord2 = coord.transform_to(some_unknown_frame) This will work even if ``some_unknown_frame`` turns out to be the same frame class as ``coord``. This is intended for cases where the frame is the same regardless of the frame attributes (e.g. ICRS), but be aware that it *might* also indicate that someone forgot to define the transformation between two objects of the same frame class but with different attributes. .. py:method:: is_frame_attr_default(attrnm) Determine whether or not a frame attribute has its value because it's the default value, or because this frame was created with that value explicitly requested. :param attrnm: The name of the attribute to check. :type attrnm: str :returns: **isdefault** -- True if the attribute ``attrnm`` has its value by default, False if it was specified at creation of this frame. :rtype: bool .. py:method:: is_equivalent_frame(other) Checks if this object is the same frame as the ``other`` object. To be the same frame, two objects must be the same frame class and have the same frame attributes. Note that it does *not* matter what, if any, data either object has. :param other: the other frame to check :type other: :class:`~astropy.coordinates.BaseCoordinateFrame` :returns: **isequiv** -- True if the frames are the same, False if not. :rtype: bool :raises TypeError: If ``other`` isn't a `~astropy.coordinates.BaseCoordinateFrame` or subclass. .. py:method:: __repr__() .. py:method:: __setitem__(item, value) .. py:method:: insert(obj, values, axis=0) .. py:method:: __dir__() Override the builtin `dir` behavior to include representation names. TODO: dynamic representation transforms (i.e. include cylindrical et al.). .. py:method:: __getattr__(attr) Allow access to attributes on the representation and differential as found via ``self.get_representation_component_names``. TODO: We should handle dynamic representation transforms here (e.g., `.cylindrical`) instead of defining properties as below. .. py:method:: __setattr__(attr, value) .. py:method:: __eq__(value) Equality operator for frame. This implements strict equality and requires that the frames are equivalent and that the representation data are exactly equal. .. py:method:: __ne__(value) .. py:method:: position_angle(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord]) -> astropy.coordinates.angles.Angle Compute the on-sky position angle to another coordinate. :param other: The other coordinate to compute the position angle to. It is treated as the "head" of the vector of the position angle. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: The (positive) position angle of the vector pointing from ``self`` to ``other``, measured East from North. If either ``self`` or ``other`` contain arrays, this will be an array following the appropriate `numpy` broadcasting rules. :rtype: `~astropy.coordinates.Angle` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import ICRS, SkyCoord >>> c1 = SkyCoord(0*u.deg, 0*u.deg) >>> c2 = ICRS(1*u.deg, 0*u.deg) >>> c1.position_angle(c2).to(u.deg) >>> c2.position_angle(c1).to(u.deg) >>> c3 = SkyCoord(1*u.deg, 1*u.deg) >>> c1.position_angle(c3).to(u.deg) # doctest: +FLOAT_CMP .. py:method:: separation(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord], *, origin_mismatch: Literal['ignore', 'warn', 'error'] = 'warn') -> astropy.coordinates.angles.Angle Computes on-sky separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate to get the separation to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :param origin_mismatch: If the ``other`` coordinates are in a different frame then they will have to be transformed, and if the transformation is not a pure rotation then ``self.separation(other)`` can be different from ``other.separation(self)``. With ``origin_mismatch="warn"`` (default) the transformation is always performed, but a warning is emitted if it is not a pure rotation. If ``origin_mismatch="ignore"`` then the required transformation is always performed without warnings. If ``origin_mismatch="error"`` then only transformations that are pure rotations are allowed. :type origin_mismatch: {"warn", "ignore", "error"}, keyword-only :returns: **sep** -- The on-sky separation between this and the ``other`` coordinate. :rtype: `~astropy.coordinates.Angle` .. rubric:: Notes The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [1]_. .. [1] https://en.wikipedia.org/wiki/Great-circle_distance .. py:method:: separation_3d(other) Computes three dimensional separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate system to get the distance to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: **sep** -- The real-space distance between these two coordinates. :rtype: `~astropy.coordinates.Distance` :raises ValueError: If this or the other coordinate do not have distances. .. py:property:: cartesian Shorthand for a cartesian representation of the coordinates in this object. .. py:property:: cylindrical Shorthand for a cylindrical representation of the coordinates in this object. .. py:property:: spherical Shorthand for a spherical representation of the coordinates in this object. .. py:property:: sphericalcoslat Shorthand for a spherical representation of the positional data and a `~astropy.coordinates.SphericalCosLatDifferential` for the velocity data in this object. .. py:property:: velocity Shorthand for retrieving the Cartesian space-motion as a `~astropy.coordinates.CartesianDifferential` object. This is equivalent to calling ``self.cartesian.differentials['s']``. .. py:property:: proper_motion Shorthand for the two-dimensional proper motion as a `~astropy.units.Quantity` object with angular velocity units. In the returned `~astropy.units.Quantity`, ``axis=0`` is the longitude/latitude dimension so that ``.proper_motion[0]`` is the longitudinal proper motion and ``.proper_motion[1]`` is latitudinal. The longitudinal proper motion already includes the cos(latitude) term. .. py:property:: radial_velocity Shorthand for the radial or line-of-sight velocity as a `~astropy.units.Quantity` object. .. py:method:: to_table() -> astropy.table.QTable Convert this |BaseFrame| to a |QTable|. Any attributes that have the same length as the |BaseFrame| will be converted to columns of the |QTable|. All other attributes will be recorded as metadata. :returns: A |QTable| containing the data of this |BaseFrame|. :rtype: `~astropy.table.QTable` .. rubric:: Examples >>> from astropy.coordinates import ICRS >>> coord = ICRS(ra=[40, 70]*u.deg, dec=[0, -20]*u.deg) >>> t = coord.to_table() >>> t ra dec deg deg float64 float64 ------- ------- 40.0 0.0 70.0 -20.0 >>> t.meta {'representation_type': 'spherical'} .. py:property:: unmasked Get an instance without the mask. Note that while one gets a new instance, the underlying data will be shared. .. seealso:: :py:obj:`filled` get a copy of the underlying data, with masked values filled in. .. py:method:: filled(fill_value) Get a copy of the underlying data, with masked values filled in. :param fill_value: Value to replace masked values with. :type fill_value: object :returns: **filled** -- Copy of ``self`` with masked items replaced by ``fill_value``. :rtype: instance .. seealso:: :py:obj:`unmasked` get an instance without the mask. .. py:property:: ndim :type: int The number of dimensions of the instance and underlying arrays. .. py:property:: isscalar :type: bool .. py:method:: __len__() -> int .. py:method:: __getitem__(item) .. py:method:: __iter__() .. py:method:: __array_function__(function, types, args, kwargs) Wrap numpy functions that make sense. .. py:method:: copy(*args, **kwargs) Return an instance containing copies of the internal data. Parameters are as for :meth:`~numpy.ndarray.copy`. .. py:method:: reshape(*args, **kwargs) Returns an instance containing the same data with a new shape. Parameters are as for :meth:`~numpy.ndarray.reshape`. Note that it is not always possible to change the shape of an array without copying the data (see :func:`~numpy.reshape` documentation). If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute (note: this may not be implemented for all classes using ``NDArrayShapeMethods``). .. py:method:: ravel(*args, **kwargs) Return an instance with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.ravel`. Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape ``(-1,)`` to the shape attribute. .. py:method:: flatten(*args, **kwargs) Return a copy with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.flatten`. .. py:method:: transpose(*args, **kwargs) Return an instance with the data transposed. Parameters are as for :meth:`~numpy.ndarray.transpose`. All internal data are views of the data of the original. .. py:property:: T :type: Self Return an instance with the data transposed. Parameters are as for :attr:`~numpy.ndarray.T`. All internal data are views of the data of the original. .. py:method:: swapaxes(*args, **kwargs) Return an instance with the given axes interchanged. Parameters are as for :meth:`~numpy.ndarray.swapaxes`: ``axis1, axis2``. All internal data are views of the data of the original. .. py:method:: diagonal(*args, **kwargs) Return an instance with the specified diagonals. Parameters are as for :meth:`~numpy.ndarray.diagonal`. All internal data are views of the data of the original. .. py:method:: squeeze(*args, **kwargs) Return an instance with single-dimensional shape entries removed. Parameters are as for :meth:`~numpy.ndarray.squeeze`. All internal data are views of the data of the original. .. py:method:: take(indices, axis=None, out=None, mode='raise') Return a new instance formed from the elements at the given indices. Parameters are as for :meth:`~numpy.ndarray.take`, except that, obviously, no output array can be given. .. py:class:: VenusFixed(*args, copy=True, representation_type=None, differential_type=None, **kwargs) Bases: :py:obj:`_PlanetaryFixed` non-inertial, body-fixed reference frame: Venus .. py:attribute:: body .. py:attribute:: equatorial .. py:attribute:: obstime .. py:method:: to_equatorial(fixed_coo, equatorial_frame) :staticmethod: convert coordinates of a fixed coordinate system to an equatorial one .. py:method:: from_equatorial(equatorial_coo, fixed_frame) :staticmethod: convert coordinates of an equatorial coordinate system to a fixed one .. py:method:: rot_elements_at_epoch(epoch=J2000) :classmethod: Provides rotational elements at epoch. Provides north pole of body and angle to prime meridian. :param epoch: Epoch, default to J2000. :type epoch: ~astropy.time.Time, optional :returns: **ra, dec, W** -- Right ascension and declination of north pole, and angle of the prime meridian. :rtype: tuple (~astropy.units.Quantity) .. py:attribute:: frame_specific_representation_info .. py:attribute:: default_representation .. py:attribute:: default_differential .. py:attribute:: frame_attributes .. py:attribute:: info .. py:method:: __init_subclass__(**kwargs) :classmethod: .. py:method:: cache() Cache for this frame, a dict. It stores anything that should be computed from the coordinate data (*not* from the frame attributes). This can be used in functions to store anything that might be expensive to compute but might be reused by some other function. E.g.:: if 'user_data' in myframe.cache: data = myframe.cache['user_data'] else: myframe.cache['user_data'] = data = expensive_func(myframe.lat) If in-place modifications are made to the frame data, the cache should be cleared:: myframe.cache.clear() .. py:property:: data The coordinate data for this object. If this frame has no data, a `ValueError` will be raised. Use `has_data` to check if data is present on this frame object. .. py:property:: has_data True if this frame has `data`, False otherwise. .. py:property:: shape The shape of the underlying data. .. py:method:: __bool__() Any instance should evaluate to True, except when it is empty. .. py:property:: size The size of the object, as calculated from its shape. .. py:property:: masked Whether the underlying data is masked. :raises ValueError: If the frame has no associated data. .. py:method:: get_mask(*attrs) Get the mask associated with these coordinates. :param \*attrs: Attributes from which to get the masks to combine. Items can be dotted, like ``"data.lon", "data.lat"``. By default, get the combined mask of all components (including from differentials), ignoring possible masks of attributes. :type \*attrs: str :returns: **mask** -- The combined, read-only mask. If the instance is not masked, it is an array of `False` with the correct shape. :rtype: ~numpy.ndarray of bool :raises ValueError: If the coordinate frame has no associated data. .. py:attribute:: mask The mask. .. py:method:: get_frame_attr_defaults() :classmethod: Return a dict with the defaults for each frame attribute. .. py:method:: get_representation_cls(which='base') The class used for part of this frame's data. :param which: The class of which part to return. 'base' means the class used to represent the coordinates; 's' the first derivative to time, i.e., the class representing the proper motion and/or radial velocity. If `None`, return a dict with both. :type which: ('base', 's', `None`) :returns: **representation** :rtype: `~astropy.coordinates.BaseRepresentation` or `~astropy.coordinates.BaseDifferential`. .. py:method:: set_representation_cls(base=None, s='base') Set representation and/or differential class for this frame's data. :param base: The name or subclass to use to represent the coordinate data. :type base: str, `~astropy.coordinates.BaseRepresentation` subclass, optional :param s: The differential subclass to use to represent any velocities, such as proper motion and radial velocity. If equal to 'base', which is the default, it will be inferred from the representation. If `None`, the representation will drop any differentials. :type s: `~astropy.coordinates.BaseDifferential` subclass, optional .. py:attribute:: representation_type .. py:property:: differential_type The differential used for this frame's data. This will be a subclass from `~astropy.coordinates.BaseDifferential`. For simultaneous setting of representation and differentials, see the ``set_representation_cls`` method. .. py:method:: representation_info() A dictionary with the information of what attribute names for this frame apply to particular representations. .. py:method:: get_representation_component_names(which='base') .. py:method:: get_representation_component_units(which='base') .. py:attribute:: representation_component_names .. py:attribute:: representation_component_units .. py:method:: replicate(copy=False, **kwargs) Return a replica of the frame, optionally with new frame attributes. The replica is a new frame object that has the same data as this frame object and with frame attributes overridden if they are provided as extra keyword arguments to this method. If ``copy`` is set to `True` then a copy of the internal arrays will be made. Otherwise the replica will use a reference to the original arrays when possible to save memory. The internal arrays are normally not changeable by the user so in most cases it should not be necessary to set ``copy`` to `True`. :param copy: If True, the resulting object is a copy of the data. When False, references are used where possible. This rule also applies to the frame attributes. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: replicate_without_data(copy=False, **kwargs) Return a replica without data, optionally with new frame attributes. The replica is a new frame object without data but with the same frame attributes as this object, except where overridden by extra keyword arguments to this method. The ``copy`` keyword determines if the frame attributes are truly copied vs being references (which saves memory for cases where frame attributes are large). This method is essentially the converse of `realize_frame`. :param copy: If True, the resulting object has copies of the frame attributes. When False, references are used where possible. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but without data and possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: realize_frame(data, **kwargs) Generates a new frame with new data from another frame (which may or may not have data). Roughly speaking, the converse of `replicate_without_data`. :param data: The representation to use as the data for the new frame. :type data: `~astropy.coordinates.BaseRepresentation` :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. In particular, `representation_type` can be specified. :returns: **frameobj** -- A new object in *this* frame, with the same frame attributes as this one, but with the ``data`` as the coordinate data. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: represent_as(base, s='base', in_frame_units=False) Generate and return a new representation of this frame's `data` as a Representation object. Note: In order to make an in-place change of the representation of a Frame or SkyCoord object, set the ``representation`` attribute of that object to the desired new representation, or use the ``set_representation_cls`` method to also set the differential. :param base: The type of representation to generate. Must be a *class* (not an instance), or the string name of the representation class. :type base: subclass of BaseRepresentation or string :param s: Class in which any velocities should be represented. Must be a *class* (not an instance), or the string name of the differential class. If equal to 'base' (default), inferred from the base class. If `None`, all velocity information is dropped. :type s: subclass of `~astropy.coordinates.BaseDifferential`, str, optional :param in_frame_units: Force the representation units to match the specified units particular to this frame :type in_frame_units: bool, keyword-only :returns: **newrep** -- A new representation object of this frame's `data`. :rtype: BaseRepresentation-derived object :raises AttributeError: If this object had no `data` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import SkyCoord, CartesianRepresentation >>> coord = SkyCoord(0*u.deg, 0*u.deg) >>> coord.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP >>> coord.representation_type = CartesianRepresentation >>> coord # doctest: +FLOAT_CMP .. py:method:: transform_to(new_frame) Transform this object's coordinate data to a new frame. :param new_frame: The frame to transform this coordinate frame into. :type new_frame: coordinate-like :returns: **transframe** -- A new object with the coordinate data represented in the ``newframe`` system. :rtype: coordinate-like :raises ValueError: If there is no possible transformation route. .. py:method:: is_transformable_to(new_frame) Determines if this coordinate frame can be transformed to another given frame. :param new_frame: The proposed frame to transform into. :type new_frame: `~astropy.coordinates.BaseCoordinateFrame` subclass or instance :returns: **transformable** -- `True` if this can be transformed to ``new_frame``, `False` if not, or the string 'same' if ``new_frame`` is the same system as this object but no transformation is defined. :rtype: bool or str .. rubric:: Notes A return value of 'same' means the transformation will work, but it will just give back a copy of this object. The intended usage is:: if coord.is_transformable_to(some_unknown_frame): coord2 = coord.transform_to(some_unknown_frame) This will work even if ``some_unknown_frame`` turns out to be the same frame class as ``coord``. This is intended for cases where the frame is the same regardless of the frame attributes (e.g. ICRS), but be aware that it *might* also indicate that someone forgot to define the transformation between two objects of the same frame class but with different attributes. .. py:method:: is_frame_attr_default(attrnm) Determine whether or not a frame attribute has its value because it's the default value, or because this frame was created with that value explicitly requested. :param attrnm: The name of the attribute to check. :type attrnm: str :returns: **isdefault** -- True if the attribute ``attrnm`` has its value by default, False if it was specified at creation of this frame. :rtype: bool .. py:method:: is_equivalent_frame(other) Checks if this object is the same frame as the ``other`` object. To be the same frame, two objects must be the same frame class and have the same frame attributes. Note that it does *not* matter what, if any, data either object has. :param other: the other frame to check :type other: :class:`~astropy.coordinates.BaseCoordinateFrame` :returns: **isequiv** -- True if the frames are the same, False if not. :rtype: bool :raises TypeError: If ``other`` isn't a `~astropy.coordinates.BaseCoordinateFrame` or subclass. .. py:method:: __repr__() .. py:method:: __setitem__(item, value) .. py:method:: insert(obj, values, axis=0) .. py:method:: __dir__() Override the builtin `dir` behavior to include representation names. TODO: dynamic representation transforms (i.e. include cylindrical et al.). .. py:method:: __getattr__(attr) Allow access to attributes on the representation and differential as found via ``self.get_representation_component_names``. TODO: We should handle dynamic representation transforms here (e.g., `.cylindrical`) instead of defining properties as below. .. py:method:: __setattr__(attr, value) .. py:method:: __eq__(value) Equality operator for frame. This implements strict equality and requires that the frames are equivalent and that the representation data are exactly equal. .. py:method:: __ne__(value) .. py:method:: position_angle(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord]) -> astropy.coordinates.angles.Angle Compute the on-sky position angle to another coordinate. :param other: The other coordinate to compute the position angle to. It is treated as the "head" of the vector of the position angle. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: The (positive) position angle of the vector pointing from ``self`` to ``other``, measured East from North. If either ``self`` or ``other`` contain arrays, this will be an array following the appropriate `numpy` broadcasting rules. :rtype: `~astropy.coordinates.Angle` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import ICRS, SkyCoord >>> c1 = SkyCoord(0*u.deg, 0*u.deg) >>> c2 = ICRS(1*u.deg, 0*u.deg) >>> c1.position_angle(c2).to(u.deg) >>> c2.position_angle(c1).to(u.deg) >>> c3 = SkyCoord(1*u.deg, 1*u.deg) >>> c1.position_angle(c3).to(u.deg) # doctest: +FLOAT_CMP .. py:method:: separation(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord], *, origin_mismatch: Literal['ignore', 'warn', 'error'] = 'warn') -> astropy.coordinates.angles.Angle Computes on-sky separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate to get the separation to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :param origin_mismatch: If the ``other`` coordinates are in a different frame then they will have to be transformed, and if the transformation is not a pure rotation then ``self.separation(other)`` can be different from ``other.separation(self)``. With ``origin_mismatch="warn"`` (default) the transformation is always performed, but a warning is emitted if it is not a pure rotation. If ``origin_mismatch="ignore"`` then the required transformation is always performed without warnings. If ``origin_mismatch="error"`` then only transformations that are pure rotations are allowed. :type origin_mismatch: {"warn", "ignore", "error"}, keyword-only :returns: **sep** -- The on-sky separation between this and the ``other`` coordinate. :rtype: `~astropy.coordinates.Angle` .. rubric:: Notes The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [1]_. .. [1] https://en.wikipedia.org/wiki/Great-circle_distance .. py:method:: separation_3d(other) Computes three dimensional separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate system to get the distance to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: **sep** -- The real-space distance between these two coordinates. :rtype: `~astropy.coordinates.Distance` :raises ValueError: If this or the other coordinate do not have distances. .. py:property:: cartesian Shorthand for a cartesian representation of the coordinates in this object. .. py:property:: cylindrical Shorthand for a cylindrical representation of the coordinates in this object. .. py:property:: spherical Shorthand for a spherical representation of the coordinates in this object. .. py:property:: sphericalcoslat Shorthand for a spherical representation of the positional data and a `~astropy.coordinates.SphericalCosLatDifferential` for the velocity data in this object. .. py:property:: velocity Shorthand for retrieving the Cartesian space-motion as a `~astropy.coordinates.CartesianDifferential` object. This is equivalent to calling ``self.cartesian.differentials['s']``. .. py:property:: proper_motion Shorthand for the two-dimensional proper motion as a `~astropy.units.Quantity` object with angular velocity units. In the returned `~astropy.units.Quantity`, ``axis=0`` is the longitude/latitude dimension so that ``.proper_motion[0]`` is the longitudinal proper motion and ``.proper_motion[1]`` is latitudinal. The longitudinal proper motion already includes the cos(latitude) term. .. py:property:: radial_velocity Shorthand for the radial or line-of-sight velocity as a `~astropy.units.Quantity` object. .. py:method:: to_table() -> astropy.table.QTable Convert this |BaseFrame| to a |QTable|. Any attributes that have the same length as the |BaseFrame| will be converted to columns of the |QTable|. All other attributes will be recorded as metadata. :returns: A |QTable| containing the data of this |BaseFrame|. :rtype: `~astropy.table.QTable` .. rubric:: Examples >>> from astropy.coordinates import ICRS >>> coord = ICRS(ra=[40, 70]*u.deg, dec=[0, -20]*u.deg) >>> t = coord.to_table() >>> t ra dec deg deg float64 float64 ------- ------- 40.0 0.0 70.0 -20.0 >>> t.meta {'representation_type': 'spherical'} .. py:property:: unmasked Get an instance without the mask. Note that while one gets a new instance, the underlying data will be shared. .. seealso:: :py:obj:`filled` get a copy of the underlying data, with masked values filled in. .. py:method:: filled(fill_value) Get a copy of the underlying data, with masked values filled in. :param fill_value: Value to replace masked values with. :type fill_value: object :returns: **filled** -- Copy of ``self`` with masked items replaced by ``fill_value``. :rtype: instance .. seealso:: :py:obj:`unmasked` get an instance without the mask. .. py:property:: ndim :type: int The number of dimensions of the instance and underlying arrays. .. py:property:: isscalar :type: bool .. py:method:: __len__() -> int .. py:method:: __getitem__(item) .. py:method:: __iter__() .. py:method:: __array_function__(function, types, args, kwargs) Wrap numpy functions that make sense. .. py:method:: copy(*args, **kwargs) Return an instance containing copies of the internal data. Parameters are as for :meth:`~numpy.ndarray.copy`. .. py:method:: reshape(*args, **kwargs) Returns an instance containing the same data with a new shape. Parameters are as for :meth:`~numpy.ndarray.reshape`. Note that it is not always possible to change the shape of an array without copying the data (see :func:`~numpy.reshape` documentation). If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute (note: this may not be implemented for all classes using ``NDArrayShapeMethods``). .. py:method:: ravel(*args, **kwargs) Return an instance with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.ravel`. Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape ``(-1,)`` to the shape attribute. .. py:method:: flatten(*args, **kwargs) Return a copy with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.flatten`. .. py:method:: transpose(*args, **kwargs) Return an instance with the data transposed. Parameters are as for :meth:`~numpy.ndarray.transpose`. All internal data are views of the data of the original. .. py:property:: T :type: Self Return an instance with the data transposed. Parameters are as for :attr:`~numpy.ndarray.T`. All internal data are views of the data of the original. .. py:method:: swapaxes(*args, **kwargs) Return an instance with the given axes interchanged. Parameters are as for :meth:`~numpy.ndarray.swapaxes`: ``axis1, axis2``. All internal data are views of the data of the original. .. py:method:: diagonal(*args, **kwargs) Return an instance with the specified diagonals. Parameters are as for :meth:`~numpy.ndarray.diagonal`. All internal data are views of the data of the original. .. py:method:: squeeze(*args, **kwargs) Return an instance with single-dimensional shape entries removed. Parameters are as for :meth:`~numpy.ndarray.squeeze`. All internal data are views of the data of the original. .. py:method:: take(indices, axis=None, out=None, mode='raise') Return a new instance formed from the elements at the given indices. Parameters are as for :meth:`~numpy.ndarray.take`, except that, obviously, no output array can be given. .. py:class:: MarsFixed(*args, copy=True, representation_type=None, differential_type=None, **kwargs) Bases: :py:obj:`_PlanetaryFixed` non-inertial, body-fixed reference frame: Mars .. py:attribute:: body .. py:attribute:: equatorial .. py:attribute:: obstime .. py:method:: to_equatorial(fixed_coo, equatorial_frame) :staticmethod: convert coordinates of a fixed coordinate system to an equatorial one .. py:method:: from_equatorial(equatorial_coo, fixed_frame) :staticmethod: convert coordinates of an equatorial coordinate system to a fixed one .. py:method:: rot_elements_at_epoch(epoch=J2000) :classmethod: Provides rotational elements at epoch. Provides north pole of body and angle to prime meridian. :param epoch: Epoch, default to J2000. :type epoch: ~astropy.time.Time, optional :returns: **ra, dec, W** -- Right ascension and declination of north pole, and angle of the prime meridian. :rtype: tuple (~astropy.units.Quantity) .. py:attribute:: frame_specific_representation_info .. py:attribute:: default_representation .. py:attribute:: default_differential .. py:attribute:: frame_attributes .. py:attribute:: info .. py:method:: __init_subclass__(**kwargs) :classmethod: .. py:method:: cache() Cache for this frame, a dict. It stores anything that should be computed from the coordinate data (*not* from the frame attributes). This can be used in functions to store anything that might be expensive to compute but might be reused by some other function. E.g.:: if 'user_data' in myframe.cache: data = myframe.cache['user_data'] else: myframe.cache['user_data'] = data = expensive_func(myframe.lat) If in-place modifications are made to the frame data, the cache should be cleared:: myframe.cache.clear() .. py:property:: data The coordinate data for this object. If this frame has no data, a `ValueError` will be raised. Use `has_data` to check if data is present on this frame object. .. py:property:: has_data True if this frame has `data`, False otherwise. .. py:property:: shape The shape of the underlying data. .. py:method:: __bool__() Any instance should evaluate to True, except when it is empty. .. py:property:: size The size of the object, as calculated from its shape. .. py:property:: masked Whether the underlying data is masked. :raises ValueError: If the frame has no associated data. .. py:method:: get_mask(*attrs) Get the mask associated with these coordinates. :param \*attrs: Attributes from which to get the masks to combine. Items can be dotted, like ``"data.lon", "data.lat"``. By default, get the combined mask of all components (including from differentials), ignoring possible masks of attributes. :type \*attrs: str :returns: **mask** -- The combined, read-only mask. If the instance is not masked, it is an array of `False` with the correct shape. :rtype: ~numpy.ndarray of bool :raises ValueError: If the coordinate frame has no associated data. .. py:attribute:: mask The mask. .. py:method:: get_frame_attr_defaults() :classmethod: Return a dict with the defaults for each frame attribute. .. py:method:: get_representation_cls(which='base') The class used for part of this frame's data. :param which: The class of which part to return. 'base' means the class used to represent the coordinates; 's' the first derivative to time, i.e., the class representing the proper motion and/or radial velocity. If `None`, return a dict with both. :type which: ('base', 's', `None`) :returns: **representation** :rtype: `~astropy.coordinates.BaseRepresentation` or `~astropy.coordinates.BaseDifferential`. .. py:method:: set_representation_cls(base=None, s='base') Set representation and/or differential class for this frame's data. :param base: The name or subclass to use to represent the coordinate data. :type base: str, `~astropy.coordinates.BaseRepresentation` subclass, optional :param s: The differential subclass to use to represent any velocities, such as proper motion and radial velocity. If equal to 'base', which is the default, it will be inferred from the representation. If `None`, the representation will drop any differentials. :type s: `~astropy.coordinates.BaseDifferential` subclass, optional .. py:attribute:: representation_type .. py:property:: differential_type The differential used for this frame's data. This will be a subclass from `~astropy.coordinates.BaseDifferential`. For simultaneous setting of representation and differentials, see the ``set_representation_cls`` method. .. py:method:: representation_info() A dictionary with the information of what attribute names for this frame apply to particular representations. .. py:method:: get_representation_component_names(which='base') .. py:method:: get_representation_component_units(which='base') .. py:attribute:: representation_component_names .. py:attribute:: representation_component_units .. py:method:: replicate(copy=False, **kwargs) Return a replica of the frame, optionally with new frame attributes. The replica is a new frame object that has the same data as this frame object and with frame attributes overridden if they are provided as extra keyword arguments to this method. If ``copy`` is set to `True` then a copy of the internal arrays will be made. Otherwise the replica will use a reference to the original arrays when possible to save memory. The internal arrays are normally not changeable by the user so in most cases it should not be necessary to set ``copy`` to `True`. :param copy: If True, the resulting object is a copy of the data. When False, references are used where possible. This rule also applies to the frame attributes. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: replicate_without_data(copy=False, **kwargs) Return a replica without data, optionally with new frame attributes. The replica is a new frame object without data but with the same frame attributes as this object, except where overridden by extra keyword arguments to this method. The ``copy`` keyword determines if the frame attributes are truly copied vs being references (which saves memory for cases where frame attributes are large). This method is essentially the converse of `realize_frame`. :param copy: If True, the resulting object has copies of the frame attributes. When False, references are used where possible. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but without data and possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: realize_frame(data, **kwargs) Generates a new frame with new data from another frame (which may or may not have data). Roughly speaking, the converse of `replicate_without_data`. :param data: The representation to use as the data for the new frame. :type data: `~astropy.coordinates.BaseRepresentation` :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. In particular, `representation_type` can be specified. :returns: **frameobj** -- A new object in *this* frame, with the same frame attributes as this one, but with the ``data`` as the coordinate data. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: represent_as(base, s='base', in_frame_units=False) Generate and return a new representation of this frame's `data` as a Representation object. Note: In order to make an in-place change of the representation of a Frame or SkyCoord object, set the ``representation`` attribute of that object to the desired new representation, or use the ``set_representation_cls`` method to also set the differential. :param base: The type of representation to generate. Must be a *class* (not an instance), or the string name of the representation class. :type base: subclass of BaseRepresentation or string :param s: Class in which any velocities should be represented. Must be a *class* (not an instance), or the string name of the differential class. If equal to 'base' (default), inferred from the base class. If `None`, all velocity information is dropped. :type s: subclass of `~astropy.coordinates.BaseDifferential`, str, optional :param in_frame_units: Force the representation units to match the specified units particular to this frame :type in_frame_units: bool, keyword-only :returns: **newrep** -- A new representation object of this frame's `data`. :rtype: BaseRepresentation-derived object :raises AttributeError: If this object had no `data` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import SkyCoord, CartesianRepresentation >>> coord = SkyCoord(0*u.deg, 0*u.deg) >>> coord.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP >>> coord.representation_type = CartesianRepresentation >>> coord # doctest: +FLOAT_CMP .. py:method:: transform_to(new_frame) Transform this object's coordinate data to a new frame. :param new_frame: The frame to transform this coordinate frame into. :type new_frame: coordinate-like :returns: **transframe** -- A new object with the coordinate data represented in the ``newframe`` system. :rtype: coordinate-like :raises ValueError: If there is no possible transformation route. .. py:method:: is_transformable_to(new_frame) Determines if this coordinate frame can be transformed to another given frame. :param new_frame: The proposed frame to transform into. :type new_frame: `~astropy.coordinates.BaseCoordinateFrame` subclass or instance :returns: **transformable** -- `True` if this can be transformed to ``new_frame``, `False` if not, or the string 'same' if ``new_frame`` is the same system as this object but no transformation is defined. :rtype: bool or str .. rubric:: Notes A return value of 'same' means the transformation will work, but it will just give back a copy of this object. The intended usage is:: if coord.is_transformable_to(some_unknown_frame): coord2 = coord.transform_to(some_unknown_frame) This will work even if ``some_unknown_frame`` turns out to be the same frame class as ``coord``. This is intended for cases where the frame is the same regardless of the frame attributes (e.g. ICRS), but be aware that it *might* also indicate that someone forgot to define the transformation between two objects of the same frame class but with different attributes. .. py:method:: is_frame_attr_default(attrnm) Determine whether or not a frame attribute has its value because it's the default value, or because this frame was created with that value explicitly requested. :param attrnm: The name of the attribute to check. :type attrnm: str :returns: **isdefault** -- True if the attribute ``attrnm`` has its value by default, False if it was specified at creation of this frame. :rtype: bool .. py:method:: is_equivalent_frame(other) Checks if this object is the same frame as the ``other`` object. To be the same frame, two objects must be the same frame class and have the same frame attributes. Note that it does *not* matter what, if any, data either object has. :param other: the other frame to check :type other: :class:`~astropy.coordinates.BaseCoordinateFrame` :returns: **isequiv** -- True if the frames are the same, False if not. :rtype: bool :raises TypeError: If ``other`` isn't a `~astropy.coordinates.BaseCoordinateFrame` or subclass. .. py:method:: __repr__() .. py:method:: __setitem__(item, value) .. py:method:: insert(obj, values, axis=0) .. py:method:: __dir__() Override the builtin `dir` behavior to include representation names. TODO: dynamic representation transforms (i.e. include cylindrical et al.). .. py:method:: __getattr__(attr) Allow access to attributes on the representation and differential as found via ``self.get_representation_component_names``. TODO: We should handle dynamic representation transforms here (e.g., `.cylindrical`) instead of defining properties as below. .. py:method:: __setattr__(attr, value) .. py:method:: __eq__(value) Equality operator for frame. This implements strict equality and requires that the frames are equivalent and that the representation data are exactly equal. .. py:method:: __ne__(value) .. py:method:: position_angle(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord]) -> astropy.coordinates.angles.Angle Compute the on-sky position angle to another coordinate. :param other: The other coordinate to compute the position angle to. It is treated as the "head" of the vector of the position angle. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: The (positive) position angle of the vector pointing from ``self`` to ``other``, measured East from North. If either ``self`` or ``other`` contain arrays, this will be an array following the appropriate `numpy` broadcasting rules. :rtype: `~astropy.coordinates.Angle` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import ICRS, SkyCoord >>> c1 = SkyCoord(0*u.deg, 0*u.deg) >>> c2 = ICRS(1*u.deg, 0*u.deg) >>> c1.position_angle(c2).to(u.deg) >>> c2.position_angle(c1).to(u.deg) >>> c3 = SkyCoord(1*u.deg, 1*u.deg) >>> c1.position_angle(c3).to(u.deg) # doctest: +FLOAT_CMP .. py:method:: separation(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord], *, origin_mismatch: Literal['ignore', 'warn', 'error'] = 'warn') -> astropy.coordinates.angles.Angle Computes on-sky separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate to get the separation to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :param origin_mismatch: If the ``other`` coordinates are in a different frame then they will have to be transformed, and if the transformation is not a pure rotation then ``self.separation(other)`` can be different from ``other.separation(self)``. With ``origin_mismatch="warn"`` (default) the transformation is always performed, but a warning is emitted if it is not a pure rotation. If ``origin_mismatch="ignore"`` then the required transformation is always performed without warnings. If ``origin_mismatch="error"`` then only transformations that are pure rotations are allowed. :type origin_mismatch: {"warn", "ignore", "error"}, keyword-only :returns: **sep** -- The on-sky separation between this and the ``other`` coordinate. :rtype: `~astropy.coordinates.Angle` .. rubric:: Notes The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [1]_. .. [1] https://en.wikipedia.org/wiki/Great-circle_distance .. py:method:: separation_3d(other) Computes three dimensional separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate system to get the distance to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: **sep** -- The real-space distance between these two coordinates. :rtype: `~astropy.coordinates.Distance` :raises ValueError: If this or the other coordinate do not have distances. .. py:property:: cartesian Shorthand for a cartesian representation of the coordinates in this object. .. py:property:: cylindrical Shorthand for a cylindrical representation of the coordinates in this object. .. py:property:: spherical Shorthand for a spherical representation of the coordinates in this object. .. py:property:: sphericalcoslat Shorthand for a spherical representation of the positional data and a `~astropy.coordinates.SphericalCosLatDifferential` for the velocity data in this object. .. py:property:: velocity Shorthand for retrieving the Cartesian space-motion as a `~astropy.coordinates.CartesianDifferential` object. This is equivalent to calling ``self.cartesian.differentials['s']``. .. py:property:: proper_motion Shorthand for the two-dimensional proper motion as a `~astropy.units.Quantity` object with angular velocity units. In the returned `~astropy.units.Quantity`, ``axis=0`` is the longitude/latitude dimension so that ``.proper_motion[0]`` is the longitudinal proper motion and ``.proper_motion[1]`` is latitudinal. The longitudinal proper motion already includes the cos(latitude) term. .. py:property:: radial_velocity Shorthand for the radial or line-of-sight velocity as a `~astropy.units.Quantity` object. .. py:method:: to_table() -> astropy.table.QTable Convert this |BaseFrame| to a |QTable|. Any attributes that have the same length as the |BaseFrame| will be converted to columns of the |QTable|. All other attributes will be recorded as metadata. :returns: A |QTable| containing the data of this |BaseFrame|. :rtype: `~astropy.table.QTable` .. rubric:: Examples >>> from astropy.coordinates import ICRS >>> coord = ICRS(ra=[40, 70]*u.deg, dec=[0, -20]*u.deg) >>> t = coord.to_table() >>> t ra dec deg deg float64 float64 ------- ------- 40.0 0.0 70.0 -20.0 >>> t.meta {'representation_type': 'spherical'} .. py:property:: unmasked Get an instance without the mask. Note that while one gets a new instance, the underlying data will be shared. .. seealso:: :py:obj:`filled` get a copy of the underlying data, with masked values filled in. .. py:method:: filled(fill_value) Get a copy of the underlying data, with masked values filled in. :param fill_value: Value to replace masked values with. :type fill_value: object :returns: **filled** -- Copy of ``self`` with masked items replaced by ``fill_value``. :rtype: instance .. seealso:: :py:obj:`unmasked` get an instance without the mask. .. py:property:: ndim :type: int The number of dimensions of the instance and underlying arrays. .. py:property:: isscalar :type: bool .. py:method:: __len__() -> int .. py:method:: __getitem__(item) .. py:method:: __iter__() .. py:method:: __array_function__(function, types, args, kwargs) Wrap numpy functions that make sense. .. py:method:: copy(*args, **kwargs) Return an instance containing copies of the internal data. Parameters are as for :meth:`~numpy.ndarray.copy`. .. py:method:: reshape(*args, **kwargs) Returns an instance containing the same data with a new shape. Parameters are as for :meth:`~numpy.ndarray.reshape`. Note that it is not always possible to change the shape of an array without copying the data (see :func:`~numpy.reshape` documentation). If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute (note: this may not be implemented for all classes using ``NDArrayShapeMethods``). .. py:method:: ravel(*args, **kwargs) Return an instance with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.ravel`. Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape ``(-1,)`` to the shape attribute. .. py:method:: flatten(*args, **kwargs) Return a copy with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.flatten`. .. py:method:: transpose(*args, **kwargs) Return an instance with the data transposed. Parameters are as for :meth:`~numpy.ndarray.transpose`. All internal data are views of the data of the original. .. py:property:: T :type: Self Return an instance with the data transposed. Parameters are as for :attr:`~numpy.ndarray.T`. All internal data are views of the data of the original. .. py:method:: swapaxes(*args, **kwargs) Return an instance with the given axes interchanged. Parameters are as for :meth:`~numpy.ndarray.swapaxes`: ``axis1, axis2``. All internal data are views of the data of the original. .. py:method:: diagonal(*args, **kwargs) Return an instance with the specified diagonals. Parameters are as for :meth:`~numpy.ndarray.diagonal`. All internal data are views of the data of the original. .. py:method:: squeeze(*args, **kwargs) Return an instance with single-dimensional shape entries removed. Parameters are as for :meth:`~numpy.ndarray.squeeze`. All internal data are views of the data of the original. .. py:method:: take(indices, axis=None, out=None, mode='raise') Return a new instance formed from the elements at the given indices. Parameters are as for :meth:`~numpy.ndarray.take`, except that, obviously, no output array can be given. .. py:class:: JupiterFixed(*args, copy=True, representation_type=None, differential_type=None, **kwargs) Bases: :py:obj:`_PlanetaryFixed` non-inertial, body-fixed reference frame: Jupiter .. py:attribute:: body .. py:attribute:: equatorial .. py:attribute:: obstime .. py:method:: to_equatorial(fixed_coo, equatorial_frame) :staticmethod: convert coordinates of a fixed coordinate system to an equatorial one .. py:method:: from_equatorial(equatorial_coo, fixed_frame) :staticmethod: convert coordinates of an equatorial coordinate system to a fixed one .. py:method:: rot_elements_at_epoch(epoch=J2000) :classmethod: Provides rotational elements at epoch. Provides north pole of body and angle to prime meridian. :param epoch: Epoch, default to J2000. :type epoch: ~astropy.time.Time, optional :returns: **ra, dec, W** -- Right ascension and declination of north pole, and angle of the prime meridian. :rtype: tuple (~astropy.units.Quantity) .. py:attribute:: frame_specific_representation_info .. py:attribute:: default_representation .. py:attribute:: default_differential .. py:attribute:: frame_attributes .. py:attribute:: info .. py:method:: __init_subclass__(**kwargs) :classmethod: .. py:method:: cache() Cache for this frame, a dict. It stores anything that should be computed from the coordinate data (*not* from the frame attributes). This can be used in functions to store anything that might be expensive to compute but might be reused by some other function. E.g.:: if 'user_data' in myframe.cache: data = myframe.cache['user_data'] else: myframe.cache['user_data'] = data = expensive_func(myframe.lat) If in-place modifications are made to the frame data, the cache should be cleared:: myframe.cache.clear() .. py:property:: data The coordinate data for this object. If this frame has no data, a `ValueError` will be raised. Use `has_data` to check if data is present on this frame object. .. py:property:: has_data True if this frame has `data`, False otherwise. .. py:property:: shape The shape of the underlying data. .. py:method:: __bool__() Any instance should evaluate to True, except when it is empty. .. py:property:: size The size of the object, as calculated from its shape. .. py:property:: masked Whether the underlying data is masked. :raises ValueError: If the frame has no associated data. .. py:method:: get_mask(*attrs) Get the mask associated with these coordinates. :param \*attrs: Attributes from which to get the masks to combine. Items can be dotted, like ``"data.lon", "data.lat"``. By default, get the combined mask of all components (including from differentials), ignoring possible masks of attributes. :type \*attrs: str :returns: **mask** -- The combined, read-only mask. If the instance is not masked, it is an array of `False` with the correct shape. :rtype: ~numpy.ndarray of bool :raises ValueError: If the coordinate frame has no associated data. .. py:attribute:: mask The mask. .. py:method:: get_frame_attr_defaults() :classmethod: Return a dict with the defaults for each frame attribute. .. py:method:: get_representation_cls(which='base') The class used for part of this frame's data. :param which: The class of which part to return. 'base' means the class used to represent the coordinates; 's' the first derivative to time, i.e., the class representing the proper motion and/or radial velocity. If `None`, return a dict with both. :type which: ('base', 's', `None`) :returns: **representation** :rtype: `~astropy.coordinates.BaseRepresentation` or `~astropy.coordinates.BaseDifferential`. .. py:method:: set_representation_cls(base=None, s='base') Set representation and/or differential class for this frame's data. :param base: The name or subclass to use to represent the coordinate data. :type base: str, `~astropy.coordinates.BaseRepresentation` subclass, optional :param s: The differential subclass to use to represent any velocities, such as proper motion and radial velocity. If equal to 'base', which is the default, it will be inferred from the representation. If `None`, the representation will drop any differentials. :type s: `~astropy.coordinates.BaseDifferential` subclass, optional .. py:attribute:: representation_type .. py:property:: differential_type The differential used for this frame's data. This will be a subclass from `~astropy.coordinates.BaseDifferential`. For simultaneous setting of representation and differentials, see the ``set_representation_cls`` method. .. py:method:: representation_info() A dictionary with the information of what attribute names for this frame apply to particular representations. .. py:method:: get_representation_component_names(which='base') .. py:method:: get_representation_component_units(which='base') .. py:attribute:: representation_component_names .. py:attribute:: representation_component_units .. py:method:: replicate(copy=False, **kwargs) Return a replica of the frame, optionally with new frame attributes. The replica is a new frame object that has the same data as this frame object and with frame attributes overridden if they are provided as extra keyword arguments to this method. If ``copy`` is set to `True` then a copy of the internal arrays will be made. Otherwise the replica will use a reference to the original arrays when possible to save memory. The internal arrays are normally not changeable by the user so in most cases it should not be necessary to set ``copy`` to `True`. :param copy: If True, the resulting object is a copy of the data. When False, references are used where possible. This rule also applies to the frame attributes. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: replicate_without_data(copy=False, **kwargs) Return a replica without data, optionally with new frame attributes. The replica is a new frame object without data but with the same frame attributes as this object, except where overridden by extra keyword arguments to this method. The ``copy`` keyword determines if the frame attributes are truly copied vs being references (which saves memory for cases where frame attributes are large). This method is essentially the converse of `realize_frame`. :param copy: If True, the resulting object has copies of the frame attributes. When False, references are used where possible. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but without data and possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: realize_frame(data, **kwargs) Generates a new frame with new data from another frame (which may or may not have data). Roughly speaking, the converse of `replicate_without_data`. :param data: The representation to use as the data for the new frame. :type data: `~astropy.coordinates.BaseRepresentation` :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. In particular, `representation_type` can be specified. :returns: **frameobj** -- A new object in *this* frame, with the same frame attributes as this one, but with the ``data`` as the coordinate data. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: represent_as(base, s='base', in_frame_units=False) Generate and return a new representation of this frame's `data` as a Representation object. Note: In order to make an in-place change of the representation of a Frame or SkyCoord object, set the ``representation`` attribute of that object to the desired new representation, or use the ``set_representation_cls`` method to also set the differential. :param base: The type of representation to generate. Must be a *class* (not an instance), or the string name of the representation class. :type base: subclass of BaseRepresentation or string :param s: Class in which any velocities should be represented. Must be a *class* (not an instance), or the string name of the differential class. If equal to 'base' (default), inferred from the base class. If `None`, all velocity information is dropped. :type s: subclass of `~astropy.coordinates.BaseDifferential`, str, optional :param in_frame_units: Force the representation units to match the specified units particular to this frame :type in_frame_units: bool, keyword-only :returns: **newrep** -- A new representation object of this frame's `data`. :rtype: BaseRepresentation-derived object :raises AttributeError: If this object had no `data` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import SkyCoord, CartesianRepresentation >>> coord = SkyCoord(0*u.deg, 0*u.deg) >>> coord.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP >>> coord.representation_type = CartesianRepresentation >>> coord # doctest: +FLOAT_CMP .. py:method:: transform_to(new_frame) Transform this object's coordinate data to a new frame. :param new_frame: The frame to transform this coordinate frame into. :type new_frame: coordinate-like :returns: **transframe** -- A new object with the coordinate data represented in the ``newframe`` system. :rtype: coordinate-like :raises ValueError: If there is no possible transformation route. .. py:method:: is_transformable_to(new_frame) Determines if this coordinate frame can be transformed to another given frame. :param new_frame: The proposed frame to transform into. :type new_frame: `~astropy.coordinates.BaseCoordinateFrame` subclass or instance :returns: **transformable** -- `True` if this can be transformed to ``new_frame``, `False` if not, or the string 'same' if ``new_frame`` is the same system as this object but no transformation is defined. :rtype: bool or str .. rubric:: Notes A return value of 'same' means the transformation will work, but it will just give back a copy of this object. The intended usage is:: if coord.is_transformable_to(some_unknown_frame): coord2 = coord.transform_to(some_unknown_frame) This will work even if ``some_unknown_frame`` turns out to be the same frame class as ``coord``. This is intended for cases where the frame is the same regardless of the frame attributes (e.g. ICRS), but be aware that it *might* also indicate that someone forgot to define the transformation between two objects of the same frame class but with different attributes. .. py:method:: is_frame_attr_default(attrnm) Determine whether or not a frame attribute has its value because it's the default value, or because this frame was created with that value explicitly requested. :param attrnm: The name of the attribute to check. :type attrnm: str :returns: **isdefault** -- True if the attribute ``attrnm`` has its value by default, False if it was specified at creation of this frame. :rtype: bool .. py:method:: is_equivalent_frame(other) Checks if this object is the same frame as the ``other`` object. To be the same frame, two objects must be the same frame class and have the same frame attributes. Note that it does *not* matter what, if any, data either object has. :param other: the other frame to check :type other: :class:`~astropy.coordinates.BaseCoordinateFrame` :returns: **isequiv** -- True if the frames are the same, False if not. :rtype: bool :raises TypeError: If ``other`` isn't a `~astropy.coordinates.BaseCoordinateFrame` or subclass. .. py:method:: __repr__() .. py:method:: __setitem__(item, value) .. py:method:: insert(obj, values, axis=0) .. py:method:: __dir__() Override the builtin `dir` behavior to include representation names. TODO: dynamic representation transforms (i.e. include cylindrical et al.). .. py:method:: __getattr__(attr) Allow access to attributes on the representation and differential as found via ``self.get_representation_component_names``. TODO: We should handle dynamic representation transforms here (e.g., `.cylindrical`) instead of defining properties as below. .. py:method:: __setattr__(attr, value) .. py:method:: __eq__(value) Equality operator for frame. This implements strict equality and requires that the frames are equivalent and that the representation data are exactly equal. .. py:method:: __ne__(value) .. py:method:: position_angle(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord]) -> astropy.coordinates.angles.Angle Compute the on-sky position angle to another coordinate. :param other: The other coordinate to compute the position angle to. It is treated as the "head" of the vector of the position angle. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: The (positive) position angle of the vector pointing from ``self`` to ``other``, measured East from North. If either ``self`` or ``other`` contain arrays, this will be an array following the appropriate `numpy` broadcasting rules. :rtype: `~astropy.coordinates.Angle` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import ICRS, SkyCoord >>> c1 = SkyCoord(0*u.deg, 0*u.deg) >>> c2 = ICRS(1*u.deg, 0*u.deg) >>> c1.position_angle(c2).to(u.deg) >>> c2.position_angle(c1).to(u.deg) >>> c3 = SkyCoord(1*u.deg, 1*u.deg) >>> c1.position_angle(c3).to(u.deg) # doctest: +FLOAT_CMP .. py:method:: separation(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord], *, origin_mismatch: Literal['ignore', 'warn', 'error'] = 'warn') -> astropy.coordinates.angles.Angle Computes on-sky separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate to get the separation to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :param origin_mismatch: If the ``other`` coordinates are in a different frame then they will have to be transformed, and if the transformation is not a pure rotation then ``self.separation(other)`` can be different from ``other.separation(self)``. With ``origin_mismatch="warn"`` (default) the transformation is always performed, but a warning is emitted if it is not a pure rotation. If ``origin_mismatch="ignore"`` then the required transformation is always performed without warnings. If ``origin_mismatch="error"`` then only transformations that are pure rotations are allowed. :type origin_mismatch: {"warn", "ignore", "error"}, keyword-only :returns: **sep** -- The on-sky separation between this and the ``other`` coordinate. :rtype: `~astropy.coordinates.Angle` .. rubric:: Notes The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [1]_. .. [1] https://en.wikipedia.org/wiki/Great-circle_distance .. py:method:: separation_3d(other) Computes three dimensional separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate system to get the distance to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: **sep** -- The real-space distance between these two coordinates. :rtype: `~astropy.coordinates.Distance` :raises ValueError: If this or the other coordinate do not have distances. .. py:property:: cartesian Shorthand for a cartesian representation of the coordinates in this object. .. py:property:: cylindrical Shorthand for a cylindrical representation of the coordinates in this object. .. py:property:: spherical Shorthand for a spherical representation of the coordinates in this object. .. py:property:: sphericalcoslat Shorthand for a spherical representation of the positional data and a `~astropy.coordinates.SphericalCosLatDifferential` for the velocity data in this object. .. py:property:: velocity Shorthand for retrieving the Cartesian space-motion as a `~astropy.coordinates.CartesianDifferential` object. This is equivalent to calling ``self.cartesian.differentials['s']``. .. py:property:: proper_motion Shorthand for the two-dimensional proper motion as a `~astropy.units.Quantity` object with angular velocity units. In the returned `~astropy.units.Quantity`, ``axis=0`` is the longitude/latitude dimension so that ``.proper_motion[0]`` is the longitudinal proper motion and ``.proper_motion[1]`` is latitudinal. The longitudinal proper motion already includes the cos(latitude) term. .. py:property:: radial_velocity Shorthand for the radial or line-of-sight velocity as a `~astropy.units.Quantity` object. .. py:method:: to_table() -> astropy.table.QTable Convert this |BaseFrame| to a |QTable|. Any attributes that have the same length as the |BaseFrame| will be converted to columns of the |QTable|. All other attributes will be recorded as metadata. :returns: A |QTable| containing the data of this |BaseFrame|. :rtype: `~astropy.table.QTable` .. rubric:: Examples >>> from astropy.coordinates import ICRS >>> coord = ICRS(ra=[40, 70]*u.deg, dec=[0, -20]*u.deg) >>> t = coord.to_table() >>> t ra dec deg deg float64 float64 ------- ------- 40.0 0.0 70.0 -20.0 >>> t.meta {'representation_type': 'spherical'} .. py:property:: unmasked Get an instance without the mask. Note that while one gets a new instance, the underlying data will be shared. .. seealso:: :py:obj:`filled` get a copy of the underlying data, with masked values filled in. .. py:method:: filled(fill_value) Get a copy of the underlying data, with masked values filled in. :param fill_value: Value to replace masked values with. :type fill_value: object :returns: **filled** -- Copy of ``self`` with masked items replaced by ``fill_value``. :rtype: instance .. seealso:: :py:obj:`unmasked` get an instance without the mask. .. py:property:: ndim :type: int The number of dimensions of the instance and underlying arrays. .. py:property:: isscalar :type: bool .. py:method:: __len__() -> int .. py:method:: __getitem__(item) .. py:method:: __iter__() .. py:method:: __array_function__(function, types, args, kwargs) Wrap numpy functions that make sense. .. py:method:: copy(*args, **kwargs) Return an instance containing copies of the internal data. Parameters are as for :meth:`~numpy.ndarray.copy`. .. py:method:: reshape(*args, **kwargs) Returns an instance containing the same data with a new shape. Parameters are as for :meth:`~numpy.ndarray.reshape`. Note that it is not always possible to change the shape of an array without copying the data (see :func:`~numpy.reshape` documentation). If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute (note: this may not be implemented for all classes using ``NDArrayShapeMethods``). .. py:method:: ravel(*args, **kwargs) Return an instance with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.ravel`. Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape ``(-1,)`` to the shape attribute. .. py:method:: flatten(*args, **kwargs) Return a copy with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.flatten`. .. py:method:: transpose(*args, **kwargs) Return an instance with the data transposed. Parameters are as for :meth:`~numpy.ndarray.transpose`. All internal data are views of the data of the original. .. py:property:: T :type: Self Return an instance with the data transposed. Parameters are as for :attr:`~numpy.ndarray.T`. All internal data are views of the data of the original. .. py:method:: swapaxes(*args, **kwargs) Return an instance with the given axes interchanged. Parameters are as for :meth:`~numpy.ndarray.swapaxes`: ``axis1, axis2``. All internal data are views of the data of the original. .. py:method:: diagonal(*args, **kwargs) Return an instance with the specified diagonals. Parameters are as for :meth:`~numpy.ndarray.diagonal`. All internal data are views of the data of the original. .. py:method:: squeeze(*args, **kwargs) Return an instance with single-dimensional shape entries removed. Parameters are as for :meth:`~numpy.ndarray.squeeze`. All internal data are views of the data of the original. .. py:method:: take(indices, axis=None, out=None, mode='raise') Return a new instance formed from the elements at the given indices. Parameters are as for :meth:`~numpy.ndarray.take`, except that, obviously, no output array can be given. .. py:class:: SaturnFixed(*args, copy=True, representation_type=None, differential_type=None, **kwargs) Bases: :py:obj:`_PlanetaryFixed` non-inertial, body-fixed reference frame: Saturn .. py:attribute:: body .. py:attribute:: equatorial .. py:attribute:: obstime .. py:method:: to_equatorial(fixed_coo, equatorial_frame) :staticmethod: convert coordinates of a fixed coordinate system to an equatorial one .. py:method:: from_equatorial(equatorial_coo, fixed_frame) :staticmethod: convert coordinates of an equatorial coordinate system to a fixed one .. py:method:: rot_elements_at_epoch(epoch=J2000) :classmethod: Provides rotational elements at epoch. Provides north pole of body and angle to prime meridian. :param epoch: Epoch, default to J2000. :type epoch: ~astropy.time.Time, optional :returns: **ra, dec, W** -- Right ascension and declination of north pole, and angle of the prime meridian. :rtype: tuple (~astropy.units.Quantity) .. py:attribute:: frame_specific_representation_info .. py:attribute:: default_representation .. py:attribute:: default_differential .. py:attribute:: frame_attributes .. py:attribute:: info .. py:method:: __init_subclass__(**kwargs) :classmethod: .. py:method:: cache() Cache for this frame, a dict. It stores anything that should be computed from the coordinate data (*not* from the frame attributes). This can be used in functions to store anything that might be expensive to compute but might be reused by some other function. E.g.:: if 'user_data' in myframe.cache: data = myframe.cache['user_data'] else: myframe.cache['user_data'] = data = expensive_func(myframe.lat) If in-place modifications are made to the frame data, the cache should be cleared:: myframe.cache.clear() .. py:property:: data The coordinate data for this object. If this frame has no data, a `ValueError` will be raised. Use `has_data` to check if data is present on this frame object. .. py:property:: has_data True if this frame has `data`, False otherwise. .. py:property:: shape The shape of the underlying data. .. py:method:: __bool__() Any instance should evaluate to True, except when it is empty. .. py:property:: size The size of the object, as calculated from its shape. .. py:property:: masked Whether the underlying data is masked. :raises ValueError: If the frame has no associated data. .. py:method:: get_mask(*attrs) Get the mask associated with these coordinates. :param \*attrs: Attributes from which to get the masks to combine. Items can be dotted, like ``"data.lon", "data.lat"``. By default, get the combined mask of all components (including from differentials), ignoring possible masks of attributes. :type \*attrs: str :returns: **mask** -- The combined, read-only mask. If the instance is not masked, it is an array of `False` with the correct shape. :rtype: ~numpy.ndarray of bool :raises ValueError: If the coordinate frame has no associated data. .. py:attribute:: mask The mask. .. py:method:: get_frame_attr_defaults() :classmethod: Return a dict with the defaults for each frame attribute. .. py:method:: get_representation_cls(which='base') The class used for part of this frame's data. :param which: The class of which part to return. 'base' means the class used to represent the coordinates; 's' the first derivative to time, i.e., the class representing the proper motion and/or radial velocity. If `None`, return a dict with both. :type which: ('base', 's', `None`) :returns: **representation** :rtype: `~astropy.coordinates.BaseRepresentation` or `~astropy.coordinates.BaseDifferential`. .. py:method:: set_representation_cls(base=None, s='base') Set representation and/or differential class for this frame's data. :param base: The name or subclass to use to represent the coordinate data. :type base: str, `~astropy.coordinates.BaseRepresentation` subclass, optional :param s: The differential subclass to use to represent any velocities, such as proper motion and radial velocity. If equal to 'base', which is the default, it will be inferred from the representation. If `None`, the representation will drop any differentials. :type s: `~astropy.coordinates.BaseDifferential` subclass, optional .. py:attribute:: representation_type .. py:property:: differential_type The differential used for this frame's data. This will be a subclass from `~astropy.coordinates.BaseDifferential`. For simultaneous setting of representation and differentials, see the ``set_representation_cls`` method. .. py:method:: representation_info() A dictionary with the information of what attribute names for this frame apply to particular representations. .. py:method:: get_representation_component_names(which='base') .. py:method:: get_representation_component_units(which='base') .. py:attribute:: representation_component_names .. py:attribute:: representation_component_units .. py:method:: replicate(copy=False, **kwargs) Return a replica of the frame, optionally with new frame attributes. The replica is a new frame object that has the same data as this frame object and with frame attributes overridden if they are provided as extra keyword arguments to this method. If ``copy`` is set to `True` then a copy of the internal arrays will be made. Otherwise the replica will use a reference to the original arrays when possible to save memory. The internal arrays are normally not changeable by the user so in most cases it should not be necessary to set ``copy`` to `True`. :param copy: If True, the resulting object is a copy of the data. When False, references are used where possible. This rule also applies to the frame attributes. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: replicate_without_data(copy=False, **kwargs) Return a replica without data, optionally with new frame attributes. The replica is a new frame object without data but with the same frame attributes as this object, except where overridden by extra keyword arguments to this method. The ``copy`` keyword determines if the frame attributes are truly copied vs being references (which saves memory for cases where frame attributes are large). This method is essentially the converse of `realize_frame`. :param copy: If True, the resulting object has copies of the frame attributes. When False, references are used where possible. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but without data and possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: realize_frame(data, **kwargs) Generates a new frame with new data from another frame (which may or may not have data). Roughly speaking, the converse of `replicate_without_data`. :param data: The representation to use as the data for the new frame. :type data: `~astropy.coordinates.BaseRepresentation` :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. In particular, `representation_type` can be specified. :returns: **frameobj** -- A new object in *this* frame, with the same frame attributes as this one, but with the ``data`` as the coordinate data. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: represent_as(base, s='base', in_frame_units=False) Generate and return a new representation of this frame's `data` as a Representation object. Note: In order to make an in-place change of the representation of a Frame or SkyCoord object, set the ``representation`` attribute of that object to the desired new representation, or use the ``set_representation_cls`` method to also set the differential. :param base: The type of representation to generate. Must be a *class* (not an instance), or the string name of the representation class. :type base: subclass of BaseRepresentation or string :param s: Class in which any velocities should be represented. Must be a *class* (not an instance), or the string name of the differential class. If equal to 'base' (default), inferred from the base class. If `None`, all velocity information is dropped. :type s: subclass of `~astropy.coordinates.BaseDifferential`, str, optional :param in_frame_units: Force the representation units to match the specified units particular to this frame :type in_frame_units: bool, keyword-only :returns: **newrep** -- A new representation object of this frame's `data`. :rtype: BaseRepresentation-derived object :raises AttributeError: If this object had no `data` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import SkyCoord, CartesianRepresentation >>> coord = SkyCoord(0*u.deg, 0*u.deg) >>> coord.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP >>> coord.representation_type = CartesianRepresentation >>> coord # doctest: +FLOAT_CMP .. py:method:: transform_to(new_frame) Transform this object's coordinate data to a new frame. :param new_frame: The frame to transform this coordinate frame into. :type new_frame: coordinate-like :returns: **transframe** -- A new object with the coordinate data represented in the ``newframe`` system. :rtype: coordinate-like :raises ValueError: If there is no possible transformation route. .. py:method:: is_transformable_to(new_frame) Determines if this coordinate frame can be transformed to another given frame. :param new_frame: The proposed frame to transform into. :type new_frame: `~astropy.coordinates.BaseCoordinateFrame` subclass or instance :returns: **transformable** -- `True` if this can be transformed to ``new_frame``, `False` if not, or the string 'same' if ``new_frame`` is the same system as this object but no transformation is defined. :rtype: bool or str .. rubric:: Notes A return value of 'same' means the transformation will work, but it will just give back a copy of this object. The intended usage is:: if coord.is_transformable_to(some_unknown_frame): coord2 = coord.transform_to(some_unknown_frame) This will work even if ``some_unknown_frame`` turns out to be the same frame class as ``coord``. This is intended for cases where the frame is the same regardless of the frame attributes (e.g. ICRS), but be aware that it *might* also indicate that someone forgot to define the transformation between two objects of the same frame class but with different attributes. .. py:method:: is_frame_attr_default(attrnm) Determine whether or not a frame attribute has its value because it's the default value, or because this frame was created with that value explicitly requested. :param attrnm: The name of the attribute to check. :type attrnm: str :returns: **isdefault** -- True if the attribute ``attrnm`` has its value by default, False if it was specified at creation of this frame. :rtype: bool .. py:method:: is_equivalent_frame(other) Checks if this object is the same frame as the ``other`` object. To be the same frame, two objects must be the same frame class and have the same frame attributes. Note that it does *not* matter what, if any, data either object has. :param other: the other frame to check :type other: :class:`~astropy.coordinates.BaseCoordinateFrame` :returns: **isequiv** -- True if the frames are the same, False if not. :rtype: bool :raises TypeError: If ``other`` isn't a `~astropy.coordinates.BaseCoordinateFrame` or subclass. .. py:method:: __repr__() .. py:method:: __setitem__(item, value) .. py:method:: insert(obj, values, axis=0) .. py:method:: __dir__() Override the builtin `dir` behavior to include representation names. TODO: dynamic representation transforms (i.e. include cylindrical et al.). .. py:method:: __getattr__(attr) Allow access to attributes on the representation and differential as found via ``self.get_representation_component_names``. TODO: We should handle dynamic representation transforms here (e.g., `.cylindrical`) instead of defining properties as below. .. py:method:: __setattr__(attr, value) .. py:method:: __eq__(value) Equality operator for frame. This implements strict equality and requires that the frames are equivalent and that the representation data are exactly equal. .. py:method:: __ne__(value) .. py:method:: position_angle(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord]) -> astropy.coordinates.angles.Angle Compute the on-sky position angle to another coordinate. :param other: The other coordinate to compute the position angle to. It is treated as the "head" of the vector of the position angle. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: The (positive) position angle of the vector pointing from ``self`` to ``other``, measured East from North. If either ``self`` or ``other`` contain arrays, this will be an array following the appropriate `numpy` broadcasting rules. :rtype: `~astropy.coordinates.Angle` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import ICRS, SkyCoord >>> c1 = SkyCoord(0*u.deg, 0*u.deg) >>> c2 = ICRS(1*u.deg, 0*u.deg) >>> c1.position_angle(c2).to(u.deg) >>> c2.position_angle(c1).to(u.deg) >>> c3 = SkyCoord(1*u.deg, 1*u.deg) >>> c1.position_angle(c3).to(u.deg) # doctest: +FLOAT_CMP .. py:method:: separation(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord], *, origin_mismatch: Literal['ignore', 'warn', 'error'] = 'warn') -> astropy.coordinates.angles.Angle Computes on-sky separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate to get the separation to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :param origin_mismatch: If the ``other`` coordinates are in a different frame then they will have to be transformed, and if the transformation is not a pure rotation then ``self.separation(other)`` can be different from ``other.separation(self)``. With ``origin_mismatch="warn"`` (default) the transformation is always performed, but a warning is emitted if it is not a pure rotation. If ``origin_mismatch="ignore"`` then the required transformation is always performed without warnings. If ``origin_mismatch="error"`` then only transformations that are pure rotations are allowed. :type origin_mismatch: {"warn", "ignore", "error"}, keyword-only :returns: **sep** -- The on-sky separation between this and the ``other`` coordinate. :rtype: `~astropy.coordinates.Angle` .. rubric:: Notes The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [1]_. .. [1] https://en.wikipedia.org/wiki/Great-circle_distance .. py:method:: separation_3d(other) Computes three dimensional separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate system to get the distance to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: **sep** -- The real-space distance between these two coordinates. :rtype: `~astropy.coordinates.Distance` :raises ValueError: If this or the other coordinate do not have distances. .. py:property:: cartesian Shorthand for a cartesian representation of the coordinates in this object. .. py:property:: cylindrical Shorthand for a cylindrical representation of the coordinates in this object. .. py:property:: spherical Shorthand for a spherical representation of the coordinates in this object. .. py:property:: sphericalcoslat Shorthand for a spherical representation of the positional data and a `~astropy.coordinates.SphericalCosLatDifferential` for the velocity data in this object. .. py:property:: velocity Shorthand for retrieving the Cartesian space-motion as a `~astropy.coordinates.CartesianDifferential` object. This is equivalent to calling ``self.cartesian.differentials['s']``. .. py:property:: proper_motion Shorthand for the two-dimensional proper motion as a `~astropy.units.Quantity` object with angular velocity units. In the returned `~astropy.units.Quantity`, ``axis=0`` is the longitude/latitude dimension so that ``.proper_motion[0]`` is the longitudinal proper motion and ``.proper_motion[1]`` is latitudinal. The longitudinal proper motion already includes the cos(latitude) term. .. py:property:: radial_velocity Shorthand for the radial or line-of-sight velocity as a `~astropy.units.Quantity` object. .. py:method:: to_table() -> astropy.table.QTable Convert this |BaseFrame| to a |QTable|. Any attributes that have the same length as the |BaseFrame| will be converted to columns of the |QTable|. All other attributes will be recorded as metadata. :returns: A |QTable| containing the data of this |BaseFrame|. :rtype: `~astropy.table.QTable` .. rubric:: Examples >>> from astropy.coordinates import ICRS >>> coord = ICRS(ra=[40, 70]*u.deg, dec=[0, -20]*u.deg) >>> t = coord.to_table() >>> t ra dec deg deg float64 float64 ------- ------- 40.0 0.0 70.0 -20.0 >>> t.meta {'representation_type': 'spherical'} .. py:property:: unmasked Get an instance without the mask. Note that while one gets a new instance, the underlying data will be shared. .. seealso:: :py:obj:`filled` get a copy of the underlying data, with masked values filled in. .. py:method:: filled(fill_value) Get a copy of the underlying data, with masked values filled in. :param fill_value: Value to replace masked values with. :type fill_value: object :returns: **filled** -- Copy of ``self`` with masked items replaced by ``fill_value``. :rtype: instance .. seealso:: :py:obj:`unmasked` get an instance without the mask. .. py:property:: ndim :type: int The number of dimensions of the instance and underlying arrays. .. py:property:: isscalar :type: bool .. py:method:: __len__() -> int .. py:method:: __getitem__(item) .. py:method:: __iter__() .. py:method:: __array_function__(function, types, args, kwargs) Wrap numpy functions that make sense. .. py:method:: copy(*args, **kwargs) Return an instance containing copies of the internal data. Parameters are as for :meth:`~numpy.ndarray.copy`. .. py:method:: reshape(*args, **kwargs) Returns an instance containing the same data with a new shape. Parameters are as for :meth:`~numpy.ndarray.reshape`. Note that it is not always possible to change the shape of an array without copying the data (see :func:`~numpy.reshape` documentation). If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute (note: this may not be implemented for all classes using ``NDArrayShapeMethods``). .. py:method:: ravel(*args, **kwargs) Return an instance with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.ravel`. Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape ``(-1,)`` to the shape attribute. .. py:method:: flatten(*args, **kwargs) Return a copy with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.flatten`. .. py:method:: transpose(*args, **kwargs) Return an instance with the data transposed. Parameters are as for :meth:`~numpy.ndarray.transpose`. All internal data are views of the data of the original. .. py:property:: T :type: Self Return an instance with the data transposed. Parameters are as for :attr:`~numpy.ndarray.T`. All internal data are views of the data of the original. .. py:method:: swapaxes(*args, **kwargs) Return an instance with the given axes interchanged. Parameters are as for :meth:`~numpy.ndarray.swapaxes`: ``axis1, axis2``. All internal data are views of the data of the original. .. py:method:: diagonal(*args, **kwargs) Return an instance with the specified diagonals. Parameters are as for :meth:`~numpy.ndarray.diagonal`. All internal data are views of the data of the original. .. py:method:: squeeze(*args, **kwargs) Return an instance with single-dimensional shape entries removed. Parameters are as for :meth:`~numpy.ndarray.squeeze`. All internal data are views of the data of the original. .. py:method:: take(indices, axis=None, out=None, mode='raise') Return a new instance formed from the elements at the given indices. Parameters are as for :meth:`~numpy.ndarray.take`, except that, obviously, no output array can be given. .. py:class:: UranusFixed(*args, copy=True, representation_type=None, differential_type=None, **kwargs) Bases: :py:obj:`_PlanetaryFixed` non-inertial, body-fixed reference frame: Uranus .. py:attribute:: body .. py:attribute:: equatorial .. py:attribute:: obstime .. py:method:: to_equatorial(fixed_coo, equatorial_frame) :staticmethod: convert coordinates of a fixed coordinate system to an equatorial one .. py:method:: from_equatorial(equatorial_coo, fixed_frame) :staticmethod: convert coordinates of an equatorial coordinate system to a fixed one .. py:method:: rot_elements_at_epoch(epoch=J2000) :classmethod: Provides rotational elements at epoch. Provides north pole of body and angle to prime meridian. :param epoch: Epoch, default to J2000. :type epoch: ~astropy.time.Time, optional :returns: **ra, dec, W** -- Right ascension and declination of north pole, and angle of the prime meridian. :rtype: tuple (~astropy.units.Quantity) .. py:attribute:: frame_specific_representation_info .. py:attribute:: default_representation .. py:attribute:: default_differential .. py:attribute:: frame_attributes .. py:attribute:: info .. py:method:: __init_subclass__(**kwargs) :classmethod: .. py:method:: cache() Cache for this frame, a dict. It stores anything that should be computed from the coordinate data (*not* from the frame attributes). This can be used in functions to store anything that might be expensive to compute but might be reused by some other function. E.g.:: if 'user_data' in myframe.cache: data = myframe.cache['user_data'] else: myframe.cache['user_data'] = data = expensive_func(myframe.lat) If in-place modifications are made to the frame data, the cache should be cleared:: myframe.cache.clear() .. py:property:: data The coordinate data for this object. If this frame has no data, a `ValueError` will be raised. Use `has_data` to check if data is present on this frame object. .. py:property:: has_data True if this frame has `data`, False otherwise. .. py:property:: shape The shape of the underlying data. .. py:method:: __bool__() Any instance should evaluate to True, except when it is empty. .. py:property:: size The size of the object, as calculated from its shape. .. py:property:: masked Whether the underlying data is masked. :raises ValueError: If the frame has no associated data. .. py:method:: get_mask(*attrs) Get the mask associated with these coordinates. :param \*attrs: Attributes from which to get the masks to combine. Items can be dotted, like ``"data.lon", "data.lat"``. By default, get the combined mask of all components (including from differentials), ignoring possible masks of attributes. :type \*attrs: str :returns: **mask** -- The combined, read-only mask. If the instance is not masked, it is an array of `False` with the correct shape. :rtype: ~numpy.ndarray of bool :raises ValueError: If the coordinate frame has no associated data. .. py:attribute:: mask The mask. .. py:method:: get_frame_attr_defaults() :classmethod: Return a dict with the defaults for each frame attribute. .. py:method:: get_representation_cls(which='base') The class used for part of this frame's data. :param which: The class of which part to return. 'base' means the class used to represent the coordinates; 's' the first derivative to time, i.e., the class representing the proper motion and/or radial velocity. If `None`, return a dict with both. :type which: ('base', 's', `None`) :returns: **representation** :rtype: `~astropy.coordinates.BaseRepresentation` or `~astropy.coordinates.BaseDifferential`. .. py:method:: set_representation_cls(base=None, s='base') Set representation and/or differential class for this frame's data. :param base: The name or subclass to use to represent the coordinate data. :type base: str, `~astropy.coordinates.BaseRepresentation` subclass, optional :param s: The differential subclass to use to represent any velocities, such as proper motion and radial velocity. If equal to 'base', which is the default, it will be inferred from the representation. If `None`, the representation will drop any differentials. :type s: `~astropy.coordinates.BaseDifferential` subclass, optional .. py:attribute:: representation_type .. py:property:: differential_type The differential used for this frame's data. This will be a subclass from `~astropy.coordinates.BaseDifferential`. For simultaneous setting of representation and differentials, see the ``set_representation_cls`` method. .. py:method:: representation_info() A dictionary with the information of what attribute names for this frame apply to particular representations. .. py:method:: get_representation_component_names(which='base') .. py:method:: get_representation_component_units(which='base') .. py:attribute:: representation_component_names .. py:attribute:: representation_component_units .. py:method:: replicate(copy=False, **kwargs) Return a replica of the frame, optionally with new frame attributes. The replica is a new frame object that has the same data as this frame object and with frame attributes overridden if they are provided as extra keyword arguments to this method. If ``copy`` is set to `True` then a copy of the internal arrays will be made. Otherwise the replica will use a reference to the original arrays when possible to save memory. The internal arrays are normally not changeable by the user so in most cases it should not be necessary to set ``copy`` to `True`. :param copy: If True, the resulting object is a copy of the data. When False, references are used where possible. This rule also applies to the frame attributes. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: replicate_without_data(copy=False, **kwargs) Return a replica without data, optionally with new frame attributes. The replica is a new frame object without data but with the same frame attributes as this object, except where overridden by extra keyword arguments to this method. The ``copy`` keyword determines if the frame attributes are truly copied vs being references (which saves memory for cases where frame attributes are large). This method is essentially the converse of `realize_frame`. :param copy: If True, the resulting object has copies of the frame attributes. When False, references are used where possible. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but without data and possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: realize_frame(data, **kwargs) Generates a new frame with new data from another frame (which may or may not have data). Roughly speaking, the converse of `replicate_without_data`. :param data: The representation to use as the data for the new frame. :type data: `~astropy.coordinates.BaseRepresentation` :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. In particular, `representation_type` can be specified. :returns: **frameobj** -- A new object in *this* frame, with the same frame attributes as this one, but with the ``data`` as the coordinate data. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: represent_as(base, s='base', in_frame_units=False) Generate and return a new representation of this frame's `data` as a Representation object. Note: In order to make an in-place change of the representation of a Frame or SkyCoord object, set the ``representation`` attribute of that object to the desired new representation, or use the ``set_representation_cls`` method to also set the differential. :param base: The type of representation to generate. Must be a *class* (not an instance), or the string name of the representation class. :type base: subclass of BaseRepresentation or string :param s: Class in which any velocities should be represented. Must be a *class* (not an instance), or the string name of the differential class. If equal to 'base' (default), inferred from the base class. If `None`, all velocity information is dropped. :type s: subclass of `~astropy.coordinates.BaseDifferential`, str, optional :param in_frame_units: Force the representation units to match the specified units particular to this frame :type in_frame_units: bool, keyword-only :returns: **newrep** -- A new representation object of this frame's `data`. :rtype: BaseRepresentation-derived object :raises AttributeError: If this object had no `data` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import SkyCoord, CartesianRepresentation >>> coord = SkyCoord(0*u.deg, 0*u.deg) >>> coord.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP >>> coord.representation_type = CartesianRepresentation >>> coord # doctest: +FLOAT_CMP .. py:method:: transform_to(new_frame) Transform this object's coordinate data to a new frame. :param new_frame: The frame to transform this coordinate frame into. :type new_frame: coordinate-like :returns: **transframe** -- A new object with the coordinate data represented in the ``newframe`` system. :rtype: coordinate-like :raises ValueError: If there is no possible transformation route. .. py:method:: is_transformable_to(new_frame) Determines if this coordinate frame can be transformed to another given frame. :param new_frame: The proposed frame to transform into. :type new_frame: `~astropy.coordinates.BaseCoordinateFrame` subclass or instance :returns: **transformable** -- `True` if this can be transformed to ``new_frame``, `False` if not, or the string 'same' if ``new_frame`` is the same system as this object but no transformation is defined. :rtype: bool or str .. rubric:: Notes A return value of 'same' means the transformation will work, but it will just give back a copy of this object. The intended usage is:: if coord.is_transformable_to(some_unknown_frame): coord2 = coord.transform_to(some_unknown_frame) This will work even if ``some_unknown_frame`` turns out to be the same frame class as ``coord``. This is intended for cases where the frame is the same regardless of the frame attributes (e.g. ICRS), but be aware that it *might* also indicate that someone forgot to define the transformation between two objects of the same frame class but with different attributes. .. py:method:: is_frame_attr_default(attrnm) Determine whether or not a frame attribute has its value because it's the default value, or because this frame was created with that value explicitly requested. :param attrnm: The name of the attribute to check. :type attrnm: str :returns: **isdefault** -- True if the attribute ``attrnm`` has its value by default, False if it was specified at creation of this frame. :rtype: bool .. py:method:: is_equivalent_frame(other) Checks if this object is the same frame as the ``other`` object. To be the same frame, two objects must be the same frame class and have the same frame attributes. Note that it does *not* matter what, if any, data either object has. :param other: the other frame to check :type other: :class:`~astropy.coordinates.BaseCoordinateFrame` :returns: **isequiv** -- True if the frames are the same, False if not. :rtype: bool :raises TypeError: If ``other`` isn't a `~astropy.coordinates.BaseCoordinateFrame` or subclass. .. py:method:: __repr__() .. py:method:: __setitem__(item, value) .. py:method:: insert(obj, values, axis=0) .. py:method:: __dir__() Override the builtin `dir` behavior to include representation names. TODO: dynamic representation transforms (i.e. include cylindrical et al.). .. py:method:: __getattr__(attr) Allow access to attributes on the representation and differential as found via ``self.get_representation_component_names``. TODO: We should handle dynamic representation transforms here (e.g., `.cylindrical`) instead of defining properties as below. .. py:method:: __setattr__(attr, value) .. py:method:: __eq__(value) Equality operator for frame. This implements strict equality and requires that the frames are equivalent and that the representation data are exactly equal. .. py:method:: __ne__(value) .. py:method:: position_angle(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord]) -> astropy.coordinates.angles.Angle Compute the on-sky position angle to another coordinate. :param other: The other coordinate to compute the position angle to. It is treated as the "head" of the vector of the position angle. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: The (positive) position angle of the vector pointing from ``self`` to ``other``, measured East from North. If either ``self`` or ``other`` contain arrays, this will be an array following the appropriate `numpy` broadcasting rules. :rtype: `~astropy.coordinates.Angle` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import ICRS, SkyCoord >>> c1 = SkyCoord(0*u.deg, 0*u.deg) >>> c2 = ICRS(1*u.deg, 0*u.deg) >>> c1.position_angle(c2).to(u.deg) >>> c2.position_angle(c1).to(u.deg) >>> c3 = SkyCoord(1*u.deg, 1*u.deg) >>> c1.position_angle(c3).to(u.deg) # doctest: +FLOAT_CMP .. py:method:: separation(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord], *, origin_mismatch: Literal['ignore', 'warn', 'error'] = 'warn') -> astropy.coordinates.angles.Angle Computes on-sky separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate to get the separation to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :param origin_mismatch: If the ``other`` coordinates are in a different frame then they will have to be transformed, and if the transformation is not a pure rotation then ``self.separation(other)`` can be different from ``other.separation(self)``. With ``origin_mismatch="warn"`` (default) the transformation is always performed, but a warning is emitted if it is not a pure rotation. If ``origin_mismatch="ignore"`` then the required transformation is always performed without warnings. If ``origin_mismatch="error"`` then only transformations that are pure rotations are allowed. :type origin_mismatch: {"warn", "ignore", "error"}, keyword-only :returns: **sep** -- The on-sky separation between this and the ``other`` coordinate. :rtype: `~astropy.coordinates.Angle` .. rubric:: Notes The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [1]_. .. [1] https://en.wikipedia.org/wiki/Great-circle_distance .. py:method:: separation_3d(other) Computes three dimensional separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate system to get the distance to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: **sep** -- The real-space distance between these two coordinates. :rtype: `~astropy.coordinates.Distance` :raises ValueError: If this or the other coordinate do not have distances. .. py:property:: cartesian Shorthand for a cartesian representation of the coordinates in this object. .. py:property:: cylindrical Shorthand for a cylindrical representation of the coordinates in this object. .. py:property:: spherical Shorthand for a spherical representation of the coordinates in this object. .. py:property:: sphericalcoslat Shorthand for a spherical representation of the positional data and a `~astropy.coordinates.SphericalCosLatDifferential` for the velocity data in this object. .. py:property:: velocity Shorthand for retrieving the Cartesian space-motion as a `~astropy.coordinates.CartesianDifferential` object. This is equivalent to calling ``self.cartesian.differentials['s']``. .. py:property:: proper_motion Shorthand for the two-dimensional proper motion as a `~astropy.units.Quantity` object with angular velocity units. In the returned `~astropy.units.Quantity`, ``axis=0`` is the longitude/latitude dimension so that ``.proper_motion[0]`` is the longitudinal proper motion and ``.proper_motion[1]`` is latitudinal. The longitudinal proper motion already includes the cos(latitude) term. .. py:property:: radial_velocity Shorthand for the radial or line-of-sight velocity as a `~astropy.units.Quantity` object. .. py:method:: to_table() -> astropy.table.QTable Convert this |BaseFrame| to a |QTable|. Any attributes that have the same length as the |BaseFrame| will be converted to columns of the |QTable|. All other attributes will be recorded as metadata. :returns: A |QTable| containing the data of this |BaseFrame|. :rtype: `~astropy.table.QTable` .. rubric:: Examples >>> from astropy.coordinates import ICRS >>> coord = ICRS(ra=[40, 70]*u.deg, dec=[0, -20]*u.deg) >>> t = coord.to_table() >>> t ra dec deg deg float64 float64 ------- ------- 40.0 0.0 70.0 -20.0 >>> t.meta {'representation_type': 'spherical'} .. py:property:: unmasked Get an instance without the mask. Note that while one gets a new instance, the underlying data will be shared. .. seealso:: :py:obj:`filled` get a copy of the underlying data, with masked values filled in. .. py:method:: filled(fill_value) Get a copy of the underlying data, with masked values filled in. :param fill_value: Value to replace masked values with. :type fill_value: object :returns: **filled** -- Copy of ``self`` with masked items replaced by ``fill_value``. :rtype: instance .. seealso:: :py:obj:`unmasked` get an instance without the mask. .. py:property:: ndim :type: int The number of dimensions of the instance and underlying arrays. .. py:property:: isscalar :type: bool .. py:method:: __len__() -> int .. py:method:: __getitem__(item) .. py:method:: __iter__() .. py:method:: __array_function__(function, types, args, kwargs) Wrap numpy functions that make sense. .. py:method:: copy(*args, **kwargs) Return an instance containing copies of the internal data. Parameters are as for :meth:`~numpy.ndarray.copy`. .. py:method:: reshape(*args, **kwargs) Returns an instance containing the same data with a new shape. Parameters are as for :meth:`~numpy.ndarray.reshape`. Note that it is not always possible to change the shape of an array without copying the data (see :func:`~numpy.reshape` documentation). If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute (note: this may not be implemented for all classes using ``NDArrayShapeMethods``). .. py:method:: ravel(*args, **kwargs) Return an instance with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.ravel`. Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape ``(-1,)`` to the shape attribute. .. py:method:: flatten(*args, **kwargs) Return a copy with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.flatten`. .. py:method:: transpose(*args, **kwargs) Return an instance with the data transposed. Parameters are as for :meth:`~numpy.ndarray.transpose`. All internal data are views of the data of the original. .. py:property:: T :type: Self Return an instance with the data transposed. Parameters are as for :attr:`~numpy.ndarray.T`. All internal data are views of the data of the original. .. py:method:: swapaxes(*args, **kwargs) Return an instance with the given axes interchanged. Parameters are as for :meth:`~numpy.ndarray.swapaxes`: ``axis1, axis2``. All internal data are views of the data of the original. .. py:method:: diagonal(*args, **kwargs) Return an instance with the specified diagonals. Parameters are as for :meth:`~numpy.ndarray.diagonal`. All internal data are views of the data of the original. .. py:method:: squeeze(*args, **kwargs) Return an instance with single-dimensional shape entries removed. Parameters are as for :meth:`~numpy.ndarray.squeeze`. All internal data are views of the data of the original. .. py:method:: take(indices, axis=None, out=None, mode='raise') Return a new instance formed from the elements at the given indices. Parameters are as for :meth:`~numpy.ndarray.take`, except that, obviously, no output array can be given. .. py:class:: NeptuneFixed(*args, copy=True, representation_type=None, differential_type=None, **kwargs) Bases: :py:obj:`_PlanetaryFixed` non-inertial, body-fixed reference frame: Neptune .. py:attribute:: body .. py:attribute:: equatorial .. py:attribute:: obstime .. py:method:: to_equatorial(fixed_coo, equatorial_frame) :staticmethod: convert coordinates of a fixed coordinate system to an equatorial one .. py:method:: from_equatorial(equatorial_coo, fixed_frame) :staticmethod: convert coordinates of an equatorial coordinate system to a fixed one .. py:method:: rot_elements_at_epoch(epoch=J2000) :classmethod: Provides rotational elements at epoch. Provides north pole of body and angle to prime meridian. :param epoch: Epoch, default to J2000. :type epoch: ~astropy.time.Time, optional :returns: **ra, dec, W** -- Right ascension and declination of north pole, and angle of the prime meridian. :rtype: tuple (~astropy.units.Quantity) .. py:attribute:: frame_specific_representation_info .. py:attribute:: default_representation .. py:attribute:: default_differential .. py:attribute:: frame_attributes .. py:attribute:: info .. py:method:: __init_subclass__(**kwargs) :classmethod: .. py:method:: cache() Cache for this frame, a dict. It stores anything that should be computed from the coordinate data (*not* from the frame attributes). This can be used in functions to store anything that might be expensive to compute but might be reused by some other function. E.g.:: if 'user_data' in myframe.cache: data = myframe.cache['user_data'] else: myframe.cache['user_data'] = data = expensive_func(myframe.lat) If in-place modifications are made to the frame data, the cache should be cleared:: myframe.cache.clear() .. py:property:: data The coordinate data for this object. If this frame has no data, a `ValueError` will be raised. Use `has_data` to check if data is present on this frame object. .. py:property:: has_data True if this frame has `data`, False otherwise. .. py:property:: shape The shape of the underlying data. .. py:method:: __bool__() Any instance should evaluate to True, except when it is empty. .. py:property:: size The size of the object, as calculated from its shape. .. py:property:: masked Whether the underlying data is masked. :raises ValueError: If the frame has no associated data. .. py:method:: get_mask(*attrs) Get the mask associated with these coordinates. :param \*attrs: Attributes from which to get the masks to combine. Items can be dotted, like ``"data.lon", "data.lat"``. By default, get the combined mask of all components (including from differentials), ignoring possible masks of attributes. :type \*attrs: str :returns: **mask** -- The combined, read-only mask. If the instance is not masked, it is an array of `False` with the correct shape. :rtype: ~numpy.ndarray of bool :raises ValueError: If the coordinate frame has no associated data. .. py:attribute:: mask The mask. .. py:method:: get_frame_attr_defaults() :classmethod: Return a dict with the defaults for each frame attribute. .. py:method:: get_representation_cls(which='base') The class used for part of this frame's data. :param which: The class of which part to return. 'base' means the class used to represent the coordinates; 's' the first derivative to time, i.e., the class representing the proper motion and/or radial velocity. If `None`, return a dict with both. :type which: ('base', 's', `None`) :returns: **representation** :rtype: `~astropy.coordinates.BaseRepresentation` or `~astropy.coordinates.BaseDifferential`. .. py:method:: set_representation_cls(base=None, s='base') Set representation and/or differential class for this frame's data. :param base: The name or subclass to use to represent the coordinate data. :type base: str, `~astropy.coordinates.BaseRepresentation` subclass, optional :param s: The differential subclass to use to represent any velocities, such as proper motion and radial velocity. If equal to 'base', which is the default, it will be inferred from the representation. If `None`, the representation will drop any differentials. :type s: `~astropy.coordinates.BaseDifferential` subclass, optional .. py:attribute:: representation_type .. py:property:: differential_type The differential used for this frame's data. This will be a subclass from `~astropy.coordinates.BaseDifferential`. For simultaneous setting of representation and differentials, see the ``set_representation_cls`` method. .. py:method:: representation_info() A dictionary with the information of what attribute names for this frame apply to particular representations. .. py:method:: get_representation_component_names(which='base') .. py:method:: get_representation_component_units(which='base') .. py:attribute:: representation_component_names .. py:attribute:: representation_component_units .. py:method:: replicate(copy=False, **kwargs) Return a replica of the frame, optionally with new frame attributes. The replica is a new frame object that has the same data as this frame object and with frame attributes overridden if they are provided as extra keyword arguments to this method. If ``copy`` is set to `True` then a copy of the internal arrays will be made. Otherwise the replica will use a reference to the original arrays when possible to save memory. The internal arrays are normally not changeable by the user so in most cases it should not be necessary to set ``copy`` to `True`. :param copy: If True, the resulting object is a copy of the data. When False, references are used where possible. This rule also applies to the frame attributes. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: replicate_without_data(copy=False, **kwargs) Return a replica without data, optionally with new frame attributes. The replica is a new frame object without data but with the same frame attributes as this object, except where overridden by extra keyword arguments to this method. The ``copy`` keyword determines if the frame attributes are truly copied vs being references (which saves memory for cases where frame attributes are large). This method is essentially the converse of `realize_frame`. :param copy: If True, the resulting object has copies of the frame attributes. When False, references are used where possible. :type copy: bool, optional :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. :returns: **frameobj** -- Replica of this object, but without data and possibly with new frame attributes. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: realize_frame(data, **kwargs) Generates a new frame with new data from another frame (which may or may not have data). Roughly speaking, the converse of `replicate_without_data`. :param data: The representation to use as the data for the new frame. :type data: `~astropy.coordinates.BaseRepresentation` :param \*\*kwargs: Any additional keywords are treated as frame attributes to be set on the new frame object. In particular, `representation_type` can be specified. :returns: **frameobj** -- A new object in *this* frame, with the same frame attributes as this one, but with the ``data`` as the coordinate data. :rtype: `~astropy.coordinates.BaseCoordinateFrame` subclass instance .. py:method:: represent_as(base, s='base', in_frame_units=False) Generate and return a new representation of this frame's `data` as a Representation object. Note: In order to make an in-place change of the representation of a Frame or SkyCoord object, set the ``representation`` attribute of that object to the desired new representation, or use the ``set_representation_cls`` method to also set the differential. :param base: The type of representation to generate. Must be a *class* (not an instance), or the string name of the representation class. :type base: subclass of BaseRepresentation or string :param s: Class in which any velocities should be represented. Must be a *class* (not an instance), or the string name of the differential class. If equal to 'base' (default), inferred from the base class. If `None`, all velocity information is dropped. :type s: subclass of `~astropy.coordinates.BaseDifferential`, str, optional :param in_frame_units: Force the representation units to match the specified units particular to this frame :type in_frame_units: bool, keyword-only :returns: **newrep** -- A new representation object of this frame's `data`. :rtype: BaseRepresentation-derived object :raises AttributeError: If this object had no `data` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import SkyCoord, CartesianRepresentation >>> coord = SkyCoord(0*u.deg, 0*u.deg) >>> coord.represent_as(CartesianRepresentation) # doctest: +FLOAT_CMP >>> coord.representation_type = CartesianRepresentation >>> coord # doctest: +FLOAT_CMP .. py:method:: transform_to(new_frame) Transform this object's coordinate data to a new frame. :param new_frame: The frame to transform this coordinate frame into. :type new_frame: coordinate-like :returns: **transframe** -- A new object with the coordinate data represented in the ``newframe`` system. :rtype: coordinate-like :raises ValueError: If there is no possible transformation route. .. py:method:: is_transformable_to(new_frame) Determines if this coordinate frame can be transformed to another given frame. :param new_frame: The proposed frame to transform into. :type new_frame: `~astropy.coordinates.BaseCoordinateFrame` subclass or instance :returns: **transformable** -- `True` if this can be transformed to ``new_frame``, `False` if not, or the string 'same' if ``new_frame`` is the same system as this object but no transformation is defined. :rtype: bool or str .. rubric:: Notes A return value of 'same' means the transformation will work, but it will just give back a copy of this object. The intended usage is:: if coord.is_transformable_to(some_unknown_frame): coord2 = coord.transform_to(some_unknown_frame) This will work even if ``some_unknown_frame`` turns out to be the same frame class as ``coord``. This is intended for cases where the frame is the same regardless of the frame attributes (e.g. ICRS), but be aware that it *might* also indicate that someone forgot to define the transformation between two objects of the same frame class but with different attributes. .. py:method:: is_frame_attr_default(attrnm) Determine whether or not a frame attribute has its value because it's the default value, or because this frame was created with that value explicitly requested. :param attrnm: The name of the attribute to check. :type attrnm: str :returns: **isdefault** -- True if the attribute ``attrnm`` has its value by default, False if it was specified at creation of this frame. :rtype: bool .. py:method:: is_equivalent_frame(other) Checks if this object is the same frame as the ``other`` object. To be the same frame, two objects must be the same frame class and have the same frame attributes. Note that it does *not* matter what, if any, data either object has. :param other: the other frame to check :type other: :class:`~astropy.coordinates.BaseCoordinateFrame` :returns: **isequiv** -- True if the frames are the same, False if not. :rtype: bool :raises TypeError: If ``other`` isn't a `~astropy.coordinates.BaseCoordinateFrame` or subclass. .. py:method:: __repr__() .. py:method:: __setitem__(item, value) .. py:method:: insert(obj, values, axis=0) .. py:method:: __dir__() Override the builtin `dir` behavior to include representation names. TODO: dynamic representation transforms (i.e. include cylindrical et al.). .. py:method:: __getattr__(attr) Allow access to attributes on the representation and differential as found via ``self.get_representation_component_names``. TODO: We should handle dynamic representation transforms here (e.g., `.cylindrical`) instead of defining properties as below. .. py:method:: __setattr__(attr, value) .. py:method:: __eq__(value) Equality operator for frame. This implements strict equality and requires that the frames are equivalent and that the representation data are exactly equal. .. py:method:: __ne__(value) .. py:method:: position_angle(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord]) -> astropy.coordinates.angles.Angle Compute the on-sky position angle to another coordinate. :param other: The other coordinate to compute the position angle to. It is treated as the "head" of the vector of the position angle. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: The (positive) position angle of the vector pointing from ``self`` to ``other``, measured East from North. If either ``self`` or ``other`` contain arrays, this will be an array following the appropriate `numpy` broadcasting rules. :rtype: `~astropy.coordinates.Angle` .. rubric:: Examples >>> from astropy import units as u >>> from astropy.coordinates import ICRS, SkyCoord >>> c1 = SkyCoord(0*u.deg, 0*u.deg) >>> c2 = ICRS(1*u.deg, 0*u.deg) >>> c1.position_angle(c2).to(u.deg) >>> c2.position_angle(c1).to(u.deg) >>> c3 = SkyCoord(1*u.deg, 1*u.deg) >>> c1.position_angle(c3).to(u.deg) # doctest: +FLOAT_CMP .. py:method:: separation(other: Union[BaseCoordinateFrame, astropy.coordinates.SkyCoord], *, origin_mismatch: Literal['ignore', 'warn', 'error'] = 'warn') -> astropy.coordinates.angles.Angle Computes on-sky separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate to get the separation to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :param origin_mismatch: If the ``other`` coordinates are in a different frame then they will have to be transformed, and if the transformation is not a pure rotation then ``self.separation(other)`` can be different from ``other.separation(self)``. With ``origin_mismatch="warn"`` (default) the transformation is always performed, but a warning is emitted if it is not a pure rotation. If ``origin_mismatch="ignore"`` then the required transformation is always performed without warnings. If ``origin_mismatch="error"`` then only transformations that are pure rotations are allowed. :type origin_mismatch: {"warn", "ignore", "error"}, keyword-only :returns: **sep** -- The on-sky separation between this and the ``other`` coordinate. :rtype: `~astropy.coordinates.Angle` .. rubric:: Notes The separation is calculated using the Vincenty formula, which is stable at all locations, including poles and antipodes [1]_. .. [1] https://en.wikipedia.org/wiki/Great-circle_distance .. py:method:: separation_3d(other) Computes three dimensional separation between this coordinate and another. For more on how to use this (and related) functionality, see the examples in :ref:`astropy-coordinates-separations-matching`. :param other: The coordinate system to get the distance to. :type other: `~astropy.coordinates.BaseCoordinateFrame` or `~astropy.coordinates.SkyCoord` :returns: **sep** -- The real-space distance between these two coordinates. :rtype: `~astropy.coordinates.Distance` :raises ValueError: If this or the other coordinate do not have distances. .. py:property:: cartesian Shorthand for a cartesian representation of the coordinates in this object. .. py:property:: cylindrical Shorthand for a cylindrical representation of the coordinates in this object. .. py:property:: spherical Shorthand for a spherical representation of the coordinates in this object. .. py:property:: sphericalcoslat Shorthand for a spherical representation of the positional data and a `~astropy.coordinates.SphericalCosLatDifferential` for the velocity data in this object. .. py:property:: velocity Shorthand for retrieving the Cartesian space-motion as a `~astropy.coordinates.CartesianDifferential` object. This is equivalent to calling ``self.cartesian.differentials['s']``. .. py:property:: proper_motion Shorthand for the two-dimensional proper motion as a `~astropy.units.Quantity` object with angular velocity units. In the returned `~astropy.units.Quantity`, ``axis=0`` is the longitude/latitude dimension so that ``.proper_motion[0]`` is the longitudinal proper motion and ``.proper_motion[1]`` is latitudinal. The longitudinal proper motion already includes the cos(latitude) term. .. py:property:: radial_velocity Shorthand for the radial or line-of-sight velocity as a `~astropy.units.Quantity` object. .. py:method:: to_table() -> astropy.table.QTable Convert this |BaseFrame| to a |QTable|. Any attributes that have the same length as the |BaseFrame| will be converted to columns of the |QTable|. All other attributes will be recorded as metadata. :returns: A |QTable| containing the data of this |BaseFrame|. :rtype: `~astropy.table.QTable` .. rubric:: Examples >>> from astropy.coordinates import ICRS >>> coord = ICRS(ra=[40, 70]*u.deg, dec=[0, -20]*u.deg) >>> t = coord.to_table() >>> t ra dec deg deg float64 float64 ------- ------- 40.0 0.0 70.0 -20.0 >>> t.meta {'representation_type': 'spherical'} .. py:property:: unmasked Get an instance without the mask. Note that while one gets a new instance, the underlying data will be shared. .. seealso:: :py:obj:`filled` get a copy of the underlying data, with masked values filled in. .. py:method:: filled(fill_value) Get a copy of the underlying data, with masked values filled in. :param fill_value: Value to replace masked values with. :type fill_value: object :returns: **filled** -- Copy of ``self`` with masked items replaced by ``fill_value``. :rtype: instance .. seealso:: :py:obj:`unmasked` get an instance without the mask. .. py:property:: ndim :type: int The number of dimensions of the instance and underlying arrays. .. py:property:: isscalar :type: bool .. py:method:: __len__() -> int .. py:method:: __getitem__(item) .. py:method:: __iter__() .. py:method:: __array_function__(function, types, args, kwargs) Wrap numpy functions that make sense. .. py:method:: copy(*args, **kwargs) Return an instance containing copies of the internal data. Parameters are as for :meth:`~numpy.ndarray.copy`. .. py:method:: reshape(*args, **kwargs) Returns an instance containing the same data with a new shape. Parameters are as for :meth:`~numpy.ndarray.reshape`. Note that it is not always possible to change the shape of an array without copying the data (see :func:`~numpy.reshape` documentation). If you want an error to be raise if the data is copied, you should assign the new shape to the shape attribute (note: this may not be implemented for all classes using ``NDArrayShapeMethods``). .. py:method:: ravel(*args, **kwargs) Return an instance with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.ravel`. Note that it is not always possible to unravel an array without copying the data. If you want an error to be raise if the data is copied, you should should assign shape ``(-1,)`` to the shape attribute. .. py:method:: flatten(*args, **kwargs) Return a copy with the array collapsed into one dimension. Parameters are as for :meth:`~numpy.ndarray.flatten`. .. py:method:: transpose(*args, **kwargs) Return an instance with the data transposed. Parameters are as for :meth:`~numpy.ndarray.transpose`. All internal data are views of the data of the original. .. py:property:: T :type: Self Return an instance with the data transposed. Parameters are as for :attr:`~numpy.ndarray.T`. All internal data are views of the data of the original. .. py:method:: swapaxes(*args, **kwargs) Return an instance with the given axes interchanged. Parameters are as for :meth:`~numpy.ndarray.swapaxes`: ``axis1, axis2``. All internal data are views of the data of the original. .. py:method:: diagonal(*args, **kwargs) Return an instance with the specified diagonals. Parameters are as for :meth:`~numpy.ndarray.diagonal`. All internal data are views of the data of the original. .. py:method:: squeeze(*args, **kwargs) Return an instance with single-dimensional shape entries removed. Parameters are as for :meth:`~numpy.ndarray.squeeze`. All internal data are views of the data of the original. .. py:method:: take(indices, axis=None, out=None, mode='raise') Return a new instance formed from the elements at the given indices. Parameters are as for :meth:`~numpy.ndarray.take`, except that, obviously, no output array can be given.