opticam

Submodules

Classes

`BaseBackground`	Base class for OPTICAM background estimators.
`DefaultBackground`	Default background estimator.
`BaseLocalBackground`	Base class for local background estimators.
`DefaultLocalBackground`	Default local background estimator using an elliptical annulus.
`DefaultFinder`	Default source finder. Combines image segmentation with source deblending.
`Reducer`	Class for reducing OPTICAM data.
`DifferentialPhotometer`	Helper class for creating relative light curves from OPTICAM data.
`AperturePhotometer`	A photometer for performing aperture photometry.
`OptimalPhotometer`	A photometer that implements the optimal photometry method described in Naylor 1998, MNRAS, 296, 339-346.
`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.
`check_data`(out_directory[, data_directory, ...])	Check that the data are self-consistent.

Package Contents

class opticam.BaseBackground(box_size)

Bases: abc.ABC

Base class for OPTICAM background estimators.

Parameters:: box_size (int | Tuple[int, int])

box_size

abstractmethod __call__(image)

Compute the 2D background for an image.

Parameters

imageNDArray: The image.

Returns

Background2D: The two-dimensional background.

Parameters:: image (numpy.typing.NDArray)
Return type:: photutils.background.Background2D

class opticam.DefaultBackground(box_size)

Bases: BaseBackground

Default background estimator.

Parameters:: box_size (int | Tuple[int, int])

__call__(image)

Compute the 2D background for an image.

Parameters

imageNDArray: The image.

Returns

Background2D: The two-dimensional background.

Parameters:: image (numpy.typing.NDArray)
Return type:: photutils.background.Background2D

class opticam.BaseLocalBackground(r_in_scale=5, r_out_scale=7.5, sigma_clip=SigmaClip(sigma=3, maxiters=10))

Bases: abc.ABC

Base class for local background estimators.

Parameters:

r_in_scale (float)
r_out_scale (float)
sigma_clip (None | astropy.stats.SigmaClip)

r_in_scale = 5

r_out_scale = 7.5

sigma_clip

abstractmethod __call__(data, position, semimajor_axis, semiminor_axis, theta)

Compute the local background and its error at a given position (per pixel).

Parameters

dataNDArray: The image data.
semimajor_axisfloat: The (unscaled) semi-major axis of the aperture.
semiminor_axisfloat: The (unscaled) semi-minor axis of the aperture.
thetafloat: The rotation angle of the PSF.
positionTuple[float, float]: The x, y position at which to compute the local background.

Returns

Tuple[float, float]: The local background and its error per pixel.

Parameters:

data (numpy.typing.NDArray)
position (numpy.typing.NDArray)
semimajor_axis (float)
semiminor_axis (float)
theta (float)

Return type:

Tuple[float, float]

abstractmethod get_annulus(position, semimajor_axis, semiminor_axis, theta)

Define an annulus at the given position.

Parameters

positionNDArray: The centre of the annulus.
semimajor_axisfloat: The semimajor standard deviation of the PSF.
semiminor_axisfloat: The semiminor standard deviation of the PSF.
thetafloat: The orientation of the source in radians.

Returns

Aperture: The annulus.

Parameters:

position (numpy.typing.NDArray)
semimajor_axis (float)
semiminor_axis (float)
theta (float)

Return type:

photutils.aperture.Aperture

get_stats(data, position, semimajor_axis, semiminor_axis, theta)

Get the stats of the annulus.

Parameters

dataNDArray: The image data.
positionNDArray: The centre of the annulus.
semimajor_axisfloat: The semimajor standard deviation of the PSF.
semiminor_axisfloat: The semiminor standard deviation of the PSF.
thetafloat: The orientation of the source in radians.

Returns

ApertureStats: The stats of the annulus.

Parameters:

data (numpy.typing.NDArray)
position (numpy.typing.NDArray)
semimajor_axis (float)
semiminor_axis (float)
theta (float)

Return type:

photutils.aperture.ApertureStats

class opticam.DefaultLocalBackground(r_in_scale=5, r_out_scale=7.5, 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)

get_annulus(position, semimajor_axis, semiminor_axis, theta)

Define an annulus at the given position.

Parameters

positionNDArray: The centre of the annulus.
semimajor_axisfloat: The semimajor standard deviation of the PSF.
semiminor_axisfloat: The semiminor standard deviation of the PSF.
thetafloat: The orientation of the source in radians.

Returns

Aperture: The annulus.

Parameters:

position (numpy.typing.NDArray)
semimajor_axis (float)
semiminor_axis (float)
theta (float)

Return type:

photutils.aperture.Aperture

__call__(data, position, semimajor_axis, semiminor_axis=None, theta=0.0)

Compute the sigma-clipped local background (mean) and its error (standard deviation) at a given position.

Parameters

dataNDArray: The image data.
errorNDArray: The error in the image data.
positionNDArray: 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 annulus is circular).
thetafloat, optional: The rotation angle of the PSF, by default 0 (i.e., no rotation).

Returns

Tuple[float, float]: The local background (mean) and its error (standard deviation).

Parameters:

data (numpy.typing.NDArray)
position (numpy.typing.NDArray)
semimajor_axis (float)
semiminor_axis (float | None)
theta (float)

Return type:

Tuple[float, float]

class opticam.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 | numpy.typing.NDArray)

Return type:

astropy.table.QTable

class opticam.Reducer(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=False, barycenter=True, number_of_processors=cpu_count() // 2, show_plots=True, verbose=True)

Class for reducing 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.correctors.flat_field_corrector.FlatFieldCorrector)
background (opticam.background.global_background.BaseBackground | None)
finder (None | Callable)
threshold (float)
aperture_selector (Callable)
remove_cosmic_rays (bool)
barycenter (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 = False

barycenter = True

number_of_processors

show_plots = True

reference_files

transforms

unaligned_files = []

catalogs: Dict[str, astropy.table.QTable]

psf_params

create_catalogs(max_catalog_sources=15, n_alignment_sources=15, transform_type='affine', rotation_limit=None, translation_limit=None, scale_limit=None, overwrite=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 to include in the catalog, by default 30. Since source IDs are ordered by brightness, 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 30. 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 ‘affine’. ‘translation’ performs simple x, y translations, while ‘affine’ uses astroalign.find_transform(). ‘affine’ is generally more robust (and is therefore the default) while ‘translation’ can work with fewer sources.
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 | int | List[float | int] | None, optional: The maximum translation limit for both types of 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.

Parameters:

max_catalog_sources (int)
n_alignment_sources (int)
transform_type (Literal['affine', 'translation'])
rotation_limit (float | None)
translation_limit (float | int | List[float | int] | None)
scale_limit (float | None)
overwrite (bool)

Return type:

None

plot_background_meshes(save=False)

Plot the background mesh over an image from each filter to verify it’s appropriately sized. If stacked catalog images exist, those will be used. Otherwise, a random image will be chosen for each filter.

Parameters

savebool, optional: Whether to save the plot, by default False.

Parameters:: save (bool)
Return type:: None

plot_growth_curves(targets=None, save=False)

Plot the growth curves for the sources identified in the catalog images. The resulting plots are saved to out_directory/diag/growth_curves as PDF files.

Parameters

targetsDict[str, int | List[int]] | None, optional

The targets for which growth curves will be created, by default None (growth curves are created for all catalog sources). To create growth curves for specific targets, pass a dictionary with keys listing the desired filters and values listing each filter’s correpsonding target(s). For example: ``` # plot growth curves for the three brightest sources in each catalog plot_growth_curves(

