Coverage for python/lsst/daf/butler/core/dataUnit.py : 93%

Hot-keys on this page
r m x p toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
# This file is part of daf_butler. # # Developed for the LSST Data Management System. # This product includes software developed by the LSST Project # (http://www.lsst.org). # See the COPYRIGHT file at the top-level directory of this distribution # for details of code ownership. # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by # the Free Software Foundation, either version 3 of the License, or # (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU General Public License for more details. # # You should have received a copy of the GNU General Public License # along with this program. If not, see <http://www.gnu.org/licenses/>.
"""A discrete abstract unit of data that can be associated with metadata and used to label datasets.
`DataUnit` instances represent concrete units such as e.g. `Camera`, `Sensor`, `Visit` and `SkyMap`.
Parameters ---------- name : `str` Name of this `DataUnit`. Also assumed to be the name of the primary table (if present). requiredDependencies : `frozenset` Related `DataUnit` instances on which existence this `DataUnit` instance depends. optionalDependencies : `frozenset` Related `DataUnit` instances that may also be provided (and when they are, they must be kept in sync). link : `tuple` Names of columns that form the `DataUnit` specific part of the primary-key in this `DataUnit` table and are also the names of the link column in the Datasets table. table : `sqlalchemy.core.Table`, optional When not ``None`` the primary table entry corresponding to this `DataUnit`. spatial : `bool`, optional Is this a spatial `DataUnit`? If so then it either has a ``region`` column, or some other way to get a region (e.g. ``SkyPix``). """
link=(), table=None, spatial=False):
return "DataUnit({})".format(self.name)
def name(self): """Name of this `DataUnit` (`str`, read-only).
Also assumed to be the name of the primary table (if present)."""
def requiredDependencies(self): """Related `DataUnit` instances on which existence this `DataUnit` instance depends (`frozenset`, read-only). """
def optionalDependencies(self): """Related `DataUnit` instances that may also be provided (and when they are, they must be kept in sync) (`frozenset`, read-only). """
def dependencies(self): """The union of `requiredDependencies` and `optionalDependencies` (`frozenset`, read-only). """
def table(self): """When not ``None`` the primary table entry corresponding to this `DataUnit` (`sqlalchemy.core.Table`, optional). """
def link(self): """Names of columns that form the `DataUnit` specific part of the primary-key in this `DataUnit` table and are also the names of the link column in the Datasets table (`tuple`). """
def primaryKey(self): """Full primary-key column name tuple. Consists of the ``link`` of this `DataUnit` and that of all its ``requiredDependencies`` (`set`). """
def linkColumns(self): """Dictionary keyed on ``link`` names with `sqlalchemy.Column` entries into this `DataUnit` primary table as values (`dict`). """ return {name: self.table.columns[name] for name in self.link}
def primaryKeyColumns(self): """Dictionary keyed on ``primaryKey`` names with `sqlalchemy.Column` entries into this `DataUnit` primary table as values (`dict`). """
def regionColumn(self): """Table column (`sqlalchemy.Column`) with encoded region data, ``None`` if table has no region column. """ return None
def spatial(self): """Is this a spatial `DataUnitJoin`? """
"""Check if given dataId is valid.
Parameters ---------- dataId : `dict` A `dict` of `DataUnit` link name, value pairs that label the `DatasetRef` within a Collection.
Raises ------ ValueError If a value for a required dependency is missing. """ missing, dataId, self.name))
"""Represents a join between one or more `DataUnit`s.
Parameters ---------- name : `str` Name of this `DataUnit` (`str`, read-only). Also assumed to be the name of the primary table (if present). lhs : `tuple` Left-hand-side of the join. rhs : `tuple` Right-hand-side of the join. summarizes : `DataUnitJoin` Summarizes this other `DataUnitJoin`. isView : `bool`, optional True if the table assocaited with this join is actually a view, False if it is a regular table, and None if it is neither. table : `sqlalchemy.TableClause` or `sqlalchemy.Table` The table to be used for queries. Note that this is not an actual `Table` in many cases because joins are often materialized as views (and thus are also not present in `Registry._schema._metadata`). relates : `tuple` of `DataUnit` The DataUnits in this relationship. spatial : `bool`, optional Is this a spatial `DataUnit`? If so then it either has a ``region`` column, or some other way to get a region (e.g. ``SkyPix``). """
isView=None, table=None, relates=None, spatial=False):
def name(self): """Name of this `DataUnit` (`str`, read-only).
Also assumed to be the name of the primary table (if present)."""
def lhs(self):
def rhs(self):
def relates(self):
def spatial(self):
def summarizes(self):
def isView(self):
def table(self): """When not ``None`` the primary table entry corresponding to this `DataUnitJoin` (`sqlalchemy.core.TableClause`, optional). """
def primaryKey(self): """Full primary-key column name tuple. """
def primaryKeyColumns(self): """Dictionary keyed on ``primaryKey`` names with `sqlalchemy.Column` entries into this `DataUnitJoin` primary table as values (`dict`). """
def regionColumn(self): """Table column with encoded region data, ``None`` if table has no region column (`sqlalchemy.Column`, optional). """ return None
"""Instances of this class keep track of `DataUnit` relations.
Entries in this `dict`-like object represent `DataUnit` instances, keyed on `DataUnit` names. """
"""Alternative constructor.
Build a `DataUnitRegistry` instance from a `Config` object and an (optional) `SchemaBuilder`.
Parameters ---------- config : `SchemaConfig` `Registry` schema configuration containing "DataUnits", "dataUnitRegions", and "dataUnitJoins" entries. builder : `SchemaBuilder`, optional When given, create `sqlalchemy.core.Table` entries for every `DataUnit` table. """
return len(self._dataUnits)
return iter(self._dataUnitNames)
return iter(self._dataUnitNames)
return (self[dataUnitName] for dataUnitName in self._dataUnitNames)
"""Return the DataUnit or DataUnitJoin that holds region for the given combination of DataUnits.
Returned object can be either `DataUnitJoin` or `DataUnit`. Use ``table`` and/or ``regionColumn`` properties of returned object to retrieve region data from database table.
Returns ------- `DataUnitJoin` or `DataUnit` instance. """
"""Return the DataUnitJoin that relates the given DataUnit names.
While DataUnitJoins are associated with a specific ordering or lhs and rhs, this method tries both.
Parameters ---------- lhs : `str` or sequence DataUnit name or sequence of names for one side of the join. rhs : `str` or sequence DataUnit name or sequence of names for the other side of the join.
Returns ------- join : `DataUnitJoin` The DataUnitJoin that relates the given DataUnits, or None. """
"""Initialize DataUnit names.
Because `DataUnit` entries may apear in any order in the `Config`, but dependencies between them define a topological order in which objects should be created, store them in a `TopologicalSet`.
Parameters ---------- config : `SchemaConfig` The `dataUnits` component of a `SchemaConfig`. """
"""Initialize `DataUnit` entries.
Parameters ---------- config : `Config` The `dataUnits` component of a `SchemaConfig`. builder : `SchemaBuilder`, optional When given, create `sqlalchemy.core.Table` entries for every `DataUnit` table. """ # Visit DataUnits in dependency order # Link names # Link columns that will become part of the Datasets table # Primary table for this DataUnit else: # Secondary table builder.addTable(tableName, tableDescription) requiredDependencies=requiredDependencies, optionalDependencies=optionalDependencies, table=table, link=link, spatial=spatial) # The DataUnit (or DataUnitJoin) instance that can be used # to retreive the region is keyed based on the union # of the DataUnit and its required dependencies that are also spatial. # E.g. "Patch" is keyed on ("Tract", "Patch"). # This requires that DataUnit's are visited in topologically sorted order # (which they are). tuple(d.name for d in dataUnit.requiredDependencies if d.name in self._spatialDataUnits))
"""Initialize `DataUnit` join entries.
Parameters ---------- config : `SchemaConfig` Schema configuration describing `DataUnit` join relations. builder : `SchemaBuilder`, optional When given, create `sqlalchemy.core.Table` entries for every `DataUnit` table. """ lhs=lhs, rhs=rhs, summarizes=summarizes, isView=isView, table=table, spatial=spatial, relates=relates)
"""Get all primary-key column names for the given ``dataUnitNames``.
Parameters ---------- dataUnitNames : `sequence` A sequence of `DataUnit` names.
Returns ------- primaryKeyNames : `set` All primary-key column names for the given ``dataUnitNames``. """
"""Get a `DataUnit` for which ``name`` is part of the link.
Parameters ---------- name : `str` Link name.
Returns ------- dataUnit : `DataUnit` The corresponding `DataUnit` instance.
Raises ------ KeyError When the provided ``name`` does not correspond to a link for any of the `DataUnit` entries in the registry. """ |