TransformGraph

class utilipy.data_utils.xfm.TransformGraph(seed_basic: bool = True)

Bases: object

Graph representing the paths between data types.

Notes

Note that the _graph key-value order is “totype”: “fromtype”. This is the opposite type as Astropy’s since this TransformGraph needs to support:

• catch-all conversions, such as converting from any sequence data to type list by applying list(data)

• sub-type conversions, where the conversion a -> b (with types A, B) works on any subtype of A (like A1(A)).

Todo

• catch-all conversions to a specific type

• multiple input option conversions to a specific type

• multiple output option conversions by choosing one with shortest path

• pre-register basic conversions like None->None, list->tuple

Data Transformation Graph.

Parameters

seed_basicbool

whether to start with a basic set of transformations

Todo

Generate documentation / colored graph like Astropy’s

Attributes Summary

type_set

A set of all data types present in this TransformGraph.

Methods Summary

add_transform(fromtype, totype, transform)	Add a new data transformation to the graph.
decorate([function, _doc_style, _doc_fmt])	Apply data transformations to function arguments.
find_shortest_path(fromtype, totype)	Compute shortest path along graph from one system to another.
function_decorator([function, _doc_style, …])	Apply data transformations to function arguments.
get_names()	Returns all available transform names.
get_transform(fromtype, totype)	Generate CompositeTransform for a datatype transformation.
invalidate_cache()	Clears all caching attributes.
lookup_name(name)	Tries to locate the class with the provided alias.
register(transcls, fromtype, totype[, priority])	A function decorator for defining a transformation.
remove_transform(fromtype, totype, transform)	Removes a data transform from the graph.
transform(transcls, fromtype, totype[, priority])	A function decorator for defining a transformation.

Attributes Documentation

type_set

A set of all data types present in this TransformGraph.

Methods Documentation

add_transform(fromtype, totype, transform)

Add a new data transformation to the graph.

Todo

• support an “Any” option in fromtype

• support adding a tuple of types as the “fromtype”

• support subtypes in “fromtype”

Parameters

fromtypeclass

The data class to start from.

totypeclass

The data class to transform into.

transformDataTransform or similar callable

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

Raises

TypeError

If fromtype or totype are not classes or transform is not callable.

decorate(function: Optional[Callable] = None, *, _doc_style: str = 'numpy', _doc_fmt: Dict[str, Any] = {}, **arguments)

Apply data transformations to function arguments.

Parameters

functionT.Callable or None, optional

the function to be decoratored if None, then returns decorator to apply.

**arguments: dict

argument information, where keyword is the argument parameter name in function. The values are either the desired output type or a 3-element tuple in the following order (outtype, (args), dict(kwargs)). The args and kwargs are passed into the transformation.

Returns

wrapperT.Callable

wrapper for function that manage input catalog tables. includes the original function in a method __wrapped__

Other Parameters

_doc_style: str or formatter, optional

function docstring style. Parameter to wraps.

_doc_fmt: dict, optional

function docstring format arguments. Parameter to wraps.

Notes

Todo

• scrape output type from function argument annotation

• support a multiple possible output types (Union[etc]), choosing the one with the shortest path

find_shortest_path(fromtype, totype)

Compute shortest path along graph from one system to another.

Parameters

fromtypeclass

The coordinate frame class to start from.

totypeclass

The coordinate frame class to transform into.

Returns

pathlist of classes or None

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

distancenumber

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

function_decorator(function: Optional[Callable] = None, *, _doc_style: str = 'numpy', _doc_fmt: Dict[str, Any] = {}, **arguments)

Apply data transformations to function arguments.

Parameters

functionT.Callable or None, optional

the function to be decoratored if None, then returns decorator to apply.

**arguments: dict

argument information, where keyword is the argument parameter name in function. The values are either the desired output type or a 3-element tuple in the following order (outtype, (args), dict(kwargs)). The args and kwargs are passed into the transformation.

Returns

wrapperT.Callable

wrapper for function that manage input catalog tables. includes the original function in a method __wrapped__

Other Parameters

_doc_style: str or formatter, optional

function docstring style. Parameter to wraps.

_doc_fmt: dict, optional

function docstring format arguments. Parameter to wraps.

Notes

Todo

• scrape output type from function argument annotation

• support a multiple possible output types (Union[etc]), choosing the one with the shortest path

get_names()

Returns all available transform names.

Returns

nmslist

The aliases for coordinate systems. They will all be valid arguments to lookup_name.

get_transform(fromtype, totype)

Generate CompositeTransform for a datatype transformation.

Parameters

fromtypeclass

The coordinate frame class to start from.

totypeclass

The coordinate frame class to transform into.

Returns

transCompositeTransform or None

If there is a path from fromtype to totype, this is a transform object for that path. If no path could be found, this is None.

Notes

This function always returns a CompositeTransform, 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.

invalidate_cache()

Clears all caching attributes.

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: str)

Tries to locate the class with the provided alias.

Parameters

namestr

The alias to look up.

Returns

datacls

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

register(transcls, fromtype, totype, priority: int = 1, **kwargs)

A function decorator for defining a transformation.

Note

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

Parameters

transclsclass

The class of the transformation object to create.

fromtypeclass

The data class to start from.

totypeclass

The data class to transform into.

prioritynumber

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

decofunction

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 fromtype and totype. If this is not true, you should just initialize the class manually and use add_transform instead of using this decorator.

Examples

graph = TransformGraph()

@graph.transform(DataTransform, list, tuple)
def list_to_tuple(data):
    return tuple(data)

remove_transform(fromtype, totype, transform)

Removes a data transform from the graph.

Todo

• support removing catch-all transformations

Parameters

fromtypeclass or None

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

totypeclass or None

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

transformcallable or None

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

transform(transcls, fromtype, totype, priority: int = 1, **kwargs)

A function decorator for defining a transformation.

Note

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

Parameters

transclsclass

The class of the transformation object to create.

fromtypeclass

The data class to start from.

totypeclass

The data class to transform into.

prioritynumber

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

decofunction

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 fromtype and totype. If this is not true, you should just initialize the class manually and use add_transform instead of using this decorator.

Examples

graph = TransformGraph()

@graph.transform(DataTransform, list, tuple)
def list_to_tuple(data):
    return tuple(data)