cobtools.data_models package

Submodules

cobtools.data_models.gaia module

Data model for the Gaia archive.

This module provides data classes for representing and validating Gaia-specific identifiers and related data.

Classes

SourceID: A data class representing a Gaia source ID.

class cobtools.data_models.gaia.SourceID(source_id: int | str, data_release: str = 'dr3')[source]

Bases: object

Data class representing a Gaia source_id.

Parameters:

source_id (Union[int, str]) – The Gaia source_id provided to the constructor. It may be given as an integer or as a string representing an integer; it will be normalized to an integer during initialization.
data_release (str, optional) – The data release to which the source_id belongs. Defaults to “dr3”.

source_id

The normalized Gaia source_id stored on the instance as an integer.

Type:: int

data_release

The validated data release associated with the source_id.

Type:: str

Raises:

ValueError – If source_id is a float or if it cannot be converted to an integer.
ValueError – If data_release is not one of the valid options (“dr1”, “dr2”, “edr3”, “dr3”, “dr4”, “dr5”).

data_release: str = 'dr3'

property designation: str

The Gaia source designation string, which is derived from the source_id and data_release.

Returns:: The Gaia source designation string.
Return type:: str

source_id: int | str

cobtools.data_models.band module

class cobtools.data_models.band.Band(name: str)[source]

Bases: object

name: str

property system: str: Return the photometric system for this band.

property w_eff: float: Return the effective wavelength for this band in Angstroms.

property zp_flam: float: Return the zero-point flux for this band in erg/s/cm^2/AA.

property zp_mag: float: Return the zero-point magnitude for this band.

cobtools.data_models.light_curve module

A data model for light curves.

Classes

LightCurve: A data class representing a light curve, which consists of time-series data for flux measurements and their associated uncertainties. The class includes methods for rebinning the light curve into fixed time intervals and for folding the light curve on a specified period.

Bases: object

A data class representing a light curve.

Parameters:

time_axis (ArrayLike) – An array of time values in an appropriate time unit (e.g., MJD, JD, seconds). Must contain at least one data point.
flux (ArrayLike) – Fluxes corresponding to the time axis.
flux_err (ArrayLike) – The corresponding uncertainties on the fluxes.

time_axis

An array of time values in an appropriate time unit (e.g., MJD, JD, seconds).

Type:: numpy.ndarray

flux

Fluxes corresponding to the time axis.

Type:: numpy.ndarray

flux_err

The corresponding uncertainties on the fluxes.

Type:: numpy.ndarray

rebin(bin_size: float)[source]: Rebin light curve into time bins of fixed intervals (even binning). This method modifies the light curve in place.

fold(period: float) → 'LightCurve'[source]: Fold the light curve on a given period and return a new LightCurve instance with the folded data.

Raises:: ValueError – If the time_axis is empty or if the lengths of time_axis, flux, and flux_err do not match.

flux: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]

flux_err: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]

fold(period: float) → LightCurve[source]

Fold the light curve on a given period.

Parameters:

(float) (period)
time_axis. (should be the same as that of the)

Returns:

folded_time (numpy.ndarray) (Time values folded on the period.)
folded_flux (numpy.ndarray) (Corresponding flux values.)
folded_flux_err (numpy.ndarray) (Corresponding flux error values.)

Raises:

ValueError – If the period is not a positive number.

Example

from cobtools.data_models.light_curve import LightCurve
import numpy as np
# Create a sample light curve
time_axis = np.arange(0, 10, 0.1)
period = 3.0
flux = 10 + 2 * np.sin(2 * np.pi * time_axis
/ period)
flux_err = 0.5 * np.ones_like(flux)
lc = LightCurve(time_axis=time_axis, flux=flux, flux_err=flux_err)
# Fold the light curve on the period
folded_lc = lc.fold(period=period)

rebin(bin_size: float | None) → None[source]

Regroup light curve data into bins of fixed time intervals.

