opticam.analyzer

Classes

Analyzer

Helper class for analyzing OPTICAM light curves.

Functions

rebin(method, light_curves[, time_bin_size, ...])	Rebin an astropy Table or similar to a lower time resolution while propagating errors correctly.
bin_timeseries(ts, aggregate_func, time_bin_size, ...)	Bin an astropy.timeseries.TimeSeries. The resulting astropy.timeseries.BinnedTimeSeries is converted into an
bin_table(tbl, aggregate_func, nbins)	Bin an astropy.table.Table into a specified number of bins.
convert_binned_timeseries_to_timeseries(binned_ts, gtis)	Convert an astropy.timeseries.BinnedTimeSeries into an astropy.timeseries.TimeSeries and apply the "Good Time
aggregate_mean(col)	Aggregate a column of values using the mean. If the column represents error values, then the propagated error
tidy_light_curves(light_curves)	Tidy a light curve table. Groups rows that have the same time value and sorts by time.
validate_light_curves(light_curves, norm, keys)	Validate light curves. This ensures light curves are normalised and groups redundant rows.
get_norm_factor(norm, fluxes)	Compute the specified normalisation factor for the given fluxes.
convert_lc_to_stingray(lc, key, t_ref)	Convert a light curve from an astropy.timeseries.TimeSeries instance to a stingray.Lightcurve instance.

Module Contents

class opticam.analyzer.Analyzer(out_directory, light_curves=None, norm='mean', prefix=None, phot_label=None, show_plots=True)

Helper class for analyzing OPTICAM light curves.

Parameters:

• out_directory (pathlib.Path | str)

• light_curves (astropy.timeseries.TimeSeries | None)

• norm (Literal['max', 'mean', 'none'])

• prefix (str | None)

• phot_label (str | None)

• show_plots (bool)

norm = 'mean'

out_directory

prefix = None

phot_label = None

show_plots = True

join(analyzer)

Combine another Analyzer instance with the current one. If the new Analyzer has light curves with filters that are not present in the current Analyzer, those filters will be added. If the new Analyzer has light curves with filters that are already present in the current Analyzer, those light curves will be merged.

Parameters

analyzerAnalyzer

The analyzer instance being combined with the current one.

Returns

Analyzer

A new Analyzer instance with the combined light curves.

Parameters:

analyzer (Analyzer)

Return type:

Analyzer

rebin(time_bin_size, method='mean')

Rebin the light curves, propagating errors accordingly. Returns a new Analyzer instance containing the binned light curves. Rebinning uses a common reference time to ensure simultaneity between multiple light curves.

Parameters

time_bin_sizeQuantity

The time bin size.

methodLiteral[‘mean’, ‘sum’], optional

The type of binning, by default ‘mean’.

Returns

Analyzer

A new Analyzer instance containing the binned light curves.

Parameters:

• time_bin_size (astropy.units.quantity.Quantity)

• method (Literal['mean'])

Return type:

Analyzer

get_lc(key)

Return the light curve for a single key.

Parameters

keystr

The camera:filter key (e.g., “1:g” for camera 1 with a g filter).

Returns

TimeSeries

The light curve for the key.

Parameters:

key (str)

Return type:

astropy.timeseries.TimeSeries

plot(save=True, return_fig=False)

Plot the light curves.

Parameters

savebool, optional

Whether to save the plot, by default True.

return_figbool, optional

Whether to return the resulting Figure instance, by default False. This can be used to make edits to the plot.

Returns

Figure | None

The figure containing the light curves.

Parameters:

• save (bool)

• return_fig (bool)

Return type:

matplotlib.figure.Figure | None

fold(period, epoch_time=None, nbins=None, sharey=False, save=True, return_fig=False)

Fold the light curves on the given period.

Parameters

periodQuantity

The period used to fold the light curves. Must have units of time.

epoch_timeTime | None, optional

The reference time that defines zero phase, by default None. If None, the first time light curve time value is used.

nbinsint | None, optional

Bin the folded light curve into this many bins, by default None. If None, no binning is performed.

shareybool, optional

Whether to share y axes, by default False.

savebool, optional

Whether to save the figure, by default True.

return_figbool, optional

Whether to return the figure, by default False. Useful if you want to edit the figure before saving.

Returns

Table | tuple[Table, Figure]

If return_fig=True, the folded light curve and resulting figure are returned. Otherwise, just the folded time series is returned. The folded light curve is converted from a TimeSeries to a Table since the fold() method of TimeSeries replaces the time column with phase values, causing time formatting errors.

