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

41 statements  

« prev     ^ index     » next       coverage.py v7.4.4, created at 2024-04-05 12:21 +0000

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 numbers import Number 

38from typing import Any, Iterable, Mapping, MutableMapping, Protocol, TypeAlias, runtime_checkable 

39 

40import numpy as np 

41from healsparse import HealSparseMap 

42from lsst.verify import Measurement 

43from matplotlib.figure import Figure 

44from numpy.typing import NDArray 

45 

46 

47@runtime_checkable 

48class Tensor(Protocol): 

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

50 is 2+ dimensions. 

51 

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

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

54 

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

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

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

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

59 backend native types will work. 

60 

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

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

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

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

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

66 """ 

67 

68 ndim: int 

69 shape: tuple[int, ...] 

70 strides: tuple[int, ...] 

71 

72 def __dlpack__(self, /, *, stream: int | None = ...) -> Any: ... 72 ↛ exitline 72 didn't jump to line 72, because

73 

74 def __dlpack_device__(self) -> tuple[int, int]: ... 74 ↛ exitline 74 didn't jump to line 74, because

75 

76 

77class ScalarMeta(ABCMeta): 

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

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

80 

81 

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

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

84 the various types of numbers used in Python. 

85 

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

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

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

89 

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

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

92 """ 

93 

94 def __init__(self) -> None: 

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

96 

97 

98ScalarType = type[Scalar] 

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

100 

101Vector = NDArray 

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

103like an NDArray should be considered a Vector. 

104""" 

105 

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

107"""KeyedData is an interface where either a `Vector` or `Scalar` can be 

108retrieved using a key which is of str type. 

109""" 

110 

111KeyedDataTypes = MutableMapping[str, type[Vector] | ScalarType | type[HealSparseMap] | type[Tensor]] 

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

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

114``getOutputSchema`` methods. 

115""" 

116 

117KeyedDataSchema = Iterable[tuple[str, type[Vector] | ScalarType | type[HealSparseMap] | type[Tensor]]] 

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

119``getInputSchema`` and ``getOutputSchema`` methods. 

120""" 

121 

122PlotTypes = Figure 

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

124""" 

125 

126KeyedResults = Mapping[str, PlotTypes | Measurement] 

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

128 

129MetricResultType: TypeAlias = Mapping[str, Measurement] | Measurement 

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

131 

132PlotResultType: TypeAlias = Mapping[str, PlotTypes] | PlotTypes 

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