opticam.analyzer ================ .. py:module:: opticam.analyzer Classes ------- .. autoapisummary:: opticam.analyzer.Analyzer Functions --------- .. autoapisummary:: opticam.analyzer.rebin opticam.analyzer.bin_timeseries opticam.analyzer.bin_table opticam.analyzer.convert_binned_timeseries_to_timeseries opticam.analyzer.aggregate_mean opticam.analyzer.tidy_light_curves opticam.analyzer.validate_light_curves opticam.analyzer.get_norm_factor opticam.analyzer.convert_lc_to_stingray Module Contents --------------- .. py:class:: Analyzer(out_directory, light_curves = None, norm = 'mean', prefix = None, phot_label = None, show_plots = True) Helper class for analyzing OPTICAM light curves. .. py:attribute:: norm :value: 'mean' .. 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(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_size : Quantity The time bin size. method : Literal['mean', 'sum'], optional The type of binning, by default `'mean'`. Returns ------- Analyzer A new `Analyzer` instance containing the binned light curves. .. py:method:: get_lc(key) Return the light curve for a single key. Parameters ---------- key : str The camera:filter key (e.g., "1:g" for camera 1 with a g filter). Returns ------- TimeSeries The light curve for the key. .. py:method:: plot(save = True, return_fig = False) Plot the light curves. Parameters ---------- save : bool, optional Whether to save the plot, by default `True`. return_fig : bool, 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. .. py:method:: fold(period, epoch_time = None, nbins = None, sharey = False, save = True, return_fig = False) Fold the light curves on the given period. Parameters ---------- period : Quantity The period used to fold the light curves. Must have units of time. epoch_time : Time | None, optional The reference time that defines zero phase, by default `None`. If `None`, the first time light curve time value is used. nbins : int | None, optional Bin the folded light curve into this many bins, by default `None`. If `None`, no binning is performed. sharey : bool, optional Whether to share y axes, by default `False`. save : bool, optional Whether to save the figure, by default `True`. return_fig : bool, 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. .. py:method:: lomb_scargle(frequency = None, scale = 'linear', save = True, return_fig = False) Compute the Lomb-Scargle periodogram for each light curve. Parameters ---------- frequency : Quantity | 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. scale : Literal['linear', 'semilogx', 'semilogy', 'loglog'], optional The scale for the resulting plot, by default `'linear'`. save : bool, optional Whether to save the resulting plot, by default `True`. return_fig : bool, 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. .. py:method:: multiband_lomb_scargle(frequency = None, scale = 'linear', save = True, return_fig = False) Compute the multiband Lomb-Scargle periodogram from all light curves. Parameters ---------- frequency : Quantity | 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. scale : Literal['linear', 'semilogx', 'semilogy', 'loglog'], optional The scale for the resulting plot, by default `'linear'`. save : bool, optional Whether to save the resulting plot, by default `True`. return_fig : bool, 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. .. py:method:: 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}. .. py:function:: 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 ---------- method : Literal['mean', 'sum'] The rebinning method. light_curves : Table | TimeSeries | QTable The light curves being rebinned. time_bin_size : Quantity | None, optional The time resolution of the binned light curve, by default `None`. time_bin_start : Time | None The time bin start (useful for ensuring simultaneity between binned time series), by default `None`. nbins : int | 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. .. py:function:: 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 ---------- ts : TimeSeries The time series. aggregate_func : Callable The aggregate function - should propagate error columns correctly. time_bin_size : Quantity The time bin size. time_bin_start : Time | None The time bin start - useful for ensuring simultaneity between binned time series. Returns ------- TimeSeries The binned time series. .. py:function:: bin_table(tbl, aggregate_func, nbins) Bin an `astropy.table.Table` into a specified number of bins. Parameters ---------- tbl : Table The table. aggregate_func : Callable The aggregate function - should propagate error columns correctly. nbins : int The number of bins. Returns ------- Table The binned table. .. py:function:: 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_lc : BinnedTimeSeries The binned time series. gtis : Quantity The "Good Time Intervals" of the time series. Used to mask gaps. Returns ------- TimeSeries The binned time series as an `astropy.timeseries.TimeSeries`. .. py:function:: aggregate_mean(col) Aggregate a column of values using the mean. If the column represents error values, then the propagated error is returned. Parameters ---------- col : MaskedColumn The column values. Returns ------- Quantity | float The aggregated column values. .. py:function:: tidy_light_curves(light_curves) Tidy a light curve table. Groups rows that have the same time value and sorts by time. Parameters ---------- light_curves : TimeSeries The light curve table. Returns ------- TimeSeries The tidied light curve table. .. py:function:: validate_light_curves(light_curves, norm, keys) Validate light curves. This ensures light curves are normalised and groups redundant rows. Parameters ---------- light_curves : TimeSeries | None The light curves. norm : Literal['max', 'mean', 'none'] The normalisation. keys : list[str] The light curve keys. Returns ------- TimeSeries The validated light curves. .. py:function:: get_norm_factor(norm, fluxes) Compute the specified normalisation factor for the given fluxes. Parameters ---------- norm : Literal['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. fluxes : NDArray The light curve fluxes. Returns ------- float The normalisation factor. .. py:function:: convert_lc_to_stingray(lc, key, t_ref) Convert a light curve from an `astropy.timeseries.TimeSeries` instance to a `stingray.Lightcurve` instance. Parameters ---------- lc : TimeSeries The light curve. key : str The camera:filter key. t_ref : Time The reference time. Returns ------- Lightcurve The light curve as a `stingray.Lightcurve` instance.