ATK.Models.Lightcurve#

class ATK.Models.Lightcurve[source]#

Bases: Container, DataFrameIOMixin, TableIOMixin, FITSIOMixin

Container for storing time-series photometry. This object stores both data and relevant metadata.

Valid Configurations

A Lightcurve must be initialised with one of the following mutually exclusive forms:

Photometry:

flux and flux_err
mag and mag_err

Time axis:

mjd
phase

Providing both or neither in either group raises a ValueError.

Units

The following attributes are automatically converted to Quantity with a default unit unless one is explictly provided:

mjd - d
mag - mag
mag_err - mag
flux - ct s⁻¹
flux_err - ct s⁻¹
ra - deg
dec - deg
phase - dimensionless

Data Methods

The following Data Methods are supported by Lightcurve - either individually or through DataSet.apply():

crop()
bin()
clip()
fold()
pspec()

Plotting Arguments

The following keyword arguments are accepted when plotting via plot() or open().

bandslist of str, optional

Bands to process and include in figure. Only used

If not provided, all bands are plotted. See here for a list of supported bands in default surveys.

colourslist of str, optional

Colour to give to each band.

If not provided, a default set of colours are used. The following colours are supported: "green", "red", "blue", "orange", "purple", "black".

If bands is None, colours are automatically assigned among all available bands.

cmap{‘mean’, ‘flat’}, optional

Sets the colour map. Only used in unfolded Lightcurves, i.e. when phase is None.

'mean': colour scales with distance from the centre.

'flat': no colour scaling.

Default is 'mean'.

time_format{‘reduced’, ‘original’}, optional

Sets the format of the time axis. Only used in unfolded Lightcurves, i.e. when phase is None.

'reduced': minimum MJD across all available photometry is subtracted. Time axis starts at date of first observation.

'original': time axis is MJD.

Default is 'reduced'.

subtract{‘mean’, ‘mean’, None}, optional

Sets metric used in subtracting (and hence aligning) photometry. E.g. if 'median, y-axis represents change in brightness relative to median. Only used in folded Lightcurves, i.e. when phase is not None.

If None, no photometry subtraction/alignment is performed.

Default is 'median'.

align{‘max’, ‘min’, ‘median’, ‘mean’, None}, optional

Aligns photometry to a chosen feature.

'max': photometry is aligned to begin at a local maximum in modulation.

'min': photometry is aligned to begin at a local minimum in modulation.

'median': photometry is aligned to begin at the median.

'mean': photometry is aligned to begin at the mean.

If None, no phase-alignment is performed.

Default is 'max'.

repeatint, optional

Sets the number of modulations in brightness to display.

Default is 2.

Attributes

`band`	Photometric band of stored data.
`correction`	Achieved degree of proper motion correction.
`dec`	Declination values.
`flux`	Flux values.
`flux_err`	Flux error values.
`fopt`	Fold frequency.
`mag`	Magnitude values.
`mag_err`	Magnitude error values.
`mjd`	Modified Julian Day values.
`obj_id`	Survey-specific object ID.
`phase`	Phase values.
`popt`	Fold period.
`ra`	Right ascension values.
`search_pos`	Position of search at time of execution (i.e. post-correction).
`separation`	Separation between position of the search and the returned data.
`survey`	Survey from which the stored data originates.

Methods

`bin`([bins, size, inplace])	Bins all array-like attributes into a number of bins or a bin size in x (i.e. `mjd` or `phase`).
`clip`(sigma[, sigma_lower, sigma_upper, inplace])	Sigma clips a `Lightcurve` to a given sigma (or range in sigma) in y (i.e. `mag` or `flux`).
`crop`([cmin, cmax, inplace])	Crops all array-like attributes to a given range in x (i.e. `mjd` or `phase`).
`fold`(fmin, fmax, samples[, optimise, freq, ...])	Phase-folds the `Lightcurve` curve onto the best frequency over a range of trial frequencies, or a fixed frequency.
`from_dataframe`(target, data, **kwargs)	Construct a `Lightcurve` from a `DataFrame`.
`from_table`(target, data, **kwargs)	Construct a `Lightcurve` from a `Table`.
`pspec`(fmin, fmax, samples)	Generates a `Powspec` (power spectrum) using `astropy.timeseries.LombScargle` over a range of trial frequencies.
`show`([show_types, show_all])	Prints structure to stdout in a human-readable format.
`to_dataframe`()	Combines all array-like attributes of a structure into a `DataFrame`.
`to_hdu`()	Converts structure into a FITS `BinTableHDU`.
`to_table`()	Combines all array-like attributes of a structure into a `Table`, preserving units.