targets = {
‘g-band’: [1, 2, 3], ‘r-band’: [1, 2, 3], ‘i-band’: [1, 2, 3], },

)

```

savebool, optional

Whether to save the plots, by default False.

Parameters:

targets (Dict[str, int | List[int]] | None)
save (bool)

Return type:

None

plot_psfs()

Plot the PSFs for the catalog sources.

Return type:: None

plot_snrs(save=False)

Plot the signal-to-noise ratios for each catalogued source in the reference images.

Parameters

savebool, optional: Whether to save the plot, by default False.

Parameters:: save (bool)
Return type:: None

plot_noise(save=False)

Plot the noise characterisation for each reference image.

Parameters

savebool, optional: Whether to save the plot, by default ‘False’.

Parameters:: save (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

plot_apertures(photometer, targets=None, save=False)

Plot the apertures over each source.

Parameters

photometerAperturePhotometer

The AperturePhotometer instance. If a local background estimator has been defined, this will also be plotted.

targetsDict[str, int] | Dict[str, List[int]] | Dict[str, List[int] | int] | None

The targets for which apertures will be plotted, by default None (apertures are plotted for all sources). To plot apertures for specific targets, pass a dictionary with keys listing the desired filters and values listing each filter’s correpsonding target(s). For example: ``` # plot apertures for the three brightest sources in each filter photometer = opticam.AperturePhotometer() plot_apertures(

