opticam.analysis.analyzer

Classes

Analyzer

Helper class for analyzing OPTICAM light curves.

Functions

validate_light_curves(light_curves)

Validate the light curves by converting DataFrames to Lightcurve objects and inferring GTIs.

convert_lc_time_to_seconds(lc, t_ref)

Convert the time of a light curve from days to seconds from some reference time.

plot(results[, scale])

Plot the results of some timing analysis. Not intended to be called directly by the user, but rather via

define_yerr(obj)

Determine the y-error for the given object.

get_normalisation_units(norm)

Get the units of the normalisation based on the specified normalisation type.

match_light_curve_times(lc1, lc2)

Match the time columns of two light curves.

intersect_gtis(gti1, gti2)

restrict_to_gti(lc, gti)

Module Contents

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

Helper class for analyzing OPTICAM light curves.

Parameters:

  • out_directory (str)

  • light_curves (Dict[str, stingray.Lightcurve | pandas.DataFrame] | None)

  • prefix (str | None)

  • phot_label (str | None)

  • show_plots (bool)

light_curves
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_light_curves(dt, method='mean')

Rebin the light curves to a desired time resolution using stingray.Lightcurve.rebin().

Parameters

dtQuantity

The desired time resolution for the rebinned light curves. This must be an astropy Quantity with units of time (e.g., astropy.units.s) to ensure correct handling of the time resolution.

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

The rebinning method, by default ‘mean’.

Parameters:

  • dt (astropy.units.quantity.Quantity)

  • method (Literal['mean', 'sum'])

Return type:

None

plot_light_curves(show_gtis=False)

Plot the light curves.

Parameters

show_gtisbool, optional

Whether to highlight the Good Time Intervals on the light curve plot, by default False.

Returns

Figure

The figure containing the light curves.

Parameters:

show_gtis (bool)

Return type:

matplotlib.figure.Figure

phase_fold_light_curves(period)

Phase fold each light curve using the given period.

Parameters

periodQuantity

The period to use for phase folding. This must be an astropy Quantity with units of time (e.g., astropy.units.s) to ensure correct handling of the period.

Returns

Dict[str, NDArray]

The phase folded light curves.

Parameters:

period (astropy.units.quantity.Quantity)

Return type:

Dict[str, numpy.typing.NDArray]

phase_bin_light_curves(period, t0=None, n_bins=10, plot=True, subplot=True, sharey=False)

Phase bin each light curve using the given period.

Parameters

periodQuantity

The period to use for phase binning. This must be an astropy Quantity with units of time (e.g., astropy.units.s) to ensure correct handling of the period.

t0float | None, optional

Time of zero phase, by default None. If None, the first time value in the light curve will be used.

n_binsint, optional

The number of phase bins, by default 10.

plotbool, optional

Whether to plot the phase binned light curves, by default True.

subplotbool, optional

Whether to plot filters in separate subplots, by default True.

shareybool, optional

Whether to render the plot with a common y-axis (useful for directly comparing amplitudes), by default False. Only used if plot=True and subplot=True.

Returns

Dict[str, Dict[str, NDArray]]

The phase binned light curves.

Parameters:

  • period (astropy.units.quantity.Quantity)

  • t0 (float | None)

  • n_bins (int)

  • plot (bool)

  • subplot (bool)

  • sharey (bool)

Return type:

Dict[str, Dict[str, numpy.typing.NDArray]]

compute_power_spectra(norm='frac', scale='linear')

Compute the power spectrum for each light curve using stingray.Powerspectrum. It’s usually a good idea to call the rebin() method to rebin your light curves to a regular time grid before calling this method.

Parameters

normLiteral[‘frac’, ‘abs’], optional

The normalisation to use for the power spectrum, by default ‘frac’. If ‘frac’, the power spectrum is normalised to fractional rms. If ‘abs’, the power spectrum is normalised to absolute power.

scaleLiteral[‘linear’, ‘log’, ‘loglog’], optional

The scale to use for the plot, by default ‘linear’. If ‘linear’, all axes are linear. If ‘log’, the frequency axis is logarithmic. If ‘loglog’, both the frequency and power axes are logarithmic.

Returns

Dict[str, Powerspectrum]

