Coverage for python / lsst / analysis / tools / interfaces / _interfaces.py: 95%

1# This file is part of analysis_tools. 

2# 

3# Developed for the LSST Data Management System. 

4# This product includes software developed by the LSST Project 

5# (https://www.lsst.org). 

6# See the COPYRIGHT file at the top-level directory of this distribution 

7# for details of code ownership. 

8# 

9# This program is free software: you can redistribute it and/or modify 

10# it under the terms of the GNU General Public License as published by 

11# the Free Software Foundation, either version 3 of the License, or 

12# (at your option) any later version. 

13# 

14# This program is distributed in the hope that it will be useful, 

15# but WITHOUT ANY WARRANTY; without even the implied warranty of 

16# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 

17# GNU General Public License for more details. 

18# 

19# You should have received a copy of the GNU General Public License 

20# along with this program. If not, see <https://www.gnu.org/licenses/>. 

21 

22from __future__ import annotations 

23 

24__all__ = ( 

25 "Tensor", 

26 "Scalar", 

27 "ScalarType", 

28 "KeyedData", 

29 "KeyedDataTypes", 

30 "KeyedDataSchema", 

31 "Vector", 

32 "PlotTypes", 

33 "KeyedResults", 

34) 

35 

36from abc import ABCMeta 

37from collections.abc import Iterable, Mapping, MutableMapping 

38from numbers import Number 

39from typing import Any, Protocol, runtime_checkable 

40 

41import numpy as np 

42from healsparse import HealSparseMap 

43from matplotlib.figure import Figure 

44from numpy.typing import NDArray 

45 

46from lsst.verify import Measurement 

47 

48 

49@runtime_checkable 

50class Tensor(Protocol): 

51 r"""This is an interface only class and is intended to represent data that 

52 is 2+ dimensions. 

53 

54 Technically one could use this for scalars or 1D arrays, 

55 but for those the Scalar or Vector interface should be preferred. 

56 

57 `Tensor`\ s abstract around the idea of a multidimensional array, and work 

58 with a variety of backends including Numpy, CuPy, Tensorflow, PyTorch, 

59 MXNet, TVM, and mpi4py. This intentionally has a minimum interface to 

60 comply with the industry standard dlpack which ensures each of these 

61 backend native types will work. 

62 

63 To ensure that a `Tensor` is in a desired container (e.g. ndarray) one can 

64 call the corresponding ``from_dlpack`` method. Whenever possible this will 

65 be a zero copy action. For instance to work with a Tensor named 

66 ``input_tensor`` as if it were a numpy object, one would do 

67 ``image = np.from_dlpack(input_tensor)``. 

68 """ 

69 

70 ndim: int 

71 shape: tuple[int, ...] 

72 strides: tuple[int, ...] 

73 

74 def __dlpack__(self, /, *, stream: int | None = ...) -> Any: ... 

75 

76 def __dlpack_device__(self) -> tuple[int, int]: ... 

77 

78 

79class ScalarMeta(ABCMeta): 

80 def __instancecheck__(cls: ABCMeta, instance: Any) -> Any: 

81 return isinstance(instance, tuple(cls.mro()[1:])) 

82 

83 

84class Scalar(Number, np.number, metaclass=ScalarMeta): # type: ignore 

85 """This is an interface only class, and is intended to abstract around all 

86 the various types of numbers used in Python. 

87 

88 This has been tried many times with various levels of success in python, 

89 and this is another attempt. However, as this class is only intended as an 

90 interface, and not something concrete to use it works. 

91 

92 Users should not directly instantiate from this class, instead they should 

93 use a built in python number type, or a numpy number. 

94 """ 

95 

96 def __init__(self) -> None: 

97 raise NotImplementedError("Scalar is only an interface and should not be directly instantiated") 

98 

99 

100ScalarType = type[Scalar] 

101"""A type alias for the Scalar interface.""" 

102 

103Vector = NDArray 

104"""A Vector is an abstraction around the NDArray interface, things that 'quack' 

105like an NDArray should be considered a Vector. 

106""" 

107 

108KeyedData = MutableMapping[str, Vector | Scalar | HealSparseMap | Tensor | Mapping] 

109"""KeyedData is an interface where either a `Vector`, `Scalar`, 

110`HealSparseMap`, `Tensor`, or `Mapping` can be retrieved using a key which is 

111of str type. 

112""" 

113 

114KeyedDataTypes = MutableMapping[ 

115 str, type[Vector] | ScalarType | type[HealSparseMap] | type[Tensor] | type[Mapping] 

116] 

117r"""A mapping of str keys to the Types which are valid in `KeyedData` objects. 

118This is useful in conjunction with `AnalysisAction`\ 's ``getInputSchema`` and 

119``getOutputSchema`` methods. 

120""" 

121 

122KeyedDataSchema = Iterable[ 

123 tuple[str, type[Vector] | ScalarType | type[HealSparseMap] | type[Tensor] | type[Mapping]] 

124] 

125r"""An interface that represents a type returned by `AnalysisAction`\ 's 

126``getInputSchema`` and ``getOutputSchema`` methods. 

127""" 

128 

129PlotTypes = Figure 

130"""An interface that represents the various plot types analysis tools supports. 

131""" 

132 

133KeyedResults = Mapping[str, PlotTypes | Measurement] 

134"""A mapping of the return types for an analysisTool.""" 

135 

136type MetricResultType = Mapping[str, Measurement] | Measurement 

137"""A type alias for the return type of a MetricAction.""" 

138 

139type PlotResultType = Mapping[str, PlotTypes] | PlotTypes 

140"""A type alias for the return type of a PlotAction."""