stdpipe.pipeline module

Module containing higher-level pipeline building blocks, wrapping together lower-level functionality of STDPipe modules.

stdpipe.pipeline.make_mask(image, header=None, saturation=None, external_mask=None, mask_cosmics=False, gain=None, verbose=True)[source]

Make a basic mask for an image.

The mask is a boolean bitmap with True values marking regions to be excluded from further processing. The following regions are masked:

  • pixels with undefined or non-finite (inf or nan) values

  • regions outside the usable area defined by the DATASEC or TRIMSEC header keyword

  • pixels above the saturation limit, if provided

  • pixels set in the external mask, if provided

  • cosmic rays, if requested

If saturation=True, the saturation level is estimated from the image as median + 0.95 * (max - median).

Parameters:
imagendarray

2D image array to mask.

headerastropy.io.fits.Header, optional

FITS header; used to read DATASEC / TRIMSEC keywords.

saturationfloat or bool, optional

Saturation level in ADU. If True, estimated automatically from the image.

external_maskndarray, optional

Boolean mask to OR with the created mask.

mask_cosmicsbool, optional

If True, detect and mask cosmic rays using the LACosmic algorithm.

gainfloat, optional

Detector gain in e-/ADU, used for cosmic-ray masking.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

Returns:
ndarray of bool

Boolean mask with True marking excluded pixels.

stdpipe.pipeline.refine_astrometry(obj, cat, sr=0.002777777777777778, wcs=None, order=0, cat_col_mag='V', cat_col_mag_err=None, cat_col_ra='RAJ2000', cat_col_dec='DEJ2000', cat_col_ra_err='e_RAJ2000', cat_col_dec_err='e_DEJ2000', n_iter=3, use_photometry=True, min_matches=5, method='quadhash', update=True, refine_residual_field=False, residual_field_kwargs=None, verbose=False, **kwargs)[source]

Higher-level astrometric refinement routine.

Dispatches to quad-hash, SCAMP, astropy, or astrometrynet fitting depending on method.

Parameters:
objastropy.table.Table

List of objects on the frame, must contain at least x, y, and flux columns.

catastropy.table.Table or str

Reference astrometric catalogue.

srfloat, optional

Matching radius in degrees.

wcsastropy.wcs.WCS, optional

Initial WCS solution.

orderint, optional

Polynomial order for SIP or PV distortion solution. Default 0 for TAN; 2 is recommended for quadhash.

cat_col_magstr, optional

Catalogue column name for magnitude.

cat_col_mag_errstr, optional

Catalogue column name for magnitude error.

cat_col_rastr, optional

Catalogue column name for Right Ascension.

cat_col_decstr, optional

Catalogue column name for Declination.

cat_col_ra_errstr, optional

Catalogue column name for Right Ascension error.

cat_col_dec_errstr, optional

Catalogue column name for Declination error.

n_iterint, optional

Number of iterations for Python-based matching.

use_photometrybool, optional

Use photometry-assisted matching in Python-based methods.

min_matchesint, optional

Minimum number of good matches required.

methodstr, optional

Fitting method. One of 'quadhash' (default, 2–7× more accurate), 'scamp', 'astropy', or 'astrometrynet'.

updatebool, optional

If True, update ra and dec columns in obj in-place. When combined with refine_residual_field=True, x/y of obj are also corrected (their residual against the catalogue is subtracted) before ra/dec are recomputed from the refined positions.

refine_residual_fieldbool, optional

If True, after the WCS fit, fit a smooth (dx, dy) correction field on the matched obj–cat residuals using stdpipe.astrometry.refine_positions_from_catalog() and (if update=True) apply the inverse correction to obj['x'], obj['y'] in place.

residual_field_kwargsdict, optional

Forwarded to refine_positions_from_catalog(). Common keys: backend, image_shape, grid_shape, min_per_cell, smooth_sigma.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

**kwargs

All other keyword arguments are passed to the respective refinement function.

Returns:
astropy.wcs.WCS or None

Refined astrometric solution, or None on failure.

stdpipe.pipeline.filter_transient_candidates(obj, sr=None, pixscale=None, fwhm=None, time=None, obj_col_ra='ra', obj_col_dec='dec', cat=None, cat_col_ra='RAJ2000', cat_col_dec='DEJ2000', vizier=[], skybot=True, ned=False, flagged=True, flagmask=32512, col_id=None, vizier_checker_fn=None, get_candidates=True, remove=True, verbose=False)[source]

Higher-level transient candidate filtering routine.

Optionally filters out the following classes of objects:

  • flagged ones (obj['flags'] != 0)

  • positionally coincident with stars from a provided reference catalogue

  • positionally coincident with stars from Vizier catalogues

  • positionally and temporally coincident with Solar System objects from SkyBoT

  • positionally and temporally coincident with NED objects

The original object list is never modified; a filtered or annotated copy is returned.

If get_candidates=False, returns only a boolean mask of objects surviving all filters. If get_candidates=True and remove=False, all objects are returned but annotated with candidate_* columns indicating which filters matched each object, plus a candidate_good column that is True for objects surviving all filters.