Attribute Descriptions

band: str | None = None#: Photometric band of stored data.

correction: str | None = None#

Achieved degree of proper motion correction.

'full' = complete 3-dimensional projection on the sky.
'partial' = 2-dimensional plane projection.
'none' = no correction.

dec: Quantity | None = None#

Declination values.

None unless light curve has been folded with fold().

flux: Quantity | None = None#: Flux values. Mutually exclusive with mag.

flux_err: Quantity | None = None#: Flux error values. Mutually exclusive with mag_err.

fopt: Quantity | None = None#

Fold frequency.

Only relevant in folded light curves (i.e. when phase is not None).

mag: Quantity | None = None#: Magnitude values. Mutually exclusive with flux.

mag_err: Quantity | None = None#: Magnitude error values. Mutually exclusive with flux_err.

mjd: Quantity | None = None#: Modified Julian Day values. Mutually exclusive with phase.

obj_id: str | None = None#

Survey-specific object ID.

Set when performing light curve queries with split = True.

phase: Quantity | None = None#: Phase values. Mutually exclusive with mjd.

popt: Quantity | None = None#

Fold period.

Only relevant in folded light curves (i.e. when phase is not None).

ra: Quantity | None = None#

Right ascension values.

None unless light curve has been folded with fold().

search_pos: SkyCoord | None = None#: Position of search at time of execution (i.e. post-correction).

separation: Quantity | None = None#: Separation between position of the search and the returned data.

survey: str | None = None#: Survey from which the stored data originates.

Method Descriptions

bin(bins: int | None = None, size: Quantity | float | None = None, inplace=True) → Self[source]#

Bins all array-like attributes into a number of bins or a bin size in x (i.e. mjd or phase).

Exactly one of bin or size must be provided.

Parameters:

binsint, optional: Number of bins in which to bin data.
sizefloat or Quantity, optional: Size of each bin in which to bin data. If a Unit is not provided, size is assumed to be in the same unit as x.
inplacebool, optional: If True, modify the current Lightcurve inplace. If False, operate on and return a copy - leaving the original unchanged.

Returns:

Self: The binned Lightcurve. Returns self if inplace=True, otherwise returns a new instance.

clip(sigma: float, sigma_lower: float | None = None, sigma_upper: float | None = None, inplace: bool = False) → Self[source]#

Sigma clips a Lightcurve to a given sigma (or range in sigma) in y (i.e. mag or flux).

This method utilises astropy.stats.sigma_clip(), see the Astropy documentation for details.

Parameters:

sigmafloat: Number of standard deviations to use for clipping.
sigma_lowerfloat or None, optional: Lower bound for clipping. If None, defaults to sigma.
sigma_upperfloat or None, optional: Upper bound for clipping. If None, defaults to sigma.
inplacebool, optional: If True, modify the current Lightcurve inplace. If False, operate on and return a copy - leaving the original unchanged.

Returns:

Self: The clipped Lightcurve. Returns self if inplace=True, otherwise returns a new instance.

crop(cmin: float | Quantity | None = None, cmax: float | Quantity | None = None, inplace: bool = True) → Self[source]#

Crops all array-like attributes to a given range in x (i.e. mjd or phase).

At least one of cmin, cmax must be provided.

Parameters:

cminfloat or Quantity, optional

Minimum x value. If not provided, bottom range is not clipped.

If a Unit is not provided, cmin is assumed to be in the same unit as x.

cmaxfloat or Quantity, optional.

Maximum x value. If not provided, top range is not clipped.

