potpyri.instruments.instrument

Base instrument class and shared reduction logic for POTPyRI.

Defines detector keywords, calibration flags, file naming, and methods for importing/processing science frames, building master bias/dark/flat, and loading static masks. Subclasses (GMOS, LRIS, BINOSPEC, etc.) set instrument-specific attributes.

Functions

fix_deprecated_wcs_header_cards(header)

Normalize WCS-related FITS cards before WCS parses the header.

Classes

Instrument()

Base class for all POTPyRI instruments.

class potpyri.instruments.instrument.Instrument[source]

Bases: object

Base class for all POTPyRI instruments.

Holds detector parameters (gain, rdnoise, pixscale, saturation), header keyword names, file-sorting rules, and methods for calibration and science processing. Subclasses override attributes as needed.

PROC_FITS_ALIASES = frozenset({'.fits', 'fits', 'uncompressed'})

PROC_FITS_GLOB = '*.fits'

apply_optical_background_subtraction(processed_data, bkg_sub='local', save_bkg=False, paths=None, log=None)[source]

Subtract per-frame background for optical data (not NIR master sky).

Parameters:

processed_data (ccdproc.CCDData) – Bias/dark/flat-corrected science frame with mask set.
bkg_sub (str, optional) – 'local' (default): photutils Background2D mesh model. 'constant': single sigma-clipped median subtracted from every pixel. 'none': no subtraction; SKYBKG set to 0.
save_bkg (bool, optional) – If True and bkg_sub='local', write the 2D background model.
paths (dict, optional) – Paths dict (work key) required when save_bkg is True.
log (ColoredLogger, optional) – Logger for progress.

Returns:

Background-subtracted frame with SKYBKG and BKGSUB header keys.

Return type:

ccdproc.CCDData

create_bias(bias_list, amp, binn, paths, log=None, **kwargs)[source]

Combine bias frames into master bias and write to paths[‘cal’].

Parameters:

bias_list (list of str) – Paths to bias FITS files.
amp (str) – Amplifier identifier.
binn (str) – Binning string.
paths (dict) – Paths dict (cal key).
log (ColoredLogger, optional) – Logger for progress.
**kwargs – Unused; for subclass compatibility.

Returns:

Master bias written via get_mbias_name.

Return type:

None

create_dark(dark_list, amp, binn, paths, mbias=None, log=None)[source]

Combine dark frames (with optional bias subtraction) and write master dark.

Parameters:

dark_list (list of str) – Paths to dark FITS files.
amp (str) – Amplifier identifier.
binn (str) – Binning string.
paths (dict) – Paths dict (cal key).
mbias (ccdproc.CCDData, optional) – Master bias to subtract before combining.
log (ColoredLogger, optional) – Logger for progress.

Returns:

Master dark written via get_mdark_name.

Return type:

None

create_flat(flat_list, fil, amp, binn, paths, mbias=None, mdark=None, is_science=False, log=None, **kwargs)[source]

Combine flat frames (bias/dark subtract, normalize) and write master flat.

Parameters:

flat_list (list of str) – Paths to flat FITS files.
fil (str) – Filter name.
amp (str) – Amplifier identifier.
binn (str) – Binning string.
paths (dict) – Paths dict (cal key).
mbias (ccdproc.CCDData, optional) – Master bias to subtract.
mdark (ccdproc.CCDData, optional) – Master dark to subtract.
is_science (bool, optional) – If True, mask high pixels as for science. Default is False.
log (ColoredLogger, optional) – Logger for progress.
**kwargs – Unused; for subclass compatibility.

Returns:

Master flat written via get_mflat_name.

Return type:

None

create_sky(sky_list, fil, amp, binn, paths, log=None, sky_sigma_upper=3.0, sky_sigma_lower=4.0, sky_maxiters=5, sky_n_sigma_high=3.0, sky_n_sigma_low=4.0, msky_n_sigma_high=5.0, msky_n_sigma_low=5.0, msky_maxiters=5, **kwargs)[source]

Combine sky frames (normalize by median) and write master sky.

Uses iterative sigma clipping to estimate the sky background and mask bright sources (and optionally low outliers) so the median is not biased. Per-frame and combined master sky masking use configurable sigma and iteration limits.

Parameters:

sky_list (list of str) – Paths to sky FITS files.
fil (str) – Filter name.
amp (str) – Amplifier identifier.
binn (str) – Binning string.
paths (dict) – Paths dict (cal key).
log (ColoredLogger, optional) – Logger for progress.
sky_sigma_upper (float, optional) – Upper sigma for iterative clip when estimating per-frame sky. Default 3.0.
sky_sigma_lower (float, optional) – Lower sigma for iterative clip when estimating per-frame sky. Default 4.0.
sky_maxiters (int, optional) – Max iterations for sigma clipping per sky frame. Default 5.
sky_n_sigma_high (float, optional) – Mask pixels above med + this many * std (bright sources). Default 3.0.
sky_n_sigma_low (float, optional) – Mask pixels below med - this many * std (defects). Default 4.0.
msky_n_sigma_high (float, optional) – Mask master sky pixels above median + this * std. Default 5.0.
msky_n_sigma_low (float, optional) – Mask master sky pixels below median - this * std. Default 5.0.
msky_maxiters (int, optional) – Max iterations for sigma clipping on combined master sky. Default 5.
**kwargs – Unused; for subclass compatibility.

