opticam

Submodules

Classes

`Analyzer`	Helper class for analyzing OPTICAM light curves.
`DifferentialPhotometer`	Helper class for creating relative light curves.
`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.
`BiasCorrector`	Helper clsas for performing bias corrections.
`DarkNoiseCorrector`	Helper class for performing dark noise corrections.
`FlatFieldCorrector`	Helper class for performing flat-field corrections.
`DefaultFinder`	Default source finder. Combines image segmentation with source deblending.
`Instrument`	Base class for instruments.
`OPTICAM_MX`	OAN-SPM OPTICAM-MX instrument.
`MEFSlice`	Helper class to represent a slice of a Multi-extension FITS (MEF) file.
`AperturePhotometer`	A photometer for performing aperture photometry.
`OptimalPhotometer`	A photometer that implements the optimal photometry method described in Naylor 1998, MNRAS, 296, 339-346.
`Reducer`	Class for reducing astronomical images.

Functions

`generate_instrument_json_template`(out_directory)	Generate a template JSON file that can be used to define an Instrument.
`generate_flats`(out_directory[, n_flats, ...])	Create synthetic flat-field images.
`generate_observations`(out_directory[, n_images, ...])	Create synthetic observation data for testing and following the tutorials.
`generate_gappy_observations`(out_directory[, n_images, ...])	Create synthetic observation data for testing and following the tutorials.
`scan_data`(out_directory, data_directory, instrument[, ...])	Check that the data are self-consistent.

Package Contents

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 (pathlib.Path | str)
light_curves (astropy.timeseries.TimeSeries | None)
norm (Literal['max', 'mean', 'none'])
prefix (str | None)
phot_label (str | None)
show_plots (bool)

norm = 'mean'

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(time_bin_size, method='mean')

Rebin the light curves, propagating errors accordingly. Returns a new Analyzer instance containing the binned light curves. Rebinning uses a common reference time to ensure simultaneity between multiple light curves.

Parameters

time_bin_sizeQuantity: The time bin size.
methodLiteral[‘mean’, ‘sum’], optional: The type of binning, by default ‘mean’.

Returns

Analyzer: A new Analyzer instance containing the binned light curves.

Parameters:

time_bin_size (astropy.units.quantity.Quantity)
method (Literal['mean'])

Return type:

Analyzer

get_lc(key)

Return the light curve for a single key.

Parameters

keystr: The camera:filter key (e.g., “1:g” for camera 1 with a g filter).

Returns

TimeSeries: The light curve for the key.

Parameters:: key (str)
Return type:: astropy.timeseries.TimeSeries

plot(save=True, return_fig=False)

Plot the light curves.

Parameters

savebool, optional: Whether to save the plot, by default True.
return_figbool, optional: Whether to return the resulting Figure instance, by default False. This can be used to make edits to the plot.

Returns

Figure | None: The figure containing the light curves.

Parameters:

save (bool)
return_fig (bool)

Return type:

matplotlib.figure.Figure | None

fold(period, epoch_time=None, nbins=None, sharey=False, save=True, return_fig=False)

Fold the light curves on the given period.

Parameters

periodQuantity: The period used to fold the light curves. Must have units of time.
epoch_timeTime | None, optional: The reference time that defines zero phase, by default None. If None, the first time light curve time value is used.
nbinsint | None, optional: Bin the folded light curve into this many bins, by default None. If None, no binning is performed.
shareybool, optional: Whether to share y axes, by default False.
savebool, optional: Whether to save the figure, by default True.
return_figbool, optional: Whether to return the figure, by default False. Useful if you want to edit the figure before saving.

Returns

Table | tuple[Table, Figure]: If return_fig=True, the folded light curve and resulting figure are returned. Otherwise, just the folded time series is returned. The folded light curve is converted from a TimeSeries to a Table since the fold() method of TimeSeries replaces the time column with phase values, causing time formatting errors.

Parameters:

period (astropy.units.quantity.Quantity)
epoch_time (astropy.time.Time | None)
nbins (int | None)
sharey (bool)
save (bool)
return_fig (bool)

Return type:

astropy.table.Table | tuple[astropy.table.Table, matplotlib.figure.Figure]

lomb_scargle(frequency=None, scale='linear', save=True, return_fig=False)

Compute the Lomb-Scargle periodogram for each light curve.

Parameters

frequencyQuantity | None, optional: The frequency grid, by default None. If None, the autofrequency() method of astropy’s LombScargle class is used to generate a frequency grid.
scaleLiteral['linear', 'semilogx', 'semilogy', 'loglog'], optional: The scale for the resulting plot, by default ‘linear’.
savebool, optional: Whether to save the resulting plot, by default True.
return_figbool, optional: Whether to return the figure, by default False. Useful if you want to edit the figure before saving.

Returns

dict[str, LombScargle] | tuple[dict[str, LombScargle], Figure]: If return_fig=True, the Lomb-Scargle periodograms and figure are returned. Otherwise, only the Lomb-Scargle periodograms are returned.

Parameters:

frequency (astropy.units.quantity.Quantity | None)
scale (Literal['linear', 'semilogx', 'semilogy', 'loglog'])
save (bool)
return_fig (bool)

Return type:

dict[str, astropy.timeseries.LombScargle] | tuple[dict[str, astropy.timeseries.LombScargle], matplotlib.figure.Figure]

multiband_lomb_scargle(frequency=None, scale='linear', save=True, return_fig=False)

Compute the multiband Lomb-Scargle periodogram from all light curves.

Parameters

frequencyQuantity | None, optional: The frequency grid, by default None. If None, the autofrequency() method of astropy’s LombScargleMultiband class is used to generate a frequency grid.
scaleLiteral['linear', 'semilogx', 'semilogy', 'loglog'], optional: The scale for the resulting plot, by default ‘linear’.
savebool, optional: Whether to save the resulting plot, by default True.
return_figbool, optional: Whether to return the figure, by default False. Useful if you want to edit the figure before saving.

Returns

LombScargleMultiband | tuple[LombScargleMultiband, Figure]: If return_fig=True, the multiband Lomb-Scargle periodogram and figure are returned. Otherwise, only the multiband Lomb-Scargle periodogram is returned.

Parameters:

frequency (astropy.units.quantity.Quantity | None)
scale (Literal['linear', 'semilogx', 'semilogy', 'loglog'])
save (bool)
return_fig (bool)

Return type:

astropy.timeseries.LombScargleMultiband | tuple[astropy.timeseries.LombScargleMultiband, matplotlib.figure.Figure]

export_light_curves_to_stingray()

Export the light curves from an astropy.timeseries.TimeSeries table to a dictionary of stingray.Lightcurve instances.

Returns

dict[str, Lightcurve]: The light curves {filter: Lightcurve}.

Return type:: dict[str, stingray.Lightcurve]

class opticam.DifferentialPhotometer(out_directory, show_plots=True)

Helper class for creating relative light curves.

Parameters:

out_directory (pathlib.Path)
show_plots (bool)

out_directory

show_plots = True

keys

time_key = 'BMJD'

time_scale = 'tdb'

t_ref

catalogs

get_relative_light_curve(key, 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

keystr: The camera:filter key for which the relative light curve will be computed.
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:

key (str)
target (int)
comparisons (int | List[int])
phot_label (str)
prefix (str | None)
match_other_cameras (bool)
show_diagnostics (bool)

Return type:

opticam.analyzer.Analyzer

_compute_relative_light_curve(key, 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

keystr: The camera:filter key.
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

TimeSeries | 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:

key (str)
target (int)
comparisons (List[int])
prefix (str | None)
phot_label (str)
show_diagnostics (bool)

Return type:

astropy.timeseries.TimeSeries | None

_match_other_cameras(input_key, input_target, input_comparisons, prefix, phot_label, show_diagnostics)

Compute the relative light curves for all available filters.

Parameters

input_keystr: The input filter.
input_targetint: The target ID in the input filter’s catalog.
input_comparisonsList[int]: The comparison ID(s) in the input filter’s catalog.
prefixstr | None: The prefix to use when saving the relative light curve (e.g., the target source’s name).
phot_labelstr: The photometry label.
show_diagnosticsbool: Whether to show the diagnostic plots.

Returns

Tuple[TimeSeries, List[str]]: The light curves for all available filters and the list of filters that were successfully matched.

Parameters:

input_key (str)
input_target (int)
input_comparisons (List[int])
prefix (str | None)
phot_label (str)
show_diagnostics (bool)

Return type:

Tuple[astropy.timeseries.TimeSeries, List[str]]

_plot_diags(key, target, comparisons, target_df, comp_dfs, phot_label, show)

Plot a combination of diagnostic plots for the specified target and comparison sources.

Parameters

keystr: The image filter.
targetint: The target ID.
comparisonsList[int]: The comparison ID(s).
target_dfDataFrame: The target light curve.
comp_dfsList[DataFrame]: The comparison light curve(s).
phot_labelstr: The photometry label.
showbool: Whether to show the plots.

Parameters:

key (str)
target (int)
comparisons (List[int])
target_df (pandas.DataFrame)
comp_dfs (List[pandas.DataFrame])
phot_label (str)
show (bool)

Return type:

None

_plot_diag(key, comparison1, comparison2, comparison1_df, comparison2_df, phot_label, show)

Plot the relative diagnostic light curve for two comparison sources for a given filter.

Parameters

keystr: 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_dfDataFrame: The data frame of the first comparison source.
comparison2_dfDataFrame: The data frame of the second comparison source.
phot_labelstr: The photometry label.
showbool: Whether to show the diagnostic plot.

Parameters:

key (str)
comparison1 (int)
comparison2 (int)
comparison1_df (pandas.DataFrame)
comparison2_df (pandas.DataFrame)
phot_label (str)
show (bool)

Return type:

None

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.BiasCorrector(out_directory=None, data_directory=None, instrument=OPTICAM_MX(), rebin_factor=1, *args, **kwargs)

Bases: Corrector

Helper clsas for performing bias corrections.

Parameters:

out_directory (pathlib.Path | str | None)
data_directory (pathlib.Path | str | None)
instrument (opticam.instruments.Instrument)
rebin_factor (int)

property master_image_path: pathlib.Path | None

The path to the master calibration image.

Returns

Path: The path to the master calibration image.

Return type:: pathlib.Path | None

correct(image, camera)

Subtract the bias from an image.

Parameters

imageNDArray[np.float64]: The image.
camerastr: The camera that took the image.

Returns

tuple[NDArray[np.float64], NDArray[np.float64]]: The corrected image and the variance of the master bias image.

Raises

ValueError: If no bias images were found with the given filter.

Parameters:

image (numpy.typing.NDArray[numpy.float64])
camera (str)

Return type:

tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

create_master_images(overwrite=False)

Create master bias images for each filter.

Parameters

overwritebool, optional: Whether to overwrite the existing master bias image, by default False.

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

run_checks(data_files_by_key, return_errors=False)

Run a series of checks on the corrector to ensure that it is compatible with the data. In this case, check the binning of the science images matches those of the bias images (ignoring self.rebin_factor) and that there are no missing filters.

Parameters

data_files_by_keydict[str, list[MEFSlice]: The science image files grouped by camera:filter keys.
return_errorsbool, optional: Whether to return the number of errors raised, by default False.

Returns

None | int: If return_errors=True, the number of errors raised is returned. Otherwise, nothing is returned.

Parameters:

data_files_by_key (dict[str, list[opticam.mef_slice.MEFSlice]])
return_errors (bool)

Return type:

None | int

_validate_data(files)

Ensure that the bias images in the specified directory are valid (i.e., all use the same binning and have exposure times of 0 s).

Parameters

fileslist[MEFSlice]: The bias image files.

Returns

dict[str, list[MEFSlice]]: A dictionary containing the bias image files for each camera.

Parameters:: files (list[opticam.mef_slice.MEFSlice])
Return type:: dict[str, list[opticam.mef_slice.MEFSlice]]

class opticam.DarkNoiseCorrector(out_directory=None, data_directory=None, instrument=OPTICAM_MX(), rebin_factor=1, bias_corrector=None)

Bases: Corrector

Helper class for performing dark noise corrections.

Parameters:

out_directory (pathlib.Path | str | None)
data_directory (pathlib.Path | str | None)
instrument (opticam.instruments.Instrument)
rebin_factor (int)
bias_corrector (BiasCorrector | None)

bias_corrector = None

property master_image_path: pathlib.Path | None

The path to the master calibration image.

Returns

Path: The path to the master calibration image.

Return type:: pathlib.Path | None

correct(image, camera=None, fltr=None, key=None, dark_flux=None)

Subtract the dark noise from an image.

Parameters

imageNDArray[np.float64]: The image.
camerastr: The camera that took the image.
fltrstr: The image filter.
dark_fluxfloat | None, optional: The exposure-integrated dark current, by default None. If the instrument provides a measure of the dark current in the image header, this obviates the need for master darks.

Returns

NDArray[np.float64] | tuple[NDArray[np.float64], float]: The corrected image and the variance of the master dark image.

Raises

ValueError: If no dark images were found with the given filter.

Parameters:

image (numpy.typing.NDArray[numpy.float64])
camera (str | None)
fltr (str | None)
key (str | None)
dark_flux (float | None)

Return type:

tuple[numpy.typing.NDArray[numpy.float64], float | numpy.typing.NDArray[numpy.float64]]

create_master_images(overwrite=False)

Create master dark images for each available filter.

Parameters

overwritebool, optional: Whether to overwrite any existing master dark image, by default False.

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

run_checks(data_files_by_key, return_errors=False)

Run a series of checks on the corrector to ensure that it is compatible with the data. In this case, check the binning of the science images matches to those of the darks (neglecting self.rebin_factor), there are no missing filters, and the exposure times of the science images matches those of the darks.

Parameters

data_files_by_keydict[str, list[MEFSlice]: The science image files grouped by camera:filter keys.
return_errorsbool, optional: Whether to return the number of errors raised, by default False.

Returns

None | int: If return_errors=True, the number of errors raised is returned. Otherwise, nothing is returned.

Parameters:

data_files_by_key (dict[str, list[opticam.mef_slice.MEFSlice]])
return_errors (bool)

Return type:

None | int

_validate_data(files)

Ensure that the dark images in the specified directory are valid (i.e., all use the same binning).

Parameters

file_pathslist[MEFSlice]: The dark image files

Returns

dict[str, list[Path]]: A dictionary containing the dark image files for each filter.

Parameters:: files (list[opticam.mef_slice.MEFSlice])
Return type:: dict[str, list[opticam.mef_slice.MEFSlice]]

class opticam.FlatFieldCorrector(out_directory=None, data_directory=None, instrument=OPTICAM_MX(), rebin_factor=1, bias_corrector=None, dark_corrector=None)

Bases: Corrector

Helper class for performing flat-field corrections.

Parameters:

out_directory (pathlib.Path | str | None)
data_directory (pathlib.Path | str | None)
instrument (opticam.instruments.Instrument)
rebin_factor (int)
bias_corrector (BiasCorrector | None)
dark_corrector (DarkNoiseCorrector | None)

bias_corrector = None

dark_corrector = None

property master_image_path: pathlib.Path | None

The path to the master flat.

Returns

Path: The path to the master flat.

Return type:: pathlib.Path | None

correct(image, camera=None, fltr=None, key=None)

Correct an image for flat-fielding.

Parameters

imageNDArray[np.float64]: The image.
camerastr: The camera that took the image.
fltrstr: The image filter.

Returns

tuple[NDArray[np.float64], NDArray[np.float64]]: The corrected image and the variance of the master flat-field image scaled by the square of the calibrated image.

Parameters:

image (numpy.typing.NDArray[numpy.float64])
camera (str | None)
fltr (str | None)
key (str | None)

Return type:

tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

create_master_images(overwrite=False)

Create master flat-field images for each filter.

Parameters

bias_correctorBiasCorrector | None, optional: The bias corrector.
overwritebool, optional: Whether to overwrite the existing master flat-field image, by default False.

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

run_checks(data_files_by_key, return_errors=False)

Run a series of checks on the corrector to ensure that it is compatible with the data. In this case, check the binning of the science images can be matched to those of the flats (accounting for self.rebin_factor), and that the there are no missing filters.

Parameters

data_files_by_keydict[str, list[MEFSlice]]: The science images grouped by camera:filter keys.
return_errorsbool, optional: Whether to return the number of errors raised, by default False.

Returns

None | int: If return_errors=True, the number of errors raised is returned. Otherwise, nothing is returned.

Parameters:

data_files_by_key (dict[str, list[opticam.mef_slice.MEFSlice]])
return_errors (bool)

Return type:

None | int

_validate_data(files)

Ensure that the flat-field images in the specified directory are valid (i.e., all use the same binning).

Parameters

file_pathslist[MEFSlice]: The flat-field image files.

Returns

dict[str, list[MEFSlice]]: A dictionary containing the paths to the flat-field image files grouped by each filter.

Parameters:: files (list[opticam.mef_slice.MEFSlice])
Return type:: dict[str, list[opticam.mef_slice.MEFSlice]]

_dark_corrector_is_valid()

Check that the dark images have the same exposure time as the flat-field images.

Returns

tuple[bool, float, float]: If the exposure times are equal, returns True, 0., 0.,. Otherwise, returns False, flat_exposure_time, dark_exposure_time.

Return type:: tuple[bool, 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

opticam.generate_instrument_json_template(out_directory)

Generate a template JSON file that can be used to define an Instrument.

Parameters

out_directoryPath | str: The path to the directory to which the template is saved.

Parameters:: out_directory (pathlib.Path | str)
Return type:: None

class opticam.Instrument

Bases: abc.ABC

Base class for instruments.

Parameters

locationEarthLocation: The location of the observatory as an astropy.coordinates.EarthLocation object.
pixel_scalesdict[str, float]: The pixel scales for each camera in arcsec/pixel {camera: pixel scale}.
binning_kwstr, optional: The binning keyword, by default “BINNING”.
camera_kwstr, optional: The keyword that uniquely identifies the camera that took the image, by default “INSTRUME”. For single-camera instruments, this keyword doesn’t matter. For multi-camera instruments, however, it is used to apply calibrations like flats correctly.
dark_curr_kwstr, optional: The dark current keyword, by default “DARKCURR”. Dark current values are assumed to be in electrons/pixel.
dateobs_kwstr, optional: The observation date keyword, by default “DATE-OBS”. By default, observation dates are assumed to be in ISO 8601/FITS format (YYYY-MM-DDTHH:MM:SS[.sss]).
dec_kwstr, optional: The DEC keyword, by default “DEC”. DEC values are assumed to be in units of degrees.
exptime_kwstr, optional: The exposure time keyword, by default “EXPTIME”. Exposure times are assumed to be in units of seconds.
filter_kwstr, optional: The filter keyword, by default “FILTER”.
gain_kwstr, optional: The gain keyword, by default “GAIN”. Gain values are assumed to be in units of electrons/ADU.
ra_kwstr, optional: The RA keyword, by default “RA”. RA values are assumed to be in units of hour angle.
read_noise_kwstr, optional: The read noise keyword, by default “RDNOISE”.

location: astropy.coordinates.EarthLocation

pixel_scales: dict[str, float]

binning_kw: str = 'BINNING'

camera_kw: str = 'INSTRUME'

dark_curr_kw: str = 'DARKCURR'

dateobs_kw: str = 'DATE-OBS'

dec_kw: str = 'DEC'

exptime_kw: str = 'EXPTIME'

filter_kw: str = 'FILTER'

gain_kw: str = 'GAIN'

ra_kw: str = 'RA'

read_noise_kw: str = 'RDNOISE'

run_checks(file, return_errors=False)

Check that the instrument can be used to parse an image’s header.

Parameters

fileMEFSlice | Path: The file to use for checking the instrument. If a Path or str instance is specified, the first HDU of the corresponding FITS file is used.
return_errorsbool, optional: Whether to return the number of errors raised, by default False.

Returns

None | int: If return_errors=True, returns the number of errors raised. Otherwise, nothing is returned.

Raises

ValueError: If the header of the file could not be read.

Parameters:

file (opticam.mef_slice.MEFSlice | pathlib.Path)
return_errors (bool)

Return type:

None | int

get_mjd(file=None, header=None)

Given the path to a FITS file, or its header, parse its observation date into local Modified Julian Date (MJD).

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

float: The local MJD of the image.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

float

get_camera(file=None, header=None)

Given the path to a FITS file, get the corresponding camera.

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

str: A unique identifier for the camera.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

str

get_sky_coord(file=None, header=None)

Given the path to a FITS file, get the corresponding sky coordinates.

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

SkyCoord: The sky coordinates of the image.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

astropy.coordinates.SkyCoord

get_dark_flux(file=None, header=None)

Given the path to a FITS file, get the corresponding dark flux (i.e., the exposure-integrated dark current). If the instrument does not list a dark current in the image headers, the returned dark flux can be None.

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

float | None: The dark flux in the image.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

float | None

get_binning(file=None, header=None)

Get the binning of an image using the instrument’s binning_kw attribute.

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

str: The binning of the image.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

str

get_filter(file=None, header=None)

Get the filter of an image using the instrument’s filter_kw attribute.

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

str: The filter of the image.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

str

get_read_noise(file=None, header=None)

Get the read noise in an image, in electrons per pixel, using the instrument’s read_noise_kw attribute.

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

float: The read noise in the image.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

float

classmethod from_json(file_path=None, config=None)

Create an instrument from a configuration file/dictionary.

Parameters

file_pathPath | str | None, optional: The path to the configuration file, by default None. If None, a dictionary must be passed to config. If a value is passed to file_path, config is ignored.
configdict[str, Any] | None, optional: The configuration dictionary, by default None. If None, a path must be passed to file_path. If a value is passed to file_path, config is ignored.

Returns

Instrument: The configured instrument.

Raises

AssertionError: If required keys are missing from the configuration file/dictionary.

Parameters:

file_path (pathlib.Path | str | None)
config (dict[str, Any] | None)

Return type:

Instrument

to_json(file_path)

Export the instrument configuration to a JSON file.

Parameters

file_pathPath | str: The location to which the file is written. If save_path does not include the file name, the file will be saved as instrument_config.json.

Parameters:: file_path (pathlib.Path | str)
Return type:: None

class opticam.OPTICAM_MX(location=EarthLocation.from_geodetic(lon=-115.463611 * u.deg, lat=31.044167 * u.deg, height=2790 * u.m), pixel_scales={'1': 0.1397, '2': 0.1406, '3': 0.1661}, dateobs_kw='UT', exptime_kw='EXPOSURE')

Bases: Instrument

OAN-SPM OPTICAM-MX instrument.

get_mjd(file=None, header=None)

Get the timestamp of the image in MJD. OPTICAM uses a “UT” keyword to represent an image’s timestamp in ISO format.

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

float: The timestamp of the image in MJD format.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

float

get_camera(file=None, header=None)

Given the path to a FITS file, get the corresponding camera.

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

str: A unique identifier for the camera.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

str

get_read_noise(file=None, header=None)

Get the read noise in an image, in electrons per pixel, using the instrument’s read_noise_kw attribute.

Parameters

fileMEFSlice | None, optional: The MEFSlice instance corresponding to the file, by default None. If None, a Header must be passed to header instead.
headerHeader, optional: The header of the FITS file, by default None. If None, a MEFSlice must be passed to file instead.

Returns

float: The read noise in the image.

Parameters:

file (opticam.mef_slice.MEFSlice | None)
header (astropy.io.fits.Header | None)

Return type:

float

class opticam.MEFSlice

Helper class to represent a slice of a Multi-extension FITS (MEF) file.

Parameters

pathPath: The file path.
extint: The slice’s extension number.

path: pathlib.Path

ext: int

property key: str

The file path and extension number combined to create a uniquely identifiable string.

Returns

str: The uniquely identifiable string.

Return type:: str

get_header()

Get the slice’s header.

Returns

Header: The slice’s header.

Return type:: astropy.io.fits.Header

get_data()

Get the slice’s data.

Returns

NDArray[np.float64]: The slice’s data.

Return type:: numpy.typing.NDArray[numpy.float64]

get_data_and_header()

Get the slice’s data and header.

Returns

tuple[NDArray[np.float64], Header]: The slice’s data and header.

Return type:: tuple[numpy.typing.NDArray[numpy.float64], astropy.io.fits.Header]

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, bias_var, dark_var, flat_var, background_rms, cat_coords, image_coords, psf_params, read_noise)

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.
bias_varfloat | NDArray: The bias correction variance term.
dark_varfloat | NDArray: The dark noise correction variance term.
flat_varfloat | NDArray: The flat-field correction variance term scaled by the square of the calibrated image.
background_rmsNDArray | None: The background RMS. May be None if self.local_background_estimator is defined.
cat_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).
read_noisefloat: The detector’s read noise.

Returns

Dict[str, List]: The photometry results.

Parameters:

image (numpy.typing.NDArray)
bias_var (float | numpy.typing.NDArray)
dark_var (float | numpy.typing.NDArray)
flat_var (float | numpy.typing.NDArray)
background_rms (numpy.typing.NDArray | None)
cat_coords (numpy.typing.NDArray)
image_coords (numpy.typing.NDArray | None)
psf_params (Dict[str, float])
read_noise (float)

Return type:

Dict[str, List]

compute_aperture_flux(image, bias_var, dark_var, flat_var, background_rms, position, psf_params, read_noise)

Compute the aperture flux of a source in the image.

Parameters

imageNDArray: The image.
bias_varfloat | NDArray: The bias correction variance term.
dark_varfloat | NDArray: The dark noise correction variance term.
flat_varfloat | NDArray: The flat-field correction variance term scaled by the square of the calibrated image.
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).
read_noisefloat: The instrument’s read noise.

Returns

Tuple[float, float] | Tuple[float, float, float, float, float]: The flux and its error. If local_background_estimator is defined, the local background and its error are also returned.

Parameters:

image (numpy.typing.NDArray)
bias_var (float | numpy.typing.NDArray)
dark_var (float | numpy.typing.NDArray)
flat_var (float | numpy.typing.NDArray)
background_rms (numpy.typing.NDArray | None)
position (numpy.typing.NDArray)
psf_params (Dict[str, float])
read_noise (float)

Return type:

Tuple[float, float] | Tuple[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, bias_var, dark_var, flat_var, background_rms, cat_coords, image_coords, psf_params, read_noise)

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.
bias_varfloat | NDArray: The bias correction variance term.
dark_varfloat | NDArray: The dark noise correction variance term.
flat_varfloat | NDArray: The flat-field correction variance term scaled by the square of the calibrated image.
background_rmsNDArray | None: The background RMS. May be None if self.local_background_estimator is defined.
cat_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).
read_noisefloat: The detector’s read noise.

Returns

Dict[str, List]: The photometry results.

Parameters:

image (numpy.typing.NDArray)
bias_var (float | numpy.typing.NDArray[numpy.float64])
dark_var (float | numpy.typing.NDArray[numpy.float64])
flat_var (float | numpy.typing.NDArray[numpy.float64])
background_rms (numpy.typing.NDArray | None)
cat_coords (numpy.typing.NDArray)
image_coords (numpy.typing.NDArray | None)
psf_params (Dict[str, float])
read_noise (float)

Return type:

Dict[str, List]

compute_optimal_flux(image, bias_var, dark_var, flat_var, background_rms, position, psf_params, read_noise)

Compute the optimal flux of a source in the image as described in Naylor 1998, MNRAS, 296, 339-346.

Parameters

imageNDArray: The image.
bias_varfloat | NDArray: The bias correction variance term.
dark_varfloat | NDArray: The dark noise correction variance term.
flat_varfloat | NDArray: The flat-field correction variance term scaled by the square of the calibrated image.
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).
read_noisefloat: The instrument’s read noise.

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)
bias_var (float | numpy.typing.NDArray[numpy.float64])
dark_var (float | numpy.typing.NDArray[numpy.float64])
flat_var (float | numpy.typing.NDArray[numpy.float64])
background_rms (numpy.typing.NDArray | None)
position (numpy.typing.NDArray)
psf_params (Dict[str, float])
read_noise (float)

Return type:

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

class opticam.Reducer(out_directory, data_directory, aperture_selector=np.median, background=None, barycenter=True, bias_corrector=None, dark_corrector=None, finder=None, flat_corrector=None, instrument=OPTICAM_MX(), number_of_processors=cpu_count() // 2, rebin_factor=1, remove_cosmic_rays=False, show_plots=True, threshold=5, verbose=True)

Class for reducing astronomical images.

Parameters:

out_directory (pathlib.Path | str)
data_directory (pathlib.Path | str)
aperture_selector (Callable)
background (opticam.background.global_background.BaseBackground | None)
barycenter (bool)
bias_corrector (opticam.correctors.BiasCorrector | None)
dark_corrector (opticam.correctors.DarkNoiseCorrector | None)
finder (None | Callable)
flat_corrector (opticam.correctors.FlatFieldCorrector | None)
instrument (opticam.instruments.Instrument)
number_of_processors (int)
rebin_factor (int)
remove_cosmic_rays (bool)
show_plots (bool)
threshold (float)
verbose (bool)

verbose = True

out_directory

logger

data_directory

rebin_factor = 1

instrument

aperture_selector

threshold = 5

remove_cosmic_rays = False

barycenter = True

number_of_processors

show_plots = True

bias_corrector = None

dark_corrector = None

flat_corrector = None

reference_files

transforms

unaligned_files = []

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

psf_params

_log_params()

Log the input parameters of a Reducer instance to file.

Parameters

reducerReducer: The Reducer instance.

Return type:: None

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

_align_batch(batch, reference_image_shape, reference_coords, transform_type, rotation_limit, scale_limit, translation_limit, n_alignment_sources)

Align a batch of images with respect to some reference coordinates.

Parameters

batch: list[MEFSlice]: The files.
reference_image_shapetuple[int]: The reference image’s shape.
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_limitlist[float] | None: The maximum translation limit for image alignment.
n_alignment_sourcesint: The (maximum) number of sources to use for image alignment.

Returns

tuple[NDArray[np.float64], dict[str, list[float]], dict[str, dict[str, float]], list[tuple[str, str]]]: The stacked image, transforms, background results, and log messages.

Parameters:

batch (list[opticam.mef_slice.MEFSlice])
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 (list[float] | None)
n_alignment_sources (int)

Return type:

tuple[numpy.typing.NDArray[numpy.float64], dict[str, list[float]], dict[str, dict[str, float]], list[tuple[str, str]]]

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

Find whether a transform is valid given some transform limits.

Parameters

fileMEFSlice: The path to the file being transformed.
transformSimilarityTransform: The transform.
rotation_limitfloat | None: The rotation limit.
scale_limitfloat | None: The scale limit.
translation_limitlist[float] | None: The translation limit.

Returns

tuple[bool, None | tuple[str, str]]: Whether the transform is valid. If not, a log message is also returned as a tuple: (log level, log string).

Parameters:

file (opticam.mef_slice.MEFSlice)
transform (skimage.transform.SimilarityTransform)
rotation_limit (float | None)
scale_limit (float | None)
translation_limit (list[float] | None)

Return type:

tuple[bool, None | tuple[str, str]]

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’: [1, 2, 3], ‘r’: [1, 2, 3], ‘i’: [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/*_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’: [1, 2, 3], ‘r’: [1, 2, 3], ‘i’: [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

_perform_photometry(file, photometer, cat_coords, key)

Perform photometry on a file.

Parameters

fileMEFSlice: The file.
photometerBasePhotometer: The photometer to use.
cat_coordsNDArray: The coordinates of the sources in the catalog.
keystr: The camera:filter key.

Returns

dict[str, list]: The photometry results.

Parameters:

file (opticam.mef_slice.MEFSlice)
photometer (opticam.photometers.BasePhotometer)
cat_coords (numpy.typing.NDArray)
key (str)

Return type:

dict[str, list]

update_unaligned_files(files)

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

Parameters

filesMEFSlice | list[MEFSlice]: The file or files.

Parameters:: files (opticam.mef_slice.MEFSlice | list[opticam.mef_slice.MEFSlice])
Return type:: None

opticam.generate_flats(out_directory, n_flats=5, binning_scale=4, overwrite=False)

Create synthetic flat-field images.

Parameters

out_directoryPath | str: 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_directory (pathlib.Path | str)
n_flats (int)
binning_scale (int)
overwrite (bool)

Return type:

None

opticam.generate_observations(out_directory, n_images=100, circular_aperture=True, binning_scale=4, overwrite=False)

Create synthetic observation data for testing and following the tutorials.

Parameters

out_directoryPath | str: 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_directory (pathlib.Path | str)
n_images (int)
circular_aperture (bool)
binning_scale (int)
overwrite (bool)

Return type:

None

opticam.generate_gappy_observations(out_directory, n_images=1000, circular_aperture=True, binning_scale=4, overwrite=False)

Create synthetic observation data for testing and following the tutorials.

Parameters

out_directoryPath | str: 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_directory (pathlib.Path | str)
n_images (int)
circular_aperture (bool)
binning_scale (int)
overwrite (bool)

Return type:

None

opticam.scan_data(out_directory, data_directory, instrument, barycenter=True, verbose=True, return_output=False, logger=None, number_of_processors=cpu_count() // 2)

Check that the data are self-consistent.

Parameters

out_directoryPath | str: The path to the directory in which output files will be saved.
data_directoryPath | str: The path to the directory containing the data.
instrumentInstrument: The instrument that produced the data.
barycenterbool, optional: Whether to apply a Barycentric correction to the image time stamps, by default True. Only relevant if return_output=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, list[MEFSlice]], int, dict[str, float], list[MEFSlice], float]:: If return_output=True, the files grouped by camera, binning scale, Barycentric MJD dates, ignored files, and the reference date are returned. Otherwise, nothing is returned.

Parameters:

out_directory (pathlib.Path | str)
data_directory (pathlib.Path | str)
instrument (opticam.instruments.Instrument)
barycenter (bool)
verbose (bool)
return_output (bool)
logger (logging.Logger | None)

Return type:

None | tuple[dict[str, list[opticam.mef_slice.MEFSlice]], int, dict[str, float], list[opticam.mef_slice.MEFSlice], float]