opticam_new

Submodules

• opticam_new.analysis
• opticam_new.reduction
• opticam_new.utils

Classes

DefaultBackground	Default background estimator.
DefaultFinder	Default source finder. Combines image segmentation with source deblending.
Catalog	Create a catalog of sources from OPTICAM data.
DifferentialPhotometer	Helper class for creating relative light curves from OPTICAM data.
SimplePhotometer	A simple photometer that provides simple aperture photometry routines with support for local background estimations
OptimalPhotometer	A photometer that implements the optimal photometry method described in Naylor 1998, MNRAS, 296, 339-346.
DefaultLocalBackground	Default local background estimator using an elliptical annulus.
FlatFieldCorrector	Helper class for performing flat-field corrections on OPTICAM images.
Analyzer	Helper class for analyzing OPTICAM light curves.

Functions

generate_flats(out_dir[, n_flats, binning_scale, ...])	Create synthetic flat-field images.
generate_observations(out_dir[, n_images, ...])	Create synthetic observation data for testing and following the tutorials.
generate_gappy_observations(out_dir[, n_images, ...])	Create synthetic observation data for testing and following the tutorials.

Package Contents

class opticam_new.DefaultBackground(box_size)

Default background estimator.

Parameters:

box_size (int | Tuple[int, int])

box_size

__call__(data)

Compute the 2D background for an image.

Parameters

dataNDArray

Image data.

Returns

Background2D

2D background.

Parameters:

data (numpy.typing.NDArray)

Return type:

photutils.background.Background2D

class opticam_new.DefaultFinder(npixels, border_width=0)

Default source finder. Combines image segmentation with source deblending.

Parameters:

• npixels (int)

• border_width (int)

border_width = 0

finder

__call__(data, threshold)

Parameters:

• data (numpy.typing.NDArray)

• threshold (float)

Return type:

photutils.segmentation.SegmentationImage

class opticam_new.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.

Parameters:

• out_directory (str)

• data_directory (None | str)

• c1_directory (None | str)

• c2_directory (None | str)

• c3_directory (None | str)

• rebin_factor (int)

• flat_corrector (None | opticam_new.reduction.correctors.FlatFieldCorrector)

• background (None | Callable)

• finder (None | Callable)

• threshold (float)

• aperture_selector (Callable)

• remove_cosmic_rays (bool)

• number_of_processors (int)

• show_plots (bool)

• verbose (bool)

verbose = True

out_directory

logger

data_directory = None

c1_directory = None

c2_directory = None

c3_directory = None

rebin_factor = 1

flat_corrector = None

aperture_selector

threshold = 5

remove_cosmic_rays = True

number_of_processors

show_plots = True

file_paths = []

ignored_files = []