A dictionary containing the power spectrum for each light curve, where the keys are the filter names and the values are the power spectra.

Parameters:

  • norm (Literal['frac', 'abs'])

  • scale (Literal['linear', 'log', 'loglog'])

Return type:

Dict[str, stingray.Powerspectrum]

compute_averaged_power_spectra(segment_size, rebin_factor=None, norm='frac', scale='linear')

Compute the averaged power spectrum for each light curve using stingray.AveragedPowerSpectrum. It’s usually a good idea to call the rebin() method to rebin your light curves to a regular time grid before calling this method.

Parameters

segment_sizeQuantity

The size of the segments to use for averaging the power spectra. This must be an astropy Quantity with units of time (e.g., astropy.units.s) to ensure correct handling of the segment size.

rebin_factorfloat | None, optional

The factor by which to rebin the power spectrum in frequency. If ‘None’, no rebinning will be performed. If a float, the power spectrum will be geometrically/logarithmically rebinned with each bin being a factor 1 + rebin_factor larger than the previous one.

normLiteral[‘frac’, ‘abs’], optional

The normalisation to use for the power spectrum, by default ‘frac’. If ‘frac’, the power spectrum is normalised to the fractional rms. If ‘abs’, the power spectrum is normalised to the absolute rms.

scaleLiteral[‘linear’, ‘log’, ‘loglog’], optional

The scale to use for the plot, by default ‘linear’. If ‘linear’, all axes are linear. If ‘log’, the frequency axis is logarithmic. If ‘loglog’, both the frequency and power axes are logarithmic.

Returns

Dict[str, AveragedPowerspectrum]

The averaged power spectrum for each light curve, where the keys are the filter names and the values are the averaged power spectra.

Parameters:

  • segment_size (astropy.units.quantity.Quantity)

  • rebin_factor (float | None)

  • norm (Literal['frac', 'abs'])

  • scale (Literal['linear', 'log', 'loglog'])

Return type:

Dict[str, stingray.AveragedPowerspectrum]

compute_lomb_scargle_periodograms(norm='frac', scale='linear')

Compute the Lomb-Scargle periodogram for each light curve using stingray.LombScarglePowerspectrum.

Parameters

normLiteral[‘abs’, ‘frac’], optional

The normalisation to use for the Lomb-Scargle periodogram, by default ‘frac’. If ‘abs’, the periodogram is normalised to absolute power. If ‘frac’, the periodogram is normalised to fractional rms.

scaleLiteral[‘linear’, ‘log’, ‘loglog’], optional

The scale to use for the inferred frequencies, by default ‘linear’. If ‘linear’, the frequency grid is linearly spaced. If ‘log’, the frequency grid is logarithmically spaced. If ‘loglog’, both the frequency and power axes will be in logarithm. The upper and lower bounds of the frequencies are the same in all cases.

Returns

Tuple[NDArray, Dict[str, NDArray]] | Dict[str, NDArray]

If no frequencies are provided, returns a tuple containing the frequencies and a dictionary of periodograms for each light curve. If frequencies are provided, returns a dictionary of periodogram powers for each light curve.

Parameters:

  • norm (Literal['abs', 'frac'])

  • scale (Literal['linear', 'log', 'loglog'])

Return type:

Dict[str, stingray.lombscargle.LombScarglePowerspectrum]

compute_cross_correlations(mode='same', norm='variance', force_match=True)

Compute the cross-correlations for each pair of light curves using stingray.CrossCorrelation.

Parameters

modeLiteral[‘same’, ‘valid’, ‘full’], optional

The mode to use for the cross-correlation, by default ‘same’. See stingray.CrossCorrelation for details on the different modes.

normLiteral[‘none’, ‘variance’], optional

The normalisation to use for the cross-correlation, by default ‘variance’. See stingray.CrossCorrelation for details on the different normalisations.

force_matchbool, optional

Whether to force the light curves to have the same time columns before computing the cross-correlation, by default True. If False, cross-correlation calculations may fail if the light curves have different time columns.

Returns

Dict[str, CrossCorrelation]

A dictionary containing the cross-correlations for each pair of light curves, where the keys are tuples of filter names and the values are the cross-correlations.