Parameters:
objastropy.table.Table

Input object list.

srfloat, optional

Matching radius in degrees. Defaults to half FWHM (if pixscale is set) or 1 arcsec.

pixscalefloat, optional

Pixel scale in degrees/pixel. Used to compute the default matching radius.

fwhmfloat, optional

FWHM in pixels. Estimated from unflagged objects if not provided.

timeastropy.time.Time or datetime.datetime, optional

Observation time; required for SkyBoT cross-matching.

obj_col_rastr, optional

Column name for object Right Ascension.

obj_col_decstr, optional

Column name for object Declination.

catastropy.table.Table, optional

Reference catalogue for spatial cross-matching.

cat_col_rastr, optional

Column name for catalogue Right Ascension.

cat_col_decstr, optional

Column name for catalogue Declination.

vizierlist of str, optional

Vizier catalogue identifiers (or short names) to cross-match against.

skybotbool, optional

If True, cross-match with SkyBoT Solar System object positions.

nedbool, optional

If True, cross-match with NED database entries.

flaggedbool, optional

If True, filter out objects where (obj['flags'] & flagmask) != 0.

flagmaskint, optional

Bitmask applied to obj['flags'] for flag filtering.

col_idstr, optional

Column name for a unique object identifier. A stdpipe_id column is created automatically if not specified.

vizier_checker_fncallable, optional

Function fn(obj, xcat, catname) -> bool array to apply additional conditions on Vizier cross-matches before they are considered true matches.

get_candidatesbool, optional

If True (default), return the filtered/annotated object list. If False, return only a boolean mask over the original list.

removebool, optional

If True (default), remove filtered entries from the returned list. If False, keep all objects and add candidate_* annotation columns.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

Returns:
astropy.table.Table or ndarray of bool

Filtered/annotated copy of the object list, or (if get_candidates=False) a boolean mask of the same length as the input.

stdpipe.pipeline.calibrate_photometry(obj, cat, sr=None, pixscale=None, order=0, bg_order=None, obj_col_mag='mag', obj_col_mag_err='magerr', obj_col_ra='ra', obj_col_dec='dec', obj_col_flags='flags', obj_col_x='x', obj_col_y='y', cat_col_mag='R', cat_col_mag_err=None, cat_col_mag1=None, cat_col_mag2=None, cat_col_ra='RAJ2000', cat_col_dec='DEJ2000', update=True, verbose=False, **kwargs)[source]

Higher-level photometric calibration routine.

Wraps stdpipe.photometry.match() with convenient defaults for typical tabular data.

Parameters:
objastropy.table.Table

Table of detected objects.

catastropy.table.Table

Reference photometric catalogue.

srfloat, optional

Matching radius in degrees. Defaults to half the median FWHM in sky units if pixscale is provided, otherwise 1 arcsec.

pixscalefloat, optional

Pixel scale in degrees/pixel; used to compute the default matching radius.

orderint, optional

Spatial polynomial order for the zero-point model (0 = constant).

bg_orderint or None, optional

Spatial polynomial order for an additive flux background term. None disables this term.

obj_col_magstr, optional

Column name for object instrumental magnitude.

obj_col_mag_errstr, optional

Column name for object magnitude error.

obj_col_rastr, optional

Column name for object Right Ascension.

obj_col_decstr, optional

Column name for object Declination.

obj_col_flagsstr, optional

Column name for object flags.

obj_col_xstr, optional

Column name for object x coordinate.

obj_col_ystr, optional

Column name for object y coordinate.

cat_col_magstr, optional

Column name for catalogue magnitude.

cat_col_mag_errstr, optional

Column name for catalogue magnitude error.

cat_col_mag1str, optional

First catalogue magnitude column for the color term (e.g. 'B').

cat_col_mag2str, optional

Second catalogue magnitude column for the color term (e.g. 'R').

cat_col_rastr, optional

Column name for catalogue Right Ascension.

cat_col_decstr, optional

Column name for catalogue Declination.

updatebool, optional

If True, add mag_calib and mag_calib_err columns to obj in-place with the calibrated magnitude and its error.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

**kwargs

Additional keyword arguments passed to stdpipe.photometry.match().

Returns:
dict or None

Dictionary with photometric results as returned by stdpipe.photometry.match(), or None on failure.

stdpipe.pipeline.make_random_stars(width=None, height=None, shape=None, nstars=100, minflux=1, maxflux=100000, edge=0, wcs=None, verbose=False)[source]

Generate a table of random stars.

Coordinates are distributed uniformly with edge <= x < width - edge and edge <= y < height - edge. Fluxes are log-uniform between minflux and maxflux.

Parameters:
widthint, optional

Width of the image in pixels.

heightint, optional

Height of the image in pixels.

shapetuple of int, optional

Image shape (height, width); used instead of width and height if set.

nstarsint, optional

Number of artificial stars to generate.

minfluxfloat, optional

Minimum star flux in ADU.

maxfluxfloat, optional

Maximum star flux in ADU.

edgeint, optional

Minimum distance to image edges for star placement.

wcsastropy.wcs.WCS, optional

If provided, sky coordinates ra and dec are added to the catalogue.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