Returns:

Master sky written via get_msky_name.

Return type:

None

discover_raw_files(paths, proc=None)[source]

Glob raw inputs under paths['raw'], paths['data'], and paths['bad'].

Returns:: pattern, instrument_pattern, proc, proc_fits_override, per_dir (list of label, directory, glob_path, matched paths), and files (combined matches).
Return type:: dict

expand_mask(input_data, input_mask=None)[source]

Build combined mask from NaN, inf, zero pixels and optional input mask.

Parameters:

input_data (ccdproc.CCDData) – Image data (input_data.data used).
input_mask (np.ndarray, optional) – Boolean mask to OR with bad-pixel mask.

Returns:

Boolean mask (True = bad).

Return type:

np.ndarray

format_datasec(sec_string, binning=1)[source]

Convert datasec string to binned pixel bounds (e.g. ‘[1:100,1:200]’).

Parameters:

sec_string (str) – Data section string like ‘[x1:x2,y1:y2]’.
binning (int, optional) – Binning factor. Default is 1.

Returns:

Reformatted section string with binned limits.

Return type:

str

format_raw_discovery_message(paths, proc=None)[source]: Human-readable summary of where raw files are searched and what matched.

get_ampl(hdr)[source]: Return amplifier identifier from header as string.

get_binning(hdr)[source]: Return binning string from header (e.g. ‘11’, ‘22’), normalized and no ‘x’.

get_bkg_name(hdr, red_path)[source]: Return full path for background FITS (sci name with _bkg.fits).

get_catalog(hdr)[source]: Return catalog name for zeropoint (e.g. ‘PS1’).

get_exptime(hdr)[source]: Return exposure time from header (exptime_keyword).

get_filter(hdr)[source]: Return filter name from header; leading segment before underscore.

get_gain(hdr)[source]

Return gain value(s) for the detector/amplifier.

Parameters:: hdr (astropy.io.fits.Header) – FITS header (may be used in subclasses for amp-dependent values).
Returns:: Gain in e-/ADU.
Return type:: float or list

get_instrument_name(hdr)[source]: Return instrument name (lowercase) for paths/filenames.

get_mbias_name(paths, amp, binn)[source]: Return path for master bias FITS (paths[‘cal’]/mbias_amp_binn.fits).

get_mdark_name(paths, amp, binn)[source]: Return path for master dark FITS.

get_mflat_name(paths, fil, amp, binn)[source]: Return path for master flat FITS (filter, amp, binning).

get_msky_name(paths, fil, amp, binn)[source]: Return path for master sky FITS.

get_out_size(hdr)[source]: Return output image size (pixels) for this binning (out_size / binn).

get_pixscale()[source]

Return pixel scale in arcsec/pixel.

Returns:: Pixel scale; may vary by mode in subclasses.
Return type:: float or None

get_rdnoise(hdr)[source]

Return read noise value(s) for the detector/amplifier.

Parameters:: hdr (astropy.io.fits.Header) – FITS header (may be used in subclasses for amp-dependent values).
Returns:: Read noise in electrons.
Return type:: float or list

get_sci_name(hdr, red_path)[source]: Return full path for single-extension science FITS.

get_staticmask_filename(hdr, paths)[source]

Return path(s) to the static bad-pixel mask FITS for this instrument/binning.

Parameters:

hdr (astropy.io.fits.Header) – FITS header (for binning and instrument).
paths (dict) – Paths dict with ‘code’ key (package root).

Returns:

One-element list with path to staticmask FITS, or [None] if not found.

Return type:

list

get_stk_name(hdr, red_path)[source]: Return full path for stacked output FITS (target.filter.utYYMMDD.amp.binn.stk.fits).

get_target(hdr)[source]: Return target name from header (target_keyword), spaces stripped.

get_time(hdr)[source]: Return MJD from header (mjd_keyword) as float.

import_image(filename, amp, log=None)[source]

Load raw multi-extension FITS and return processed CCDData (bias/overscan/trim/gain).

Parameters:

filename (str) – Path to raw FITS file.
amp (str) – Amplifier identifier (number of extensions).
log (ColoredLogger, optional) – Logger for progress.

Returns:

Processed frame in electrons (single combined image).

Return type:

ccdproc.CCDData

