Exposures

class daschlab.exposures.Exposures(data=None, masked=False, names=None, dtype=None, meta=None, copy=True, rows=None, copy_indices=True, units=None, descriptions=None, **kwargs)

Bases: Table

A table of DASCH exposure information.

An Exposures table is a subclass of astropy.table.Table containing DASCH exposure data and associated exposure-specific methods. You can use all of the usual methods and properties made available by the astropy.table.Table class. Items provided by the Table class are not documented here.

You should not construct Exposures instances directly. Instead, obtain the full table using the daschlab.Session.exposures() method.

The actual data contained in these tables — the columns — are documented elsewhere, on the main DASCH website.

See the module-level documentation of the daschlab.lightcurves for a summary of the filtering and subsetting functionality provided by this class.

Attributes Summary

count	An action returning the number of selected rows
drop	An action returning an Exposures copy dropping the selected rows; all non-selected rows are retained.
keep_only	An action returning an Exposures copy containing only the selected rows.
match	An action returning a boolean array identifying selected rows.
reject	An action modifying the exposure-list in-place, rejecting the selected rows.
reject_unless	An action modifying the exposure-list in-place, rejecting rows not matching the selection.

Methods Summary

candidate_nice_cutouts([source_of_interest, ...])	Return a table with information about exposures that might contain "nice" imagery of the target, in some vague sense.
export(path[, format, drop_rejects])	Save a copy of this exposure list to a file.
export_cutouts_to_pdf(pdfpath, **kwargs)	Export cutouts of the exposures in this list to a PDF file.
series_info()	Obtain a table summarizing information about the different plate series in the non-rejected rows of the current table.
show(exp_ref)	Display the cutout of the specified exposure in the WWT view.
show_extract(exp_ref)	Display the catalog extract of the specified exposure in the WWT view.
time_coverage()	Plot the observing time coverage of the non-rejected exposures in this list.

Attributes Documentation

count

An action returning the number of selected rows

Unlike many actions, this returns an int, not a new Exposures.

drop

An action returning an Exposures copy dropping the selected rows; all non-selected rows are retained.

keep_only

An action returning an Exposures copy containing only the selected rows.

match

An action returning a boolean array identifying selected rows.

Unlike many actions, this does not return a new Exposures. It can be used to implement arbitrary boolean logic within the action/selection framework:

exp = sess.exposures()
subset = exp.keep_only.where(
    exp.match.series("a") & exp.match.has_imaging()
)

reject

An action modifying the exposure-list in-place, rejecting the selected rows.

Usage is as follows:

exp = sess.exposures()

# Mark all exposures from meteor telescopes as rejected:
exp.reject.meteor(tag="meteor")

The tag keyword argument to the selector is mandatory. It specifies a short, arbitrary “tag” documenting the reason for rejection. Each unique tag is associated with a binary bit of the "reject" column, and these bits are logically OR’ed together as rejections are established. The maximum number of distinct rejection tags is 64, since the "reject" column is stored as a 64-bit integer.

reject_unless

An action modifying the exposure-list in-place, rejecting rows not matching the selection.

Usage is as follows:

exp = sess.exposures()

# Mark all exposures *not* from narrow-field telescopes as rejected:
exp.reject_unless.narrow(tag="lowrez")

# This is equivalent to:
exp.reject.not_.narrow(tag="lowrez")

The tag keyword argument to the selector is mandatory. It specifies a short, arbitrary “tag” documenting the reason for rejection. Each unique tag is associated with a binary bit of the "reject" column, and these bits are logically OR’ed together as rejections are established. The maximum number of distinct rejection tags is 64, since the "reject" column is stored as a 64-bit integer.

Methods Documentation

candidate_nice_cutouts(source_of_interest=0, limit_cols: bool = True, limit_rows: int | None = 8) → daschlab.lightcurves.Lightcurve

Return a table with information about exposures that might contain “nice” imagery of the target, in some vague sense.

Parameters:

source_of_interestoptional source reference, default 0

A source of interest that will be used to evaluate imaging quality. The lightcurve for this source will be downloaded, with the reference resolved as per the function daschlab.Session.lightcurve().

limit_colsoptional bool, default True

If true, drop various columns from the returned table. The preserved columns will be only the ones relevant to inferring the exposure image quality.

limit_rowsoptional int or None, default 10

If a positive integer, limit the returned table to only this many rows.

Returns:

