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.

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.

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

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

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, 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. Default is False.
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 files (e.g. ‘sci_img_*.fits’ or ‘sci_img*[!proc].fits’).