Lightcurve

class snappl.lightcurve.Lightcurve(id=None, data=None, meta=None, multiband=False, filepath=None, base_dir=None, base_path=None, full_filepath=None, no_base_path=False)

Bases: PathedObject

A class to store and save lightcurve data across different SNPIT photometry codes.

Properties include:

• filepath : pathlib.Path ; path relative to the base path of the lightcurve file

• full_filepath : pathlib.Path ; absolute path on the system to the lightcurve file

• base_path : base path for lightcurves; usually will be Config value system.paths.lightcurves

• base_dir : synonym for base_path

• lightcurveThe actual lightcurve data, an Astropy QTable

  (see https://github.com/Roman-Supernova-PIT/Roman-Supernova-PIT/wiki/lightcurve )

• data : synonm for lightcurve

• metadict, the metadata; synonym for self.lightcurve.meta, or None if the lightcurve data isn’t loaded

  (access the lightcurve property to force it to load)

Instantiate a lightcurve.

Lightcurve file schema are defined here:

https://github.com/Roman-Supernova-PIT/Roman-Supernova-PIT/wiki/lightcurve

Inside the instantiated Lightcurve object, the lightcurve is stored as an astropy QTable that may be accessed via the lightcurve property of the Lightcurve object.

FOR LIGHTCURVE FILES THAT WILL BE SAVED TO THE DATABASE: Data can only have a single band.

idUUID or str or None

ID of this lightcurve. If None, one will be generated, and thereafter available in the id property.

filepathPath or str, default None

File path to find the lightcurve, relative to base_dir. You must specify either filepath, or both data and meta.

base_pathPath or str, default None

Base directory that filepath is relative to. If None, will use the config value of “system.paths.lightcurves”.

datadict, astropy.table.Table, astropy.table.QTable, or pandas.DataFrame, default None

The data. It must have the following columns, in order, as its first columns; additional columns after that are allowed.

• mjd : float (MJD in days of this lightcurve point)

• flux : float (DN/s in the transient at this point)

• flux_err : float (uncertainty on flux)

• zpt : float (mag_ab = -2.5*log10(flux) + zpt)

• NEA : float (Noise-equivalent area in pixels²)

• sky_rms : float (sky noise level, not including galaxy, at this image position in DN/s)

• observation_id : str (the observation id of the exposure)

• sca : int (the SCA of this image)

• pix_x : float (The 0-offset position of the SN on the detector)

• pix_y : float (The 0-offset position of the SN on the detector)

If multiband is true, then there needs to be a column band (string) after mjd.

If a dict, must be a dict of lists. The keys of the dict are the columns; they will be sorted as listed above. There is no guarantee as to the sorting of additional columns after the required ones.

metadict

Lightcurve metadata. Requires the following keys; can have additional keys in addition to this metadata.

• provenance_id : str or UUID (provenance of this lightcuve)

• diaobject_id : str or UUID (SN this is a lightcurve for)

• diaobject_position_id : str or UUID (ID of the position in the database used*)

• iau_name : str or None (TNS/IAU name of this SN)

• band : string (only required if multiband is False, otherwise prohibited)

• ra : float (RA used for forced photometry / scene modelling for this lightcurve)

• ra_err : float (uncertainty on RA)

• dec : float (dec used for forced photometry /scene modelling for this lightcurve)

• dec_err : float (uncertainty on dec)

• ra_dec_covar : float (covariance between ra and dec)

• local_surface_brightness_{band} : float (galaxy surface brightiness in DN/sec/pixel)

There must be a local_surface_brightness_{band} for every band that shows up in the data.

iau_name, ra_err, dec_err, and ra_dec_covar may be None.

NEA isn’t supposed to be None, but may be in the short term.

If diaobject_position_id is None, it means that the lightcurve used the intial object position pulled from the diaobject, or got its position somewhere else that is not adequately tracked.

If the lightcurve is not intended to be saved to the database, provenance_id and diaobject_id may be none, otherwise they are requried.

multibandbool, default False

Lightcurves as saved in the database are stored one band at a time. However, you can write lightcurves that have all the bands mixed together if you wish.

If a lightcurve is going to be saved to the databse, then multiband must be False.

If multiband is True, then:

• The “band” metadata field is no longer required (and probably shouldn’t be there)

• There is a required string column “band” after “mjd” in the data

Attributes Summary

data
filename_extensions
lightcurve
meta

Methods Summary

find_lightcurves([diaobject, provenance, ...])	Find lightcurves for an object.
generate_filepath([filetype])	Classes that have default filepaths should override this function to set self._filepath.
get_by_id(lightcurve_id[, dbclient])	Get a lightcurve from its ID.
get_combined_lightcurve(diaobject[, ...])	Return a lightcurve combining together all bands that are available.
read([base_dir, filepath])	Reads the lightcurve from its filepath.
save_to_db([dbclient])	Write the existence of this file to the database.
write([base_dir, filepath, filetype, overwrite])	Save the lightcurve to a parquet file.

Attributes Documentation

data

filename_extensions = {'ecsv': '.ecsv', 'parquet': '.parquet'}

lightcurve

meta

Methods Documentation

classmethod find_lightcurves(diaobject=None, provenance=None, provenance_tag=None, process=None, dbclient=None, **kwargs)

Find lightcurves for an object.

You may get back multiple lightcurves if you don’t specify a band.

If what you want is the combined lightcurve for all bands, call get_combined_lightcurve.

Parameters:

• diaobject (DiaObject or UUID or str) – The DiaObject, or the id of the DiaObject, whose lightcurve you want.

• provenance (Provenance or UUID or str, default None) – The Provenance, or the id of the Provenacne, of the lightcurve you want. You must pass either provenance or provenance_tag. (If you pass both, provenance_tag will be ignored).

• provenance_tag (str, default None) – The provenance tag used to find the provenance of the lightcurves you want. Ignored if provenance is not None. Requires process.

• process (str, default None) – The process used together with provenance_tag to find the provenance of the lightcurves you want. Required if provenance_tag is not None.

• band (str, default None) – If given only return the lightcurve for this band. Otherwise, return all available bands.

• dbclient (SNPITDBClient, default None) – The connection to the database web server. If None, a new one will be made that logs you in using the information in Config.

Return type:

List of Lightcurve

generate_filepath(filetype='parquet')

Classes that have default filepaths should override this function to set self._filepath.

classmethod get_by_id(lightcurve_id, dbclient=None)

Get a lightcurve from its ID.

classmethod get_combined_lightcurve(diaobject, provenance=None, provenance_tag=None, process=None, dbclient=None)

Return a lightcurve combining together all bands that are available.

Will raise exceptions if the various lightcurves it’s trying to combine aren’t all self-consistent. (In that case, it means that we did something wrong in generating those files.)

WARNING : after calling this, do NOT save it to the database. You can write the file with write().

read(base_dir=None, filepath=None)

Reads the lightcurve from its filepath.

save_to_db(dbclient=None)

Write the existence of this file to the database.

Note that the database does not store the actual lightcurve files! You must call write() first.

Parameters:

dbclient (SNPITDBClient, default None) – The connection to the database web server. If None, a new one will be made that logs you in using the information in Config.

write(base_dir=None, filepath=None, filetype='parquet', overwrite=False)

Save the lightcurve to a parquet file.

To save it to the database, you must also call save_to_db after calling this function.

After calling this function, the object’s property filepath will be set with the output file’s path relative to base_dir.

Parameters:

• base_dir (str or pathlib.Path, default None) – The base directory where lightcurves are saved. If None, this will use the one set when the Lightcurve was instantiated.

• filepath (str or pathlib.Path, default None) –

  The path relative to base_dir to write the file. If None, the path will be constructed as

  {provid}/{i0}/{i1}/{i2}/{id}.ltcv.parquet

  where {provid} is the provenance id of the lightcurve, {id} is the id of the lightcurve, and {id[012]} are the first three characters of the id of the lightcurve. (This is done so that no directory will have too many files; filesystems used on HPC clusters often do not want to have too many files in one directory.)

• filetype (str, default "parquet") – Must be either “parquet” or “ecsv”. “parquet” is the standard for the SN PIT.

• overwrite (bool, default False) – If the file already exists, raise an Exception, unless this is True, in which case overwrite the existing file.