Parameters:

• period (astropy.units.quantity.Quantity)

• epoch_time (astropy.time.Time | None)

• nbins (int | None)

• sharey (bool)

• save (bool)

• return_fig (bool)

Return type:

astropy.table.Table | tuple[astropy.table.Table, matplotlib.figure.Figure]

lomb_scargle(frequency=None, scale='linear', save=True, return_fig=False)

Compute the Lomb-Scargle periodogram for each light curve.

Parameters

frequencyQuantity | None, optional

The frequency grid, by default None. If None, the autofrequency() method of astropy’s LombScargle class is used to generate a frequency grid.

scaleLiteral['linear', 'semilogx', 'semilogy', 'loglog'], optional

The scale for the resulting plot, by default ‘linear’.

savebool, optional

Whether to save the resulting plot, by default True.

return_figbool, optional

Whether to return the figure, by default False. Useful if you want to edit the figure before saving.

Returns

dict[str, LombScargle] | tuple[dict[str, LombScargle], Figure]

If return_fig=True, the Lomb-Scargle periodograms and figure are returned. Otherwise, only the Lomb-Scargle periodograms are returned.

Parameters:

• frequency (astropy.units.quantity.Quantity | None)

• scale (Literal['linear', 'semilogx', 'semilogy', 'loglog'])

• save (bool)

• return_fig (bool)

Return type:

dict[str, astropy.timeseries.LombScargle] | tuple[dict[str, astropy.timeseries.LombScargle], matplotlib.figure.Figure]

multiband_lomb_scargle(frequency=None, scale='linear', save=True, return_fig=False)

Compute the multiband Lomb-Scargle periodogram from all light curves.

Parameters

frequencyQuantity | None, optional

The frequency grid, by default None. If None, the autofrequency() method of astropy’s LombScargleMultiband class is used to generate a frequency grid.

scaleLiteral['linear', 'semilogx', 'semilogy', 'loglog'], optional

The scale for the resulting plot, by default ‘linear’.

savebool, optional

Whether to save the resulting plot, by default True.

return_figbool, optional

Whether to return the figure, by default False. Useful if you want to edit the figure before saving.

Returns

LombScargleMultiband | tuple[LombScargleMultiband, Figure]

If return_fig=True, the multiband Lomb-Scargle periodogram and figure are returned. Otherwise, only the multiband Lomb-Scargle periodogram is returned.

Parameters:

• frequency (astropy.units.quantity.Quantity | None)

• scale (Literal['linear', 'semilogx', 'semilogy', 'loglog'])

• save (bool)

• return_fig (bool)

Return type:

astropy.timeseries.LombScargleMultiband | tuple[astropy.timeseries.LombScargleMultiband, matplotlib.figure.Figure]

export_light_curves_to_stingray()

Export the light curves from an astropy.timeseries.TimeSeries table to a dictionary of stingray.Lightcurve instances.

Returns

dict[str, Lightcurve]

The light curves {filter: Lightcurve}.

Return type:

dict[str, stingray.Lightcurve]

opticam.analyzer.rebin(method, light_curves, time_bin_size=None, time_bin_start=None, nbins=None)

Rebin an astropy Table or similar to a lower time resolution while propagating errors correctly.

Parameters

methodLiteral['mean', 'sum']

The rebinning method.

light_curvesTable | TimeSeries | QTable

The light curves being rebinned.

time_bin_sizeQuantity | None, optional

The time resolution of the binned light curve, by default None.

time_bin_startTime | None

The time bin start (useful for ensuring simultaneity between binned time series), by default None.

nbinsint | None, optional

The desired number of light curve bins, by default None. This parameter does nothing if time_bin_size is defined.

Returns

Table | TimeSeries | QTable

The rebinned light curve.

Raises

ValueError

If the value passed to method is not recognised.

ValueError

If neither time_bin_size or nbins are defined.

Parameters:

• method (Literal['mean'])

• light_curves (astropy.table.Table | astropy.timeseries.TimeSeries | astropy.table.QTable)

• time_bin_size (astropy.units.quantity.Quantity | None)

• time_bin_start (astropy.time.Time | None)

• nbins (int | None)

Return type:

astropy.table.Table | astropy.timeseries.TimeSeries | astropy.table.QTable

opticam.analyzer.bin_timeseries(ts, aggregate_func, time_bin_size, time_bin_start)

