Public Member Functions |
Public Attributes |
Protected Attributes |
Properties |
List of all members
lsst.afw.table._base.Catalog Class Reference
Inheritance diagram for lsst.afw.table._base.Catalog:
Public Member Functions | |
| getColumnView (self) | |
| __getitem__ (self, key) | |
| __setitem__ (self, key, value) | |
| __delitem__ (self, key) | |
| append (self, record) | |
| insert (self, key, value) | |
| clear (self) | |
| addNew (self) | |
| cast (self, type_, deep=False) | |
| copy (self, deep=False) | |
| extend (self, iterable, deep=False, mapper=None) | |
| __reduce__ (self) | |
| asAstropy (self, cls=None, copy=False, unviewable="copy") | |
| __dir__ (self) | |
| __getattr__ (self, name) | |
| __str__ (self) | |
| __repr__ (self) | |
| extract (self, *patterns, **kwds) | |
Public Attributes | |
| table = None | |
Protected Attributes | |
| _columns = self._getColumnView() | |
Properties | |
| columns = property(__getColumns, doc="a column view of the catalog") | |
Detailed Description
Member Function Documentation
◆ __delitem__()
| lsst.afw.table._base.Catalog.__delitem__ | ( | self, | |
| key ) |
◆ __dir__()
| lsst.afw.table._base.Catalog.__dir__ | ( | self | ) |
This custom dir is necessary due to the custom getattr below. Without it, not all of the methods available are returned with dir. See DM-7199.
Definition at line 312 of file _base.py.
312 def __dir__(self):
313 """
314 This custom dir is necessary due to the custom getattr below.
315 Without it, not all of the methods available are returned with dir.
316 See DM-7199.
317 """
318 def recursive_get_class_dir(cls):
319 """
320 Return a set containing the names of all methods
321 for a given class *and* all of its subclasses.
322 """
323 result = set()
324 if cls.__bases__:
325 for subcls in cls.__bases__:
326 result |= recursive_get_class_dir(subcls)
327 result |= set(cls.__dict__.keys())
328 return result
329 return sorted(set(dir(self.columns)) | set(dir(self.table))
330 | recursive_get_class_dir(type(self)) | set(self.__dict__.keys()))
331
◆ __getattr__()
| lsst.afw.table._base.Catalog.__getattr__ | ( | self, | |
| name ) |
Definition at line 332 of file _base.py.
332 def __getattr__(self, name):
333 # Catalog forwards unknown method calls to its table and column view
334 # for convenience. (Feature requested by RHL; complaints about magic
335 # should be directed to him.)
336 if name == "_columns":
337 self._columns = None
338 return None
339 try:
340 return getattr(self.table, name)
341 except AttributeError:
342 # Special case __ properties as they are never going to be column
343 # names.
344 if name.startswith("__"):
345 raise
346 # This can fail if the table is non-contiguous
347 try:
348 attr = getattr(self.columns, name)
349 except Exception as e:
350 e.add_note(f"Error retrieving column attribute '{name}' from {type(self)}")
351 raise
352 return attr
353
◆ __getitem__()
| lsst.afw.table._base.Catalog.__getitem__ | ( | self, | |
| key ) |
Return the record at index key if key is an integer, return a column if `key` is a string field name or Key, or return a subset of the catalog if key is a slice or boolean NumPy array.
Definition at line 85 of file _base.py.
85 def __getitem__(self, key):
86 """Return the record at index key if key is an integer,
87 return a column if `key` is a string field name or Key,
88 or return a subset of the catalog if key is a slice
89 or boolean NumPy array.
90 """
91 if type(key) is slice:
92 (start, stop, step) = (key.start, key.stop, key.step)
93 if step is None:
94 step = 1
95 if start is None:
96 start = 0
97 if stop is None:
98 stop = len(self)
99 return self.subset(start, stop, step)
100 elif isinstance(key, np.ndarray):
101 if key.dtype == bool:
102 return self.subset(key)
103 raise RuntimeError("Unsupported array type for indexing a Catalog, "
104 f"only boolean arrays are supported: {key.dtype}")
105 elif isinstance(key, str):
106 key = self.schema.find(key).key
107 result, self._columns = self._get_column_from_key(key, self._columns)
108 return result
109 elif isinstance(key, Key):
110 result, self._columns = self._get_column_from_key(key, self._columns)
111 return result
112 else:
113 return self._getitem_(key)
114
◆ __reduce__()
| lsst.afw.table._base.Catalog.__reduce__ | ( | self | ) |
◆ __repr__()
| lsst.afw.table._base.Catalog.__repr__ | ( | self | ) |
◆ __setitem__()
| lsst.afw.table._base.Catalog.__setitem__ | ( | self, | |
| key, | |||
| value ) |
If ``key`` is an integer, set ``catalog[key]`` to ``value``. Otherwise select column ``key`` and set it to ``value``.
Definition at line 115 of file _base.py.
115 def __setitem__(self, key, value):
116 """If ``key`` is an integer, set ``catalog[key]`` to
117 ``value``. Otherwise select column ``key`` and set it to
118 ``value``.
119 """
120 self._columns = None
121 if isinstance(key, str):
122 key = self.schema[key].asKey()
123 if isinstance(key, Key):
124 if isinstance(key, Key["Flag"]):
125 self._set_flag(key, value)
126 else:
127 self.columns[key] = value
128 else:
129 return self.set(key, value)
130
◆ __str__()
| lsst.afw.table._base.Catalog.__str__ | ( | self | ) |
◆ addNew()
| lsst.afw.table._base.Catalog.addNew | ( | self | ) |
◆ append()
| lsst.afw.table._base.Catalog.append | ( | self, | |
| record ) |
◆ asAstropy()
| lsst.afw.table._base.Catalog.asAstropy | ( | self, | |
| cls = None, | |||
| copy = False, | |||
| unviewable = "copy" ) |
Return an astropy.table.Table (or subclass thereof) view into this catalog.
Parameters
----------
cls :
Table subclass to use; `None` implies `astropy.table.Table`
itself. Use `astropy.table.QTable` to get Quantity columns.
copy : bool, optional
If `True`, copy data from the LSST catalog to the astropy
table. Not copying is usually faster, but can keep memory
from being freed if columns are later removed from the
Astropy view.
unviewable : `str`, optional
One of the following options (which is ignored if
copy=`True` ), indicating how to handle field types (`str`
and `Flag`) for which views cannot be constructed:
- 'copy' (default): copy only the unviewable fields.
- 'raise': raise ValueError if unviewable fields are present.
- 'skip': do not include unviewable fields in the Astropy Table.
Returns
-------
cls : `astropy.table.Table`
Astropy view into the catalog.
Raises
------
ValueError
Raised if the `unviewable` option is not a known value, or
if the option is 'raise' and an uncopyable field is found.
Definition at line 221 of file _base.py.
221 def asAstropy(self, cls=None, copy=False, unviewable="copy"):
222 """Return an astropy.table.Table (or subclass thereof) view into this catalog.
223
224 Parameters
225 ----------
226 cls :
227 Table subclass to use; `None` implies `astropy.table.Table`
228 itself. Use `astropy.table.QTable` to get Quantity columns.
229 copy : bool, optional
230 If `True`, copy data from the LSST catalog to the astropy
231 table. Not copying is usually faster, but can keep memory
232 from being freed if columns are later removed from the
233 Astropy view.
234 unviewable : `str`, optional
235 One of the following options (which is ignored if
236 copy=`True` ), indicating how to handle field types (`str`
237 and `Flag`) for which views cannot be constructed:
238
239 - 'copy' (default): copy only the unviewable fields.
240 - 'raise': raise ValueError if unviewable fields are present.
241 - 'skip': do not include unviewable fields in the Astropy Table.
242
243 Returns
244 -------
245 cls : `astropy.table.Table`
246 Astropy view into the catalog.
247
248 Raises
249 ------
250 ValueError
251 Raised if the `unviewable` option is not a known value, or
252 if the option is 'raise' and an uncopyable field is found.
253
254 """
255 import astropy.table
256 if cls is None:
257 cls = astropy.table.Table
258 if unviewable not in ("copy", "raise", "skip"):
259 raise ValueError(
260 f"'unviewable'={unviewable!r} must be one of 'copy', 'raise', or 'skip'")
261 ps = self.getMetadata()
262 meta = ps.toOrderedDict() if ps is not None else None
263 columns = []
264 items = self.schema.extract("*", ordered=True)
265 for name, item in items.items():
266 key = item.key
267 unit = item.field.getUnits() or None # use None instead of "" when empty
268 if key.getTypeString() == "String":
269 if not copy:
270 if unviewable == "raise":
271 raise ValueError("Cannot extract string "
272 "unless copy=True or unviewable='copy' or 'skip'.")
273 elif unviewable == "skip":
274 continue
275 data = np.zeros(
276 len(self), dtype=np.dtype((str, key.getSize())))
277 for i, record in enumerate(self):
278 data[i] = record.get(key)
279 elif key.getTypeString() == "Flag":
280 if not copy:
281 if unviewable == "raise":
282 raise ValueError("Cannot extract packed bit columns "
283 "unless copy=True or unviewable='copy' or 'skip'.")
284 elif unviewable == "skip":
285 continue
286 data = self[key]
287 elif key.getTypeString() == "Angle":
288 data = self.columns.get(key)
289 unit = "radian"
290 if copy:
291 data = data.copy()
292 elif "Array" in key.getTypeString() and key.isVariableLength():
293 # Can't get columns for variable-length array fields.
294 if unviewable == "raise":
295 raise ValueError("Cannot extract variable-length array fields unless unviewable='skip'.")
296 elif unviewable == "skip" or unviewable == "copy":
297 continue
298 else:
299 data = self.columns.get(key)
300 if copy:
301 data = data.copy()
302 columns.append(
303 astropy.table.Column(
304 data,
305 name=name,
306 unit=unit,
307 description=item.field.getDoc()
308 )
309 )
310 return cls(columns, meta=meta, copy=False)
311
◆ cast()
| lsst.afw.table._base.Catalog.cast | ( | self, | |
| type_, | |||
| deep = False ) |
Return a copy of the catalog with the given type.
Parameters
----------
type_ :
Type of catalog to return.
deep : `bool`, optional
If `True`, clone the table and deep copy all records.
Returns
-------
copy :
Copy of catalog with the requested type.
Definition at line 154 of file _base.py.
154 def cast(self, type_, deep=False):
155 """Return a copy of the catalog with the given type.
156
157 Parameters
158 ----------
159 type_ :
160 Type of catalog to return.
161 deep : `bool`, optional
162 If `True`, clone the table and deep copy all records.
163
164 Returns
165 -------
166 copy :
167 Copy of catalog with the requested type.
168 """
169 if deep:
170 table = self.table.clone()
171 table.preallocate(len(self))
172 else:
173 table = self.table
174 copy = type_(table)
175 copy.extend(self, deep=deep)
176 return copy
177
◆ clear()
| lsst.afw.table._base.Catalog.clear | ( | self | ) |
◆ copy()
| lsst.afw.table._base.Catalog.copy | ( | self, | |
| deep = False ) |
◆ extend()
| lsst.afw.table._base.Catalog.extend | ( | self, | |
| iterable, | |||
| deep = False, | |||
| mapper = None ) |
Append all records in the given iterable to the catalog.
Parameters
----------
iterable :
Any Python iterable containing records.
deep : `bool`, optional
If `True`, the records will be deep-copied; ignored if
mapper is not `None` (that always implies `True`).
mapper : `lsst.afw.table.schemaMapper.SchemaMapper`, optional
Used to translate records.
Definition at line 184 of file _base.py.
184 def extend(self, iterable, deep=False, mapper=None):
185 """Append all records in the given iterable to the catalog.
186
187 Parameters
188 ----------
189 iterable :
190 Any Python iterable containing records.
191 deep : `bool`, optional
192 If `True`, the records will be deep-copied; ignored if
193 mapper is not `None` (that always implies `True`).
194 mapper : `lsst.afw.table.schemaMapper.SchemaMapper`, optional
195 Used to translate records.
196 """
197 self._columns = None
198 # We can't use isinstance here, because the SchemaMapper symbol isn't available
199 # when this code is part of a subclass of Catalog in another package.
200 if type(deep).__name__ == "SchemaMapper":
201 mapper = deep
202 deep = None
203 if isinstance(iterable, type(self)):
204 if mapper is not None:
205 self._extend(iterable, mapper)
206 else:
207 self._extend(iterable, deep)
208 else:
209 for record in iterable:
210 if mapper is not None:
211 self._append(self.table.copyRecord(record, mapper))
212 elif deep:
213 self._append(self.table.copyRecord(record))
214 else:
215 self._append(record)
216
◆ extract()
| lsst.afw.table._base.Catalog.extract | ( | self, | |
| * | patterns, | ||
| ** | kwds ) |
Extract a dictionary of {<name>: <column-array>} in which the field
names match the given shell-style glob pattern(s).
Any number of glob patterns may be passed (including none); the result
will be the union of all the result of each glob considered separately.
Note that extract("*", copy=True) provides an easy way to transform a
catalog into a set of writeable contiguous NumPy arrays.
This routines unpacks `Flag` columns into full boolean arrays. String
fields are silently ignored.
Parameters
----------
patterns : Array of `str`
List of glob patterns to use to select field names.
kwds : `dict`
Dictionary of additional keyword arguments. May contain:
``items`` : `list`
The result of a call to self.schema.extract(); this will be
used instead of doing any new matching, and allows the pattern
matching to be reused to extract values from multiple records.
This keyword is incompatible with any position arguments and
the regex, sub, and ordered keyword arguments.
``where`` : array index expression
Any expression that can be passed as indices to a NumPy array,
including slices, boolean arrays, and index arrays, that will
be used to index each column array. This is applied before
arrays are copied when copy is True, so if the indexing results
in an implicit copy no unnecessary second copy is performed.
``copy`` : `bool`
If True, the returned arrays will be contiguous copies rather
than strided views into the catalog. This ensures that the
lifetime of the catalog is not tied to the lifetime of a
particular catalog, and it also may improve the performance if
the array is used repeatedly. Default is False. Copies are
always made if the catalog is noncontiguous, but if
``copy=False`` these set as read-only to ensure code does not
assume they are views that could modify the original catalog.
``regex`` : `str` or `re` pattern
A regular expression to be used in addition to any glob
patterns passed as positional arguments. Note that this will
be compared with re.match, not re.search.
``sub`` : `str`
A replacement string (see re.MatchObject.expand) used to set
the dictionary keys of any fields matched by regex.
``ordered`` : `bool`
If True, a collections.OrderedDict will be returned instead of
a standard dict, with the order corresponding to the definition
order of the Schema. Default is False.
Returns
-------
d : `dict`
Dictionary of extracted name-column array sets.
Raises
------
ValueError
Raised if a list of ``items`` is supplied with additional keywords.
Definition at line 364 of file _base.py.
364 def extract(self, *patterns, **kwds):
365 """Extract a dictionary of {<name>: <column-array>} in which the field
366 names match the given shell-style glob pattern(s).
367
368 Any number of glob patterns may be passed (including none); the result
369 will be the union of all the result of each glob considered separately.
370
371 Note that extract("*", copy=True) provides an easy way to transform a
372 catalog into a set of writeable contiguous NumPy arrays.
373
374 This routines unpacks `Flag` columns into full boolean arrays. String
375 fields are silently ignored.
376
377 Parameters
378 ----------
379 patterns : Array of `str`
380 List of glob patterns to use to select field names.
381 kwds : `dict`
382 Dictionary of additional keyword arguments. May contain:
383
384 ``items`` : `list`
385 The result of a call to self.schema.extract(); this will be
386 used instead of doing any new matching, and allows the pattern
387 matching to be reused to extract values from multiple records.
388 This keyword is incompatible with any position arguments and
389 the regex, sub, and ordered keyword arguments.
390 ``where`` : array index expression
391 Any expression that can be passed as indices to a NumPy array,
392 including slices, boolean arrays, and index arrays, that will
393 be used to index each column array. This is applied before
394 arrays are copied when copy is True, so if the indexing results
395 in an implicit copy no unnecessary second copy is performed.
396 ``copy`` : `bool`
397 If True, the returned arrays will be contiguous copies rather
398 than strided views into the catalog. This ensures that the
399 lifetime of the catalog is not tied to the lifetime of a
400 particular catalog, and it also may improve the performance if
401 the array is used repeatedly. Default is False. Copies are
402 always made if the catalog is noncontiguous, but if
403 ``copy=False`` these set as read-only to ensure code does not
404 assume they are views that could modify the original catalog.
405 ``regex`` : `str` or `re` pattern
406 A regular expression to be used in addition to any glob
407 patterns passed as positional arguments. Note that this will
408 be compared with re.match, not re.search.
409 ``sub`` : `str`
410 A replacement string (see re.MatchObject.expand) used to set
411 the dictionary keys of any fields matched by regex.
412 ``ordered`` : `bool`
413 If True, a collections.OrderedDict will be returned instead of
414 a standard dict, with the order corresponding to the definition
415 order of the Schema. Default is False.
416
417 Returns
418 -------
419 d : `dict`
420 Dictionary of extracted name-column array sets.
421
422 Raises
423 ------
424 ValueError
425 Raised if a list of ``items`` is supplied with additional keywords.
426 """
427 copy = kwds.pop("copy", False)
428 where = kwds.pop("where", None)
429 d = kwds.pop("items", None)
430 # If ``items`` is given as a kwd, an extraction has already been
431 # performed and there shouldn't be any additional keywords. Otherwise
432 # call schema.extract to load the dictionary.
433 if d is None:
434 d = self.schema.extract(*patterns, **kwds).copy()
435 elif kwds:
436 raise ValueError(
437 "kwd 'items' was specified, which is not compatible with additional keywords")
438
439 def processArray(a):
440 if where is not None:
441 a = a[where]
442 if copy:
443 a = a.copy()
444 return a
445
446 # must use list because we might be adding/deleting elements
447 for name, schemaItem in list(d.items()):
448 key = schemaItem.key
449 if key.getTypeString() == "String":
450 del d[name]
451 else:
452 d[name] = processArray(self[schemaItem.key])
453 return d
454
455
◆ getColumnView()
| lsst.afw.table._base.Catalog.getColumnView | ( | self | ) |
◆ insert()
| lsst.afw.table._base.Catalog.insert | ( | self, | |
| key, | |||
| value ) |
Member Data Documentation
◆ _columns
|
protected |
◆ table
Property Documentation
◆ columns
|
static |
The documentation for this class was generated from the following file:
- /j/snowflake/release/lsstsw/stack/lsst-scipipe-10.0.0/Linux64/afw/g0485b4d2cb+c8d56b10d4/python/lsst/afw/table/_base.py
Generated on Tue May 13 2025 08:22:21 for LSST Applications by
1.13.2