opticam_new =========== .. py:module:: opticam_new Submodules ---------- .. toctree:: :maxdepth: 1 /autoapi/opticam_new/analysis/index /autoapi/opticam_new/reduction/index /autoapi/opticam_new/utils/index Classes ------- .. autoapisummary:: opticam_new.DefaultBackground opticam_new.DefaultFinder opticam_new.Catalog opticam_new.DifferentialPhotometer opticam_new.SimplePhotometer opticam_new.OptimalPhotometer opticam_new.DefaultLocalBackground opticam_new.FlatFieldCorrector opticam_new.Analyzer Functions --------- .. autoapisummary:: opticam_new.generate_flats opticam_new.generate_observations opticam_new.generate_gappy_observations Package Contents ---------------- .. py:class:: DefaultBackground(box_size) Default background estimator. .. py:attribute:: box_size .. py:method:: __call__(data) Compute the 2D background for an image. Parameters ---------- data : NDArray Image data. Returns ------- Background2D 2D background. .. py:class:: DefaultFinder(npixels, border_width = 0) Default source finder. Combines image segmentation with source deblending. .. py:attribute:: border_width :value: 0 .. py:attribute:: finder .. py:method:: __call__(data, threshold) .. py:class:: Catalog(out_directory, data_directory = None, c1_directory = None, c2_directory = None, c3_directory = None, rebin_factor = 1, flat_corrector = None, background = None, finder = None, threshold = 5, aperture_selector = np.median, remove_cosmic_rays = True, number_of_processors = cpu_count() // 2, show_plots = True, verbose = True) Create a catalog of sources from OPTICAM data. .. py:attribute:: verbose :value: True .. py:attribute:: out_directory .. py:attribute:: logger .. py:attribute:: data_directory :value: None .. py:attribute:: c1_directory :value: None .. py:attribute:: c2_directory :value: None .. py:attribute:: c3_directory :value: None .. py:attribute:: rebin_factor :value: 1 .. py:attribute:: flat_corrector :value: None .. py:attribute:: aperture_selector .. py:attribute:: threshold :value: 5 .. py:attribute:: remove_cosmic_rays :value: True .. py:attribute:: number_of_processors .. py:attribute:: show_plots :value: True .. py:attribute:: file_paths :value: [] .. py:attribute:: ignored_files :value: [] .. py:attribute:: colours :value: ['tab:blue', 'tab:orange', 'tab:green', 'tab:red', 'tab:purple', 'tab:brown', 'tab:pink',... .. py:attribute:: transforms .. py:attribute:: unaligned_files :value: [] .. py:attribute:: catalogs .. py:attribute:: psf_params .. py:method:: _scan_data_directory() Scan the data directory for files and extract the MJD, filter, binning, and gain from each file header. Raises ------ ValueError If more than 3 filters are found. ValueError If the binning is not consistent. .. py:method:: _get_header_info(file) Get the MJD, filter, binning, and gain from a file header. Parameters ---------- file : str The file path. Returns ------- Tuple[float, str, str, float] The BMJD, filter, binning, and gain dictionaries. Raises ------ KeyError If the file header does not contain the required keys. .. py:method:: _parse_header_results(results) Parse the results returned by self._get_header_info(). Parameters ---------- results : Tuple The results. Returns ------- Tuple[str, str] The filter dictionary (file : filter). Raises ------ ValueError If more than 3 filters are found. ValueError If the binning is not consistent. .. py:method:: _log_parameters() Log any and all object parameters to a JSON file. .. py:method:: _plot_time_between_files() Plot the times between each file for each camera. Parameters ---------- show : bool Whether to display the plot. .. py:method:: _set_psf_params(fltr) Set the PSF parameters for a given filter based on the catalog data. Parameters ---------- fltr : str The filter for which to set the PSF parameters. .. py:method:: _get_data(file, return_error = False) Get data from a file. Parameters ---------- file : str Directory path to file. return_error : bool, optional Whether to return the error array, by default False. Returns ------- NDArray | Tuple[NDArray, NDArray] The data array or the data and error arrays. .. py:method:: _get_source_coords_from_image(image, bkg = None, away_from_edge = False, n_sources = None) Get an array of source coordinates from an image in descending order of source brightness. Parameters ---------- image : NDArray The **non-background-subtracted** image from which to extract source coordinates. bkg : Background2D, optional The background of the image, by default None. If None, the background is estimated from the image. away_from_edge : bool, optional Whether to exclude sources near the edge of the image, by default False. n_sources : int, optional The number of source coordinates to return, by default `None` (all sources will be returned). Returns ------- NDArray The source coordinates in descending order of brightness. .. py:method:: create_catalogs(max_catalog_sources = 50, n_alignment_sources = 3, transform_type = 'translation', rotation_limit = None, translation_limit = None, scale_limit = None, overwrite = False, show_diagnostic_plots = False) Initialise the source catalogs for each camera. Some aspects of this method are parallelised for speed. Parameters ---------- max_catalog_sources : int, optional The maximum number of sources above the specified threshold that will be included in the catalog, by default 50. Only the brightest max_catalog_sources sources are included in the catalog. n_alignment_sources : int, optional The (maximum) number of sources to use for image alignment, by default 3. If `transform_type='translation'`, `n_alignment_sources` must be >= 1, and the brightest `n_alignment_sources` sources are used for image alignment. If `transform_type='affine'`, `n_alignment_sources` must be >= 3 and represents that *maximum* number of sources that *may* be used for image alignment. transform_type : Literal['affine', 'translation'], optional The type of transform to use for image alignment, by default 'translation'. 'translation' performs simple x, y translations, while 'affine' uses `astroalign.find_transform()`. rotation_limit : float, optional The maximum rotation limit (in degrees) for affine transformations, by default `None` (no limit). scale_limit : float, optional The maximum scale limit for affine transformations, by default `None` (no limit). translation_limit : float | Iterable[float], optional The maximum translation limit for transformations, by default `None` (no limit). Can be a scalar value that applies to both x- and y-translations, or an iterable where the first value defines the x-translation limit and the second value defines the y-translation limit. overwrite : bool, optional Whether to overwrite existing catalogs, by default False. show_diagnostic_plots : bool, optional Whether to show diagnostic plots, by default False. Diagnostic plots are saved to out_directory, so this parameter only affects whether the plots are displayed in the console. .. py:method:: _align_images(batch, reference_image_shape, reference_coords, transform_type, rotation_limit, scale_limit, translation_limit, n_alignment_sources) Align an image based on some reference coordinates. Parameters ---------- file: str The file path. reference_image : NDArray The reference image. reference_coords : NDArray The source coordinates in the reference image. transform_type : Literal['affine', 'translation'] The type of transform to use for image alignment. rotation_limit : float | None The maximum rotation limit (in degrees) for image alignment. scale_limit : float | None The maximum scaling limit for image alignment. translation_limit : Iterable[float] | None The maximum translation limit for image alignment. n_alignment_sources : int The (maximum) number of sources to use for image alignment. Returns ------- Tuple[List[float], float, float] The transform parameters, background median, and background RMS. .. py:method:: _valid_transform(file, transform, rotation_limit, scale_limit, translation_limit) Find whether a transform is valid given some transform limits. Parameters ---------- file : str The file being transformed. transform : SimilarityTransform The transform. rotation_limit : float | None The rotation limit. scale_limit : float | None The scale limit. translation_limit : Iterable[float] | None The translation limit. Returns ------- bool Whether the transform is valid. .. py:method:: _parse_alignment_results(results, fltr) Parse the results of image alignment. Parameters ---------- results : Tuple The results. fltr : str The filter. Returns ------- Tuple[NDArray, Dict[str, float], Dict[str, float]]: The stacked image, background medians, and background RMSs. .. py:method:: _plot_background_meshes(stacked_images, show) Plot the background meshes on top of the catalog images. Parameters ---------- stacked_images : Dict[str, NDArray] The stacked images for each camera. show : bool Whether to display the plot. .. py:method:: _visualise_psfs(image, fltr, show) Generate PSF plots for each source in an image. Parameters ---------- image : NDArray The image (not background subtracted). fltr : str The image filter. show: bool Whether to display the plot. .. py:method:: create_gifs(keep_frames = True, overwrite = False) Create alignment gifs for each camera. Some aspects of this method are parallelised for speed. The frames are saved in out_directory/diag/*-band_gif_frames and the GIFs are saved in out_directory/cat. Parameters ---------- keep_frames : bool, optional Whether to save the GIF frames in out_directory/diag, by default True. If False, the frames will be deleted after the GIF is saved. overwrite : bool, optional Whether to overwrite existing GIFs, by default False. .. py:method:: _create_gif_frames(file, fltr) Create a gif frames from a batch of images and save it to the out_directory. Parameters ---------- file : str The list of file names in the batch. fltr : str The filter. .. py:method:: _compile_gif(fltr, keep_frames) Create a gif from the frames saved in out_directory. Parameters ---------- fltr : str The filter. keep_frames : bool Whether to keep the frames after the gif is saved. .. py:method:: photometry(photometer) Perform photometry on the catalogs using the provided photometer. Parameters ---------- photometer : BasePhotometer The photometer. Should be a subclass of `BasePhotometer`, or implement a `compute` method that follows the `BasePhotometer` interface. .. py:method:: _photometry(photometer, source_coords, fltr, file) .. py:method:: identify_gaps(files) Identify gaps in the observation sequence and logs them to log_dir/diag/gaps.txt. Parameters ---------- files : List[str] The list of files for a single filter. .. py:class:: DifferentialPhotometer(out_directory, show_plots = True) Helper class for creating relative light curves from OPTICAM data. .. py:attribute:: out_directory .. py:attribute:: show_plots :value: True .. py:attribute:: filters .. py:attribute:: t_ref .. py:attribute:: catalogs .. py:method:: get_relative_light_curve(fltr, target, comparisons, phot_label, prefix = None, match_other_cameras = False, show_diagnostics = True) Compute the relative light curve for a target source with respect to one or more comparison sources. By default, the relative light curve is computed for a single filter. The relative light curve is saved to out_directory/relative_light_curves. To automatically match the target and comparison sources across the other two filters, set match_other_cameras to True. Note that this can incorrectly match sources, so it is recommended to manually check the results. Parameters ---------- fltr : str The filter to compute the relative light curve for. target : int The catalog ID of the target source. comparisons : int | List[int] The catalog ID(s) of the comparison source(s). phot_label : str The photometry label, used for file reading and labelling. prefix : str, optional The prefix to use when saving the relative light curve (e.g., the target star's name), by default None. match_other_cameras : bool, optional Whether to match the target and comparison(s) IDs to the remaining catalog filters, by default `False`. If `True`, astroalign must be installed. show_diagnostics : bool, optional Whether to show diagnostic plots, by default True. Returns ------- Analyzer An Analyzer object containing the relative light curve(s). .. py:method:: _compute_relative_light_curve(fltr, target, comparisons, prefix, phot_label, show_diagnostics) Compute the relative light curve for a target source with respect to one or more comparison sources for a given filter. Parameters ---------- fltr : str The filter to compute the relative light curve for. target : int The catalog ID of the target source. comparisons : List[int] The catalog ID(s) of the comparison source(s). prefix : str | None The prefix to use when saving the relative light curve (e.g., the target star's name), by default None. phot_label : str The photometry label, used for file reading and labelling. show_diagnostics : bool Whether to show diagnostic plots, by default True. Returns ------- Lightcurve | None The relative light curve for the target source with respect to the comparison sources, or None if the light curve could not be computed. .. py:method:: _plot_relative_light_curve(relative_light_curve, target, comparisons, prefix, fltr, phot_label, ax = None) Plot the relative light curve for a target source with respect to one or more comparison sources for a given filter. Parameters ---------- relative_light_curve : Lightcurve The relative light curve to plot. target : int The catalog ID of the target source. comparisons : List[int] The catalog ID(s) of the comparison source(s). prefix : str | None The prefix to use when saving the relative light curve (e.g., the target star's name), by default None. fltr : str The filter to plot the relative light curve for. phot_label : str The photometry label, used for file reading and labelling. ax : Axes, optional The axes to plot the relative light curve on, by default None. If None, a new figure and axes will be created. .. py:method:: _plot_diag(fltr, comparison1, comparison2, comparison1_df, comparison2_df, phot_label, show) Plot the relative diagnostic light curve for two comparison sources for a given filter. Parameters ---------- fltr : str The filter to compute the relative light curve. comparison1 : int The catalog ID of the first comparison source. comparison2 : int The catalog ID of the second comparison source. comparison1_df : pd.DataFrame The data frame of the first comparison source. comparison2_df : pd.DataFrame The data frame of the second comparison source. pho_label : str The photometry label. t_ref : float The time of the earliest observation (used for plotting the relative light curve in seconds from t_ref). show : bool Whether to show the diagnostic plot. .. py:class:: SimplePhotometer(match_sources = True, source_matching_tolerance = 2.0, local_background_estimator = None) Bases: :py:obj:`BasePhotometer` A simple photometer that provides simple aperture photometry routines with support for local background estimations using annuli. .. py:method:: compute(image, image_err, source_coords, image_coords, psf_params) Compute the simple photometry for the given image using the provided source coordinates and PSF parameters. Parameters ---------- image : NDArray The image. If `local_background_estimator` is undefined, this image will be background subtracted. image_err : NDArray The error in the image. source_coords : NDArray The source coordinates in the catalogue. image_coords : None | NDArray The source coordinates in the image. If `match_sources` is True, this will be used to match sources in the image to sources in the catalogue. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). Returns ------- Dict[str, List] The results of the photometry .. py:method:: compute_aperture_flux(data, error, position, psf_params) Compute the aperture flux of a source in the image. Parameters ---------- data : NDArray The image. error : NDArray The error in the image. position : NDArray The position of the source. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). Returns ------- Tuple[float, float] | Tuple[float, float, float, float] The flux and flux error. If `local_background_estimator` is defined, the background and its error are also returned. .. py:method:: get_position(source_coords, image_coords, source_index, psf_params) Get the position of a source in an image. Parameters ---------- source_coords : NDArray The source coordinates in the catalogue. image_coords : NDArray | None The source coordinates in the image. source_index : int The source index. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). Returns ------- NDArray The source coordinates. .. py:method:: get_closest_source(source_coords, image_coords, source_index, psf_params) Given a source, find the closest source in the catalogue. Parameters ---------- source_coords : NDArray The source coordinates in the catalogue. image_coords : NDArray | None The source coordinates in the image. source_index : int The source index. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). Returns ------- NDArray | None The coordinates of the closest source. .. py:method:: define_results_dict() Define a results dictionary for the photometer depending on whether `local_background_estimator` is defined. Returns ------- Dict[str, List] The results dictionary with keys 'flux', 'flux_error'. If `local_background_estimator` is defined, the dictionary will also contain 'background' and 'background_error'. .. py:method:: pad_results_dict(results) Pad the results dictionary with None values for flux and flux error, and background and background error if `local_background_estimator' is defined. This is used when a source cannot be matched or its position is invalid. Parameters ---------- results : Dict[str, List] The results dictionary to pad. Returns ------- Dict[str, List] The padded results dictionary. .. py:method:: populate_results_dict(results, phot_function, image, image_err, position, psf_params) Populate the results dictionary with the computed flux, flux error, and background (if applicable) using the provided photometry function. Parameters ---------- results : Dict[str, List] The results dictionary to populate. phot_function : Callable The photometry function to use for computing the flux and flux error. This function should take the image, image error, position, and PSF parameters as arguments and return the flux and flux error, and optionally the background and background error if `local_background_estimator` is defined. image : NDArray The image. image_err : NDArray The error in the image. position : NDArray The position of the source in the image. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). Returns ------- Dict[str, List] The updated results dictionary with the computed flux, flux error, and background (if applicable). .. py:class:: OptimalPhotometer(match_sources = True, source_matching_tolerance = 2.0, local_background_estimator = None) Bases: :py:obj:`SimplePhotometer` A photometer that implements the optimal photometry method described in Naylor 1998, MNRAS, 296, 339-346. .. py:method:: compute(image, image_err, source_coords, image_coords, psf_params) Compute the optimal photometry for each source in the image using the method described in Naylor 1998, MNRAS, 296, 339-346. Parameters ---------- image : NDArray The image. If `local_background_estimator` is undefined, this image will be background subtracted. image_err : NDArray The error in the image. source_coords : NDArray The source coordinates in the catalogue. image_coords : None | NDArray The source coordinates in the image. If `match_sources` is True, this will be used to match sources in the image to sources in the catalogue. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). Returns ------- Dict[str, List] The results of the photometry, including 'flux', 'flux_error', and optionally 'background' and 'background_error' if `local_background_estimator` is defined. .. py:method:: compute_optimal_flux(image, error, position, psf_params) Compute the optimal flux of a source in the image as described in Naylor 1998, MNRAS, 296, 339-346. Parameters ---------- image : NDArray The image. error : NDArray The error in the image. position : NDArray The position of the source in the image, given as (y, x) coordinates. psf_params : Dict[str, float] The PSF parameters for the camera used to take the image. This parameter is defined in the catalogue and has the following keys: 'semimajor_sigma' (in pixels), 'semiminor_sigma' (in pixels), and 'orientation' (in *degrees*). Returns ------- Tuple[float, float] | Tuple[float, float, float, float] The flux and flux error. If `local_background_estimator` is defined, the background and its error are also returned. .. py:class:: DefaultLocalBackground(r_in_scale = 5, r_out_scale = 6, sigma_clip = SigmaClip(sigma=3, maxiters=10)) Bases: :py:obj:`BaseLocalBackground` Default local background estimator using an elliptical annulus. .. py:method:: __call__(data, error, position, semimajor_axis, semiminor_axis = None, theta = 0.0) Compute the local background and its error at a given position (**per pixel**). Parameters ---------- data : NDArray The image data. error : NDArray The error in the image data. position : ArrayLike[float, float] The x, y position at which to compute the local background. semimajor_axis : float The (unscaled) semimajor axis of the aperture. semiminor_axis : float | None, optional The (unscaled) semiminor axis of the aperture, by default None. If None, it is assumed to be equal to the semimajor axis (i.e., the aperture is circular). theta : float, optional The rotation angle of the PSF, by default 0.0 (i.e., no rotation). Returns ------- Tuple[float, float] The local background and its error **per pixel**. .. py:class:: FlatFieldCorrector(out_dir, flats_dir = None, c1_flats_dir = None, c2_flats_dir = None, c3_flats_dir = None) Helper class for performing flat-field corrections on OPTICAM images. .. py:attribute:: out_dir .. py:attribute:: flat_paths .. py:attribute:: master_flats .. py:method:: _validate_flat_files(flat_paths) Ensure that the flat-field images in the specified directory are valid (i.e., contain at most three filters and use the same binning). Parameters ---------- flat_paths : List[str] The paths to the flat-field images. Returns ------- Dict[str, List[str]] A dictionary containing the paths to the flat-field images for each filter. .. py:method:: create_master_flats(overwrite = False) Create master flat-field images for each available filter. Parameters ---------- overwrite : bool, optional Whether to overwrite the existing master flat-field image, by default False. .. py:method:: correct(image, fltr) Correct an image for flat-fielding. Parameters ---------- image : np.ndarray The image to correct. fltr : str The image filter. Returns ------- NDArray The corrected image. .. 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:: _validate_light_curves(light_curves) :staticmethod: 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: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) 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. .. py:method:: _convert_lc_time_to_seconds(lc) Convert the time of a light curve from days to seconds, relative to the reference time. Parameters ---------- lc : Lightcurve The light curve to convert. Returns ------- Lightcurve The light curve with time converted to seconds, relative to the reference time. .. py:method:: plot_light_curves(title = None) Plot the light curves. Parameters ---------- title : str | None, optional The figure title, by default `None`. 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) 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. 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_crossspectra(norm = 'frac', scale = 'linear') Compute the cross-spectra for each pair of light curves using `stingray.Crossspectrum`. 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 cross-spectrum, by default 'frac'. If 'frac', the cross-spectrum is normalised to fractional rms. If 'abs', the cross-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, Crossspectrum] A dictionary containing the cross-spectra for each pair of light curves, where the keys are tuples of filter names and the values are the cross-spectra. .. py:method:: compute_averaged_crossspectra(segment_size, norm = 'frac', scale = 'linear') Compute the cross-spectra for each pair of light curves using `stingray.Crossspectrum`. 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 cross-spectra. This must be an astropy `Quantity` with units of time (e.g., `astropy.units.s`) to ensure correct handling of the segment size. norm : Literal['frac', 'abs'], optional The normalisation to use for the cross-spectrum, by default 'frac'. If 'frac', the cross-spectrum is normalised to fractional rms. If 'abs', the cross-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, AveragedCrossspectrum] A dictionary containing the averaged cross-spectra for each pair of light curves, where the keys are tuples of filter names and the values are the cross-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:: generate_flats(out_dir, n_flats = 5, binning_scale = 4, overwrite = False) Create synthetic flat-field images. Parameters ---------- out_dir : str The directory to save the data. n_flats : int, optional The number of flats per camera, by default 5. binning_scale : int, optional The binning scale of the flat-field images, by default 4 (512x512). overwrite : bool, optional Whether to overwrite data if they currently exist, by default False. .. py:function:: generate_observations(out_dir, n_images = 100, circular_aperture = True, binning_scale = 4, overwrite = False) Create synthetic observation data for testing and following the tutorials. Parameters ---------- out_dir : str The directory to save the data. n_images : int, optional The number of images to create, by default 100. circular_aperture : bool, optional Whether to apply a circular aperture shadow to the images, by default True. binning_scale : int, optional The binning scale of the images, by default 4 (512x512). overwrite : bool, optional Whether to overwrite data if they currently exist, by default False. .. py:function:: generate_gappy_observations(out_dir, n_images = 1000, circular_aperture = True, binning_scale = 4, overwrite = False) Create synthetic observation data for testing and following the tutorials. Parameters ---------- out_dir : str The directory to save the data. n_images : int, optional The number of images to create, by default 100. circular_aperture : bool, optional Whether to apply a circular aperture shadow to the images, by default True. binning_scale : int, optional The binning scale of the images, by default 4 (512x512). overwrite : bool, optional Whether to overwrite data if they currently exist, by default False.