Returns:
astropy.table.Table

Catalogue with columns x, y, flux, mag, and optionally ra, dec if wcs is provided.

stdpipe.pipeline.place_random_stars(image, psf_model, nstars=100, minflux=1, maxflux=100000, gain=None, saturation=65535, edge=0, wcs=None, verbose=False)[source]

Randomly place artificial stars into an image in-place.

Stars are added on top of the existing image content. Poissonian noise is applied according to gain, and pixel values are clipped at saturation. Coordinates are uniformly distributed; fluxes are log-uniform.

Parameters:
imagendarray

2D image array; modified in-place.

psf_modeldict

PSF model structure as returned by stdpipe.psf.run_psfex().

nstarsint, optional

Number of artificial stars to inject.

minfluxfloat, optional

Minimum star flux in ADU.

maxfluxfloat, optional

Maximum star flux in ADU.

gainfloat, optional

Detector gain in e-/ADU; used to add Poissonian noise to each injected star.

saturationfloat, optional

Saturation level in ADU; injected pixels above this are clipped.

edgeint, optional

Minimum distance to image edges for star placement.

wcsastropy.wcs.WCS, optional

If provided, sky coordinates ra and dec are added to the catalogue.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

Returns:
astropy.table.Table

Catalogue of injected stars as returned by make_random_stars(), with columns x, y, flux, mag, and optionally ra, dec.

stdpipe.pipeline.split_sub_fn(x1, y1, dx1, dy1, *args, get_origin=False, **kwargs)[source]
stdpipe.pipeline.split_image(image, *args, nx=1, ny=None, overlap=0, xmin=None, xmax=None, ymin=None, ymax=None, get_index=False, get_origin=False, verbose=False, **kwargs)[source]

Generator that splits an image into nx × ny sub-image blocks.

Also optionally yields sub-setted copies of any additional images, FITS headers, WCS solutions, PSF models, catalogues, or object lists passed as positional or keyword arguments. FITS headers and WCS solutions are adjusted to reflect the sub-image astrometry. Tables are filtered to rows whose x/y, ra/dec, or RAJ2000/DEJ2000 coordinates fall inside the sub-image.

Sub-images may optionally overlap by overlap pixels in every direction, so that each part of the original image appears far from an edge in at least one block.

Parameters:
imagendarray

2D image to split.

*args

Additional images, headers, WCS objects, or tables to crop alongside image.

nxint, optional

Number of sub-images along the x axis.

nyint, optional

Number of sub-images along the y axis. Defaults to nx.

overlapint, optional

Number of pixels by which adjacent blocks overlap.

xmin, xmaxint, optional

Horizontal extent of the region to split (defaults to full image width).

ymin, ymaxint, optional

Vertical extent of the region to split (defaults to full image height).

get_indexbool, optional

If True, prepend the sub-image index (0-based) to each yielded list.

get_originbool, optional

If True, include the sub-image origin (x1, y1) in each yielded list.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

**kwargs

Additional images, headers, WCS objects, or tables to crop.

Yields:
list

Each element is a list built from (in order):

  • sub-image index, if get_index=True

  • origin x1, y1, if get_origin=True

  • cropped image

  • cropped versions of each *args and **kwargs entry

stdpipe.pipeline.get_subimage_centered(image, *args, x0=None, y0=None, width=None, height=None, get_origin=False, verbose=False, **kwargs)[source]

Crop a sub-image centered at a given pixel position.

Also optionally crops any additional images, masks, headers, WCS solutions, PSF models, object lists, etc. passed as arguments. Behaviour is identical to split_image() for a single block.

Unlike stdpipe.utils.crop_image_centered(), this function accepts explicit output width and height. If the requested region extends beyond the image boundary, the returned sub-image will be smaller (no padding is applied).

Parameters:
imagendarray

2D image to crop.

*args

Additional images, headers, WCS objects, or tables to crop alongside image.

x0int or float

Pixel x coordinate of the desired center in the original image.

y0int or float

Pixel y coordinate of the desired center in the original image.

widthint

Pixel width of the sub-image.

heightint, optional

Pixel height of the sub-image. Defaults to width.

get_originbool, optional

If True, include the sub-image origin (x1, y1) in the returned list.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

**kwargs

Additional images, headers, WCS objects, or tables to crop.

Returns:
list

List containing:

  • origin x1, y1, if get_origin=True

  • cropped image

  • cropped versions of each *args and **kwargs entry

stdpipe.pipeline.get_detection_limit(obj, sn=5, method='sn', verbose=True)[source]

Estimate the detection limit magnitude.

The object table must contain calibrated magnitudes and errors in mag_calib and mag_calib_err columns.

Parameters:
objastropy.table.Table

Table with calibrated objects.

snfloat, optional

S/N threshold defining the detection limit.

methodstr, optional

Estimation method. Currently only 'sn' (S/N vs magnitude extrapolation) is implemented.

verbosebool or callable, optional

Whether to show verbose messages. May be boolean or a print-like callable.

Returns:
float or None

Magnitude corresponding to the detection limit at the given S/N level, or None if estimation fails.