Coverage for python/lsst/daf/butler/_topology.py: 85%
47 statements
« prev ^ index » next coverage.py v7.3.2, created at 2023-10-27 09:44 +0000
« prev ^ index » next coverage.py v7.3.2, created at 2023-10-27 09:44 +0000
1# This file is part of daf_butler.
2#
3# Developed for the LSST Data Management System.
4# This product includes software developed by the LSST Project
5# (http://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 software is dual licensed under the GNU General Public License and also
10# under a 3-clause BSD license. Recipients may choose which of these licenses
11# to use; please see the files gpl-3.0.txt and/or bsd_license.txt,
12# respectively. If you choose the GPL option then the following text applies
13# (but note that there is still no warranty even if you opt for BSD instead):
14#
15# This program is free software: you can redistribute it and/or modify
16# it under the terms of the GNU General Public License as published by
17# the Free Software Foundation, either version 3 of the License, or
18# (at your option) any later version.
19#
20# This program is distributed in the hope that it will be useful,
21# but WITHOUT ANY WARRANTY; without even the implied warranty of
22# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
23# GNU General Public License for more details.
24#
25# You should have received a copy of the GNU General Public License
26# along with this program. If not, see <http://www.gnu.org/licenses/>.
28from __future__ import annotations
30__all__ = (
31 "TopologicalSpace",
32 "TopologicalFamily",
33 "TopologicalRelationshipEndpoint",
34)
36import enum
37from abc import ABC, abstractmethod
38from collections.abc import Mapping
39from typing import Any
41from lsst.utils.classes import immutable
43from ._named import NamedValueAbstractSet
46@enum.unique
47class TopologicalSpace(enum.Enum):
48 """Enumeration of continuous-variable relationships for dimensions.
50 Most dimension relationships are discrete, in that they are regular foreign
51 key relationships between tables. Those connected to a
52 `TopologicalSpace` are not - a row in a table instead occupies some
53 region in a continuous-variable space, and topological operators like
54 "overlaps" between regions in that space define the relationships between
55 rows.
56 """
58 SPATIAL = enum.auto()
59 """The (spherical) sky, using `lsst.sphgeom.Region` objects to represent
60 those regions in memory.
61 """
63 TEMPORAL = enum.auto()
64 """Time, using `Timespan` instances (with TAI endpoints) to represent
65 intervals in memory.
66 """
69@immutable
70class TopologicalFamily(ABC):
71 """A grouping of `TopologicalRelationshipEndpoint` objects.
73 These regions form a hierarchy in which one endpoint's rows always contain
74 another's in a predefined way.
76 This hierarchy means that endpoints in the same family do not generally
77 have to be have to be related using (e.g.) overlaps; instead, the regions
78 from one "best" endpoint from each family are related to the best endpoint
79 from each other family in a query.
81 Parameters
82 ----------
83 name : `str`
84 Unique string identifier for this family.
85 category : `TopologicalSpace`
86 Space in which the regions of this family live.
87 """
89 def __init__(
90 self,
91 name: str,
92 space: TopologicalSpace,
93 ):
94 self.name = name
95 self.space = space
97 def __eq__(self, other: Any) -> bool:
98 if isinstance(other, TopologicalFamily):
99 return self.space == other.space and self.name == other.name
100 return False
102 def __hash__(self) -> int:
103 return hash(self.name)
105 def __contains__(self, other: TopologicalRelationshipEndpoint) -> bool:
106 return other.topology.get(self.space) == self
108 @abstractmethod
109 def choose(
110 self, endpoints: NamedValueAbstractSet[TopologicalRelationshipEndpoint]
111 ) -> TopologicalRelationshipEndpoint:
112 """Select the best member of this family to use.
114 These are to be used in a query join or data ID when more than one
115 is present.
117 Usually this should correspond to the most fine-grained region.
119 Parameters
120 ----------
121 endpoints : `NamedValueAbstractSet` [`TopologicalRelationshipEndpoint`]
122 Endpoints to choose from. May include endpoints that are not
123 members of this family (which should be ignored).
125 Returns
126 -------
127 best : `TopologicalRelationshipEndpoint`
128 The best endpoint that is both a member of ``self`` and in
129 ``endpoints``.
130 """
131 raise NotImplementedError()
133 name: str
134 """Unique string identifier for this family (`str`).
135 """
137 space: TopologicalSpace
138 """Space in which the regions of this family live (`TopologicalSpace`).
139 """
142@immutable
143class TopologicalRelationshipEndpoint(ABC):
144 """Representation of a logical table that can participate in overlap joins.
146 An abstract base class whose instances represent a logical table that
147 may participate in overlap joins defined by a `TopologicalSpace`.
148 """
150 @property
151 @abstractmethod
152 def name(self) -> str:
153 """Return unique string identifier for this endpoint (`str`)."""
154 raise NotImplementedError()
156 @property
157 @abstractmethod
158 def topology(self) -> Mapping[TopologicalSpace, TopologicalFamily]:
159 """Return the relationship families to which this endpoint belongs.
161 It is keyed by the category for that family.
162 """
163 raise NotImplementedError()
165 @property
166 def spatial(self) -> TopologicalFamily | None:
167 """Return this endpoint's `~TopologicalSpace.SPATIAL` family."""
168 return self.topology.get(TopologicalSpace.SPATIAL)
170 @property
171 def temporal(self) -> TopologicalFamily | None:
172 """Return this endpoint's `~TopologicalSpace.TEMPORAL` family."""
173 return self.topology.get(TopologicalSpace.TEMPORAL)