Bin an astropy.timeseries.TimeSeries. The resulting astropy.timeseries.BinnedTimeSeries is converted into an astropy.timeseries.TimeSeries using the time bin centers as the new times. This allows for gaps to be removed from the time series instead of being padded with zeros.

Parameters

tsTimeSeries

The time series.

aggregate_funcCallable

The aggregate function - should propagate error columns correctly.

time_bin_sizeQuantity

The time bin size.

time_bin_startTime | None

The time bin start - useful for ensuring simultaneity between binned time series.

Returns

TimeSeries

The binned time series.

Parameters:

• ts (astropy.timeseries.TimeSeries)

• aggregate_func (Callable)

• time_bin_size (astropy.units.quantity.Quantity)

• time_bin_start (astropy.time.Time | None)

Return type:

astropy.timeseries.TimeSeries

opticam.analyzer.bin_table(tbl, aggregate_func, nbins)

Bin an astropy.table.Table into a specified number of bins.

Parameters

tblTable

The table.

aggregate_funcCallable

The aggregate function - should propagate error columns correctly.

nbinsint

The number of bins.

Returns

Table

The binned table.

Parameters:

• tbl (astropy.table.Table)

• aggregate_func (Callable)

• nbins (int)

Return type:

astropy.table.Table

opticam.analyzer.convert_binned_timeseries_to_timeseries(binned_ts, gtis)

Convert an astropy.timeseries.BinnedTimeSeries into an astropy.timeseries.TimeSeries and apply the “Good Time Intervals”.

Parameters

binned_lcBinnedTimeSeries

The binned time series.

gtisQuantity

The “Good Time Intervals” of the time series. Used to mask gaps.

Returns

TimeSeries

The binned time series as an astropy.timeseries.TimeSeries.

Parameters:

• binned_ts (astropy.timeseries.BinnedTimeSeries)

• gtis (astropy.units.quantity.Quantity)

Return type:

astropy.timeseries.TimeSeries

opticam.analyzer.aggregate_mean(col)

Aggregate a column of values using the mean. If the column represents error values, then the propagated error is returned.

Parameters

colMaskedColumn

The column values.

Returns

Quantity | float

The aggregated column values.

Parameters:

col (astropy.table.MaskedColumn)

Return type:

astropy.units.quantity.Quantity | float

opticam.analyzer.tidy_light_curves(light_curves)

Tidy a light curve table. Groups rows that have the same time value and sorts by time.

Parameters

light_curvesTimeSeries

The light curve table.

Returns

TimeSeries

The tidied light curve table.

Parameters:

light_curves (astropy.timeseries.TimeSeries)

Return type:

astropy.timeseries.TimeSeries

opticam.analyzer.validate_light_curves(light_curves, norm, keys)

Validate light curves. This ensures light curves are normalised and groups redundant rows.

Parameters

light_curvesTimeSeries | None

The light curves.

normLiteral['max', 'mean', 'none']

The normalisation.

keyslist[str]

The light curve keys.

Returns

TimeSeries

The validated light curves.

Parameters:

• light_curves (astropy.timeseries.TimeSeries | None)

• norm (Literal['max', 'mean', 'none'])

• keys (list[str])

Return type:

astropy.timeseries.TimeSeries

opticam.analyzer.get_norm_factor(norm, fluxes)

Compute the specified normalisation factor for the given fluxes.

Parameters

normLiteral[‘max’, ‘mean’, ‘none’], optional

The light curve normalisation. ‘max’ normalises the fluxes to a maximum flux of 1, ‘mean’ normalises the fluxes to a mean flux of 1, and ‘none’ applies no normalisation.

fluxesNDArray

The light curve fluxes.

Returns

float

The normalisation factor.

Parameters:

• norm (Literal['max', 'mean', 'none'])

• fluxes (numpy.typing.NDArray)

Return type:

float

opticam.analyzer.convert_lc_to_stingray(lc, key, t_ref)

Convert a light curve from an astropy.timeseries.TimeSeries instance to a stingray.Lightcurve instance.

Parameters

lcTimeSeries

The light curve.

keystr

The camera:filter key.

t_refTime

The reference time.

Returns

Lightcurve

The light curve as a stingray.Lightcurve instance.

Parameters:

• lc (astropy.timeseries.TimeSeries)

• key (str)

• t_ref (astropy.time.Time)

Return type:

stingray.Lightcurve