stdpipe.photometry_model module

Photometric modeling routines.

This module contains functions for photometric calibration and modeling, including catalog matching with spatial zero-point models, S/N modeling, and detection limit estimation.

stdpipe.photometry_model.make_series(mul=1.0, x=1.0, y=1.0, order=1, sum=False, zero=True)

stdpipe.photometry_model.get_intrinsic_scatter(y, yerr, min=0, max=None)

stdpipe.photometry_model.format_color_term(color_term, name=None, color_name=None, fmt='.2f')

stdpipe.photometry_model.match(obj_ra, obj_dec, obj_mag, obj_magerr, obj_flags, cat_ra, cat_dec, cat_mag, cat_magerr=None, cat_color=None, sr=0.0008333333333333334, obj_x=None, obj_y=None, spatial_order=0, bg_order=None, nonlin=False, threshold=5.0, niter=10, accept_flags=0, cat_saturation=None, max_intrinsic_rms=0, sn=None, verbose=False, robust=True, scale_noise=False, use_color=True, force_color_term=None)

Low-level photometric matching routine.

Builds a photometric model for objects detected on the image that includes catalogue magnitude, positionally-dependent zero point, linear color term, optional additive flux term, and also takes into account possible intrinsic magnitude scatter on top of measurement errors.

Parameters:

obj_raarray-like

Right Ascension values for the objects.

obj_decarray-like

Declination values for the objects.

obj_magarray-like

Instrumental magnitude values for the objects.

obj_magerrarray-like

Instrumental magnitude errors for the objects.

obj_flagsarray-like

Flags for the objects.

cat_raarray-like

Catalogue Right Ascension values.

cat_decarray-like

Catalogue Declination values.

cat_magarray-like

Catalogue magnitudes.

cat_magerrarray-like, optional

Catalogue magnitude errors.

cat_colorarray-like, optional

Catalogue color values.

srfloat

Matching radius in degrees.

obj_xarray-like, optional

X coordinates of objects on the image.

obj_yarray-like, optional

Y coordinates of objects on the image.

spatial_orderint

Order of zero point spatial polynomial (0 for constant).

bg_orderint or None

Order of additive flux term spatial polynomial. None to disable this term in the model.

nonlinbool

Whether to fit for simple non-linearity.

thresholdfloat

Rejection threshold (relative to magnitude errors) for object-catalogue pair to be rejected from the fit.

niterint

Number of iterations for the fitting.

accept_flagsint

Bitmask for acceptable object flags. Objects having any other bits set will be excluded from the model.

cat_saturationfloat or None

Saturation level for the catalogue. Stars brighter than this magnitude will be excluded from the fit.

max_intrinsic_rmsfloat

Maximal intrinsic RMS to use during the fitting. If set to 0, no intrinsic scatter is included in the noise model.

snfloat or None

Minimal acceptable signal to noise ratio (1/obj_magerr) for the objects to be included in the fit.

verbosebool or callable

Whether to show verbose messages during the run. May be either boolean, or a print-like function.

robustbool

Whether to use robust least squares fitting instead of weighted least squares.

scale_noisebool

Whether to re-scale the noise model (object and catalogue magnitude errors) to match actual scatter of the data points. Intrinsic scatter term is not scaled this way.

use_colorbool or int

Whether to use catalogue color for deriving the color term. If integer, it determines the color term order.

force_color_termfloat or None

Do not fit for the color term, but use this fixed value instead.

Returns:

dict or None

Dictionary with photometric results, or None if the fit failed. Contains the following keys:

• oidx, cidx, dist – indices of positionally matched objects and catalogue stars, and their pairwise distances in degrees.

• omag, omag_err, cmag, cmag_err – instrumental magnitudes of matched objects, corresponding catalogue magnitudes, and their errors. Array lengths equal the number of positional matches.

• color – catalogue colors corresponding to the matches, or zeros if no color term fitting is requested.

• ox, oy, oflags – coordinates of matched objects on the image, and their flags.

• zero, zero_err – empirical zero points (catalogue minus instrumental magnitudes) for every matched object, and errors derived as a hypotenuse of their corresponding errors.

• zero_model, zero_model_err – modeled “full” zero points (including color terms) for matched objects, and their errors from the fit.

• color_term – fitted color term. Instrumental photometric system is defined as obj_mag = cat_mag - color * color_term.

• zero_fn – function to compute the zero point (without color term) at a given position and for a given instrumental magnitude, and optionally its error.

• obj_zero – zero points for all input objects (not necessarily matched to the catalogue) computed via zero_fn, without color term.

• params – internal parameters of the fitting polynomial.

• intrinsic_rms, error_scale – fitted values of intrinsic scatter and noise scaling.

• idx – boolean index of matched objects/catalogue stars used in the final fit (not rejected during iterative thresholding, and passing initial quality cuts).

• idx0 – same as idx but with only initial quality cuts applied.

Notes

The returned zero point function zero_fn has the signature:

zero_fn(xx, yy, mag=None, get_err=False, add_intrinsic_rms=False)

where xx and yy are coordinates on the image, mag is the object instrumental magnitude (needed to compute the additive flux term). If get_err=True, the function returns estimated zero point error instead of zero point, and add_intrinsic_rms controls whether this error estimation should also include the intrinsic scatter term.

The zero point returned by this function does not include the contribution of the color term. To derive the final calibrated magnitude for an object, manually add the color contribution:

mag_calibrated = mag_instrumental + color * color_term

where color is the true object color, and color_term is reported in the photometric results.

stdpipe.photometry_model.make_sn_model(mag, sn)

Build a model for signal to noise (S/N) ratio versus magnitude.

Assumes the noise comes from constant background noise plus Poissonian noise with constant gain.

Parameters:

magarray-like

Calibrated magnitudes.

snarray-like

S/N values corresponding to the magnitudes.

Returns:

callable

Function that accepts an array of magnitudes and returns the S/N model values for them.

Raises:

ValueError

If no finite positive S/N values are available to build the model.

stdpipe.photometry_model.get_detection_limit_sn(mag, mag_sn, sn=5, get_model=False, verbose=True)

Estimate the detection limit using S/N vs magnitude method.

Parameters:

magarray-like

Calibrated magnitudes.

mag_snarray-like

S/N values corresponding to these magnitudes.

snfloat

S/N level for the detection limit.

get_modelbool

If True, also return the S/N model function.

verbosebool or callable

Whether to show verbose messages during the run. May be either boolean, or a print-like function.

Returns:

float or None

Magnitude corresponding to the detection limit at the given S/N level. None if the model cannot be built or the root is not found.

callable or None

S/N model function (only returned when get_model=True). None if the model cannot be built.