import_sci_image(filename, log=None)[source]

Load a single science FITS as CCDData (no overscan/trim; already reduced).

Parameters:

filename (str) – Path to FITS file.
log (ColoredLogger, optional) – Logger for progress.

Returns:

Science frame.

Return type:

ccdproc.CCDData

load_bias(paths, amp, binn)[source]

Load master bias CCDData for given amp and binning.

Parameters:

paths (dict) – Paths dict (cal key).
amp (str) – Amplifier identifier.
binn (str) – Binning string.

Returns:

Master bias in electrons.

Return type:

ccdproc.CCDData

Raises:

Exception – If master bias file not found.

load_dark(paths, amp, binn)[source]

Load master dark CCDData for given amp and binning.

Parameters:

paths (dict) – Paths dict (cal key).
amp (str) – Amplifier identifier.
binn (str) – Binning string.

Returns:

Master dark in electrons.

Return type:

ccdproc.CCDData

Raises:

Exception – If master dark file not found.

load_flat(paths, fil, amp, binn)[source]

Load master flat CCDData for given filter, amp, and binning.

Parameters:

paths (dict) – Paths dict (cal key).
fil (str) – Filter name.
amp (str) – Amplifier identifier.
binn (str) – Binning string.

Returns:

Master flat (normalized).

Return type:

ccdproc.CCDData

Raises:

Exception – If master flat file not found.

load_sky(paths, fil, amp, binn)[source]

Load master sky CCDData for given filter, amp, and binning.

Parameters:

paths (dict) – Paths dict (cal key).
fil (str) – Filter name.
amp (str) – Amplifier identifier.
binn (str) – Binning string.

Returns:

Master sky (normalized).

Return type:

ccdproc.CCDData

Raises:

Exception – If master sky file not found.

load_staticmask(hdr, paths)[source]

Load the static mask array for this instrument and binning.

Parameters:

hdr (astropy.io.fits.Header) – FITS header (for binning and instrument name).
paths (dict) – Paths dict with ‘code’ key.

Returns:

Boolean mask from static mask FITS extension [1], or None if not found.

Return type:

np.ndarray or None

match_type_keywords(kwds, file_table)[source]

Return a boolean mask of file_table rows whose Type is in kwds.

Parameters:

kwds (str) – Comma-separated type names (e.g. ‘SCIENCE’, ‘FLAT’).
file_table (astropy.table.Table) – File list table with ‘Type’ column.

Returns:

Boolean mask, True where file_table[‘Type’] is in kwds.

Return type:

np.ndarray

needs_sky_subtraction(filt)[source]

Return True if sky subtraction should be run for this filter.

Parameters:: filt (str) – Filter name (e.g. ‘r’, ‘J’).
Returns:: True for NIR wavelength instruments, False otherwise.
Return type:: bool

process_science(sci_list, fil, amp, binn, paths, mbias=None, mflat=None, mdark=None, skip_skysub=False, bkg_sub='local', save_bkg=False, log=None)[source]

Reduce science frames: bias/dark/flat, optional sky subtraction; return CCDData list.

Parameters:

sci_list (list of str) – Paths to science FITS files.
fil (str) – Filter name.
amp (str) – Amplifier identifier.
binn (str) – Binning string.
paths (dict) – Paths dict (work, cal, etc.).
mbias (ccdproc.CCDData, optional) – Master bias.
mflat (ccdproc.CCDData, optional) – Master flat.
mdark (ccdproc.CCDData, optional) – Master dark.
skip_skysub (bool, optional) – If True, skip 2D background subtraction. Deprecated; use bkg_sub='none'. Default is False.
bkg_sub (str, optional) – Per-frame background subtraction for optical data: 'local' (2D mesh, default), 'constant' (single value per frame), or 'none'. Ignored when needs_sky_subtraction(fil) is True (NIR / GMOS z-band use master sky instead).
save_bkg (bool, optional) – If True, save background model. Default is False.
log (ColoredLogger, optional) – Logger for progress.

Returns:

Reduced science frames (each with FILENAME in header).

Return type:

list of ccdproc.CCDData

raw_format(proc)[source]

Return glob pattern for raw file discovery under data/raw, data, bad.

If proc is fits / .fits / uncompressed, returns *.fits regardless of instrument. Otherwise delegates to _default_raw_format().

potpyri.instruments.instrument.fix_deprecated_wcs_header_cards(header)[source]

Normalize WCS-related FITS cards before WCS parses the header.

Archive and Gemini raw frames often use deprecated RADECSYS instead of RADESYS, and leave MJD-OBS in a form that makes WCSLib run datfix and emit FITSFixedWarning. Updating the header in place avoids those warnings without globally filtering them.

Parameters:: header (astropy.io.fits.Header) – Header to modify in place (pass a copy if the on-disk HDU must be unchanged).