Parameters:

  • mode (Literal['same', 'valid', 'full'])

  • norm (Literal['none', 'variance'])

  • force_match (bool)

Return type:

Dict[str, stingray.CrossCorrelation]

opticam.analysis.analyzer.validate_light_curves(light_curves)

Validate the light curves by converting DataFrames to Lightcurve objects and inferring GTIs.

Parameters

light_curvesDict[str, Lightcurve | DataFrame] | None

The light curves to validate, where the keys are the filter names and the values are either Lightcurve objects or DataFrames containing ‘BMJD’, ‘rel_flux’, and ‘rel_flux_err’ columns. If None, an empty dictionary will be returned.

Returns

Dict[str, Lightcurve]

If light_curves is None, returns an empty dictionary. Otherwise, returns a dictionary containing the validated light curves, where the keys are the filter names and the values are Lightcurve objects.

Parameters:

light_curves (Dict[str, stingray.Lightcurve | pandas.DataFrame] | None)

Return type:

Dict[str, stingray.Lightcurve]

opticam.analysis.analyzer.convert_lc_time_to_seconds(lc, t_ref)

Convert the time of a light curve from days to seconds from some reference time.

Parameters

lcLightcurve

The light curve to convert.

t_reffloat

The reference time.

Returns

Lightcurve

The light curve with time converted to seconds from t_ref.

Parameters:

  • lc (stingray.Lightcurve)

  • t_ref (float)

Return type:

stingray.Lightcurve

opticam.analysis.analyzer.plot(results, scale='linear')

Plot the results of some timing analysis. Not intended to be called directly by the user, but rather via various timing methods.

Parameters

results : Dict[str, AveragedPowerspectrum | Powerspectrum | Crossspectrum | AveragedCrossspectrum | LombScarglePowerspectrum | CrossCorrelation]

The timing analysis results, where the keys are the filter names and the values are the results.

scaleLiteral[‘linear’, ‘log’, ‘loglog’], optional

The scale to use for the plot, by default ‘linear’. If ‘linear’, all axes are linear. If ‘log’, the x-axis is logarithmic. If ‘loglog’, both the x- and y-axes are logarithmic.

Returns

Figure

The figure containing the plot.

Parameters:

  • results (Dict[str, stingray.AveragedPowerspectrum | stingray.Powerspectrum | stingray.Crossspectrum | stingray.AveragedCrossspectrum | stingray.lombscargle.LombScarglePowerspectrum | stingray.CrossCorrelation])

  • scale (Literal['linear', 'log', 'loglog'])

Return type:

matplotlib.figure.Figure

opticam.analysis.analyzer.define_yerr(obj)

Determine the y-error for the given object.

Parameters

objAveragedPowerspectrum | Powerspectrum | Crossspectrum | AveragedCrossspectrum | LombScarglePowerspectrum

The object for which to determine the y-error.

Returns

NDArray | None

The y-error array if it exists (and a sufficient number of segments has been averaged), otherwise None.

Parameters:

obj (stingray.AveragedPowerspectrum | stingray.Powerspectrum | stingray.Crossspectrum | stingray.AveragedCrossspectrum | stingray.lombscargle.LombScarglePowerspectrum)

Return type:

numpy.typing.NDArray | None

opticam.analysis.analyzer.get_normalisation_units(norm)

Get the units of the normalisation based on the specified normalisation type.

Parameters

normstr

The normalisation type.

Returns

str

The units of the normalisation.

Raises

ValueError

If the specified normalisation type is invalid.

Parameters:

norm (str)

Return type:

str

opticam.analysis.analyzer.match_light_curve_times(lc1, lc2)

Match the time columns of two light curves.

Parameters

lc1Lightcurve

The first light curve.

lc2Lightcurve

The second light curve.

Returns

Tuple[Lightcurve, Lightcurve]

The two light curves with matched time columns.

Parameters:

  • lc1 (stingray.Lightcurve)

  • lc2 (stingray.Lightcurve)

Return type:

Tuple[stingray.Lightcurve, stingray.Lightcurve]

opticam.analysis.analyzer.intersect_gtis(gti1, gti2)
opticam.analysis.analyzer.restrict_to_gti(lc, gti)