daschlab.lightcurves.Lightcurve

The returned table is actually a Lightcurve table, re-sorted and potentially subsetted. The sort order will be in decreasing predicted image quality based on the lightcurve data.

Notes

The primary sort key is based on the limiting magnitude, which is a quantity available even in rows of the lightcurve that do not detect the source of interest. So, this method should be useful even if the source is not easily detected. Other image-quality metadata, however, may be missing, so this method will restrict itself to lightcurve rows with detections if there are a sufficient number of them.

export(path: str, format: str = 'csv', drop_rejects: bool = True)

Save a copy of this exposure list to a file.

Parameters:

pathstr

The path at which the exported exposure list data will be saved.

formatstr, default "csv"

The file format in which to save the data. Currently, the only allowed value is "csv".

drop_rejectsbool, default True

If True, rejected exposures will not appear in the output file at all. Otherwise, they will be included, and there will be a "reject" column reproducing their rejection status.

Notes

The default "csv" output format only exports a subset of the table columns known as the “medium” subset. It is defined in the exposure-list table documentation.

export_cutouts_to_pdf(pdfpath: str, **kwargs)

Export cutouts of the exposures in this list to a PDF file.

Parameters:

pdf_pathstr

The path at which the output file will be written. This path is not relative to the daschlab.Session root.

refcat_stdmag_limitoptional float

If specified, only sources from the reference catalog brigher than the specified stdmag limit will be overlaid on the cutouts. Otherwise, all refcat sources are overlaid, including very faint ones and ones without stdmag records.

no_downloadoptional bool, default False

If set to true, no cutouts will be downloaded. Only cutouts that are already cached locally will be used to construct the PDF.

Notes

This operation will by default attempt to download a cutout for every exposure with imaging in the list. This can be extremely slow, as well as creating a lot of work for the API server. Only use it for short exposure lists.

The format of the created file needs to be documented.

series_info() → Table

Obtain a table summarizing information about the different plate series in the non-rejected rows of the current table.

Returns:

astropy.table.Table

A table of summary information

Notes

Columns in the returned table include:

• "series": the plate series in question

• "count": the number of exposures from the series in self

• "kind": the daschlab.series.SeriesKind of this series

• "plate_scale": the typical plate scale of this series (in arcsec/mm)

• "aperture": the telescope aperture of this series (in meters)

• "description": a textual description of this series

The table is sorted by decreasing "count".

show(exp_ref: ExposureRow | int) → ImageLayer

Display the cutout of the specified exposure in the WWT view.

Parameters:

exp_refExposureRow or int

If this argument is an integer, it is interpreted as the “local ID” of an exposure. Local IDs are assigned in chronological order of observing time, so a value of 0 shows the first exposure. This will only work if the selected exposure is scanned and WCS-solved.

If this argument is an instance of ExposureRow, the specified exposure is shown.

Returns:

pywwt.layers.ImageLayer

This is the WWT image layer object corresponding to the displayed FITS file. You can use it to programmatically control aspects of how the file is displayed, such as the colormap.

Notes

In order to use this method, you must first have called daschlab.Session.connect_to_wwt(). If needed, this method will execute an API call and download the cutout to be displayed, which may be slow.

show_extract(exp_ref: ExposureRow | int) → TableLayer

Display the catalog extract of the specified exposure in the WWT view.

Parameters:

exp_refExposureRow or int

If this argument is an integer, it is interpreted as the “local ID” of an exposure. Local IDs are assigned in chronological order of observing time, so a value of 0 shows the first exposure. This will only work if the selected exposure is scanned and WCS-solved.

If this argument is an instance of ExposureRow, the specified exposure is shown.

Returns:

pywwt.layers.TableLayer

This is the WWT table layer object corresponding to the displayed catalog extract. You can use it to programmatically control aspects of how the data are displayed.

Notes

In order to use this method, you must first have called daschlab.Session.connect_to_wwt(). If needed, this method will execute an API call and download the data to be displayed, which may be slow.

This method is equivalent to calling sess.extract(exp_ref).show().

time_coverage() → figure

Plot the observing time coverage of the non-rejected exposures in this list.

Returns:

bokeh.plotting.figure

A plot.

Notes

The plot is generated by using a Gaussian kernel density estimator to smooth out the exposure observation times.

The function bokeh.io.show (imported as bokeh.plotting.show) is called on the figure before it is returned, so you don’t need to do that yourself.