Session

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

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

  • plates() to access a table of DASCH plates overlapping your target

  • lightcurve() to access lightcurves for the catalog sources

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

Methods Summary

connect_to_wwt()

Connect this session to the WorldWide Telescope JupyterLab app.

cutout(plate_ref)

Obtain a FITS cutout for the specified plate.

lightcurve(src_ref)

Obtain a table of lightcurve data for the specified source.

path(*pieces)

Generate a filesystem path within this session.

plates()

Obtain the table of plates overlapping the session target area.

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])

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()[source]

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(plate_ref: PlateRow | int) str | None[source]

Obtain a FITS cutout for the specified plate.

Parameters:
plate_refint or PlateRow

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

If this argument is an instance of PlateRow, the cutout for the specified plate is obtained.

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 plate has not been scanned, among other reasons.

See also

daschlab.plates.Plates.show

to show a cutout in the WWT view

Notes

You must call select_target() and plates() 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 plate list is in chronological order):

from astropy.io import fits

solved_plates = sess.plates().keep_only.wcs_solved()
plate = solved_plates[0]

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

# str() needed here because Astropy does not accept Path objects:
hdu_list = fits.open(str(sess.path(relpath))
lightcurve(src_ref: RefcatSourceRow | int | Literal['click']) Lightcurve[source]

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.

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

Generate a filesystem path within this session.

Parameters:
*piecessequence of str

Path components

Returns:
A pathlib.Path relative to this session’s “root” directory.
plates() Plates[source]

Obtain the table of plates overlapping the session target area.

Returns:
A daschlab.plates.Plates 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 plate database, saving the resulting information in a file named plates.ecsv. Subsequent calls (i.e., ones made with the plates.ecsv file already existing) will merely check for consistency and load the saved file.

query() SessionQuery[source]

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[source]

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[source]

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) Session[source]

Specify the center of the session’s target area.

Parameters:
namestr

The Simbad-resolvable name of this session’s target area.

Returns:
self, for chaining convenience

Notes

The first time you call this method for a given session, it will perform a Simbad/Sesame API query to resolve the target name 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 merely provides the RA and dec.

This method could easily support queries based on RA/Dec rather than name resolution. If that’s functionality you would like, please consider filing a pull request.

wwt() WWTJupyterWidget[source]

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.