API Documentation

space_phot

API Reference

space_phot.test(package=None, test_path=None, args=None, plugins=None, verbose=False, pastebin=None, remote_data=False, pep8=False, pdb=False, coverage=False, open_files=False, **kwargs)

Copied over from sncosmo v1.6 (http://sncosmo.readthedocs.org)

Run the tests using py.test. A proper set of arguments is constructed and passed to pytest.main.

Parameters:

• package (str, optional) – The name of a specific package to test, e.g. ‘io.fits’ or ‘utils’. If nothing is specified all default tests are run.

• test_path (str, optional) – Specify location to test by path. May be a single file or directory. Must be specified absolutely or relative to the calling directory.

• args (str, optional) – Additional arguments to be passed to pytest.main in the args keyword argument.

• plugins (list, optional) – Plugins to be passed to pytest.main in the plugins keyword argument.

• verbose (bool, optional) – Convenience option to turn on verbose output from py.test. Passing True is the same as specifying -v in args.

• pastebin ({'failed','all',None}, optional) – Convenience option for turning on py.test pastebin output. Set to ‘failed’ to upload info for failed tests, or ‘all’ to upload info for all tests.

• remote_data (bool, optional) – Controls whether to run tests marked with @remote_data. These tests use online data and are not run by default. Set to True to run these tests.

• pep8 (bool, optional) – Turn on PEP8 checking via the pytest-pep8 plugin and disable normal tests. Same as specifying –pep8 -k pep8 in args.

• pdb (bool, optional) – Turn on PDB post-mortem analysis for failing tests. Same as specifying –pdb in args.

• coverage (bool, optional) – Generate a test coverage report. The result will be placed in the directory htmlcov.

• open_files (bool, optional) – Fail when any tests leave files open. Off by default, because this adds extra run time to the test suite. Works only on platforms with a working lsof command.

• parallel (int, optional) – When provided, run the tests in parallel on the specified number of CPUs. If parallel is negative, it will use the all the cores on the machine. Requires the pytest-xdist plugin installed. Only available when using Astropy 0.3 or later.

• kwargs – Any additional keywords passed into this function will be passed on to the astropy test runner. This allows use of test-related functionality implemented in later versions of astropy without explicitly updating the package template.

See also

pytest.main

py.test function wrapped by run_tests.

class space_phot.photometry.observation3(fname)

Bases: observation

st_phot class for level 3 (drizzled) data

upper_limit(nsigma=3, method='psf')

psf_photometry(psf_model, sky_location=None, xy_position=None, fit_width=None, background=None, fit_flux=True, fit_centroid=True, fit_bkg=False, bounds={}, npoints=100, use_MLE=False, xshift=0, yshift=0, centroidx_shift=0, centroidy_shift=0, maxiter=None, find_centroid=False, minVal=-inf, psf_method='nest', center_weight=20)

st_phot psf photometry class for level 2 data.

Parameters:

• psf_model (EPSFModel) – In reality this does not need to be an EPSFModel, but just any photutils psf model class.

• sky_location (SkyCoord) – Location of your source

• xy_positions (list) – xy position of your source in each exposure. Must supply this or sky_location but this takes precedent.

• fit_width (int) – PSF width to fit (recommend odd number)

• background (float or list) – float, list of float, array, or list of array defining the background of your data. If you define an array, it should be of the same shape as fit_width

• fit_flux (str) – One of ‘single’,’multi’,’fixed’. Single is a single flux across all exposures, multi fits a flux for every exposure, and fixed only fits the position

• fit_centroid (str) – One of ‘pixel’,’wcs’,’fixed’. Pixel fits a pixel location of the source in each exposure, wcs fits a single RA/DEC across all exposures, and fixed only fits the flux and not position.

• fit_bkg (bool) – Fit for a constant background simultaneously with the PSF fit.

• bounds (dict) – Bounds on each parameter.

• npoints (int) – Number of points in the nested sampling (higher is better posterior sampling, but slower)

• use_MLE (bool) – Use the maximum likelihood to define best fit parameters, otherwise use a weighted average of the posterior samples

• maxiter (None or int) – If None continue sampling until convergence, otherwise defines the max number of iterations

• find_centroid (bool) – If True, then tries to find the centroid around your chosen location.

create_psf_subtracted(sci_ext=1, fname=None)

Use the best fit PSF models to create a PSF-subtracted image

Parameters:

• sci_ext (int) – The SCI extension to use (e.g., if this is UVIS)

• fname (str) – Output filename

aperture_photometry(sky_location, xy_positions=None, radius=None, encircled_energy=None, skyan_in=None, skyan_out=None, alternate_ref=None, radius_in_arcsec=False)

Perform aperture photometry on a single drizzled (level 3) image.

This uses space_phot.util.generic_aperture_phot() together with the appropriate HST/JWST aperture corrections and flux calibration.

Parameters:

• sky_location (astropy.coordinates.SkyCoord) – Sky coordinate of the source. Ignored if xy_positions is given.

• xy_positions (array_like, optional) – One or more (x, y) pixel positions. If provided, these override sky_location.

• radius (float, optional) – Aperture radius in pixels (or arcsec if radius_in_arcsec=True). Required for HST. For JWST this may be omitted if encircled_energy is supplied.

• encircled_energy (int or str, optional) – For JWST only. Encircled-energy value (e.g. 70 for 70 percent) to use when querying the JWST aperture-correction reference files.

• skyan_in (float, optional) – Inner and outer radii of the background annulus in pixels. If not provided, sensible defaults are chosen based on the aperture size (or JWST reference file if available).

• skyan_out (float, optional) – Inner and outer radii of the background annulus in pixels. If not provided, sensible defaults are chosen based on the aperture size (or JWST reference file if available).

• alternate_ref (str, optional) – Optional alternate reference file to pass through to the JWST aperture-correction helper.

• radius_in_arcsec (bool, optional) – If True, radius, skyan_in, and skyan_out are interpreted as arcsec and converted to pixels using self.pixel_scale.

Returns:

aperture_result –

Result object with the following attributes:

• radius – aperture radius in pixels

• ee – encircled energy (JWST only; None for HST)

• apcorr – aperture correction factor

• sky_an – dict with the sky annulus radii

• phot_table – raw photometry table

• phot_cal_table – calibrated photometry table

Return type:

sncosmo.utils.Result

plant_psf(psf_model, plant_locations, magnitudes, out_fname=None)

PSF planting class. Output files will be the same directory as the data files, but with _plant.fits added the end.

Parameters:

• psf_model (EPSFModel) – In reality this does not need to be an EPSFModel, but just any photutils psf model class.

• plant_locations (list) – The location(s) to plant the psf

• magnitudes – The magnitudes to plant your psf (matching length of plant_locations)

fast_psf(psf_model, centers, psf_width=5, local_bkg=False, **kwargs)

Fast PSF photometry wrapper around photutils.PSFPhotometry.

Parameters:

• psf_model (astropy.modeling.Model) – PSF/PRF model (e.g., IntegratedGaussianPRF).

• centers (array-like) – Initial centers, shape (N, 2), in (y, x) pixel coordinates.

• psf_width (int) – Fit stamp size (also used as aperture_radius).

• local_bkg (bool) – If True, estimate a local background with MMMBackground.

• **kwargs – Passed through to PSFPhotometry call (currently unused, kept for API stability).

Returns:

phot – Photutils output table with added calibrated columns: flux, fluxerr, mag, magerr, zp.

Return type:

astropy.table.Table

nest_psf(vparam_names, bounds, fluxes, fluxerrs, xs, ys, cutout_big=None, psf_width=7, use_MLE=False, minsnr=0.0, priors=None, ppfs=None, npoints=100, method='single', center_weight=20, maxiter=None, maxcall=None, modelcov=False, rstate=None, verbose=False, warn=True, **kwargs)

plot_psf_fit(fast_n=0)

Plot the best-fit PSF model and residuals

plot_psf_posterior(minweight=-inf)

Plot the posterior corner plot from nested sampling

Parameters:

minweight (float) – A minimum weight to show from the nested sampling (to zoom in on posterior)

class space_phot.photometry.observation2(exposure_fnames, sci_ext=1)

Bases: observation

st_phot class for level 2 (individual exposures, cals, flts) data

fast_psf(psf_model, centers, psf_width=5, local_bkg=False, **kwargs)

Fast PSF photometry wrapper around photutils.PSFPhotometry.

Parameters:

• psf_model (astropy.modeling.Model) – PSF/PRF model (e.g., IntegratedGaussianPRF).

• centers (array-like) – Initial centers, shape (N, 2), in (y, x) pixel coordinates.

• psf_width (int) – Fit stamp size (also used as aperture_radius).

• local_bkg (bool) – If True, estimate a local background with MMMBackground.

• **kwargs – Passed through to PSFPhotometry call (currently unused, kept for API stability).

Returns:

phot – Photutils output table with added calibrated columns: flux, fluxerr, mag, magerr, zp.

Return type:

astropy.table.Table

nest_psf(vparam_names, bounds, fluxes, fluxerrs, xs, ys, cutout_big=None, psf_width=7, use_MLE=False, minsnr=0.0, priors=None, ppfs=None, npoints=100, method='single', center_weight=20, maxiter=None, maxcall=None, modelcov=False, rstate=None, verbose=False, warn=True, **kwargs)

plot_psf_fit(fast_n=0)

Plot the best-fit PSF model and residuals

plot_psf_posterior(minweight=-inf)

Plot the posterior corner plot from nested sampling

Parameters:

minweight (float) – A minimum weight to show from the nested sampling (to zoom in on posterior)

upper_limit(nsigma=3, method='psf')

plant_psf(psf_model, plant_locations, magnitudes, multi_plant=False)

PSF planting class. Output files will be the same directory as the data files, but with _plant.fits added the end.

Parameters:

• psf_model (EPSFModel) – In reality this does not need to be an EPSFModel, but just any photutils psf model class.

• plant_locations (list) – The location(s) to plant the psf

• magnitudes – The magnitudes to plant your psf (matching length of plant_locations)

aperture_photometry(sky_location, xy_positions=None, radius=None, encircled_energy=None, skyan_in=None, skyan_out=None)

Aperture photometry for level 2 data (per exposure).

Parameters:

• sky_location (astropy.coordinates.SkyCoord) – Sky position of the source. Used if xy_positions is not given.

• xy_positions ((x, y) or array_like, optional) – Pixel positions of the source. If a single (x, y) pair is given, it is used for all exposures. If an array/list of shape (n_exposures, 2) is given, the ith row is used for the ith exposure.

• radius (float, optional) – Aperture radius in pixels. Required for HST.

• encircled_energy (int, optional) – For JWST, encircled-energy value (e.g. 70) to define the aperture.

• skyan_in (float, optional) – Inner radius of the sky annulus in pixels. If None, a default is used.

• skyan_out (float, optional) – Outer radius of the sky annulus in pixels. If None, a default is used.

Returns:

aperture_result – Result object with raw and calibrated photometry tables.

Return type:

sncosmo.utils.Result

psf_photometry(psf_model, sky_location=None, xy_positions=[], fit_width=None, background=None, fit_flux='single', fit_centroid='pixel', fit_bkg=False, bounds={}, npoints=100, use_MLE=False, maxiter=None, find_centroid=False, minVal=-inf, center_weight=20.0, xshift=0, yshift=0)

st_phot psf photometry class for level 2 data.

Parameters:

• psf_model (EPSFModel) – In reality this does not need to be an EPSFModel, but just any photutils psf model class.

• sky_location (SkyCoord) – Location of your source

• xy_positions (list) – xy position of your source in each exposure. Must supply this or sky_location but this takes precedent.

• fit_width (int) – PSF width to fit (recommend odd number)

• background (float or list) – float, list of float, array, or list of array defining the background of your data. If you define an array, it should be of the same shape as fit_width

• fit_flux (str) – One of ‘single’,’multi’,’fixed’. Single is a single flux across all exposures, multi fits a flux for every exposure, and fixed only fits the position

• fit_centroid (str) – One of ‘pixel’,’wcs’,’fixed’. Pixel fits a pixel location of the source in each exposure, wcs fits a single RA/DEC across all exposures, and fixed only fits the flux and not position.

• fit_bkg (bool) – Fit for a constant background simultaneously with the PSF fit.

• bounds (dict) – Bounds on each parameter.

• npoints (int) – Number of points in the nested sampling (higher is better posterior sampling, but slower)

• use_MLE (bool) – Use the maximum likelihood to define best fit parameters, otherwise use a weighted average of the posterior samples

• maxiter (None or int) – If None continue sampling until convergence, otherwise defines the max number of iterations

• find_centroid (bool) – If True, then tries to find the centroid around your chosen location.

create_psf_subtracted(sci_ext=1, fname=None)

Use the best fit PSF models to create a PSF-subtracted image

Parameters:

• sci_ext (int) – The SCI extension to use (e.g., if this is UVIS)

• fname (str) – Output filename

plot_phot(method='psf')

Plot the photometry

Parameters:

method (str) – psf or aperture

space_phot.cal.hst_get_zp(filt, zpsys='ab')

space_phot.cal.calibrate_JWST_flux(flux, fluxerr, imwcs, flux_units=None, units=Unit('MJy'))

Calibrate JWST image-plane fluxes to a chosen flux unit and AB magnitudes.

Parameters:

• flux (array_like) – Measured source flux in the native image units (usually MJy/sr).

• fluxerr (array_like) – 1-sigma uncertainties on flux in the same native units.

• imwcs (astropy.wcs.WCS) – WCS of the image, used to compute the pixel area on the sky.

• flux_units (astropy.units.Unit or None, optional) – Unit of flux and fluxerr. If None or equal to MJy/sr, we assume MJy/sr and multiply by the pixel solid angle to get MJy.

• units (astropy.units.Unit, optional) – Desired output flux units (default: MJy).

Returns:

• flux_out (ndarray or float) – Calibrated flux in units.

• fluxerr_out (ndarray or float) – Calibrated flux uncertainty in units.

• mag (ndarray or float) – AB magnitudes corresponding to flux_out.

• magerr (ndarray or float) – Magnitude uncertainties (uses 2.5*log10(1 + fluxerr/flux)).

• zp (float or ndarray) – Zero point defined as mag + 2.5*log10(flux).

space_phot.cal.JWST_mag_to_flux(mag, imwcs, zpsys='ab', density=True)

Convert AB/Vega magnitudes back to JWST fluxes.

Parameters:

• mag (array_like) – AB or Vega magnitudes.

• imwcs (astropy.wcs.WCS) – WCS used to determine the pixel scale, if density=True.

• zpsys ({'ab', 'vega'}, optional) – Magnitude system of the input magnitudes.

• density (bool, optional) – If True, return surface-brightness units (MJy/sr). If False, return integrated flux per pixel (MJy).

Returns:

flux – Flux in MJy/sr (if density=True) or MJy (if density=False).

Return type:

ndarray

space_phot.cal.calibrate_HST_flux(flux, fluxerr, primary_header, sci_header)

Calibrate HST fluxes to magnitudes using PHOTFLAM/PHOTPLAM.

Parameters:

• flux (array_like) – Flux values in the same units used by HST PHOTFLAM/PHOTPLAM (i.e. already in flux-density units, not raw counts).

• fluxerr (array_like) – 1-sigma uncertainties on flux.

• primary_header (fits.Header) – Primary header (must contain DETECTOR, and possibly PHOTFLAM/PHOTPLAM).

• sci_header (fits.Header) – SCI extension header (preferred place for PHOTFLAM/PHOTPLAM).

Returns:

• flux_out (float or ndarray) – Input flux (unchanged), but cast to float/ndarray consistently.

• fluxerr_out (float or ndarray) – Input flux uncertainty (unchanged).

• mag (float or ndarray) – AB magnitudes derived from flux.

• magerr (float or ndarray) – Magnitude uncertainties (1.086 * fluxerr/flux).

• zp (float or ndarray) – Zero point used in the conversion.

space_phot.cal.HST_mag_to_flux(mag, primary_header, sci_header, zpsys='ab')

Convert HST magnitudes to flux density using PHOTFLAM/PHOTPLAM (or the IR zeropoint helper if that branch is ever enabled).

Parameters:

• mag (array_like) – Magnitudes in the system defined by zpsys (currently ‘ab’ expected).

• primary_header (fits.Header) – Primary header (DETECTOR, FILTER, etc.).

• sci_header (fits.Header) – SCI header with PHOTFLAM/PHOTPLAM where available.

• zpsys (str, optional) – Magnitude system. Currently only ‘ab’ is actually supported here.

Returns:

flux – Flux density corresponding to the input magnitudes.

Return type:

ndarray

space_phot.cal.calc_jwst_psf_corr(ap_rad, instrument, band, imwcs, oversample=4, show_plot=False, psf=None)

space_phot.cal.calc_hst_psf_corr(ap_rad, instrument, band, pos, psf=None, sci_ext=1)

space_phot.util.get_jwst_psf(st_obs, sky_location, psf_width=61, pipeline_level=2, fname=None, dateobs=None)

space_phot.util.get_hst_psf(st_obs, sky_location, psf_width=25, pipeline_level=2)

space_phot.util.get_jwst3_psf(st_obs, st_obs3, sky_location, num_psfs=4, psf_width=31, temp_outdir='.')

space_phot.util.get_hst3_psf(st_obs, st_obs3, sky_location, psf_width=25)

space_phot.util.get_jwst_psf_grid(st_obs, num_psfs=16, fname=None, dateobs=None)

space_phot.util.get_jwst_psf_from_grid(st_obs, sky_location, grid, psf_width=101)