Parameters:: bin_size (Optional[float]) – Size of each time bin. The unit should be the same as that of the time_axis. If None, no rebinning is performed.
Returns:: None
Return type:: This method modifies the light curve in place.
Raises:: ValueError – If the bin_size is not positive or if the time_axis is empty.

Example

from cobtools.data_models.light_curve import LightCurve
import numpy as np

# Create a sample light curve
time_axis = np.arange(0, 10, 0.1)
period = 3.0
flux = 10 + 2 * np.sin(2 * np.pi * time_axis / period)
flux_err = 0.5 * np.ones_like(flux)
lc = LightCurve(time_axis=time_axis, flux=flux, flux_err=flux_err)
# Rebin the light curve into 0.5 time units
lc.rebin(bin_size=0.5)

time_axis: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str]

cobtools.data_models.lsst module

Data models defined for the Vera C. Rubin Observatory’s Legacy Survey of Space and Time (LSST, hereafter) data. For more information, see the Rubin/LSST Alert Product Data Schema.

Classes

DiaSource: A data class representing a single diaSource entry from the LSST product. A DiaSource (Difference Image Analysis Source) is a detection on a difference image.
DiaForcedSource: A data class representing a single diaForcedSource entry from the LSST product. A DiaForcedSource is a forced photometry measurement at a known position on a difference image.
DiaObject: A data class representing a single diaObject entry from the LSST product. A DiaObject is a cataloged astrophysical object that has been identified as variable or transient based on time-series analysis of difference images.

class cobtools.data_models.lsst.DiaForcedSource(midpointMjdTai: float | None = None, band: str | None = None, psfFlux: float | None = None, psfFluxErr: float | None = None)[source]

Bases: object

Data class representing a single diaForcedSource entry from the LSST product.

Parameters:

midpointMjdTai (float, optional) – Midpoint of the exposure in Modified Julian Date, in the TAI time standard. Defaults to None.
band (str, optional) – Photometric band of the observation. Defaults to None.
psfFlux (float, optional) – PSF-fit flux measured for the source on the difference image. Defaults to None.
psfFluxErr (float, optional) – Uncertainty on the PSF-fit flux measurement. Defaults to None.

midpointMjdTai

Midpoint of the exposure in Modified Julian Date, in the TAI time standard.

Type:: float or None

band

Photometric band of the observation.

Type:: str or None

psfFlux

PSF-fit flux measured for the source on the difference image.

Type:: float or None

psfFluxErr

Uncertainty on the PSF-fit flux measurement.

Type:: float or None

band: str | None = None

midpointMjdTai: float | None = None

psfFlux: float | None = None

psfFluxErr: float | None = None

Bases: object

Data class representing a single diaObject entry from the LSST product.

Parameters:

diaObjectId (int, optional) – Unique identifier for the diaObject record.
ra (float, optional) – Right Ascension of the object in degrees. Defaults to None.
decl (float, optional) – Declination of the object in degrees. Defaults to None.
firstDiaSourceMjdTai (float, optional) – Modified Julian Date (TAI) of the first associated diaSource detection. Defaults to None.
lastDiaSourceMjdTai (float, optional) – Modified Julian Date (TAI) of the last associated diaSource detection. Defaults to None.

diaObjectId

Unique identifier for the diaObject record.

Type:: int or None

ra

Right Ascension of the object in degrees.

Type:: float or None

decl

Declination of the object in degrees.

Type:: float or None

firstDiaSourceMjdTai

Modified Julian Date (TAI) of the first associated diaSource detection.

Type:: float or None

lastDiaSourceMjdTai

Modified Julian Date (TAI) of the last associated diaSource detection.

Type:: float or None

decl: float | None = None

diaObjectId: int | None = None

firstDiaSourceMjdTai: float | None = None

lastDiaSourceMjdTai: float | None = None

ra: float | None = None

Bases: object

Data class representing a single diaSource entry from the LSST product.

A DiaSource (Difference Image Analysis Source) is a single detection on a difference image.

Parameters:

