opticam.analysis.analyzer ========================= .. py:module:: opticam.analysis.analyzer Classes ------- .. autoapisummary:: opticam.analysis.analyzer.Analyzer Functions --------- .. autoapisummary:: opticam.analysis.analyzer.validate_light_curves opticam.analysis.analyzer.convert_lc_time_to_seconds opticam.analysis.analyzer.plot opticam.analysis.analyzer.define_yerr opticam.analysis.analyzer.get_normalisation_units opticam.analysis.analyzer.match_light_curve_times opticam.analysis.analyzer.intersect_gtis opticam.analysis.analyzer.restrict_to_gti Module Contents --------------- .. py:class:: Analyzer(out_directory, light_curves = None, prefix = None, phot_label = None, show_plots = True) Helper class for analyzing OPTICAM light curves. .. py:attribute:: light_curves .. py:attribute:: out_directory .. py:attribute:: prefix :value: None .. py:attribute:: phot_label :value: None .. py:attribute:: show_plots :value: True .. py:method:: 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 ---------- analyzer : Analyzer The analyzer instance being combined with the current one. Returns ------- Analyzer A new `Analyzer` instance with the combined light curves. .. py:method:: rebin_light_curves(dt, method = 'mean') Rebin the light curves to a desired time resolution using `stingray.Lightcurve.rebin()`. Parameters ---------- dt : Quantity 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. method : Literal['mean', 'sum'], optional The rebinning method, by default `'mean'`. .. py:method:: plot_light_curves(show_gtis = False) Plot the light curves. Parameters ---------- show_gtis : bool, optional Whether to highlight the Good Time Intervals on the light curve plot, by default `False`. Returns ------- Figure The figure containing the light curves. .. py:method:: phase_fold_light_curves(period) Phase fold each light curve using the given period. Parameters ---------- period : Quantity 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. .. py:method:: 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 ---------- period : Quantity 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. t0 : float | None, optional Time of zero phase, by default `None`. If `None`, the first time value in the light curve will be used. n_bins : int, optional The number of phase bins, by default 10. plot : bool, optional Whether to plot the phase binned light curves, by default True. subplot : bool, optional Whether to plot filters in separate subplots, by default True. sharey : bool, 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. .. py:method:: 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 ---------- norm : Literal['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. scale : Literal['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. .. py:method:: 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_size : Quantity 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_factor : float | 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. norm : Literal['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. scale : Literal['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. .. py:method:: compute_lomb_scargle_periodograms(norm = 'frac', scale = 'linear') Compute the Lomb-Scargle periodogram for each light curve using `stingray.LombScarglePowerspectrum`. Parameters ---------- norm : Literal['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. scale : Literal['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. .. py:method:: compute_cross_correlations(mode = 'same', norm = 'variance', force_match = True) Compute the cross-correlations for each pair of light curves using `stingray.CrossCorrelation`. Parameters ---------- mode : Literal['same', 'valid', 'full'], optional The mode to use for the cross-correlation, by default 'same'. See `stingray.CrossCorrelation` for details on the different modes. norm : Literal['none', 'variance'], optional The normalisation to use for the cross-correlation, by default 'variance'. See `stingray.CrossCorrelation` for details on the different normalisations. force_match : bool, 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. .. py:function:: validate_light_curves(light_curves) Validate the light curves by converting DataFrames to Lightcurve objects and inferring GTIs. Parameters ---------- light_curves : Dict[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. .. py:function:: convert_lc_time_to_seconds(lc, t_ref) Convert the time of a light curve from days to seconds from some reference time. Parameters ---------- lc : Lightcurve The light curve to convert. t_ref : float The reference time. Returns ------- Lightcurve The light curve with time converted to seconds from `t_ref`. .. py:function:: 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. scale : Literal['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. .. py:function:: define_yerr(obj) Determine the y-error for the given object. Parameters ---------- obj : AveragedPowerspectrum | 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`. .. py:function:: get_normalisation_units(norm) Get the units of the normalisation based on the specified normalisation type. Parameters ---------- norm : str The normalisation type. Returns ------- str The units of the normalisation. Raises ------ ValueError If the specified normalisation type is invalid. .. py:function:: match_light_curve_times(lc1, lc2) Match the time columns of two light curves. Parameters ---------- lc1 : Lightcurve The first light curve. lc2 : Lightcurve The second light curve. Returns ------- Tuple[Lightcurve, Lightcurve] The two light curves with matched time columns. .. py:function:: intersect_gtis(gti1, gti2) .. py:function:: restrict_to_gti(lc, gti)