colours = ['tab:blue', 'tab:orange', 'tab:green', 'tab:red', 'tab:purple', 'tab:brown', 'tab:pink',...

transforms

unaligned_files = []

catalogs

psf_params

_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.

Return type:

None

_get_header_info(file)

Get the MJD, filter, binning, and gain from a file header.

Parameters

filestr

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.

Parameters:

file (str)

Return type:

Tuple[numpy.typing.ArrayLike | None, str | None, str | None, float | None]

_parse_header_results(results)

Parse the results returned by self._get_header_info().

Parameters

resultsTuple

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.

Parameters:

results (Tuple[float, float, str, str, float])

Return type:

Dict[str, str]

_log_parameters()

Log any and all object parameters to a JSON file.

_plot_time_between_files()

Plot the times between each file for each camera.

Parameters

showbool

Whether to display the plot.

Return type:

None

_set_psf_params(fltr)

Set the PSF parameters for a given filter based on the catalog data.

Parameters

fltrstr

The filter for which to set the PSF parameters.

Parameters:

fltr (str)

Return type:

None

_get_data(file, return_error=False)

Get data from a file.

Parameters

filestr

Directory path to file.

return_errorbool, optional

Whether to return the error array, by default False.

Returns

NDArray | Tuple[NDArray, NDArray]

The data array or the data and error arrays.

Parameters:

• file (str)

• return_error (bool)

Return type:

numpy.typing.NDArray | Tuple[numpy.typing.NDArray, numpy.typing.NDArray]

_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

imageNDArray

The non-background-subtracted image from which to extract source coordinates.

bkgBackground2D, optional

The background of the image, by default None. If None, the background is estimated from the image.

away_from_edgebool, optional

Whether to exclude sources near the edge of the image, by default False.

n_sourcesint, 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.

Parameters:

• image (numpy.typing.NDArray)

• bkg (photutils.background.Background2D | None)

• away_from_edge (bool | None)

• n_sources (int | None)

Return type:

numpy.typing.NDArray

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_sourcesint, 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_sourcesint, 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_typeLiteral[‘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_limitfloat, optional

The maximum rotation limit (in degrees) for affine transformations, by default None (no limit).

scale_limitfloat, optional

The maximum scale limit for affine transformations, by default None (no limit).

translation_limitfloat | 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.

overwritebool, optional

Whether to overwrite existing catalogs, by default False.

show_diagnostic_plotsbool, 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.

Parameters:

• max_catalog_sources (int)

• n_alignment_sources (int)

• transform_type (Literal['affine', 'translation'])

• rotation_limit (float | None)

• translation_limit (float | Iterable[float] | None)

• scale_limit (float | None)

• overwrite (bool)

• show_diagnostic_plots (bool)

Return type:

None

_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_imageNDArray

The reference image.

reference_coordsNDArray

The source coordinates in the reference image.

transform_typeLiteral[‘affine’, ‘translation’]

The type of transform to use for image alignment.

rotation_limitfloat | None

The maximum rotation limit (in degrees) for image alignment.

scale_limitfloat | None

The maximum scaling limit for image alignment.

translation_limitIterable[float] | None

The maximum translation limit for image alignment.

n_alignment_sourcesint

The (maximum) number of sources to use for image alignment.

Returns

Tuple[List[float], float, float]

The transform parameters, background median, and background RMS.

Parameters:

• batch (List[str])

• reference_image_shape (Tuple[int])

• reference_coords (numpy.typing.NDArray)

• transform_type (Literal['affine', 'translation'])

• rotation_limit (float | None)

• scale_limit (float | None)

• translation_limit (Iterable[float] | None)

• n_alignment_sources (int)

Return type:

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

_valid_transform(file, transform, rotation_limit, scale_limit, translation_limit)

Find whether a transform is valid given some transform limits.

Parameters

filestr

The file being transformed.

transformSimilarityTransform

The transform.

rotation_limitfloat | None

The rotation limit.

scale_limitfloat | None

The scale limit.

translation_limitIterable[float] | None

The translation limit.

Returns

bool

Whether the transform is valid.

Parameters:

• file (str)

• transform (skimage.transform.SimilarityTransform)

• rotation_limit (float | None)

• scale_limit (float | None)

• translation_limit (Iterable[float] | None)

Return type:

bool

_parse_alignment_results(results, fltr)

Parse the results of image alignment.

Parameters

resultsTuple

The results.

fltrstr

The filter.

Returns

Tuple[NDArray, Dict[str, float], Dict[str, float]]:

The stacked image, background medians, and background RMSs.

Parameters:

• results (Tuple)

• fltr (str)

Return type:

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

_plot_background_meshes(stacked_images, show)

Plot the background meshes on top of the catalog images.

Parameters

stacked_imagesDict[str, NDArray]

The stacked images for each camera.

showbool

Whether to display the plot.

Parameters:

• stacked_images (Dict[str, numpy.typing.NDArray])

• show (bool)

Return type:

None

_visualise_psfs(image, fltr, show)

Generate PSF plots for each source in an image.

Parameters

imageNDArray

The image (not background subtracted).

fltrstr

The image filter.

show: bool

Whether to display the plot.

Parameters:

• image (numpy.typing.NDArray)

• fltr (str)

• show (bool)

Return type:

None

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_framesbool, 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.

overwritebool, optional

Whether to overwrite existing GIFs, by default False.

Parameters:

• keep_frames (bool)

• overwrite (bool)

Return type:

None

_create_gif_frames(file, fltr)

Create a gif frames from a batch of images and save it to the out_directory.

Parameters

filestr

The list of file names in the batch.

fltrstr

The filter.

Parameters:

• file (str)

• fltr (str)

Return type:

None

_compile_gif(fltr, keep_frames)

Create a gif from the frames saved in out_directory.

Parameters

fltrstr

The filter.

keep_framesbool

Whether to keep the frames after the gif is saved.

Parameters:

• fltr (str)

• keep_frames (bool)

Return type:

None

photometry(photometer)

Perform photometry on the catalogs using the provided photometer.

Parameters

photometerBasePhotometer

The photometer. Should be a subclass of BasePhotometer, or implement a compute method that follows the BasePhotometer interface.

Parameters:

photometer (opticam_new.reduction.photometers.BasePhotometer)

Return type:

None

_photometry(photometer, source_coords, fltr, file)

Parameters:

• photometer (opticam_new.reduction.photometers.BasePhotometer)

• source_coords (numpy.typing.NDArray)

• fltr (str)

• file (str)

Return type:

Dict[str, List]

identify_gaps(files)

Identify gaps in the observation sequence and logs them to log_dir/diag/gaps.txt.

Parameters

filesList[str]

The list of files for a single filter.

Parameters:

files (List[str])

Return type:

None

class opticam_new.DifferentialPhotometer(out_directory, show_plots=True)

Helper class for creating relative light curves from OPTICAM data.

Parameters:

• out_directory (str)

• show_plots (bool)

out_directory

show_plots = True

filters

t_ref

catalogs

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

fltrstr

The filter to compute the relative light curve for.

targetint

The catalog ID of the target source.

comparisonsint | List[int]

The catalog ID(s) of the comparison source(s).

phot_labelstr

The photometry label, used for file reading and labelling.

prefixstr, optional

The prefix to use when saving the relative light curve (e.g., the target star’s name), by default None.

match_other_camerasbool, 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_diagnosticsbool, optional

Whether to show diagnostic plots, by default True.

Returns

Analyzer

An Analyzer object containing the relative light curve(s).

Parameters:

• fltr (str)

• target (int)

• comparisons (int | List[int])

• phot_label (str)

• prefix (str | None)

• match_other_cameras (bool)

• show_diagnostics (bool)

Return type:

opticam_new.analysis.analyzer.Analyzer

_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

fltrstr

The filter to compute the relative light curve for.

targetint

The catalog ID of the target source.

comparisonsList[int]

The catalog ID(s) of the comparison source(s).

prefixstr | None

The prefix to use when saving the relative light curve (e.g., the target star’s name), by default None.

phot_labelstr

The photometry label, used for file reading and labelling.

show_diagnosticsbool

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.

Parameters:

• fltr (str)

• target (int)

• comparisons (List[int])

• prefix (str | None)

• phot_label (str)

• show_diagnostics (bool)

Return type:

stingray.Lightcurve | None

_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_curveLightcurve

The relative light curve to plot.

targetint

The catalog ID of the target source.

comparisonsList[int]

The catalog ID(s) of the comparison source(s).

prefixstr | None

The prefix to use when saving the relative light curve (e.g., the target star’s name), by default None.

fltrstr

The filter to plot the relative light curve for.

phot_labelstr

The photometry label, used for file reading and labelling.

axAxes, optional

The axes to plot the relative light curve on, by default None. If None, a new figure and axes will be created.

Parameters:

• relative_light_curve (stingray.Lightcurve)

• target (int)

• comparisons (List[int])

• prefix (str | None)

• fltr (str)

• phot_label (str)

• ax (matplotlib.axes.Axes | None)

Return type:

None

_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

fltrstr

The filter to compute the relative light curve.

comparison1int

The catalog ID of the first comparison source.

comparison2int

The catalog ID of the second comparison source.

comparison1_dfpd.DataFrame

The data frame of the first comparison source.

comparison2_dfpd.DataFrame

The data frame of the second comparison source.

pho_labelstr

The photometry label.

t_reffloat

The time of the earliest observation (used for plotting the relative light curve in seconds from t_ref).

showbool

Whether to show the diagnostic plot.

Parameters:

• fltr (str)

• comparison1 (int)

• comparison2 (int)

• comparison1_df (pandas.DataFrame)

• comparison2_df (pandas.DataFrame)

• phot_label (str)

• show (bool)

Return type:

None

class opticam_new.SimplePhotometer(match_sources=True, source_matching_tolerance=2.0, local_background_estimator=None)

Bases: BasePhotometer

A simple photometer that provides simple aperture photometry routines with support for local background estimations using annuli.

Parameters:

• match_sources (bool)

• source_matching_tolerance (float)

• local_background_estimator (None | opticam_new.reduction.local_background.BaseLocalBackground)

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

imageNDArray

The image. If local_background_estimator is undefined, this image will be background subtracted.

image_errNDArray

The error in the image.

source_coordsNDArray

The source coordinates in the catalogue.

image_coordsNone | 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_paramsDict[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

Parameters:

• image (numpy.typing.NDArray)

• image_err (numpy.typing.NDArray)

• source_coords (numpy.typing.NDArray)

• image_coords (None | numpy.typing.NDArray)

• psf_params (Dict[str, float])

Return type:

Dict[str, List]

compute_aperture_flux(data, error, position, psf_params)

Compute the aperture flux of a source in the image.

Parameters

dataNDArray

The image.

errorNDArray

The error in the image.

positionNDArray

The position of the source.

psf_paramsDict[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.

Parameters:

• data (numpy.typing.NDArray)

• error (numpy.typing.NDArray)

• position (numpy.typing.NDArray)

• psf_params (Dict[str, float])

Return type:

Tuple[float, float] | Tuple[float, float, float, float]

get_position(source_coords, image_coords, source_index, psf_params)

Get the position of a source in an image.

Parameters

source_coordsNDArray

The source coordinates in the catalogue.

image_coordsNDArray | None

The source coordinates in the image.

source_indexint

The source index.

psf_paramsDict[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.

Parameters:

• source_coords (numpy.typing.NDArray)

• image_coords (numpy.typing.NDArray | None)

• source_index (int)

• psf_params (Dict[str, float])

Return type:

numpy.typing.NDArray | None

get_closest_source(source_coords, image_coords, source_index, psf_params)

Given a source, find the closest source in the catalogue.

Parameters

source_coordsNDArray

The source coordinates in the catalogue.

image_coordsNDArray | None

The source coordinates in the image.

source_indexint

The source index.

psf_paramsDict[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.

Parameters:

• source_coords (numpy.typing.NDArray)

• image_coords (numpy.typing.NDArray | None)

• source_index (int)

• psf_params (Dict[str, float])

Return type:

numpy.typing.NDArray | None

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’.

Return type:

Dict[str, List]

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

resultsDict[str, List]

The results dictionary to pad.

Returns

Dict[str, List]

The padded results dictionary.

Parameters:

results (Dict[str, List])

Return type:

Dict[str, List]

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

resultsDict[str, List]

The results dictionary to populate.

phot_functionCallable

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.

imageNDArray

The image.

image_errNDArray

The error in the image.

positionNDArray

The position of the source in the image.

psf_paramsDict[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).

Parameters:

• results (Dict[str, List])

• phot_function (Callable)

• image (numpy.typing.NDArray)

• image_err (numpy.typing.NDArray)

• position (numpy.typing.NDArray)

• psf_params (Dict[str, float])

Return type:

Dict[str, List]

class opticam_new.OptimalPhotometer(match_sources=True, source_matching_tolerance=2.0, local_background_estimator=None)

Bases: SimplePhotometer

A photometer that implements the optimal photometry method described in Naylor 1998, MNRAS, 296, 339-346.

Parameters:

• match_sources (bool)

• source_matching_tolerance (float)

• local_background_estimator (None | opticam_new.reduction.local_background.BaseLocalBackground)

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

imageNDArray

The image. If local_background_estimator is undefined, this image will be background subtracted.

image_errNDArray

The error in the image.

source_coordsNDArray

The source coordinates in the catalogue.

image_coordsNone | 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_paramsDict[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.

Parameters:

• image (numpy.typing.NDArray)

• image_err (numpy.typing.NDArray)

• source_coords (numpy.typing.NDArray)

• image_coords (None | numpy.typing.NDArray)

• psf_params (Dict[str, float])

Return type:

Dict[str, List]

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

imageNDArray

The image.

errorNDArray

The error in the image.

positionNDArray

The position of the source in the image, given as (y, x) coordinates.

psf_paramsDict[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.

Parameters:

• image (numpy.typing.NDArray)

• error (numpy.typing.NDArray)

• position (numpy.typing.NDArray)

• psf_params (Dict[str, float])

Return type:

Tuple[float, float] | Tuple[float, float, float, float]

class opticam_new.DefaultLocalBackground(r_in_scale=5, r_out_scale=6, sigma_clip=SigmaClip(sigma=3, maxiters=10))

Bases: BaseLocalBackground

Default local background estimator using an elliptical annulus.

Parameters:

• r_in_scale (float)

• r_out_scale (float)

• sigma_clip (None | astropy.stats.SigmaClip)

__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

dataNDArray

The image data.

errorNDArray

The error in the image data.

positionArrayLike[float, float]

The x, y position at which to compute the local background.

semimajor_axisfloat

The (unscaled) semimajor axis of the aperture.

semiminor_axisfloat | 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).

thetafloat, 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.

Parameters:

• data (numpy.typing.NDArray)

• error (numpy.typing.NDArray)

• position (numpy.typing.NDArray)

• semimajor_axis (float)

• semiminor_axis (float | None)

• theta (float)

Return type:

Tuple[float, float]

class opticam_new.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.

Parameters:

• out_dir (str)

• flats_dir (str | None)

• c1_flats_dir (str | None)

• c2_flats_dir (str | None)

• c3_flats_dir (str | None)

out_dir

flat_paths

master_flats

_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_pathsList[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.

Parameters:

flat_paths (List[str])

Return type:

Dict[str, List[str]]

create_master_flats(overwrite=False)

Create master flat-field images for each available filter.

Parameters

overwritebool, optional

Whether to overwrite the existing master flat-field image, by default False.

Parameters:

overwrite (bool)

Return type:

None

correct(image, fltr)

Correct an image for flat-fielding.

Parameters

imagenp.ndarray

The image to correct.

fltrstr

The image filter.

Returns

NDArray

The corrected image.

Parameters:

• image (numpy.typing.NDArray)

• fltr (str)

Return type:

numpy.typing.NDArray

class opticam_new.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

static _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]

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)

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.

Parameters:

dt (astropy.units.quantity.Quantity)

Return type:

None

_convert_lc_time_to_seconds(lc)

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

Parameters

lcLightcurve

The light curve to convert.

Returns

Lightcurve

The light curve with time converted to seconds, relative to the reference time.

Parameters:

lc (stingray.Lightcurve)

Return type:

stingray.Lightcurve

plot_light_curves(title=None)

Plot the light curves.

Parameters

titlestr | None, optional

The figure title, by default None.

Returns

Figure

The figure containing the light curves.

Parameters:

title (str | None)

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)

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.

Returns

Dict[str, Dict[str, NDArray]]

The phase binned light curves.

Parameters:

• period (astropy.units.quantity.Quantity)

• t0 (float | None)

• n_bins (int)

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_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

normLiteral[‘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.

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, 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.

Parameters:

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

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

Return type:

Dict[str, stingray.Crossspectrum]

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_sizeQuantity

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.

normLiteral[‘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.

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, 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.

Parameters:

• segment_size (astropy.units.quantity.Quantity)

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

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

Return type:

Dict[str, stingray.AveragedCrossspectrum]

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_new.generate_flats(out_dir, n_flats=5, binning_scale=4, overwrite=False)

Create synthetic flat-field images.

Parameters

out_dirstr

The directory to save the data.

n_flatsint, optional

The number of flats per camera, by default 5.

binning_scaleint, optional

The binning scale of the flat-field images, by default 4 (512x512).

overwritebool, optional

Whether to overwrite data if they currently exist, by default False.

Parameters:

• out_dir (str)

• n_flats (int)

• binning_scale (int)

• overwrite (bool)

Return type:

None

opticam_new.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_dirstr

The directory to save the data.

n_imagesint, optional

The number of images to create, by default 100.

circular_aperturebool, optional

Whether to apply a circular aperture shadow to the images, by default True.

binning_scaleint, optional

The binning scale of the images, by default 4 (512x512).

overwritebool, optional

Whether to overwrite data if they currently exist, by default False.

Parameters:

• out_dir (str)

• n_images (int)

• circular_aperture (bool)

• binning_scale (int)

• overwrite (bool)

Return type:

None

opticam_new.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_dirstr

The directory to save the data.

n_imagesint, optional

The number of images to create, by default 100.

circular_aperturebool, optional

Whether to apply a circular aperture shadow to the images, by default True.

binning_scaleint, optional

The binning scale of the images, by default 4 (512x512).

overwritebool, optional

Whether to overwrite data if they currently exist, by default False.

Parameters:

• out_dir (str)

• n_images (int)

• circular_aperture (bool)

• binning_scale (int)

• overwrite (bool)

Return type:

None