diaSourceId (int, optional) – Unique identifier for the diaSource record. Defaults to None.
midpointMjdTai (float, optional) – Midpoint of the exposure in Modified Julian Date, in the TAI time standard. Defaults to None.
band (str, optional) – Photometric band of the observation. Defaults to None.
psfFlux (float, optional) – PSF-fit flux measured for the source on the difference image. Defaults to None.
psfFluxErr (float, optional) – Uncertainty on the PSF-fit flux measurement. Defaults to None.
reliability (float, optional) – Reliability score associated with the detection. Defaults to None.

diaSourceId

Unique identifier for the diaSource record.

Type:: int or None

midpointMjdTai

Midpoint of the exposure in Modified Julian Date, in the TAI time standard.

Type:: float or None

band

Photometric band of the observation.

Type:: str or None

psfFlux

PSF-fit flux measured for the source on the difference image.

Type:: float or None

psfFluxErr

Uncertainty on the PSF-fit flux measurement.

Type:: float or None

reliability

Reliability score associated with the detection.

Type:: float or None

band: str | None = None

diaSourceId: int | None = None

midpointMjdTai: float | None = None

psfFlux: float | None = None

psfFluxErr: float | None = None

reliability: float | None = None

cobtools.data_models.lsst_lasair module

Data models defined for the Lasair data objects. For more information, see the Lasair documentation.

Classes

LasairData: A data class representing a data object from the Lasair database, which includes metadata provided by Lasair. Parameter meaning can be found in the Lasair Schema Browser.
LasairObject: A data class representing a single object from the Lasair database. This class is a wrapper that combines the LSST diaObject and Lasair-derived metadata.

Bases: object

A data class representing a data object from the Lasair database, which includes metadata provided by Lasair. Parameter meaning can be found in the Lasair Schema Browser.

TNS: dict | None = None

annotations: List[dict] | None = None

decsex: float | None = None

discFilter: str | None = None

discMag: float | None = None

discMjd: float | None = None

discUtc: str | None = None

ebv: float | None = None

ec_lat: float | None = None

ec_lon: float | None = None

firstDiaSourceMjdTai: float | None = None

g_lat: float | None = None

g_lon: float | None = None

glat: float | None = None

imageUrls: List[dict] | None = None

lastDiaSourceMjdTai: float | None = None

latestFilter: str | None = None

latestMag: float | None = None

latestMjd: float | None = None

latestUtc: str | None = None

mjdmax_ago: float | None = None

mjdmin_ago: float | None = None

nDiaSources: int | None = None

now_mjd: float | None = None

peakFilter: str | None = None

peakMag: float | None = None

peakMjd: float | None = None

peakUtc: str | None = None

rasex: float | None = None

sherlock: dict | None

class cobtools.data_models.lsst_lasair.LasairObject(diaObjectId: int, lasairData: LasairData, diaObject: DiaObject, diaSourcesList: List[DiaSource], diaForcedSourcesList: List[DiaForcedSource])[source]

Bases: object

A data class representing a single object from the Lasair database. This class is a wrapper that combines the LSST diaObject and Lasair-derived metadata. It is mainly designed to parse the data retrieved from the Lasair API, which is a nested dictionary. It includes methods for retrieving the light curve data as a pandas DataFrame or as a LightCurve instance.

Parameters:

diaObjectId (int) – Unique identifier for the diaObject record.
lasairData (LasairData) – Metadata provided by Lasair for the object.
diaObject (DiaObject) – The diaObject record from the LSST product, containing basic information about the object.
diaSourcesList (List[DiaSource]) – A list of diaSource records associated with the object, representing individual detections on difference images.
diaForcedSourcesList (List[DiaForcedSource]) – A list of diaForcedSource records associated with the object, representing forced photometry measurements at the object’s position on difference images.

info() → str[source]: Return a human-readable string summarizing the key information about the LasairObject.

get_lightcurve_df(option: str, band: str) → pd.DataFrame[source]: Retrieve the light curve data as a pandas DataFrame. The option parameter specifies whether to use ‘diaSources’ or ‘diaForcedSources’ for the light curve data, and the band parameter allows filtering by photometric band.