If a Unit is not provided, cmax is assumed to be in the same unit as x.

inplacebool, optional

If True, modify the current Lightcurve inplace. If False, operate on and return a copy - leaving the original unchanged.

Returns:

Self: The cropped Lightcurve. Returns self if inplace=True, otherwise returns a new instance.

fold(fmin: float | Quantity, fmax: float | Quantity, samples: int, optimise: bool = True, freq: float | Quantity | None = None, inplace: bool = True) → Self[source]#

Phase-folds the Lightcurve curve onto the best frequency over a range of trial frequencies, or a fixed frequency.

Parameters:

fminfloat or Quantity, optional

Minimum frequency.

If a Quantity is not provided, fmin is assumed to be in \(\mathrm{days}^{-1}\).

fmaxfloat or Quantity, optional

Maximum frequency.

If a Quantity is not provided, fmax is assumed to be in \(\mathrm{days}^{-1}\).

samplesint, optional

Number of samples in the frequency range defined by fmin and fmax.

optimisebool, optional

If True, a phase-dispersion metric is calculated for a set of harmonics either side of the peak frequency, and the best is chosen. This can help to preserve real periodic structure, especially in the case of asymmetric modulation.

freqfloat or Quantity, optional

Specific frequency on which to fold the Lightcurve. If provided, this overrides fmin, fmax, and samples.

If a Quantity is not provided, freq is assumed to be in \(\mathrm{days}^{-1}\).

inplacebool, optional

If True, modify the current Lightcurve in place - leaving the original unchanged. If False, operate on and return a copy.

Returns:

Self: The folded Lightcurve, with fopt and popt set to the folded frequency and folded period, respectively. Returns self if inplace=True, otherwise returns a new instance.

classmethod from_dataframe(target, data, **kwargs)#

Construct a Lightcurve from a DataFrame.

Parameters:

targetTarget, int, or SkyCoord

Astronomical target with which to associate input data.

Can be a Target, a Gaia Source ID (int), or a SkyCoord.

dataDataFrame

Tabular data containing the relevant fields (i.e. array-like attributes) required to construct a Lightcurve. Units are assumed to be as listed above.

**kwargs

Additional keyword arguments to be forwarded to the internal parser.

The following keyword arguments are required: survey, band

Returns:

Lightcurve

classmethod from_table(target, data, **kwargs)#

Construct a Lightcurve from a Table.

Parameters:

targetTarget, int, or SkyCoord

Astronomical target with which to associate input data.

Can be a Target, a Gaia Source ID (int), or a SkyCoord.

dataTable

Tabular data containing the relevant fields (i.e. array-like attributes) required to construct a Lightcurve. Units are taken from the table where available, with missing units assumed to be those listed above.

**kwargs

Additional keyword arguments to be forwarded to the internal parser.

The following keyword arguments are required: survey, band

Returns:

Lightcurve

pspec(fmin: float | Quantity, fmax: float | Quantity, samples: int) → Powspec[source]#

Generates a Powspec (power spectrum) using astropy.timeseries.LombScargle over a range of trial frequencies.

Parameters:

fminfloat | Quantity

Minimum frequency.

If a Unit is not provided, fmin is assumed to be in \(\mathrm{days}^{-1}\).

fmaxfloat | Quantity

Maximum frequency.

If a Unit is not provided, fmax is assumed to be in \(\mathrm{days}^{-1}\).

samples: int

Number of samples in frequency range defined by fmin and fmax.

Returns:

Powspec

show(show_types=False, show_all=False)#

Prints structure to stdout in a human-readable format.

Parameters:

show_typesbool, optional

If True, print data types of structure attributes.

Default is False

show_allbool, optional

If True, do not truncate printing of large iterables.

Default is False.

Returns:

self

to_dataframe()#

Combines all array-like attributes of a structure into a DataFrame.

Units are not preserved.

Returns:

DataFrame

to_hdu() → BinTableHDU#

Converts structure into a FITS BinTableHDU.

Returns:

BinTableHDU

to_table()#

Combines all array-like attributes of a structure into a Table, preserving units.

Returns:

Table