Session

class daschlab.Session(root: str, interactive: bool = True, _internal_simg: str = '')

Bases: object

A daschlab analysis session.

Do not construct instances of this class directly. Instead, use the function daschlab.open_session(), which may perform additional, helpful initializations of the analysis environment.

Once you have obtained a Session instance, you should configure its key parameters with a series of function calls resembling the following:

from daschlab import open_session

sess = open_session(".")
sess.select_target("V* RY Cnc")
sess.select_refcat("apass")

# after opening the WWT JupyterLab application:
await sess.connect_to_wwt()

# You will generally also want to run:
from bokeh.io import output_notebook
output_notebook()

After this initialization is complete, you can obtain various data products relevant to your session with the following methods:

• refcat() to access a table of DASCH catalog sources near your target

• exposures() to access a table of exposures overlapping your target

• lightcurve() to access lightcurves for the catalog sources

• cutout() to download exposure cutout images centered on your target

• mosaic() to download full-plate “mosaic” data and synthesize a “value-added” FITS image

• extract() to download photometric data from a single plate, centered on your target

Methods Summary

connect_to_wwt()	Connect this session to the WorldWide Telescope JupyterLab app.
cutout(exp_ref[, no_download])	Obtain a FITS cutout for the specified exposure.
delete_data()	Delete all files stored on-disk for this session.
exposures()	Obtain the table of exposures overlapping the session target area.
extract(exp_ref)	Obtain an extract of photometric data for the specified exposure.
lightcurve(src_ref)	Obtain a table of lightcurve data for the specified source.
merge_lightcurves(src_refs)	Obtain a lightcurve merging rows from multiple catalog source lightcurves, under the assumption that they all contain data for the same astronomical source.
mosaic(plate_id, binning)	Obtain a "value-added" full-plate FITS mosaic.
path(*pieces)	Generate a filesystem path within this session.
query()	Obtain the session "query" specifying the center of the analysis region.
refcat()	Obtain the table of reference catalog sources associated with this session.
select_refcat(name)	Specify which DASCH reference catalog to use.
select_target([name, ra_deg, dec_deg, coords])	Specify the center of the session's target area.
wwt()	Obtain the WorldWide Telescope "widget" handle associated with this session.

Methods Documentation

async connect_to_wwt()

Connect this session to the WorldWide Telescope JupyterLab app.

Notes

This is an asynchonous function and should generally be called as:

await sess.connect_to_wwt()

After calling this function, the session will be able to automatically display various catalogs and images in the WWT viewer.

cutout(exp_ref: ExposureRow | int, no_download: bool = False) → str | None

Obtain a FITS cutout for the specified exposure.

Parameters:

exp_refint or ExposureRow

If this argument is an integer, it is interpreted as the “local ID” of a row in the exposures table.

If this argument is an instance of ExposureRow, the cutout for the specified exposure is obtained.

no_downloadoptional bool, default False

If set to true, no attempt will be made to download the requested cutout. If it is already cached on disk, the path will be returned; otherwise, None will be returned.

Returns:

A str or None.

If the former, the cutout was successfully fetched; the value is a path to a local FITS file containing the cutout data, relative to the session root. If the latter, a cutout could not be obtained. This could happen if the exposure has not been scanned, among other reasons.

See also

mosaic

obtain a full-plate “mosaic” image

daschlab.exposures.Exposures.show

to show a cutout in the WWT view

Notes

You must call select_target() and exposures() before calling this method.

The first time you call this method for a given session, it will perform a DASCH API query to fetch the cutout, saving the resulting data in a file inside the session’s cutouts subdirectory. Subsequent calls (i.e., ones made with the data file already existing) will merely check for consistency and load the saved file.

Examples

Load the cutout of the chronologically-first calibrated observation of the target field (the exposure list is in chronological order):

from astropy.io import fits

imaged_exposures = sess.exposures().keep_only.has_imaging()
exp = imaged_exposures[0]

relpath = sess.cutout(exp)
assert relpath, f"could not get cutout of {exp.exp_id()}"