get_lightcurve(**kwargs) → LightCurve[source]: Retrieve the light curve data as a LightCurve instance. This method internally calls get_lightcurve_df to get the data and then constructs a LightCurve instance from it.

image_urls(img_type: str, band: str) → List[str][source]: Retrieve the URLs of images associated with the Lasair object for a specific band and image type (Science, Template, or Difference).

to_json(file_path: str | Path) → None[source]: Save the LasairObject instance to a JSON file at the specified path.

diaForcedSourcesList: List[DiaForcedSource]

diaObject: DiaObject

diaObjectId: int

diaSourcesList: List[DiaSource]

classmethod from_api_data(data: dict) → LasairObject[source]

Create a LasairObject instance from a nested dictionary retrieved from the Lasair API.

Parameters:: data (dict) – The nested dictionary containing the data for a single object as retrieved from the Lasair API.
Returns:: An instance of LasairObject populated with the data from the API.
Return type:: LasairObject
Raises:: TypeError – If the input data does not contain the required fields or if the data format is incompatible with the expected dataclass fields.

Example

# Example use of LasairObject to parse the nested dictionary from
# the Lasair API
from lasair import lasair_client as lasair
from cobtools.data_models.lsst_lasair import LasairObject

L = lasair(
    endpoint="https://api.lasair.lsst.ac.uk/api",
    token="your_api_token"
    )
# Replace objectId with a valid diaObjectId

api_data = L.object(objectId)
lasair_object = LasairObject.from_api_data(api_data)

get_lightcurve(**kwargs) → LightCurve[source]

Get the light curve data as a LightCurve instance.

Parameters:: **kwargs – Keyword arguments to be passed to get_lightcurve_df.
Returns:: LightCurve instance containing the light curve data for the object. More details can be found in the documentation of the LightCurve class in cobtools.data_models.light_curve.
Return type:: LightCurve

get_lightcurve_df(option: str | None = 'diaSources', band: str | None = 'all') → DataFrame[source]

Retrieve the light curve data as a pandas DataFrame.

Parameters:

option (str, optional) – The type of sources to include in the light curve. Choose ‘diaSources’ or ‘diaForcedSources’.
band (str, optional) – The band to filter the data by. Choose ‘all’, ‘u’, ‘g’, ‘r’, ‘i’, ‘z’, or ‘y’.

Returns:

A DataFrame containing the light curve data.

Return type:

pd.DataFrame

Raises:

ValueError – If the option parameter is not ‘diaSources’ or ‘diaForcedSources’, or if the band parameter is not one of the allowed values.

Example

# Get light curve as a DataFrame
# Assuming `lasair_object` is an instance of LasairObject
lc_df = lasair_object.get_lightcurve_df(
    option="diaSources", band="g"
)

image_urls(img_type: str, band: str) → List[str][source]

Retrieve the URLs of images associated with the Lasair object for a specific band. Each image is associated with a diaSource in the specified band.

Parameters:

img_type (str) – The type of image to retrieve. Choose ‘Science’, ‘Template’, or “Difference”. Case-insensitive.
band (str) – The band for which to retrieve image URLs. Choose ‘u’, ‘g’, ‘r’, ‘i’, ‘z’, ‘y’, or ‘all’ for all bands.

Returns:

A list of image URLs for the specified band and image type.

Return type:

List[str]

info() → str[source]

lasairData: LasairData

to_json(file_path: str | Path) → None[source]

Save the LasairObject instance to a JSON file.

Parameters:: file_path (str or Path) – The path to the JSON file where the LasairObject data will be saved. Could be a string or a pathlib.Path object.

cobtools.data_models package

Submodules

cobtools.data_models.gaia module

Classes

cobtools.data_models.band module

cobtools.data_models.light_curve module

Classes

cobtools.data_models.lsst module

Classes

cobtools.data_models.lsst_lasair module

Classes

Module contents