photometer=photometer, targets = {

‘g-band’: [1, 2, 3], ‘r-band’: [1, 2, 3], ‘i-band’: [1, 2, 3], },

)

```

savebool, optional

Whether to save the plots, by default False.

Parameters:

photometer (opticam.photometers.AperturePhotometer)
targets (Dict[str, int] | Dict[str, List[int]] | Dict[str, List[int] | int] | None)
save (bool)

Return type:

None

photometry(photometer, overwrite=False)

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.
overwritebool, optional: Whether to overwrite any existing light curves files computed using the same photometer, by default False.

Parameters:

photometer (opticam.photometers.BasePhotometer)
overwrite (bool)

Return type:

None

update_unaligned_files(files)

Add one or more files to the list of unaligned files. Unaligned files are skipped when performing photometry.

Parameters

filesstr | List[str]: The file or files.

Parameters:: files (str | List[str])
Return type:: None

class opticam.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

time_key = 'BMJD'

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.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.AperturePhotometer(semimajor_axis=None, semiminor_axis=None, orientation=None, forced=False, source_matching_tolerance=5.0, local_background_estimator=None)

Bases: BasePhotometer

A photometer for performing aperture photometry.

Parameters:

semimajor_axis (int | None)
semiminor_axis (int | None)
orientation (float | None)
forced (bool)
source_matching_tolerance (float)
local_background_estimator (None | opticam.background.local_background.BaseLocalBackground)

semimajor_axis = None

semiminor_axis = None

orientation = None

compute(image, dark_flux, background_rms, source_coords, image_coords, psf_params)

Compute the fluxes of the catalogued sources from the given image.

Parameters

imageNDArray: The image. If self.local_background_estimator is undefined, this image will be background subtracted.
dark_fluxfloat: The dark current’s “flux” contribution.
background_rmsNDArray | None: The background RMS. May be None if self.local_background_estimator is defined.
source_coordsNDArray: The source coordinates in the catalogue.
image_coordsNDArray | None: 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 photometry results.

Parameters:

image (numpy.typing.NDArray)
dark_flux (float)
background_rms (numpy.typing.NDArray | None)
source_coords (numpy.typing.NDArray)
image_coords (numpy.typing.NDArray | None)
psf_params (Dict[str, float])

Return type:

Dict[str, List]

compute_aperture_flux(image, dark_flux, background_rms, position, psf_params)

Compute the aperture flux of a source in the image.

Parameters

imageNDArray: The image.
dark_fluxfloat: The dark current’s “flux” contribution.
background_rmsNDArray | None: The background RMS. May be None if self.local_background_estimator is defined.
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, float] | Tuple[float, float, float, float, float]: The flux, flux error, and signal-to-noise ratio. If local_background_estimator is defined, the background and its error are also returned.

Parameters:

image (numpy.typing.NDArray)
dark_flux (float)
background_rms (numpy.typing.NDArray | None)
position (numpy.typing.NDArray)
psf_params (Dict[str, float])

Return type:

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

get_aperture(position, psf_params)

Parameters:

position (numpy.typing.NDArray)
psf_params (Dict[str, float])

Return type:

photutils.aperture.EllipticalAperture

get_aperture_area(psf_params)

Get the area of the aperture.

Parameters

psf_paramsDict[str, float],: The PSF parameters.

Returns

float: The area of the aperture.

Parameters:: psf_params (Dict[str, float])
Return type:: float

class opticam.OptimalPhotometer(forced=False, source_matching_tolerance=5.0, local_background_estimator=None)

Bases: BasePhotometer

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

Parameters:

forced (bool)
source_matching_tolerance (float)
local_background_estimator (opticam.background.local_background.BaseLocalBackground | Callable | None)

compute(image, dark_flux, background_rms, source_coords, image_coords, psf_params)

Compute the fluxes of the catalogued sources from the given image.

Parameters

imageNDArray: The image. If self.local_background_estimator is undefined, this image will be background subtracted.
dark_fluxfloat: The dark current’s “flux” contribution.
background_rmsNDArray | None: The background RMS. May be None if self.local_background_estimator is defined.
source_coordsNDArray: The source coordinates in the catalogue.
image_coordsNDArray | None: 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 photometry results.

Parameters:

image (numpy.typing.NDArray)
dark_flux (float)
background_rms (numpy.typing.NDArray | None)
source_coords (numpy.typing.NDArray)
image_coords (numpy.typing.NDArray | None)
psf_params (Dict[str, float])

Return type:

Dict[str, List]

compute_optimal_flux(image, dark_flux, background_rms, 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.
dark_fluxfloat: The dark current’s “flux” contribution.
background_rmsNDArray | None: The background RMS. May be None if self.local_background_estimator is defined.
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)
dark_flux (float)
background_rms (numpy.typing.NDArray | None)
position (numpy.typing.NDArray)
psf_params (Dict[str, float])

Return type:

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

static get_weights(var, position, psf_params)

Compute the optimal weight for each pixel in an image.

Parameters

varNDArray: The variance image.
positionNDArray: The position of the source.
psf_paramsDict[str, float]: The PSF parameters.

Returns

Tuple[NDArray, float]: The weights and the normalisation constant.

Parameters:

var (numpy.typing.NDArray)
position (numpy.typing.NDArray)
psf_params (Dict[str, float])

Return type:

Tuple[numpy.typing.NDArray, float]

class opticam.FlatFieldCorrector(out_directory, flats_directory=None, c1_flats_directory=None, c2_flats_directory=None, c3_flats_directory=None)

Helper class for performing flat-field corrections on OPTICAM images.

Parameters:

out_directory (str)
flats_directory (str | None)
c1_flats_directory (str | None)
c2_flats_directory (str | None)
c3_flats_directory (str | None)

out_directory

flat_paths

master_flats

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.Analyzer(out_directory, light_curves=None, norm='mean', 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)
norm (Literal['max', 'mean', 'none'])
prefix (str | None)
phot_label (str | None)
show_plots (bool)

norm = 'mean'

light_curves

out_directory

prefix = None

phot_label = None

show_plots = True

join(analyzer)

Combine another Analyzer instance with the current one. If the new Analyzer has light curves with filters that are not present in the current Analyzer, those filters will be added. If the new Analyzer has light curves with filters that are already present in the current Analyzer, those light curves will be merged.

Parameters

analyzerAnalyzer: The analyzer instance being combined with the current one.

Returns

Analyzer: A new Analyzer instance with the combined light curves.

Parameters:: analyzer (Analyzer)
Return type:: Analyzer

rebin_light_curves(dt, method='mean')

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

Parameters

dtQuantity: The desired time resolution for the rebinned light curves. This must be an astropy Quantity with units of time (e.g., astropy.units.s) to ensure correct handling of the time resolution.
methodLiteral[‘mean’, ‘sum’], optional: The rebinning method, by default ‘mean’.

Parameters:

dt (astropy.units.quantity.Quantity)
method (Literal['mean', 'sum'])

Return type:

None

plot_light_curves(show_gtis=False)

Plot the light curves.

Parameters

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

Returns

Figure: The figure containing the light curves.

Parameters:: show_gtis (bool)
Return type:: matplotlib.figure.Figure

phase_fold_light_curves(period)

Phase fold each light curve using the given period.

Parameters

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

Returns

Dict[str, NDArray]: The phase folded light curves.

Parameters:: period (astropy.units.quantity.Quantity)
Return type:: Dict[str, numpy.typing.NDArray]

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

Phase bin each light curve using the given period.

Parameters

periodQuantity: The period to use for phase binning. This must be an astropy Quantity with units of time (e.g., astropy.units.s) to ensure correct handling of the period.
t0float | None, optional: Time of zero phase, by default None. If None, the first time value in the light curve will be used.
n_binsint, optional: The number of phase bins, by default 10.
plotbool, optional: Whether to plot the phase binned light curves, by default True.
subplotbool, optional: Whether to plot filters in separate subplots, by default True.
shareybool, optional: Whether to render the plot with a common y-axis (useful for directly comparing amplitudes), by default False. Only used if plot=True and subplot=True.

Returns

Dict[str, Dict[str, NDArray]]: The phase binned light curves.

Parameters:

period (astropy.units.quantity.Quantity)
t0 (float | None)
n_bins (int)
plot (bool)
subplot (bool)
sharey (bool)

Return type:

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

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

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

Parameters

normLiteral[‘frac’, ‘abs’], optional: The normalisation to use for the power spectrum, by default ‘frac’. If ‘frac’, the power spectrum is normalised to fractional rms. If ‘abs’, the power spectrum is normalised to absolute power.
scaleLiteral[‘linear’, ‘log’, ‘loglog’], optional: The scale to use for the plot, by default ‘linear’. If ‘linear’, all axes are linear. If ‘log’, the frequency axis is logarithmic. If ‘loglog’, both the frequency and power axes are logarithmic.

Returns

Dict[str, Powerspectrum]: A dictionary containing the power spectrum for each light curve, where the keys are the filter names and the values are the power spectra.

Parameters:

norm (Literal['frac', 'abs'])
scale (Literal['linear', 'log', 'loglog'])

Return type:

Dict[str, stingray.Powerspectrum]

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

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

Parameters

segment_sizeQuantity: The size of the segments to use for averaging the power spectra. This must be an astropy Quantity with units of time (e.g., astropy.units.s) to ensure correct handling of the segment size.
rebin_factorfloat | None, optional: The factor by which to rebin the power spectrum in frequency. If ‘None’, no rebinning will be performed. If a float, the power spectrum will be geometrically/logarithmically rebinned with each bin being a factor 1 + rebin_factor larger than the previous one.
normLiteral[‘frac’, ‘abs’], optional: The normalisation to use for the power spectrum, by default ‘frac’. If ‘frac’, the power spectrum is normalised to the fractional rms. If ‘abs’, the power spectrum is normalised to the absolute rms.
scaleLiteral[‘linear’, ‘log’, ‘loglog’], optional: The scale to use for the plot, by default ‘linear’. If ‘linear’, all axes are linear. If ‘log’, the frequency axis is logarithmic. If ‘loglog’, both the frequency and power axes are logarithmic.

Returns

Dict[str, AveragedPowerspectrum]: The averaged power spectrum for each light curve, where the keys are the filter names and the values are the averaged power spectra.

Parameters:

segment_size (astropy.units.quantity.Quantity)
rebin_factor (float | None)
norm (Literal['frac', 'abs'])
scale (Literal['linear', 'log', 'loglog'])

Return type:

Dict[str, stingray.AveragedPowerspectrum]

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

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

Parameters

normLiteral[‘abs’, ‘frac’], optional: The normalisation to use for the Lomb-Scargle periodogram, by default ‘frac’. If ‘abs’, the periodogram is normalised to absolute power. If ‘frac’, the periodogram is normalised to fractional rms.
scaleLiteral[‘linear’, ‘log’, ‘loglog’], optional: The scale to use for the inferred frequencies, by default ‘linear’. If ‘linear’, the frequency grid is linearly spaced. If ‘log’, the frequency grid is logarithmically spaced. If ‘loglog’, both the frequency and power axes will be in logarithm. The upper and lower bounds of the frequencies are the same in all cases.

Returns

Tuple[NDArray, Dict[str, NDArray]] | Dict[str, NDArray]: If no frequencies are provided, returns a tuple containing the frequencies and a dictionary of periodograms for each light curve. If frequencies are provided, returns a dictionary of periodogram powers for each light curve.

Parameters:

norm (Literal['abs', 'frac'])
scale (Literal['linear', 'log', 'loglog'])

Return type:

Dict[str, stingray.lombscargle.LombScarglePowerspectrum]

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

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

Parameters

modeLiteral[‘same’, ‘valid’, ‘full’], optional: The mode to use for the cross-correlation, by default ‘same’. See stingray.CrossCorrelation for details on the different modes.
normLiteral[‘none’, ‘variance’], optional: The normalisation to use for the cross-correlation, by default ‘variance’. See stingray.CrossCorrelation for details on the different normalisations.
force_matchbool, optional: Whether to force the light curves to have the same time columns before computing the cross-correlation, by default True. If False, cross-correlation calculations may fail if the light curves have different time columns.

Returns

Dict[str, CrossCorrelation]: A dictionary containing the cross-correlations for each pair of light curves, where the keys are tuples of filter names and the values are the cross-correlations.

Parameters:

mode (Literal['same', 'valid', 'full'])
norm (Literal['none', 'variance'])
force_match (bool)

Return type:

Dict[str, stingray.CrossCorrelation]

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

opticam.check_data(out_directory, data_directory=None, c1_directory=None, c2_directory=None, c3_directory=None, barycenter=True, verbose=True, return_output=False, logger=None, number_of_processors=cpu_count() // 2)

Check that the data are self-consistent.

Parameters

out_directorystr: The directory path to which any output files will be saved.
data_directoryNone | str, optional: The directory path to the data for all three cameras, by default None.
c1_directoryNone | str, optional: The directory path to the data for Camera 1, by default None.
c2_directoryNone | str, optional: The directory path to the data for Camera 2, by default None
c3_directoryNone | str, optional: The directory path to the data for Camera 3, by default None
barycenterbool, optional: Whether to apply a Barycentric correction to the image time stamps, by default True.
verbosebool, optional: Whether to print any output info, by default True.
return_outputbool, optional: Whether to return any output, by default False.
loggerLogger | None, optional: The logger, by default None.
number_of_processors_type_, optional: The number of processors to use, by default cpu_count() // 2.

Returns

None | Tuple[Dict[str, str], int, Dict[str, float], List[str], Dict[str, float], float]: If return_output=True, the file paths, binning scale, Barycentric MJD dates, ignored files, file gains, and the reference date are returned. Otherwise, nothing is returned.

Parameters:

out_directory (str)
data_directory (None | str)
c1_directory (None | str)
c2_directory (None | str)
c3_directory (None | str)
barycenter (bool)
verbose (bool)
return_output (bool)
logger (logging.Logger | None)

Return type:

None | Tuple[Dict[str, List[str]], int, Dict[str, float], List[str], Dict[str, float], Dict[str, float], float]