Lightcurve

class daschlab.lightcurves.Lightcurve(data=None, *, time=None, time_start=None, time_delta=None, n_samples=None, **kwargs)[source]

Bases: TimeSeries

A DASCH lightcurve data table.

A Lightcurve is a subclass of astropy.timeseries.TimeSeries, which in turn is a subclass of astropy.table.Table. It contains DASCH lightcurve data and associated lightcurve-specific methods. You can use all of the usual methods and properties made available by the astropy.timeseries.TimeSeries and astropy.table.Table classes. Items provided by those classes are not documented here.

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

You should not construct Lightcurve instances directly. Instead, obtain lightcurves using the daschlab.Session.lightcurve() method.

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

Cheat sheet:

  • time is HJD midpoint

  • magcal_magdep is preferred calibrated phot measurement

  • legacy plotter error bar is magcal_local_rms` * `error_bar_factor, the latter being set to match the error bars to the empirical RMS, if this would shrink the error bars

Attributes Summary

count

An action returning the number of selected rows

drop

An action returning a Lightcurve copy dropping the selected rows; all non-selected rows are retained.

keep_only

An action returning a Lightcurve copy containing only the selected rows.

match

An action returning a boolean array identifying selected rows.

reject

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

reject_unless

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

split_by

An action returning two Lightcurve copies, partitioning by the selection.

Methods Summary

apply_standard_rejections()

Apply a standard set of data-quality rejections to the lightcurve.

export(path[, format, drop_rejects])

Save a copy of this lightcurve to a file.

mean_pos()

Obtain the mean source position from the lightcurve points.

plot([x_axis, callout])

Plot the lightcurve using default settings.

scatter(x_axis, y_axis[, rejects])

Make a Bokeh scatter plot of lightcurve data.

summary()

Print a brief textual summary of the lightcurve contents.

Attributes Documentation

count

An action returning the number of selected rows

Unlike many actions, this returns an int, not a new Lightcurve

drop

An action returning a Lightcurve copy dropping the selected rows; all non-selected rows are retained.

keep_only

An action returning a Lightcurve 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 Lightcurve. It can be used to implement arbitrary boolean logic within the action/selection framework:

lc = sess.lightcurve(some_local_id)
subset = lc.keep_only.where(
    lc.match.series("a") & lc.match.brighter(13)
)
reject

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

Usage is as follows:

lc = sess.lightcurve(some_local_id)

# Mark all points from meteor telescopes as rejected:
lc.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.

If a verbose keyword argument is true (the default), a message will be printed summarizing the number of rejected rows. If false, nothing will be printed.

If a dry_run keyword argument is true (not the default), the "reject" column will not actually be modified. Instead, a message about what would have changed is printed.

reject_unless

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

Usage is as follows:

lc = sess.lightcurve(some_local_id)

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

# This is equivalent to:
lc.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.

The logical negation used by this function can cause problems if your lightcurve contains nondetections. For instance, if you intend to reject points unless they are brighter than a mag of 15.0, you will also reject all of the nondetections, even shallow upper limits consistent with that cutoff.

split_by

An action returning two Lightcurve copies, partitioning by the selection.

Unlike many actions, this returns a tuple of two new Lightcurve instances, not just one. The first returned instance contains only the selected points; the second instance returns all others. This can be useful for statistical comparisons:

from astropy import units as u

lc = sess.lightcurve(some_local_id)
neardet, fardet = lc.keep_only.nonrej_detected().split_by.sep_below(20 * u.arcsec)
near_std = neardet["magcal_magdep"].std()
far_std = neardet["magcal_magdep"].std()

Methods Documentation

apply_standard_rejections()[source]

Apply a standard set of data-quality rejections to the lightcurve.

Warning: this function is in development. Do not rely on it to fully clean your data.

Notes

Until this functionality is more settled, the rejections will not be documented here. See the source code to see what it does.

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

Save a copy of this lightcurve to a file.

Parameters:
pathstr

The path at which the exported lightcurve 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 points 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 lightcurve table documentation.

mean_pos() SkyCoord[source]

Obtain the mean source position from the lightcurve points.

Returns:
astropy.coordinates.SkyCoord

The mean position of the non-rejected detections

Notes

Average is done in degrees naively, so if your source has RA values of both 0 and 360, you might get seriously bogus results.

plot(x_axis: str = 'year', callout: ndarray | None = None) figure[source]

Plot the lightcurve using default settings.

Parameters:
x_axisoptional str, default "year"

The name of the column to use for the X axis. "year" is a synthetic column calculated on-the-fly from the "time" column, corresponding to the jyear property of the astropy.time.Time object.

calloutoptional numpy.ndarray, default None

If provided, this should be a boolean array of the same size as the lightcurve table. Points (both detections and nondetections) for which the array is true will be visually “called out” in the plot, highlighted in red.

Returns:
bokeh.plotting.figure

A plot.

Notes

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.

Examples

The match selector combines conveniently with the callout functionality in constructs like this:

# Call out points in the lightcurve with the "suspected defect" flag
lc.plot(callout=lc.match.any_aflags(AFlags.SUSPECTED_DEFECT))
scatter(x_axis: str, y_axis: str, rejects: bool = False) figure[source]

Make a Bokeh scatter plot of lightcurve data.

Parameters:
x_axisstr

The name of the column to use for the X axis.

y_axisstr

The name of the column to use for the Y axis.

rejectsoptional bool, default False

Whether to include rejected points in the resulting plot.

Returns:
bokeh.plotting.figure

A plot.

Notes

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.

summary()[source]

Print a brief textual summary of the lightcurve contents.