# str() needed here because Astropy does not accept Path objects:
hdu_list = fits.open(str(sess.path(relpath))

delete_data()

Delete all files stored on-disk for this session.

Notes

This command will also clear any data tables stored in-memory, forcing them to be re-fetched from the data API as needed. It will recreate the session directory afterwards.

exposures() → Exposures

Obtain the table of exposures overlapping the session target area.

Returns:

A daschlab.exposures.Exposures instance.

Notes

You must call select_target() and select_refcat() before calling this method.

The first time you call this method for a given session, it will perform a DASCH API query to fetch information from the exposure database, saving the resulting information in a file named exposures.ecsv. Subsequent calls (i.e., ones made with the exposures.ecsv file already existing) will merely check for consistency and load the saved file.

extract(exp_ref: ExposureRow | int) → Extract

Obtain an extract of photometric data for the specified exposure.

Parameters:

exp_refint or …

Returns:

A daschlab.extracts.Extract instance.

Notes

You must call select_target() and select_refcat() before calling this method.

The first time you call this method for a given session, it will perform a DASCH API query to fetch information from the lightcurve database, saving the resulting information in a file inside the session’s lightcurves subdirectory. Subsequent calls (i.e., ones made with the data file already existing) will merely check for consistency and load the saved file.

lightcurve(src_ref: RefcatSourceRow | int | Literal['click']) → Lightcurve

Obtain a table of lightcurve data for the specified source.

Parameters:

src_refint or RefcatSourceRow or "click".

If this argument is an integer, it is interpreted as the “local ID” of a row in the reference catalog. Local IDs are assigned in order of distance from the query center, so a value of 0 fetches the lightcurve for the catalog source closest to the query target. This is probably what you want.

If this argument is an instance of RefcatSourceRow, the lightcurve for the specified source is obtained.

If this argument is the literal string value "click", the lightcurve for the catalog source that was most recently clicked in the WWT app is obtained. In particular, the most recently-clicked source must have a piece of metadata tagged local_id, which is interpreted as a refcat local ID.

Returns:

A daschlab.lightcurves.Lightcurve instance.

Notes

You must call select_target() and select_refcat() before calling this method.

The first time you call this method for a given session, it will perform a DASCH API query to fetch information from the lightcurve database, saving the resulting information in a file inside the session’s lightcurves subdirectory. Subsequent calls (i.e., ones made with the data file already existing) will merely check for consistency and load the saved file.

merge_lightcurves(src_refs: Iterable[RefcatSourceRow | int | Literal['click']]) → Lightcurve

Obtain a lightcurve merging rows from multiple catalog source lightcurves, under the assumption that they all contain data for the same astronomical source.

Parameters:

lcslist of int or RefcatSourceRow or "click"

These parameters specify the refcat sources whose lightcurves will be merged together. Individual values are interpreted as in lightcurve().

Returns:

merged_lcLightcurve

The merged lightcurve.

Notes

See the documentation for daschlab.lightcurves.merge() for details on the motivation, merge algorithm, and return value of this method.

Examples

Obtain a merged lightcurve from the four refcat sources closest to the session’s query position:

lc = session.merge_lightcurves(range(4))

mosaic(plate_id: str, binning: int) → str

Obtain a “value-added” full-plate FITS mosaic.

Parameters:

plate_idstr

The ID of the plate whose mosaic will be fetched. This should have the form {series}{platenum}, where the plate number is zero-padded to be five digits wide. Given an exposure table record, you can obtain its plate ID with plate_id().

binningint

Allowed values are 1 or 16. If 1, the full-resolution mosaic is downloaded. If 16, the 16×16 binned mosaic is downloaded. The binned file is smaller by a factor of 256, so the binned mosaics should be preferred if at all possible.

Returns:

str

The returned value is a path to a local FITS file containing the value-added mosaic, relative to the session root.

See also

cutout

get a full-resolution cutout around the session query point

Notes

The first time you call this method for a given plate, it will perform several DASCH API queries and download the “base” DASCH mosaic, saving the resulting file inside the session’s base_mosaics subdirectory. This download may take a while; the largest DASCH base mosaics are more than a gigabyte in size. daschlab will then create the “value-add” mosaic inside the session’s mosaics subdirectory, normalizing the data structure and inserting a variety of headers into the final FITS file. Subsequent invocations do no extra work if the final output file already exists.

Unbinned full-plate mosaics are large, and they can therefore be slow to load into visualization tools. Prefer using the cutout method unless you are really going to want to examine the entire mosaic at the pixel level.

Once a value-added mosaic is created, you can delete the base mosaics in the base_mosaics directory to save disk space.

Examples

Construct a binned FITS file for the plate with chronologically-last calibrated observation of the target field (the exposure list is in chronological order), and add it to the WWT display:

# Assumes `sess` is a Session object and it has been connected to
# WWT.

from toasty import TilingMethod

imaged_exposures = sess.exposures().keep_only.has_imaging()
exp = imaged_exposures[-1]

# Generate the value-add bin16 mosaic
relpath = sess.mosaic(exp.plate_id(), 16)

# Important to force TOAST tiling to avoid distortions with the
# large angular sizes of DASCH plates.
diskpath = str(sess.path(relpath))
sess.wwt().layers.add_image_layer(diskpath, tiling_method=TilingMethod.TOAST)

path(*pieces: Iterable[str]) → Path

Generate a filesystem path within this session.

Parameters:

*piecessequence of str

Path components

Returns:

A pathlib.Path relative to this session’s “root” directory.

query() → SessionQuery

Obtain the session “query” specifying the center of the analysis region.

Returns:

A daschlab.query.SessionQuery instance

Notes

You must call select_target() before calling this method.

refcat() → RefcatSources

Obtain the table of reference catalog sources associated with this session.

Returns:

A daschlab.refcat.RefcatSources instance.

Notes

You must call select_target() and select_refcat() before calling this method.

select_refcat(name: str) → Session

Specify which DASCH reference catalog to use.

Parameters:

namestr

The name of the reference catalog. Supported values are "apass" and "atlas", with "apass" being strongly recommended.

Returns:

self, for chaining convenience

Notes

You must have called select_target() before calling this method.

The first time you call this method for a given session, it will perform a DASCH API query to fetch information from the specified catalog, saving the resulting information in a file named refcat.ecsv. Subsequent calls (i.e., ones made with the refcat.ecsv file already existing) will merely check for consistency.

After calling this method, you may use refcat() to obtain the reference catalog data table. This table is a daschlab.refcat.RefcatSources object, which is a subclass of astropy.table.Table.

select_target(name: str | None = None, ra_deg: float | None = None, dec_deg: float | None = None, coords: SkyCoord | None = None) → Session

Specify the center of the session’s target area.

Parameters:

nameoptional str

If specified, target this session based on the given Simbad-resolvable source name.

ra_degoptional float

If specified, target this session based on given equatorial right ascension and declination, both measured in degrees.

dec_degoptional float

Companion to the ra_deg argument.

coordsoptional astropy.coordinates.SkyCoord

If specified, target this session based on the given Astropy coordinates, which will be converted to equatorial form.

Returns:

self, for chaining convenience

Notes

There are three ways to identify the session target: a Simbad/Sesame-resolvable name; explicit equatorial (RA/dec) coordinates in degrees; or an Astropy SkyCoord object. You may only provide one form of identification.

The first time you call this method for a given session, it resolve the target location (potentially making a Simbad/Sesame API call) and save the resulting information in a file named query.json. Subsequent calls (i.e., ones made with the query.json file already existing) will merely check for consistency.

After calling this method, you may use query() to obtain the cached information about your session’s target. This provides the RA and dec.

wwt() → WWTJupyterWidget

Obtain the WorldWide Telescope “widget” handle associated with this session.

Returns:

pywwt.jupyter.WWTJupyterWidget

The WWT widget object.

Notes

You must call connect_to_wwt() before you can use this method.