Commit 19af7b19 authored by karpov-sv's avatar karpov-sv
Browse files

Improve documentation

parent 2870ec84
Reference catalogues
====================
In order to perform :doc:`astrometric <astrometry>` and :doc:`photometric <photometry>` calibrations, you will need a reference catalogue. For *STDPipe*, any table that contains sky positions of the stars and their magnitudes will work - so you may either construct it yourself, load from file or database, or download from Internet.
For the latter, we have a convenience routine :func:`stdpipe.catalogs.get_cat_vizier` that helps accessing any catalogue available in `Vizier <https://vizier.cds.unistra.fr>`_.
For some of them we have a special support - we automatically augment them with magnitudes in photometric bands not originally present there. To do so, we use the following sources of photometric transformations:
- for Pan-STARRS to Johnson-Cousins magnitudes, we use conversion coefficients from https://arxiv.org/pdf/1706.06147.pdf
- for Gaia DR2, we use some self-made conversion coefficients derived by cross-matching with Stetson standards, along with linearity correction described at https://www.cosmos.esa.int/web/gaia/dr2-known-issues#PhotometrySystematicEffectsAndResponseCurves
The following example shows how to get a reference catalogue for a given image
.. code-block:: python
# Load initial WCS from FITS header
wcs = WCS(header)
# Get the center position, size and pixel scale for the image from WCS
center_ra,center_dec,center_sr = astrometry.get_frame_center(wcs=wcs, width=image.shape[1], height=image.shape[0])
pixscale = astrometry.get_pixscale(wcs=wcs)
print('Frame center is %.2f %.2f radius %.2f deg, %.2f arcsec/pixel' % (center_ra, center_dec, center_sr, pixscale*3600))
# Load Pan-STARRS stars for this region brighter than r=18.0 mag
cat = catalogs.get_cat_vizier(center_ra, center_dec, center_sr, 'ps1', filters={'rmag':'<18'})
print(len(cat), 'catalogue stars')
.. autofunction:: stdpipe.catalogs.get_cat_vizier
:noindex:
Cross-matching with Vizier catalogues
-------------------------------------
*STDPipe* also has a couple of convenience routines for cross-matching object lists with Vizier catalogues that use `CDS XMatch service <http://cdsxmatch.u-strasbg.fr>`_, as well as with Solar system objects using `IMCCE SkyBoT service <http://vo.imcce.fr/webservices/skybot/>`_. Both are thin wrappers around corresponding routines from `Astroquery <https://astroquery.readthedocs.io/en/latest/index.html>`_ package.
.. autofunction:: stdpipe.catalogs.xmatch_objects
:noindex:
.. autofunction:: stdpipe.catalogs.xmatch_skybot
:noindex:
......@@ -33,17 +33,11 @@ sys.path.insert(0, os.path.abspath(".."))
# ones.
extensions = [
"myst_parser",
# "recommonmark",
# "sphinx_math_dollar",
"sphinx.ext.autodoc",
"sphinxcontrib.apidoc",
"sphinx.ext.autosummary",
# 'sphinx.ext.pngmath',
# "numpydoc",
# 'plot2rst',
"sphinx.ext.intersphinx",
# 'sphinx.ext.linkcode',
# 'sphinx_gallery.gen_gallery'
]
mathjax_config = {
......@@ -113,7 +107,7 @@ exclude_patterns = ["_build"]
# The reST default role (used for this markup: `text`) to use for all
# documents.
default_role = 'obj'
default_role = 'code'
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
......
Object detection and measurement
================================
Detecting objects on the image
------------------------------
*STDPipe* currently contains two functions for detecting objects on the image, one based on external `SExtractor <https://github.com/astromatic/sextractor>`_ binary (:func:`stdpipe.photometry.get_objects_sextractor`), other - on Python `SEP <https://github.com/kbarbary/sep>`_ library (:func:`stdpipe.photometry.get_objects_sextractor`). They have mostly identical signatures and arguments, but differ in minor details like meaning of returned detection flags etc.
The detection in both cases is based on building the noise model through (grid-based) background and background rms estimation, and then extracting the groups of connected pixels above some pre-defined threshold. Optionally, before the thresholding, the image may be smoothed with some small kernel in order to improve the detection of fainter obects.
Also, the routines may automatically reject the objects detected too close to frame edge, and probably truncated or improperly measured - this is controlled by `edge` argument. Less significant detections - with :math:`\frac1{\rm magerr} < {\rm S/N}` - may also be automatically rejected by providing the `sn` argument.
Both routines return the results as a standard Astropy Table, ordered by the object brightness. The table contains at least the following columns:
- `x`, `y`, `xerr`, `yerr` - positions of the objects in image coordinates
- `ra`, `dec` - positions of the objects in sky coordinates according to provided WCS
- `a`, `b`, `theta` - object ellipse semimajor and semiminor axes, as well as its position angle in image coordinates
- `flux`, `fluxerr` - measured flux and its error in a circular aperture
- `mag`, `magerr` - instrumental magnitude computed as `-2.5*log10(flux)`, and its error computed as `2.5/log(10)*fluxerr/flux`
- `flags` - detection flags
- `fwhm` - per-object FWHM estimation
For :func:`~stdpipe.photometry.get_objects_sextractor`, the output may also contain columns related to PSF photometry (`x_psf`, `y_psf`, `flux_psf`, `fluxerr_psf`, `mag_psf`, `magerr_psf`, `chi2_psf`, `spread_model`, `spreaderr_model`), as well as any additional measuremet parameter requested through `extra_params` argument.
Below are some examples of object detection.
.. code-block:: python
# We will detect objects using SExtractor and get their measurements in apertures with 3 pixels radius
# We will also ignore anything closer than 10 pixels to image edge
obj = photometry.get_objects_sextractor(image, mask=mask, aper=3.0, gain=gain, edge=10)
print(len(obj), 'objects detected')
# Rough estimation of average FWHM of detected objects, taking into account only unflagged (e.g. not saturated) ones
fwhm = np.median(obj['fwhm'][obj['flags'] == 0])
print('Average FWHM is %.1f pixels' % fwhm)
Next example shows how to receive extra columns, as well as checkimages, from SExtractor
.. code-block:: python
# Now we will also get segmentation map and a column with object numbers correspoding to this map
obj,segm = photometry.get_objects_sextractor(image, mask=mask, aper=3.0, gain=gain, edge=10, extra_params=['NUMBER'], checkimages=['SEGMENTATION'], verbose=True)
# We may now e.g. completely mask the footprints of objects having masked pixels
fmask = np.zeros_like(mask)
for _ in obj[(obj['flags'] & 0x100) > 0]:
fmask |= segm == _['NUMBER']
Finally, using SExtractor star/galaxy separators - `CLASS_STAR` and `SPREAD_MODEL`. The latter require PSF model - so we will build it using :func:`stdpipe.psf.run_psfex` documented elsewhere
.. code-block:: python
# Get PSF model and store it to temporary file
psf_model = psf.run_psfex(image, mask=mask, order=0, gain=gain, psffile='/tmp/psf.psf', verbose=True)
# Run SExtractor
# You should provide correct path to default.nnw file from SExtractor installation on your system!
obj = photometry.get_objects_sextractor(image, mask=mask, edge=10, wcs=wcs, aper=3.0, extra_params=['CLASS_STAR', 'NUMBER'], extra={'SEEING_FWHM':fwhm, 'STARNNW_NAME':'/Users/karpov/opt/miniconda3/envs/stdpipe//share/sextractor/default.nnw'}, psf='/tmp/psf.psf', verbose=True)
for i,cand in enumerate(obj):
print('Candidate %d at x/y = %.1f %.1d and RA/Dec = %.4f %.4f' % (i, cand['x'], cand['y'], cand['ra'], cand['dec']))
print('SPREAD_MODEL = %.3f +/- %.3f, CLASS_STAR = %.2f' % (cand['spread_model'], cand['spreaderr_model'], cand['CLASS_STAR']))
.. attention::
The most important problem with object detection using these routines is handling of blended objects, as the codes we are using can't properly deblend close groups, except for simplest cases.
.. autofunction:: stdpipe.photometry.get_objects_sextractor
:noindex:
.. autofunction:: stdpipe.photometry.get_objects_sep
:noindex:
More accurate photometric measurements
--------------------------------------
The photometric measurements returned by the routines above are sometimes not the best ones you may extract from the image. E.g. they are based on globally estimated background model (built as a low-resolution spatial map and then intepolated to original pixels, see `here <https://sextractor.readthedocs.io/en/latest/Background.html>`_). On a rapidly varying backgrounds, you may expect better results from locally estimated background - e.g using local annuli around every object and sigma-clipped averages of pixel values inside them. We have a function :func:`stdpipe.photometry.measure_objects` that tries to compute it.
.. code-block:: python
# We will pass this FWHM to measurement function so that aperture and background radii will be relative to it.
# We will also reject all objects with measured S/N < 5
obj = photometry.measure_objects(obj, image, mask=mask, fwhm=fwhm, gain=gain, aper=1.0, bkgann=[5, 7], sn=5, verbose=True)
print(len(obj), 'objects properly measured')
.. autofunction:: stdpipe.photometry.measure_objects
:noindex:
......@@ -23,7 +23,7 @@ User Guide
----------
.. toctree::
:maxdepth: 2
:maxdepth: 3
installation
usage
......@@ -38,7 +38,7 @@ modify it, reuse it, and contribute changes back for the benefit of
others. We follow standard open source development practices: changes
are submitted as pull requests and, once they pass the test suite,
reviewed by the team before inclusion. Please also see
`our contributing guide <./contributing.html>`_.
:doc:`our contributing guide <contributing>`.
Authors
-------
......
......@@ -49,6 +49,9 @@ You may want to stack/coadd or mosaic some images before processing them. While
You may check `simple example notebook <https://github.com/karpov-sv/stdpipe/blob/master/notebooks/image_stacking.ipynb>`_
that shows how to do it.
.. attention::
The stacking modify the statistical properties of resulting image! The reasons are both averaging (or especially median averaging!) of the images that modify effective gain value (typically increasing it by the factor equal to number of averaged images), and pixel interpolation when re-projecting the images onto the same pixel grid.
*STDPipe* also contains a simple wrapper for `SWarp <https://github.com/astromatic/swarp>`_ re-projection code, :func:`stdpipe.templates.reproject_swarp`, that is implemented to resemble the calling conventions of `reproject <https://github.com/astropy/reproject>`_ package routines as much as possible - i.e. allows directly stacking the image files without loading them to memory first:
.. autofunction:: stdpipe.templates.reproject_swarp
......
......@@ -42,6 +42,7 @@ Data processing
preprocessing
detection
catalogs
astrometry
photometry
subtraction
......@@ -51,7 +52,7 @@ Common principles
The functions included in *STDPipe* try to follow several common principles related to their behaviour and arguments. They are summarized below.
- Most of functions accept ``verbose`` argument that controls the amount of informational outputs the function produces. You may use ``verbose=True`` to see the details of what exactly the function is doing. Also, you may pass any ``print``-like function to this argument to receive the messages instead of printing - so e.g. they may be logged.
- Most of functions accept `verbose` argument that controls the amount of informational outputs the function produces. You may use `verbose=True` to see the details of what exactly the function is doing. Also, you may pass any `print`-like function to this argument to receive the messages instead of printing - so e.g. they may be logged.
.. code-block:: python
......@@ -72,8 +73,8 @@ The functions included in *STDPipe* try to follow several common principles rela
# Now use it to redirect STDPipe function output to log file
obj = photometry.get_objects_sextractor(image, mask=mask, verbose=verbose)
- Functions that produce (and then delete of course) some temporary files during its operation usually accept ``_tmpdir`` argument to manually specify the location where these temporary files (usually in a dedicated per-task temporary folder, so thread-safe and stuff) will be stored. This is useful if your system-wide temporary directory (usually :file:`/tmp` in Linux) is low on free space - then you may use some larger volume for storing temporary files by adding ``_tmpdir=/large/volume/tmp`` to function call.
- Functions that produce (and then delete of course) some temporary files during its operation usually accept `_tmpdir` argument to manually specify the location where these temporary files (usually in a dedicated per-task temporary folder, so thread-safe and stuff) will be stored. This is useful if your system-wide temporary directory (usually :file:`/tmp` in Linux) is low on free space - then you may use some larger volume for storing temporary files by adding `_tmpdir=/large/volume/tmp` to function call.
- Functions that operate on temporary files in temporary folders may be supplied with ``_workdir`` argument - then they will store all temporary files related to their work in this specific folder, and will not remove them afterwards. So e.g. you will be able to directly see e.g what configuration files were created, manually re-run the failed command to experiment with its options (with ``verbose=True`` function call typically prints the complete command line of all calls to external programs, so you may just directly copy and paste it to terminal to repeat its invocation), etc.
- Functions that operate on temporary files in temporary folders may be supplied with `_workdir` argument - then they will store all temporary files related to their work in this specific folder, and will not remove them afterwards. So e.g. you will be able to directly see e.g what configuration files were created, manually re-run the failed command to experiment with its options (with `verbose=True` function call typically prints the complete command line of all calls to external programs, so you may just directly copy and paste it to terminal to repeat its invocation), etc.
- Functions that run external programs (e.g. SExtractor, HOTPANTS, or Astrometry.Net) usually accept ``_exe`` argument to directly specify the path to corresponding executable. If not specified, the code will try to automatically find it for you, so normally you do not need to worry about it.
- Functions that run external programs (e.g. SExtractor, HOTPANTS, or Astrometry.Net) usually accept `_exe` argument to directly specify the path to corresponding executable. If not specified, the code will try to automatically find it for you, so normally you do not need to worry about it.
......@@ -30,6 +30,31 @@ catalogs = {
}
def get_cat_vizier(ra0, dec0, sr0, catalog='ps1', limit=-1, filters={}, extra=[]):
"""Download any catalogue from Vizier.
The catalogue may be anything recognizable by Vizier. For some most popular ones, we have additional support - we try to augment them with photometric measurements not originally present there, based on some analytical magnitude conversion formulae. These catalogues are:
- ps1 - Pan-STARRS DR1. We augment it with Johnson-Cousins B, V, R and I magnitudes
- gaiadr2 - Gaia DR2. We augment it with Johnson-Cousins B, V, R and I magnitudes, as well as Pan-STARRS and SDSS ones
- gaiaedr3 - Gaia eDR3
- skymapper - SkyMapper DR1.1
- vsx - AAVSO Variable Stars Index
- apass - AAVSO APASS DR9
- sdss - SDSS DR12
- atlas - ATLAS-RefCat2, compilative all-sky reference catalogue with uniform zero-points in Pan-STARRS-like bands. We augment it with Johnson-Cousins B, V, R and I magnitudes the same way as Pan-STARRS.
- usnob1 - USNO-B1
- gsc - Guide Star Catalogue 2.2
:param ra0: Right Ascension of the field center, degrees
:param dec0: Declination of the field center, degrees
:param sr0: Field radius, degrees
:param catalog: Any Vizier catalogue identifier, or a catalogue short name (see above)
:param limit: Limit for the number of returned rows, optional
:param filters: Dictionary with column filters to be applied on Vizier side. Dictionary key is the column name, value - filter expression as documented at https://vizier.u-strasbg.fr/vizier/vizHelp/cst.htx
:param extra: List of extra column names to return in addition to default ones.
:returns: astropy.table.Table with catalogue as returned by Vizier, with some additional columns added for supported catalogues.
"""
# TODO: add positional errors
if catalog in catalogs:
......@@ -122,6 +147,18 @@ def get_cat_vizier(ra0, dec0, sr0, catalog='ps1', limit=-1, filters={}, extra=[]
return cat
def xmatch_objects(obj, catalog='ps1', sr=3/3600, col_ra='ra', col_dec='dec'):
"""Cross-match object list with Vizier catalogue using CDS XMatch service.
Any Vizier catalogue may be used for cross-matching.
:param obj: astropy.table.Table with objects
:param catalog: Any Vizier catalogue identifier, or a catalogue short name
:param sr: Cross-matching radius in degrees
:param col_ra: Column name in `obj` table containing Right Ascension values
:param col_dec: Column name in `obj` table containing Declination values
:returns: The table of matched objects augmented with some fields from the Vizier catalogue.
"""
if catalog in catalogs:
vizier_id = catalogs.get(catalog)['vizier']
else:
......@@ -131,7 +168,23 @@ def xmatch_objects(obj, catalog='ps1', sr=3/3600, col_ra='ra', col_dec='dec'):
return xcat
def xmatch_skybot(obj, sr=10/3600, time=None, location='500', col_ra='ra', col_dec='dec', col_id='id'):
def xmatch_skybot(obj, sr=10/3600, time=None, col_ra='ra', col_dec='dec', col_id='id'):
"""Cross-match object list with positions of Solar System objects using SkyBoT service
The routine works by requesting the list of all solar system objects in a cone containing all
input objects, and then cross-matching them using the radius defined by `sr` parameter. Then it
returns the table of solar system objects plus a column of unique identifiers corresponding
to user objects.
:param obj: astropy.table.Table with objects
:param sr: Cross-matching radius in degrees
:param time: Time of the observation corresponding to the objects
:param col_ra: Column name in `obj` table containing Right Ascension values
:param col_dec: Column name in `obj` table containing Declination values
:param col_id: Column name in `obj` table containing some unique object identifier
:returns: The table of solar system objects augmented with `col_id` column of matched objects.
"""
ra0,dec0,sr0 = astrometry.get_objects_center(obj)
try:
......
"""
Routines for object detection and photometry.
"""
from __future__ import absolute_import, division, print_function, unicode_literals
import os, shutil, tempfile, shlex
......@@ -39,8 +43,37 @@ def make_kernel(r0=1.0, ext=1.0):
return image
def get_objects_sep(image, header=None, mask=None, err=None, thresh=4.0, aper=3.0, bkgann=None, r0=0.5, gain=1, edge=0, minnthresh=2, minarea=5, relfluxradius=2.0, wcs=None, use_fwhm=False, use_mask_large=False, subtract_bg=True, npix_large=100, sn=10.0, verbose=True, **kwargs):
# Simple wrapper around print for logging in verbose mode only
def get_objects_sep(image, header=None, mask=None, err=None, thresh=4.0, aper=3.0, bkgann=None, r0=0.5, gain=1, edge=0, minnthresh=2, minarea=5, relfluxradius=2.0, wcs=None, bg_size=64, use_fwhm=False, use_mask_large=False, subtract_bg=True, npix_large=100, sn=10.0, verbose=True, **kwargs):
"""Opject detection and simple aperture photometry using `SEP <https://github.com/kbarbary/sep>`_ routines, with the signature as similar as possible to :func:`~stdpipe.photometry.get_objects_sextractor` function.
Detection flags are documented at https://sep.readthedocs.io/en/v1.1.x/reference.html - they are different from SExtractor ones!
:param image: Input image as a NumPy array
:param header: Image header, optional
:param mask: Image mask as a boolean array (True values will be masked), optional
:param err: Image noise map as a NumPy array, optional
:param thresh: Detection threshold in sigmas above local background
:param aper: Circular aperture radius in pixels, to be used for flux measurement
:param bkgann: Background annulus (tuple with inner and outer radii) to be used for local background estimation. Inside the annulus, simple arithmetic mean of unmasked pixels is used for computing the background, and thus it is subject to some bias in crowded stellar fields. If not set, global background model is used instead.
:param r0: Smoothing kernel size (sigma) to be used for improving object detection
:param gain: Image gain, e/ADU
:param edge: Reject all detected objects closer to image edge than this parameter
:param minnthresh: Minumal number of pixels above the threshold to be considered a detection
:param minarea: Minimal number of pixels in the object to be considered a detection
:param relfluxradius:
:param wcs: Astrometric solution to be used for assigning sky coordinates (`ra`/`dec`) to detected objects
:param bg_size: Background grid size in pixels
:param use_fwhm: If True, the aperture will be set to 1.5*FWHM (if greater than `aper`)
:param use_mask_large: If True, filter out large objects (with footprints larger than `npix_large` pixels)
:param npix_large: Threshold for rejecting large objects (if `use_mask_large` is set)
:param subtract_bg: Whether to subtract the background (default) or not
:param sn: Minimal S/N ratio for the object to be considered a detection
:param verbose: Whether to show verbose messages during the run of the function or not. May be either boolean, or a `print`-like function.
:param verbose: Whether to show verbose messages during the run of the function or not. May be either boolean, or a `print`-like function.
:returns: astropy.table.Table object with detected objects
"""
# Simple Wrapper around print for logging in verbose mode only
log = (verbose if callable(verbose) else print) if verbose else lambda *args,**kwargs: None
if r0 > 0.0:
......@@ -58,7 +91,7 @@ def get_objects_sep(image, header=None, mask=None, err=None, thresh=4.0, aper=3.
log("Building background map")
bg = sep.Background(image, mask=mask|mask_bg, bw=64, bh=64)
bg = sep.Background(image, mask=mask|mask_bg, bw=bg_size, bh=bg_size)
if subtract_bg:
image1 = image - bg.back()
else:
......@@ -160,17 +193,39 @@ def get_objects_sep(image, header=None, mask=None, err=None, thresh=4.0, aper=3.
return obj
def get_objects_sextractor(image, header=None, mask=None, err=None, thresh=2.0, aper=3.0, r0=0.5, gain=1, edge=0, minarea=5, wcs=None, sn=3.0, bg_size=None, sort=True, reject_negative=True, checkimages=[], extra_params=[], extra={}, psf=None, catfile=None, _workdir=None, _tmpdir=None, _exe=None, verbose=False):
'''
Thin wrapper around SExtractor binary.
It processes the image provided as a NumPy array, with optional mask and noise (err) arrays.
It optionally filters out the detections having too small S/N ratio (sn) or the ones located too close to frame edges (edge), as well as detections with negative fluxes (reject_negatives).
The resulting detections are returned as an Astropy Table, and may be optionally stored to the file specified with catfile option.
The routine also optionally returns as an arrays the following checkimages: BACKGROUND, BACKGROUND_RMS, MINIBACKGROUND, MINIBACK_RMS, -BACKGROUND, FILTERED, OBJECTS, -OBJECTS, SEGMENTATION, APERTURES
'''
"""Thin wrapper around SExtractor binary.
It processes the image taking into account optional mask and noise map, and returns the list of detected objects and optionally a set of SExtractor-produced checkimages.
You may check the SExtractor documentation at https://sextractor.readthedocs.io/en/latest/ for more details about possible parameters and general principles of its operation.
E.g. detection flags (returned in `flags` column of results table) are documented at https://sextractor.readthedocs.io/en/latest/Flagging.html#extraction-flags-flags . In addition to these flags, any object having pixels masked by the input `mask` in its footprint will have :code:`0x100` flag set.
:param image: Input image as a NumPy array
:param header: Image header, optional
:param mask: Image mask as a boolean array (True values will be masked), optional
:param err: Image noise map as a NumPy array, optional
:param thresh: Detection threshold, in sigmas above local background, to be used for `DETECT_THRESH` parameter of SExtractor call
:param aper: Circular aperture radius in pixels, to be used for flux measurement
:param r0: Smoothing kernel size (sigma) to be used for improving object detection
:param gain: Image gain, e/ADU
:param edge: Reject all detected objects closer to image edge than this parameter
:param minarea: Minimal number of pixels in the object to be considered a detection (`DETECT_MINAREA` parameter of SExtractor)
:param wcs: Astrometric solution to be used for assigning sky coordinates (`ra`/`dec`) to detected objects
:param sn: Minimal S/N ratio for the object to be considered a detection
:param bg_size: Background grid size in pixels (`BACK_SIZE` SExtractor parameter)
:param sort: Whether to sort the detections in decreasing brightness or not
:param reject_negative: Whether to reject the detections with negative fluxes
:param checkimages: List of SExtractor checkimages to return along with detected objects. Any SExtractor checkimage type may be used here (e.g. `BACKGROUND`, `BACKGROUND_RMS`, `MINIBACKGROUND`, `MINIBACK_RMS`, `-BACKGROUND`, `FILTERED`, `OBJECTS`, `-OBJECTS`, `SEGMENTATION`, `APERTURES`). Optional.
:param extra_params: List of extra object parameters to return for the detection. See :code:`sex -dp` for the full list.
:param extra: Dictionary of extra configuration parameters to be passed to SExtractor call, with keys as parameter names. See :code:`sex -dd` for the full list.
:param psf: Path to PSFEx-made PSF model file to be used for PSF photometry. If provided, a set of PSF-measured parameters (`FLUX_PSF`, `MAG_PSF` etc) are added to detected objects. Optional
:param catfile: If provided, output SExtractor catalogue file will be copied to this location, to be reused by external codes. Optional.
:param _workdir: If specified, all temporary files will be created in this directory, and will be kept intact after running SExtractor. May be used for debugging exact inputs and outputs of the executable. Optional
:param _tmpdir: If specified, all temporary files will be created in a dedicated directory (that will be deleted after running the executable) inside this path.
:param _exe: Full path to SExtractor executable. If not provided, the code tries to locate it automatically in your :envvar:`PATH`.
:param verbose: Whether to show verbose messages during the run of the function or not. May be either boolean, or a `print`-like function.
:returns: Either the astropy.table.Table object with detected objects, or a list with table of objects (first element) and checkimages (consecutive elements), if checkimages are requested.
"""
# Simple wrapper around print for logging in verbose mode only
log = (verbose if callable(verbose) else print) if verbose else lambda *args,**kwargs: None
......@@ -589,15 +644,30 @@ def get_background(image, mask=None, method='sep', size=128, get_rms=False, **kw
return back
def measure_objects(obj, image, aper=3, bkgann=None, fwhm=None, mask=None, bg=None, err=None, gain=None, bg_size=64, sn=None, get_bg=False, verbose=False):
'''
Aperture photometry at the positions of already detected objects.
It will estimate and subtract the background unless external background estimation (bg) is provided, and use user-provided noise map if requested.
If the mask is provided, it will set 0x200 bit in object flags if at least one of aperture pixels is masked.
The results may optionally filtered to drop the detections with low signal to noise ratio if sn parameter is set and positive. It will also filter out the events with negative flux.
'''
"""Aperture photometry at the positions of already detected objects.
It will estimate and subtract the background unless external background estimation (`bg`) is provided, and use user-provided noise map (`err`) if requested.
If the `mask` is provided, it will set 0x200 bit in object `flags` if at least one of aperture pixels is masked.
The results may optionally filtered to drop the detections with low signal to noise ratio if `sn` parameter is set and positive. It will also filter out the events with negative flux.
:param obj: astropy.table.Table with initial object detections to be measured
:param image: Input image as a NumPy array
:param aper: Circular aperture radius in pixels, to be used for flux measurement
:param bkgann: Background annulus (tuple with inner and outer radii) to be used for local background estimation. If not set, global background model is used instead.
:param fwhm: If provided, `aper` and `bkgann` will be measured in units of this value (so they will be specified in units of FWHM)
:param mask: Image mask as a boolean array (True values will be masked), optional
:param bg: If provided, use this background (NumPy array with same shape as input image) instead of automatically computed one
:param err: Image noise map as a NumPy array to be used instead of automatically computed one, optional
:param gain: Image gain, e/ADU, used to build image noise model
:param bg_size: Background grid size in pixels
:param sn: Minimal S/N ratio for the object to be considered good. If set, all measurements with magnitude errors exceeding 1/SN will be discarded
:param get_bg: If True, the routine will also return estimated background and background noise images
:param verbose: Whether to show verbose messages during the run of the function or not. May be either boolean, or a `print`-like function.
:returns: The copy of original table with `flux`, `fluxerr`, `mag` and `magerr` columns replaced with the values measured in the routine. If :code:`get_bg=True`, also returns the background and background error images.
"""
# Simple wrapper around print for logging in verbose mode only
log = (verbose if callable(verbose) else print) if verbose else lambda *args,**kwargs: None
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment