Skip to main content
`Ctrl`+`K`

# TransformGraph

class astropy.coordinates.TransformGraph

  Bases: `object`

  A graph representing the paths between coordinate frames.

  Attributes Summary

  `frame_attributes` | A `dict` of all the attributes of all frame classes in this TransformGraph.
  `frame_component_names` | A `set` of all component names every defined within any frame class in this TransformGraph.
  `frame_set` | A `set` of all the frame classes present in this TransformGraph.

  Methods Summary

  `add_transform`(fromsys, tosys, transform) | Add a new coordinate transformation to the graph.
  `find_shortest_path`(fromsys, tosys) | Computes the shortest distance along the transform graph from one system to another.
  `get_names`() | Returns all available transform names.
  `get_transform`(fromsys, tosys) | Generates and returns the CompositeTransform for a transformation between two coordinate systems.
  `impose_finite_difference_dt`(dt) | Context manager to impose a finite-difference time step on all applicable transformations.
  `invalidate_cache`() | Invalidates the cache that stores optimizations for traversing the transform graph.
  `lookup_name`(name) | Tries to locate the coordinate class with the provided alias.
  `remove_transform`(fromsys, tosys, transform) | Removes a coordinate transform from the graph.
  `to_dot_graph`([priorities, addnodes, savefn, ...]) | Converts this transform graph to the graphviz DOT format.
  `to_networkx_graph`() | Converts this transform graph into a networkx graph.
  `transform`(transcls, fromsys, tosys[, priority]) | A function decorator for defining transformations.

  Attributes Documentation

  frame_attributes

    A `dict` of all the attributes of all frame classes in this TransformGraph.

  frame_component_names

    A `set` of all component names every defined within any frame class in this TransformGraph.

  frame_set

    A `set` of all the frame classes present in this TransformGraph.

  Methods Documentation

  add_transform(fromsys, tosys, transform)

    Add a new coordinate transformation to the graph.

    Parameters:
      fromsys class

        The coordinate frame class to start from.

      tosys class

        The coordinate frame class to transform into.

      transform `CoordinateTransform`

        The transformation object. Typically a `CoordinateTransform` object, although it may be some other callable that is called with the same signature.

    Raises:
      `TypeError`

        If `fromsys` or `tosys` are not classes or `transform` is not callable.

  find_shortest_path(fromsys, tosys)

    Computes the shortest distance along the transform graph from one system to another.

    Parameters:
      fromsys class

        The coordinate frame class to start from.

      tosys class

        The coordinate frame class to transform into.

    Returns:
      path `python:list` of class or `python:None`

        The path from `fromsys` to `tosys` as an in-order sequence of classes. This list includes both `fromsys` and `tosys`. Is `None` if there is no possible path.

      distance `python:float` or `python:int`

        The total distance/priority from `fromsys` to `tosys`. If priorities are not set this is the number of transforms needed. Is `inf` if there is no possible path.

  get_names()

    Returns all available transform names. They will all be valid arguments to `lookup_name`.

    Returns:
      nms `python:list`

        The aliases for coordinate systems.

  get_transform(fromsys, tosys)

    Generates and returns the CompositeTransform for a transformation between two coordinate systems.

    Parameters:
      fromsys class

        The coordinate frame class to start from.

      tosys class

        The coordinate frame class to transform into.

    Returns:
      trans `CompositeTransform` or `python:None`

        If there is a path from `fromsys` to `tosys`, this is a transform object for that path. If no path could be found, this is `None`.

    Notes

    A `CompositeTransform` is always returned, because `CompositeTransform` is slightly more adaptable in the way it can be called than other transform classes. Specifically, it takes care of intermediate steps of transformations in a way that is consistent with 1-hop transformations.

  impose_finite_difference_dt(dt)

    Context manager to impose a finite-difference time step on all applicable transformations.

    For each transformation in this transformation graph that has the attribute `finite_difference_dt`, that attribute is set to the provided value. The only standard transformation with this attribute is `FunctionTransformWithFiniteDifference`.

    Parameters:
      dt `Quantity` [:ref: ‘time’] or `python:callable()`

        If a quantity, this is the size of the differential used to do the finite difference. If a callable, should accept `(fromcoord, toframe)` and return the `dt` value.

  invalidate_cache()

    Invalidates the cache that stores optimizations for traversing the transform graph. This is called automatically when transforms are added or removed, but will need to be called manually if weights on transforms are modified inplace.

  lookup_name(name)

    Tries to locate the coordinate class with the provided alias.

    Parameters:
      name `python:str`

        The alias to look up.

    Returns:
      `BaseCoordinateFrame` subclass

        The coordinate class corresponding to the `name` or `None` if no such class exists.

  remove_transform(fromsys, tosys, transform)

    Removes a coordinate transform from the graph.

    Parameters:
      fromsys class or `python:None`

        The coordinate frame class to start from. If `None`, `transform` will be searched for and removed (`tosys` must also be `None`).

      tosys class or `python:None`

        The coordinate frame class to transform into. If `None`, `transform` will be searched for and removed (`fromsys` must also be `None`).

      transform `python:callable()` or `python:None`

        The transformation object to be removed or `None`. If `None` and `tosys` and `fromsys` are supplied, there will be no check to ensure the correct object is removed.

  to_dot_graph(priorities=True, addnodes=[], savefn=None, savelayout='plain', saveformat=None, color_edges=True)

    Converts this transform graph to the graphviz DOT format.

    Optionally saves it (requires graphviz be installed and on your path).

    Parameters:
      priorities bool

        If `True`, show the priority values for each transform. Otherwise, the will not be included in the graph.

      addnodes python:sequence of `python:str`

        Additional coordinate systems to add (this can include systems already in the transform graph, but they will only appear once).

      savefn `python:None` or `python:str`

        The file name to save this graph to or `None` to not save to a file.

      savelayout{“plain”, “dot”, “neato”, “fdp”, “sfdp”, “circo”, “twopi”, “nop”, “nop2”, “osage”, “patchwork”}

        The graphviz program to use to layout the graph (see graphviz for details) or ‘plain’ to just save the DOT graph content. Ignored if `savefn` is `None`.

      saveformat `python:str`

        The graphviz output format. (e.g. the `-Txxx` option for the command line program - see graphviz docs for details). Ignored if `savefn` is `None`.

      color_edges bool

        Color the edges between two nodes (frames) based on the type of transform. `FunctionTransform`: red, `StaticMatrixTransform`: blue, `DynamicMatrixTransform`: green.

    Returns:
      dotgraph `python:str`

        A string with the DOT format graph.

  to_networkx_graph()

    Converts this transform graph into a networkx graph.

    Note

    You must have the networkx package installed for this to work.

    Returns:
      nxgraph `networkx.Graph`

        This `TransformGraph` as a networkx.Graph.

  transform(transcls, fromsys, tosys, priority=1, **kwargs)

    A function decorator for defining transformations.

    Note

    If decorating a static method of a class, `@staticmethod` should be added above this decorator.

    Parameters:
      transcls class

        The class of the transformation object to create.

      fromsys class

        The coordinate frame class to start from.

      tosys class

        The coordinate frame class to transform into.

      priority `python:float` or `python:int`

        The priority if this transform when finding the shortest coordinate transform path - large numbers are lower priorities.

      Additional keyword arguments are passed into the ``transcls``
      constructor.
    Returns:
      deco python:function

        A function that can be called on another function as a decorator (see example).

    Notes

    This decorator assumes the first argument of the `transcls` initializer accepts a callable, and that the second and third are `fromsys` and `tosys`. If this is not true, you should just initialize the class manually and use `add_transform` instead of this decorator.

    Examples

        graph = TransformGraph()

        class Frame1(BaseCoordinateFrame):
           ...

        class Frame2(BaseCoordinateFrame):
            ...

        @graph.transform(FunctionTransform, Frame1, Frame2)
        def f1_to_f2(f1_obj):
            ... do something with f1_obj ...
            return f2_obj